Package: clickext
clickextExtended features for the Pythonclicklibrary. Includes global logging configuration and error handling for pretty console output, aliased commands, command groups with global and shared subcommand options, mutually exclusive options, verbosity level options, and a configuration file option.RequirementsPython 3.10.x, 3.11.xclick 8.x.xInstallationpip install clickextUsageLogging and Error MessagesThis functionality is disabled by default. It must be explicitly enabled by callingclickext.init_loggingor using theclickext.verboseorclickext.verbositydecorators on a command.The logging facility provides a way to capture all informational output, emit console-friendly messages, and control the output that is displayed based on the logging level.click.ClickException,click.UsageError, their children, warnings issued bywarning.warnand any uncaught exceptions are handled by theclickext.log.ConsoleHandler. Exception information, including the traceback, is available when the log level is set tologging.DEBUG. Higher log levels will only print a user-friendly error message. The default level islogging.INFO.All informational messages intended for the console that an application user may want to suppress should be sent in a logging call rather than direct calls toprint,click.echo, or similar, so they can be handled and displayed consistently according to the logging configuration. Messages that should always be displayed (e.g., the expected result of an invoked command) should be displayed withclick.echoandnotsent to a logger.Messages are formatted by default with a styled log level prefix followed by the message, except forlogging.INFOlevel messages which are not prefixed. The style for each level can be customized by passing a mapping of log levels toclick.styleparameters in theclickext.init_loggingcall. Setting a level toNonewill remove the prefix and styles from the message. For example:{logging.INFO: {"fg": "green"}, logging.DEBUG: None}will formatlogging.INFOlevel messages as "Info: {msg}", with "Info:" in green text, andlogging.DEBUGmessages as "{msg}" with no prefix.An additional log level namedQUIETis defined when logging is initialized and can be used to provide a "quiet mode" that hides all informational output sent to a logger.Logging is configured on the root logger in order to capture and format all logging and warning output regardless of where it originates. Any existing configuration will be replaced by the clickext logging facility. Additional handlers that do not write to stdout/stderr can be attached to the application logger normally, and to the root logger by passing them in theclickext.init_loggingcall. The application logger level andpropagateproperties are configured automatically when logging is initialized and should not be changed.Example:import logging
import click
import clickext

logger = logging.getLogger("__package__")
clickext.init_logging(logger, logging.INFO)

@click.command(cls=clickext.ClickextCommand)
def cmd():
    logger.info("some basic info")
    logger.error("uh-oh")
    logger.debug("secrets live here")Output:$ cmd
some basic info
Error: uh-ohCommands with aliasesCommand aliases provide alternate names for a single command. This is helpful for commands with long names or to shorten commands with many options/arguments. Aliased commands must be in aclickext.ClickextGroupcommand group.Example:import click
import clickext

@click.group(cls=clickext.ClickextGroup)
def cli():
    pass

@cli.command(cls=clickext.ClickextCommand, aliases=["c"])
def cmd():
    click.echo("ok!")Output:$ cli cmd
ok!
$ cli c
ok!Mutually exclusive optionsMutually exclusive options prevent two or more options being passed together. Shared and command-specific options can be mutually exclusive. Global group options can be mutually exclusive with other group options, but not with shared parameters or subcommand options.Example:import click
import clickext

@click.command(cls=clickext.ClickextCommand, mx_opts=[("foo", "bar")])
@click.option("--foo", is_flag=True)
@click.option("--bar", is_flag=True)
def cmd(foo, bar):
    passOutput:$ cmd --foo --bar
Usage: cmd [OPTIONS]
Try 'cmd --help' for help.

Error: Mutually exclusive options: --foo --barShared ParametersShared parameters are parameters required by all subcommands in a group. They are defined at the group level and automatically added to all subcommands, but not the group itself. Subcommand signatures must accept the shared parameters as arguments unless the parameter was defined withexpose_value=False.Example:import click
import clickext

@click.group(cls=clickext.ClickextGroup, shared_params=["foo", "bar"])
@click.option("--foo", is_flag=True)
@click.option("--bar", is_flag=True)
def cli():
    pass

@cli.command(cls=clickext.ClickextCommand)
def cmd1(foo, bar):
    for value in [foo, bar]:
        if value:
            click.echo("Yes!")
        else:
            click.echo("No!")

@cli.command(cls=clickext.ClickextCommand)
def cmd2(foo, bar):
    for value in [foo, bar]:
        if value:
            click.echo("Also Yes!")
        else:
            click.echo("Also No!")Output:$ cli cmd1 --foo
Yes!
No!
$ cli cmd2 --foo --bar
Also Yes!
Also Yes!Global OptionsGlobal options are group-level options that may be passed to any subcommand in the group. The options are extracted from the passed arguments before parsing and processed at the group level regardless of where they originally appeared. Global options cannot have the same name as a subcommand or subcommand option; options that accept values should not accept values with the same name as a subcommand.Example:import click
import clickext

@click.group(cls=clickext.ClickextGroup, global_opts=["foo", "bar"])
@click.option("--foo", is_flag=True)
@click.option("--bar", is_flag=True)
def cli(foo, bar):
    for value in [foo, bar]:
        if value:
            click.echo("Yes!")
        else:
            click.echo("No!")

@cli.command(cls=clickext.ClickextCommand)
@click.option("--baz", is_flag=True)
def cmd(baz):
    if baz:
        click.echo("Yes baz!")
    else:
        click.echo("No baz!")Output:$ cli --foo
Yes!
No!
$ cli cmd --bar
No!
Yes!
No baz!
$ cli --bar cmd --baz --foo
Yes!
Yes!
Yes baz!Config OptionTheclickext.config_optionprovides a mechanism for loading configuration from a JSON, TOML, or YAML file and storing it onclick.Context.obj. An optionalprocessorcan be provided to prepare the parsed data for application use.Example config.json:{
    "a": "x",
    "b": "y",
    "c": "z"
}Example:import click
import clickext

def exclaim(data):
    for k, v in data.items():
        data[k] = v + "!"
    return data

@click.command(cls=clickext.ClickextCommand)
@clickext.config_option('config.json', processor=exclaim)
@click.pass_obj
def cmd(obj)
    for k, v in obj.items():
        click.echo(k + ": " + v)Output:$ cmd
a: x!
b: y!
c: z!Verbose and Verbosity OptionsTheclickext.verbose_optionprovides a simple verbosity toggle betweenlogging.DEBUGand the default log level output (logging.INFO, by default). Theclickext.verbosity_optionprovides a configurable verbosity level that can be set to any log level by passing that level name as the argument. Logging configuration adds aQUIETlevel that can be used to provide a "quiet mode" with no optional output. When either of these options is used logging will be enabled and configured automatically; it is not necessary to callclickext.init_loggingbeforehand.Example verbose switch:import logging
import click
import clickext

logger = logging.getLogger(__package__)

@click.command(cls=clickext.ClickextCommand)
@clickext.verbose_option(logger)
def cmd():
    logger.debug("a debug message")
    logger.info("an info message")Output:$ cmd
an info message
$ cmd --verbose
Debug: a debug message
an info messageExample verbosity switch:import logging
import click
import clickext

logger = logging.getLogger(__package__)

@click.command(cls=clickext.ClickextCommand)
@clickext.verbosity_option(logger)
def cmd():
    logger.info("an info message")
    logger.warning("a warning message")Output:$ cmd
an info message
Warning: a warning message
$ cmd --verbosity WARNING
Warning: a warning message
$ cmd --verbosity QUIET
$Licenseclickext is released under theMIT License