mafw.scripts.mafw_exe

MAFw executable root and command registration.

mafw

The Modular Analysis Framework execution.

This is the command line interface where you can configure and launch your analysis tasks.

More information on our documentation page.

param ctx:

The click context.

type ctx:

click.core.Context

param log_level:

The logging level as a string. Choice from debug, info, warning, error and critical.

type log_level:

str

param ui:

The user interface as a string. Choice from console and rich.

type ui:

str

param debug:

Flag to show debug information about exception.

type debug:

bool

param no_banner:

Flag to disable the welcome banner.

type no_banner:

bool

Usage

mafw [OPTIONS] [COMMAND] [ARGS]...

Options

--log-level <log_level>

Log level

Default:

'info'

Options:

debug | info | warning | error | critical

--ui <ui>

The user interface

Default:

'rich'

Options:

console | rich

-D, --debug

Show debug information about errors

--no-banner

Disable the welcome banner

-v, --version

Show the version and exit.

completion

Manage shell completion for the mafw command.

The completion workflow installs the Click-generated shell code into the active virtual environment, updates the activation script so completion is loaded automatically, and exposes a show helper for direct evaluation.

Added in version v2.2.

param ctx:

The click context.

type ctx:

click.core.Context

Usage

mafw completion [OPTIONS] COMMAND [ARGS]...

install

Install the mafw shell completion script.

When --shell is omitted, the command guesses the shell from $SHELL. The generated Click completion script is stored in the active virtual environment and the activation script is updated so that future shell sessions load completion automatically.

Added in version 2.2.

param ctx:

The click context.

type ctx:

click.core.Context

param shell:

Target shell selector.

type shell:

str

param force:

Reinstall completion even if already loaded.

type force:

bool

Usage

mafw completion install [OPTIONS]

Options

-s, --shell <shell>

Target shell for completion installation

Default:

'auto'

Options:

auto | bash | zsh | fish | powershell

-F, --force

Reinstall completion even if already loaded

show

Display the Click completion script on standard output.

The output is intentionally clean so it can be used with eval:

eval "$(mafw completion show)"

Added in version 2.2.

param ctx:

The click context.

type ctx:

click.core.Context

param shell:

Target shell selector.

type shell:

str

Usage

mafw completion show [OPTIONS]

Options

-s, --shell <shell>

Target shell for completion output

Default:

'auto'

Options:

auto | bash | zsh | fish | powershell

uninstall

Remove the installed mafw shell completion files.

This command removes generated completion files from share/mafw and strips the marker block from the activation scripts.

Added in version 2.2.

param ctx:

The click context.

type ctx:

click.core.Context

Usage

mafw completion uninstall [OPTIONS]

db

Advanced database commands.

The db group of commands offers a set of useful database operations. Invoke the help option of each command for more details.

param ctx:

The click context.

type ctx:

click.core.Context

Usage

mafw db [OPTIONS] COMMAND [ARGS]...

diff

Report the supported differences between the models and the database.

This command is read-only: it modifies neither the database schema nor any migration script. An empty result is reported as synchronization scoped to the supported difference types only, never as full schema equivalence.

param obj:

The root context object.

type obj:

dict

param directory:

Optional migration-directory override.

type directory:

str | None

param steering_file:

Path to the steering file.

type steering_file:

str

return:

OK on success, Error on failure.

rtype:

ReturnValue

Usage

mafw db diff [OPTIONS] STEERING_FILE

Options

-d, --migration-directory <directory>

Override directory.

Arguments

STEERING_FILE

Required argument

migrate

Versioned schema-migration commands.

The migrate subgroup exposes generate, status, up and baseline. Use mafw db diff for a read-only report of the detected differences.

param ctx:

The click context.

type ctx:

click.core.Context

Usage

mafw db migrate [OPTIONS] COMMAND [ARGS]...

baseline

Baseline a legacy database by recording its existing schema.

Creates the migration history and records the existing schema as the initial applied entry, running no create/alter/drop against the existing tables. It refuses (without modification) when a history already exists.

Added in version 2.4.

param obj:

The root context object.

type obj:

dict

param directory:

Optional migration-directory override.

type directory:

str | None

param steering_file:

Path to the steering file.

type steering_file:

str

return:

OK on success, Error when a history already exists.

rtype:

ReturnValue

Usage

mafw db migrate baseline [OPTIONS] STEERING_FILE

Options

-d, --migration-directory <directory>

Override directory.

Arguments

STEERING_FILE

Required argument

generate

Generate one reviewable migration script for a supported change.

The command never alters the database. It reports the absolute path of the generated script. If a pending migration already exists, or the diff contains only unsupported differences, it reports that and exits with an error status.

