mafw.scripts.mafw_exe

The execution framework.

This module provides the run functionality to the whole library.

It is heavily relying on click for the generation of commands, options, and arguments.

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 v2.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

-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 v2.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

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 v2.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]...

wizard

Reflect an existing DB into a python module.

mafw db wizard [Options] Database

Database Name of the Database to be reflected.

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

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.

STEERING_FILE A path to the steering file to execute.

param obj:: The context object being passed from the main command.
type obj:: dict
param steering_file:: The path to the output steering file.
type steering_file:: Path

Usage

mafw run [OPTIONS] STEERING_FILE

Arguments

STEERING_FILE: Required argument

steering

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

STEERING_FILE A path to the steering file to execute.

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 [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

Functions

`custom_formatwarning`(message, category, ...)	Return the pure message of the warning.
`display_exception`(exception[, show_traceback])	Display exception information with optional debug details.
`is_bugged_warning_capture_version`()	Check if the Python version has the warning capture bug in free-threading mode.
`logger_setup`(level, ui, tracebacks)	Set up the logger.
`print_banner`(ctx)	Print the welcome banner only once, only for rich UI, and only if not disabled.

Classes

`MAFwGroup`([name, commands, ...])	Click group with abbreviation and MAFw-specific exit handling.
`ReturnValue`(*values)	Enumerator to handle the script return value.

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)[source]

Bases: AbbreviateGroup

Click group with abbreviation and MAFw-specific exit handling.

group_class: alias of AbbreviateGroup

_detect_command_name(args: list[str]) → str | None[source]: Return the first subcommand token while skipping root option values.

invoke(ctx: Context) → Any[source]: Invoke the command and normalize Click exceptions to MAFw exits.

main(*args: Any, **kwargs: Any) → None[source]: Run the CLI and convert returned statuses to process exit codes.

parse_args(ctx: Context, args: list[str]) → list[str][source]: Parse arguments and record the selected root command before invoke.

class mafw.scripts.mafw_exe.ReturnValue(*values)[source]

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[source]: Return the pure message of the warning.

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

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[source]

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[source]

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[source]: 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.