mafw.scripts.support

Shared runtime support for the MAFw Click executable.

This module contains root-group behavior, logging and exception display, banner rendering, and warning-capture setup used by the command modules.

author:

Bulgheroni Antonio

Module Attributes

suppress	Modules omitted from rich traceback locals.
LEVELS	Numeric logging levels accepted by the root CLI option.
CONTEXT_SETTINGS	Click settings shared by the MAFw root group.
welcome_message	Styled welcome banner rendered for rich command invocations.
log	Root logger configured by the CLI options.

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.support.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.support.ReturnValue(*values)

Bases: IntEnum

Enumerator to handle the script return value.

Error = 1

Generic error

OK = 0

No error

mafw.scripts.support.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.support.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.support.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.support.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.support.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.

mafw.scripts.support.CONTEXT_SETTINGS = {'help_option_names': ['-h', '--help']}

Click settings shared by the MAFw root group.

mafw.scripts.support.LEVELS = {'critical': 50, 'debug': 10, 'error': 40, 'info': 20, 'warning': 30}

Numeric logging levels accepted by the root CLI option.

mafw.scripts.support._warnings_captured = False

Whether logging has installed the warning capture hook.

mafw.scripts.support.log = <RootLogger root (WARNING)>

Root logger configured by the CLI options.

mafw.scripts.support.suppress = [<module 'click' from '/opt/hatch/env/virtual/mafw/pyqYxQxp/dev.py3.14/lib/python3.14/site-packages/click/__init__.py'>]

Modules omitted from rich traceback locals.

mafw.scripts.support.welcome_message = <rich_pyfiglet.rich_figlet.RichFiglet object>

Styled welcome banner rendered for rich command invocations.