Added in version 2.4.

param obj:

The root context object.

type obj:

dict

param directory:

Optional migration-directory override.

type directory:

str | None

param steering_file:

Path to the steering file.

type steering_file:

str

return:

OK on success, Error otherwise.

rtype:

ReturnValue

Usage

mafw db migrate generate [OPTIONS] STEERING_FILE

Options

-d, --migration-directory <directory>

Override directory.

Arguments

STEERING_FILE

Required argument

status

Show the applied and pending migrations for the target database.

Applied migrations are listed with their identifier and application timestamp in chronological order; pending migrations are listed in migration order. A legacy database (no history) is reported distinctly from a fully applied one.

Added in version 2.4.

param obj:

The root context object.

type obj:

dict

param directory:

Optional migration-directory override.

type directory:

str | None

param steering_file:

Path to the steering file.

type steering_file:

str

return:

OK on success, Error on inconsistency or unavailable database.

rtype:

ReturnValue

Usage

mafw db migrate status [OPTIONS] STEERING_FILE

Options

-d, --migration-directory <directory>

Override directory.

Arguments

STEERING_FILE

Required argument

up

Apply all pending migrations in ascending version order.

Each script is applied exactly once and recorded in the history before the next is applied. On the first failure the command halts, names the failing script, and leaves the schema and history consistent. After applying, the schema is re-checked against the models.

param obj:

The root context object.

type obj:

dict

param directory:

Optional migration-directory override.

type directory:

str | None

param steering_file:

Path to the steering file.

type steering_file:

str

return:

OK on success, Error on the first application failure.

rtype:

ReturnValue

Usage

mafw db migrate up [OPTIONS] STEERING_FILE

Options

-d, --migration-directory <directory>

Override directory.

Arguments

STEERING_FILE

Required argument

wizard

Reflect an existing DB into a python module.

About connection options (user / host / port):

That information will be used only in case you are trying to access a network database (MySQL or PostgreSQL). In case of Sqlite, the parameters will be discarded.

About passwords:

If you need to specify a password to connect to the DB server, just add –password in the command line without typing your password as clear text. You will be prompted to insert the password with hidden characters at the start of the processor.

About engines:

The full list of supported engines is provided in the option below. If you do not specify any engine and the database is actually an existing filename, then engine is set to Sqlite, otherwise to postgresql.

param database:

The name of the database.

type database:

str

param schema:

The database schema to be reflected.

type schema:

str

param engine:

The database engine. A selection of possible values is provided in the script help.

type engine:

str

param password:

The password for the DB connection. Not used in case of Sqlite.

type password:

str

param user:

The username for the DB connection. Not used in case of Sqlite.

type user:

str

param port:

The port number of the database server. Not used in case of Sqlite.

type port:

int

param host:

The database hostname. Not used in case of Sqlite.

type host:

str

param output_file:

The filename for the output python module.

type output_file:

click.Path | pathlib.Path | str

param snake_case:

Flag to select snake_case convention for table and field names, or all small letter formatting.

type snake_case:

bool

param ignore_unknown:

Flag to ignore unknown fields. If False, an unknown field will be labelled with UnknownField.

type ignore_unknown:

bool

param with_views:

Flag to include views in the reflected elements.

type with_views:

bool

param preserve_order:

Flag to select if table fields should be reflected in the original order (True) or in alphabetical order (False)

type preserve_order:

bool

param tables:

A tuple containing a selection of table names to be reflected.

type tables:

tuple[str, …]

param overwrite:

Flag to overwrite the output file if exists. If False and the output file already exists, the user can decide what to do.

type overwrite:

bool

param ctx:

The click context, that includes the original object with global options.

type ctx:

click.core.Context

return:

The script return value

Usage

mafw db wizard [OPTIONS] DATABASE

Options

-o, --output-file <output_file>

The name of the output file with the reflected model.

-s, --schema <schema>

The name of the DB schema

-t, --tables <tables>

Generate model for selected tables. Multiple option possible.

--overwrite, --no-overwrite

Overwrite output file if already exists.

--preserve-order, --no-preserve-order

Preserve column order.

--with-views, --without-views

Include also database views.

--ignore-unknown, --no-ignore-unknown

Ignore unknown fields.

--snake-case, --no-snake-case

Use snake case for table and field names.

--host <host>

Hostname for the DB server.

-p, --port <port>

Port number for the DB server.

-u, --user, --username <user>

Username for the connection to the DB server.

--password <password>

Insert password when prompted

-e, --engine <engine>

The DB engine

Options:

cockroach | cockroachdb | crdb | mysql | mysqldb | postgres | postgresql | sqlite | sqlite3

Arguments

DATABASE

Required argument

