nadzoring.utils.decorators module

Common decorators for CLI commands.

class nadzoring.utils.decorators._CliOptionSpec(flag: str, kwarg: str, click_options: tuple[Any, ...], extractor: Callable[[dict[str, Any]], Any], default: Any)

Bases: object

Descriptor for a single injectable CLI option group.

Adding a new option to the decorator requires only a new entry in _OPTION_REGISTRY — nothing else in this file changes.

flag

Keyword argument name for common_cli_options, e.g. "include_verbose".

Type:

str

kwarg

Parameter name injected into the wrapped function, e.g. "verbose".

Type:

str

click_options

Click option decorators that register the underlying CLI flags. May be empty when the injected value is synthesised from multiple raw flags (e.g. timeout_config).

Type:

tuple[Any, …]

extractor

(kwargs) -> value — pops the relevant keys from the raw kwargs dict and returns the value to inject.

Type:

collections.abc.Callable[[dict[str, Any]], Any]

default

Value used when the option group is disabled.

Type:

Any

__init__(flag: str, kwarg: str, click_options: tuple[Any, ...], extractor: Callable[[dict[str, Any]], Any], default: Any) → None

click_options: tuple[Any, ...]

default: Any

extractor: Callable[[dict[str, Any]], Any]

flag: str

kwarg: str

nadzoring.utils.decorators._handle_output(result: Any, output_format: str, *, no_color: bool) → None

Render command results in the requested format.

Parameters:

• result – Data returned by the command.

• output_format – One of json, yaml, table, csv, html, html_table.

• no_color – Disable ANSI colours in table output.

Raises:

click.ClickException – On any rendering error.

nadzoring.utils.decorators._handle_save(result: Any, save_path: str | None, output_format: str) → None

Persist command results to a file when a path is provided.

Parameters:

• result – Data returned by the command.

• save_path – Destination path, or None to skip.

• output_format – Format used when serialising.

Raises:

click.ClickException – On any I/O error.

nadzoring.utils.decorators._make_timeout_config(kwargs: dict[str, Any]) → TimeoutConfig

Pop timeout-related kwargs and build a TimeoutConfig.

Resolution order for connect and read: 1. Explicit --connect-timeout / --read-timeout. 2. Generic --timeout (lifetime fallback for both phases). 3. Module-level defaults.

Parameters:

kwargs – Mutable dict from the wrapper call.

Returns:

Fully populated TimeoutConfig.

nadzoring.utils.decorators._setup_logging(cli_options: SimpleNamespace) → None

Configure logging based on CLI options.

Parameters:

cli_options – Namespace with verbose, quiet, no_color.

nadzoring.utils.decorators._show_completion_time(elapsed: float, *, verbose: bool) → None

Print elapsed time when verbose mode is active.

Parameters:

• elapsed – Seconds since the command started.

• verbose – Emit the timing line only when True.

nadzoring.utils.decorators.common_cli_options(**enabled_flags: bool) → Callable[[F], F]

Decorator factory that adds common CLI options to click commands.

Pass any subset of the known include_* flags as keyword arguments. Unknown flag names raise ValueError at decoration time.

Known flags (see _OPTION_REGISTRY for the authoritative list):

include_verbose, include_quiet, include_no_color, include_output, include_save, include_timeout.

Parameters:

**enabled_flags – Mapping of include_<name> → bool. Omitted flags default to False.

Returns:

A decorator that wraps a click command with the requested options.

Raises:

ValueError – If an unknown flag name is supplied.

Example

@click.command() @common_cli_options(include_verbose=True, include_timeout=True) def port_scan(verbose: bool, timeout_config: TimeoutConfig) -> dict:

…