clapper.click

Helpers to build command-line interfaces (CLI) via click.

Module Attributes

module_logger

Module logger.

Functions

config_group(logger, entry_point_group)	Add a command group to list/describe/copy job configurations.
log_parameters(logger_handle[, ignore])	Log the click parameters with the logging module.
user_defaults_group(logger, config)	Add a command group to read/write RC configuration.
verbosity_option(logger[, short_name, name, ...])	Click-option decorator that adds a -v/--verbose option to a cli.

Classes

AliasedGroup([name, commands, ...])	Class that handles prefix aliasing for commands.
ConfigCommand(name, *args[, help, ...])	A click.Command that can read options from config files.
CustomParamType()	Custom parameter class allowing click to receive complex Python types as parameters.
ResourceOption([param_decls, show_default, ...])	An extended click.Option that automatically loads resources from config files.

clapper.click.module_logger = <Logger clapper.click (WARNING)>

Module logger.

clapper.click.verbosity_option(logger, short_name='v', name='verbose', dflt=0, **kwargs)

Click-option decorator that adds a -v/--verbose option to a cli.

This decorator adds a click option to your CLI to set the log-level on a provided logging.Logger. You must specifically determine the logger that will be affected by this CLI option, via the logger option.

@verbosity_option(logger=logger)

The verbosity option has the “count” type, and has a default value of 0. At each time you provide -v options on the command-line, this value is increased by one. For example, a CLI setting of -vvv will set the value of this option to 3. This is the mapping between the value of this option (count of -v CLI options passed) and the log-level set at the provided logger:

• 0 (no -v option provided): logger.setLevel(logging.ERROR)

• 1 (-v): logger.setLevel(logging.WARNING)

• 2 (-vv): logger.setLevel(logging.INFO)

• 3 (-vvv or more): logger.setLevel(logging.DEBUG)

The verbosity level specified in this option will also be set during the loading of the ResourceOption or CommandConfig configuration files unless verbosity_option is a ResourceOption itself. If this is the case, the logging level during the configuration loading will be the default level of the logger and the option will only effect the logging after the options handling.

Parameters:

• logger (Logger) – The logging.Logger to be set.

• short_name (str) – Short name of the option. If not set, then use v

• name (str) – Long name of the option. If not set, then use verbose – this will also become the name of the contextual parameter for click.

• dflt (int) – The default verbosity level to use (defaults to 0).

• **kwargs (Any) – Further keyword-arguments to be forwarded to the underlying click.option()

Return type:

Callable[..., Any]

Returns:

A callable, that follows the click-framework policy for option decorators. Use it accordingly.

class clapper.click.ConfigCommand(name, *args, help=None, entry_point_group=None, **kwargs)

Bases: Command

A click.Command that can read options from config files.

Warning

In order to use this class, you have to use the ResourceOption class also.

Parameters:

• name (str) – The name to be used for the configuration argument

• *args (tuple) – Unnamed parameters passed to click.Command

• help (str | None) – Help message associated with this command

• entry_point_group (str | None) – Name of the entry point group from which entry-points will be searched

• **kwargs (Any) – Named parameters passed to click.Command

config_argument_name: str

The name of the config argument.

entry_point_group: str

The name of entry point that will be used to load the config files.

dump_config(ctx, param, value)

Generate configuration file from parameters and context.

Using this function will conclude the command-line execution.

Parameters:

ctx (Any) – Click context

Return type:

None

class clapper.click.CustomParamType

Bases: ParamType

Custom parameter class allowing click to receive complex Python types as parameters.

name: str = 'custom'

the descriptive name of this type

class clapper.click.ResourceOption(param_decls=None, show_default=False, prompt=False, confirmation_prompt=False, hide_input=False, is_flag=None, flag_value=None, multiple=False, count=False, allow_from_autoenv=True, type=None, help=None, entry_point_group=None, required=False, string_exceptions=None, **kwargs)

Bases: Option

