click_utils package¶
Submodules¶
click_utils.defaults module¶
click_utils.help module¶
click_utils.logging module¶
-
class
click_utils.logging.
LogLevelChoice
(*extra_levels)[source]¶ 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.enotset
,debug
,info
,warning
,error
andcritical
):$ 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))¶
-
-
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)[source]¶ a factory for creating parametrized callbacks to invoke
logging.config.fileConfig
-
click_utils.logging.
logconfig_option
(*param_decls, **attrs)[source]¶ An option to easily configure logging via
logging.config.fileConfig
. This one allows to specify a file that will be passed as an argument tologging.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 differentcallback
though). Additionally it accepts two extra keyword arguments which are passed tologging.config.fileConfig
:fileconfig_defaults
is passed asdefaults
argument (default:None
)disable_existing_loggers
is passed asdisable_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)[source]¶ a specific type of
logger_option
that configures a logging file handler (by default it’s alogging.handlers.RotatingFileHandler
) on a logger (root logger by default).In addition to all
click_utils.logger_option
andclick.option
arguments it accepts four keyword arguments to control handler creation and format settings.Parameters: - fmt – a format (
fmt
) argument forlogging.Formatter
class - datefmt – a date format (
datefmt
) argument forlogging.Formatter
class - maxBytes – a
maxBytes
argument forRotatingFileHandler
class - backupCount – a
backupCount
argument forRotatingFileHandler
class
- fmt – a format (
-
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)[source]¶
-
click_utils.logging.
logger_option
(*param_decls, **attrs)[source]¶ 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 byloglevel_option
). If it fails to find it a default level islogging.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)
- 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
-
click_utils.logging.
loglevel_option
(*param_decls, **attrs)[source]¶ 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.