consolekit.options

Command line options.

New in version 0.4.0.

Classes:

DescribedArgument(*args[, description])

click.Argument with an additional keyword argument and attribute giving a short description.

MultiValueOption([param_decls, …])

Subclass of click.Option that behaves like argparse’s nargs='+'.

Data:

_A

Invariant TypeVar bound to click.Argument.

_C

Invariant TypeVar bound to click.Command.

Functions:

auto_default_argument(*param_decls, **attrs)

Attaches an argument to the command, with a default value determined from the decorated function’s signature.

auto_default_option(*param_decls, **attrs)

Attaches an option to the command, with a default value determined from the decorated function’s signature.

colour_option([help_text])

Adds an option (via the parameter colour: bool) to enable verbose output.

flag_option(*args[, default])

Decorator to a flag option to a click command.

force_option(help_text)

Decorator to add the -f / --force option to a click command.

no_pager_option([help_text])

Decorator to add the --no-pager option to a click command.

verbose_option([help_text])

Adds an option (via the parameter verbose: int) to enable verbose output.

version_option(callback)

Adds an option to show the version and exit.

class DescribedArgument(*args, description=None, **kwargs)[source]

Bases: Argument

click.Argument with an additional keyword argument and attribute giving a short description.

This is not shown in the help text, but may be useful for manpages or HTML documentation where additional information can be provided.

New in version 1.2.0.

Parameters

description (Optional[str]) – Default None.

See click.Argument and click.Parameter for descriptions of the other keyword argu ments.

description

Type:    Optional[str]

A short description of the argument.

class MultiValueOption(param_decls=None, show_default=False, help=None, hidden=False, type=None, required=False, default=(), callback=None, metavar=None, expose_value=True, is_eager=False)[source]

Bases: Option

Subclass of click.Option that behaves like argparse’s nargs='+'.

New in version 0.6.0.

Parameters
  • param_decls (Optional[List[str]]) – The parameter declarations for this option or argument. This is a list of flags or argument names. Default None.

  • show_default (bool) – Controls whether the default value should be shown on the help page. Normally, defaults are not shown. If this value is a string, it shows the string instead of the value. This is particularly useful for dynamic options. Default False.

  • help (Optional[str]) – The help string. Default None.

  • hidden (bool) – Hide this option from help outputs. Default False.

  • type (Union[type, ParamType, Tuple[Union[type, ParamType], …], Callable[[str], Any], Callable[[Optional[str]], Any], None]) – The type that should be used. Either a click.ParamType or a Python type. The later is converted into the former automatically if supported. Default None.

  • required (bool) – Controls whether this is optional. Default False.

  • default (Optional[Any]) – The default value if omitted. This can also be a callable, in which case it is invoked when the default is needed without any arguments. Default ().

  • callback (Optional[Callable[[Context, Parameter, str], Any]]) – A callback that should be executed after the parameter was matched. This is called as fn(ctx, param, value) and needs to return the value. Default None.

  • metavar (Optional[str]) – How the value is represented in the help page. Default None.

  • expose_value (bool) – If True then the value is passed onwards to the command callback and stored on the context, otherwise it is skipped. Default True.

  • is_eager (bool) – Eager values are processed before non eager ones. Default False.

Example usage:

@click.option(
        "--select",
        type=click.STRING,
        help="The checks to enable",
        cls=MultiValueOption,
        )
@click_command()
def main(select: Iterable[str]):
    select = list(select)

Methods:

add_to_parser(parser, ctx)

Add the MultiValueOption to the given parser.

process_value(ctx, value)

Given a value and context, converts the value as necessary.

add_to_parser(parser, ctx)[source]

Add the MultiValueOption to the given parser.

Parameters
Return type

Any

process_value(ctx, value)[source]

Given a value and context, converts the value as necessary.

Parameters
Return type

Optional[Tuple]

_A = TypeVar(_A, bound=Argument)

Type:    TypeVar

Invariant TypeVar bound to click.Argument.

_C = TypeVar(_C, bound=Command)

Type:    TypeVar

Invariant TypeVar bound to click.Command.

auto_default_argument(*param_decls, **attrs)[source]

Attaches an argument to the command, with a default value determined from the decorated function’s signature.

All positional arguments are passed as parameter declarations to click.Argument; all keyword arguments are forwarded unchanged (except cls). This is equivalent to creating an click.Argument instance manually and attaching it to the click.Command.params list.

New in version 0.8.0.

Parameters

cls – the option class to instantiate. This defaults to click.Argument.

Return type

Callable[[~_C], ~_C]

auto_default_option(*param_decls, **attrs)[source]

Attaches an option to the command, with a default value determined from the decorated function’s signature.

All positional arguments are passed as parameter declarations to click.Option; all keyword arguments are forwarded unchanged (except cls). This is equivalent to creating an click.Option instance manually and attaching it to the click.Command.params list.

New in version 0.7.0.

Parameters

cls – the option class to instantiate. This defaults to click.Option.

Return type

Callable[[~_C], ~_C]

colour_option(help_text='Whether to use coloured output.')[source]

Adds an option (via the parameter colour: bool) to enable verbose output.

New in version 0.4.0.

Parameters

help_text (str) – The help text for the option. Default 'Whether to use coloured output.'.

Return type

Callable[[~_C], ~_C]

flag_option(*args, default=False, **kwargs)[source]

Decorator to a flag option to a click command.

New in version 0.7.0.

Parameters
Return type

Callable[[~_C], ~_C]

force_option(help_text)[source]

Decorator to add the -f / --force option to a click command.

The value is exposed via the parameter force: bool.

New in version 0.5.0.

Parameters

help_text (str) – The help text for the option.

Return type

Callable[[~_C], ~_C]

no_pager_option(help_text='Disable the output pager.')[source]

Decorator to add the --no-pager option to a click command.

The value is exposed via the parameter no_pager: bool.

New in version 0.5.0.

Parameters

help_text (str) – The help text for the option. Default 'Disable the output pager.'.

Return type

Callable[[~_C], ~_C]

verbose_option(help_text='Show verbose output.')[source]

Adds an option (via the parameter verbose: int) to enable verbose output.

The option can be provided multiple times by the user.

New in version 0.4.0.

Parameters

help_text (str) – The help text for the option. Default 'Show verbose output.'.

Return type

Callable[[~_C], ~_C]

version_option(callback)[source]

Adds an option to show the version and exit.

The option can be provided multiple times by the user. The count is stored as an integer and passed as the third parameter to the callback function.

New in version 0.4.0.

Parameters

callback (Callable[[Context, Option, int], Any]) – The callback to invoke when the option is provided.

The callback function might look like:

def version_callback(ctx: click.Context, param: click.Option, value: int):
    if not value or ctx.resilient_parsing:
        return

    if value > 1:
        click.echo(f"consolekit version {__version__}, Python {sys.version}")
    else:
        click.echo(f"consolekit version {__version__}")

    ctx.exit()
Return type

Callable[[~_C], ~_C]