An extended click.Option that automatically loads resources from config files.

This class comes with two different functionalities that are independent and could be combined:

1. If used in commands that are inherited from ConfigCommand, it will lookup inside the config files (that are provided as argument to the command) to resolve its value. Values given explicitly in the command line take precedence.

2. If entry_point_group is provided, it will treat values given to it (by any means) as resources to be loaded. Loading is done using config.load(). Check Loading Single Objects for more details on this topic. The final value cannot be a string.

You may use this class in three ways:

1. Using this class (without using ConfigCommand) AND (providing entry_point_group).

2. Using this class (with ConfigCommand) AND (providing entry_point_group).

3. Using this class (with ConfigCommand) AND (without providing entry_point_group).

Using this class without ConfigCommand and without providing entry_point_group does nothing and is not allowed.

entry_point_group: str | None

If provided, the strings values to this option are assumed to be entry points from entry_point_group that need to be loaded.

This may be different than the wrapping ConfigCommand.

string_exceptions: list[str] | None

If provided and entry_point_group is provided, the code will not treat strings in string_exceptions as entry points and does not try to load them.

consume_value(ctx, opts)

Retrieve value for parameter from appropriate context.

This method will retrieve the value of its own parameter from the appropriate context, by trying various sources.

Parameters:

• ctx (Context) – The click context to retrieve the value from

• opts (dict) – command-line options, eventually passed by the user

Return type:

tuple[Any, ParameterSource]

Returns:

A tuple containing the parameter value (of any type) and the source it used to retrieve it.

type_cast_value(ctx, value)

Convert and validate a value against the option’s type.

This method considers the option’s type, multiple, and nargs. Furthermore, if the an entry_point_group is provided, it will load it.

Parameters:

• ctx (Context) – The click context to be used for casting the value

• value (Any) – The actual value, that needs to be cast

Return type:

Any

Returns:

The cast value

class clapper.click.AliasedGroup(name=None, commands=None, invoke_without_command=False, no_args_is_help=None, subcommand_metavar=None, chain=False, result_callback=None, **kwargs)

Bases: Group

Class that handles prefix aliasing for commands.

Basically just implements get_command that is used by click to choose the command based on the name.

Example

To enable prefix aliasing of commands for a given group, just set cls=AliasedGroup parameter in click.group decorator.

get_command(ctx, cmd_name)

get_command with prefix aliasing.

clapper.click.user_defaults_group(logger, config)

Add a command group to read/write RC configuration.

This decorator adds a whole command group to a user predefined function which is part of the user’s CLI. The command group allows the user to get and set options through the command-line interface:

import logging
from expose.rc import UserDefaults
from expose.click import user_defaults_group

logger = logging.getLogger(__name__)
user_defaults = UserDefaults("~/.myapprc")
...


@user_defaults_group(logger=logger, config=user_defaults)
def rc(**kwargs):
    '''Use this command to affect the global user configuration.'''
    pass

Then use it like this:

$ user-cli rc --help
usage: ...

Return type:

Callable[..., Any]

clapper.click.config_group(logger, entry_point_group)

Add a command group to list/describe/copy job configurations.

This decorator adds a whole command group to a user predefined function which is part of the user’s CLI. The command group provides an interface to list, fully describe or locally copy configuration files distributed with the package. Commands accept both entry-point or module names to be provided as input.

import logging
from expose.click import config_group

logger = logging.getLogger(__name__)
...


@config_group(logger=logger, entry_point_group="mypackage.config")
def config(**kwargs):
    '''Use this command to list/describe/copy config files.'''
    pass

Then use it like this:

$ user-cli config --help
usage: ...

Return type:

Callable[..., Any]

clapper.click.log_parameters(logger_handle, ignore=None)

Log the click parameters with the logging module.

Parameters:

• logger – The logging.Logger handle to write debug information into.

• ignore (tuple[str] | None) – List of the parameters to ignore when logging. (Tuple)