click_utils package

Submodules

click_utils.defaults module

click_utils.help module

class click_utils.help.EnvHelpCommand(*args, **kwargs)

Bases: click.core.Command

class click_utils.help.EnvHelpOption(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, **attrs)

Bases: click.core.Option

get_envvar_names(ctx)

get_help_record(ctx)

click_utils.logging module

class click_utils.logging.LogLevelChoice(*extra_levels)

Bases: click.types.Choice

A subclass of click.Choice class for specifying a logging level.

Example usage:

import click
import click_utils

@click.command()
@click.option('--loglevel', type=click_utils.LogLevelChoice())
def cli(loglevel):
    click.echo(loglevel)

This option type returns an integer representation of a logging level:

$ cli --loglevel=error
40

By default available choices are the lowercased standard logging level names (i.e notset, debug, info, warning, error and critical):

$ cli --help

Usage: cli [OPTIONS]

Options:
  --loglevel [notset|debug|info|warning|error|critical]
...

But you can pass your additional logging levels like this:

logging.addLevelName(102, 'My custom level')

@click.command()
@click.option('--loglevel', type=click_utils.LogLevelChoice(101, 102))
def cli(loglevel):
    click.echo(loglevel)

...

$ cli --help

Usage: cli [OPTIONS]

Options:
  --loglevel [notset|debug|info|warning|error|critical|level101|mycustomlevel]
...

$ cli --loglevel=level101
101

You can also pass level name in the uppercased form:

$ cli --loglevel=WARNING
30

Finally, as a special case, user can provide any integer as a logging level:

$ cli --loglevel=123
123

LOGGING_LEVELS = (('notset', 0), ('debug', 10), ('info', 20), ('warning', 30), ('error', 40), ('critical', 50))

convert(value, param, ctx)

click_utils.logging.logconfig_callback(ctx, param, value)

a default callback for invoking:

logging.config.fileConfig(value, defaults=None, disable_existing_loggers=False)

click_utils.logging.logconfig_callback_factory(defaults=None, disable_existing_loggers=False)

a factory for creating parametrized callbacks to invoke logging.config.fileConfig

click_utils.logging.logconfig_option(*param_decls, **attrs)

An option to easily configure logging via logging.config.fileConfig. This one allows to specify a file that will be passed as an argument to logging.config.fileConfig function. Using this option like this:

@click.command()
@click_utils.logconfig_option()
def cli():
    pass

is equivalent to:

def mycallback(ctx, param, value):
    if not value or ctx.resilient_parsing:
        return
    logging.config.fileConfig(value,
                              defaults=None,
                              disable_existing_loggers=False)

@click.command()
@click.option('--logconfig',
              expose_value=False,
              type=click.Path(exists=True, file_okay=True, dir_okay=False,
                              writable=False, readable=True, resolve_path=True)
              callback=mycallback
              )
def cli():
    pass

This option accepts all the usual arguments and keyword arguments as click.option (be careful with passing a different callback though). Additionally it accepts two extra keyword arguments which are passed to logging.config.fileConfig:

• fileconfig_defaults is passed as defaults argument (default: None)
• disable_existing_loggers is passed as disable_existing_loggers argument (default: False)

So you can add logconfig option like this:

@click.command()
@click_utils.logconfig_option(disable_existing_loggers=True)
def cli():
    pass

click_utils.logging.logfile_option(*param_decls, **attrs)

a specific type of logger_option that configures a logging file handler (by default it’s a logging.handlers.RotatingFileHandler) on a logger (root logger by default).

In addition to all click_utils.logger_option and click.option arguments it accepts four keyword arguments to control handler creation and format settings.

Parameters:

• fmt – a format (fmt) argument for logging.Formatter class
• datefmt – a date format (datefmt) argument for logging.Formatter class
• maxBytes – a maxBytes argument for RotatingFileHandler class
• backupCount – a backupCount argument for RotatingFileHandler class

click_utils.logging.logger_callback_factory(logger_name='', handler_cls=None, handler_attrs=None, formatter_cls=None, formatter_attrs=None, filters=None, level=None, ctx_loglevel_attr=None, ctx_key=None)

click_utils.logging.logger_option(*param_decls, **attrs)

An abstract option for configuring a specific handler to a given logger (root logger by default). This logger is then attached to a context for further usage. This option accepts all the

Parameters:

• handler_cls – required a logging Handler class. A value of this option will be passed as a first positional argument while creating an instance of the handler_cls.
• handler_attrs – a dictionary of keyword arguments passed to handler_cls while instantiating
• formatter_cls – a Formatter class which instance will be added to a handler
• formatter_attrs – a dictionary of keyword arguments passed to formatter_cls while instantiating
• filters – an iterable of filters to add to the logger
• level – enforce a minimum logging level on a logger and handler. If this is None then a callback will try to retrieve the level from context (e.g. that was stored by loglevel_option). If it fails to find it a default level is logging.WARNING
• ctx_loglevel_attr – an attribute name of the context to find a stored logging level (by loglevel_option for example)
• ctx_key – an attribute name of the context to store a logger. Pass a falsy value to disable storing (default: None).
• logger_name – a name of a logger to configure (default: '' i.e. a root logger)

click_utils.logging.loglevel_callback_factory(ctx_loglevel_attr=None)

click_utils.logging.loglevel_option(*param_decls, **attrs)

Shortcut for logging level option type.

This is equivalent to decorating a function with option() with the following parameters:

@click.command()
@click.option('--loglevel', type=click_utils.LogLevelChoice())
def cli(loglevel):
    pass

It also has a callback that stores a chosen loglevel on the context object. By default the loglevel is stored in attribute called click_utils_loglevel

To change the attribute name you can pass an keyword arg to this option called ctx_loglevel_attr. This is useful for other options to know what loglevel was set. If you want to disable storing the loglevel on context just pass:

@click.command()
@click_utils.loglevel_option(ctx_loglevel_attr=False)
def cli(loglevel):
    click.echo(loglevel)

Also this option is eager by default.

Module contents