click.decorators

module documentation

Undocumented

Function pass​_meta​_key Create a decorator that passes a key from click.Context.meta as the first argument to the decorated function.
Constant F Undocumented
Constant FC Undocumented
Function ​_make​_command Undocumented
Function ​_param​_memo Undocumented
Function argument No summary
Function command Creates a new Command and uses the decorated function as callback. This will also automatically attach all decorated options and arguments as parameters to the command.
Function confirmation​_option Add a --yes option which shows a prompt before continuing if not passed. If the prompt is declined, the program will exit.
Function group Creates a new Group with a function as callback. This works otherwise the same as command just that the cls parameter is set to Group.
Function help​_option Add a --help option which immediately prints the help page and exits the program.
Function make​_pass​_decorator No summary
Function option No summary
Function pass​_context Marks a callback as wanting to receive the current context object as first argument.
Function pass​_obj Similar to pass_context, but only pass the object on the context onwards (Context.obj). This is useful if that object represents the state of a nested system.
Function password​_option Add a --password option which prompts for a password, hiding input and asking to enter the value again for confirmation.
Function version​_option Add a --version option which immediately prints the version number and exits the program.
def pass_meta_key(key, *, doc_description=None):

Create a decorator that passes a key from click.Context.meta as the first argument to the decorated function.

New in version 8.0.
Parameters
key:strKey in Context.meta to pass.
doc​_description:t.Optional[str]Description of the object being passed, inserted into the decorator's docstring. Defaults to "the 'key' key from Context.meta".
Returns
t.Callable[[F], F]Undocumented
F =

Undocumented

Value
t.TypeVar('F',
          bound=t.Callable[..., t.Any])
FC =

Undocumented

Value
t.TypeVar('FC', t.Callable[..., t.Any], Command)
def _make_command(f, name, attrs, cls):

Undocumented

Parameters
f:FUndocumented
name:t.Optional[str]Undocumented
attrs:t.MutableMapping[str, t.Any]Undocumented
cls:t.Type[Command]Undocumented
Returns
CommandUndocumented
def _param_memo(f, param):

Undocumented

Parameters
f:FCUndocumented
param:ParameterUndocumented
def argument(*param_decls, **attrs):
Attaches an argument to the command. All positional arguments are passed as parameter declarations to Argument; all keyword arguments are forwarded unchanged (except cls). This is equivalent to creating an Argument instance manually and attaching it to the Command.params list.
Parameters
*param​_decls:strUndocumented
**attrs:t.AnyUndocumented
clsthe argument class to instantiate. This defaults to Argument.
Returns
t.Callable[[FC], FC]Undocumented
def command(name=None, cls=None, **attrs):

Creates a new Command and uses the decorated function as callback. This will also automatically attach all decorated options and arguments as parameters to the command.

The name of the command defaults to the name of the function with underscores replaced by dashes. If you want to change that, you can pass the intended name as the first argument.

All keyword arguments are forwarded to the underlying command class.

Once decorated the function turns into a Command instance that can be invoked as a command line utility or be attached to a command Group.

Parameters
name:t.Optional[str]the name of the command. This defaults to the function name with underscores replaced by dashes.
cls:t.Optional[t.Type[Command]]the command class to instantiate. This defaults to Command.
**attrs:t.AnyUndocumented
Returns
t.Callable[[F], Command]Undocumented
def confirmation_option(*param_decls, **kwargs):
Add a --yes option which shows a prompt before continuing if not passed. If the prompt is declined, the program will exit.
Parameters
*param​_decls:strOne or more option names. Defaults to the single value "--yes".
**kwargs:t.AnyExtra arguments are passed to option.
Returns
t.Callable[[FC], FC]Undocumented
def group(name=None, **attrs):
Creates a new Group with a function as callback. This works otherwise the same as command just that the cls parameter is set to Group.
Parameters
name:t.Optional[str]Undocumented
**attrs:t.AnyUndocumented
Returns
t.Callable[[F], Group]Undocumented
def help_option(*param_decls, **kwargs):

Add a --help option which immediately prints the help page and exits the program.

This is usually unnecessary, as the --help option is added to each command automatically unless add_help_option=False is passed.

Parameters
*param​_decls:strOne or more option names. Defaults to the single value "--help".
**kwargs:t.AnyExtra arguments are passed to option.
Returns
t.Callable[[FC], FC]Undocumented
def make_pass_decorator(object_type, ensure=False):

Given an object type this creates a decorator that will work similar to pass_obj but instead of passing the object of the current context, it will find the innermost context of type object_type.

This generates a decorator that works roughly like this:

from functools import update_wrapper

def decorator(f):
    @pass_context
    def new_func(ctx, *args, **kwargs):
        obj = ctx.find_object(object_type)
        return ctx.invoke(f, obj, *args, **kwargs)
    return update_wrapper(new_func, f)
return decorator
Parameters
object​_type:t.Typethe type of the object to pass.
ensure:boolif set to True, a new object will be created and remembered on the context if it's not there yet.
Returns
t.Callable[[F], F]Undocumented
def option(*param_decls, **attrs):
Attaches an option to the command. All positional arguments are passed as parameter declarations to Option; all keyword arguments are forwarded unchanged (except cls). This is equivalent to creating an Option instance manually and attaching it to the Command.params list.
Parameters
*param​_decls:strUndocumented
**attrs:t.AnyUndocumented
clsthe option class to instantiate. This defaults to Option.
Returns
t.Callable[[FC], FC]Undocumented
def pass_context(f):
Marks a callback as wanting to receive the current context object as first argument.
Parameters
f:FUndocumented
Returns
FUndocumented
def pass_obj(f):
Similar to pass_context, but only pass the object on the context onwards (Context.obj). This is useful if that object represents the state of a nested system.
Parameters
f:FUndocumented
Returns
FUndocumented
def password_option(*param_decls, **kwargs):
Add a --password option which prompts for a password, hiding input and asking to enter the value again for confirmation.
Parameters
*param​_decls:strOne or more option names. Defaults to the single value "--password".
**kwargs:t.AnyExtra arguments are passed to option.
Returns
t.Callable[[FC], FC]Undocumented
def version_option(version=None, *param_decls, package_name=None, prog_name=None, message=None, **kwargs):

Add a --version option which immediately prints the version number and exits the program.

If version is not provided, Click will try to detect it using importlib.metadata.version to get the version for the package_name. On Python < 3.8, the importlib_metadata backport must be installed.

If package_name is not provided, Click will try to detect it by inspecting the stack frames. This will be used to detect the version, so it must match the name of the installed package.

Changed in version 8.0: Add the package_name parameter, and the %(package)s value for messages.
Changed in version 8.0: Use importlib.metadata instead of pkg_resources. The version is detected based on the package name, not the entry point name. The Python package name must match the installed package name, or be passed with package_name=.
Parameters
version:t.Optional[str]The version number to show. If not provided, Click will try to detect it.
*param​_decls:strOne or more option names. Defaults to the single value "--version".
package​_name:t.Optional[str]The package name to detect the version from. If not provided, Click will try to detect it.
prog​_name:t.Optional[str]The name of the CLI to show in the message. If not provided, it will be detected from the command.
message:t.Optional[str]The message to show. The values %(prog)s, %(package)s, and %(version)s are available. Defaults to "%(prog)s, version %(version)s".
**kwargs:t.AnyExtra arguments are passed to option.
Returns
t.Callable[[FC], FC]Undocumented
Raises
RuntimeErrorversion could not be detected.