rics.click#

Utility functions and classes for working with https://pypi.org/project/click/ CLI applications.

Functions

get_user_command([cxt, meta])

Recreate the user CLI command.

logging_verbosity_option(*param_decls[, ...])

Add a click option to a command.
get_user_command(cxt: Context | None = None, *, meta: bool = True) → str[source]#

Recreate the user CLI command.

Parameters:

  • cxt – Click context. Derive is None.

  • meta – If True, use click.Context.meta caching.

Returns:

A user command such as python -m rics.cli -v kernel --name=my-kernel.

logging_verbosity_option(*param_decls: str, mode: Literal['forward', 'forward_both', 'pop', 'skip'] = 'pop', levels: Iterable[Mapping[str, int | str] | Mapping[Logger, int | str] | Mapping[str | Logger, int | str] | Mapping[str | LoggerAdapter[Any], int | str] | Mapping[str | Logger | LoggerAdapter[Any], int | str]], format: str = '%(asctime)s [%(name)s:%(levelname)s] %(message)s', datefmt: str = '%Y-%m-%dT%H:%M:%S', cls: type[Option] | None = None, **attrs: Any) → Callable[[Callable[[...], Any]], Callable[[...], Any]][source]#

Add a click option to a command.

Mode options:

  • forward: Configure logging, then forward the parameter.

  • forward_both: Do not configure logging. Forward a tuple (verbosity, helper) instead.

  • pop (default): Configure logging and remove the parameter.

  • skip: Does not configure logging or create a helper. The parameter is forwarded.

Parameters:

  • *param_decls – Positional arguments to the constructor of cls.

  • mode – Logging setup mode. See above for options.

  • levels – An iterable of levels, where each level is a dict {logger_name: log_level}.

  • format – Format string for emitted messages; see rics.logs.basic_config().

  • datefmt – Format string for date/time; see rics.logs.basic_config().

  • cls – Type of click.Option to instantiate.

  • **attrs – Passed as keyword arguments to the constructor of cls. Defaults are provided for help, count, and type.

Raises:

TypeError – If attrs is incompatible with this method.

See also

The click.option() function and rics.logs.LoggingSetupHelper() class.

Examples

Decorating click commands.

>>> import logging, click
>>> @click.command
>>> @logging_verbosity_option(
...     "--verbose", "-v",
...     levels=[
...         {"rics": "INFO", "id_translation": "WARNING"},
...         {"rics": "DEBUG"},
...     ],
... )
>>> @click.pass_context
>>> def cli(cxt: click.Context, verbose: int) -> None:
>>>     print(verbose)
>>>     print(logging.getLogger("rics"))
>>>     print(logging.getLogger("id_translation"))

When running this command, passing -vv increases rics verbosity to logging.DEBUG.

Advanced configuration with mode="forward_both".

>>> import logging, click
>>> from rics.logs import LoggingSetupHelper
>>> @click.command
>>> @logging_verbosity_option(
...     "--verbose", "-v",
...     mode="forward_both",
...     levels=[
...         {"rics": "INFO", "id_translation": "WARNING"},
...         {"rics": "DEBUG"},
...     ],
... )
>>> @click.pass_context
>>> def cli(
...     cxt: click.Context,
...     verbose: tuple[int, LoggingSetupHelper],
... ) -> None:
>>>     verbosity, helper = verbose
>>>     helper.configure_logging(verbosity)  # 0=logging.root.disabled=True
>>>     if verbosity == 0:
>>>         import os, sys
>>>         sys.stdout = open(os.devnull, "w")
>>>         cxt.meta["no_stdout"] = True

In this mode, LoggingSetupHelper.configure_logging() is not called before invoking cli(). Above is a dummy program that disables sys.stdout if verbosity is zero (i.e. -v is repeated zero times).