Database name or path to reflect (e.g. a SQLite file or PostgreSQL name)

filter

Extract and transform reusable filter files.

Usage

mafw filter [OPTIONS] COMMAND [ARGS]...

drop

Remove filter definitions from a steering file without exporting them.

Usage

mafw filter drop [OPTIONS]

Options

-i, --input <source>

Required

--yes

Confirm modifying the input without prompting.

extract

Export filters from a steering file.

Usage

mafw filter extract [OPTIONS]

Options

-i, --input <source>

Required

-o, --output <output>

Required

--strip

Remove exported filters from the source, retaining new_only.

--yes

Confirm file overwrites without prompting.

merge

Merge two or more filter files into a single filter file.

Usage

mafw filter merge [OPTIONS]

Options

-i, --input <filters>

Required Input filter TOML; provide at least two in precedence order.

-o, --output <output>

Required

--yes

Confirm file overwrites without prompting.

init

Create a ready-to-use MAFw analysis project from the bundled template.

The command normalises the project name, validates it, renders the canonical template, writes the project atomically, and prints the commands needed to install and run the example. In interactive mode it prompts for any missing required value and for the optional description and Python version; with --non-interactive it never prompts. Use --with-storage to include an example logical storage volume; storage remains disabled by default.

Changed in version 2.4: Added the --with-storage and --without-storage options.

param obj:

The context object carrying the global options.

type obj:

dict

param project_name:

The distribution name of the new project (hyphens allowed).

type project_name:

str | None

param path:

The parent directory for the new project.

type path:

pathlib.Path | None

param description:

An optional project description.

type description:

str | None

param python_version:

An optional minimum Python version.

type python_version:

str | None

param author_name:

An optional project author name.

type author_name:

str | None

param author_email:

An optional project author e-mail address.

type author_email:

str | None

param with_storage:

Include an example logical storage volume.

type with_storage:

bool

param non_interactive:

Disable all prompting.

type non_interactive:

bool

param install:

Install the generated project with the given (or default) manager.

type install:

str | None

param init_git:

Initialise a Git repository in the generated project.

type init_git:

bool

Usage

mafw init [OPTIONS] [PROJECT_NAME]

Options

--path <path>

Parent directory for the new project (default: current directory).

--description <description>

Short description of the project.

--python <python_version>

Minimum supported Python version, e.g. 3.11.

--author <author_name>

Project author name (written into the package metadata).

--author-email <author_email>

Project author e-mail (written into the package metadata).

--with-storage, --without-storage

Include an example logical storage volume in the generated steering file.

--non-interactive

Never prompt; fail if a required value is missing.

--install <install>

Install the generated project, optionally choosing a manager (default: hatch).

--git, --no-git

Initialise a Git repository in the project (opt-in).

Arguments

PROJECT_NAME

Optional argument

list

Display the list of available processors.

This command will retrieve all available processors via the plugin manager. Both internal and external processors will be listed if the ext-plugins option is passed.

Usage

mafw list [OPTIONS]

run

Runs a steering file.

param obj:

The context object being passed from the main command.

type obj:

dict

param steering_file:

The path to the input steering file.

type steering_file:

str

param filter_files:

The list of filter files to be overlaid to the steering file.

type filter_files:

tuple[str, …]

Changed in version 2.4: Added ordered external filter overlays through repeatable --filter options.

Usage

mafw run [OPTIONS] STEERING_FILE

Options

--filter <filter_files>

External filter TOML; repeat in precedence order.

Arguments

STEERING_FILE

Required argument

Path to an existing TOML steering file to execute

steering

Create, update, reset, and validate steering files.

Usage

mafw steering [OPTIONS] COMMAND [ARGS]...

add

Add named processor sections at defaults; existing sections are unchanged.

Usage

mafw steering add [OPTIONS] NAMES...

Options

-f, --file <filename>

Required Steering TOML file to edit.

Arguments

NAMES

Required argument(s)

create

Generates a steering file with the default parameters of all available processors.

The user must modify the generated steering file to ensure it can be executed using the run command.

param obj:

The context object being passed from the main command.

type obj:

dict

param show:

Display the steering file in the console after the generation. Defaults to False.

type show:

bool

param ext_plugins:

Extend the search for processor to external libraries.

type ext_plugins:

bool

param open_editor:

Open a text editor after the generation to allow direct editing.

type open_editor:

bool

param steering_file:

The steering file path.

type steering_file:

Path

param db_engine:

The name of the db engine.

type db_engine:

str

param db_url:

The URL of the database.

type db_url:

str

Usage

mafw steering create [OPTIONS] STEERING_FILE

Options

--show, --no-show

Display the generated steering file on console

--ext-plugins, --no-ext-plugin

