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.

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

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.

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

Pop timeout-related kwargs and build a TimeoutConfig.

nadzoring.utils.decorators._parse_proxy_url(proxy_url: str) → tuple[str, str, int]

Parse proxy URL and return (proxy_type, host, port).

Supported formats: - socks5://host:port - socks4://host:port - http://host:port - https://host:port

Parameters:

proxy_url – Proxy URL string.

Returns:

Tuple of (proxy_type, host, port).

Raises:

ValueError – If proxy URL format is invalid.

nadzoring.utils.decorators._setup_global_proxy(proxy: str | None) → None

Setup global proxy for all socket connections.

Supports SOCKS4, SOCKS5, HTTP, HTTPS proxies. For HTTP/HTTPS, sets environment variables (compatible with requests library) and configures urllib. For SOCKS, patches the socket module globally.

Parameters:

proxy – Proxy URL (e.g., ‘socks5://host:port’, ‘http://host:port’) or None to disable.

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

Configure logging based on CLI options.

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

Print elapsed time when verbose mode is active.

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

Decorator factory that adds common CLI options to click commands.