click.core.Parameter

class documentation

class Parameter:

Known subclasses: click.core.Argument, click.core.Option

A parameter to a command comes in two versions: they are either Options or Arguments. Other subclasses are currently not supported by design as some of the internals for parsing are intentionally not finalized.

Some settings are supported by both options and arguments.

Changed in version 8.0: process_value validates required parameters and bounded nargs, and invokes the parameter callback before returning the value. This allows the callback to validate prompts. full_process_value is removed.

Changed in version 8.0: autocompletion is renamed to shell_complete and has new semantics described above. The old name is deprecated and will be removed in 8.1, until then it will be wrapped to match the new requirements.

Changed in version 8.0: For multiple=True, nargs>1, the default must be a list of tuples.

Changed in version 8.0: Setting a default is no longer required for nargs>1, it will default to None. multiple=True or nargs=-1 will default to ().

Changed in version 7.1: Empty environment variables are ignored rather than taking the empty string value. This makes it possible for scripts to clear variables if they can't unset them.

Changed in version 2.0: Changed signature for parameter callback to also be passed the parameter. The old callback format will still work, but it will raise a warning to give you a chance to migrate the code easier.

Parameters
param_decls	the parameter declarations for this option or argument. This is a list of flags or argument names.
type	the type that should be used. Either a `ParamType` or a Python type. The later is converted into the former automatically if supported.
required	controls if this is optional or not.
default	the default value if omitted. This can also be a callable, in which case it's invoked when the default is needed without any arguments.
callback	A function to further process or validate the value after type conversion. It is called as `f(ctx, param, value)` and must return the value. It is called for all sources, including prompts.
nargs	the number of arguments to match. If not `1` the return value is a tuple instead of single value. The default for nargs is `1` (except if the type is a tuple, then it's the arity of the tuple). If `nargs=-1`, all remaining parameters are collected.
metavar	how the value is represented in the help page.
expose_value	if this is `True` then the value is passed onwards to the command callback and stored on the context, otherwise it's skipped.
is_eager	eager values are processed before non eager ones. This should not be set for arguments or it will inverse the order of processing.
envvar	a string or list of strings that are environment variables that should be checked.
shell_complete	A function that returns custom shell completions. Used instead of the param's type completion if given. Takes `ctx, param, incomplete` and must return a list of `~click.shell_completion.CompletionItem` or a list of strings.

Method	`__init__`	Undocumented
Method	`__repr__`	Undocumented
Method	`_parse_decls`	Undocumented
Method	`add_to_parser`	Undocumented
Method	`consume_value`	Undocumented
Method	`get_default`	Get the default for the parameter. Tries `Context.lookup_default` first, then the local default.
Method	`get_error_hint`	Get a stringified version of the param for use in error messages to indicate which param caused the error.
Method	`get_help_record`	Undocumented
Method	`get_usage_pieces`	Undocumented
Method	`handle_parse_result`	Undocumented
Method	`make_metavar`	Undocumented
Method	`process_value`	Undocumented
Method	`resolve_envvar_value`	Undocumented
Method	`shell_complete`	No summary
Method	`to_info_dict`	Gather information that could be useful for a tool generating user-facing documentation.
Method	`type_cast_value`	Convert and validate a value against the option's `type`, `multiple`, and `nargs`.
Method	`value_from_envvar`	Undocumented
Method	`value_is_missing`	Undocumented
Class Variable	`param_type_name`	Undocumented
Instance Variable	`_custom_shell_complete`	Undocumented
Instance Variable	`callback`	Undocumented
Instance Variable	`default`	Undocumented
Instance Variable	`envvar`	Undocumented
Instance Variable	`expose_value`	Undocumented
Instance Variable	`is_eager`	Undocumented
Instance Variable	`metavar`	Undocumented
Instance Variable	`multiple`	Undocumented
Instance Variable	`name`	Undocumented
Instance Variable	`nargs`	Undocumented
Instance Variable	`opts`	Undocumented
Instance Variable	`required`	Undocumented
Instance Variable	`secondary_opts`	Undocumented
Instance Variable	`type`	Undocumented
Property	`human_readable_name`	Returns the human readable name of this parameter. This is the same as the name for options, but the metavar for arguments.

def __init__(self, param_decls=None, type=None, required=False, default=None, callback=None, nargs=None, multiple=False, metavar=None, expose_value=True, is_eager=False, envvar=None, shell_complete=None, autocompletion=None):

overridden in click.core.Argument, click.core.Option

Undocumented

Parameters
param_decls:`t.Optional[t.Sequence[str]]`	Undocumented
type:`t.Optional[t.Union[types.ParamType, t.Any]]`	Undocumented
required:`bool`	Undocumented
default:`t.Optional[t.Union[t.Any, t.Callable[[], t.Any]]]`	Undocumented
callback:`t.Optional[t.Callable[[Context, Parameter, t.Any], t.Any]]`	Undocumented
nargs:`t.Optional[int]`	Undocumented
multiple:`bool`	Undocumented
metavar:`t.Optional[str]`	Undocumented
expose_value:`bool`	Undocumented
is_eager:`bool`	Undocumented
envvar:`t.Optional[t.Union[str, t.Sequence[str]]]`	Undocumented
shell_complete:`t.Optional[t.Callable[[Context, Parameter, str], t.Union[t.List[CompletionItem], t.List[str]]]]`	Undocumented
autocompletion:`t.Optional[t.Callable[[Context, t.List[str], str], t.List[t.Union[t.Tuple[str, str], str]]]]`	Undocumented

def __repr__(self):

Undocumented

Returns
`str`	Undocumented

def _parse_decls(self, decls, expose_value):

overridden in click.core.Argument, click.core.Option

Undocumented

Parameters
decls:`t.Sequence[str]`	Undocumented
expose_value:`bool`	Undocumented
Returns
`t.Tuple[t.Optional[str], t.List[str], t.List[str]]`	Undocumented

def add_to_parser(self, parser, ctx):

overridden in click.core.Argument, click.core.Option

Undocumented

Parameters
parser:`OptionParser`	Undocumented
ctx:`Context`	Undocumented

def consume_value(self, ctx, opts):

overridden in click.core.Option

Undocumented

Parameters
ctx:`Context`	Undocumented
opts:`t.Mapping[str, t.Any]`	Undocumented
Returns
`t.Tuple[t.Any, ParameterSource]`	Undocumented

def get_default(self, ctx, call=True):

overridden in click.core.Option

Get the default for the parameter. Tries Context.lookup_default first, then the local default.

Changed in version 8.0.2: Type casting is no longer performed when getting a default.

Changed in version 8.0.1: Type casting can fail in resilient parsing mode. Invalid defaults will not prevent showing help text.

Changed in version 8.0: Looks at ctx.default_map first.

Changed in version 8.0: Added the call parameter.

Parameters
ctx:`Context`	Current context.
call:`bool`	If the default is a callable, call it. Disable to return the callable instead.
Returns
`t.Optional[t.Union[t.Any, t.Callable[[], t.Any]]]`	Undocumented

def get_error_hint(self, ctx):

overridden in click.core.Argument

Get a stringified version of the param for use in error messages to indicate which param caused the error.

Parameters
ctx:`Context`	Undocumented
Returns
`str`	Undocumented

def get_help_record(self, ctx):

overridden in click.core.Option

Undocumented

Parameters
ctx:`Context`	Undocumented
Returns
`t.Optional[t.Tuple[str, str]]`	Undocumented

def get_usage_pieces(self, ctx):

overridden in click.core.Argument

Undocumented

Parameters
ctx:`Context`	Undocumented
Returns
`t.List[str]`	Undocumented

def handle_parse_result(self, ctx, opts, args):

Undocumented

Parameters
ctx:`Context`	Undocumented
opts:`t.Mapping[str, t.Any]`	Undocumented
args:`t.List[str]`	Undocumented
Returns
`t.Tuple[t.Any, t.List[str]]`	Undocumented

def make_metavar(self):

overridden in click.core.Argument

Undocumented

Returns
`str`	Undocumented

def process_value(self, ctx, value):

Undocumented

Parameters
ctx:`Context`	Undocumented
value:`t.Any`	Undocumented
Returns
`t.Any`	Undocumented

def resolve_envvar_value(self, ctx):

overridden in click.core.Option

Undocumented

Parameters
ctx:`Context`	Undocumented
Returns
`t.Optional[str]`	Undocumented

def shell_complete(self, ctx, incomplete):

Return a list of completions for the incomplete value. If a shell_complete function was given during init, it is used. Otherwise, the type ~click.types.ParamType.shell_complete function is used.

New in version 8.0.

Parameters
ctx:`Context`	Invocation context for this command.
incomplete:`str`	Value being completed. May be empty.
Returns
`t.List[CompletionItem]`	Undocumented

def to_info_dict(self):

overridden in click.core.Option

Gather information that could be useful for a tool generating user-facing documentation.

Use click.Context.to_info_dict to traverse the entire CLI structure.

New in version 8.0.

Returns
`t.Dict[str, t.Any]`	Undocumented

def type_cast_value(self, ctx, value):

Convert and validate a value against the option's type, multiple, and nargs.

Parameters
ctx:`Context`	Undocumented
value:`t.Any`	Undocumented
Returns
`t.Any`	Undocumented

def value_from_envvar(self, ctx):

overridden in click.core.Option

Undocumented

Parameters
ctx:`Context`	Undocumented
Returns
`t.Optional[t.Any]`	Undocumented

def value_is_missing(self, value):

Undocumented

Parameters
value:`t.Any`	Undocumented
Returns
`bool`	Undocumented

param_type_name: str =

overridden in click.core.Argument, click.core.Option

Undocumented

_custom_shell_complete =

Undocumented

callback =

Undocumented

default =

overridden in click.core.Option

Undocumented

envvar =

Undocumented

expose_value =

Undocumented

is_eager =

Undocumented

metavar =

Undocumented

multiple =

Undocumented

name =

Undocumented

nargs =

Undocumented

opts =

Undocumented

required =

Undocumented

secondary_opts =

Undocumented

type =

overridden in click.core.Option

Undocumented

@property
human_readable_name: str =

overridden in click.core.Argument

Returns the human readable name of this parameter. This is the same as the name for options, but the metavar for arguments.