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.

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.
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, ...])	Custom Click Group for MAFw runner.
ReturnValue(value)	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)

Bases: Group

Custom Click Group for MAFw runner.

It implements two main features:

1. Support commands abbreviation. Instead of providing the whole command, the user can use whatever abbreviation instead as long as it is unique. So for example, instead of mafw list, the use can provide mafw l and the result will be the same.

2. Implements the cascading of return values among different command levels.

get_command(ctx: Context, cmd_name: str) → Command | None

Return a command.

Given a context and a command name as passed from the CLI, the click.Command is returned. This method overloads the basic one allowing to use command abbreviations.

If more than one match is found, then an error is raised.

If no matches are found, then click will handle this case as in the standard situation.

Parameters:

• ctx – The click context

• cmd_name – The command name as provided from the CLI

Returns:

The corresponding command or None if no command is found.

invoke(ctx: Context) → Any

Invoke the command.

This override method is just wrapping the base invoke call in a try / except block.

In the case of a ClickException, then this is shown and its exit code is used passed to the sys.exit call. In case of a SystemExit or click.exceptions.Exit, then this is simply re-raised, so that Click can handle it as in normal circumstances In all other cases, the exception is caught and the sys.exit is called with the ReturnValue.Error.

Parameters:

ctx – The click context

Returns:

The return value of the invoked command

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

Override main to handle return values properly.

class mafw.scripts.mafw_exe.ReturnValue(value)

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