Load external plugins

--open-editor, --no-open-editor

Open the file in your editor.

--db-engine <db_engine>

Select a DB engine

Options:

sqlite | mysql | postgresql

--db-url <db_url>

URL to the DB

Arguments

STEERING_FILE

Required argument

Path to the TOML steering file to generate

merge

Overlay external filters into a standalone steering file.

Usage

mafw steering merge [OPTIONS]

Options

-i, --input <source>

Required

--filter <filters>

Required

-o, --output <output>

--in-place

Replace the input steering file after confirmation.

--yes

Confirm file overwrites without prompting.

reset

Reset selected processor parameters to their current defaults.

Usage

mafw steering reset [OPTIONS] [NAMES]...

Options

-f, --file <filename>

Required Steering TOML file to edit.

--all

Reset every discovered processor.

Arguments

NAMES

Optional argument(s)

update

Add missing processor sections and schema parameters without changing values.

Usage

mafw steering update [OPTIONS] [NAMES]...

Options

-f, --file <filename>

Required Steering TOML file to update.

--all

Update every discovered processor.

Arguments

NAMES

Optional argument(s)

validate

Load GUI-equivalent plugin registrations and validate without writing the file.

Usage

mafw steering validate [OPTIONS]

Options

-f, --file <filename>

Required Steering TOML file to validate.

--level <level>

Validation level to use.

Default:

'semantic'

Options:

semantic | full

author:

Bulgheroni Antonio

class mafw.scripts.mafw_exe.MAFwGroup(name: str | None = None, commands: MutableMapping[str, Command] | Sequence[Command] | None = None, invoke_without_command: bool = False, no_args_is_help: bool | None = None, subcommand_metavar: str | None = None, chain: bool = False, result_callback: Callable[[...], Any] | None = None, **kwargs: Any)

Bases: AbbreviateGroup

Click group with abbreviation and MAFw-specific exit handling.

group_class

alias of AbbreviateGroup

_detect_command_name(args: list[str]) → str | None

Return the first subcommand token while skipping root option values.

invoke(ctx: Context) → Any

Invoke the command and normalize Click exceptions to MAFw exits.

main(*args: Any, **kwargs: Any) → None

Run the CLI and convert returned statuses to process exit codes.

parse_args(ctx: Context, args: list[str]) → list[str]

Parse arguments and record the selected root command before invoke.

class mafw.scripts.mafw_exe.ReturnValue(*values)

Bases: IntEnum

Enumerator to handle the script return value.

Error = 1

Generic error

OK = 0

No error

mafw.scripts.mafw_exe.custom_formatwarning(message: Warning | str, category: type[Warning], filename: str, lineno: int, line: str | None = None) → str

Return the pure message of the warning.

mafw.scripts.mafw_exe.display_exception(exception: Exception, show_traceback: bool = False) → None

Display exception information with optional debug details.

This function logs exception information at the critical level. When show_traceback is enabled, it logs the full exception including traceback information. Otherwise, it logs a simplified message directing users to enable debug mode for more details.

Parameters:

• exception (Exception) – The exception to be displayed and logged.

• show_traceback (bool) – Flag indicating whether to show detailed traceback information. Defaults to False

mafw.scripts.mafw_exe.is_bugged_warning_capture_version() → bool

Check if the Python version has the warning capture bug in free-threading mode.

Python 3.14.0 through 3.14.3 (free-threading builds only) have a bug where logging.captureWarnings(True) can crash or misbehave. This function returns True when the current interpreter is affected.

Note

See https://github.com/python/cpython/pull/146374 for details.

Todo

Remove this workaround when Python 3.14 is no longer a supported version (expected late 2030).

Returns:

True if the interpreter is affected by the warning capture bug, False otherwise.

Return type:

bool

mafw.scripts.mafw_exe.logger_setup(level: str, ui: str, tracebacks: bool) → None

Set up the logger.

This function is actually configuring the root logger level from the command line options and it attaches either a RichHandler or a StreamHandler depending on the user interface type.

The tracebacks flag is used only by the RichHandler. Printing the tracebacks is rather useful when debugging the code, but it could be detrimental for final users. In normal circumstances, tracebacks is set to False, and is turned on when the debug flag is activated.

Parameters:

• level (str) – Logging level as a string.

• ui (str) – User interface as a string (‘rich’ or ‘console’).

• tracebacks – Enable/disable the logging of exception tracebacks.

mafw.scripts.mafw_exe.print_banner(ctx: Context) → None

Print the welcome banner only once, only for rich UI, and only if not disabled.

Note

ctx.obj is not yet populated when Group.invoke() is called, but ctx.params contains parsed options for the current group. We therefore inspect the root context params.