`consolekit.options`

Command line options.

New in version 0.4.0.

Classes:

`ChoiceOption`(param_decls, type[, …])	`click.Option` subclass for a string choice.
`DescribedArgument`(*args[, description])	`click.Argument` with an additional keyword argument and attribute giving a short description.
`LazyChoice`(getter[, case_sensitive])	Modified choice type that lazily loads the data.
`MultiValueOption`([param_decls, …])	Subclass of `click.Option` that behaves like argparse’s `nargs='+'`.
`PromptOption`([param_decls, show_default, …])	`click.Option` subclass that prompts for a value if none is provided on the command line.
`VerboseVersionCountType`()	Subclass of `click.IntRange` which doesn’t show the range of valid values.

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 ChoiceOption(param_decls, type, show_default=None, prompt='', help=None, hidden=False, show_choices=True, **kwargs)[source]

Bases: Option

click.Option subclass for a string choice.

If a value is not provided a prompt (where the user chooses the corresponding number) is shown.

Parameters

param_decls (Sequence[str]) – The parameter declarations for this option.
type (Choice) – The type that should be used.
show_default (Union[bool, str, None]) – Show the default value for this option in its help text. Values are not shown by default, unless Context.show_default is True. If this value is a string, it shows that string in parentheses instead of the actual value. This is particularly useful for dynamic options. For single option boolean flags, the default remains hidden if its value is False. Default None.
prompt (str) – The prompt text. Defaults to the option name (capitalised and with spaces) if unset. Default ''.
help (Optional[str]) – The help text. Default None.
hidden (bool) – Hide this option from help outputs. Default False.
show_choices (bool) – Default True.
deprecated – If True or a non-empty string, issues a message indicating that the argument is deprecated and highlights its deprecation in –help. The message can be customized by using a string as the value. A deprecated parameter cannot be required, a ValueError will be raised otherwise.

New in version 1.11.0.

Methods:

prompt_for_value(ctx)

Show the prompt if a value was not provided.

prompt_for_value(ctx)[source]

Show the prompt if a value was not provided.

Parameters: ctx (Context)
Return type: str

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 LazyChoice(getter, case_sensitive=True)[source]

Bases: Choice

Modified choice type that lazily loads the data.

Useful for expensive operations that need not happen if the option is not provided or the help text is not being displayed.

Parameters

getter (Callable[[], Iterable[str]]) – Function that returns the actual choices.
case_sensitive (bool) – Set to False to make choices case insensitive. Default True.

New in version 1.11.0.

Attributes:

choices

The choices, obtained from the getter function and cached.

property choices

The choices, obtained from the getter function and cached.

Return type: Sequence[str]

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

parser (OptionParser)
ctx (Context)

Return type

Any

process_value(ctx, value)[source]

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

Parameters

ctx (Context)
value (Any)

Return type

Optional[Tuple]

class PromptOption(param_decls=None, show_default=None, prompt=False, confirmation_prompt=False, prompt_required=True, hide_input=False, is_flag=None, flag_value=None, multiple=False, count=False, allow_from_autoenv=True, type=None, help=None, hidden=False, show_choices=True, show_envvar=False, **attrs)[source]

Bases: Option

click.Option subclass that prompts for a value if none is provided on the command line.

Supports boolean, string or numeric values.

New in version 1.11.0.

Methods:

prompt_for_value(ctx)

Prompt the user until a valid value exists and then returns the processed value as result.

prompt_for_value(ctx)[source]

Prompt the user until a valid value exists and then returns the processed value as result.

Parameters: ctx (Context)

class VerboseVersionCountType[source]

Bases: IntRange

Subclass of click.IntRange which doesn’t show the range of valid values.

New in version 0.8.1.

_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

*args – Positional arguments passed to click.option().
default (Optional[bool]) – The default state of the flag. Default False.
**kwargs – Keyword arguments passed to click.option().

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]

consolekit.options

`consolekit.options`