click API Reference
Full documentation for click (8.4.2)
click.Abort
Python Library Documentation: class Abort in module click.exceptions class Abort(builtins.RuntimeError) | An internal signalling exception that signals Click to abort. | | Method resolution order: | Abort | builtins.RuntimeError | builtins.Exception | builtins.BaseException | builtins.object | | Data descriptors defined here: | | __weakref__ | list of weak references to the object | | ---------------------------------------------------------------------- | Methods inherited from builtins.RuntimeError: | | __init__(self, /, *args, **kwargs) | Initialize self. See help(type(self)) for accurate signature. | | ---------------------------------------------------------------------- | Static methods inherited from builtins.RuntimeError: | | __new__(*args, **kwargs) class method of builtins.RuntimeError | Create and return a new object. See help(type) for accurate signature. | | ---------------------------------------------------------------------- | Methods inherited from builtins.BaseException: | | __getattribute__(self, name, /) | Return getattr(self, name). | | __reduce__(...) | Helper for pickle. | | __repr__(self, /) | Return repr(self). | | __setstate__(...) | | __str__(self, /) | Return str(self). | | add_note(...) | Exception.add_note(note) -- | add a note to the exception | | with_traceback(...) | Exception.with_traceback(tb) -- | set self.__traceback__ to tb and return self. | | ---------------------------------------------------------------------- | Data descriptors inherited from builtins.BaseException: | | __cause__ | exception cause | | __context__ | exception context | | __dict__ | | __suppress_context__ | | __traceback__ | | args
click.Argument
Python Library Documentation: class Argument in module click.core
class Argument(Parameter)
| Argument(param_decls: 'cabc.Sequence[str]', required: 'bool | None' = None, **attrs: 't.Any') -> 'None'
|
| Arguments are positional parameters to a command. They generally
| provide fewer features than options but can have infinite ``nargs``
| and are required by default.
|
| All parameters are passed onwards to the constructor of :class:`Parameter`.
|
| Method resolution order:
| Argument
| Parameter
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, param_decls: 'cabc.Sequence[str]', required: 'bool | None' = None, **attrs: 't.Any') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| add_to_parser(self, parser: '_OptionParser', ctx: 'Context') -> 'None'
|
| get_error_hint(self, ctx: 'Context | None') -> 'str'
| Get a stringified version of the param for use in error messages to
| indicate which param caused the error.
|
| .. versionchanged:: 8.4.0
| ``ctx`` can be ``None``.
|
| get_usage_pieces(self, ctx: 'Context') -> 'list[str]'
|
| make_metavar(self, ctx: 'Context') -> 'str'
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| 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.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| param_type_name = 'argument'
|
| ----------------------------------------------------------------------
| Methods inherited from Parameter:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| consume_value(self, ctx: 'Context', opts: 'cabc.Mapping[str, t.Any]') -> 'tuple[t.Any, ParameterSource]'
| Returns the parameter value produced by the parser.
|
| If the parser did not produce a value from user input, the value is either
| sourced from the environment variable, the default map, or the parameter's
| default value. In that order of precedence.
|
| If no value is found, an internal sentinel value is returned.
|
| :meta private:
|
| get_default(self, ctx: 'Context', call: 'bool' = True) -> 't.Any | t.Callable[[], t.Any] | None'
| Get the default for the parameter. Tries
| :meth:`Context.lookup_default` first, then the local default.
|
| :param ctx: Current context.
| :param call: If the default is a callable, call it. Disable to
| return the callable instead.
|
| .. versionchanged:: 8.0.2
| Type casting is no longer performed when getting a default.
|
| .. versionchanged:: 8.0.1
| Type casting can fail in resilient parsing mode. Invalid
| defaults will not prevent showing help text.
|
| .. versionchanged:: 8.0
| Looks at ``ctx.default_map`` first.
|
| .. versionchanged:: 8.0
| Added the ``call`` parameter.
|
| get_help_record(self, ctx: 'Context') -> 'tuple[str, str] | None'
|
| handle_parse_result(self, ctx: 'Context', opts: 'cabc.Mapping[str, t.Any]', args: 'list[str]') -> 'tuple[t.Any, list[str]]'
| Process the value produced by the parser from user input.
|
| Always process the value through the Parameter's :attr:`type`, wherever it
| comes from.
|
| If the parameter is deprecated, this method warn the user about it. But only if
| the value has been explicitly set by the user (and as such, is not coming from
| a default).
|
| :meta private:
|
| process_value(self, ctx: 'Context', value: 't.Any') -> 't.Any'
| Process the value of this parameter:
|
| 1. Type cast the value using :meth:`type_cast_value`.
| 2. Check if the value is missing (see: :meth:`value_is_missing`), and raise
| :exc:`MissingParameter` if it is required.
| 3. If a :attr:`callback` is set, call it to have the value replaced by the
| result of the callback. If the value was not set, the callback receive
| ``None``. This keep the legacy behavior as it was before the introduction of
| the :attr:`UNSET` sentinel.
|
| :meta private:
|
| resolve_envvar_value(self, ctx: 'Context') -> 'str | None'
| Returns the value found in the environment variable(s) attached to this
| parameter.
|
| Environment variables values are `always returned as strings
| <https://docs.python.org/3/library/os.html#os.environ>`_.
|
| This method returns ``None`` if:
|
| - the :attr:`envvar` property is not set on the :class:`Parameter`,
| - the environment variable is not found in the environment,
| - the variable is found in the environment but its value is empty (i.e. the
| environment variable is present but has an empty string).
|
| If :attr:`envvar` is setup with multiple environment variables,
| then only the first non-empty value is returned.
|
| .. caution::
|
| The raw value extracted from the environment is not normalized and is
| returned as-is. Any normalization or reconciliation is performed later by
| the :class:`Parameter`'s :attr:`type`.
|
| :meta private:
|
| shell_complete(self, ctx: 'Context', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of completions for the incomplete value. If a
| ``shell_complete`` function was given during init, it is used.
| Otherwise, the :attr:`type`
| :meth:`~click.types.ParamType[t.Any].shell_complete` function is used.
|
| :param ctx: Invocation context for this command.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self) -> 'dict[str, t.Any]'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionchanged:: 8.3.0
| Returns ``None`` for the :attr:`default` if it was not set.
|
| .. versionadded:: 8.0
|
| type_cast_value(self, ctx: 'Context', value: 't.Any') -> 't.Any'
| Convert and validate a value against the parameter's
| :attr:`type`, :attr:`multiple`, and :attr:`nargs`.
|
| value_from_envvar(self, ctx: 'Context') -> 'str | cabc.Sequence[str] | None'
| Process the raw environment variable string for this parameter.
|
| Returns the string as-is or splits it into a sequence of strings if the
| parameter is expecting multiple values (i.e. its :attr:`nargs` property is set
| to a value other than ``1``).
|
| :meta private:
|
| value_is_missing(self, value: 't.Any') -> 'bool'
| A value is considered missing if:
|
| - it is :attr:`UNSET`,
| - or if it is an empty sequence while the parameter is suppose to have
| non-single value (i.e. :attr:`nargs` is not ``1`` or :attr:`multiple` is
| set).
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Parameter:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
click.BOOL
Python Library Documentation: BoolParamType in module click.types object
class BoolParamType(ParamType)
| Method resolution order:
| BoolParamType
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: 't.Any', param: 'Parameter | None', ctx: 'Context | None') -> 'bool'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| str_to_bool(value: 'str | bool') -> 'bool | None'
| Convert a string to a boolean value.
|
| If the value is already a boolean, it is returned as-is. If the value is a
| string, it is stripped of whitespaces and lower-cased, then checked against
| the known boolean states pre-defined in the `BoolParamType.bool_states` mapping
| above.
|
| Returns `None` if the value does not match any known boolean state.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'bool_states': 'dict[str, bool]'}
|
| __orig_bases__ = (click.types.ParamType[bool],)
|
| __parameters__ = ()
|
| bool_states = {'': False, '0': False, '1': True, 'f': False, 'false': ...
|
| name = 'boolean'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.BadArgumentUsage
Python Library Documentation: class BadArgumentUsage in module click.exceptions
class BadArgumentUsage(UsageError)
| BadArgumentUsage(message: 'str', ctx: 'Context | None' = None) -> 'None'
|
| Raised if an argument is generally supplied but the use of the argument
| was incorrect. This is for instance raised if the number of values
| for an argument is not correct.
|
| .. versionadded:: 6.0
|
| Method resolution order:
| BadArgumentUsage
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from UsageError:
|
| __init__(self, message: 'str', ctx: 'Context | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UsageError:
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
click.BadOptionUsage
Python Library Documentation: class BadOptionUsage in module click.exceptions
class BadOptionUsage(UsageError)
| BadOptionUsage(option_name: 'str', message: 'str', ctx: 'Context | None' = None) -> 'None'
|
| Raised if an option is generally supplied but the use of the option
| was incorrect. This is for instance raised if the number of arguments
| for an option is not correct.
|
| .. versionadded:: 4.0
|
| :param option_name: the name of the option being used incorrectly.
|
| Method resolution order:
| BadOptionUsage
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, option_name: 'str', message: 'str', ctx: 'Context | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'option_name': 't.Final[str]'}
|
| ----------------------------------------------------------------------
| Methods inherited from UsageError:
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UsageError:
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
click.BadParameter
Python Library Documentation: class BadParameter in module click.exceptions
class BadParameter(UsageError)
| BadParameter(message: 'str', ctx: 'Context | None' = None, param: 'Parameter | None' = None, param_hint: 'cabc.Sequence[str] | str | None' = None) -> 'None'
|
| An exception that formats out a standardized error message for a
| bad parameter. This is useful when thrown from a callback or type as
| Click will attach contextual information to it (for instance, which
| parameter it is).
|
| .. versionadded:: 2.0
|
| :param param: the parameter object that caused this error. This can
| be left out, and Click will attach this info itself
| if possible.
| :param param_hint: a string that shows up as parameter name. This
| can be used as alternative to `param` in cases
| where custom validation should happen. If it is
| a string it's used as such, if it's a list then
| each item is quoted and separated.
|
| Method resolution order:
| BadParameter
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, message: 'str', ctx: 'Context | None' = None, param: 'Parameter | None' = None, param_hint: 'cabc.Sequence[str] | str | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'param': 'Parameter | None', 'param_hint': 'cabc.Se...
|
| ----------------------------------------------------------------------
| Methods inherited from UsageError:
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UsageError:
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
click.Choice
Python Library Documentation: class Choice in module click.types
class Choice(ParamType, typing.Generic)
| Choice(choices: 'cabc.Iterable[_ValueT_co]', case_sensitive: 'bool' = True) -> 'None'
|
| The choice type allows a value to be checked against a fixed set
| of supported values.
|
| You may pass any iterable value which will be converted to a tuple
| and thus will only be iterated once.
|
| The resulting value will always be one of the originally passed choices.
| See :meth:`normalize_choice` for more info on the mapping of strings
| to choices. See :ref:`choice-opts` for an example.
|
| :param case_sensitive: Set to false to make choices case
| insensitive. Defaults to true.
|
| .. versionchanged:: 8.4.0
| Now generic in the choice value type. Parameterize with the type of
| the choice values (``Choice[HashType]`` for an enum, ``Choice[str]``
| for plain strings) to enable type-checked consumers.
|
| .. versionchanged:: 8.2.0
| Non-``str`` ``choices`` are now supported. It can additionally be any
| iterable. Before you were not recommended to pass anything but a list or
| tuple.
|
| .. versionadded:: 8.2.0
| Choice normalization can be overridden via :meth:`normalize_choice`.
|
| Method resolution order:
| Choice
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, choices: 'cabc.Iterable[_ValueT_co]', case_sensitive: 'bool' = True) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: 't.Any', param: 'Parameter | None', ctx: 'Context | None') -> '_ValueT_co'
| For a given value from the parser, normalize it and find its
| matching normalized value in the list of choices. Then return the
| matched "original" choice.
|
| get_invalid_choice_message(self, value: 't.Any', ctx: 'Context | None') -> 'str'
| Get the error message when the given choice is invalid.
|
| :param value: The invalid value.
|
| .. versionadded:: 8.2
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str'
| Message shown when no choice is passed.
|
| .. versionchanged:: 8.2.0 Added ``ctx`` argument.
|
| normalize_choice(self, choice: 'object', ctx: 'Context | None') -> 'str'
| Normalize a choice value, used to map a passed string to a choice.
| Each choice must have a unique normalized value.
|
| By default uses :meth:`Context.token_normalize_func` and if not case
| sensitive, convert it to a casefolded value.
|
| .. versionadded:: 8.2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Complete choices that start with the incomplete value.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self) -> 'ChoiceInfoDict[_ValueT_co]'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'case_sensitive': 'bool', 'choices': 'tuple[_ValueT...
|
| __orig_bases__ = (click.types.ParamType[+_ValueT_co], typing.Generic[+...
|
| __parameters__ = (+_ValueT_co,)
|
| name = 'choice'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.ClickException
Python Library Documentation: class ClickException in module click.exceptions
class ClickException(builtins.Exception)
| ClickException(message: 'str') -> 'None'
|
| An exception that Click can handle and show to the user.
|
| Method resolution order:
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, message: 'str') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __str__(self) -> 'str'
| Return str(self).
|
| format_message(self) -> 'str'
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'exit_code': 't.ClassVar[int]', 'message': 't.Final...
|
| exit_code = 1
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
click.Command
Python Library Documentation: class Command in module click.core
class Command(builtins.object)
| Command(name: 'str | None', context_settings: 'cabc.MutableMapping[str, t.Any] | None' = None, callback: 't.Callable[..., t.Any] | None' = None, params: 'list[Parameter] | None' = None, help: 'str | None' = None, epilog: 'str | None' = None, short_help: 'str | None' = None, options_metavar: 'str | None' = '[OPTIONS]', add_help_option: 'bool' = True, no_args_is_help: 'bool' = False, hidden: 'bool' = False, deprecated: 'bool | str' = False) -> 'None'
|
| Commands are the basic building block of command line interfaces in
| Click. A basic command handles command line parsing and might dispatch
| more parsing to commands nested below it.
|
| :param name: the name of the command to use unless a group overrides it.
| :param context_settings: an optional dictionary with defaults that are
| passed to the context object.
| :param callback: the callback to invoke. This is optional.
| :param params: the parameters to register with this command. This can
| be either :class:`Option` or :class:`Argument` objects.
| :param help: the help string to use for this command.
| :param epilog: like the help string but it's printed at the end of the
| help page after everything else.
| :param short_help: the short help to use for this command. This is
| shown on the command listing of the parent command.
| :param add_help_option: by default each command registers a ``--help``
| option. This can be disabled by this parameter.
| :param no_args_is_help: this controls what happens if no arguments are
| provided. This option is disabled by default.
| If enabled this will add ``--help`` as argument
| if no arguments are passed
| :param hidden: hide this command from help outputs.
| :param deprecated: If ``True`` or non-empty string, issues a message
| indicating that the command is deprecated and highlights
| its deprecation in --help. The message can be customized
| by using a string as the value.
|
| .. versionchanged:: 8.2
| This is the base class for all commands, not ``BaseCommand``.
| ``deprecated`` can be set to a string as well to customize the
| deprecation message.
|
| .. versionchanged:: 8.1
| ``help``, ``epilog``, and ``short_help`` are stored unprocessed,
| all formatting is done when outputting help text, not at init,
| and is done even if not using the ``@command`` decorator.
|
| .. versionchanged:: 8.0
| Added a ``repr`` showing the command name.
|
| .. versionchanged:: 7.1
| Added the ``no_args_is_help`` parameter.
|
| .. versionchanged:: 2.0
| Added the ``context_settings`` parameter.
|
| Methods defined here:
|
| __call__(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Any'
| Alias for :meth:`main`.
|
| __init__(self, name: 'str | None', context_settings: 'cabc.MutableMapping[str, t.Any] | None' = None, callback: 't.Callable[..., t.Any] | None' = None, params: 'list[Parameter] | None' = None, help: 'str | None' = None, epilog: 'str | None' = None, short_help: 'str | None' = None, options_metavar: 'str | None' = '[OPTIONS]', add_help_option: 'bool' = True, no_args_is_help: 'bool' = False, hidden: 'bool' = False, deprecated: 'bool | str' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| collect_usage_pieces(self, ctx: 'Context') -> 'list[str]'
| Returns all the pieces that go into the usage line and returns
| it as a list of strings.
|
| format_epilog(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the epilog into the formatter if it exists.
|
| format_help(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the help into the formatter if it exists.
|
| This is a low-level method called by :meth:`get_help`.
|
| This calls the following methods:
|
| - :meth:`format_usage`
| - :meth:`format_help_text`
| - :meth:`format_options`
| - :meth:`format_epilog`
|
| format_help_text(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the help text to the formatter if it exists.
|
| format_options(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes all the options into the formatter if they exist.
|
| format_usage(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the usage line into the formatter.
|
| This is a low-level method called by :meth:`get_usage`.
|
| get_help(self, ctx: 'Context') -> 'str'
| Formats the help into a string and returns it.
|
| Calls :meth:`format_help` internally.
|
| get_help_option(self, ctx: 'Context') -> 'Option | None'
| Returns the help option object.
|
| Skipped if :attr:`add_help_option` is ``False``.
|
| .. versionchanged:: 8.1.8
| The help option is now cached to avoid creating it multiple times.
|
| get_help_option_names(self, ctx: 'Context') -> 'list[str]'
| Returns the names for the help option.
|
| get_params(self, ctx: 'Context') -> 'list[Parameter]'
|
| get_short_help_str(self, limit: 'int' = 45) -> 'str'
| Gets short help for the command or makes it by shortening the
| long help string.
|
| get_usage(self, ctx: 'Context') -> 'str'
| Formats the usage line into a string and returns it.
|
| Calls :meth:`format_usage` internally.
|
| invoke(self, ctx: 'Context') -> 't.Any'
| Given a context, this invokes the attached callback (if it exists)
| in the right way.
|
| main(self, args: 'cabc.Sequence[str] | None' = None, prog_name: 'str | None' = None, complete_var: 'str | None' = None, standalone_mode: 'bool' = True, windows_expand_args: 'bool' = True, **extra: 't.Any') -> 't.Any'
| This is the way to invoke a script with all the bells and
| whistles as a command line application. This will always terminate
| the application after a call. If this is not wanted, ``SystemExit``
| needs to be caught.
|
| This method is also available by directly calling the instance of
| a :class:`Command`.
|
| :param args: the arguments that should be used for parsing. If not
| provided, ``sys.argv[1:]`` is used.
| :param prog_name: the program name that should be used. By default
| the program name is constructed by taking the file
| name from ``sys.argv[0]``.
| :param complete_var: the environment variable that controls the
| bash completion support. The default is
| ``"_<prog_name>_COMPLETE"`` with prog_name in
| uppercase.
| :param standalone_mode: the default behavior is to invoke the script
| in standalone mode. Click will then
| handle exceptions and convert them into
| error messages and the function will never
| return but shut down the interpreter. If
| this is set to `False` they will be
| propagated to the caller and the return
| value of this function is the return value
| of :meth:`invoke`.
| :param windows_expand_args: Expand glob patterns, user dir, and
| env vars in command line args on Windows.
| :param extra: extra keyword arguments are forwarded to the context
| constructor. See :class:`Context` for more information.
|
| .. versionchanged:: 8.0.1
| Added the ``windows_expand_args`` parameter to allow
| disabling command line arg expansion on Windows.
|
| .. versionchanged:: 8.0
| When taking arguments from ``sys.argv`` on Windows, glob
| patterns, user dir, and env vars are expanded.
|
| .. versionchanged:: 3.0
| Added the ``standalone_mode`` parameter.
|
| make_context(self, info_name: 'str | None', args: 'list[str]', parent: 'Context | None' = None, **extra: 't.Any') -> 'Context'
| This function when given an info name and arguments will kick
| off the parsing and create a new :class:`Context`. It does not
| invoke the actual command callback though.
|
| To quickly customize the context class used without overriding
| this method, set the :attr:`context_class` attribute.
|
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it's usually
| the name of the script, for commands below it's
| the name of the command.
| :param args: the arguments to parse as list of strings.
| :param parent: the parent context if available.
| :param extra: extra keyword arguments forwarded to the context
| constructor.
|
| .. versionchanged:: 8.0
| Added the :attr:`context_class` attribute.
|
| make_parser(self, ctx: 'Context') -> '_OptionParser'
| Creates the underlying option parser for this command.
|
| parse_args(self, ctx: 'Context', args: 'list[str]') -> 'list[str]'
|
| shell_complete(self, ctx: 'Context', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of completions for the incomplete value. Looks
| at the names of options and chained multi-commands.
|
| Any command could be part of a chained multi-command, so sibling
| commands are valid at any point during command completion.
|
| :param ctx: Invocation context for this command.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self, ctx: 'Context') -> 'dict[str, t.Any]'
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_help_option': 'Option | None', 'add_help_option':...
|
| allow_extra_args = False
|
| allow_interspersed_args = True
|
| context_class = <class 'click.core.Context'>
| The context is a special internal object that holds state relevant
| for the script execution at every single level. It's normally invisible
| to commands unless they opt-in to getting access to it.
|
| The context is useful as it can pass internal objects around and can
| control special execution features such as reading data from
| environment variables.
|
| A context can be used as context manager in which case it will call
| :meth:`close` on teardown.
|
| :param command: the command class for this context.
| :param parent: the parent context.
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it is usually
| the name of the script, for commands below that it's
| the name of the script.
| :param obj: an arbitrary object of user data.
| :param auto_envvar_prefix: the prefix to use for automatic environment
| variables. If this is `None` then reading
| from environment variables is disabled. This
| does not affect manually set environment
| variables which are always read.
| :param default_map: a dictionary (like object) with default values
| for parameters.
| :param terminal_width: the width of the terminal. The default is
| inherit from parent context. If no context
| defines the terminal width then auto
| detection will be applied.
| :param max_content_width: the maximum width for content rendered by
| Click (this currently only affects help
| pages). This defaults to 80 characters if
| not overridden. In other words: even if the
| terminal is larger than that, Click will not
| format things wider than 80 characters by
| default. In addition to that, formatters might
| add some safety mapping on the right.
| :param resilient_parsing: if this flag is enabled then Click will
| parse without any interactivity or callback
| invocation. Default values will also be
| ignored. This is useful for implementing
| things such as completion support.
| :param allow_extra_args: if this is set to `True` then extra arguments
| at the end will not raise an error and will be
| kept on the context. The default is to inherit
| from the command.
| :param allow_interspersed_args: if this is set to `False` then options
| and arguments cannot be mixed. The
| default is to inherit from the command.
| :param ignore_unknown_options: instructs click to ignore options it does
| not know and keeps them for later
| processing.
| :param help_option_names: optionally a list of strings that define how
| the default help parameter is named. The
| default is ``['--help']``.
| :param token_normalize_func: an optional function that is used to
| normalize tokens (options, choices,
| etc.). This for instance can be used to
| implement case insensitive behavior.
| :param color: controls if the terminal supports ANSI colors or not. The
| default is autodetection. This is only needed if ANSI
| codes are used in texts that Click prints which is by
| default not the case. This for instance would affect
| help output.
| :param show_default: Show the default value for commands. If this
| value is not set, it defaults to the value from the parent
| context. ``Command.show_default`` overrides this default for the
| specific command.
|
| .. versionchanged:: 8.2
| The ``protected_args`` attribute is deprecated and will be removed in
| Click 9.0. ``args`` will contain remaining unparsed tokens.
|
| .. versionchanged:: 8.1
| The ``show_default`` parameter is overridden by
| ``Command.show_default``, instead of the other way around.
|
| .. versionchanged:: 8.0
| The ``show_default`` parameter defaults to the value from the
| parent context.
|
| .. versionchanged:: 7.1
| Added the ``show_default`` parameter.
|
| .. versionchanged:: 4.0
| Added the ``color``, ``ignore_unknown_options``, and
| ``max_content_width`` parameters.
|
| .. versionchanged:: 3.0
| Added the ``allow_extra_args`` and ``allow_interspersed_args``
| parameters.
|
| .. versionchanged:: 2.0
| Added the ``resilient_parsing``, ``help_option_names``, and
| ``token_normalize_func`` parameters.
|
|
| ignore_unknown_options = False
click.CommandCollection
Python Library Documentation: class CommandCollection in module click.core
class CommandCollection(Group)
| CommandCollection(name: 'str | None' = None, sources: 'list[Group] | None' = None, **kwargs: 't.Any') -> 'None'
|
| A :class:`Group` that looks up subcommands on other groups. If a command
| is not found on this group, each registered source is checked in order.
| Parameters on a source are not added to this group, and a source's callback
| is not invoked when invoking its commands. In other words, this "flattens"
| commands in many groups into this one group.
|
| :param name: The name of the group command.
| :param sources: A list of :class:`Group` objects to look up commands from.
| :param kwargs: Other arguments passed to :class:`Group`.
|
| .. versionchanged:: 8.2
| This is a subclass of ``Group``. Commands are looked up first on this
| group, then each of its sources.
|
| Method resolution order:
| CommandCollection
| Group
| Command
| builtins.object
|
| Methods defined here:
|
| __init__(self, name: 'str | None' = None, sources: 'list[Group] | None' = None, **kwargs: 't.Any') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| add_source(self, group: 'Group') -> 'None'
| Add a group as a source of commands.
|
| get_command(self, ctx: 'Context', cmd_name: 'str') -> 'Command | None'
| Given a context and a command name, this returns a :class:`Command`
| object if it exists or returns ``None``.
|
| list_commands(self, ctx: 'Context') -> 'list[str]'
| Returns a list of subcommand names in the order they should appear.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'sources': 'list[Group]'}
|
| ----------------------------------------------------------------------
| Methods inherited from Group:
|
| add_command(self, cmd: 'Command', name: 'str | None' = None) -> 'None'
| Registers another :class:`Command` with this group. If the name
| is not provided, the name of the command is used.
|
| collect_usage_pieces(self, ctx: 'Context') -> 'list[str]'
| Returns all the pieces that go into the usage line and returns
| it as a list of strings.
|
| command(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Callable[[t.Callable[..., t.Any]], Command] | Command'
| A shortcut decorator for declaring and attaching a command to
| the group. This takes the same arguments as :func:`command` and
| immediately registers the created command with this group by
| calling :meth:`add_command`.
|
| To customize the command class used, set the
| :attr:`command_class` attribute.
|
| .. versionchanged:: 8.1
| This decorator can be applied without parentheses.
|
| .. versionchanged:: 8.0
| Added the :attr:`command_class` attribute.
|
| format_commands(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Extra format methods for multi methods that adds all the commands
| after the options.
|
| format_options(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes all the options into the formatter if they exist.
|
| group(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Callable[[t.Callable[..., t.Any]], Group] | Group'
| A shortcut decorator for declaring and attaching a group to
| the group. This takes the same arguments as :func:`group` and
| immediately registers the created group with this group by
| calling :meth:`add_command`.
|
| To customize the group class used, set the :attr:`group_class`
| attribute.
|
| .. versionchanged:: 8.1
| This decorator can be applied without parentheses.
|
| .. versionchanged:: 8.0
| Added the :attr:`group_class` attribute.
|
| invoke(self, ctx: 'Context') -> 't.Any'
| Given a context, this invokes the attached callback (if it exists)
| in the right way.
|
| parse_args(self, ctx: 'Context', args: 'list[str]') -> 'list[str]'
|
| resolve_command(self, ctx: 'Context', args: 'list[str]') -> 'tuple[str | None, Command | None, list[str]]'
|
| result_callback(self, replace: 'bool' = False) -> 't.Callable[[F], F]'
| Adds a result callback to the command. By default if a
| result callback is already registered this will chain them but
| this can be disabled with the `replace` parameter. The result
| callback is invoked with the return value of the subcommand
| (or the list of return values from all subcommands if chaining
| is enabled) as well as the parameters as they would be passed
| to the main callback.
|
| Example::
|
| @click.group()
| @click.option('-i', '--input', default=23)
| def cli(input):
| return 42
|
| @cli.result_callback()
| def process_result(result, input):
| return result + input
|
| :param replace: if set to `True` an already existing result
| callback will be removed.
|
| .. versionchanged:: 8.0
| Renamed from ``resultcallback``.
|
| .. versionadded:: 3.0
|
| shell_complete(self, ctx: 'Context', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of completions for the incomplete value. Looks
| at the names of options, subcommands, and chained
| multi-commands.
|
| :param ctx: Invocation context for this command.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self, ctx: 'Context') -> 'dict[str, t.Any]'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Group:
|
| allow_extra_args = True
|
| allow_interspersed_args = False
|
| command_class = None
|
| group_class = None
|
| ----------------------------------------------------------------------
| Methods inherited from Command:
|
| __call__(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Any'
| Alias for :meth:`main`.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| format_epilog(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the epilog into the formatter if it exists.
|
| format_help(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the help into the formatter if it exists.
|
| This is a low-level method called by :meth:`get_help`.
|
| This calls the following methods:
|
| - :meth:`format_usage`
| - :meth:`format_help_text`
| - :meth:`format_options`
| - :meth:`format_epilog`
|
| format_help_text(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the help text to the formatter if it exists.
|
| format_usage(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the usage line into the formatter.
|
| This is a low-level method called by :meth:`get_usage`.
|
| get_help(self, ctx: 'Context') -> 'str'
| Formats the help into a string and returns it.
|
| Calls :meth:`format_help` internally.
|
| get_help_option(self, ctx: 'Context') -> 'Option | None'
| Returns the help option object.
|
| Skipped if :attr:`add_help_option` is ``False``.
|
| .. versionchanged:: 8.1.8
| The help option is now cached to avoid creating it multiple times.
|
| get_help_option_names(self, ctx: 'Context') -> 'list[str]'
| Returns the names for the help option.
|
| get_params(self, ctx: 'Context') -> 'list[Parameter]'
|
| get_short_help_str(self, limit: 'int' = 45) -> 'str'
| Gets short help for the command or makes it by shortening the
| long help string.
|
| get_usage(self, ctx: 'Context') -> 'str'
| Formats the usage line into a string and returns it.
|
| Calls :meth:`format_usage` internally.
|
| main(self, args: 'cabc.Sequence[str] | None' = None, prog_name: 'str | None' = None, complete_var: 'str | None' = None, standalone_mode: 'bool' = True, windows_expand_args: 'bool' = True, **extra: 't.Any') -> 't.Any'
| This is the way to invoke a script with all the bells and
| whistles as a command line application. This will always terminate
| the application after a call. If this is not wanted, ``SystemExit``
| needs to be caught.
|
| This method is also available by directly calling the instance of
| a :class:`Command`.
|
| :param args: the arguments that should be used for parsing. If not
| provided, ``sys.argv[1:]`` is used.
| :param prog_name: the program name that should be used. By default
| the program name is constructed by taking the file
| name from ``sys.argv[0]``.
| :param complete_var: the environment variable that controls the
| bash completion support. The default is
| ``"_<prog_name>_COMPLETE"`` with prog_name in
| uppercase.
| :param standalone_mode: the default behavior is to invoke the script
| in standalone mode. Click will then
| handle exceptions and convert them into
| error messages and the function will never
| return but shut down the interpreter. If
| this is set to `False` they will be
| propagated to the caller and the return
| value of this function is the return value
| of :meth:`invoke`.
| :param windows_expand_args: Expand glob patterns, user dir, and
| env vars in command line args on Windows.
| :param extra: extra keyword arguments are forwarded to the context
| constructor. See :class:`Context` for more information.
|
| .. versionchanged:: 8.0.1
| Added the ``windows_expand_args`` parameter to allow
| disabling command line arg expansion on Windows.
|
| .. versionchanged:: 8.0
| When taking arguments from ``sys.argv`` on Windows, glob
| patterns, user dir, and env vars are expanded.
|
| .. versionchanged:: 3.0
| Added the ``standalone_mode`` parameter.
|
| make_context(self, info_name: 'str | None', args: 'list[str]', parent: 'Context | None' = None, **extra: 't.Any') -> 'Context'
| This function when given an info name and arguments will kick
| off the parsing and create a new :class:`Context`. It does not
| invoke the actual command callback though.
|
| To quickly customize the context class used without overriding
| this method, set the :attr:`context_class` attribute.
|
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it's usually
| the name of the script, for commands below it's
| the name of the command.
| :param args: the arguments to parse as list of strings.
| :param parent: the parent context if available.
| :param extra: extra keyword arguments forwarded to the context
| constructor.
|
| .. versionchanged:: 8.0
| Added the :attr:`context_class` attribute.
|
| make_parser(self, ctx: 'Context') -> '_OptionParser'
| Creates the underlying option parser for this command.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Command:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Command:
|
| context_class = <class 'click.core.Context'>
| The context is a special internal object that holds state relevant
| for the script execution at every single level. It's normally invisible
| to commands unless they opt-in to getting access to it.
|
| The context is useful as it can pass internal objects around and can
| control special execution features such as reading data from
| environment variables.
|
| A context can be used as context manager in which case it will call
| :meth:`close` on teardown.
|
| :param command: the command class for this context.
| :param parent: the parent context.
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it is usually
| the name of the script, for commands below that it's
| the name of the script.
| :param obj: an arbitrary object of user data.
| :param auto_envvar_prefix: the prefix to use for automatic environment
| variables. If this is `None` then reading
| from environment variables is disabled. This
| does not affect manually set environment
| variables which are always read.
| :param default_map: a dictionary (like object) with default values
| for parameters.
| :param terminal_width: the width of the terminal. The default is
| inherit from parent context. If no context
| defines the terminal width then auto
| detection will be applied.
| :param max_content_width: the maximum width for content rendered by
| Click (this currently only affects help
| pages). This defaults to 80 characters if
| not overridden. In other words: even if the
| terminal is larger than that, Click will not
| format things wider than 80 characters by
| default. In addition to that, formatters might
| add some safety mapping on the right.
| :param resilient_parsing: if this flag is enabled then Click will
| parse without any interactivity or callback
| invocation. Default values will also be
| ignored. This is useful for implementing
| things such as completion support.
| :param allow_extra_args: if this is set to `True` then extra arguments
| at the end will not raise an error and will be
| kept on the context. The default is to inherit
| from the command.
| :param allow_interspersed_args: if this is set to `False` then options
| and arguments cannot be mixed. The
| default is to inherit from the command.
| :param ignore_unknown_options: instructs click to ignore options it does
| not know and keeps them for later
| processing.
| :param help_option_names: optionally a list of strings that define how
| the default help parameter is named. The
| default is ``['--help']``.
| :param token_normalize_func: an optional function that is used to
| normalize tokens (options, choices,
| etc.). This for instance can be used to
| implement case insensitive behavior.
| :param color: controls if the terminal supports ANSI colors or not. The
| default is autodetection. This is only needed if ANSI
| codes are used in texts that Click prints which is by
| default not the case. This for instance would affect
| help output.
| :param show_default: Show the default value for commands. If this
| value is not set, it defaults to the value from the parent
| context. ``Command.show_default`` overrides this default for the
| specific command.
|
| .. versionchanged:: 8.2
| The ``protected_args`` attribute is deprecated and will be removed in
| Click 9.0. ``args`` will contain remaining unparsed tokens.
|
| .. versionchanged:: 8.1
| The ``show_default`` parameter is overridden by
| ``Command.show_default``, instead of the other way around.
|
| .. versionchanged:: 8.0
| The ``show_default`` parameter defaults to the value from the
| parent context.
|
| .. versionchanged:: 7.1
| Added the ``show_default`` parameter.
|
| .. versionchanged:: 4.0
| Added the ``color``, ``ignore_unknown_options``, and
| ``max_content_width`` parameters.
|
| .. versionchanged:: 3.0
| Added the ``allow_extra_args`` and ``allow_interspersed_args``
| parameters.
|
| .. versionchanged:: 2.0
| Added the ``resilient_parsing``, ``help_option_names``, and
| ``token_normalize_func`` parameters.
|
|
| ignore_unknown_options = False
click.Context
Python Library Documentation: class Context in module click.core
class Context(builtins.object)
| Context(command: 'Command', parent: 'Context | None' = None, info_name: 'str | None' = None, obj: 't.Any | None' = None, auto_envvar_prefix: 'str | None' = None, default_map: 'cabc.MutableMapping[str, t.Any] | None' = None, terminal_width: 'int | None' = None, max_content_width: 'int | None' = None, resilient_parsing: 'bool' = False, allow_extra_args: 'bool | None' = None, allow_interspersed_args: 'bool | None' = None, ignore_unknown_options: 'bool | None' = None, help_option_names: 'list[str] | None' = None, token_normalize_func: 't.Callable[[str], str] | None' = None, color: 'bool | None' = None, show_default: 'bool | None' = None) -> 'None'
|
| The context is a special internal object that holds state relevant
| for the script execution at every single level. It's normally invisible
| to commands unless they opt-in to getting access to it.
|
| The context is useful as it can pass internal objects around and can
| control special execution features such as reading data from
| environment variables.
|
| A context can be used as context manager in which case it will call
| :meth:`close` on teardown.
|
| :param command: the command class for this context.
| :param parent: the parent context.
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it is usually
| the name of the script, for commands below that it's
| the name of the script.
| :param obj: an arbitrary object of user data.
| :param auto_envvar_prefix: the prefix to use for automatic environment
| variables. If this is `None` then reading
| from environment variables is disabled. This
| does not affect manually set environment
| variables which are always read.
| :param default_map: a dictionary (like object) with default values
| for parameters.
| :param terminal_width: the width of the terminal. The default is
| inherit from parent context. If no context
| defines the terminal width then auto
| detection will be applied.
| :param max_content_width: the maximum width for content rendered by
| Click (this currently only affects help
| pages). This defaults to 80 characters if
| not overridden. In other words: even if the
| terminal is larger than that, Click will not
| format things wider than 80 characters by
| default. In addition to that, formatters might
| add some safety mapping on the right.
| :param resilient_parsing: if this flag is enabled then Click will
| parse without any interactivity or callback
| invocation. Default values will also be
| ignored. This is useful for implementing
| things such as completion support.
| :param allow_extra_args: if this is set to `True` then extra arguments
| at the end will not raise an error and will be
| kept on the context. The default is to inherit
| from the command.
| :param allow_interspersed_args: if this is set to `False` then options
| and arguments cannot be mixed. The
| default is to inherit from the command.
| :param ignore_unknown_options: instructs click to ignore options it does
| not know and keeps them for later
| processing.
| :param help_option_names: optionally a list of strings that define how
| the default help parameter is named. The
| default is ``['--help']``.
| :param token_normalize_func: an optional function that is used to
| normalize tokens (options, choices,
| etc.). This for instance can be used to
| implement case insensitive behavior.
| :param color: controls if the terminal supports ANSI colors or not. The
| default is autodetection. This is only needed if ANSI
| codes are used in texts that Click prints which is by
| default not the case. This for instance would affect
| help output.
| :param show_default: Show the default value for commands. If this
| value is not set, it defaults to the value from the parent
| context. ``Command.show_default`` overrides this default for the
| specific command.
|
| .. versionchanged:: 8.2
| The ``protected_args`` attribute is deprecated and will be removed in
| Click 9.0. ``args`` will contain remaining unparsed tokens.
|
| .. versionchanged:: 8.1
| The ``show_default`` parameter is overridden by
| ``Command.show_default``, instead of the other way around.
|
| .. versionchanged:: 8.0
| The ``show_default`` parameter defaults to the value from the
| parent context.
|
| .. versionchanged:: 7.1
| Added the ``show_default`` parameter.
|
| .. versionchanged:: 4.0
| Added the ``color``, ``ignore_unknown_options``, and
| ``max_content_width`` parameters.
|
| .. versionchanged:: 3.0
| Added the ``allow_extra_args`` and ``allow_interspersed_args``
| parameters.
|
| .. versionchanged:: 2.0
| Added the ``resilient_parsing``, ``help_option_names``, and
| ``token_normalize_func`` parameters.
|
| Methods defined here:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, exc_type: 'type[BaseException] | None', exc_value: 'BaseException | None', tb: 'TracebackType | None') -> 'bool | None'
|
| __init__(self, command: 'Command', parent: 'Context | None' = None, info_name: 'str | None' = None, obj: 't.Any | None' = None, auto_envvar_prefix: 'str | None' = None, default_map: 'cabc.MutableMapping[str, t.Any] | None' = None, terminal_width: 'int | None' = None, max_content_width: 'int | None' = None, resilient_parsing: 'bool' = False, allow_extra_args: 'bool | None' = None, allow_interspersed_args: 'bool | None' = None, ignore_unknown_options: 'bool | None' = None, help_option_names: 'list[str] | None' = None, token_normalize_func: 't.Callable[[str], str] | None' = None, color: 'bool | None' = None, show_default: 'bool | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| abort(self) -> 't.NoReturn'
| Aborts the script.
|
| call_on_close(self, f: 't.Callable[..., t.Any]') -> 't.Callable[..., t.Any]'
| Register a function to be called when the context tears down.
|
| This can be used to close resources opened during the script
| execution. Resources that support Python's context manager
| protocol which would be used in a ``with`` statement should be
| registered with :meth:`with_resource` instead.
|
| :param f: The function to execute on teardown.
|
| close(self) -> 'None'
| Invoke all close callbacks registered with
| :meth:`call_on_close`, and exit all context managers entered
| with :meth:`with_resource`.
|
| ensure_object(self, object_type: 'type[V]') -> 'V'
| Like :meth:`find_object` but sets the innermost object to a
| new instance of `object_type` if it does not exist.
|
| exit(self, code: 'int' = 0) -> 't.NoReturn'
| Exits the application with a given exit code.
|
| .. versionchanged:: 8.2
| Callbacks and context managers registered with :meth:`call_on_close`
| and :meth:`with_resource` are closed before exiting.
|
| fail(self, message: 'str') -> 't.NoReturn'
| Aborts the execution of the program with a specific error
| message.
|
| :param message: the error message to fail with.
|
| find_object(self, object_type: 'type[V]') -> 'V | None'
| Finds the closest object of a given type.
|
| find_root(self) -> 'Context'
| Finds the outermost context.
|
| forward(self, cmd: 'Command', /, *args: 't.Any', **kwargs: 't.Any') -> 't.Any'
| Similar to :meth:`invoke` but fills in default keyword
| arguments from the current context if the other command expects
| it. This cannot invoke callbacks directly, only other commands.
|
| .. versionchanged:: 8.0
| All ``kwargs`` are tracked in :attr:`params` so they will be
| passed if ``forward`` is called at multiple levels.
|
| get_help(self) -> 'str'
| Helper method to get formatted help page for the current
| context and command.
|
| get_parameter_source(self, name: 'str') -> 'ParameterSource | None'
| Get the source of a parameter. This indicates the location
| from which the value of the parameter was obtained.
|
| This can be useful for determining when a user specified a value
| on the command line that is the same as the default value. It
| will be :attr:`~click.core.ParameterSource.DEFAULT` only if the
| value was actually taken from the default.
|
| :param name: The name of the parameter.
| :rtype: ParameterSource
|
| .. versionchanged:: 8.0
| Returns ``None`` if the parameter was not provided from any
| source.
|
| get_usage(self) -> 'str'
| Helper method to get formatted usage string for the current
| context and command.
|
| invoke(self, callback: 'Command | t.Callable[..., V]', /, *args: 't.Any', **kwargs: 't.Any') -> 't.Any | V'
| Invokes a command callback in exactly the way it expects. There
| are two ways to invoke this method:
|
| 1. the first argument can be a callback and all other arguments and
| keyword arguments are forwarded directly to the function.
| 2. the first argument is a click command object. In that case all
| arguments are forwarded as well but proper click parameters
| (options and click arguments) must be keyword arguments and Click
| will fill in defaults.
|
| .. versionchanged:: 8.0
| All ``kwargs`` are tracked in :attr:`params` so they will be
| passed if :meth:`forward` is called at multiple levels.
|
| .. versionchanged:: 3.2
| A new context is created, and missing arguments use default values.
|
| lookup_default(self, name: 'str', call: 'bool' = True) -> 't.Any | None'
| Get the default for a parameter from :attr:`default_map`.
|
| :param name: Name of the parameter.
| :param call: If the default is a callable, call it. Disable to
| return the callable instead.
|
| .. versionchanged:: 8.0
| Added the ``call`` parameter.
|
| make_formatter(self) -> 'HelpFormatter'
| Creates the :class:`~click.HelpFormatter` for the help and
| usage output.
|
| To quickly customize the formatter class used without overriding
| this method, set the :attr:`formatter_class` attribute.
|
| .. versionchanged:: 8.0
| Added the :attr:`formatter_class` attribute.
|
| scope(self, cleanup: 'bool' = True) -> 'cabc.Generator[Context]'
| This helper method can be used with the context object to promote
| it to the current thread local (see :func:`get_current_context`).
| The default behavior of this is to invoke the cleanup functions which
| can be disabled by setting `cleanup` to `False`. The cleanup
| functions are typically used for things such as closing file handles.
|
| If the cleanup is intended the context object can also be directly
| used as a context manager.
|
| Example usage::
|
| with ctx.scope():
| assert get_current_context() is ctx
|
| This is equivalent::
|
| with ctx:
| assert get_current_context() is ctx
|
| .. versionadded:: 5.0
|
| :param cleanup: controls if the cleanup functions should be run or
| not. The default is to run these functions. In
| some situations the context only wants to be
| temporarily pushed in which case this can be disabled.
| Nested pushes automatically defer the cleanup.
|
| set_parameter_source(self, name: 'str', source: 'ParameterSource') -> 'None'
| Set the source of a parameter. This indicates the location
| from which the value of the parameter was obtained.
|
| :param name: The name of the parameter.
| :param source: A member of :class:`~click.core.ParameterSource`.
|
| to_info_dict(self) -> 'dict[str, t.Any]'
| Gather information that could be useful for a tool generating
| user-facing documentation. This traverses the entire CLI
| structure.
|
| .. code-block:: python
|
| with Context(cli) as ctx:
| info = ctx.to_info_dict()
|
| .. versionadded:: 8.0
|
| with_resource(self, context_manager: 'AbstractContextManager[V]') -> 'V'
| Register a resource as if it were used in a ``with``
| statement. The resource will be cleaned up when the context is
| popped.
|
| Uses :meth:`contextlib.ExitStack.enter_context`. It calls the
| resource's ``__enter__()`` method and returns the result. When
| the context is popped, it closes the stack, which calls the
| resource's ``__exit__()`` method.
|
| To register a cleanup function for something that isn't a
| context manager, use :meth:`call_on_close`. Or use something
| from :mod:`contextlib` to turn it into a context manager first.
|
| .. code-block:: python
|
| @click.group()
| @click.option("--name")
| @click.pass_context
| def cli(ctx):
| ctx.obj = ctx.with_resource(connect_db(name))
|
| :param context_manager: The context manager to enter.
| :return: Whatever ``context_manager.__enter__()`` returns.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| command_path
| The computed command path. This is used for the ``usage``
| information on the help page. It's automatically created by
| combining the info names of the chain of contexts to the root.
|
| meta
| This is a dictionary which is shared with all the contexts
| that are nested. It exists so that click utilities can store some
| state here if they need to. It is however the responsibility of
| that code to manage this dictionary well.
|
| The keys are supposed to be unique dotted strings. For instance
| module paths are a good choice for it. What is stored in there is
| irrelevant for the operation of click. However what is important is
| that code that places data here adheres to the general semantics of
| the system.
|
| Example usage::
|
| LANG_KEY = f'{__name__}.lang'
|
| def set_language(value):
| ctx = get_current_context()
| ctx.meta[LANG_KEY] = value
|
| def get_language():
| return get_current_context().meta.get(LANG_KEY, 'en_US')
|
| .. versionadded:: 5.0
|
| protected_args
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_close_callbacks': 'list[t.Callable[[], t.Any]]', ...
|
| formatter_class = <class 'click.formatting.HelpFormatter'>
| This class helps with formatting text-based help pages. It's
| usually just needed for very special internal cases, but it's also
| exposed so that developers can write their own fancy outputs.
|
| At present, it always writes into memory.
|
| :param indent_increment: the additional increment for each level.
| :param width: the width for the text. This defaults to the terminal
| width clamped to a maximum of 78.
click.DateTime
Python Library Documentation: class DateTime in module click.types
class DateTime(ParamType)
| DateTime(formats: 'cabc.Sequence[str] | None' = None)
|
| The DateTime type converts date strings into `datetime` objects.
|
| The format strings which are checked are configurable, but default to some
| common (non-timezone aware) ISO 8601 formats.
|
| When specifying *DateTime* formats, you should only pass a list or a tuple.
| Other iterables, like generators, may lead to surprising results.
|
| The format strings are processed using ``datetime.strptime``, and this
| consequently defines the format strings which are allowed.
|
| Parsing is tried using each format, in order, and the first format which
| parses successfully is used.
|
| :param formats: A list or tuple of date format strings, in the order in
| which they should be tried. Defaults to
| ``'%Y-%m-%d'``, ``'%Y-%m-%dT%H:%M:%S'``,
| ``'%Y-%m-%d %H:%M:%S'``.
|
| Method resolution order:
| DateTime
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, formats: 'cabc.Sequence[str] | None' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: 't.Any', param: 'Parameter | None', ctx: 'Context | None') -> 'datetime'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str'
| Returns the metavar default for this param if it provides one.
|
| to_info_dict(self) -> 'DateTimeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'formats': 'cabc.Sequence[str]'}
|
| __orig_bases__ = (click.types.ParamType[datetime.datetime],)
|
| __parameters__ = ()
|
| name = 'datetime'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.FLOAT
Python Library Documentation: FloatParamType in module click.types object
class FloatParamType(_NumberParamTypeBase)
| Method resolution order:
| FloatParamType
| _NumberParamTypeBase
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types._NumberParamTypeBase[typing.SupportsFloa...
|
| __parameters__ = ()
|
| name = 'float'
|
| ----------------------------------------------------------------------
| Methods inherited from _NumberParamTypeBase:
|
| convert(self, value: '_ValueT_contra', param: 'Parameter | None', ctx: 'Context | None') -> '_ValueT_co'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.File
Python Library Documentation: class File in module click.types
class File(ParamType)
| File(mode: 'str' = 'r', encoding: 'str | None' = None, errors: 'str | None' = 'strict', lazy: 'bool | None' = None, atomic: 'bool' = False) -> 'None'
|
| Declares a parameter to be a file for reading or writing. The file
| is automatically closed once the context tears down (after the command
| finished working).
|
| Files can be opened for reading or writing. The special value ``-``
| indicates stdin or stdout depending on the mode.
|
| By default, the file is opened for reading text data, but it can also be
| opened in binary mode or for writing. The encoding parameter can be used
| to force a specific encoding.
|
| The `lazy` flag controls if the file should be opened immediately or upon
| first IO. The default is to be non-lazy for standard input and output
| streams as well as files opened for reading, `lazy` otherwise. When opening a
| file lazily for reading, it is still opened temporarily for validation, but
| will not be held open until first IO. lazy is mainly useful when opening
| for writing to avoid creating the file until it is needed.
|
| Files can also be opened atomically in which case all writes go into a
| separate file in the same folder and upon completion the file will
| be moved over to the original location. This is useful if a file
| regularly read by other users is modified.
|
| See :ref:`file-args` for more information.
|
| .. versionchanged:: 2.0
| Added the ``atomic`` parameter.
|
| Method resolution order:
| File
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, mode: 'str' = 'r', encoding: 'str | None' = None, errors: 'str | None' = 'strict', lazy: 'bool | None' = None, atomic: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| convert(self, value: 'str | os.PathLike[str] | t.IO[t.Any]', param: 'Parameter | None', ctx: 'Context | None') -> 't.IO[t.Any]'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| resolve_lazy_flag(self, value: 'str | os.PathLike[str]') -> 'bool'
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a special completion marker that tells the completion
| system to use the shell to provide file path completions.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self) -> 'FileInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'atomic': 'bool', 'encoding': 'str | None', 'envvar...
|
| __orig_bases__ = (click.types.ParamType[typing.IO[typing.Any]],)
|
| __parameters__ = ()
|
| envvar_list_splitter = ';'
|
| name = 'filename'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.FileError
Python Library Documentation: class FileError in module click.exceptions
class FileError(ClickException)
| FileError(filename: 'str', hint: 'str | None' = None) -> 'None'
|
| Raised if a file cannot be opened.
|
| Method resolution order:
| FileError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, filename: 'str', hint: 'str | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'filename': 't.Final[str]', 'ui_filename': 't.Final...
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClickException:
|
| exit_code = 1
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
click.FloatRange
Python Library Documentation: class FloatRange in module click.types
class FloatRange(_NumberRangeBase, FloatParamType)
| FloatRange(min: 'float | None' = None, max: 'float | None' = None, min_open: 'bool' = False, max_open: 'bool' = False, clamp: 'bool' = False) -> 'None'
|
| Restrict a :data:`click.FLOAT` value to a range of accepted
| values. See :ref:`ranges`.
|
| If ``min`` or ``max`` are not passed, any value is accepted in that
| direction. If ``min_open`` or ``max_open`` are enabled, the
| corresponding boundary is not included in the range.
|
| If ``clamp`` is enabled, a value outside the range is clamped to the
| boundary instead of failing. This is not supported if either
| boundary is marked ``open``.
|
| .. versionchanged:: 8.0
| Added the ``min_open`` and ``max_open`` parameters.
|
| Method resolution order:
| FloatRange
| _NumberRangeBase
| FloatParamType
| _NumberParamTypeBase
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, min: 'float | None' = None, max: 'float | None' = None, min_open: 'bool' = False, max_open: 'bool' = False, clamp: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types._NumberRangeBase[float, float], <class '...
|
| __parameters__ = ()
|
| name = 'float range'
|
| ----------------------------------------------------------------------
| Methods inherited from _NumberRangeBase:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: '_ValueT_contra', param: 'Parameter | None', ctx: 'Context | None') -> '_FloatValueT_co'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| to_info_dict(self) -> 'NumberRangeInfoDict[_FloatValueT_co]'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.Group
Python Library Documentation: class Group in module click.core
class Group(Command)
| Group(name: 'str | None' = None, commands: 'cabc.MutableMapping[str, Command] | cabc.Sequence[Command] | None' = None, invoke_without_command: 'bool' = False, no_args_is_help: 'bool | None' = None, subcommand_metavar: 'str | None' = None, chain: 'bool' = False, result_callback: 't.Callable[..., t.Any] | None' = None, **kwargs: 't.Any') -> 'None'
|
| A group is a command that nests other commands (or more groups).
|
| :param name: The name of the group command.
| :param commands: Map names to :class:`Command` objects. Can be a list, which
| will use :attr:`Command.name` as the keys.
| :param invoke_without_command: Invoke the group's callback even if a
| subcommand is not given.
| :param no_args_is_help: If no arguments are given, show the group's help and
| exit. Defaults to the opposite of ``invoke_without_command``.
| :param subcommand_metavar: How to represent the subcommand argument in help.
| The default will represent whether ``chain`` is set or not.
| :param chain: Allow passing more than one subcommand argument. After parsing
| a command's arguments, if any arguments remain another command will be
| matched, and so on.
| :param result_callback: A function to call after the group's and
| subcommand's callbacks. The value returned by the subcommand is passed.
| If ``chain`` is enabled, the value will be a list of values returned by
| all the commands. If ``invoke_without_command`` is enabled, the value
| will be the value returned by the group's callback, or an empty list if
| ``chain`` is enabled.
| :param kwargs: Other arguments passed to :class:`Command`.
|
| .. versionchanged:: 8.0
| The ``commands`` argument can be a list of command objects.
|
| .. versionchanged:: 8.2
| Merged with and replaces the ``MultiCommand`` base class.
|
| Method resolution order:
| Group
| Command
| builtins.object
|
| Methods defined here:
|
| __init__(self, name: 'str | None' = None, commands: 'cabc.MutableMapping[str, Command] | cabc.Sequence[Command] | None' = None, invoke_without_command: 'bool' = False, no_args_is_help: 'bool | None' = None, subcommand_metavar: 'str | None' = None, chain: 'bool' = False, result_callback: 't.Callable[..., t.Any] | None' = None, **kwargs: 't.Any') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| add_command(self, cmd: 'Command', name: 'str | None' = None) -> 'None'
| Registers another :class:`Command` with this group. If the name
| is not provided, the name of the command is used.
|
| collect_usage_pieces(self, ctx: 'Context') -> 'list[str]'
| Returns all the pieces that go into the usage line and returns
| it as a list of strings.
|
| command(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Callable[[t.Callable[..., t.Any]], Command] | Command'
| A shortcut decorator for declaring and attaching a command to
| the group. This takes the same arguments as :func:`command` and
| immediately registers the created command with this group by
| calling :meth:`add_command`.
|
| To customize the command class used, set the
| :attr:`command_class` attribute.
|
| .. versionchanged:: 8.1
| This decorator can be applied without parentheses.
|
| .. versionchanged:: 8.0
| Added the :attr:`command_class` attribute.
|
| format_commands(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Extra format methods for multi methods that adds all the commands
| after the options.
|
| format_options(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes all the options into the formatter if they exist.
|
| get_command(self, ctx: 'Context', cmd_name: 'str') -> 'Command | None'
| Given a context and a command name, this returns a :class:`Command`
| object if it exists or returns ``None``.
|
| group(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Callable[[t.Callable[..., t.Any]], Group] | Group'
| A shortcut decorator for declaring and attaching a group to
| the group. This takes the same arguments as :func:`group` and
| immediately registers the created group with this group by
| calling :meth:`add_command`.
|
| To customize the group class used, set the :attr:`group_class`
| attribute.
|
| .. versionchanged:: 8.1
| This decorator can be applied without parentheses.
|
| .. versionchanged:: 8.0
| Added the :attr:`group_class` attribute.
|
| invoke(self, ctx: 'Context') -> 't.Any'
| Given a context, this invokes the attached callback (if it exists)
| in the right way.
|
| list_commands(self, ctx: 'Context') -> 'list[str]'
| Returns a list of subcommand names in the order they should appear.
|
| parse_args(self, ctx: 'Context', args: 'list[str]') -> 'list[str]'
|
| resolve_command(self, ctx: 'Context', args: 'list[str]') -> 'tuple[str | None, Command | None, list[str]]'
|
| result_callback(self, replace: 'bool' = False) -> 't.Callable[[F], F]'
| Adds a result callback to the command. By default if a
| result callback is already registered this will chain them but
| this can be disabled with the `replace` parameter. The result
| callback is invoked with the return value of the subcommand
| (or the list of return values from all subcommands if chaining
| is enabled) as well as the parameters as they would be passed
| to the main callback.
|
| Example::
|
| @click.group()
| @click.option('-i', '--input', default=23)
| def cli(input):
| return 42
|
| @cli.result_callback()
| def process_result(result, input):
| return result + input
|
| :param replace: if set to `True` an already existing result
| callback will be removed.
|
| .. versionchanged:: 8.0
| Renamed from ``resultcallback``.
|
| .. versionadded:: 3.0
|
| shell_complete(self, ctx: 'Context', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of completions for the incomplete value. Looks
| at the names of options, subcommands, and chained
| multi-commands.
|
| :param ctx: Invocation context for this command.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self, ctx: 'Context') -> 'dict[str, t.Any]'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_result_callback': 't.Callable[..., t.Any] | None'...
|
| allow_extra_args = True
|
| allow_interspersed_args = False
|
| command_class = None
|
| group_class = None
|
| ----------------------------------------------------------------------
| Methods inherited from Command:
|
| __call__(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Any'
| Alias for :meth:`main`.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| format_epilog(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the epilog into the formatter if it exists.
|
| format_help(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the help into the formatter if it exists.
|
| This is a low-level method called by :meth:`get_help`.
|
| This calls the following methods:
|
| - :meth:`format_usage`
| - :meth:`format_help_text`
| - :meth:`format_options`
| - :meth:`format_epilog`
|
| format_help_text(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the help text to the formatter if it exists.
|
| format_usage(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the usage line into the formatter.
|
| This is a low-level method called by :meth:`get_usage`.
|
| get_help(self, ctx: 'Context') -> 'str'
| Formats the help into a string and returns it.
|
| Calls :meth:`format_help` internally.
|
| get_help_option(self, ctx: 'Context') -> 'Option | None'
| Returns the help option object.
|
| Skipped if :attr:`add_help_option` is ``False``.
|
| .. versionchanged:: 8.1.8
| The help option is now cached to avoid creating it multiple times.
|
| get_help_option_names(self, ctx: 'Context') -> 'list[str]'
| Returns the names for the help option.
|
| get_params(self, ctx: 'Context') -> 'list[Parameter]'
|
| get_short_help_str(self, limit: 'int' = 45) -> 'str'
| Gets short help for the command or makes it by shortening the
| long help string.
|
| get_usage(self, ctx: 'Context') -> 'str'
| Formats the usage line into a string and returns it.
|
| Calls :meth:`format_usage` internally.
|
| main(self, args: 'cabc.Sequence[str] | None' = None, prog_name: 'str | None' = None, complete_var: 'str | None' = None, standalone_mode: 'bool' = True, windows_expand_args: 'bool' = True, **extra: 't.Any') -> 't.Any'
| This is the way to invoke a script with all the bells and
| whistles as a command line application. This will always terminate
| the application after a call. If this is not wanted, ``SystemExit``
| needs to be caught.
|
| This method is also available by directly calling the instance of
| a :class:`Command`.
|
| :param args: the arguments that should be used for parsing. If not
| provided, ``sys.argv[1:]`` is used.
| :param prog_name: the program name that should be used. By default
| the program name is constructed by taking the file
| name from ``sys.argv[0]``.
| :param complete_var: the environment variable that controls the
| bash completion support. The default is
| ``"_<prog_name>_COMPLETE"`` with prog_name in
| uppercase.
| :param standalone_mode: the default behavior is to invoke the script
| in standalone mode. Click will then
| handle exceptions and convert them into
| error messages and the function will never
| return but shut down the interpreter. If
| this is set to `False` they will be
| propagated to the caller and the return
| value of this function is the return value
| of :meth:`invoke`.
| :param windows_expand_args: Expand glob patterns, user dir, and
| env vars in command line args on Windows.
| :param extra: extra keyword arguments are forwarded to the context
| constructor. See :class:`Context` for more information.
|
| .. versionchanged:: 8.0.1
| Added the ``windows_expand_args`` parameter to allow
| disabling command line arg expansion on Windows.
|
| .. versionchanged:: 8.0
| When taking arguments from ``sys.argv`` on Windows, glob
| patterns, user dir, and env vars are expanded.
|
| .. versionchanged:: 3.0
| Added the ``standalone_mode`` parameter.
|
| make_context(self, info_name: 'str | None', args: 'list[str]', parent: 'Context | None' = None, **extra: 't.Any') -> 'Context'
| This function when given an info name and arguments will kick
| off the parsing and create a new :class:`Context`. It does not
| invoke the actual command callback though.
|
| To quickly customize the context class used without overriding
| this method, set the :attr:`context_class` attribute.
|
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it's usually
| the name of the script, for commands below it's
| the name of the command.
| :param args: the arguments to parse as list of strings.
| :param parent: the parent context if available.
| :param extra: extra keyword arguments forwarded to the context
| constructor.
|
| .. versionchanged:: 8.0
| Added the :attr:`context_class` attribute.
|
| make_parser(self, ctx: 'Context') -> '_OptionParser'
| Creates the underlying option parser for this command.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Command:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Command:
|
| context_class = <class 'click.core.Context'>
| The context is a special internal object that holds state relevant
| for the script execution at every single level. It's normally invisible
| to commands unless they opt-in to getting access to it.
|
| The context is useful as it can pass internal objects around and can
| control special execution features such as reading data from
| environment variables.
|
| A context can be used as context manager in which case it will call
| :meth:`close` on teardown.
|
| :param command: the command class for this context.
| :param parent: the parent context.
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it is usually
| the name of the script, for commands below that it's
| the name of the script.
| :param obj: an arbitrary object of user data.
| :param auto_envvar_prefix: the prefix to use for automatic environment
| variables. If this is `None` then reading
| from environment variables is disabled. This
| does not affect manually set environment
| variables which are always read.
| :param default_map: a dictionary (like object) with default values
| for parameters.
| :param terminal_width: the width of the terminal. The default is
| inherit from parent context. If no context
| defines the terminal width then auto
| detection will be applied.
| :param max_content_width: the maximum width for content rendered by
| Click (this currently only affects help
| pages). This defaults to 80 characters if
| not overridden. In other words: even if the
| terminal is larger than that, Click will not
| format things wider than 80 characters by
| default. In addition to that, formatters might
| add some safety mapping on the right.
| :param resilient_parsing: if this flag is enabled then Click will
| parse without any interactivity or callback
| invocation. Default values will also be
| ignored. This is useful for implementing
| things such as completion support.
| :param allow_extra_args: if this is set to `True` then extra arguments
| at the end will not raise an error and will be
| kept on the context. The default is to inherit
| from the command.
| :param allow_interspersed_args: if this is set to `False` then options
| and arguments cannot be mixed. The
| default is to inherit from the command.
| :param ignore_unknown_options: instructs click to ignore options it does
| not know and keeps them for later
| processing.
| :param help_option_names: optionally a list of strings that define how
| the default help parameter is named. The
| default is ``['--help']``.
| :param token_normalize_func: an optional function that is used to
| normalize tokens (options, choices,
| etc.). This for instance can be used to
| implement case insensitive behavior.
| :param color: controls if the terminal supports ANSI colors or not. The
| default is autodetection. This is only needed if ANSI
| codes are used in texts that Click prints which is by
| default not the case. This for instance would affect
| help output.
| :param show_default: Show the default value for commands. If this
| value is not set, it defaults to the value from the parent
| context. ``Command.show_default`` overrides this default for the
| specific command.
|
| .. versionchanged:: 8.2
| The ``protected_args`` attribute is deprecated and will be removed in
| Click 9.0. ``args`` will contain remaining unparsed tokens.
|
| .. versionchanged:: 8.1
| The ``show_default`` parameter is overridden by
| ``Command.show_default``, instead of the other way around.
|
| .. versionchanged:: 8.0
| The ``show_default`` parameter defaults to the value from the
| parent context.
|
| .. versionchanged:: 7.1
| Added the ``show_default`` parameter.
|
| .. versionchanged:: 4.0
| Added the ``color``, ``ignore_unknown_options``, and
| ``max_content_width`` parameters.
|
| .. versionchanged:: 3.0
| Added the ``allow_extra_args`` and ``allow_interspersed_args``
| parameters.
|
| .. versionchanged:: 2.0
| Added the ``resilient_parsing``, ``help_option_names``, and
| ``token_normalize_func`` parameters.
|
|
| ignore_unknown_options = False
click.HelpFormatter
Python Library Documentation: class HelpFormatter in module click.formatting
class HelpFormatter(builtins.object)
| HelpFormatter(indent_increment: 'int' = 2, width: 'int | None' = None, max_width: 'int | None' = None) -> 'None'
|
| This class helps with formatting text-based help pages. It's
| usually just needed for very special internal cases, but it's also
| exposed so that developers can write their own fancy outputs.
|
| At present, it always writes into memory.
|
| :param indent_increment: the additional increment for each level.
| :param width: the width for the text. This defaults to the terminal
| width clamped to a maximum of 78.
|
| Methods defined here:
|
| __init__(self, indent_increment: 'int' = 2, width: 'int | None' = None, max_width: 'int | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| dedent(self) -> 'None'
| Decreases the indentation.
|
| getvalue(self) -> 'str'
| Returns the buffer contents.
|
| indent(self) -> 'None'
| Increases the indentation.
|
| indentation(self) -> 'cabc.Generator[None]'
| A context manager that increases the indentation.
|
| section(self, name: 'str') -> 'cabc.Generator[None]'
| Helpful context manager that writes a paragraph, a heading,
| and the indents.
|
| :param name: the section name that is written as heading.
|
| write(self, string: 'str') -> 'None'
| Writes a unicode string into the internal buffer.
|
| write_dl(self, rows: 'cabc.Iterable[tuple[str, str]]', col_max: 'int' = 30, col_spacing: 'int' = 2) -> 'None'
| Writes a definition list into the buffer. This is how options
| and commands are usually formatted.
|
| :param rows: a list of two item tuples for the terms and values.
| :param col_max: the maximum width of the first column.
| :param col_spacing: the number of spaces between the first and
| second column.
|
| write_heading(self, heading: 'str') -> 'None'
| Writes a heading into the buffer.
|
| write_paragraph(self) -> 'None'
| Writes a paragraph into the buffer.
|
| write_text(self, text: 'str') -> 'None'
| Writes re-indented text into the buffer. This rewraps and
| preserves paragraphs.
|
| write_usage(self, prog: 'str', args: 'str' = '', prefix: 'str | None' = None) -> 'None'
| Writes a usage line into the buffer.
|
| :param prog: the program name.
| :param args: whitespace separated list of arguments.
| :param prefix: The prefix for the first line. Defaults to
| ``"Usage: "``.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'buffer': 'list[str]', 'current_indent': 'int', 'in...
click.INT
Python Library Documentation: IntParamType in module click.types object
class IntParamType(_NumberParamTypeBase)
| Method resolution order:
| IntParamType
| _NumberParamTypeBase
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types._NumberParamTypeBase[typing.SupportsInt ...
|
| __parameters__ = ()
|
| name = 'integer'
|
| ----------------------------------------------------------------------
| Methods inherited from _NumberParamTypeBase:
|
| convert(self, value: '_ValueT_contra', param: 'Parameter | None', ctx: 'Context | None') -> '_ValueT_co'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.IntRange
Python Library Documentation: class IntRange in module click.types
class IntRange(_NumberRangeBase, IntParamType)
| IntRange(min: '_FloatValueT_co | None' = None, max: '_FloatValueT_co | None' = None, min_open: 'bool' = False, max_open: 'bool' = False, clamp: 'bool' = False) -> 'None'
|
| Restrict an :data:`click.INT` value to a range of accepted
| values. See :ref:`ranges`.
|
| If ``min`` or ``max`` are not passed, any value is accepted in that
| direction. If ``min_open`` or ``max_open`` are enabled, the
| corresponding boundary is not included in the range.
|
| If ``clamp`` is enabled, a value outside the range is clamped to the
| boundary instead of failing.
|
| .. versionchanged:: 8.0
| Added the ``min_open`` and ``max_open`` parameters.
|
| Method resolution order:
| IntRange
| _NumberRangeBase
| IntParamType
| _NumberParamTypeBase
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types._NumberRangeBase[int, int], <class 'clic...
|
| __parameters__ = ()
|
| name = 'integer range'
|
| ----------------------------------------------------------------------
| Methods inherited from _NumberRangeBase:
|
| __init__(self, min: '_FloatValueT_co | None' = None, max: '_FloatValueT_co | None' = None, min_open: 'bool' = False, max_open: 'bool' = False, clamp: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: '_ValueT_contra', param: 'Parameter | None', ctx: 'Context | None') -> '_FloatValueT_co'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| to_info_dict(self) -> 'NumberRangeInfoDict[_FloatValueT_co]'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.MissingParameter
Python Library Documentation: class MissingParameter in module click.exceptions
class MissingParameter(BadParameter)
| MissingParameter(message: 'str | None' = None, ctx: 'Context | None' = None, param: 'Parameter | None' = None, param_hint: 'cabc.Sequence[str] | str | None' = None, param_type: 'str | None' = None) -> 'None'
|
| Raised if click required an option or argument but it was not
| provided when invoking the script.
|
| .. versionadded:: 4.0
|
| :param param_type: a string that indicates the type of the parameter.
| The default is to inherit the parameter type from
| the given `param`. Valid values are ``'parameter'``,
| ``'option'`` or ``'argument'``.
|
| Method resolution order:
| MissingParameter
| BadParameter
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, message: 'str | None' = None, ctx: 'Context | None' = None, param: 'Parameter | None' = None, param_hint: 'cabc.Sequence[str] | str | None' = None, param_type: 'str | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __str__(self) -> 'str'
| Return str(self).
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'param_type': 't.Final[str | None]'}
|
| ----------------------------------------------------------------------
| Methods inherited from UsageError:
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UsageError:
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
click.NoSuchCommand
Python Library Documentation: class NoSuchCommand in module click.exceptions
class NoSuchCommand(UsageError)
| NoSuchCommand(command_name: 'str', message: 'str | None' = None, possibilities: 'cabc.Iterable[str] | None' = None, ctx: 'Context | None' = None) -> 'None'
|
| Raised if Click attempted to handle a command that does not exist.
|
| .. versionadded:: 8.4.0
|
| Method resolution order:
| NoSuchCommand
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, command_name: 'str', message: 'str | None' = None, possibilities: 'cabc.Iterable[str] | None' = None, ctx: 'Context | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'command_name': 't.Final[str]', 'possibilities': 't...
|
| ----------------------------------------------------------------------
| Methods inherited from UsageError:
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UsageError:
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
click.NoSuchOption
Python Library Documentation: class NoSuchOption in module click.exceptions
class NoSuchOption(UsageError)
| NoSuchOption(option_name: 'str', message: 'str | None' = None, possibilities: 'cabc.Iterable[str] | None' = None, ctx: 'Context | None' = None) -> 'None'
|
| Raised if Click attempted to handle an option that does not exist.
|
| .. versionadded:: 4.0
|
| Method resolution order:
| NoSuchOption
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, option_name: 'str', message: 'str | None' = None, possibilities: 'cabc.Iterable[str] | None' = None, ctx: 'Context | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'option_name': 't.Final[str]', 'possibilities': 't....
|
| ----------------------------------------------------------------------
| Methods inherited from UsageError:
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UsageError:
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
click.Option
Python Library Documentation: class Option in module click.core
class Option(Parameter)
| Option(param_decls: 'cabc.Sequence[str] | None' = None, show_default: 'bool | str | None' = None, prompt: 'bool | str' = False, confirmation_prompt: 'bool | str' = False, prompt_required: 'bool' = True, hide_input: 'bool' = False, is_flag: 'bool | None' = None, flag_value: 't.Any' = Sentinel.UNSET, multiple: 'bool' = False, count: 'bool' = False, allow_from_autoenv: 'bool' = True, type: 'types.ParamType[t.Any] | t.Any | None' = None, help: 'str | None' = None, hidden: 'bool' = False, show_choices: 'bool' = True, show_envvar: 'bool' = False, deprecated: 'bool | str' = False, **attrs: 't.Any') -> 'None'
|
| Options are usually optional values on the command line and
| have some extra features that arguments don't have.
|
| All other parameters are passed onwards to the parameter constructor.
|
| :param show_default: Show the default value for this option in its
| help text. Values are not shown by default, unless
| :attr:`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``.
| :param show_envvar: Controls if an environment variable should be
| shown on the help page and error messages.
| Normally, environment variables are not shown.
| :param prompt: If set to ``True`` or a non empty string then the
| user will be prompted for input. If set to ``True`` the prompt
| will be the option name capitalized. A deprecated option cannot be
| prompted.
| :param confirmation_prompt: Prompt a second time to confirm the
| value if it was prompted for. Can be set to a string instead of
| ``True`` to customize the message.
| :param prompt_required: If set to ``False``, the user will be
| prompted for input only when the option was specified as a flag
| without a value.
| :param hide_input: If this is ``True`` then the input on the prompt
| will be hidden from the user. This is useful for password input.
| :param is_flag: forces this option to act as a flag. The default is
| auto detection.
| :param flag_value: which value should be used for this flag if it's
| enabled. This is set to a boolean automatically if
| the option string contains a slash to mark two options.
| :param multiple: if this is set to `True` then the argument is accepted
| multiple times and recorded. This is similar to ``nargs``
| in how it works but supports arbitrary number of
| arguments.
| :param count: this flag makes an option increment an integer.
| :param allow_from_autoenv: if this is enabled then the value of this
| parameter will be pulled from an environment
| variable in case a prefix is defined on the
| context.
| :param help: the help string.
| :param hidden: hide this option from help outputs.
| :param attrs: Other command arguments described in :class:`Parameter`.
|
| .. versionchanged:: 8.4.0
| Non-basic ``flag_value`` types (not ``str``, ``int``, ``float``, or
| ``bool``) are passed through unchanged instead of being stringified.
| Previously, ``type=click.UNPROCESSED`` was required to preserve them.
|
| .. versionchanged:: 8.2
| ``envvar`` used with ``flag_value`` will always use the ``flag_value``,
| previously it would use the value of the environment variable.
|
| .. versionchanged:: 8.1
| Help text indentation is cleaned here instead of only in the
| ``@option`` decorator.
|
| .. versionchanged:: 8.1
| The ``show_default`` parameter overrides
| ``Context.show_default``.
|
| .. versionchanged:: 8.1
| The default of a single option boolean flag is not shown if the
| default value is ``False``.
|
| .. versionchanged:: 8.0.1
| ``type`` is detected from ``flag_value`` if given, for basic Python
| types (``str``, ``int``, ``float``, ``bool``).
|
| Method resolution order:
| Option
| Parameter
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, param_decls: 'cabc.Sequence[str] | None' = None, show_default: 'bool | str | None' = None, prompt: 'bool | str' = False, confirmation_prompt: 'bool | str' = False, prompt_required: 'bool' = True, hide_input: 'bool' = False, is_flag: 'bool | None' = None, flag_value: 't.Any' = Sentinel.UNSET, multiple: 'bool' = False, count: 'bool' = False, allow_from_autoenv: 'bool' = True, type: 'types.ParamType[t.Any] | t.Any | None' = None, help: 'str | None' = None, hidden: 'bool' = False, show_choices: 'bool' = True, show_envvar: 'bool' = False, deprecated: 'bool | str' = False, **attrs: 't.Any') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| add_to_parser(self, parser: '_OptionParser', ctx: 'Context') -> 'None'
|
| consume_value(self, ctx: 'Context', opts: 'cabc.Mapping[str, Parameter]') -> 'tuple[t.Any, ParameterSource]'
| For :class:`Option`, the value can be collected from an interactive prompt
| if the option is a flag that needs a value (and the :attr:`prompt` property is
| set).
|
| Additionally, this method handles flag option that are activated without a
| value, in which case the :attr:`flag_value` is returned.
|
| :meta private:
|
| get_default(self, ctx: 'Context', call: 'bool' = True) -> 't.Any | t.Callable[[], t.Any] | None'
| Return the default value for this option.
|
| For non-boolean flag options, ``default=True`` is treated as a sentinel
| meaning "activate this flag by default" and is resolved to
| :attr:`flag_value`. For example, with ``--upper/--lower`` feature
| switches where ``flag_value="upper"`` and ``default=True``, the default
| resolves to ``"upper"``.
|
| .. caution::
| This substitution only applies to non-boolean flags
| (:attr:`is_bool_flag` is ``False``). For boolean flags, ``True`` is
| a legitimate Python value and ``default=True`` is returned as-is.
|
| .. versionchanged:: 8.3.3
| ``default=True`` is no longer substituted with ``flag_value`` for
| boolean flags, fixing negative boolean flags like
| ``flag_value=False, default=True``.
|
| get_error_hint(self, ctx: 'Context | None') -> 'str'
| Get a stringified version of the param for use in error messages to
| indicate which param caused the error.
|
| .. versionchanged:: 8.4.0
| ``ctx`` can be ``None``.
|
| get_help_extra(self, ctx: 'Context') -> 'types.OptionHelpExtra'
|
| get_help_record(self, ctx: 'Context') -> 'tuple[str, str] | None'
|
| process_value(self, ctx: 'Context', value: 't.Any') -> 't.Any'
| Process the value of this parameter:
|
| 1. Type cast the value using :meth:`type_cast_value`.
| 2. Check if the value is missing (see: :meth:`value_is_missing`), and raise
| :exc:`MissingParameter` if it is required.
| 3. If a :attr:`callback` is set, call it to have the value replaced by the
| result of the callback. If the value was not set, the callback receive
| ``None``. This keep the legacy behavior as it was before the introduction of
| the :attr:`UNSET` sentinel.
|
| :meta private:
|
| prompt_for_value(self, ctx: 'Context') -> 't.Any'
| This is an alternative flow that can be activated in the full
| value processing if a value does not exist. It will prompt the
| user until a valid value exists and then returns the processed
| value as result.
|
| resolve_envvar_value(self, ctx: 'Context') -> 'str | None'
| :class:`Option` resolves its environment variable the same way as
| :func:`Parameter.resolve_envvar_value`, but it also supports
| :attr:`Context.auto_envvar_prefix`. If we could not find an environment from
| the :attr:`envvar` property, we fallback on :attr:`Context.auto_envvar_prefix`
| to build dynamiccaly the environment variable name using the
| :python:`{ctx.auto_envvar_prefix}_{self.name.upper()}` template.
|
| :meta private:
|
| to_info_dict(self) -> 'dict[str, t.Any]'
| .. versionchanged:: 8.3.0
| Returns ``None`` for the :attr:`flag_value` if it was not set.
|
| value_from_envvar(self, ctx: 'Context') -> 't.Any'
| For :class:`Option`, this method processes the raw environment variable
| string the same way as :func:`Parameter.value_from_envvar` does.
|
| But in the case of non-boolean flags, the value is analyzed to determine if the
| flag is activated or not, and returns a boolean of its activation, or the
| :attr:`flag_value` if the latter is set.
|
| This method also takes care of repeated options (i.e. options with
| :attr:`multiple` set to ``True``).
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'_flag_needs_value': 'bool', 'allow_from_autoenv': ...
|
| param_type_name = 'option'
|
| ----------------------------------------------------------------------
| Methods inherited from Parameter:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| get_usage_pieces(self, ctx: 'Context') -> 'list[str]'
|
| handle_parse_result(self, ctx: 'Context', opts: 'cabc.Mapping[str, t.Any]', args: 'list[str]') -> 'tuple[t.Any, list[str]]'
| Process the value produced by the parser from user input.
|
| Always process the value through the Parameter's :attr:`type`, wherever it
| comes from.
|
| If the parameter is deprecated, this method warn the user about it. But only if
| the value has been explicitly set by the user (and as such, is not coming from
| a default).
|
| :meta private:
|
| make_metavar(self, ctx: 'Context') -> 'str'
|
| shell_complete(self, ctx: 'Context', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of completions for the incomplete value. If a
| ``shell_complete`` function was given during init, it is used.
| Otherwise, the :attr:`type`
| :meth:`~click.types.ParamType[t.Any].shell_complete` function is used.
|
| :param ctx: Invocation context for this command.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| type_cast_value(self, ctx: 'Context', value: 't.Any') -> 't.Any'
| Convert and validate a value against the parameter's
| :attr:`type`, :attr:`multiple`, and :attr:`nargs`.
|
| value_is_missing(self, value: 't.Any') -> 'bool'
| A value is considered missing if:
|
| - it is :attr:`UNSET`,
| - or if it is an empty sequence while the parameter is suppose to have
| non-single value (i.e. :attr:`nargs` is not ``1`` or :attr:`multiple` is
| set).
|
| :meta private:
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Parameter:
|
| 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.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Parameter:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
click.ParamType
Python Library Documentation: class ParamType in module click.types
class ParamType(typing.Generic, abc.ABC)
| Represents the type of a parameter. Validates and converts values
| from the command line or Python into the correct type.
|
| To implement a custom type, subclass and implement at least the
| following:
|
| - The :attr:`name` class attribute must be set.
| - Calling an instance of the type with ``None`` must return
| ``None``. This is already implemented by default.
| - :meth:`convert` must convert string values to the correct type.
| - :meth:`convert` must accept values that are already the correct
| type.
| - It must be able to convert a value if the ``ctx`` and ``param``
| arguments are ``None``. This can occur when converting prompt
| input.
|
| .. versionchanged:: 8.4.0
| Now a generic abstract base class. Parameterize with the
| converted value type (``ParamType[int]`` for an integer-returning
| type) so that :meth:`convert` and downstream consumers carry the
| narrowed return type.
|
| Method resolution order:
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| convert(self, value: 't.Any', param: 'Parameter | None', ctx: 'Context | None') -> '_ValueT_co'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'arity': 'int', 'envvar_list_splitter': 't.ClassVar...
|
| __orig_bases__ = (typing.Generic[+_ValueT_co], <class 'abc.ABC'>)
|
| __parameters__ = (+_ValueT_co,)
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.Parameter
Python Library Documentation: class Parameter in module click.core
class Parameter(abc.ABC)
| Parameter(param_decls: 'cabc.Sequence[str] | None' = None, type: 'types.ParamType[t.Any] | t.Any | None' = None, required: 'bool' = False, default: 't.Any | t.Callable[[], t.Any] | None' = Sentinel.UNSET, callback: 't.Callable[[Context, Parameter, t.Any], t.Any] | None' = None, nargs: 'int | None' = None, multiple: 'bool' = False, metavar: 'str | None' = None, expose_value: 'bool' = True, is_eager: 'bool' = False, envvar: 'str | cabc.Sequence[str] | None' = None, shell_complete: 't.Callable[[Context, Parameter, str], list[CompletionItem] | list[str]] | None' = None, deprecated: 'bool | str' = False) -> 'None'
|
| A parameter to a command comes in two versions: they are either
| :class:`Option`\s or :class:`Argument`\s. 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.
|
| :param param_decls: the parameter declarations for this option or
| argument. This is a list of flags or argument
| names.
| :param type: the type that should be used. Either a :class:`ParamType`
| or a Python type. The latter is converted into the former
| automatically if supported.
| :param required: controls if this is optional or not.
| :param 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.
| :param 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.
| :param 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.
| :param metavar: how the value is represented in the help page.
| :param 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.
| :param 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.
| :param envvar: environment variable(s) that are used to provide a default value for
| this parameter. This can be a string or a sequence of strings. If a sequence is
| given, only the first non-empty environment variable is used for the parameter.
| :param 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 :class:`~click.shell_completion.CompletionItem` or a list of
| strings.
| :param deprecated: If ``True`` or 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.
|
| .. versionchanged:: 8.2.0
| Introduction of ``deprecated``.
|
| .. versionchanged:: 8.2
| Adding duplicate parameter names to a :class:`~click.core.Command` will
| result in a ``UserWarning`` being shown.
|
| .. versionchanged:: 8.2
| Adding duplicate parameter names to a :class:`~click.core.Command` will
| result in a ``UserWarning`` being shown.
|
| .. versionchanged:: 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.
|
| .. versionchanged:: 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.
|
| .. versionchanged:: 8.0
| For ``multiple=True, nargs>1``, the default must be a list of
| tuples.
|
| .. versionchanged:: 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 ``()``.
|
| .. versionchanged:: 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.
|
| .. versionchanged:: 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.
|
| Method resolution order:
| Parameter
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, param_decls: 'cabc.Sequence[str] | None' = None, type: 'types.ParamType[t.Any] | t.Any | None' = None, required: 'bool' = False, default: 't.Any | t.Callable[[], t.Any] | None' = Sentinel.UNSET, callback: 't.Callable[[Context, Parameter, t.Any], t.Any] | None' = None, nargs: 'int | None' = None, multiple: 'bool' = False, metavar: 'str | None' = None, expose_value: 'bool' = True, is_eager: 'bool' = False, envvar: 'str | cabc.Sequence[str] | None' = None, shell_complete: 't.Callable[[Context, Parameter, str], list[CompletionItem] | list[str]] | None' = None, deprecated: 'bool | str' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| add_to_parser(self, parser: '_OptionParser', ctx: 'Context') -> 'None'
|
| consume_value(self, ctx: 'Context', opts: 'cabc.Mapping[str, t.Any]') -> 'tuple[t.Any, ParameterSource]'
| Returns the parameter value produced by the parser.
|
| If the parser did not produce a value from user input, the value is either
| sourced from the environment variable, the default map, or the parameter's
| default value. In that order of precedence.
|
| If no value is found, an internal sentinel value is returned.
|
| :meta private:
|
| get_default(self, ctx: 'Context', call: 'bool' = True) -> 't.Any | t.Callable[[], t.Any] | None'
| Get the default for the parameter. Tries
| :meth:`Context.lookup_default` first, then the local default.
|
| :param ctx: Current context.
| :param call: If the default is a callable, call it. Disable to
| return the callable instead.
|
| .. versionchanged:: 8.0.2
| Type casting is no longer performed when getting a default.
|
| .. versionchanged:: 8.0.1
| Type casting can fail in resilient parsing mode. Invalid
| defaults will not prevent showing help text.
|
| .. versionchanged:: 8.0
| Looks at ``ctx.default_map`` first.
|
| .. versionchanged:: 8.0
| Added the ``call`` parameter.
|
| get_error_hint(self, ctx: 'Context | None') -> 'str'
| Get a stringified version of the param for use in error messages to
| indicate which param caused the error.
|
| .. versionchanged:: 8.4.0
| ``ctx`` can be ``None``.
|
| get_help_record(self, ctx: 'Context') -> 'tuple[str, str] | None'
|
| get_usage_pieces(self, ctx: 'Context') -> 'list[str]'
|
| handle_parse_result(self, ctx: 'Context', opts: 'cabc.Mapping[str, t.Any]', args: 'list[str]') -> 'tuple[t.Any, list[str]]'
| Process the value produced by the parser from user input.
|
| Always process the value through the Parameter's :attr:`type`, wherever it
| comes from.
|
| If the parameter is deprecated, this method warn the user about it. But only if
| the value has been explicitly set by the user (and as such, is not coming from
| a default).
|
| :meta private:
|
| make_metavar(self, ctx: 'Context') -> 'str'
|
| process_value(self, ctx: 'Context', value: 't.Any') -> 't.Any'
| Process the value of this parameter:
|
| 1. Type cast the value using :meth:`type_cast_value`.
| 2. Check if the value is missing (see: :meth:`value_is_missing`), and raise
| :exc:`MissingParameter` if it is required.
| 3. If a :attr:`callback` is set, call it to have the value replaced by the
| result of the callback. If the value was not set, the callback receive
| ``None``. This keep the legacy behavior as it was before the introduction of
| the :attr:`UNSET` sentinel.
|
| :meta private:
|
| resolve_envvar_value(self, ctx: 'Context') -> 'str | None'
| Returns the value found in the environment variable(s) attached to this
| parameter.
|
| Environment variables values are `always returned as strings
| <https://docs.python.org/3/library/os.html#os.environ>`_.
|
| This method returns ``None`` if:
|
| - the :attr:`envvar` property is not set on the :class:`Parameter`,
| - the environment variable is not found in the environment,
| - the variable is found in the environment but its value is empty (i.e. the
| environment variable is present but has an empty string).
|
| If :attr:`envvar` is setup with multiple environment variables,
| then only the first non-empty value is returned.
|
| .. caution::
|
| The raw value extracted from the environment is not normalized and is
| returned as-is. Any normalization or reconciliation is performed later by
| the :class:`Parameter`'s :attr:`type`.
|
| :meta private:
|
| shell_complete(self, ctx: 'Context', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of completions for the incomplete value. If a
| ``shell_complete`` function was given during init, it is used.
| Otherwise, the :attr:`type`
| :meth:`~click.types.ParamType[t.Any].shell_complete` function is used.
|
| :param ctx: Invocation context for this command.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self) -> 'dict[str, t.Any]'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionchanged:: 8.3.0
| Returns ``None`` for the :attr:`default` if it was not set.
|
| .. versionadded:: 8.0
|
| type_cast_value(self, ctx: 'Context', value: 't.Any') -> 't.Any'
| Convert and validate a value against the parameter's
| :attr:`type`, :attr:`multiple`, and :attr:`nargs`.
|
| value_from_envvar(self, ctx: 'Context') -> 'str | cabc.Sequence[str] | None'
| Process the raw environment variable string for this parameter.
|
| Returns the string as-is or splits it into a sequence of strings if the
| parameter is expecting multiple values (i.e. its :attr:`nargs` property is set
| to a value other than ``1``).
|
| :meta private:
|
| value_is_missing(self, value: 't.Any') -> 'bool'
| A value is considered missing if:
|
| - it is :attr:`UNSET`,
| - or if it is an empty sequence while the parameter is suppose to have
| non-single value (i.e. :attr:`nargs` is not ``1`` or :attr:`multiple` is
| set).
|
| :meta private:
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| 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.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset({'_parse_decls', 'add_to_parser'})
|
| __annotations__ = {'_custom_shell_complete': 't.Callable[[Context, Par...
|
| param_type_name = 'parameter'
click.ParameterSource
Python Library Documentation: class ParameterSource in module click.core
class ParameterSource(enum.IntEnum)
| ParameterSource(*values)
|
| This is an :class:`~enum.IntEnum` that indicates the source of a
| parameter's value.
|
| Use :meth:`click.Context.get_parameter_source` to get the
| source for a parameter by name.
|
| Members are ordered from most explicit to least explicit source.
| This allows comparison to check if a value was explicitly provided:
|
| .. code-block:: python
|
| source = ctx.get_parameter_source("port")
| if source < click.ParameterSource.DEFAULT_MAP:
| ... # value was explicitly set
|
| .. versionchanged:: 8.3.3
| Use :class:`~enum.IntEnum` and reorder members from most to
| least explicit. Supports comparison operators.
|
| .. versionchanged:: 8.0
| Use :class:`~enum.Enum` and drop the ``validate`` method.
|
| .. versionchanged:: 8.0
| Added the ``PROMPT`` value.
|
| Method resolution order:
| ParameterSource
| enum.IntEnum
| builtins.int
| enum.ReprEnum
| enum.Enum
| builtins.object
|
| Methods defined here:
|
| __format__(self, format_spec, /) from builtins.int
| Convert to a string according to format_spec.
|
| __new__(cls, value) from enum.Enum
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| COMMANDLINE = <ParameterSource.COMMANDLINE: 2>
|
| DEFAULT = <ParameterSource.DEFAULT: 5>
|
| DEFAULT_MAP = <ParameterSource.DEFAULT_MAP: 4>
|
| ENVIRONMENT = <ParameterSource.ENVIRONMENT: 3>
|
| PROMPT = <ParameterSource.PROMPT: 1>
|
| ----------------------------------------------------------------------
| Methods inherited from enum.IntEnum:
|
| __repr__(self) from enum.Enum
| Return repr(self).
|
| __str__ = __repr__(self, /) from builtins.int
| Return repr(self).
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.int:
|
| __abs__(self, /)
| abs(self)
|
| __add__(self, value, /)
| Return self+value.
|
| __and__(self, value, /)
| Return self&value.
|
| __bool__(self, /)
| True if self else False
|
| __ceil__(...)
| Ceiling of an Integral returns itself.
|
| __divmod__(self, value, /)
| Return divmod(self, value).
|
| __eq__(self, value, /)
| Return self==value.
|
| __float__(self, /)
| float(self)
|
| __floor__(...)
| Flooring an Integral returns itself.
|
| __floordiv__(self, value, /)
| Return self//value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getnewargs__(self, /)
|
| __gt__(self, value, /)
| Return self>value.
|
| __hash__(self, /)
| Return hash(self).
|
| __index__(self, /)
| Return self converted to an integer, if self is suitable for use as an index into a list.
|
| __int__(self, /)
| int(self)
|
| __invert__(self, /)
| ~self
|
| __le__(self, value, /)
| Return self<=value.
|
| __lshift__(self, value, /)
| Return self<<value.
|
| __lt__(self, value, /)
| Return self<value.
|
| __mod__(self, value, /)
| Return self%value.
|
| __mul__(self, value, /)
| Return self*value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __neg__(self, /)
| -self
|
| __or__(self, value, /)
| Return self|value.
|
| __pos__(self, /)
| +self
|
| __pow__(self, value, mod=None, /)
| Return pow(self, value, mod).
|
| __radd__(self, value, /)
| Return value+self.
|
| __rand__(self, value, /)
| Return value&self.
|
| __rdivmod__(self, value, /)
| Return divmod(value, self).
|
| __rfloordiv__(self, value, /)
| Return value//self.
|
| __rlshift__(self, value, /)
| Return value<<self.
|
| __rmod__(self, value, /)
| Return value%self.
|
| __rmul__(self, value, /)
| Return value*self.
|
| __ror__(self, value, /)
| Return value|self.
|
| __round__(...)
| Rounding an Integral returns itself.
|
| Rounding with an ndigits argument also returns an integer.
|
| __rpow__(self, value, mod=None, /)
| Return pow(value, self, mod).
|
| __rrshift__(self, value, /)
| Return value>>self.
|
| __rshift__(self, value, /)
| Return self>>value.
|
| __rsub__(self, value, /)
| Return value-self.
|
| __rtruediv__(self, value, /)
| Return value/self.
|
| __rxor__(self, value, /)
| Return value^self.
|
| __sizeof__(self, /)
| Returns size in memory, in bytes.
|
| __sub__(self, value, /)
| Return self-value.
|
| __truediv__(self, value, /)
| Return self/value.
|
| __trunc__(...)
| Truncating an Integral returns itself.
|
| __xor__(self, value, /)
| Return self^value.
|
| as_integer_ratio(self, /)
| Return a pair of integers, whose ratio is equal to the original int.
|
| The ratio is in lowest terms and has a positive denominator.
|
| >>> (10).as_integer_ratio()
| (10, 1)
| >>> (-10).as_integer_ratio()
| (-10, 1)
| >>> (0).as_integer_ratio()
| (0, 1)
|
| bit_count(self, /)
| Number of ones in the binary representation of the absolute value of self.
|
| Also known as the population count.
|
| >>> bin(13)
| '0b1101'
| >>> (13).bit_count()
| 3
|
| bit_length(self, /)
| Number of bits necessary to represent self in binary.
|
| >>> bin(37)
| '0b100101'
| >>> (37).bit_length()
| 6
|
| conjugate(...)
| Returns self, the complex conjugate of any int.
|
| is_integer(self, /)
| Returns True. Exists for duck type compatibility with float.is_integer.
|
| to_bytes(self, /, length=1, byteorder='big', *, signed=False)
| Return an array of bytes representing an integer.
|
| length
| Length of bytes object to use. An OverflowError is raised if the
| integer is not representable with the given number of bytes. Default
| is length 1.
| byteorder
| The byte order used to represent the integer. If byteorder is 'big',
| the most significant byte is at the beginning of the byte array. If
| byteorder is 'little', the most significant byte is at the end of the
| byte array. To request the native byte order of the host system, use
| `sys.byteorder' as the byte order value. Default is to use 'big'.
| signed
| Determines whether two's complement is used to represent the integer.
| If signed is False and a negative integer is given, an OverflowError
| is raised.
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.int:
|
| from_bytes(bytes, byteorder='big', *, signed=False)
| Return the integer represented by the given array of bytes.
|
| bytes
| Holds the array of bytes to convert. The argument must either
| support the buffer protocol or be an iterable object producing bytes.
| Bytes and bytearray are examples of built-in objects that support the
| buffer protocol.
| byteorder
| The byte order used to represent the integer. If byteorder is 'big',
| the most significant byte is at the beginning of the byte array. If
| byteorder is 'little', the most significant byte is at the end of the
| byte array. To request the native byte order of the host system, use
| `sys.byteorder' as the byte order value. Default is to use 'big'.
| signed
| Indicates whether two's complement is used to represent the integer.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.int:
|
| denominator
| the denominator of a rational number in lowest terms
|
| imag
| the imaginary part of a complex number
|
| numerator
| the numerator of a rational number in lowest terms
|
| real
| the real part of a complex number
|
| ----------------------------------------------------------------------
| Methods inherited from enum.Enum:
|
| __dir__(self)
| Returns public methods and other interesting attributes.
|
| __init__(self, *args, **kwds)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce_ex__(self, proto)
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from enum.Enum:
|
| name
| The name of the Enum member.
|
| value
| The value of the Enum member.
|
| ----------------------------------------------------------------------
| Static methods inherited from enum.EnumType:
|
| __contains__(value)
| Return True if `value` is in `cls`.
|
| `value` is in `cls` if:
| 1) `value` is a member of `cls`, or
| 2) `value` is the value of one of the `cls`'s members.
|
| __getitem__(name)
| Return the member matching `name`.
|
| __iter__()
| Return members in definition order.
|
| __len__()
| Return the number of members (no aliases)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from enum.EnumType:
|
| __members__
| Returns a mapping of member name->value.
|
| This mapping lists all enum members, including aliases. Note that this
| is a read-only view of the internal mapping.
click.Path
Python Library Documentation: class Path in module click.types
class Path(ParamType)
| Path(exists: 'bool' = False, file_okay: 'bool' = True, dir_okay: 'bool' = True, writable: 'bool' = False, readable: 'bool' = True, resolve_path: 'bool' = False, allow_dash: 'bool' = False, path_type: 'type | None' = None, executable: 'bool' = False) -> 'None'
|
| The ``Path`` type is similar to the :class:`File` type, but
| returns the filename instead of an open file. Various checks can be
| enabled to validate the type of file and permissions.
|
| :param exists: The file or directory needs to exist for the value to
| be valid. If this is not set to ``True``, and the file does not
| exist, then all further checks are silently skipped.
| :param file_okay: Allow a file as a value.
| :param dir_okay: Allow a directory as a value.
| :param readable: if true, a readable check is performed.
| :param writable: if true, a writable check is performed.
| :param executable: if true, an executable check is performed.
| :param resolve_path: Make the value absolute and resolve any
| symlinks. A ``~`` is not expanded, as this is supposed to be
| done by the shell only.
| :param allow_dash: Allow a single dash as a value, which indicates
| a standard stream (but does not open it). Use
| :func:`~click.open_file` to handle opening this value.
| :param path_type: Convert the incoming path value to this type. If
| ``None``, keep Python's default, which is ``str``. Useful to
| convert to :class:`pathlib.Path`.
|
| .. versionchanged:: 8.1
| Added the ``executable`` parameter.
|
| .. versionchanged:: 8.0
| Allow passing ``path_type=pathlib.Path``.
|
| .. versionchanged:: 6.0
| Added the ``allow_dash`` parameter.
|
| Method resolution order:
| Path
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, exists: 'bool' = False, file_okay: 'bool' = True, dir_okay: 'bool' = True, writable: 'bool' = False, readable: 'bool' = True, resolve_path: 'bool' = False, allow_dash: 'bool' = False, path_type: 'type | None' = None, executable: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| coerce_path_result(self, value: 'str | os.PathLike[str]') -> 'str | bytes | os.PathLike[str]'
|
| convert(self, value: 'str | os.PathLike[str]', param: 'Parameter | None', ctx: 'Context | None') -> 'str | bytes | os.PathLike[str]'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a special completion marker that tells the completion
| system to use the shell to provide path completions for only
| directories or any paths.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self) -> 'PathInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'allow_dash': 'bool', 'dir_okay': 'bool', 'envvar_l...
|
| __orig_bases__ = (click.types.ParamType[str | bytes | os.PathLike[str]...
|
| __parameters__ = ()
|
| envvar_list_splitter = ';'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.STRING
Python Library Documentation: StringParamType in module click.types object
class StringParamType(ParamType)
| Method resolution order:
| StringParamType
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: 't.Any', param: 'Parameter | None', ctx: 'Context | None') -> 'str'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types.ParamType[str],)
|
| __parameters__ = ()
|
| name = 'text'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.Tuple
Python Library Documentation: class Tuple in module click.types
class Tuple(CompositeParamType)
| Tuple(types: 'cabc.Sequence[type[t.Any] | ParamType[t.Any]]') -> 'None'
|
| The default behavior of Click is to apply a type on a value directly.
| This works well in most cases, except for when `nargs` is set to a fixed
| count and different types should be used for different items. In this
| case the :class:`Tuple` type can be used. This type can only be used
| if `nargs` is set to a fixed number.
|
| For more information see :ref:`tuple-type`.
|
| This can be selected by using a Python tuple literal as a type.
|
| :param types: a list of types that should be used for the tuple items.
|
| Method resolution order:
| Tuple
| CompositeParamType
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, types: 'cabc.Sequence[type[t.Any] | ParamType[t.Any]]') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| convert(self, value: 't.Any', param: 'Parameter | None', ctx: 'Context | None') -> 'tuple[t.Any, ...]'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| to_info_dict(self) -> 'TupleInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| arity
|
| name
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types.CompositeParamType[tuple[typing.Any, ......
|
| __parameters__ = ()
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompositeParamType:
|
| is_composite = True
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| envvar_list_splitter = None
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.UNPROCESSED
Python Library Documentation: UnprocessedParamType in module click.types object
class UnprocessedParamType(ParamType)
| Method resolution order:
| UnprocessedParamType
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: '_ValueT', param: 'Parameter | None', ctx: 'Context | None') -> '_ValueT'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types.ParamType[typing.Any],)
|
| __parameters__ = ()
|
| name = 'text'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.UUID
Python Library Documentation: UUIDParameterType in module click.types object
class UUIDParameterType(ParamType)
| Method resolution order:
| UUIDParameterType
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: 'uuid.UUID | str', param: 'Parameter | None', ctx: 'Context | None') -> 'uuid.UUID'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types.ParamType[uuid.UUID],)
|
| __parameters__ = ()
|
| name = 'uuid'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
click.UsageError
Python Library Documentation: class UsageError in module click.exceptions
class UsageError(ClickException)
| UsageError(message: 'str', ctx: 'Context | None' = None) -> 'None'
|
| An internal exception that signals a usage error. This typically
| aborts any further handling.
|
| :param message: the error message to display.
| :param ctx: optionally the context that caused this error. Click will
| fill in the context automatically in some situations.
|
| Method resolution order:
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, message: 'str', ctx: 'Context | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'cmd': 't.Final[Command | None]', 'ctx': 'Context |...
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
click.annotations
Python Library Documentation: _Feature in module __future__ object class _Feature(builtins.object) | _Feature(optionalRelease, mandatoryRelease, compiler_flag) | | Methods defined here: | | __init__(self, optionalRelease, mandatoryRelease, compiler_flag) | Initialize self. See help(type(self)) for accurate signature. | | __repr__(self) | Return repr(self). | | getMandatoryRelease(self) | Return release in which this feature will become mandatory. | | This is a 5-tuple, of the same form as sys.version_info, or, if | the feature was dropped, or the release date is undetermined, is None. | | getOptionalRelease(self) | Return first release in which this feature was recognized. | | This is a 5-tuple, of the same form as sys.version_info. | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables | | __weakref__ | list of weak references to the object
click.argument
Python Library Documentation: function argument in module click.decorators
argument(*param_decls: 'str', cls: 'type[Argument] | None' = None, **attrs: 't.Any') -> 't.Callable[[FC], FC]'
Attaches an argument to the command. All positional arguments are
passed as parameter declarations to :class:`Argument`; all keyword
arguments are forwarded unchanged (except ``cls``).
This is equivalent to creating an :class:`Argument` instance manually
and attaching it to the :attr:`Command.params` list.
For the default argument class, refer to :class:`Argument` and
:class:`Parameter` for descriptions of parameters.
:param cls: the argument class to instantiate. This defaults to
:class:`Argument`.
:param param_decls: Passed as positional arguments to the constructor of
``cls``.
:param attrs: Passed as keyword arguments to the constructor of ``cls``.
click.clear
Python Library Documentation: function clear in module click.termui
clear() -> 'None'
Clears the terminal screen. This will have the effect of clearing
the whole visible space of the terminal and moving the cursor to the
top left. This does not do anything if not connected to a terminal.
.. versionadded:: 2.0
click.command
Python Library Documentation: function command in module click.decorators
command(name: 'str | _AnyCallable | None' = None, cls: 'type[CmdType] | None' = None, **attrs: 't.Any') -> 'Command | t.Callable[[_AnyCallable], Command | CmdType]'
Creates a new :class:`Command` and uses the decorated function as
callback. This will also automatically attach all decorated
:func:`option`\s and :func:`argument`\s as parameters to the command.
The name of the command defaults to the name of the function, converted to
lowercase, with underscores ``_`` replaced by dashes ``-``, and the suffixes
``_command``, ``_cmd``, ``_group``, and ``_grp`` are removed. For example,
``init_data_command`` becomes ``init-data``.
All keyword arguments are forwarded to the underlying command class.
For the ``params`` argument, any decorated params are appended to
the end of the list.
Once decorated the function turns into a :class:`Command` instance
that can be invoked as a command line utility or be attached to a
command :class:`Group`.
:param name: The name of the command. Defaults to modifying the function's
name as described above.
:param cls: The command class to create. Defaults to :class:`Command`.
.. versionchanged:: 8.2
The suffixes ``_command``, ``_cmd``, ``_group``, and ``_grp`` are
removed when generating the name.
.. versionchanged:: 8.1
This decorator can be applied without parentheses.
.. versionchanged:: 8.1
The ``params`` argument can be used. Decorated params are
appended to the end of the list.
click.confirm
Python Library Documentation: function confirm in module click.termui
confirm(text: 'str', default: 'bool | None' = False, abort: 'bool' = False, prompt_suffix: 'str' = ': ', show_default: 'bool' = True, err: 'bool' = False) -> 'bool'
Prompts for confirmation (yes/no question).
If the user aborts the input by sending a interrupt signal this
function will catch it and raise a :exc:`Abort` exception.
:param text: the question to ask.
:param default: The default value to use when no input is given. If
``None``, repeat until input is given.
:param abort: if this is set to `True` a negative answer aborts the
exception by raising :exc:`Abort`.
:param prompt_suffix: a suffix that should be added to the prompt.
:param show_default: shows or hides the default value in the prompt.
:param err: if set to true the file defaults to ``stderr`` instead of
``stdout``, the same as with echo.
.. versionchanged:: 8.3.1
A space is no longer appended to the prompt.
.. versionchanged:: 8.0
Repeat until input is given if ``default`` is ``None``.
.. versionadded:: 4.0
Added the ``err`` parameter.
click.confirmation_option
Python Library Documentation: function confirmation_option in module click.decorators
confirmation_option(*param_decls: 'str', **kwargs: 't.Any') -> 't.Callable[[FC], FC]'
Add a ``--yes`` option which shows a prompt before continuing if
not passed. If the prompt is declined, the program will exit.
:param param_decls: One or more option names. Defaults to the single
value ``"--yes"``.
:param kwargs: Extra arguments are passed to :func:`option`.
click.core
Python Library Documentation: module click.core in click
NAME
click.core
CLASSES
abc.ABC(builtins.object)
Parameter
Argument
Option
builtins.object
Command
Group
CommandCollection
Context
enum.IntEnum(builtins.int, enum.ReprEnum)
ParameterSource
class Argument(Parameter)
| Argument(param_decls: 'cabc.Sequence[str]', required: 'bool | None' = None, **attrs: 't.Any') -> 'None'
|
| Arguments are positional parameters to a command. They generally
| provide fewer features than options but can have infinite ``nargs``
| and are required by default.
|
| All parameters are passed onwards to the constructor of :class:`Parameter`.
|
| Method resolution order:
| Argument
| Parameter
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, param_decls: 'cabc.Sequence[str]', required: 'bool | None' = None, **attrs: 't.Any') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| add_to_parser(self, parser: '_OptionParser', ctx: 'Context') -> 'None'
|
| get_error_hint(self, ctx: 'Context | None') -> 'str'
| Get a stringified version of the param for use in error messages to
| indicate which param caused the error.
|
| .. versionchanged:: 8.4.0
| ``ctx`` can be ``None``.
|
| get_usage_pieces(self, ctx: 'Context') -> 'list[str]'
|
| make_metavar(self, ctx: 'Context') -> 'str'
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| 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.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| param_type_name = 'argument'
|
| ----------------------------------------------------------------------
| Methods inherited from Parameter:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| consume_value(self, ctx: 'Context', opts: 'cabc.Mapping[str, t.Any]') -> 'tuple[t.Any, ParameterSource]'
| Returns the parameter value produced by the parser.
|
| If the parser did not produce a value from user input, the value is either
| sourced from the environment variable, the default map, or the parameter's
| default value. In that order of precedence.
|
| If no value is found, an internal sentinel value is returned.
|
| :meta private:
|
| get_default(self, ctx: 'Context', call: 'bool' = True) -> 't.Any | t.Callable[[], t.Any] | None'
| Get the default for the parameter. Tries
| :meth:`Context.lookup_default` first, then the local default.
|
| :param ctx: Current context.
| :param call: If the default is a callable, call it. Disable to
| return the callable instead.
|
| .. versionchanged:: 8.0.2
| Type casting is no longer performed when getting a default.
|
| .. versionchanged:: 8.0.1
| Type casting can fail in resilient parsing mode. Invalid
| defaults will not prevent showing help text.
|
| .. versionchanged:: 8.0
| Looks at ``ctx.default_map`` first.
|
| .. versionchanged:: 8.0
| Added the ``call`` parameter.
|
| get_help_record(self, ctx: 'Context') -> 'tuple[str, str] | None'
|
| handle_parse_result(self, ctx: 'Context', opts: 'cabc.Mapping[str, t.Any]', args: 'list[str]') -> 'tuple[t.Any, list[str]]'
| Process the value produced by the parser from user input.
|
| Always process the value through the Parameter's :attr:`type`, wherever it
| comes from.
|
| If the parameter is deprecated, this method warn the user about it. But only if
| the value has been explicitly set by the user (and as such, is not coming from
| a default).
|
| :meta private:
|
| process_value(self, ctx: 'Context', value: 't.Any') -> 't.Any'
| Process the value of this parameter:
|
| 1. Type cast the value using :meth:`type_cast_value`.
| 2. Check if the value is missing (see: :meth:`value_is_missing`), and raise
| :exc:`MissingParameter` if it is required.
| 3. If a :attr:`callback` is set, call it to have the value replaced by the
| result of the callback. If the value was not set, the callback receive
| ``None``. This keep the legacy behavior as it was before the introduction of
| the :attr:`UNSET` sentinel.
|
| :meta private:
|
| resolve_envvar_value(self, ctx: 'Context') -> 'str | None'
| Returns the value found in the environment variable(s) attached to this
| parameter.
|
| Environment variables values are `always returned as strings
| <https://docs.python.org/3/library/os.html#os.environ>`_.
|
| This method returns ``None`` if:
|
| - the :attr:`envvar` property is not set on the :class:`Parameter`,
| - the environment variable is not found in the environment,
| - the variable is found in the environment but its value is empty (i.e. the
| environment variable is present but has an empty string).
|
| If :attr:`envvar` is setup with multiple environment variables,
| then only the first non-empty value is returned.
|
| .. caution::
|
| The raw value extracted from the environment is not normalized and is
| returned as-is. Any normalization or reconciliation is performed later by
| the :class:`Parameter`'s :attr:`type`.
|
| :meta private:
|
| shell_complete(self, ctx: 'Context', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of completions for the incomplete value. If a
| ``shell_complete`` function was given during init, it is used.
| Otherwise, the :attr:`type`
| :meth:`~click.types.ParamType[t.Any].shell_complete` function is used.
|
| :param ctx: Invocation context for this command.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self) -> 'dict[str, t.Any]'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionchanged:: 8.3.0
| Returns ``None`` for the :attr:`default` if it was not set.
|
| .. versionadded:: 8.0
|
| type_cast_value(self, ctx: 'Context', value: 't.Any') -> 't.Any'
| Convert and validate a value against the parameter's
| :attr:`type`, :attr:`multiple`, and :attr:`nargs`.
|
| value_from_envvar(self, ctx: 'Context') -> 'str | cabc.Sequence[str] | None'
| Process the raw environment variable string for this parameter.
|
| Returns the string as-is or splits it into a sequence of strings if the
| parameter is expecting multiple values (i.e. its :attr:`nargs` property is set
| to a value other than ``1``).
|
| :meta private:
|
| value_is_missing(self, value: 't.Any') -> 'bool'
| A value is considered missing if:
|
| - it is :attr:`UNSET`,
| - or if it is an empty sequence while the parameter is suppose to have
| non-single value (i.e. :attr:`nargs` is not ``1`` or :attr:`multiple` is
| set).
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Parameter:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Command(builtins.object)
| Command(name: 'str | None', context_settings: 'cabc.MutableMapping[str, t.Any] | None' = None, callback: 't.Callable[..., t.Any] | None' = None, params: 'list[Parameter] | None' = None, help: 'str | None' = None, epilog: 'str | None' = None, short_help: 'str | None' = None, options_metavar: 'str | None' = '[OPTIONS]', add_help_option: 'bool' = True, no_args_is_help: 'bool' = False, hidden: 'bool' = False, deprecated: 'bool | str' = False) -> 'None'
|
| Commands are the basic building block of command line interfaces in
| Click. A basic command handles command line parsing and might dispatch
| more parsing to commands nested below it.
|
| :param name: the name of the command to use unless a group overrides it.
| :param context_settings: an optional dictionary with defaults that are
| passed to the context object.
| :param callback: the callback to invoke. This is optional.
| :param params: the parameters to register with this command. This can
| be either :class:`Option` or :class:`Argument` objects.
| :param help: the help string to use for this command.
| :param epilog: like the help string but it's printed at the end of the
| help page after everything else.
| :param short_help: the short help to use for this command. This is
| shown on the command listing of the parent command.
| :param add_help_option: by default each command registers a ``--help``
| option. This can be disabled by this parameter.
| :param no_args_is_help: this controls what happens if no arguments are
| provided. This option is disabled by default.
| If enabled this will add ``--help`` as argument
| if no arguments are passed
| :param hidden: hide this command from help outputs.
| :param deprecated: If ``True`` or non-empty string, issues a message
| indicating that the command is deprecated and highlights
| its deprecation in --help. The message can be customized
| by using a string as the value.
|
| .. versionchanged:: 8.2
| This is the base class for all commands, not ``BaseCommand``.
| ``deprecated`` can be set to a string as well to customize the
| deprecation message.
|
| .. versionchanged:: 8.1
| ``help``, ``epilog``, and ``short_help`` are stored unprocessed,
| all formatting is done when outputting help text, not at init,
| and is done even if not using the ``@command`` decorator.
|
| .. versionchanged:: 8.0
| Added a ``repr`` showing the command name.
|
| .. versionchanged:: 7.1
| Added the ``no_args_is_help`` parameter.
|
| .. versionchanged:: 2.0
| Added the ``context_settings`` parameter.
|
| Methods defined here:
|
| __call__(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Any'
| Alias for :meth:`main`.
|
| __init__(self, name: 'str | None', context_settings: 'cabc.MutableMapping[str, t.Any] | None' = None, callback: 't.Callable[..., t.Any] | None' = None, params: 'list[Parameter] | None' = None, help: 'str | None' = None, epilog: 'str | None' = None, short_help: 'str | None' = None, options_metavar: 'str | None' = '[OPTIONS]', add_help_option: 'bool' = True, no_args_is_help: 'bool' = False, hidden: 'bool' = False, deprecated: 'bool | str' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| collect_usage_pieces(self, ctx: 'Context') -> 'list[str]'
| Returns all the pieces that go into the usage line and returns
| it as a list of strings.
|
| format_epilog(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the epilog into the formatter if it exists.
|
| format_help(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the help into the formatter if it exists.
|
| This is a low-level method called by :meth:`get_help`.
|
| This calls the following methods:
|
| - :meth:`format_usage`
| - :meth:`format_help_text`
| - :meth:`format_options`
| - :meth:`format_epilog`
|
| format_help_text(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the help text to the formatter if it exists.
|
| format_options(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes all the options into the formatter if they exist.
|
| format_usage(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the usage line into the formatter.
|
| This is a low-level method called by :meth:`get_usage`.
|
| get_help(self, ctx: 'Context') -> 'str'
| Formats the help into a string and returns it.
|
| Calls :meth:`format_help` internally.
|
| get_help_option(self, ctx: 'Context') -> 'Option | None'
| Returns the help option object.
|
| Skipped if :attr:`add_help_option` is ``False``.
|
| .. versionchanged:: 8.1.8
| The help option is now cached to avoid creating it multiple times.
|
| get_help_option_names(self, ctx: 'Context') -> 'list[str]'
| Returns the names for the help option.
|
| get_params(self, ctx: 'Context') -> 'list[Parameter]'
|
| get_short_help_str(self, limit: 'int' = 45) -> 'str'
| Gets short help for the command or makes it by shortening the
| long help string.
|
| get_usage(self, ctx: 'Context') -> 'str'
| Formats the usage line into a string and returns it.
|
| Calls :meth:`format_usage` internally.
|
| invoke(self, ctx: 'Context') -> 't.Any'
| Given a context, this invokes the attached callback (if it exists)
| in the right way.
|
| main(self, args: 'cabc.Sequence[str] | None' = None, prog_name: 'str | None' = None, complete_var: 'str | None' = None, standalone_mode: 'bool' = True, windows_expand_args: 'bool' = True, **extra: 't.Any') -> 't.Any'
| This is the way to invoke a script with all the bells and
| whistles as a command line application. This will always terminate
| the application after a call. If this is not wanted, ``SystemExit``
| needs to be caught.
|
| This method is also available by directly calling the instance of
| a :class:`Command`.
|
| :param args: the arguments that should be used for parsing. If not
| provided, ``sys.argv[1:]`` is used.
| :param prog_name: the program name that should be used. By default
| the program name is constructed by taking the file
| name from ``sys.argv[0]``.
| :param complete_var: the environment variable that controls the
| bash completion support. The default is
| ``"_<prog_name>_COMPLETE"`` with prog_name in
| uppercase.
| :param standalone_mode: the default behavior is to invoke the script
| in standalone mode. Click will then
| handle exceptions and convert them into
| error messages and the function will never
| return but shut down the interpreter. If
| this is set to `False` they will be
| propagated to the caller and the return
| value of this function is the return value
| of :meth:`invoke`.
| :param windows_expand_args: Expand glob patterns, user dir, and
| env vars in command line args on Windows.
| :param extra: extra keyword arguments are forwarded to the context
| constructor. See :class:`Context` for more information.
|
| .. versionchanged:: 8.0.1
| Added the ``windows_expand_args`` parameter to allow
| disabling command line arg expansion on Windows.
|
| .. versionchanged:: 8.0
| When taking arguments from ``sys.argv`` on Windows, glob
| patterns, user dir, and env vars are expanded.
|
| .. versionchanged:: 3.0
| Added the ``standalone_mode`` parameter.
|
| make_context(self, info_name: 'str | None', args: 'list[str]', parent: 'Context | None' = None, **extra: 't.Any') -> 'Context'
| This function when given an info name and arguments will kick
| off the parsing and create a new :class:`Context`. It does not
| invoke the actual command callback though.
|
| To quickly customize the context class used without overriding
| this method, set the :attr:`context_class` attribute.
|
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it's usually
| the name of the script, for commands below it's
| the name of the command.
| :param args: the arguments to parse as list of strings.
| :param parent: the parent context if available.
| :param extra: extra keyword arguments forwarded to the context
| constructor.
|
| .. versionchanged:: 8.0
| Added the :attr:`context_class` attribute.
|
| make_parser(self, ctx: 'Context') -> '_OptionParser'
| Creates the underlying option parser for this command.
|
| parse_args(self, ctx: 'Context', args: 'list[str]') -> 'list[str]'
|
| shell_complete(self, ctx: 'Context', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of completions for the incomplete value. Looks
| at the names of options and chained multi-commands.
|
| Any command could be part of a chained multi-command, so sibling
| commands are valid at any point during command completion.
|
| :param ctx: Invocation context for this command.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self, ctx: 'Context') -> 'dict[str, t.Any]'
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_help_option': 'Option | None', 'add_help_option':...
|
| allow_extra_args = False
|
| allow_interspersed_args = True
|
| context_class = <class 'click.core.Context'>
| The context is a special internal object that holds state relevant
| for the script execution at every single level. It's normally invisible
| to commands unless they opt-in to getting access to it.
|
| The context is useful as it can pass internal objects around and can
| control special execution features such as reading data from
| environment variables.
|
| A context can be used as context manager in which case it will call
| :meth:`close` on teardown.
|
| :param command: the command class for this context.
| :param parent: the parent context.
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it is usually
| the name of the script, for commands below that it's
| the name of the script.
| :param obj: an arbitrary object of user data.
| :param auto_envvar_prefix: the prefix to use for automatic environment
| variables. If this is `None` then reading
| from environment variables is disabled. This
| does not affect manually set environment
| variables which are always read.
| :param default_map: a dictionary (like object) with default values
| for parameters.
| :param terminal_width: the width of the terminal. The default is
| inherit from parent context. If no context
| defines the terminal width then auto
| detection will be applied.
| :param max_content_width: the maximum width for content rendered by
| Click (this currently only affects help
| pages). This defaults to 80 characters if
| not overridden. In other words: even if the
| terminal is larger than that, Click will not
| format things wider than 80 characters by
| default. In addition to that, formatters might
| add some safety mapping on the right.
| :param resilient_parsing: if this flag is enabled then Click will
| parse without any interactivity or callback
| invocation. Default values will also be
| ignored. This is useful for implementing
| things such as completion support.
| :param allow_extra_args: if this is set to `True` then extra arguments
| at the end will not raise an error and will be
| kept on the context. The default is to inherit
| from the command.
| :param allow_interspersed_args: if this is set to `False` then options
| and arguments cannot be mixed. The
| default is to inherit from the command.
| :param ignore_unknown_options: instructs click to ignore options it does
| not know and keeps them for later
| processing.
| :param help_option_names: optionally a list of strings that define how
| the default help parameter is named. The
| default is ``['--help']``.
| :param token_normalize_func: an optional function that is used to
| normalize tokens (options, choices,
| etc.). This for instance can be used to
| implement case insensitive behavior.
| :param color: controls if the terminal supports ANSI colors or not. The
| default is autodetection. This is only needed if ANSI
| codes are used in texts that Click prints which is by
| default not the case. This for instance would affect
| help output.
| :param show_default: Show the default value for commands. If this
| value is not set, it defaults to the value from the parent
| context. ``Command.show_default`` overrides this default for the
| specific command.
|
| .. versionchanged:: 8.2
| The ``protected_args`` attribute is deprecated and will be removed in
| Click 9.0. ``args`` will contain remaining unparsed tokens.
|
| .. versionchanged:: 8.1
| The ``show_default`` parameter is overridden by
| ``Command.show_default``, instead of the other way around.
|
| .. versionchanged:: 8.0
| The ``show_default`` parameter defaults to the value from the
| parent context.
|
| .. versionchanged:: 7.1
| Added the ``show_default`` parameter.
|
| .. versionchanged:: 4.0
| Added the ``color``, ``ignore_unknown_options``, and
| ``max_content_width`` parameters.
|
| .. versionchanged:: 3.0
| Added the ``allow_extra_args`` and ``allow_interspersed_args``
| parameters.
|
| .. versionchanged:: 2.0
| Added the ``resilient_parsing``, ``help_option_names``, and
| ``token_normalize_func`` parameters.
|
|
| ignore_unknown_options = False
class CommandCollection(Group)
| CommandCollection(name: 'str | None' = None, sources: 'list[Group] | None' = None, **kwargs: 't.Any') -> 'None'
|
| A :class:`Group` that looks up subcommands on other groups. If a command
| is not found on this group, each registered source is checked in order.
| Parameters on a source are not added to this group, and a source's callback
| is not invoked when invoking its commands. In other words, this "flattens"
| commands in many groups into this one group.
|
| :param name: The name of the group command.
| :param sources: A list of :class:`Group` objects to look up commands from.
| :param kwargs: Other arguments passed to :class:`Group`.
|
| .. versionchanged:: 8.2
| This is a subclass of ``Group``. Commands are looked up first on this
| group, then each of its sources.
|
| Method resolution order:
| CommandCollection
| Group
| Command
| builtins.object
|
| Methods defined here:
|
| __init__(self, name: 'str | None' = None, sources: 'list[Group] | None' = None, **kwargs: 't.Any') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| add_source(self, group: 'Group') -> 'None'
| Add a group as a source of commands.
|
| get_command(self, ctx: 'Context', cmd_name: 'str') -> 'Command | None'
| Given a context and a command name, this returns a :class:`Command`
| object if it exists or returns ``None``.
|
| list_commands(self, ctx: 'Context') -> 'list[str]'
| Returns a list of subcommand names in the order they should appear.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'sources': 'list[Group]'}
|
| ----------------------------------------------------------------------
| Methods inherited from Group:
|
| add_command(self, cmd: 'Command', name: 'str | None' = None) -> 'None'
| Registers another :class:`Command` with this group. If the name
| is not provided, the name of the command is used.
|
| collect_usage_pieces(self, ctx: 'Context') -> 'list[str]'
| Returns all the pieces that go into the usage line and returns
| it as a list of strings.
|
| command(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Callable[[t.Callable[..., t.Any]], Command] | Command'
| A shortcut decorator for declaring and attaching a command to
| the group. This takes the same arguments as :func:`command` and
| immediately registers the created command with this group by
| calling :meth:`add_command`.
|
| To customize the command class used, set the
| :attr:`command_class` attribute.
|
| .. versionchanged:: 8.1
| This decorator can be applied without parentheses.
|
| .. versionchanged:: 8.0
| Added the :attr:`command_class` attribute.
|
| format_commands(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Extra format methods for multi methods that adds all the commands
| after the options.
|
| format_options(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes all the options into the formatter if they exist.
|
| group(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Callable[[t.Callable[..., t.Any]], Group] | Group'
| A shortcut decorator for declaring and attaching a group to
| the group. This takes the same arguments as :func:`group` and
| immediately registers the created group with this group by
| calling :meth:`add_command`.
|
| To customize the group class used, set the :attr:`group_class`
| attribute.
|
| .. versionchanged:: 8.1
| This decorator can be applied without parentheses.
|
| .. versionchanged:: 8.0
| Added the :attr:`group_class` attribute.
|
| invoke(self, ctx: 'Context') -> 't.Any'
| Given a context, this invokes the attached callback (if it exists)
| in the right way.
|
| parse_args(self, ctx: 'Context', args: 'list[str]') -> 'list[str]'
|
| resolve_command(self, ctx: 'Context', args: 'list[str]') -> 'tuple[str | None, Command | None, list[str]]'
|
| result_callback(self, replace: 'bool' = False) -> 't.Callable[[F], F]'
| Adds a result callback to the command. By default if a
| result callback is already registered this will chain them but
| this can be disabled with the `replace` parameter. The result
| callback is invoked with the return value of the subcommand
| (or the list of return values from all subcommands if chaining
| is enabled) as well as the parameters as they would be passed
| to the main callback.
|
| Example::
|
| @click.group()
| @click.option('-i', '--input', default=23)
| def cli(input):
| return 42
|
| @cli.result_callback()
| def process_result(result, input):
| return result + input
|
| :param replace: if set to `True` an already existing result
| callback will be removed.
|
| .. versionchanged:: 8.0
| Renamed from ``resultcallback``.
|
| .. versionadded:: 3.0
|
| shell_complete(self, ctx: 'Context', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of completions for the incomplete value. Looks
| at the names of options, subcommands, and chained
| multi-commands.
|
| :param ctx: Invocation context for this command.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self, ctx: 'Context') -> 'dict[str, t.Any]'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Group:
|
| allow_extra_args = True
|
| allow_interspersed_args = False
|
| command_class = None
|
| group_class = None
|
| ----------------------------------------------------------------------
| Methods inherited from Command:
|
| __call__(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Any'
| Alias for :meth:`main`.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| format_epilog(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the epilog into the formatter if it exists.
|
| format_help(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the help into the formatter if it exists.
|
| This is a low-level method called by :meth:`get_help`.
|
| This calls the following methods:
|
| - :meth:`format_usage`
| - :meth:`format_help_text`
| - :meth:`format_options`
| - :meth:`format_epilog`
|
| format_help_text(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the help text to the formatter if it exists.
|
| format_usage(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the usage line into the formatter.
|
| This is a low-level method called by :meth:`get_usage`.
|
| get_help(self, ctx: 'Context') -> 'str'
| Formats the help into a string and returns it.
|
| Calls :meth:`format_help` internally.
|
| get_help_option(self, ctx: 'Context') -> 'Option | None'
| Returns the help option object.
|
| Skipped if :attr:`add_help_option` is ``False``.
|
| .. versionchanged:: 8.1.8
| The help option is now cached to avoid creating it multiple times.
|
| get_help_option_names(self, ctx: 'Context') -> 'list[str]'
| Returns the names for the help option.
|
| get_params(self, ctx: 'Context') -> 'list[Parameter]'
|
| get_short_help_str(self, limit: 'int' = 45) -> 'str'
| Gets short help for the command or makes it by shortening the
| long help string.
|
| get_usage(self, ctx: 'Context') -> 'str'
| Formats the usage line into a string and returns it.
|
| Calls :meth:`format_usage` internally.
|
| main(self, args: 'cabc.Sequence[str] | None' = None, prog_name: 'str | None' = None, complete_var: 'str | None' = None, standalone_mode: 'bool' = True, windows_expand_args: 'bool' = True, **extra: 't.Any') -> 't.Any'
| This is the way to invoke a script with all the bells and
| whistles as a command line application. This will always terminate
| the application after a call. If this is not wanted, ``SystemExit``
| needs to be caught.
|
| This method is also available by directly calling the instance of
| a :class:`Command`.
|
| :param args: the arguments that should be used for parsing. If not
| provided, ``sys.argv[1:]`` is used.
| :param prog_name: the program name that should be used. By default
| the program name is constructed by taking the file
| name from ``sys.argv[0]``.
| :param complete_var: the environment variable that controls the
| bash completion support. The default is
| ``"_<prog_name>_COMPLETE"`` with prog_name in
| uppercase.
| :param standalone_mode: the default behavior is to invoke the script
| in standalone mode. Click will then
| handle exceptions and convert them into
| error messages and the function will never
| return but shut down the interpreter. If
| this is set to `False` they will be
| propagated to the caller and the return
| value of this function is the return value
| of :meth:`invoke`.
| :param windows_expand_args: Expand glob patterns, user dir, and
| env vars in command line args on Windows.
| :param extra: extra keyword arguments are forwarded to the context
| constructor. See :class:`Context` for more information.
|
| .. versionchanged:: 8.0.1
| Added the ``windows_expand_args`` parameter to allow
| disabling command line arg expansion on Windows.
|
| .. versionchanged:: 8.0
| When taking arguments from ``sys.argv`` on Windows, glob
| patterns, user dir, and env vars are expanded.
|
| .. versionchanged:: 3.0
| Added the ``standalone_mode`` parameter.
|
| make_context(self, info_name: 'str | None', args: 'list[str]', parent: 'Context | None' = None, **extra: 't.Any') -> 'Context'
| This function when given an info name and arguments will kick
| off the parsing and create a new :class:`Context`. It does not
| invoke the actual command callback though.
|
| To quickly customize the context class used without overriding
| this method, set the :attr:`context_class` attribute.
|
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it's usually
| the name of the script, for commands below it's
| the name of the command.
| :param args: the arguments to parse as list of strings.
| :param parent: the parent context if available.
| :param extra: extra keyword arguments forwarded to the context
| constructor.
|
| .. versionchanged:: 8.0
| Added the :attr:`context_class` attribute.
|
| make_parser(self, ctx: 'Context') -> '_OptionParser'
| Creates the underlying option parser for this command.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Command:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Command:
|
| context_class = <class 'click.core.Context'>
| The context is a special internal object that holds state relevant
| for the script execution at every single level. It's normally invisible
| to commands unless they opt-in to getting access to it.
|
| The context is useful as it can pass internal objects around and can
| control special execution features such as reading data from
| environment variables.
|
| A context can be used as context manager in which case it will call
| :meth:`close` on teardown.
|
| :param command: the command class for this context.
| :param parent: the parent context.
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it is usually
| the name of the script, for commands below that it's
| the name of the script.
| :param obj: an arbitrary object of user data.
| :param auto_envvar_prefix: the prefix to use for automatic environment
| variables. If this is `None` then reading
| from environment variables is disabled. This
| does not affect manually set environment
| variables which are always read.
| :param default_map: a dictionary (like object) with default values
| for parameters.
| :param terminal_width: the width of the terminal. The default is
| inherit from parent context. If no context
| defines the terminal width then auto
| detection will be applied.
| :param max_content_width: the maximum width for content rendered by
| Click (this currently only affects help
| pages). This defaults to 80 characters if
| not overridden. In other words: even if the
| terminal is larger than that, Click will not
| format things wider than 80 characters by
| default. In addition to that, formatters might
| add some safety mapping on the right.
| :param resilient_parsing: if this flag is enabled then Click will
| parse without any interactivity or callback
| invocation. Default values will also be
| ignored. This is useful for implementing
| things such as completion support.
| :param allow_extra_args: if this is set to `True` then extra arguments
| at the end will not raise an error and will be
| kept on the context. The default is to inherit
| from the command.
| :param allow_interspersed_args: if this is set to `False` then options
| and arguments cannot be mixed. The
| default is to inherit from the command.
| :param ignore_unknown_options: instructs click to ignore options it does
| not know and keeps them for later
| processing.
| :param help_option_names: optionally a list of strings that define how
| the default help parameter is named. The
| default is ``['--help']``.
| :param token_normalize_func: an optional function that is used to
| normalize tokens (options, choices,
| etc.). This for instance can be used to
| implement case insensitive behavior.
| :param color: controls if the terminal supports ANSI colors or not. The
| default is autodetection. This is only needed if ANSI
| codes are used in texts that Click prints which is by
| default not the case. This for instance would affect
| help output.
| :param show_default: Show the default value for commands. If this
| value is not set, it defaults to the value from the parent
| context. ``Command.show_default`` overrides this default for the
| specific command.
|
| .. versionchanged:: 8.2
| The ``protected_args`` attribute is deprecated and will be removed in
| Click 9.0. ``args`` will contain remaining unparsed tokens.
|
| .. versionchanged:: 8.1
| The ``show_default`` parameter is overridden by
| ``Command.show_default``, instead of the other way around.
|
| .. versionchanged:: 8.0
| The ``show_default`` parameter defaults to the value from the
| parent context.
|
| .. versionchanged:: 7.1
| Added the ``show_default`` parameter.
|
| .. versionchanged:: 4.0
| Added the ``color``, ``ignore_unknown_options``, and
| ``max_content_width`` parameters.
|
| .. versionchanged:: 3.0
| Added the ``allow_extra_args`` and ``allow_interspersed_args``
| parameters.
|
| .. versionchanged:: 2.0
| Added the ``resilient_parsing``, ``help_option_names``, and
| ``token_normalize_func`` parameters.
|
|
| ignore_unknown_options = False
class Context(builtins.object)
| Context(command: 'Command', parent: 'Context | None' = None, info_name: 'str | None' = None, obj: 't.Any | None' = None, auto_envvar_prefix: 'str | None' = None, default_map: 'cabc.MutableMapping[str, t.Any] | None' = None, terminal_width: 'int | None' = None, max_content_width: 'int | None' = None, resilient_parsing: 'bool' = False, allow_extra_args: 'bool | None' = None, allow_interspersed_args: 'bool | None' = None, ignore_unknown_options: 'bool | None' = None, help_option_names: 'list[str] | None' = None, token_normalize_func: 't.Callable[[str], str] | None' = None, color: 'bool | None' = None, show_default: 'bool | None' = None) -> 'None'
|
| The context is a special internal object that holds state relevant
| for the script execution at every single level. It's normally invisible
| to commands unless they opt-in to getting access to it.
|
| The context is useful as it can pass internal objects around and can
| control special execution features such as reading data from
| environment variables.
|
| A context can be used as context manager in which case it will call
| :meth:`close` on teardown.
|
| :param command: the command class for this context.
| :param parent: the parent context.
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it is usually
| the name of the script, for commands below that it's
| the name of the script.
| :param obj: an arbitrary object of user data.
| :param auto_envvar_prefix: the prefix to use for automatic environment
| variables. If this is `None` then reading
| from environment variables is disabled. This
| does not affect manually set environment
| variables which are always read.
| :param default_map: a dictionary (like object) with default values
| for parameters.
| :param terminal_width: the width of the terminal. The default is
| inherit from parent context. If no context
| defines the terminal width then auto
| detection will be applied.
| :param max_content_width: the maximum width for content rendered by
| Click (this currently only affects help
| pages). This defaults to 80 characters if
| not overridden. In other words: even if the
| terminal is larger than that, Click will not
| format things wider than 80 characters by
| default. In addition to that, formatters might
| add some safety mapping on the right.
| :param resilient_parsing: if this flag is enabled then Click will
| parse without any interactivity or callback
| invocation. Default values will also be
| ignored. This is useful for implementing
| things such as completion support.
| :param allow_extra_args: if this is set to `True` then extra arguments
| at the end will not raise an error and will be
| kept on the context. The default is to inherit
| from the command.
| :param allow_interspersed_args: if this is set to `False` then options
| and arguments cannot be mixed. The
| default is to inherit from the command.
| :param ignore_unknown_options: instructs click to ignore options it does
| not know and keeps them for later
| processing.
| :param help_option_names: optionally a list of strings that define how
| the default help parameter is named. The
| default is ``['--help']``.
| :param token_normalize_func: an optional function that is used to
| normalize tokens (options, choices,
| etc.). This for instance can be used to
| implement case insensitive behavior.
| :param color: controls if the terminal supports ANSI colors or not. The
| default is autodetection. This is only needed if ANSI
| codes are used in texts that Click prints which is by
| default not the case. This for instance would affect
| help output.
| :param show_default: Show the default value for commands. If this
| value is not set, it defaults to the value from the parent
| context. ``Command.show_default`` overrides this default for the
| specific command.
|
| .. versionchanged:: 8.2
| The ``protected_args`` attribute is deprecated and will be removed in
| Click 9.0. ``args`` will contain remaining unparsed tokens.
|
| .. versionchanged:: 8.1
| The ``show_default`` parameter is overridden by
| ``Command.show_default``, instead of the other way around.
|
| .. versionchanged:: 8.0
| The ``show_default`` parameter defaults to the value from the
| parent context.
|
| .. versionchanged:: 7.1
| Added the ``show_default`` parameter.
|
| .. versionchanged:: 4.0
| Added the ``color``, ``ignore_unknown_options``, and
| ``max_content_width`` parameters.
|
| .. versionchanged:: 3.0
| Added the ``allow_extra_args`` and ``allow_interspersed_args``
| parameters.
|
| .. versionchanged:: 2.0
| Added the ``resilient_parsing``, ``help_option_names``, and
| ``token_normalize_func`` parameters.
|
| Methods defined here:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, exc_type: 'type[BaseException] | None', exc_value: 'BaseException | None', tb: 'TracebackType | None') -> 'bool | None'
|
| __init__(self, command: 'Command', parent: 'Context | None' = None, info_name: 'str | None' = None, obj: 't.Any | None' = None, auto_envvar_prefix: 'str | None' = None, default_map: 'cabc.MutableMapping[str, t.Any] | None' = None, terminal_width: 'int | None' = None, max_content_width: 'int | None' = None, resilient_parsing: 'bool' = False, allow_extra_args: 'bool | None' = None, allow_interspersed_args: 'bool | None' = None, ignore_unknown_options: 'bool | None' = None, help_option_names: 'list[str] | None' = None, token_normalize_func: 't.Callable[[str], str] | None' = None, color: 'bool | None' = None, show_default: 'bool | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| abort(self) -> 't.NoReturn'
| Aborts the script.
|
| call_on_close(self, f: 't.Callable[..., t.Any]') -> 't.Callable[..., t.Any]'
| Register a function to be called when the context tears down.
|
| This can be used to close resources opened during the script
| execution. Resources that support Python's context manager
| protocol which would be used in a ``with`` statement should be
| registered with :meth:`with_resource` instead.
|
| :param f: The function to execute on teardown.
|
| close(self) -> 'None'
| Invoke all close callbacks registered with
| :meth:`call_on_close`, and exit all context managers entered
| with :meth:`with_resource`.
|
| ensure_object(self, object_type: 'type[V]') -> 'V'
| Like :meth:`find_object` but sets the innermost object to a
| new instance of `object_type` if it does not exist.
|
| exit(self, code: 'int' = 0) -> 't.NoReturn'
| Exits the application with a given exit code.
|
| .. versionchanged:: 8.2
| Callbacks and context managers registered with :meth:`call_on_close`
| and :meth:`with_resource` are closed before exiting.
|
| fail(self, message: 'str') -> 't.NoReturn'
| Aborts the execution of the program with a specific error
| message.
|
| :param message: the error message to fail with.
|
| find_object(self, object_type: 'type[V]') -> 'V | None'
| Finds the closest object of a given type.
|
| find_root(self) -> 'Context'
| Finds the outermost context.
|
| forward(self, cmd: 'Command', /, *args: 't.Any', **kwargs: 't.Any') -> 't.Any'
| Similar to :meth:`invoke` but fills in default keyword
| arguments from the current context if the other command expects
| it. This cannot invoke callbacks directly, only other commands.
|
| .. versionchanged:: 8.0
| All ``kwargs`` are tracked in :attr:`params` so they will be
| passed if ``forward`` is called at multiple levels.
|
| get_help(self) -> 'str'
| Helper method to get formatted help page for the current
| context and command.
|
| get_parameter_source(self, name: 'str') -> 'ParameterSource | None'
| Get the source of a parameter. This indicates the location
| from which the value of the parameter was obtained.
|
| This can be useful for determining when a user specified a value
| on the command line that is the same as the default value. It
| will be :attr:`~click.core.ParameterSource.DEFAULT` only if the
| value was actually taken from the default.
|
| :param name: The name of the parameter.
| :rtype: ParameterSource
|
| .. versionchanged:: 8.0
| Returns ``None`` if the parameter was not provided from any
| source.
|
| get_usage(self) -> 'str'
| Helper method to get formatted usage string for the current
| context and command.
|
| invoke(self, callback: 'Command | t.Callable[..., V]', /, *args: 't.Any', **kwargs: 't.Any') -> 't.Any | V'
| Invokes a command callback in exactly the way it expects. There
| are two ways to invoke this method:
|
| 1. the first argument can be a callback and all other arguments and
| keyword arguments are forwarded directly to the function.
| 2. the first argument is a click command object. In that case all
| arguments are forwarded as well but proper click parameters
| (options and click arguments) must be keyword arguments and Click
| will fill in defaults.
|
| .. versionchanged:: 8.0
| All ``kwargs`` are tracked in :attr:`params` so they will be
| passed if :meth:`forward` is called at multiple levels.
|
| .. versionchanged:: 3.2
| A new context is created, and missing arguments use default values.
|
| lookup_default(self, name: 'str', call: 'bool' = True) -> 't.Any | None'
| Get the default for a parameter from :attr:`default_map`.
|
| :param name: Name of the parameter.
| :param call: If the default is a callable, call it. Disable to
| return the callable instead.
|
| .. versionchanged:: 8.0
| Added the ``call`` parameter.
|
| make_formatter(self) -> 'HelpFormatter'
| Creates the :class:`~click.HelpFormatter` for the help and
| usage output.
|
| To quickly customize the formatter class used without overriding
| this method, set the :attr:`formatter_class` attribute.
|
| .. versionchanged:: 8.0
| Added the :attr:`formatter_class` attribute.
|
| scope(self, cleanup: 'bool' = True) -> 'cabc.Generator[Context]'
| This helper method can be used with the context object to promote
| it to the current thread local (see :func:`get_current_context`).
| The default behavior of this is to invoke the cleanup functions which
| can be disabled by setting `cleanup` to `False`. The cleanup
| functions are typically used for things such as closing file handles.
|
| If the cleanup is intended the context object can also be directly
| used as a context manager.
|
| Example usage::
|
| with ctx.scope():
| assert get_current_context() is ctx
|
| This is equivalent::
|
| with ctx:
| assert get_current_context() is ctx
|
| .. versionadded:: 5.0
|
| :param cleanup: controls if the cleanup functions should be run or
| not. The default is to run these functions. In
| some situations the context only wants to be
| temporarily pushed in which case this can be disabled.
| Nested pushes automatically defer the cleanup.
|
| set_parameter_source(self, name: 'str', source: 'ParameterSource') -> 'None'
| Set the source of a parameter. This indicates the location
| from which the value of the parameter was obtained.
|
| :param name: The name of the parameter.
| :param source: A member of :class:`~click.core.ParameterSource`.
|
| to_info_dict(self) -> 'dict[str, t.Any]'
| Gather information that could be useful for a tool generating
| user-facing documentation. This traverses the entire CLI
| structure.
|
| .. code-block:: python
|
| with Context(cli) as ctx:
| info = ctx.to_info_dict()
|
| .. versionadded:: 8.0
|
| with_resource(self, context_manager: 'AbstractContextManager[V]') -> 'V'
| Register a resource as if it were used in a ``with``
| statement. The resource will be cleaned up when the context is
| popped.
|
| Uses :meth:`contextlib.ExitStack.enter_context`. It calls the
| resource's ``__enter__()`` method and returns the result. When
| the context is popped, it closes the stack, which calls the
| resource's ``__exit__()`` method.
|
| To register a cleanup function for something that isn't a
| context manager, use :meth:`call_on_close`. Or use something
| from :mod:`contextlib` to turn it into a context manager first.
|
| .. code-block:: python
|
| @click.group()
| @click.option("--name")
| @click.pass_context
| def cli(ctx):
| ctx.obj = ctx.with_resource(connect_db(name))
|
| :param context_manager: The context manager to enter.
| :return: Whatever ``context_manager.__enter__()`` returns.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| command_path
| The computed command path. This is used for the ``usage``
| information on the help page. It's automatically created by
| combining the info names of the chain of contexts to the root.
|
| meta
| This is a dictionary which is shared with all the contexts
| that are nested. It exists so that click utilities can store some
| state here if they need to. It is however the responsibility of
| that code to manage this dictionary well.
|
| The keys are supposed to be unique dotted strings. For instance
| module paths are a good choice for it. What is stored in there is
| irrelevant for the operation of click. However what is important is
| that code that places data here adheres to the general semantics of
| the system.
|
| Example usage::
|
| LANG_KEY = f'{__name__}.lang'
|
| def set_language(value):
| ctx = get_current_context()
| ctx.meta[LANG_KEY] = value
|
| def get_language():
| return get_current_context().meta.get(LANG_KEY, 'en_US')
|
| .. versionadded:: 5.0
|
| protected_args
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_close_callbacks': 'list[t.Callable[[], t.Any]]', ...
|
| formatter_class = <class 'click.formatting.HelpFormatter'>
| This class helps with formatting text-based help pages. It's
| usually just needed for very special internal cases, but it's also
| exposed so that developers can write their own fancy outputs.
|
| At present, it always writes into memory.
|
| :param indent_increment: the additional increment for each level.
| :param width: the width for the text. This defaults to the terminal
| width clamped to a maximum of 78.
class Group(Command)
| Group(name: 'str | None' = None, commands: 'cabc.MutableMapping[str, Command] | cabc.Sequence[Command] | None' = None, invoke_without_command: 'bool' = False, no_args_is_help: 'bool | None' = None, subcommand_metavar: 'str | None' = None, chain: 'bool' = False, result_callback: 't.Callable[..., t.Any] | None' = None, **kwargs: 't.Any') -> 'None'
|
| A group is a command that nests other commands (or more groups).
|
| :param name: The name of the group command.
| :param commands: Map names to :class:`Command` objects. Can be a list, which
| will use :attr:`Command.name` as the keys.
| :param invoke_without_command: Invoke the group's callback even if a
| subcommand is not given.
| :param no_args_is_help: If no arguments are given, show the group's help and
| exit. Defaults to the opposite of ``invoke_without_command``.
| :param subcommand_metavar: How to represent the subcommand argument in help.
| The default will represent whether ``chain`` is set or not.
| :param chain: Allow passing more than one subcommand argument. After parsing
| a command's arguments, if any arguments remain another command will be
| matched, and so on.
| :param result_callback: A function to call after the group's and
| subcommand's callbacks. The value returned by the subcommand is passed.
| If ``chain`` is enabled, the value will be a list of values returned by
| all the commands. If ``invoke_without_command`` is enabled, the value
| will be the value returned by the group's callback, or an empty list if
| ``chain`` is enabled.
| :param kwargs: Other arguments passed to :class:`Command`.
|
| .. versionchanged:: 8.0
| The ``commands`` argument can be a list of command objects.
|
| .. versionchanged:: 8.2
| Merged with and replaces the ``MultiCommand`` base class.
|
| Method resolution order:
| Group
| Command
| builtins.object
|
| Methods defined here:
|
| __init__(self, name: 'str | None' = None, commands: 'cabc.MutableMapping[str, Command] | cabc.Sequence[Command] | None' = None, invoke_without_command: 'bool' = False, no_args_is_help: 'bool | None' = None, subcommand_metavar: 'str | None' = None, chain: 'bool' = False, result_callback: 't.Callable[..., t.Any] | None' = None, **kwargs: 't.Any') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| add_command(self, cmd: 'Command', name: 'str | None' = None) -> 'None'
| Registers another :class:`Command` with this group. If the name
| is not provided, the name of the command is used.
|
| collect_usage_pieces(self, ctx: 'Context') -> 'list[str]'
| Returns all the pieces that go into the usage line and returns
| it as a list of strings.
|
| command(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Callable[[t.Callable[..., t.Any]], Command] | Command'
| A shortcut decorator for declaring and attaching a command to
| the group. This takes the same arguments as :func:`command` and
| immediately registers the created command with this group by
| calling :meth:`add_command`.
|
| To customize the command class used, set the
| :attr:`command_class` attribute.
|
| .. versionchanged:: 8.1
| This decorator can be applied without parentheses.
|
| .. versionchanged:: 8.0
| Added the :attr:`command_class` attribute.
|
| format_commands(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Extra format methods for multi methods that adds all the commands
| after the options.
|
| format_options(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes all the options into the formatter if they exist.
|
| get_command(self, ctx: 'Context', cmd_name: 'str') -> 'Command | None'
| Given a context and a command name, this returns a :class:`Command`
| object if it exists or returns ``None``.
|
| group(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Callable[[t.Callable[..., t.Any]], Group] | Group'
| A shortcut decorator for declaring and attaching a group to
| the group. This takes the same arguments as :func:`group` and
| immediately registers the created group with this group by
| calling :meth:`add_command`.
|
| To customize the group class used, set the :attr:`group_class`
| attribute.
|
| .. versionchanged:: 8.1
| This decorator can be applied without parentheses.
|
| .. versionchanged:: 8.0
| Added the :attr:`group_class` attribute.
|
| invoke(self, ctx: 'Context') -> 't.Any'
| Given a context, this invokes the attached callback (if it exists)
| in the right way.
|
| list_commands(self, ctx: 'Context') -> 'list[str]'
| Returns a list of subcommand names in the order they should appear.
|
| parse_args(self, ctx: 'Context', args: 'list[str]') -> 'list[str]'
|
| resolve_command(self, ctx: 'Context', args: 'list[str]') -> 'tuple[str | None, Command | None, list[str]]'
|
| result_callback(self, replace: 'bool' = False) -> 't.Callable[[F], F]'
| Adds a result callback to the command. By default if a
| result callback is already registered this will chain them but
| this can be disabled with the `replace` parameter. The result
| callback is invoked with the return value of the subcommand
| (or the list of return values from all subcommands if chaining
| is enabled) as well as the parameters as they would be passed
| to the main callback.
|
| Example::
|
| @click.group()
| @click.option('-i', '--input', default=23)
| def cli(input):
| return 42
|
| @cli.result_callback()
| def process_result(result, input):
| return result + input
|
| :param replace: if set to `True` an already existing result
| callback will be removed.
|
| .. versionchanged:: 8.0
| Renamed from ``resultcallback``.
|
| .. versionadded:: 3.0
|
| shell_complete(self, ctx: 'Context', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of completions for the incomplete value. Looks
| at the names of options, subcommands, and chained
| multi-commands.
|
| :param ctx: Invocation context for this command.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self, ctx: 'Context') -> 'dict[str, t.Any]'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_result_callback': 't.Callable[..., t.Any] | None'...
|
| allow_extra_args = True
|
| allow_interspersed_args = False
|
| command_class = None
|
| group_class = None
|
| ----------------------------------------------------------------------
| Methods inherited from Command:
|
| __call__(self, *args: 't.Any', **kwargs: 't.Any') -> 't.Any'
| Alias for :meth:`main`.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| format_epilog(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the epilog into the formatter if it exists.
|
| format_help(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the help into the formatter if it exists.
|
| This is a low-level method called by :meth:`get_help`.
|
| This calls the following methods:
|
| - :meth:`format_usage`
| - :meth:`format_help_text`
| - :meth:`format_options`
| - :meth:`format_epilog`
|
| format_help_text(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the help text to the formatter if it exists.
|
| format_usage(self, ctx: 'Context', formatter: 'HelpFormatter') -> 'None'
| Writes the usage line into the formatter.
|
| This is a low-level method called by :meth:`get_usage`.
|
| get_help(self, ctx: 'Context') -> 'str'
| Formats the help into a string and returns it.
|
| Calls :meth:`format_help` internally.
|
| get_help_option(self, ctx: 'Context') -> 'Option | None'
| Returns the help option object.
|
| Skipped if :attr:`add_help_option` is ``False``.
|
| .. versionchanged:: 8.1.8
| The help option is now cached to avoid creating it multiple times.
|
| get_help_option_names(self, ctx: 'Context') -> 'list[str]'
| Returns the names for the help option.
|
| get_params(self, ctx: 'Context') -> 'list[Parameter]'
|
| get_short_help_str(self, limit: 'int' = 45) -> 'str'
| Gets short help for the command or makes it by shortening the
| long help string.
|
| get_usage(self, ctx: 'Context') -> 'str'
| Formats the usage line into a string and returns it.
|
| Calls :meth:`format_usage` internally.
|
| main(self, args: 'cabc.Sequence[str] | None' = None, prog_name: 'str | None' = None, complete_var: 'str | None' = None, standalone_mode: 'bool' = True, windows_expand_args: 'bool' = True, **extra: 't.Any') -> 't.Any'
| This is the way to invoke a script with all the bells and
| whistles as a command line application. This will always terminate
| the application after a call. If this is not wanted, ``SystemExit``
| needs to be caught.
|
| This method is also available by directly calling the instance of
| a :class:`Command`.
|
| :param args: the arguments that should be used for parsing. If not
| provided, ``sys.argv[1:]`` is used.
| :param prog_name: the program name that should be used. By default
| the program name is constructed by taking the file
| name from ``sys.argv[0]``.
| :param complete_var: the environment variable that controls the
| bash completion support. The default is
| ``"_<prog_name>_COMPLETE"`` with prog_name in
| uppercase.
| :param standalone_mode: the default behavior is to invoke the script
| in standalone mode. Click will then
| handle exceptions and convert them into
| error messages and the function will never
| return but shut down the interpreter. If
| this is set to `False` they will be
| propagated to the caller and the return
| value of this function is the return value
| of :meth:`invoke`.
| :param windows_expand_args: Expand glob patterns, user dir, and
| env vars in command line args on Windows.
| :param extra: extra keyword arguments are forwarded to the context
| constructor. See :class:`Context` for more information.
|
| .. versionchanged:: 8.0.1
| Added the ``windows_expand_args`` parameter to allow
| disabling command line arg expansion on Windows.
|
| .. versionchanged:: 8.0
| When taking arguments from ``sys.argv`` on Windows, glob
| patterns, user dir, and env vars are expanded.
|
| .. versionchanged:: 3.0
| Added the ``standalone_mode`` parameter.
|
| make_context(self, info_name: 'str | None', args: 'list[str]', parent: 'Context | None' = None, **extra: 't.Any') -> 'Context'
| This function when given an info name and arguments will kick
| off the parsing and create a new :class:`Context`. It does not
| invoke the actual command callback though.
|
| To quickly customize the context class used without overriding
| this method, set the :attr:`context_class` attribute.
|
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it's usually
| the name of the script, for commands below it's
| the name of the command.
| :param args: the arguments to parse as list of strings.
| :param parent: the parent context if available.
| :param extra: extra keyword arguments forwarded to the context
| constructor.
|
| .. versionchanged:: 8.0
| Added the :attr:`context_class` attribute.
|
| make_parser(self, ctx: 'Context') -> '_OptionParser'
| Creates the underlying option parser for this command.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Command:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Command:
|
| context_class = <class 'click.core.Context'>
| The context is a special internal object that holds state relevant
| for the script execution at every single level. It's normally invisible
| to commands unless they opt-in to getting access to it.
|
| The context is useful as it can pass internal objects around and can
| control special execution features such as reading data from
| environment variables.
|
| A context can be used as context manager in which case it will call
| :meth:`close` on teardown.
|
| :param command: the command class for this context.
| :param parent: the parent context.
| :param info_name: the info name for this invocation. Generally this
| is the most descriptive name for the script or
| command. For the toplevel script it is usually
| the name of the script, for commands below that it's
| the name of the script.
| :param obj: an arbitrary object of user data.
| :param auto_envvar_prefix: the prefix to use for automatic environment
| variables. If this is `None` then reading
| from environment variables is disabled. This
| does not affect manually set environment
| variables which are always read.
| :param default_map: a dictionary (like object) with default values
| for parameters.
| :param terminal_width: the width of the terminal. The default is
| inherit from parent context. If no context
| defines the terminal width then auto
| detection will be applied.
| :param max_content_width: the maximum width for content rendered by
| Click (this currently only affects help
| pages). This defaults to 80 characters if
| not overridden. In other words: even if the
| terminal is larger than that, Click will not
| format things wider than 80 characters by
| default. In addition to that, formatters might
| add some safety mapping on the right.
| :param resilient_parsing: if this flag is enabled then Click will
| parse without any interactivity or callback
| invocation. Default values will also be
| ignored. This is useful for implementing
| things such as completion support.
| :param allow_extra_args: if this is set to `True` then extra arguments
| at the end will not raise an error and will be
| kept on the context. The default is to inherit
| from the command.
| :param allow_interspersed_args: if this is set to `False` then options
| and arguments cannot be mixed. The
| default is to inherit from the command.
| :param ignore_unknown_options: instructs click to ignore options it does
| not know and keeps them for later
| processing.
| :param help_option_names: optionally a list of strings that define how
| the default help parameter is named. The
| default is ``['--help']``.
| :param token_normalize_func: an optional function that is used to
| normalize tokens (options, choices,
| etc.). This for instance can be used to
| implement case insensitive behavior.
| :param color: controls if the terminal supports ANSI colors or not. The
| default is autodetection. This is only needed if ANSI
| codes are used in texts that Click prints which is by
| default not the case. This for instance would affect
| help output.
| :param show_default: Show the default value for commands. If this
| value is not set, it defaults to the value from the parent
| context. ``Command.show_default`` overrides this default for the
| specific command.
|
| .. versionchanged:: 8.2
| The ``protected_args`` attribute is deprecated and will be removed in
| Click 9.0. ``args`` will contain remaining unparsed tokens.
|
| .. versionchanged:: 8.1
| The ``show_default`` parameter is overridden by
| ``Command.show_default``, instead of the other way around.
|
| .. versionchanged:: 8.0
| The ``show_default`` parameter defaults to the value from the
| parent context.
|
| .. versionchanged:: 7.1
| Added the ``show_default`` parameter.
|
| .. versionchanged:: 4.0
| Added the ``color``, ``ignore_unknown_options``, and
| ``max_content_width`` parameters.
|
| .. versionchanged:: 3.0
| Added the ``allow_extra_args`` and ``allow_interspersed_args``
| parameters.
|
| .. versionchanged:: 2.0
| Added the ``resilient_parsing``, ``help_option_names``, and
| ``token_normalize_func`` parameters.
|
|
| ignore_unknown_options = False
class Option(Parameter)
| Option(param_decls: 'cabc.Sequence[str] | None' = None, show_default: 'bool | str | None' = None, prompt: 'bool | str' = False, confirmation_prompt: 'bool | str' = False, prompt_required: 'bool' = True, hide_input: 'bool' = False, is_flag: 'bool | None' = None, flag_value: 't.Any' = Sentinel.UNSET, multiple: 'bool' = False, count: 'bool' = False, allow_from_autoenv: 'bool' = True, type: 'types.ParamType[t.Any] | t.Any | None' = None, help: 'str | None' = None, hidden: 'bool' = False, show_choices: 'bool' = True, show_envvar: 'bool' = False, deprecated: 'bool | str' = False, **attrs: 't.Any') -> 'None'
|
| Options are usually optional values on the command line and
| have some extra features that arguments don't have.
|
| All other parameters are passed onwards to the parameter constructor.
|
| :param show_default: Show the default value for this option in its
| help text. Values are not shown by default, unless
| :attr:`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``.
| :param show_envvar: Controls if an environment variable should be
| shown on the help page and error messages.
| Normally, environment variables are not shown.
| :param prompt: If set to ``True`` or a non empty string then the
| user will be prompted for input. If set to ``True`` the prompt
| will be the option name capitalized. A deprecated option cannot be
| prompted.
| :param confirmation_prompt: Prompt a second time to confirm the
| value if it was prompted for. Can be set to a string instead of
| ``True`` to customize the message.
| :param prompt_required: If set to ``False``, the user will be
| prompted for input only when the option was specified as a flag
| without a value.
| :param hide_input: If this is ``True`` then the input on the prompt
| will be hidden from the user. This is useful for password input.
| :param is_flag: forces this option to act as a flag. The default is
| auto detection.
| :param flag_value: which value should be used for this flag if it's
| enabled. This is set to a boolean automatically if
| the option string contains a slash to mark two options.
| :param multiple: if this is set to `True` then the argument is accepted
| multiple times and recorded. This is similar to ``nargs``
| in how it works but supports arbitrary number of
| arguments.
| :param count: this flag makes an option increment an integer.
| :param allow_from_autoenv: if this is enabled then the value of this
| parameter will be pulled from an environment
| variable in case a prefix is defined on the
| context.
| :param help: the help string.
| :param hidden: hide this option from help outputs.
| :param attrs: Other command arguments described in :class:`Parameter`.
|
| .. versionchanged:: 8.4.0
| Non-basic ``flag_value`` types (not ``str``, ``int``, ``float``, or
| ``bool``) are passed through unchanged instead of being stringified.
| Previously, ``type=click.UNPROCESSED`` was required to preserve them.
|
| .. versionchanged:: 8.2
| ``envvar`` used with ``flag_value`` will always use the ``flag_value``,
| previously it would use the value of the environment variable.
|
| .. versionchanged:: 8.1
| Help text indentation is cleaned here instead of only in the
| ``@option`` decorator.
|
| .. versionchanged:: 8.1
| The ``show_default`` parameter overrides
| ``Context.show_default``.
|
| .. versionchanged:: 8.1
| The default of a single option boolean flag is not shown if the
| default value is ``False``.
|
| .. versionchanged:: 8.0.1
| ``type`` is detected from ``flag_value`` if given, for basic Python
| types (``str``, ``int``, ``float``, ``bool``).
|
| Method resolution order:
| Option
| Parameter
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, param_decls: 'cabc.Sequence[str] | None' = None, show_default: 'bool | str | None' = None, prompt: 'bool | str' = False, confirmation_prompt: 'bool | str' = False, prompt_required: 'bool' = True, hide_input: 'bool' = False, is_flag: 'bool | None' = None, flag_value: 't.Any' = Sentinel.UNSET, multiple: 'bool' = False, count: 'bool' = False, allow_from_autoenv: 'bool' = True, type: 'types.ParamType[t.Any] | t.Any | None' = None, help: 'str | None' = None, hidden: 'bool' = False, show_choices: 'bool' = True, show_envvar: 'bool' = False, deprecated: 'bool | str' = False, **attrs: 't.Any') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| add_to_parser(self, parser: '_OptionParser', ctx: 'Context') -> 'None'
|
| consume_value(self, ctx: 'Context', opts: 'cabc.Mapping[str, Parameter]') -> 'tuple[t.Any, ParameterSource]'
| For :class:`Option`, the value can be collected from an interactive prompt
| if the option is a flag that needs a value (and the :attr:`prompt` property is
| set).
|
| Additionally, this method handles flag option that are activated without a
| value, in which case the :attr:`flag_value` is returned.
|
| :meta private:
|
| get_default(self, ctx: 'Context', call: 'bool' = True) -> 't.Any | t.Callable[[], t.Any] | None'
| Return the default value for this option.
|
| For non-boolean flag options, ``default=True`` is treated as a sentinel
| meaning "activate this flag by default" and is resolved to
| :attr:`flag_value`. For example, with ``--upper/--lower`` feature
| switches where ``flag_value="upper"`` and ``default=True``, the default
| resolves to ``"upper"``.
|
| .. caution::
| This substitution only applies to non-boolean flags
| (:attr:`is_bool_flag` is ``False``). For boolean flags, ``True`` is
| a legitimate Python value and ``default=True`` is returned as-is.
|
| .. versionchanged:: 8.3.3
| ``default=True`` is no longer substituted with ``flag_value`` for
| boolean flags, fixing negative boolean flags like
| ``flag_value=False, default=True``.
|
| get_error_hint(self, ctx: 'Context | None') -> 'str'
| Get a stringified version of the param for use in error messages to
| indicate which param caused the error.
|
| .. versionchanged:: 8.4.0
| ``ctx`` can be ``None``.
|
| get_help_extra(self, ctx: 'Context') -> 'types.OptionHelpExtra'
|
| get_help_record(self, ctx: 'Context') -> 'tuple[str, str] | None'
|
| process_value(self, ctx: 'Context', value: 't.Any') -> 't.Any'
| Process the value of this parameter:
|
| 1. Type cast the value using :meth:`type_cast_value`.
| 2. Check if the value is missing (see: :meth:`value_is_missing`), and raise
| :exc:`MissingParameter` if it is required.
| 3. If a :attr:`callback` is set, call it to have the value replaced by the
| result of the callback. If the value was not set, the callback receive
| ``None``. This keep the legacy behavior as it was before the introduction of
| the :attr:`UNSET` sentinel.
|
| :meta private:
|
| prompt_for_value(self, ctx: 'Context') -> 't.Any'
| This is an alternative flow that can be activated in the full
| value processing if a value does not exist. It will prompt the
| user until a valid value exists and then returns the processed
| value as result.
|
| resolve_envvar_value(self, ctx: 'Context') -> 'str | None'
| :class:`Option` resolves its environment variable the same way as
| :func:`Parameter.resolve_envvar_value`, but it also supports
| :attr:`Context.auto_envvar_prefix`. If we could not find an environment from
| the :attr:`envvar` property, we fallback on :attr:`Context.auto_envvar_prefix`
| to build dynamiccaly the environment variable name using the
| :python:`{ctx.auto_envvar_prefix}_{self.name.upper()}` template.
|
| :meta private:
|
| to_info_dict(self) -> 'dict[str, t.Any]'
| .. versionchanged:: 8.3.0
| Returns ``None`` for the :attr:`flag_value` if it was not set.
|
| value_from_envvar(self, ctx: 'Context') -> 't.Any'
| For :class:`Option`, this method processes the raw environment variable
| string the same way as :func:`Parameter.value_from_envvar` does.
|
| But in the case of non-boolean flags, the value is analyzed to determine if the
| flag is activated or not, and returns a boolean of its activation, or the
| :attr:`flag_value` if the latter is set.
|
| This method also takes care of repeated options (i.e. options with
| :attr:`multiple` set to ``True``).
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'_flag_needs_value': 'bool', 'allow_from_autoenv': ...
|
| param_type_name = 'option'
|
| ----------------------------------------------------------------------
| Methods inherited from Parameter:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| get_usage_pieces(self, ctx: 'Context') -> 'list[str]'
|
| handle_parse_result(self, ctx: 'Context', opts: 'cabc.Mapping[str, t.Any]', args: 'list[str]') -> 'tuple[t.Any, list[str]]'
| Process the value produced by the parser from user input.
|
| Always process the value through the Parameter's :attr:`type`, wherever it
| comes from.
|
| If the parameter is deprecated, this method warn the user about it. But only if
| the value has been explicitly set by the user (and as such, is not coming from
| a default).
|
| :meta private:
|
| make_metavar(self, ctx: 'Context') -> 'str'
|
| shell_complete(self, ctx: 'Context', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of completions for the incomplete value. If a
| ``shell_complete`` function was given during init, it is used.
| Otherwise, the :attr:`type`
| :meth:`~click.types.ParamType[t.Any].shell_complete` function is used.
|
| :param ctx: Invocation context for this command.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| type_cast_value(self, ctx: 'Context', value: 't.Any') -> 't.Any'
| Convert and validate a value against the parameter's
| :attr:`type`, :attr:`multiple`, and :attr:`nargs`.
|
| value_is_missing(self, value: 't.Any') -> 'bool'
| A value is considered missing if:
|
| - it is :attr:`UNSET`,
| - or if it is an empty sequence while the parameter is suppose to have
| non-single value (i.e. :attr:`nargs` is not ``1`` or :attr:`multiple` is
| set).
|
| :meta private:
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Parameter:
|
| 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.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Parameter:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class Parameter(abc.ABC)
| Parameter(param_decls: 'cabc.Sequence[str] | None' = None, type: 'types.ParamType[t.Any] | t.Any | None' = None, required: 'bool' = False, default: 't.Any | t.Callable[[], t.Any] | None' = Sentinel.UNSET, callback: 't.Callable[[Context, Parameter, t.Any], t.Any] | None' = None, nargs: 'int | None' = None, multiple: 'bool' = False, metavar: 'str | None' = None, expose_value: 'bool' = True, is_eager: 'bool' = False, envvar: 'str | cabc.Sequence[str] | None' = None, shell_complete: 't.Callable[[Context, Parameter, str], list[CompletionItem] | list[str]] | None' = None, deprecated: 'bool | str' = False) -> 'None'
|
| A parameter to a command comes in two versions: they are either
| :class:`Option`\s or :class:`Argument`\s. 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.
|
| :param param_decls: the parameter declarations for this option or
| argument. This is a list of flags or argument
| names.
| :param type: the type that should be used. Either a :class:`ParamType`
| or a Python type. The latter is converted into the former
| automatically if supported.
| :param required: controls if this is optional or not.
| :param 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.
| :param 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.
| :param 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.
| :param metavar: how the value is represented in the help page.
| :param 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.
| :param 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.
| :param envvar: environment variable(s) that are used to provide a default value for
| this parameter. This can be a string or a sequence of strings. If a sequence is
| given, only the first non-empty environment variable is used for the parameter.
| :param 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 :class:`~click.shell_completion.CompletionItem` or a list of
| strings.
| :param deprecated: If ``True`` or 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.
|
| .. versionchanged:: 8.2.0
| Introduction of ``deprecated``.
|
| .. versionchanged:: 8.2
| Adding duplicate parameter names to a :class:`~click.core.Command` will
| result in a ``UserWarning`` being shown.
|
| .. versionchanged:: 8.2
| Adding duplicate parameter names to a :class:`~click.core.Command` will
| result in a ``UserWarning`` being shown.
|
| .. versionchanged:: 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.
|
| .. versionchanged:: 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.
|
| .. versionchanged:: 8.0
| For ``multiple=True, nargs>1``, the default must be a list of
| tuples.
|
| .. versionchanged:: 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 ``()``.
|
| .. versionchanged:: 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.
|
| .. versionchanged:: 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.
|
| Method resolution order:
| Parameter
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, param_decls: 'cabc.Sequence[str] | None' = None, type: 'types.ParamType[t.Any] | t.Any | None' = None, required: 'bool' = False, default: 't.Any | t.Callable[[], t.Any] | None' = Sentinel.UNSET, callback: 't.Callable[[Context, Parameter, t.Any], t.Any] | None' = None, nargs: 'int | None' = None, multiple: 'bool' = False, metavar: 'str | None' = None, expose_value: 'bool' = True, is_eager: 'bool' = False, envvar: 'str | cabc.Sequence[str] | None' = None, shell_complete: 't.Callable[[Context, Parameter, str], list[CompletionItem] | list[str]] | None' = None, deprecated: 'bool | str' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| add_to_parser(self, parser: '_OptionParser', ctx: 'Context') -> 'None'
|
| consume_value(self, ctx: 'Context', opts: 'cabc.Mapping[str, t.Any]') -> 'tuple[t.Any, ParameterSource]'
| Returns the parameter value produced by the parser.
|
| If the parser did not produce a value from user input, the value is either
| sourced from the environment variable, the default map, or the parameter's
| default value. In that order of precedence.
|
| If no value is found, an internal sentinel value is returned.
|
| :meta private:
|
| get_default(self, ctx: 'Context', call: 'bool' = True) -> 't.Any | t.Callable[[], t.Any] | None'
| Get the default for the parameter. Tries
| :meth:`Context.lookup_default` first, then the local default.
|
| :param ctx: Current context.
| :param call: If the default is a callable, call it. Disable to
| return the callable instead.
|
| .. versionchanged:: 8.0.2
| Type casting is no longer performed when getting a default.
|
| .. versionchanged:: 8.0.1
| Type casting can fail in resilient parsing mode. Invalid
| defaults will not prevent showing help text.
|
| .. versionchanged:: 8.0
| Looks at ``ctx.default_map`` first.
|
| .. versionchanged:: 8.0
| Added the ``call`` parameter.
|
| get_error_hint(self, ctx: 'Context | None') -> 'str'
| Get a stringified version of the param for use in error messages to
| indicate which param caused the error.
|
| .. versionchanged:: 8.4.0
| ``ctx`` can be ``None``.
|
| get_help_record(self, ctx: 'Context') -> 'tuple[str, str] | None'
|
| get_usage_pieces(self, ctx: 'Context') -> 'list[str]'
|
| handle_parse_result(self, ctx: 'Context', opts: 'cabc.Mapping[str, t.Any]', args: 'list[str]') -> 'tuple[t.Any, list[str]]'
| Process the value produced by the parser from user input.
|
| Always process the value through the Parameter's :attr:`type`, wherever it
| comes from.
|
| If the parameter is deprecated, this method warn the user about it. But only if
| the value has been explicitly set by the user (and as such, is not coming from
| a default).
|
| :meta private:
|
| make_metavar(self, ctx: 'Context') -> 'str'
|
| process_value(self, ctx: 'Context', value: 't.Any') -> 't.Any'
| Process the value of this parameter:
|
| 1. Type cast the value using :meth:`type_cast_value`.
| 2. Check if the value is missing (see: :meth:`value_is_missing`), and raise
| :exc:`MissingParameter` if it is required.
| 3. If a :attr:`callback` is set, call it to have the value replaced by the
| result of the callback. If the value was not set, the callback receive
| ``None``. This keep the legacy behavior as it was before the introduction of
| the :attr:`UNSET` sentinel.
|
| :meta private:
|
| resolve_envvar_value(self, ctx: 'Context') -> 'str | None'
| Returns the value found in the environment variable(s) attached to this
| parameter.
|
| Environment variables values are `always returned as strings
| <https://docs.python.org/3/library/os.html#os.environ>`_.
|
| This method returns ``None`` if:
|
| - the :attr:`envvar` property is not set on the :class:`Parameter`,
| - the environment variable is not found in the environment,
| - the variable is found in the environment but its value is empty (i.e. the
| environment variable is present but has an empty string).
|
| If :attr:`envvar` is setup with multiple environment variables,
| then only the first non-empty value is returned.
|
| .. caution::
|
| The raw value extracted from the environment is not normalized and is
| returned as-is. Any normalization or reconciliation is performed later by
| the :class:`Parameter`'s :attr:`type`.
|
| :meta private:
|
| shell_complete(self, ctx: 'Context', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of completions for the incomplete value. If a
| ``shell_complete`` function was given during init, it is used.
| Otherwise, the :attr:`type`
| :meth:`~click.types.ParamType[t.Any].shell_complete` function is used.
|
| :param ctx: Invocation context for this command.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self) -> 'dict[str, t.Any]'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionchanged:: 8.3.0
| Returns ``None`` for the :attr:`default` if it was not set.
|
| .. versionadded:: 8.0
|
| type_cast_value(self, ctx: 'Context', value: 't.Any') -> 't.Any'
| Convert and validate a value against the parameter's
| :attr:`type`, :attr:`multiple`, and :attr:`nargs`.
|
| value_from_envvar(self, ctx: 'Context') -> 'str | cabc.Sequence[str] | None'
| Process the raw environment variable string for this parameter.
|
| Returns the string as-is or splits it into a sequence of strings if the
| parameter is expecting multiple values (i.e. its :attr:`nargs` property is set
| to a value other than ``1``).
|
| :meta private:
|
| value_is_missing(self, value: 't.Any') -> 'bool'
| A value is considered missing if:
|
| - it is :attr:`UNSET`,
| - or if it is an empty sequence while the parameter is suppose to have
| non-single value (i.e. :attr:`nargs` is not ``1`` or :attr:`multiple` is
| set).
|
| :meta private:
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| 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.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset({'_parse_decls', 'add_to_parser'})
|
| __annotations__ = {'_custom_shell_complete': 't.Callable[[Context, Par...
|
| param_type_name = 'parameter'
class ParameterSource(enum.IntEnum)
| ParameterSource(*values)
|
| This is an :class:`~enum.IntEnum` that indicates the source of a
| parameter's value.
|
| Use :meth:`click.Context.get_parameter_source` to get the
| source for a parameter by name.
|
| Members are ordered from most explicit to least explicit source.
| This allows comparison to check if a value was explicitly provided:
|
| .. code-block:: python
|
| source = ctx.get_parameter_source("port")
| if source < click.ParameterSource.DEFAULT_MAP:
| ... # value was explicitly set
|
| .. versionchanged:: 8.3.3
| Use :class:`~enum.IntEnum` and reorder members from most to
| least explicit. Supports comparison operators.
|
| .. versionchanged:: 8.0
| Use :class:`~enum.Enum` and drop the ``validate`` method.
|
| .. versionchanged:: 8.0
| Added the ``PROMPT`` value.
|
| Method resolution order:
| ParameterSource
| enum.IntEnum
| builtins.int
| enum.ReprEnum
| enum.Enum
| builtins.object
|
| Methods defined here:
|
| __format__(self, format_spec, /) from builtins.int
| Convert to a string according to format_spec.
|
| __new__(cls, value) from enum.Enum
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| COMMANDLINE = <ParameterSource.COMMANDLINE: 2>
|
| DEFAULT = <ParameterSource.DEFAULT: 5>
|
| DEFAULT_MAP = <ParameterSource.DEFAULT_MAP: 4>
|
| ENVIRONMENT = <ParameterSource.ENVIRONMENT: 3>
|
| PROMPT = <ParameterSource.PROMPT: 1>
|
| ----------------------------------------------------------------------
| Methods inherited from enum.IntEnum:
|
| __repr__(self) from enum.Enum
| Return repr(self).
|
| __str__ = __repr__(self, /) from builtins.int
| Return repr(self).
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.int:
|
| __abs__(self, /)
| abs(self)
|
| __add__(self, value, /)
| Return self+value.
|
| __and__(self, value, /)
| Return self&value.
|
| __bool__(self, /)
| True if self else False
|
| __ceil__(...)
| Ceiling of an Integral returns itself.
|
| __divmod__(self, value, /)
| Return divmod(self, value).
|
| __eq__(self, value, /)
| Return self==value.
|
| __float__(self, /)
| float(self)
|
| __floor__(...)
| Flooring an Integral returns itself.
|
| __floordiv__(self, value, /)
| Return self//value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getnewargs__(self, /)
|
| __gt__(self, value, /)
| Return self>value.
|
| __hash__(self, /)
| Return hash(self).
|
| __index__(self, /)
| Return self converted to an integer, if self is suitable for use as an index into a list.
|
| __int__(self, /)
| int(self)
|
| __invert__(self, /)
| ~self
|
| __le__(self, value, /)
| Return self<=value.
|
| __lshift__(self, value, /)
| Return self<<value.
|
| __lt__(self, value, /)
| Return self<value.
|
| __mod__(self, value, /)
| Return self%value.
|
| __mul__(self, value, /)
| Return self*value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __neg__(self, /)
| -self
|
| __or__(self, value, /)
| Return self|value.
|
| __pos__(self, /)
| +self
|
| __pow__(self, value, mod=None, /)
| Return pow(self, value, mod).
|
| __radd__(self, value, /)
| Return value+self.
|
| __rand__(self, value, /)
| Return value&self.
|
| __rdivmod__(self, value, /)
| Return divmod(value, self).
|
| __rfloordiv__(self, value, /)
| Return value//self.
|
| __rlshift__(self, value, /)
| Return value<<self.
|
| __rmod__(self, value, /)
| Return value%self.
|
| __rmul__(self, value, /)
| Return value*self.
|
| __ror__(self, value, /)
| Return value|self.
|
| __round__(...)
| Rounding an Integral returns itself.
|
| Rounding with an ndigits argument also returns an integer.
|
| __rpow__(self, value, mod=None, /)
| Return pow(value, self, mod).
|
| __rrshift__(self, value, /)
| Return value>>self.
|
| __rshift__(self, value, /)
| Return self>>value.
|
| __rsub__(self, value, /)
| Return value-self.
|
| __rtruediv__(self, value, /)
| Return value/self.
|
| __rxor__(self, value, /)
| Return value^self.
|
| __sizeof__(self, /)
| Returns size in memory, in bytes.
|
| __sub__(self, value, /)
| Return self-value.
|
| __truediv__(self, value, /)
| Return self/value.
|
| __trunc__(...)
| Truncating an Integral returns itself.
|
| __xor__(self, value, /)
| Return self^value.
|
| as_integer_ratio(self, /)
| Return a pair of integers, whose ratio is equal to the original int.
|
| The ratio is in lowest terms and has a positive denominator.
|
| >>> (10).as_integer_ratio()
| (10, 1)
| >>> (-10).as_integer_ratio()
| (-10, 1)
| >>> (0).as_integer_ratio()
| (0, 1)
|
| bit_count(self, /)
| Number of ones in the binary representation of the absolute value of self.
|
| Also known as the population count.
|
| >>> bin(13)
| '0b1101'
| >>> (13).bit_count()
| 3
|
| bit_length(self, /)
| Number of bits necessary to represent self in binary.
|
| >>> bin(37)
| '0b100101'
| >>> (37).bit_length()
| 6
|
| conjugate(...)
| Returns self, the complex conjugate of any int.
|
| is_integer(self, /)
| Returns True. Exists for duck type compatibility with float.is_integer.
|
| to_bytes(self, /, length=1, byteorder='big', *, signed=False)
| Return an array of bytes representing an integer.
|
| length
| Length of bytes object to use. An OverflowError is raised if the
| integer is not representable with the given number of bytes. Default
| is length 1.
| byteorder
| The byte order used to represent the integer. If byteorder is 'big',
| the most significant byte is at the beginning of the byte array. If
| byteorder is 'little', the most significant byte is at the end of the
| byte array. To request the native byte order of the host system, use
| `sys.byteorder' as the byte order value. Default is to use 'big'.
| signed
| Determines whether two's complement is used to represent the integer.
| If signed is False and a negative integer is given, an OverflowError
| is raised.
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.int:
|
| from_bytes(bytes, byteorder='big', *, signed=False)
| Return the integer represented by the given array of bytes.
|
| bytes
| Holds the array of bytes to convert. The argument must either
| support the buffer protocol or be an iterable object producing bytes.
| Bytes and bytearray are examples of built-in objects that support the
| buffer protocol.
| byteorder
| The byte order used to represent the integer. If byteorder is 'big',
| the most significant byte is at the beginning of the byte array. If
| byteorder is 'little', the most significant byte is at the end of the
| byte array. To request the native byte order of the host system, use
| `sys.byteorder' as the byte order value. Default is to use 'big'.
| signed
| Indicates whether two's complement is used to represent the integer.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.int:
|
| denominator
| the denominator of a rational number in lowest terms
|
| imag
| the imaginary part of a complex number
|
| numerator
| the numerator of a rational number in lowest terms
|
| real
| the real part of a complex number
|
| ----------------------------------------------------------------------
| Methods inherited from enum.Enum:
|
| __dir__(self)
| Returns public methods and other interesting attributes.
|
| __init__(self, *args, **kwds)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce_ex__(self, proto)
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from enum.Enum:
|
| name
| The name of the Enum member.
|
| value
| The value of the Enum member.
|
| ----------------------------------------------------------------------
| Static methods inherited from enum.EnumType:
|
| __contains__(value)
| Return True if `value` is in `cls`.
|
| `value` is in `cls` if:
| 1) `value` is a member of `cls`, or
| 2) `value` is the value of one of the `cls`'s members.
|
| __getitem__(name)
| Return the member matching `name`.
|
| __iter__()
| Return members in definition order.
|
| __len__()
| Return the number of members (no aliases)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from enum.EnumType:
|
| __members__
| Returns a mapping of member name->value.
|
| This mapping lists all enum members, including aliases. Note that this
| is a read-only view of the internal mapping.
FUNCTIONS
__getattr__(name: 'str') -> 'object'
augment_usage_errors(ctx: 'Context', param: 'Parameter | None' = None) -> 'cabc.Generator[None]'
Context manager that attaches extra information to exceptions.
batch(iterable: 'cabc.Iterable[V]', batch_size: 'int') -> 'list[tuple[V, ...]]'
iter_params_for_processing(invocation_order: 'cabc.Sequence[Parameter]', declaration_order: 'cabc.Sequence[Parameter]') -> 'list[Parameter]'
Returns all declared parameters in the order they should be processed.
The declared parameters are re-shuffled depending on the order in which
they were invoked, as well as the eagerness of each parameters.
The invocation order takes precedence over the declaration order. I.e. the
order in which the user provided them to the CLI is respected.
This behavior and its effect on callback evaluation is detailed at:
https://click.palletsprojects.com/en/stable/advanced/#callback-evaluation-order
DATA
F = ~F
FLAG_NEEDS_VALUE = Sentinel.FLAG_NEEDS_VALUE
UNSET = Sentinel.UNSET
V = ~V
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\click\core.py
click.decorators
Python Library Documentation: module click.decorators in click
NAME
click.decorators
FUNCTIONS
argument(*param_decls: 'str', cls: 'type[Argument] | None' = None, **attrs: 't.Any') -> 't.Callable[[FC], FC]'
Attaches an argument to the command. All positional arguments are
passed as parameter declarations to :class:`Argument`; all keyword
arguments are forwarded unchanged (except ``cls``).
This is equivalent to creating an :class:`Argument` instance manually
and attaching it to the :attr:`Command.params` list.
For the default argument class, refer to :class:`Argument` and
:class:`Parameter` for descriptions of parameters.
:param cls: the argument class to instantiate. This defaults to
:class:`Argument`.
:param param_decls: Passed as positional arguments to the constructor of
``cls``.
:param attrs: Passed as keyword arguments to the constructor of ``cls``.
command(name: 'str | _AnyCallable | None' = None, cls: 'type[CmdType] | None' = None, **attrs: 't.Any') -> 'Command | t.Callable[[_AnyCallable], Command | CmdType]'
Creates a new :class:`Command` and uses the decorated function as
callback. This will also automatically attach all decorated
:func:`option`\s and :func:`argument`\s as parameters to the command.
The name of the command defaults to the name of the function, converted to
lowercase, with underscores ``_`` replaced by dashes ``-``, and the suffixes
``_command``, ``_cmd``, ``_group``, and ``_grp`` are removed. For example,
``init_data_command`` becomes ``init-data``.
All keyword arguments are forwarded to the underlying command class.
For the ``params`` argument, any decorated params are appended to
the end of the list.
Once decorated the function turns into a :class:`Command` instance
that can be invoked as a command line utility or be attached to a
command :class:`Group`.
:param name: The name of the command. Defaults to modifying the function's
name as described above.
:param cls: The command class to create. Defaults to :class:`Command`.
.. versionchanged:: 8.2
The suffixes ``_command``, ``_cmd``, ``_group``, and ``_grp`` are
removed when generating the name.
.. versionchanged:: 8.1
This decorator can be applied without parentheses.
.. versionchanged:: 8.1
The ``params`` argument can be used. Decorated params are
appended to the end of the list.
confirmation_option(*param_decls: 'str', **kwargs: 't.Any') -> 't.Callable[[FC], FC]'
Add a ``--yes`` option which shows a prompt before continuing if
not passed. If the prompt is declined, the program will exit.
:param param_decls: One or more option names. Defaults to the single
value ``"--yes"``.
:param kwargs: Extra arguments are passed to :func:`option`.
group(name: 'str | _AnyCallable | None' = None, cls: 'type[GrpType] | None' = None, **attrs: 't.Any') -> 'Group | t.Callable[[_AnyCallable], Group | GrpType]'
Creates a new :class:`Group` with a function as callback. This
works otherwise the same as :func:`command` just that the `cls`
parameter is set to :class:`Group`.
.. versionchanged:: 8.1
This decorator can be applied without parentheses.
help_option(*param_decls: 'str', **kwargs: 't.Any') -> 't.Callable[[FC], FC]'
Pre-configured ``--help`` option which immediately prints the help page
and exits the program.
:param param_decls: One or more option names. Defaults to the single
value ``"--help"``.
:param kwargs: Extra arguments are passed to :func:`option`.
make_pass_decorator(object_type: 'type[T]', ensure: 'bool' = False) -> 't.Callable[[t.Callable[te.Concatenate[T, P], R]], t.Callable[P, R]]'
Given an object type this creates a decorator that will work
similar to :func:`pass_obj` but instead of passing the object of the
current context, it will find the innermost context of type
:func:`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
:param object_type: the type of the object to pass.
:param ensure: if set to `True`, a new object will be created and
remembered on the context if it's not there yet.
option(*param_decls: 'str', cls: 'type[Option] | None' = None, **attrs: 't.Any') -> 't.Callable[[FC], FC]'
Attaches an option to the command. All positional arguments are
passed as parameter declarations to :class:`Option`; all keyword
arguments are forwarded unchanged (except ``cls``).
This is equivalent to creating an :class:`Option` instance manually
and attaching it to the :attr:`Command.params` list.
For the default option class, refer to :class:`Option` and
:class:`Parameter` for descriptions of parameters.
:param cls: the option class to instantiate. This defaults to
:class:`Option`.
:param param_decls: Passed as positional arguments to the constructor of
``cls``.
:param attrs: Passed as keyword arguments to the constructor of ``cls``.
pass_context(f: 't.Callable[te.Concatenate[Context, P], R]') -> 't.Callable[P, R]'
Marks a callback as wanting to receive the current context
object as first argument.
pass_meta_key(key: 'str', *, doc_description: 'str | None' = None) -> 't.Callable[[t.Callable[te.Concatenate[T, P], R]], t.Callable[P, R]]'
Create a decorator that passes a key from
:attr:`click.Context.meta` as the first argument to the decorated
function.
:param key: Key in ``Context.meta`` to pass.
:param doc_description: Description of the object being passed,
inserted into the decorator's docstring. Defaults to "the 'key'
key from Context.meta".
.. versionadded:: 8.0
pass_obj(f: 't.Callable[te.Concatenate[T, P], R]') -> 't.Callable[P, R]'
Similar to :func:`pass_context`, but only pass the object on the
context onwards (:attr:`Context.obj`). This is useful if that object
represents the state of a nested system.
password_option(*param_decls: 'str', **kwargs: 't.Any') -> 't.Callable[[FC], FC]'
Add a ``--password`` option which prompts for a password, hiding
input and asking to enter the value again for confirmation.
:param param_decls: One or more option names. Defaults to the single
value ``"--password"``.
:param kwargs: Extra arguments are passed to :func:`option`.
version_option(version: 'str | None' = None, *param_decls: 'str', package_name: 'str | None' = None, prog_name: 'str | None' = None, message: 'str | None' = None, **kwargs: 't.Any') -> 't.Callable[[FC], FC]'
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
:func:`importlib.metadata.version` to get the version for the
``package_name``.
If ``package_name`` is not provided, Click will try to detect it by
inspecting the stack frames. If the detected (or given) name does
not match an installed distribution, Click resolves it as an import
(top-level module) name via
:func:`importlib.metadata.packages_distributions`, so e.g. ``PIL``
resolves to the ``Pillow`` distribution.
:param version: The version number to show. If not provided, Click
will try to detect it.
:param param_decls: One or more option names. Defaults to the single
value ``"--version"``.
:param package_name: The package name to detect the version from. If
not provided, Click will try to detect it.
:param prog_name: The name of the CLI to show in the message. If not
provided, it will be detected from the command.
:param message: The message to show. The values ``%(prog)s``,
``%(package)s``, and ``%(version)s`` are available. Defaults to
``"%(prog)s, version %(version)s"``.
:param kwargs: Extra arguments are passed to :func:`option`.
:raise RuntimeError: ``version`` could not be detected.
.. versionchanged:: 8.0
Add the ``package_name`` parameter, and the ``%(package)s``
value for messages.
.. versionchanged:: 8.0
Use :mod:`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=``.
.. versionchanged:: 8.4.2
When ``package_name`` does not match an installed distribution,
Click now resolves it as an import (top-level module).
DATA
CmdType = ~CmdType
FC = ~FC
GrpType = ~GrpType
R = ~R
T = ~T
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\click\decorators.py
click.echo
Python Library Documentation: function echo in module click.utils
echo(message: 'object' = None, file: 't.IO[t.Any] | None' = None, nl: 'bool' = True, err: 'bool' = False, color: 'bool | None' = None) -> 'None'
Print a message and newline to stdout or a file. This should be
used instead of :func:`print` because it provides better support
for different data, files, and environments.
Compared to :func:`print`, this does the following:
- Ensures that the output encoding is not misconfigured on Linux.
- Supports Unicode in the Windows console.
- Supports writing to binary outputs, and supports writing bytes
to text outputs.
- Supports colors and styles on Windows.
- Removes ANSI color and style codes if the output does not look
like an interactive terminal.
- Always flushes the output.
:param message: The string or bytes to output. Other objects are
converted to strings.
:param file: The file to write to. Defaults to ``stdout``.
:param err: Write to ``stderr`` instead of ``stdout``.
:param nl: Print a newline after the message. Enabled by default.
:param color: Force showing or hiding colors and other styles. By
default Click will remove color if the output does not look like
an interactive terminal.
.. versionchanged:: 6.0
Support Unicode output on the Windows console. Click does not
modify ``sys.stdout``, so ``sys.stdout.write()`` and ``print()``
will still not support Unicode.
.. versionchanged:: 4.0
Added the ``color`` parameter.
.. versionadded:: 3.0
Added the ``err`` parameter.
.. versionchanged:: 2.0
Support colors on Windows if colorama is installed.
click.echo_via_pager
Python Library Documentation: function echo_via_pager in module click.termui
echo_via_pager(text_or_generator: 'cabc.Iterable[str] | t.Callable[[], cabc.Iterable[str]] | str', color: 'bool | None' = None) -> 'None'
This function takes a text and shows it via an environment specific
pager on stdout.
.. versionchanged:: 3.0
Added the `color` flag.
:param text_or_generator: the text to page, or alternatively, a
generator emitting the text to page.
:param color: controls if the pager supports ANSI colors or not. The
default is autodetection.
click.edit
Python Library Documentation: function edit in module click.termui
edit(text: 'str | bytes | bytearray | None' = None, editor: 'str | None' = None, env: 'cabc.Mapping[str, str] | None' = None, require_save: 'bool' = True, extension: 'str' = '.txt', filename: 'str | cabc.Iterable[str] | None' = None) -> 'str | bytes | bytearray | None'
Edits the given text in the defined editor. If an editor is given
(should be the full path to the executable but the regular operating
system search path is used for finding the executable) it overrides
the detected editor. Optionally, some environment variables can be
used. If the editor is closed without changes, `None` is returned. In
case a file is edited directly the return value is always `None` and
`require_save` and `extension` are ignored.
If the editor cannot be opened a :exc:`UsageError` is raised.
Note for Windows: to simplify cross-platform usage, the newlines are
automatically converted from POSIX to Windows and vice versa. As such,
the message here will have ``\n`` as newline markers.
:param text: the text to edit.
:param editor: optionally the editor to use. Defaults to automatic
detection.
:param env: environment variables to forward to the editor.
:param require_save: if this is true, then not saving in the editor
will make the return value become `None`.
:param extension: the extension to tell the editor about. This defaults
to `.txt` but changing this might change syntax
highlighting.
:param filename: if provided it will edit this file instead of the
provided text contents. It will not use a temporary
file as an indirection in that case. If the editor supports
editing multiple files at once, a sequence of files may be
passed as well. Invoke `click.file` once per file instead
if multiple files cannot be managed at once or editing the
files serially is desired.
.. versionchanged:: 8.2.0
``filename`` now accepts any ``Iterable[str]`` in addition to a ``str``
if the ``editor`` supports editing multiple files at once.
click.exceptions
Python Library Documentation: module click.exceptions in click
NAME
click.exceptions
CLASSES
builtins.Exception(builtins.BaseException)
ClickException
FileError
UsageError
BadArgumentUsage
BadOptionUsage
BadParameter
MissingParameter
NoArgsIsHelpError
NoSuchCommand
NoSuchOption
builtins.RuntimeError(builtins.Exception)
Abort
Exit
class Abort(builtins.RuntimeError)
| An internal signalling exception that signals Click to abort.
|
| Method resolution order:
| Abort
| builtins.RuntimeError
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.RuntimeError:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.RuntimeError:
|
| __new__(*args, **kwargs) class method of builtins.RuntimeError
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class BadArgumentUsage(UsageError)
| BadArgumentUsage(message: 'str', ctx: 'Context | None' = None) -> 'None'
|
| Raised if an argument is generally supplied but the use of the argument
| was incorrect. This is for instance raised if the number of values
| for an argument is not correct.
|
| .. versionadded:: 6.0
|
| Method resolution order:
| BadArgumentUsage
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from UsageError:
|
| __init__(self, message: 'str', ctx: 'Context | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UsageError:
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class BadOptionUsage(UsageError)
| BadOptionUsage(option_name: 'str', message: 'str', ctx: 'Context | None' = None) -> 'None'
|
| Raised if an option is generally supplied but the use of the option
| was incorrect. This is for instance raised if the number of arguments
| for an option is not correct.
|
| .. versionadded:: 4.0
|
| :param option_name: the name of the option being used incorrectly.
|
| Method resolution order:
| BadOptionUsage
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, option_name: 'str', message: 'str', ctx: 'Context | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'option_name': 't.Final[str]'}
|
| ----------------------------------------------------------------------
| Methods inherited from UsageError:
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UsageError:
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class BadParameter(UsageError)
| BadParameter(message: 'str', ctx: 'Context | None' = None, param: 'Parameter | None' = None, param_hint: 'cabc.Sequence[str] | str | None' = None) -> 'None'
|
| An exception that formats out a standardized error message for a
| bad parameter. This is useful when thrown from a callback or type as
| Click will attach contextual information to it (for instance, which
| parameter it is).
|
| .. versionadded:: 2.0
|
| :param param: the parameter object that caused this error. This can
| be left out, and Click will attach this info itself
| if possible.
| :param param_hint: a string that shows up as parameter name. This
| can be used as alternative to `param` in cases
| where custom validation should happen. If it is
| a string it's used as such, if it's a list then
| each item is quoted and separated.
|
| Method resolution order:
| BadParameter
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, message: 'str', ctx: 'Context | None' = None, param: 'Parameter | None' = None, param_hint: 'cabc.Sequence[str] | str | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'param': 'Parameter | None', 'param_hint': 'cabc.Se...
|
| ----------------------------------------------------------------------
| Methods inherited from UsageError:
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UsageError:
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class ClickException(builtins.Exception)
| ClickException(message: 'str') -> 'None'
|
| An exception that Click can handle and show to the user.
|
| Method resolution order:
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, message: 'str') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __str__(self) -> 'str'
| Return str(self).
|
| format_message(self) -> 'str'
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'exit_code': 't.ClassVar[int]', 'message': 't.Final...
|
| exit_code = 1
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class Exit(builtins.RuntimeError)
| Exit(code: 'int' = 0) -> 'None'
|
| An exception that indicates that the application should exit with some
| status code.
|
| :param code: the status code to exit with.
|
| Method resolution order:
| Exit
| builtins.RuntimeError
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, code: 'int' = 0) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| exit_code
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'exit_code': 't.Final[int]'}
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.RuntimeError:
|
| __new__(*args, **kwargs) class method of builtins.RuntimeError
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class FileError(ClickException)
| FileError(filename: 'str', hint: 'str | None' = None) -> 'None'
|
| Raised if a file cannot be opened.
|
| Method resolution order:
| FileError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, filename: 'str', hint: 'str | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'filename': 't.Final[str]', 'ui_filename': 't.Final...
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClickException:
|
| exit_code = 1
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class MissingParameter(BadParameter)
| MissingParameter(message: 'str | None' = None, ctx: 'Context | None' = None, param: 'Parameter | None' = None, param_hint: 'cabc.Sequence[str] | str | None' = None, param_type: 'str | None' = None) -> 'None'
|
| Raised if click required an option or argument but it was not
| provided when invoking the script.
|
| .. versionadded:: 4.0
|
| :param param_type: a string that indicates the type of the parameter.
| The default is to inherit the parameter type from
| the given `param`. Valid values are ``'parameter'``,
| ``'option'`` or ``'argument'``.
|
| Method resolution order:
| MissingParameter
| BadParameter
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, message: 'str | None' = None, ctx: 'Context | None' = None, param: 'Parameter | None' = None, param_hint: 'cabc.Sequence[str] | str | None' = None, param_type: 'str | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __str__(self) -> 'str'
| Return str(self).
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'param_type': 't.Final[str | None]'}
|
| ----------------------------------------------------------------------
| Methods inherited from UsageError:
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UsageError:
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class NoArgsIsHelpError(UsageError)
| NoArgsIsHelpError(ctx: 'Context') -> 'None'
|
| Method resolution order:
| NoArgsIsHelpError
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, ctx: 'Context') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'ctx': 'Context'}
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UsageError:
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class NoSuchCommand(UsageError)
| NoSuchCommand(command_name: 'str', message: 'str | None' = None, possibilities: 'cabc.Iterable[str] | None' = None, ctx: 'Context | None' = None) -> 'None'
|
| Raised if Click attempted to handle a command that does not exist.
|
| .. versionadded:: 8.4.0
|
| Method resolution order:
| NoSuchCommand
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, command_name: 'str', message: 'str | None' = None, possibilities: 'cabc.Iterable[str] | None' = None, ctx: 'Context | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'command_name': 't.Final[str]', 'possibilities': 't...
|
| ----------------------------------------------------------------------
| Methods inherited from UsageError:
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UsageError:
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class NoSuchOption(UsageError)
| NoSuchOption(option_name: 'str', message: 'str | None' = None, possibilities: 'cabc.Iterable[str] | None' = None, ctx: 'Context | None' = None) -> 'None'
|
| Raised if Click attempted to handle an option that does not exist.
|
| .. versionadded:: 4.0
|
| Method resolution order:
| NoSuchOption
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, option_name: 'str', message: 'str | None' = None, possibilities: 'cabc.Iterable[str] | None' = None, ctx: 'Context | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'option_name': 't.Final[str]', 'possibilities': 't....
|
| ----------------------------------------------------------------------
| Methods inherited from UsageError:
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UsageError:
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class UsageError(ClickException)
| UsageError(message: 'str', ctx: 'Context | None' = None) -> 'None'
|
| An internal exception that signals a usage error. This typically
| aborts any further handling.
|
| :param message: the error message to display.
| :param ctx: optionally the context that caused this error. Click will
| fill in the context automatically in some situations.
|
| Method resolution order:
| UsageError
| ClickException
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, message: 'str', ctx: 'Context | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| show(self, file: 't.IO[t.Any] | None' = None) -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'cmd': 't.Final[Command | None]', 'ctx': 'Context |...
|
| exit_code = 2
|
| ----------------------------------------------------------------------
| Methods inherited from ClickException:
|
| __str__(self) -> 'str'
| Return str(self).
|
| format_message(self) -> 'str'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClickException:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\click\exceptions.py
click.format_filename
Python Library Documentation: function format_filename in module click.utils
format_filename(filename: 'str | bytes | os.PathLike[str] | os.PathLike[bytes]', shorten: 'bool' = False) -> 'str'
Format a filename as a string for display. Ensures the filename can be
displayed by replacing any invalid bytes or surrogate escapes in the name
with the replacement character ``�``.
Invalid bytes or surrogate escapes will raise an error when written to a
stream with ``errors="strict"``. This will typically happen with ``stdout``
when the locale is something like ``en_GB.UTF-8``.
Many scenarios *are* safe to write surrogates though, due to PEP 538 and
PEP 540, including:
- Writing to ``stderr``, which uses ``errors="backslashreplace"``.
- The system has ``LANG=C.UTF-8``, ``C``, or ``POSIX``. Python opens
stdout and stderr with ``errors="surrogateescape"``.
- None of ``LANG/LC_*`` are set. Python assumes ``LANG=C.UTF-8``.
- Python is started in UTF-8 mode with ``PYTHONUTF8=1`` or ``-X utf8``.
Python opens stdout and stderr with ``errors="surrogateescape"``.
:param filename: formats a filename for UI display. This will also convert
the filename into unicode without failing.
:param shorten: this optionally shortens the filename to strip of the
path that leads up to it.
click.formatting
Python Library Documentation: module click.formatting in click
NAME
click.formatting
CLASSES
builtins.object
HelpFormatter
class HelpFormatter(builtins.object)
| HelpFormatter(indent_increment: 'int' = 2, width: 'int | None' = None, max_width: 'int | None' = None) -> 'None'
|
| This class helps with formatting text-based help pages. It's
| usually just needed for very special internal cases, but it's also
| exposed so that developers can write their own fancy outputs.
|
| At present, it always writes into memory.
|
| :param indent_increment: the additional increment for each level.
| :param width: the width for the text. This defaults to the terminal
| width clamped to a maximum of 78.
|
| Methods defined here:
|
| __init__(self, indent_increment: 'int' = 2, width: 'int | None' = None, max_width: 'int | None' = None) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| dedent(self) -> 'None'
| Decreases the indentation.
|
| getvalue(self) -> 'str'
| Returns the buffer contents.
|
| indent(self) -> 'None'
| Increases the indentation.
|
| indentation(self) -> 'cabc.Generator[None]'
| A context manager that increases the indentation.
|
| section(self, name: 'str') -> 'cabc.Generator[None]'
| Helpful context manager that writes a paragraph, a heading,
| and the indents.
|
| :param name: the section name that is written as heading.
|
| write(self, string: 'str') -> 'None'
| Writes a unicode string into the internal buffer.
|
| write_dl(self, rows: 'cabc.Iterable[tuple[str, str]]', col_max: 'int' = 30, col_spacing: 'int' = 2) -> 'None'
| Writes a definition list into the buffer. This is how options
| and commands are usually formatted.
|
| :param rows: a list of two item tuples for the terms and values.
| :param col_max: the maximum width of the first column.
| :param col_spacing: the number of spaces between the first and
| second column.
|
| write_heading(self, heading: 'str') -> 'None'
| Writes a heading into the buffer.
|
| write_paragraph(self) -> 'None'
| Writes a paragraph into the buffer.
|
| write_text(self, text: 'str') -> 'None'
| Writes re-indented text into the buffer. This rewraps and
| preserves paragraphs.
|
| write_usage(self, prog: 'str', args: 'str' = '', prefix: 'str | None' = None) -> 'None'
| Writes a usage line into the buffer.
|
| :param prog: the program name.
| :param args: whitespace separated list of arguments.
| :param prefix: The prefix for the first line. Defaults to
| ``"Usage: "``.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'buffer': 'list[str]', 'current_indent': 'int', 'in...
FUNCTIONS
iter_rows(rows: 'cabc.Iterable[tuple[str, str]]', col_count: 'int') -> 'cabc.Iterator[tuple[str, ...]]'
join_options(options: 'cabc.Iterable[str]') -> 'tuple[str, bool]'
Given a list of option strings this joins them in the most appropriate
way and returns them in the form ``(formatted_string,
any_prefix_is_slash)`` where the second item in the tuple is a flag that
indicates if any of the option prefixes was a slash.
measure_table(rows: 'cabc.Iterable[tuple[str, str]]') -> 'tuple[int, ...]'
wrap_text(text: 'str', width: 'int' = 78, initial_indent: 'str' = '', subsequent_indent: 'str' = '', preserve_paragraphs: 'bool' = False) -> 'str'
A helper function that intelligently wraps text. By default, it
assumes that it operates on a single paragraph of text but if the
`preserve_paragraphs` parameter is provided it will intelligently
handle paragraphs (defined by two empty lines).
If paragraphs are handled, a paragraph can be prefixed with an empty
line containing the ``\b`` character (``\x08``) to indicate that
no rewrapping should happen in that block.
:param text: the text that should be rewrapped.
:param width: the maximum width for the text.
:param initial_indent: the initial indent that should be placed on the
first line as a string.
:param subsequent_indent: the indent string that should be placed on
each consecutive line.
:param preserve_paragraphs: if this flag is set then the wrapping will
intelligently handle paragraphs.
.. versionchanged:: 8.4.0
Width is measured in visible characters. ANSI escape sequences in
``text``, ``initial_indent``, or ``subsequent_indent`` no longer
count toward the width budget, so styled input wraps based on what
the user sees instead of raw byte length.
DATA
FORCED_WIDTH = None
__annotations__ = {'FORCED_WIDTH': 'int | None'}
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\click\formatting.py
click.get_app_dir
Python Library Documentation: function get_app_dir in module click.utils
get_app_dir(app_name: 'str', roaming: 'bool' = True, force_posix: 'bool' = False) -> 'str'
Returns the config folder for the application. The default behavior
is to return whatever is most appropriate for the operating system.
To give you an idea, for an app called ``"Foo Bar"``, something like
the following folders could be returned:
Mac OS X:
``~/Library/Application Support/Foo Bar``
Mac OS X (POSIX):
``~/.foo-bar``
Unix:
``~/.config/foo-bar``
Unix (POSIX):
``~/.foo-bar``
Windows (roaming):
``C:\Users\<user>\AppData\Roaming\Foo Bar``
Windows (not roaming):
``C:\Users\<user>\AppData\Local\Foo Bar``
.. versionadded:: 2.0
:param app_name: the application name. This should be properly capitalized
and can contain whitespace.
:param roaming: controls if the folder should be roaming or not on Windows.
Has no effect otherwise.
:param force_posix: if this is set to `True` then on any POSIX system the
folder will be stored in the home folder with a leading
dot instead of the XDG config home or darwin's
application support folder.
click.get_binary_stream
Python Library Documentation: function get_binary_stream in module click.utils
get_binary_stream(name: "t.Literal['stdin', 'stdout', 'stderr']") -> 't.BinaryIO'
Returns a system stream for byte processing.
:param name: the name of the stream to open. Valid names are ``'stdin'``,
``'stdout'`` and ``'stderr'``
click.get_current_context
Python Library Documentation: function get_current_context in module click.globals
get_current_context(silent: 'bool' = False) -> 'Context | None'
Returns the current click context. This can be used as a way to
access the current context object from anywhere. This is a more implicit
alternative to the :func:`pass_context` decorator. This function is
primarily useful for helpers such as :func:`echo` which might be
interested in changing its behavior based on the current context.
To push the current context, :meth:`Context.scope` can be used.
.. versionadded:: 5.0
:param silent: if set to `True` the return value is `None` if no context
is available. The default behavior is to raise a
:exc:`RuntimeError`.
click.get_pager_file
Python Library Documentation: function get_pager_file in module click.termui
get_pager_file(color: 'bool | None' = None) -> 't.ContextManager[t.TextIO]'
Context manager.
Yields a writable file-like object which can be used as an output pager.
.. versionadded:: 8.4.0
:param color: controls if the pager supports ANSI colors or not. The
default is autodetection.
click.get_text_stream
Python Library Documentation: function get_text_stream in module click.utils
get_text_stream(name: "t.Literal['stdin', 'stdout', 'stderr']", encoding: 'str | None' = None, errors: 'str | None' = 'strict') -> 't.TextIO'
Returns a system stream for text processing. This usually returns
a wrapped stream around a binary stream returned from
:func:`get_binary_stream` but it also can take shortcuts for already
correctly configured streams.
:param name: the name of the stream to open. Valid names are ``'stdin'``,
``'stdout'`` and ``'stderr'``
:param encoding: overrides the detected default encoding.
:param errors: overrides the default error mode.
click.getchar
Python Library Documentation: function getchar in module click.termui
getchar(echo: 'bool' = False) -> 'str'
Fetches a single character from the terminal and returns it. This
will always return a unicode character and under certain rare
circumstances this might return more than one character. The
situations which more than one character is returned is when for
whatever reason multiple characters end up in the terminal buffer or
standard input was not actually a terminal.
Note that this will always read from the terminal, even if something
is piped into the standard input.
Note for Windows: in rare cases when typing non-ASCII characters, this
function might wait for a second character and then return both at once.
This is because certain Unicode characters look like special-key markers.
.. versionadded:: 2.0
:param echo: if set to `True`, the character read will also show up on
the terminal. The default is to not show it.
click.globals
Python Library Documentation: module click.globals in click
NAME
click.globals
FUNCTIONS
get_current_context(silent: 'bool' = False) -> 'Context | None'
Returns the current click context. This can be used as a way to
access the current context object from anywhere. This is a more implicit
alternative to the :func:`pass_context` decorator. This function is
primarily useful for helpers such as :func:`echo` which might be
interested in changing its behavior based on the current context.
To push the current context, :meth:`Context.scope` can be used.
.. versionadded:: 5.0
:param silent: if set to `True` the return value is `None` if no context
is available. The default behavior is to raise a
:exc:`RuntimeError`.
pop_context() -> 'None'
Removes the top level from the stack.
push_context(ctx: 'Context') -> 'None'
Pushes a new context to the current stack.
resolve_color_default(color: 'bool | None' = None) -> 'bool | None'
Internal helper to get the default value of the color flag. If a
value is passed it's returned unchanged, otherwise it's looked up from
the current context.
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\click\globals.py
click.group
Python Library Documentation: function group in module click.decorators
group(name: 'str | _AnyCallable | None' = None, cls: 'type[GrpType] | None' = None, **attrs: 't.Any') -> 'Group | t.Callable[[_AnyCallable], Group | GrpType]'
Creates a new :class:`Group` with a function as callback. This
works otherwise the same as :func:`command` just that the `cls`
parameter is set to :class:`Group`.
.. versionchanged:: 8.1
This decorator can be applied without parentheses.
click.help_option
Python Library Documentation: function help_option in module click.decorators
help_option(*param_decls: 'str', **kwargs: 't.Any') -> 't.Callable[[FC], FC]'
Pre-configured ``--help`` option which immediately prints the help page
and exits the program.
:param param_decls: One or more option names. Defaults to the single
value ``"--help"``.
:param kwargs: Extra arguments are passed to :func:`option`.
click.launch
Python Library Documentation: function launch in module click.termui
launch(url: 'str', wait: 'bool' = False, locate: 'bool' = False) -> 'int'
This function launches the given URL (or filename) in the default
viewer application for this file type. If this is an executable, it
might launch the executable in a new session. The return value is
the exit code of the launched application. Usually, ``0`` indicates
success.
Examples::
click.launch('https://click.palletsprojects.com/')
click.launch('/my/downloaded/file', locate=True)
.. versionadded:: 2.0
:param url: URL or filename of the thing to launch.
:param wait: Wait for the program to exit before returning. This
only works if the launched program blocks. In particular,
``xdg-open`` on Linux does not block.
:param locate: if this is set to `True` then instead of launching the
application associated with the URL it will attempt to
launch a file manager with the file located. This
might have weird effects if the URL does not point to
the filesystem.
click.make_pass_decorator
Python Library Documentation: function make_pass_decorator in module click.decorators
make_pass_decorator(object_type: 'type[T]', ensure: 'bool' = False) -> 't.Callable[[t.Callable[te.Concatenate[T, P], R]], t.Callable[P, R]]'
Given an object type this creates a decorator that will work
similar to :func:`pass_obj` but instead of passing the object of the
current context, it will find the innermost context of type
:func:`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
:param object_type: the type of the object to pass.
:param ensure: if set to `True`, a new object will be created and
remembered on the context if it's not there yet.
click.open_file
Python Library Documentation: function open_file in module click.utils
open_file(filename: 'str | os.PathLike[str]', mode: 'str' = 'r', encoding: 'str | None' = None, errors: 'str | None' = 'strict', lazy: 'bool' = False, atomic: 'bool' = False) -> 't.IO[t.Any]'
Open a file, with extra behavior to handle ``'-'`` to indicate
a standard stream, lazy open on write, and atomic write. Similar to
the behavior of the :class:`~click.File` param type.
If ``'-'`` is given to open ``stdout`` or ``stdin``, the stream is
wrapped so that using it in a context manager will not close it.
This makes it possible to use the function without accidentally
closing a standard stream:
.. code-block:: python
with open_file(filename) as f:
...
:param filename: The name or Path of the file to open, or ``'-'`` for
``stdin``/``stdout``.
:param mode: The mode in which to open the file.
:param encoding: The encoding to decode or encode a file opened in
text mode.
:param errors: The error handling mode.
:param lazy: Wait to open the file until it is accessed. For read
mode, the file is temporarily opened to raise access errors
early, then closed until it is read again.
:param atomic: Write to a temporary file and replace the given file
on close.
.. versionadded:: 3.0
click.option
Python Library Documentation: function option in module click.decorators
option(*param_decls: 'str', cls: 'type[Option] | None' = None, **attrs: 't.Any') -> 't.Callable[[FC], FC]'
Attaches an option to the command. All positional arguments are
passed as parameter declarations to :class:`Option`; all keyword
arguments are forwarded unchanged (except ``cls``).
This is equivalent to creating an :class:`Option` instance manually
and attaching it to the :attr:`Command.params` list.
For the default option class, refer to :class:`Option` and
:class:`Parameter` for descriptions of parameters.
:param cls: the option class to instantiate. This defaults to
:class:`Option`.
:param param_decls: Passed as positional arguments to the constructor of
``cls``.
:param attrs: Passed as keyword arguments to the constructor of ``cls``.
click.parser
Python Library Documentation: module click.parser in click
NAME
click.parser
DESCRIPTION
This module started out as largely a copy paste from the stdlib's
optparse module with the features removed that we do not need from
optparse because we implement them in Click on a higher level (for
instance type handling, help formatting and a lot more).
The plan is to remove more and more from here over time.
The reason this is a different module and not optparse from the stdlib
is that there are differences in 2.x and 3.x about the error messages
generated and optparse in the stdlib uses gettext for no good reason
and might cause us issues.
Click uses parts of optparse written by Gregory P. Ward and maintained
by the Python Software Foundation. This is limited to code in parser.py.
Copyright 2001-2006 Gregory P. Ward. All rights reserved.
Copyright 2002-2006 Python Software Foundation. All rights reserved.
FUNCTIONS
__getattr__(name: 'str') -> 'object'
DATA
FLAG_NEEDS_VALUE = Sentinel.FLAG_NEEDS_VALUE
UNSET = Sentinel.UNSET
V = ~V
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\click\parser.py
click.pass_context
Python Library Documentation: function pass_context in module click.decorators
pass_context(f: 't.Callable[te.Concatenate[Context, P], R]') -> 't.Callable[P, R]'
Marks a callback as wanting to receive the current context
object as first argument.
click.pass_obj
Python Library Documentation: function pass_obj in module click.decorators
pass_obj(f: 't.Callable[te.Concatenate[T, P], R]') -> 't.Callable[P, R]'
Similar to :func:`pass_context`, but only pass the object on the
context onwards (:attr:`Context.obj`). This is useful if that object
represents the state of a nested system.
click.password_option
Python Library Documentation: function password_option in module click.decorators
password_option(*param_decls: 'str', **kwargs: 't.Any') -> 't.Callable[[FC], FC]'
Add a ``--password`` option which prompts for a password, hiding
input and asking to enter the value again for confirmation.
:param param_decls: One or more option names. Defaults to the single
value ``"--password"``.
:param kwargs: Extra arguments are passed to :func:`option`.
click.pause
Python Library Documentation: function pause in module click.termui
pause(info: 'str | None' = None, err: 'bool' = False) -> 'None'
This command stops execution and waits for the user to press any
key to continue. This is similar to the Windows batch "pause"
command. If the program is not run through a terminal, this command
will instead do nothing.
.. versionadded:: 2.0
.. versionadded:: 4.0
Added the `err` parameter.
:param info: The message to print before pausing. Defaults to
``"Press any key to continue..."``.
:param err: if set to message goes to ``stderr`` instead of
``stdout``, the same as with echo.
click.progressbar
Python Library Documentation: function progressbar in module click.termui
progressbar(iterable: 'cabc.Iterable[V] | None' = None, length: 'int | None' = None, label: 'str | None' = None, hidden: 'bool' = False, show_eta: 'bool' = True, show_percent: 'bool | None' = None, show_pos: 'bool' = False, item_show_func: 't.Callable[[V | None], str | None] | None' = None, fill_char: 'str' = '#', empty_char: 'str' = '-', bar_template: 'str' = '%(label)s [%(bar)s] %(info)s', info_sep: 'str' = ' ', width: 'int' = 36, file: 't.TextIO | None' = None, color: 'bool | None' = None, update_min_steps: 'int' = 1) -> 'ProgressBar[V]'
This function creates an iterable context manager that can be used
to iterate over something while showing a progress bar. It will
either iterate over the `iterable` or `length` items (that are counted
up). While iteration happens, this function will print a rendered
progress bar to the given `file` (defaults to stdout) and will attempt
to calculate remaining time and more. By default, this progress bar
will not be rendered if the file is not a terminal.
The context manager creates the progress bar. When the context
manager is entered the progress bar is already created. With every
iteration over the progress bar, the iterable passed to the bar is
advanced and the bar is updated. When the context manager exits,
a newline is printed and the progress bar is finalized on screen.
Note: The progress bar is currently designed for use cases where the
total progress can be expected to take at least several seconds.
Because of this, the ProgressBar class object won't display
progress that is considered too fast, and progress where the time
between steps is less than a second.
No printing must happen or the progress bar will be unintentionally
destroyed.
Example usage::
with progressbar(items) as bar:
for item in bar:
do_something_with(item)
Alternatively, if no iterable is specified, one can manually update the
progress bar through the `update()` method instead of directly
iterating over the progress bar. The update method accepts the number
of steps to increment the bar with::
with progressbar(length=chunks.total_bytes) as bar:
for chunk in chunks:
process_chunk(chunk)
bar.update(chunks.bytes)
The ``update()`` method also takes an optional value specifying the
``current_item`` at the new position. This is useful when used
together with ``item_show_func`` to customize the output for each
manual step::
with click.progressbar(
length=total_size,
label='Unzipping archive',
item_show_func=lambda a: a.filename
) as bar:
for archive in zip_file:
archive.extract()
bar.update(archive.size, archive)
:param iterable: an iterable to iterate over. If not provided the length
is required.
:param length: the number of items to iterate over. By default the
progressbar will attempt to ask the iterator about its
length, which might or might not work. If an iterable is
also provided this parameter can be used to override the
length. If an iterable is not provided the progress bar
will iterate over a range of that length.
:param label: the label to show next to the progress bar.
:param hidden: hide the progressbar. Defaults to ``False``. When no tty is
detected, it will only print the progressbar label. Setting this to
``False`` also disables that.
:param show_eta: enables or disables the estimated time display. This is
automatically disabled if the length cannot be
determined.
:param show_percent: enables or disables the percentage display. The
default is `True` if the iterable has a length or
`False` if not.
:param show_pos: enables or disables the absolute position display. The
default is `False`.
:param item_show_func: A function called with the current item which
can return a string to show next to the progress bar. If the
function returns ``None`` nothing is shown. The current item can
be ``None``, such as when entering and exiting the bar.
:param fill_char: the character to use to show the filled part of the
progress bar.
:param empty_char: the character to use to show the non-filled part of
the progress bar.
:param bar_template: the format string to use as template for the bar.
The parameters in it are ``label`` for the label,
``bar`` for the progress bar and ``info`` for the
info section.
:param info_sep: the separator between multiple info items (eta etc.)
:param width: the width of the progress bar in characters, 0 means full
terminal width
:param file: The file to write to. If this is not a terminal then
only the label is printed.
:param color: controls if the terminal supports ANSI colors or not. The
default is autodetection. This is only needed if ANSI
codes are included anywhere in the progress bar output
which is not the case by default.
:param update_min_steps: Render only when this many updates have
completed. This allows tuning for very fast iterators.
.. versionadded:: 8.2
The ``hidden`` argument.
.. versionchanged:: 8.0
Output is shown even if execution time is less than 0.5 seconds.
.. versionchanged:: 8.0
``item_show_func`` shows the current item, not the previous one.
.. versionchanged:: 8.0
Labels are echoed if the output is not a TTY. Reverts a change
in 7.0 that removed all output.
.. versionadded:: 8.0
The ``update_min_steps`` parameter.
.. versionadded:: 4.0
The ``color`` parameter and ``update`` method.
.. versionadded:: 2.0
click.prompt
Python Library Documentation: function prompt in module click.termui
prompt(text: 'str', default: 't.Any | None' = None, hide_input: 'bool' = False, confirmation_prompt: 'bool | str' = False, type: 'ParamType[t.Any] | t.Any | None' = None, value_proc: 't.Callable[[str], t.Any] | None' = None, prompt_suffix: 'str' = ': ', show_default: 'bool | str' = True, err: 'bool' = False, show_choices: 'bool' = True) -> 't.Any'
Prompts a user for input. This is a convenience function that can
be used to prompt a user for input later.
If the user aborts the input by sending an interrupt signal, this
function will catch it and raise a :exc:`Abort` exception.
:param text: the text to show for the prompt.
:param default: the default value to use if no input happens. If this
is not given it will prompt until it's aborted.
:param hide_input: if this is set to true then the input value will
be hidden.
:param confirmation_prompt: Prompt a second time to confirm the
value. Can be set to a string instead of ``True`` to customize
the message.
:param type: the type to use to check the value against.
:param value_proc: if this parameter is provided it's a function that
is invoked instead of the type conversion to
convert a value.
:param prompt_suffix: a suffix that should be added to the prompt.
:param show_default: shows or hides the default value in the prompt.
If this value is a string, it shows that string
in parentheses instead of the actual value.
:param err: if set to true the file defaults to ``stderr`` instead of
``stdout``, the same as with echo.
:param show_choices: Show or hide choices if the passed type is a Choice.
For example if type is a Choice of either day or week,
show_choices is true and text is "Group by" then the
prompt will be "Group by (day, week): ".
.. versionchanged:: 8.3.3
``show_default`` can be a string to show a custom value instead
of the actual default, matching the help text behavior.
.. versionchanged:: 8.3.1
A space is no longer appended to the prompt.
.. versionadded:: 8.0
``confirmation_prompt`` can be a custom string.
.. versionadded:: 7.0
Added the ``show_choices`` parameter.
.. versionadded:: 6.0
Added unicode support for cmd.exe on Windows.
.. versionadded:: 4.0
Added the `err` parameter.
click.secho
Python Library Documentation: function secho in module click.termui
secho(message: 't.Any | None' = None, file: 't.IO[t.AnyStr] | None' = None, nl: 'bool' = True, err: 'bool' = False, color: 'bool | None' = None, **styles: 't.Any') -> 'None'
This function combines :func:`echo` and :func:`style` into one
call. As such the following two calls are the same::
click.secho('Hello World!', fg='green')
click.echo(click.style('Hello World!', fg='green'))
All keyword arguments are forwarded to the underlying functions
depending on which one they go with.
Non-string types will be converted to :class:`str`. However,
:class:`bytes` are passed directly to :meth:`echo` without applying
style. If you want to style bytes that represent text, call
:meth:`bytes.decode` first.
.. versionchanged:: 8.0
A non-string ``message`` is converted to a string. Bytes are
passed through without style applied.
.. versionadded:: 2.0
click.style
Python Library Documentation: function style in module click.termui
style(text: 't.Any', fg: 'int | tuple[int, int, int] | str | None' = None, bg: 'int | tuple[int, int, int] | str | None' = None, bold: 'bool | None' = None, dim: 'bool | None' = None, underline: 'bool | None' = None, overline: 'bool | None' = None, italic: 'bool | None' = None, blink: 'bool | None' = None, reverse: 'bool | None' = None, strikethrough: 'bool | None' = None, reset: 'bool' = True) -> 'str'
Styles a text with ANSI styles and returns the new string. By
default the styling is self contained which means that at the end
of the string a reset code is issued. This can be prevented by
passing ``reset=False``.
Examples::
click.echo(click.style('Hello World!', fg='green'))
click.echo(click.style('ATTENTION!', blink=True))
click.echo(click.style('Some things', reverse=True, fg='cyan'))
click.echo(click.style('More colors', fg=(255, 12, 128), bg=117))
Supported color names:
* ``black`` (might be a gray)
* ``red``
* ``green``
* ``yellow`` (might be an orange)
* ``blue``
* ``magenta``
* ``cyan``
* ``white`` (might be light gray)
* ``bright_black``
* ``bright_red``
* ``bright_green``
* ``bright_yellow``
* ``bright_blue``
* ``bright_magenta``
* ``bright_cyan``
* ``bright_white``
* ``reset`` (reset the color code only)
If the terminal supports it, color may also be specified as:
- An integer in the interval [0, 255]. The terminal must support
8-bit/256-color mode.
- An RGB tuple of three integers in [0, 255]. The terminal must
support 24-bit/true-color mode.
See https://en.wikipedia.org/wiki/ANSI_color and
https://gist.github.com/XVilka/8346728 for more information.
:param text: the string to style with ansi codes.
:param fg: if provided this will become the foreground color.
:param bg: if provided this will become the background color.
:param bold: if provided this will enable or disable bold mode.
:param dim: if provided this will enable or disable dim mode. This is
badly supported.
:param underline: if provided this will enable or disable underline.
:param overline: if provided this will enable or disable overline.
:param italic: if provided this will enable or disable italic.
:param blink: if provided this will enable or disable blinking.
:param reverse: if provided this will enable or disable inverse
rendering (foreground becomes background and the
other way round).
:param strikethrough: if provided this will enable or disable
striking through text.
:param reset: by default a reset-all code is added at the end of the
string which means that styles do not carry over. This
can be disabled to compose styles.
.. versionchanged:: 8.0
A non-string ``message`` is converted to a string.
.. versionchanged:: 8.0
Added support for 256 and RGB color codes.
.. versionchanged:: 8.0
Added the ``strikethrough``, ``italic``, and ``overline``
parameters.
.. versionchanged:: 7.0
Added support for bright colors.
.. versionadded:: 2.0
click.termui
Python Library Documentation: module click.termui in click
NAME
click.termui
FUNCTIONS
clear() -> 'None'
Clears the terminal screen. This will have the effect of clearing
the whole visible space of the terminal and moving the cursor to the
top left. This does not do anything if not connected to a terminal.
.. versionadded:: 2.0
confirm(text: 'str', default: 'bool | None' = False, abort: 'bool' = False, prompt_suffix: 'str' = ': ', show_default: 'bool' = True, err: 'bool' = False) -> 'bool'
Prompts for confirmation (yes/no question).
If the user aborts the input by sending a interrupt signal this
function will catch it and raise a :exc:`Abort` exception.
:param text: the question to ask.
:param default: The default value to use when no input is given. If
``None``, repeat until input is given.
:param abort: if this is set to `True` a negative answer aborts the
exception by raising :exc:`Abort`.
:param prompt_suffix: a suffix that should be added to the prompt.
:param show_default: shows or hides the default value in the prompt.
:param err: if set to true the file defaults to ``stderr`` instead of
``stdout``, the same as with echo.
.. versionchanged:: 8.3.1
A space is no longer appended to the prompt.
.. versionchanged:: 8.0
Repeat until input is given if ``default`` is ``None``.
.. versionadded:: 4.0
Added the ``err`` parameter.
echo_via_pager(text_or_generator: 'cabc.Iterable[str] | t.Callable[[], cabc.Iterable[str]] | str', color: 'bool | None' = None) -> 'None'
This function takes a text and shows it via an environment specific
pager on stdout.
.. versionchanged:: 3.0
Added the `color` flag.
:param text_or_generator: the text to page, or alternatively, a
generator emitting the text to page.
:param color: controls if the pager supports ANSI colors or not. The
default is autodetection.
edit(text: 'str | bytes | bytearray | None' = None, editor: 'str | None' = None, env: 'cabc.Mapping[str, str] | None' = None, require_save: 'bool' = True, extension: 'str' = '.txt', filename: 'str | cabc.Iterable[str] | None' = None) -> 'str | bytes | bytearray | None'
Edits the given text in the defined editor. If an editor is given
(should be the full path to the executable but the regular operating
system search path is used for finding the executable) it overrides
the detected editor. Optionally, some environment variables can be
used. If the editor is closed without changes, `None` is returned. In
case a file is edited directly the return value is always `None` and
`require_save` and `extension` are ignored.
If the editor cannot be opened a :exc:`UsageError` is raised.
Note for Windows: to simplify cross-platform usage, the newlines are
automatically converted from POSIX to Windows and vice versa. As such,
the message here will have ``\n`` as newline markers.
:param text: the text to edit.
:param editor: optionally the editor to use. Defaults to automatic
detection.
:param env: environment variables to forward to the editor.
:param require_save: if this is true, then not saving in the editor
will make the return value become `None`.
:param extension: the extension to tell the editor about. This defaults
to `.txt` but changing this might change syntax
highlighting.
:param filename: if provided it will edit this file instead of the
provided text contents. It will not use a temporary
file as an indirection in that case. If the editor supports
editing multiple files at once, a sequence of files may be
passed as well. Invoke `click.file` once per file instead
if multiple files cannot be managed at once or editing the
files serially is desired.
.. versionchanged:: 8.2.0
``filename`` now accepts any ``Iterable[str]`` in addition to a ``str``
if the ``editor`` supports editing multiple files at once.
get_pager_file(color: 'bool | None' = None) -> 't.ContextManager[t.TextIO]'
Context manager.
Yields a writable file-like object which can be used as an output pager.
.. versionadded:: 8.4.0
:param color: controls if the pager supports ANSI colors or not. The
default is autodetection.
getchar(echo: 'bool' = False) -> 'str'
Fetches a single character from the terminal and returns it. This
will always return a unicode character and under certain rare
circumstances this might return more than one character. The
situations which more than one character is returned is when for
whatever reason multiple characters end up in the terminal buffer or
standard input was not actually a terminal.
Note that this will always read from the terminal, even if something
is piped into the standard input.
Note for Windows: in rare cases when typing non-ASCII characters, this
function might wait for a second character and then return both at once.
This is because certain Unicode characters look like special-key markers.
.. versionadded:: 2.0
:param echo: if set to `True`, the character read will also show up on
the terminal. The default is to not show it.
hidden_prompt_func(prompt: 'str') -> 'str'
launch(url: 'str', wait: 'bool' = False, locate: 'bool' = False) -> 'int'
This function launches the given URL (or filename) in the default
viewer application for this file type. If this is an executable, it
might launch the executable in a new session. The return value is
the exit code of the launched application. Usually, ``0`` indicates
success.
Examples::
click.launch('https://click.palletsprojects.com/')
click.launch('/my/downloaded/file', locate=True)
.. versionadded:: 2.0
:param url: URL or filename of the thing to launch.
:param wait: Wait for the program to exit before returning. This
only works if the launched program blocks. In particular,
``xdg-open`` on Linux does not block.
:param locate: if this is set to `True` then instead of launching the
application associated with the URL it will attempt to
launch a file manager with the file located. This
might have weird effects if the URL does not point to
the filesystem.
pause(info: 'str | None' = None, err: 'bool' = False) -> 'None'
This command stops execution and waits for the user to press any
key to continue. This is similar to the Windows batch "pause"
command. If the program is not run through a terminal, this command
will instead do nothing.
.. versionadded:: 2.0
.. versionadded:: 4.0
Added the `err` parameter.
:param info: The message to print before pausing. Defaults to
``"Press any key to continue..."``.
:param err: if set to message goes to ``stderr`` instead of
``stdout``, the same as with echo.
progressbar(iterable: 'cabc.Iterable[V] | None' = None, length: 'int | None' = None, label: 'str | None' = None, hidden: 'bool' = False, show_eta: 'bool' = True, show_percent: 'bool | None' = None, show_pos: 'bool' = False, item_show_func: 't.Callable[[V | None], str | None] | None' = None, fill_char: 'str' = '#', empty_char: 'str' = '-', bar_template: 'str' = '%(label)s [%(bar)s] %(info)s', info_sep: 'str' = ' ', width: 'int' = 36, file: 't.TextIO | None' = None, color: 'bool | None' = None, update_min_steps: 'int' = 1) -> 'ProgressBar[V]'
This function creates an iterable context manager that can be used
to iterate over something while showing a progress bar. It will
either iterate over the `iterable` or `length` items (that are counted
up). While iteration happens, this function will print a rendered
progress bar to the given `file` (defaults to stdout) and will attempt
to calculate remaining time and more. By default, this progress bar
will not be rendered if the file is not a terminal.
The context manager creates the progress bar. When the context
manager is entered the progress bar is already created. With every
iteration over the progress bar, the iterable passed to the bar is
advanced and the bar is updated. When the context manager exits,
a newline is printed and the progress bar is finalized on screen.
Note: The progress bar is currently designed for use cases where the
total progress can be expected to take at least several seconds.
Because of this, the ProgressBar class object won't display
progress that is considered too fast, and progress where the time
between steps is less than a second.
No printing must happen or the progress bar will be unintentionally
destroyed.
Example usage::
with progressbar(items) as bar:
for item in bar:
do_something_with(item)
Alternatively, if no iterable is specified, one can manually update the
progress bar through the `update()` method instead of directly
iterating over the progress bar. The update method accepts the number
of steps to increment the bar with::
with progressbar(length=chunks.total_bytes) as bar:
for chunk in chunks:
process_chunk(chunk)
bar.update(chunks.bytes)
The ``update()`` method also takes an optional value specifying the
``current_item`` at the new position. This is useful when used
together with ``item_show_func`` to customize the output for each
manual step::
with click.progressbar(
length=total_size,
label='Unzipping archive',
item_show_func=lambda a: a.filename
) as bar:
for archive in zip_file:
archive.extract()
bar.update(archive.size, archive)
:param iterable: an iterable to iterate over. If not provided the length
is required.
:param length: the number of items to iterate over. By default the
progressbar will attempt to ask the iterator about its
length, which might or might not work. If an iterable is
also provided this parameter can be used to override the
length. If an iterable is not provided the progress bar
will iterate over a range of that length.
:param label: the label to show next to the progress bar.
:param hidden: hide the progressbar. Defaults to ``False``. When no tty is
detected, it will only print the progressbar label. Setting this to
``False`` also disables that.
:param show_eta: enables or disables the estimated time display. This is
automatically disabled if the length cannot be
determined.
:param show_percent: enables or disables the percentage display. The
default is `True` if the iterable has a length or
`False` if not.
:param show_pos: enables or disables the absolute position display. The
default is `False`.
:param item_show_func: A function called with the current item which
can return a string to show next to the progress bar. If the
function returns ``None`` nothing is shown. The current item can
be ``None``, such as when entering and exiting the bar.
:param fill_char: the character to use to show the filled part of the
progress bar.
:param empty_char: the character to use to show the non-filled part of
the progress bar.
:param bar_template: the format string to use as template for the bar.
The parameters in it are ``label`` for the label,
``bar`` for the progress bar and ``info`` for the
info section.
:param info_sep: the separator between multiple info items (eta etc.)
:param width: the width of the progress bar in characters, 0 means full
terminal width
:param file: The file to write to. If this is not a terminal then
only the label is printed.
:param color: controls if the terminal supports ANSI colors or not. The
default is autodetection. This is only needed if ANSI
codes are included anywhere in the progress bar output
which is not the case by default.
:param update_min_steps: Render only when this many updates have
completed. This allows tuning for very fast iterators.
.. versionadded:: 8.2
The ``hidden`` argument.
.. versionchanged:: 8.0
Output is shown even if execution time is less than 0.5 seconds.
.. versionchanged:: 8.0
``item_show_func`` shows the current item, not the previous one.
.. versionchanged:: 8.0
Labels are echoed if the output is not a TTY. Reverts a change
in 7.0 that removed all output.
.. versionadded:: 8.0
The ``update_min_steps`` parameter.
.. versionadded:: 4.0
The ``color`` parameter and ``update`` method.
.. versionadded:: 2.0
prompt(text: 'str', default: 't.Any | None' = None, hide_input: 'bool' = False, confirmation_prompt: 'bool | str' = False, type: 'ParamType[t.Any] | t.Any | None' = None, value_proc: 't.Callable[[str], t.Any] | None' = None, prompt_suffix: 'str' = ': ', show_default: 'bool | str' = True, err: 'bool' = False, show_choices: 'bool' = True) -> 't.Any'
Prompts a user for input. This is a convenience function that can
be used to prompt a user for input later.
If the user aborts the input by sending an interrupt signal, this
function will catch it and raise a :exc:`Abort` exception.
:param text: the text to show for the prompt.
:param default: the default value to use if no input happens. If this
is not given it will prompt until it's aborted.
:param hide_input: if this is set to true then the input value will
be hidden.
:param confirmation_prompt: Prompt a second time to confirm the
value. Can be set to a string instead of ``True`` to customize
the message.
:param type: the type to use to check the value against.
:param value_proc: if this parameter is provided it's a function that
is invoked instead of the type conversion to
convert a value.
:param prompt_suffix: a suffix that should be added to the prompt.
:param show_default: shows or hides the default value in the prompt.
If this value is a string, it shows that string
in parentheses instead of the actual value.
:param err: if set to true the file defaults to ``stderr`` instead of
``stdout``, the same as with echo.
:param show_choices: Show or hide choices if the passed type is a Choice.
For example if type is a Choice of either day or week,
show_choices is true and text is "Group by" then the
prompt will be "Group by (day, week): ".
.. versionchanged:: 8.3.3
``show_default`` can be a string to show a custom value instead
of the actual default, matching the help text behavior.
.. versionchanged:: 8.3.1
A space is no longer appended to the prompt.
.. versionadded:: 8.0
``confirmation_prompt`` can be a custom string.
.. versionadded:: 7.0
Added the ``show_choices`` parameter.
.. versionadded:: 6.0
Added unicode support for cmd.exe on Windows.
.. versionadded:: 4.0
Added the `err` parameter.
raw_terminal() -> 'AbstractContextManager[int]'
secho(message: 't.Any | None' = None, file: 't.IO[t.AnyStr] | None' = None, nl: 'bool' = True, err: 'bool' = False, color: 'bool | None' = None, **styles: 't.Any') -> 'None'
This function combines :func:`echo` and :func:`style` into one
call. As such the following two calls are the same::
click.secho('Hello World!', fg='green')
click.echo(click.style('Hello World!', fg='green'))
All keyword arguments are forwarded to the underlying functions
depending on which one they go with.
Non-string types will be converted to :class:`str`. However,
:class:`bytes` are passed directly to :meth:`echo` without applying
style. If you want to style bytes that represent text, call
:meth:`bytes.decode` first.
.. versionchanged:: 8.0
A non-string ``message`` is converted to a string. Bytes are
passed through without style applied.
.. versionadded:: 2.0
style(text: 't.Any', fg: 'int | tuple[int, int, int] | str | None' = None, bg: 'int | tuple[int, int, int] | str | None' = None, bold: 'bool | None' = None, dim: 'bool | None' = None, underline: 'bool | None' = None, overline: 'bool | None' = None, italic: 'bool | None' = None, blink: 'bool | None' = None, reverse: 'bool | None' = None, strikethrough: 'bool | None' = None, reset: 'bool' = True) -> 'str'
Styles a text with ANSI styles and returns the new string. By
default the styling is self contained which means that at the end
of the string a reset code is issued. This can be prevented by
passing ``reset=False``.
Examples::
click.echo(click.style('Hello World!', fg='green'))
click.echo(click.style('ATTENTION!', blink=True))
click.echo(click.style('Some things', reverse=True, fg='cyan'))
click.echo(click.style('More colors', fg=(255, 12, 128), bg=117))
Supported color names:
* ``black`` (might be a gray)
* ``red``
* ``green``
* ``yellow`` (might be an orange)
* ``blue``
* ``magenta``
* ``cyan``
* ``white`` (might be light gray)
* ``bright_black``
* ``bright_red``
* ``bright_green``
* ``bright_yellow``
* ``bright_blue``
* ``bright_magenta``
* ``bright_cyan``
* ``bright_white``
* ``reset`` (reset the color code only)
If the terminal supports it, color may also be specified as:
- An integer in the interval [0, 255]. The terminal must support
8-bit/256-color mode.
- An RGB tuple of three integers in [0, 255]. The terminal must
support 24-bit/true-color mode.
See https://en.wikipedia.org/wiki/ANSI_color and
https://gist.github.com/XVilka/8346728 for more information.
:param text: the string to style with ansi codes.
:param fg: if provided this will become the foreground color.
:param bg: if provided this will become the background color.
:param bold: if provided this will enable or disable bold mode.
:param dim: if provided this will enable or disable dim mode. This is
badly supported.
:param underline: if provided this will enable or disable underline.
:param overline: if provided this will enable or disable overline.
:param italic: if provided this will enable or disable italic.
:param blink: if provided this will enable or disable blinking.
:param reverse: if provided this will enable or disable inverse
rendering (foreground becomes background and the
other way round).
:param strikethrough: if provided this will enable or disable
striking through text.
:param reset: by default a reset-all code is added at the end of the
string which means that styles do not carry over. This
can be disabled to compose styles.
.. versionchanged:: 8.0
A non-string ``message`` is converted to a string.
.. versionchanged:: 8.0
Added support for 256 and RGB color codes.
.. versionchanged:: 8.0
Added the ``strikethrough``, ``italic``, and ``overline``
parameters.
.. versionchanged:: 7.0
Added support for bright colors.
.. versionadded:: 2.0
unstyle(text: 'str') -> 'str'
Removes ANSI styling information from a string. Usually it's not
necessary to use this function as Click's echo function will
automatically remove styling if necessary.
.. versionadded:: 2.0
:param text: the text to remove style information from.
visible_prompt_func = input(prompt='', /)
Read a string from standard input. The trailing newline is stripped.
The prompt string, if given, is printed to standard output without a
trailing newline before reading input.
If the user hits EOF (*nix: Ctrl-D, Windows: Ctrl-Z+Return), raise EOFError.
On *nix systems, readline is used if available.
DATA
V = ~V
WIN = True
__annotations__ = {'_getchar': 't.Callable[[bool], str] | None', 'visi...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\click\termui.py
click.types
Python Library Documentation: module click.types in click
NAME
click.types
CLASSES
abc.ABC(builtins.object)
ParamType(typing.Generic, abc.ABC)
BoolParamType
Choice(ParamType, typing.Generic)
CompositeParamType
Tuple
DateTime
File
FuncParamType(ParamType, typing.Generic)
Path
StringParamType
UUIDParameterType
UnprocessedParamType
builtins.dict(builtins.object)
ChoiceInfoDict
DateTimeInfoDict
FileInfoDict
FuncParamTypeInfoDict
NumberRangeInfoDict
OptionHelpExtra
ParamTypeInfoDict
PathInfoDict
TupleInfoDict
_NumberParamTypeBase(ParamType, typing.Generic)
FloatParamType
FloatRange(_NumberRangeBase, FloatParamType)
IntParamType
IntRange(_NumberRangeBase, IntParamType)
_NumberRangeBase(_NumberParamTypeBase, typing.Generic)
FloatRange(_NumberRangeBase, FloatParamType)
IntRange(_NumberRangeBase, IntParamType)
typing.Generic(builtins.object)
ParamType(typing.Generic, abc.ABC)
BoolParamType
Choice(ParamType, typing.Generic)
CompositeParamType
Tuple
DateTime
File
FuncParamType(ParamType, typing.Generic)
Path
StringParamType
UUIDParameterType
UnprocessedParamType
class BoolParamType(ParamType)
| Method resolution order:
| BoolParamType
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: 't.Any', param: 'Parameter | None', ctx: 'Context | None') -> 'bool'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| str_to_bool(value: 'str | bool') -> 'bool | None'
| Convert a string to a boolean value.
|
| If the value is already a boolean, it is returned as-is. If the value is a
| string, it is stripped of whitespaces and lower-cased, then checked against
| the known boolean states pre-defined in the `BoolParamType.bool_states` mapping
| above.
|
| Returns `None` if the value does not match any known boolean state.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'bool_states': 'dict[str, bool]'}
|
| __orig_bases__ = (click.types.ParamType[bool],)
|
| __parameters__ = ()
|
| bool_states = {'': False, '0': False, '1': True, 'f': False, 'false': ...
|
| name = 'boolean'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class Choice(ParamType, typing.Generic)
| Choice(choices: 'cabc.Iterable[_ValueT_co]', case_sensitive: 'bool' = True) -> 'None'
|
| The choice type allows a value to be checked against a fixed set
| of supported values.
|
| You may pass any iterable value which will be converted to a tuple
| and thus will only be iterated once.
|
| The resulting value will always be one of the originally passed choices.
| See :meth:`normalize_choice` for more info on the mapping of strings
| to choices. See :ref:`choice-opts` for an example.
|
| :param case_sensitive: Set to false to make choices case
| insensitive. Defaults to true.
|
| .. versionchanged:: 8.4.0
| Now generic in the choice value type. Parameterize with the type of
| the choice values (``Choice[HashType]`` for an enum, ``Choice[str]``
| for plain strings) to enable type-checked consumers.
|
| .. versionchanged:: 8.2.0
| Non-``str`` ``choices`` are now supported. It can additionally be any
| iterable. Before you were not recommended to pass anything but a list or
| tuple.
|
| .. versionadded:: 8.2.0
| Choice normalization can be overridden via :meth:`normalize_choice`.
|
| Method resolution order:
| Choice
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, choices: 'cabc.Iterable[_ValueT_co]', case_sensitive: 'bool' = True) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: 't.Any', param: 'Parameter | None', ctx: 'Context | None') -> '_ValueT_co'
| For a given value from the parser, normalize it and find its
| matching normalized value in the list of choices. Then return the
| matched "original" choice.
|
| get_invalid_choice_message(self, value: 't.Any', ctx: 'Context | None') -> 'str'
| Get the error message when the given choice is invalid.
|
| :param value: The invalid value.
|
| .. versionadded:: 8.2
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str'
| Message shown when no choice is passed.
|
| .. versionchanged:: 8.2.0 Added ``ctx`` argument.
|
| normalize_choice(self, choice: 'object', ctx: 'Context | None') -> 'str'
| Normalize a choice value, used to map a passed string to a choice.
| Each choice must have a unique normalized value.
|
| By default uses :meth:`Context.token_normalize_func` and if not case
| sensitive, convert it to a casefolded value.
|
| .. versionadded:: 8.2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Complete choices that start with the incomplete value.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self) -> 'ChoiceInfoDict[_ValueT_co]'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'case_sensitive': 'bool', 'choices': 'tuple[_ValueT...
|
| __orig_bases__ = (click.types.ParamType[+_ValueT_co], typing.Generic[+...
|
| __parameters__ = (+_ValueT_co,)
|
| name = 'choice'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class ChoiceInfoDict(builtins.dict)
| Method resolution order:
| ChoiceInfoDict
| builtins.dict
| builtins.object
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'case_sensitive': ForwardRef('bool', module='click....
|
| __optional_keys__ = frozenset()
|
| __orig_bases__ = (<class 'click.types.ParamTypeInfoDict'>,)
|
| __required_keys__ = frozenset({'case_sensitive', 'choices', 'name', 'p...
|
| __total__ = True
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class CompositeParamType(ParamType)
| Method resolution order:
| CompositeParamType
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Readonly properties defined here:
|
| arity
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset({'arity'})
|
| __annotations__ = {'is_composite': 't.ClassVar[bool]'}
|
| __orig_bases__ = (click.types.ParamType[+_ValueT_co],)
|
| __parameters__ = (+_ValueT_co,)
|
| is_composite = True
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| convert(self, value: 't.Any', param: 'Parameter | None', ctx: 'Context | None') -> '_ValueT_co'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| envvar_list_splitter = None
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class DateTime(ParamType)
| DateTime(formats: 'cabc.Sequence[str] | None' = None)
|
| The DateTime type converts date strings into `datetime` objects.
|
| The format strings which are checked are configurable, but default to some
| common (non-timezone aware) ISO 8601 formats.
|
| When specifying *DateTime* formats, you should only pass a list or a tuple.
| Other iterables, like generators, may lead to surprising results.
|
| The format strings are processed using ``datetime.strptime``, and this
| consequently defines the format strings which are allowed.
|
| Parsing is tried using each format, in order, and the first format which
| parses successfully is used.
|
| :param formats: A list or tuple of date format strings, in the order in
| which they should be tried. Defaults to
| ``'%Y-%m-%d'``, ``'%Y-%m-%dT%H:%M:%S'``,
| ``'%Y-%m-%d %H:%M:%S'``.
|
| Method resolution order:
| DateTime
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, formats: 'cabc.Sequence[str] | None' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: 't.Any', param: 'Parameter | None', ctx: 'Context | None') -> 'datetime'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str'
| Returns the metavar default for this param if it provides one.
|
| to_info_dict(self) -> 'DateTimeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'formats': 'cabc.Sequence[str]'}
|
| __orig_bases__ = (click.types.ParamType[datetime.datetime],)
|
| __parameters__ = ()
|
| name = 'datetime'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class DateTimeInfoDict(builtins.dict)
| Method resolution order:
| DateTimeInfoDict
| builtins.dict
| builtins.object
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'formats': ForwardRef('cabc.Sequence[str]', module=...
|
| __optional_keys__ = frozenset()
|
| __orig_bases__ = (<class 'click.types.ParamTypeInfoDict'>,)
|
| __required_keys__ = frozenset({'formats', 'name', 'param_type'})
|
| __total__ = True
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class File(ParamType)
| File(mode: 'str' = 'r', encoding: 'str | None' = None, errors: 'str | None' = 'strict', lazy: 'bool | None' = None, atomic: 'bool' = False) -> 'None'
|
| Declares a parameter to be a file for reading or writing. The file
| is automatically closed once the context tears down (after the command
| finished working).
|
| Files can be opened for reading or writing. The special value ``-``
| indicates stdin or stdout depending on the mode.
|
| By default, the file is opened for reading text data, but it can also be
| opened in binary mode or for writing. The encoding parameter can be used
| to force a specific encoding.
|
| The `lazy` flag controls if the file should be opened immediately or upon
| first IO. The default is to be non-lazy for standard input and output
| streams as well as files opened for reading, `lazy` otherwise. When opening a
| file lazily for reading, it is still opened temporarily for validation, but
| will not be held open until first IO. lazy is mainly useful when opening
| for writing to avoid creating the file until it is needed.
|
| Files can also be opened atomically in which case all writes go into a
| separate file in the same folder and upon completion the file will
| be moved over to the original location. This is useful if a file
| regularly read by other users is modified.
|
| See :ref:`file-args` for more information.
|
| .. versionchanged:: 2.0
| Added the ``atomic`` parameter.
|
| Method resolution order:
| File
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, mode: 'str' = 'r', encoding: 'str | None' = None, errors: 'str | None' = 'strict', lazy: 'bool | None' = None, atomic: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| convert(self, value: 'str | os.PathLike[str] | t.IO[t.Any]', param: 'Parameter | None', ctx: 'Context | None') -> 't.IO[t.Any]'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| resolve_lazy_flag(self, value: 'str | os.PathLike[str]') -> 'bool'
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a special completion marker that tells the completion
| system to use the shell to provide file path completions.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self) -> 'FileInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'atomic': 'bool', 'encoding': 'str | None', 'envvar...
|
| __orig_bases__ = (click.types.ParamType[typing.IO[typing.Any]],)
|
| __parameters__ = ()
|
| envvar_list_splitter = ';'
|
| name = 'filename'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class FileInfoDict(builtins.dict)
| Method resolution order:
| FileInfoDict
| builtins.dict
| builtins.object
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'encoding': ForwardRef('str | None', module='click....
|
| __optional_keys__ = frozenset()
|
| __orig_bases__ = (<class 'click.types.ParamTypeInfoDict'>,)
|
| __required_keys__ = frozenset({'encoding', 'mode', 'name', 'param_type...
|
| __total__ = True
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class FloatParamType(_NumberParamTypeBase)
| Method resolution order:
| FloatParamType
| _NumberParamTypeBase
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types._NumberParamTypeBase[typing.SupportsFloa...
|
| __parameters__ = ()
|
| name = 'float'
|
| ----------------------------------------------------------------------
| Methods inherited from _NumberParamTypeBase:
|
| convert(self, value: '_ValueT_contra', param: 'Parameter | None', ctx: 'Context | None') -> '_ValueT_co'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class FloatRange(_NumberRangeBase, FloatParamType)
| FloatRange(min: 'float | None' = None, max: 'float | None' = None, min_open: 'bool' = False, max_open: 'bool' = False, clamp: 'bool' = False) -> 'None'
|
| Restrict a :data:`click.FLOAT` value to a range of accepted
| values. See :ref:`ranges`.
|
| If ``min`` or ``max`` are not passed, any value is accepted in that
| direction. If ``min_open`` or ``max_open`` are enabled, the
| corresponding boundary is not included in the range.
|
| If ``clamp`` is enabled, a value outside the range is clamped to the
| boundary instead of failing. This is not supported if either
| boundary is marked ``open``.
|
| .. versionchanged:: 8.0
| Added the ``min_open`` and ``max_open`` parameters.
|
| Method resolution order:
| FloatRange
| _NumberRangeBase
| FloatParamType
| _NumberParamTypeBase
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, min: 'float | None' = None, max: 'float | None' = None, min_open: 'bool' = False, max_open: 'bool' = False, clamp: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types._NumberRangeBase[float, float], <class '...
|
| __parameters__ = ()
|
| name = 'float range'
|
| ----------------------------------------------------------------------
| Methods inherited from _NumberRangeBase:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: '_ValueT_contra', param: 'Parameter | None', ctx: 'Context | None') -> '_FloatValueT_co'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| to_info_dict(self) -> 'NumberRangeInfoDict[_FloatValueT_co]'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class FuncParamType(ParamType, typing.Generic)
| FuncParamType(func: 't.Callable[[_ValueT_contra], _ValueT_co]') -> 'None'
|
| Method resolution order:
| FuncParamType
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, func: 't.Callable[[_ValueT_contra], _ValueT_co]') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| convert(self, value: '_ValueT_contra', param: 'Parameter | None', ctx: 'Context | None') -> '_ValueT_co'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| to_info_dict(self) -> 'FuncParamTypeInfoDict[_ValueT_contra, _ValueT_co]'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'func': 't.Callable[[_ValueT_contra], _ValueT_co]',...
|
| __orig_bases__ = (click.types.ParamType[+_ValueT_co], typing.Generic[-...
|
| __parameters__ = (-_ValueT_contra, +_ValueT_co)
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class FuncParamTypeInfoDict(builtins.dict)
| Method resolution order:
| FuncParamTypeInfoDict
| builtins.dict
| builtins.object
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'func': ForwardRef('t.Callable[[t.Any], t.Any]', mo...
|
| __optional_keys__ = frozenset()
|
| __orig_bases__ = (<class 'click.types.ParamTypeInfoDict'>,)
|
| __required_keys__ = frozenset({'func', 'name', 'param_type'})
|
| __total__ = True
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class IntParamType(_NumberParamTypeBase)
| Method resolution order:
| IntParamType
| _NumberParamTypeBase
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types._NumberParamTypeBase[typing.SupportsInt ...
|
| __parameters__ = ()
|
| name = 'integer'
|
| ----------------------------------------------------------------------
| Methods inherited from _NumberParamTypeBase:
|
| convert(self, value: '_ValueT_contra', param: 'Parameter | None', ctx: 'Context | None') -> '_ValueT_co'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class IntRange(_NumberRangeBase, IntParamType)
| IntRange(min: '_FloatValueT_co | None' = None, max: '_FloatValueT_co | None' = None, min_open: 'bool' = False, max_open: 'bool' = False, clamp: 'bool' = False) -> 'None'
|
| Restrict an :data:`click.INT` value to a range of accepted
| values. See :ref:`ranges`.
|
| If ``min`` or ``max`` are not passed, any value is accepted in that
| direction. If ``min_open`` or ``max_open`` are enabled, the
| corresponding boundary is not included in the range.
|
| If ``clamp`` is enabled, a value outside the range is clamped to the
| boundary instead of failing.
|
| .. versionchanged:: 8.0
| Added the ``min_open`` and ``max_open`` parameters.
|
| Method resolution order:
| IntRange
| _NumberRangeBase
| IntParamType
| _NumberParamTypeBase
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types._NumberRangeBase[int, int], <class 'clic...
|
| __parameters__ = ()
|
| name = 'integer range'
|
| ----------------------------------------------------------------------
| Methods inherited from _NumberRangeBase:
|
| __init__(self, min: '_FloatValueT_co | None' = None, max: '_FloatValueT_co | None' = None, min_open: 'bool' = False, max_open: 'bool' = False, clamp: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: '_ValueT_contra', param: 'Parameter | None', ctx: 'Context | None') -> '_FloatValueT_co'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| to_info_dict(self) -> 'NumberRangeInfoDict[_FloatValueT_co]'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class NumberRangeInfoDict(builtins.dict)
| Method resolution order:
| NumberRangeInfoDict
| builtins.dict
| builtins.object
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'clamp': ForwardRef('bool', module='click.types'), ...
|
| __optional_keys__ = frozenset()
|
| __orig_bases__ = (<class 'click.types.ParamTypeInfoDict'>,)
|
| __required_keys__ = frozenset({'clamp', 'max', 'max_open', 'min', 'min...
|
| __total__ = True
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class OptionHelpExtra(builtins.dict)
| Method resolution order:
| OptionHelpExtra
| builtins.dict
| builtins.object
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'default': ForwardRef('str', module='click.types'),...
|
| __optional_keys__ = frozenset({'default', 'envvars', 'range', 'require...
|
| __orig_bases__ = (<function TypedDict>,)
|
| __required_keys__ = frozenset()
|
| __total__ = False
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class ParamType(typing.Generic, abc.ABC)
| Represents the type of a parameter. Validates and converts values
| from the command line or Python into the correct type.
|
| To implement a custom type, subclass and implement at least the
| following:
|
| - The :attr:`name` class attribute must be set.
| - Calling an instance of the type with ``None`` must return
| ``None``. This is already implemented by default.
| - :meth:`convert` must convert string values to the correct type.
| - :meth:`convert` must accept values that are already the correct
| type.
| - It must be able to convert a value if the ``ctx`` and ``param``
| arguments are ``None``. This can occur when converting prompt
| input.
|
| .. versionchanged:: 8.4.0
| Now a generic abstract base class. Parameterize with the
| converted value type (``ParamType[int]`` for an integer-returning
| type) so that :meth:`convert` and downstream consumers carry the
| narrowed return type.
|
| Method resolution order:
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| convert(self, value: 't.Any', param: 'Parameter | None', ctx: 'Context | None') -> '_ValueT_co'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'arity': 'int', 'envvar_list_splitter': 't.ClassVar...
|
| __orig_bases__ = (typing.Generic[+_ValueT_co], <class 'abc.ABC'>)
|
| __parameters__ = (+_ValueT_co,)
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class ParamTypeInfoDict(builtins.dict)
| Method resolution order:
| ParamTypeInfoDict
| builtins.dict
| builtins.object
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'name': ForwardRef('str', module='click.types'), 'p...
|
| __optional_keys__ = frozenset()
|
| __orig_bases__ = (<function TypedDict>,)
|
| __required_keys__ = frozenset({'name', 'param_type'})
|
| __total__ = True
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class Path(ParamType)
| Path(exists: 'bool' = False, file_okay: 'bool' = True, dir_okay: 'bool' = True, writable: 'bool' = False, readable: 'bool' = True, resolve_path: 'bool' = False, allow_dash: 'bool' = False, path_type: 'type | None' = None, executable: 'bool' = False) -> 'None'
|
| The ``Path`` type is similar to the :class:`File` type, but
| returns the filename instead of an open file. Various checks can be
| enabled to validate the type of file and permissions.
|
| :param exists: The file or directory needs to exist for the value to
| be valid. If this is not set to ``True``, and the file does not
| exist, then all further checks are silently skipped.
| :param file_okay: Allow a file as a value.
| :param dir_okay: Allow a directory as a value.
| :param readable: if true, a readable check is performed.
| :param writable: if true, a writable check is performed.
| :param executable: if true, an executable check is performed.
| :param resolve_path: Make the value absolute and resolve any
| symlinks. A ``~`` is not expanded, as this is supposed to be
| done by the shell only.
| :param allow_dash: Allow a single dash as a value, which indicates
| a standard stream (but does not open it). Use
| :func:`~click.open_file` to handle opening this value.
| :param path_type: Convert the incoming path value to this type. If
| ``None``, keep Python's default, which is ``str``. Useful to
| convert to :class:`pathlib.Path`.
|
| .. versionchanged:: 8.1
| Added the ``executable`` parameter.
|
| .. versionchanged:: 8.0
| Allow passing ``path_type=pathlib.Path``.
|
| .. versionchanged:: 6.0
| Added the ``allow_dash`` parameter.
|
| Method resolution order:
| Path
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, exists: 'bool' = False, file_okay: 'bool' = True, dir_okay: 'bool' = True, writable: 'bool' = False, readable: 'bool' = True, resolve_path: 'bool' = False, allow_dash: 'bool' = False, path_type: 'type | None' = None, executable: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| coerce_path_result(self, value: 'str | os.PathLike[str]') -> 'str | bytes | os.PathLike[str]'
|
| convert(self, value: 'str | os.PathLike[str]', param: 'Parameter | None', ctx: 'Context | None') -> 'str | bytes | os.PathLike[str]'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a special completion marker that tells the completion
| system to use the shell to provide path completions for only
| directories or any paths.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| to_info_dict(self) -> 'PathInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'allow_dash': 'bool', 'dir_okay': 'bool', 'envvar_l...
|
| __orig_bases__ = (click.types.ParamType[str | bytes | os.PathLike[str]...
|
| __parameters__ = ()
|
| envvar_list_splitter = ';'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class PathInfoDict(builtins.dict)
| Method resolution order:
| PathInfoDict
| builtins.dict
| builtins.object
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'allow_dash': ForwardRef('bool', module='click.type...
|
| __optional_keys__ = frozenset()
|
| __orig_bases__ = (<class 'click.types.ParamTypeInfoDict'>,)
|
| __required_keys__ = frozenset({'allow_dash', 'dir_okay', 'exists', 'fi...
|
| __total__ = True
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class StringParamType(ParamType)
| Method resolution order:
| StringParamType
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: 't.Any', param: 'Parameter | None', ctx: 'Context | None') -> 'str'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types.ParamType[str],)
|
| __parameters__ = ()
|
| name = 'text'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class Tuple(CompositeParamType)
| Tuple(types: 'cabc.Sequence[type[t.Any] | ParamType[t.Any]]') -> 'None'
|
| The default behavior of Click is to apply a type on a value directly.
| This works well in most cases, except for when `nargs` is set to a fixed
| count and different types should be used for different items. In this
| case the :class:`Tuple` type can be used. This type can only be used
| if `nargs` is set to a fixed number.
|
| For more information see :ref:`tuple-type`.
|
| This can be selected by using a Python tuple literal as a type.
|
| :param types: a list of types that should be used for the tuple items.
|
| Method resolution order:
| Tuple
| CompositeParamType
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __init__(self, types: 'cabc.Sequence[type[t.Any] | ParamType[t.Any]]') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| convert(self, value: 't.Any', param: 'Parameter | None', ctx: 'Context | None') -> 'tuple[t.Any, ...]'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| to_info_dict(self) -> 'TupleInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| arity
|
| name
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types.CompositeParamType[tuple[typing.Any, ......
|
| __parameters__ = ()
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompositeParamType:
|
| is_composite = True
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| envvar_list_splitter = None
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class TupleInfoDict(builtins.dict)
| Method resolution order:
| TupleInfoDict
| builtins.dict
| builtins.object
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'name': ForwardRef('str', module='click.types'), 'p...
|
| __optional_keys__ = frozenset()
|
| __orig_bases__ = (<class 'click.types.ParamTypeInfoDict'>,)
|
| __required_keys__ = frozenset({'name', 'param_type', 'types'})
|
| __total__ = True
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.dict:
|
| __contains__(self, key, /)
| True if the dictionary has the specified key, else False.
|
| __delitem__(self, key, /)
| Delete self[key].
|
| __eq__(self, value, /)
| Return self==value.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| __ior__(self, value, /)
| Return self|=value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __or__(self, value, /)
| Return self|value.
|
| __repr__(self, /)
| Return repr(self).
|
| __reversed__(self, /)
| Return a reverse iterator over the dict keys.
|
| __ror__(self, value, /)
| Return value|self.
|
| __setitem__(self, key, value, /)
| Set self[key] to value.
|
| __sizeof__(...)
| D.__sizeof__() -> size of D in memory, in bytes
|
| clear(...)
| D.clear() -> None. Remove all items from D.
|
| copy(...)
| D.copy() -> a shallow copy of D
|
| get(self, key, default=None, /)
| Return the value for key if key is in the dictionary, else default.
|
| items(...)
| D.items() -> a set-like object providing a view on D's items
|
| keys(...)
| D.keys() -> a set-like object providing a view on D's keys
|
| pop(...)
| D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
|
| If the key is not found, return the default if given; otherwise,
| raise a KeyError.
|
| popitem(self, /)
| Remove and return a (key, value) pair as a 2-tuple.
|
| Pairs are returned in LIFO (last-in, first-out) order.
| Raises KeyError if the dict is empty.
|
| setdefault(self, key, default=None, /)
| Insert key with a value of default if key is not in the dictionary.
|
| Return the value for key if key is in the dictionary, else default.
|
| update(...)
| D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
| If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
| If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]
|
| values(...)
| D.values() -> an object providing a view on D's values
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.dict:
|
| __class_getitem__(...)
| See PEP 585
|
| fromkeys(iterable, value=None, /)
| Create a new dictionary with keys from iterable and values set to value.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.dict:
|
| __new__(*args, **kwargs) class method of builtins.dict
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from builtins.dict:
|
| __hash__ = None
class UUIDParameterType(ParamType)
| Method resolution order:
| UUIDParameterType
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: 'uuid.UUID | str', param: 'Parameter | None', ctx: 'Context | None') -> 'uuid.UUID'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types.ParamType[uuid.UUID],)
|
| __parameters__ = ()
|
| name = 'uuid'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
class UnprocessedParamType(ParamType)
| Method resolution order:
| UnprocessedParamType
| ParamType
| typing.Generic
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| convert(self, value: '_ValueT', param: 'Parameter | None', ctx: 'Context | None') -> '_ValueT'
| Convert the value to the correct type. This is not called if
| the value is ``None`` (the missing value).
|
| This must accept string values from the command line, as well as
| values that are already the correct type. It may also convert
| other compatible types.
|
| The ``param`` and ``ctx`` arguments may be ``None`` in certain
| situations, such as when converting prompt input.
|
| If the value cannot be converted, call :meth:`fail` with a
| descriptive message.
|
| :param value: The value to convert.
| :param param: The parameter that is using this type to convert
| its value. May be ``None``.
| :param ctx: The current context that arrived at this value. May
| be ``None``.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (click.types.ParamType[typing.Any],)
|
| __parameters__ = ()
|
| name = 'text'
|
| ----------------------------------------------------------------------
| Methods inherited from ParamType:
|
| __call__(self, value: 't.Any', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> '_ValueT_co | None'
| Call self as a function.
|
| fail(self, message: 'str', param: 'Parameter | None' = None, ctx: 'Context | None' = None) -> 't.NoReturn'
| Helper method to fail with an invalid value message.
|
| get_metavar(self, param: 'Parameter', ctx: 'Context') -> 'str | None'
| Returns the metavar default for this param if it provides one.
|
| get_missing_message(self, param: 'Parameter', ctx: 'Context | None') -> 'str | None'
| Optionally might return extra information about a missing
| parameter.
|
| .. versionadded:: 2.0
|
| shell_complete(self, ctx: 'Context', param: 'Parameter', incomplete: 'str') -> 'list[CompletionItem]'
| Return a list of
| :class:`~click.shell_completion.CompletionItem` objects for the
| incomplete value. Most types do not provide completions, but
| some do, and this allows custom types to provide custom
| completions as well.
|
| :param ctx: Invocation context for this command.
| :param param: The parameter that is requesting completion.
| :param incomplete: Value being completed. May be empty.
|
| .. versionadded:: 8.0
|
| split_envvar_value(self, rv: 'str') -> 'cabc.Sequence[str]'
| Given a value from an environment variable this splits it up
| into small chunks depending on the defined envvar list splitter.
|
| If the splitter is set to `None`, which means that whitespace splits,
| then leading and trailing whitespace is ignored. Otherwise, leading
| and trailing splitters usually lead to empty items being included.
|
| to_info_dict(self) -> 'ParamTypeInfoDict'
| Gather information that could be useful for a tool generating
| user-facing documentation.
|
| Use :meth:`click.Context.to_info_dict` to traverse the entire
| CLI structure.
|
| .. versionadded:: 8.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ParamType:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ParamType:
|
| arity = 1
|
| envvar_list_splitter = None
|
| is_composite = False
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
FUNCTIONS
convert_type(ty: 't.Any | None' = None, default: 't.Any | None' = None) -> 'ParamType[t.Any]'
Find the most appropriate :class:`ParamType` for the given Python
type. If the type isn't provided, it can be inferred from a default
value.
DATA
BOOL = BOOL
FLOAT = FLOAT
INT = INT
STRING = STRING
UNPROCESSED = UNPROCESSED
UUID = UUID
__annotations__ = {'BOOL': 't.Final[BoolParamType]', 'FLOAT': 't.Final...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\click\types.py
click.unstyle
Python Library Documentation: function unstyle in module click.termui
unstyle(text: 'str') -> 'str'
Removes ANSI styling information from a string. Usually it's not
necessary to use this function as Click's echo function will
automatically remove styling if necessary.
.. versionadded:: 2.0
:param text: the text to remove style information from.
click.utils
Python Library Documentation: module click.utils in click
NAME
click.utils
CLASSES
builtins.object
KeepOpenFile
LazyFile
PacifyFlushWrapper
class KeepOpenFile(builtins.object)
| KeepOpenFile(file: 't.IO[t.Any]') -> 'None'
|
| Proxy a file object but keep it open across a ``with`` block.
|
| Wraps a borrowed file (such as ``sys.stdin`` or ``sys.stdout``) so that
| leaving a ``with`` block does not close it, as used by :func:`open_file`
| for the ``-`` filename. The caller stays responsible for the file: an
| explicit :meth:`close` still passes through to the wrapped object.
|
| Dunder methods are proxied explicitly: implicit special-method lookups
| bypass :meth:`__getattr__`, because Python resolves them on the type rather
| than the instance.
|
| Methods defined here:
|
| __enter__(self) -> 'KeepOpenFile'
|
| __exit__(self, exc_type: 'type[BaseException] | None', exc_value: 'BaseException | None', tb: 'TracebackType | None') -> 'None'
|
| __getattr__(self, name: 'str') -> 't.Any'
|
| __init__(self, file: 't.IO[t.Any]') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __iter__(self) -> 'cabc.Iterator[t.AnyStr]'
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_file': 't.IO[t.Any]'}
class LazyFile(builtins.object)
| LazyFile(filename: 'str | os.PathLike[str]', mode: 'str' = 'r', encoding: 'str | None' = None, errors: 'str | None' = 'strict', atomic: 'bool' = False) -> 'None'
|
| A lazy file works like a regular file but it does not fully open
| the file but it does perform some basic checks early to see if the
| filename parameter does make sense. This is useful for safely opening
| files for writing.
|
| Methods defined here:
|
| __enter__(self) -> 'LazyFile'
|
| __exit__(self, exc_type: 'type[BaseException] | None', exc_value: 'BaseException | None', tb: 'TracebackType | None') -> 'None'
|
| __getattr__(self, name: 'str') -> 't.Any'
|
| __init__(self, filename: 'str | os.PathLike[str]', mode: 'str' = 'r', encoding: 'str | None' = None, errors: 'str | None' = 'strict', atomic: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __iter__(self) -> 'cabc.Iterator[t.AnyStr]'
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| close(self) -> 'None'
| Closes the underlying file, no matter what.
|
| close_intelligently(self) -> 'None'
| This function only closes the file if it was opened by the lazy
| file wrapper. For instance this will never close stdin.
|
| open(self) -> 't.IO[t.Any]'
| Opens the file if it's not yet open. This call might fail with
| a :exc:`FileError`. Not handling this error will produce an error
| that Click shows.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_f': 't.IO[t.Any] | None', 'atomic': 'bool', 'enco...
class PacifyFlushWrapper(builtins.object)
| PacifyFlushWrapper(wrapped: 't.IO[t.Any]') -> 'None'
|
| This wrapper is used to catch and suppress BrokenPipeErrors resulting
| from ``.flush()`` being called on broken pipe during the shutdown/final-GC
| of the Python interpreter. Notably ``.flush()`` is always called on
| ``sys.stdout`` and ``sys.stderr``. So as to have minimal impact on any
| other cleanup code, and the case where the underlying file is not a broken
| pipe, all calls and attributes are proxied.
|
| Methods defined here:
|
| __getattr__(self, attr: 'str') -> 't.Any'
|
| __init__(self, wrapped: 't.IO[t.Any]') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| flush(self) -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'wrapped': 't.IO[t.Any]'}
FUNCTIONS
echo(message: 'object' = None, file: 't.IO[t.Any] | None' = None, nl: 'bool' = True, err: 'bool' = False, color: 'bool | None' = None) -> 'None'
Print a message and newline to stdout or a file. This should be
used instead of :func:`print` because it provides better support
for different data, files, and environments.
Compared to :func:`print`, this does the following:
- Ensures that the output encoding is not misconfigured on Linux.
- Supports Unicode in the Windows console.
- Supports writing to binary outputs, and supports writing bytes
to text outputs.
- Supports colors and styles on Windows.
- Removes ANSI color and style codes if the output does not look
like an interactive terminal.
- Always flushes the output.
:param message: The string or bytes to output. Other objects are
converted to strings.
:param file: The file to write to. Defaults to ``stdout``.
:param err: Write to ``stderr`` instead of ``stdout``.
:param nl: Print a newline after the message. Enabled by default.
:param color: Force showing or hiding colors and other styles. By
default Click will remove color if the output does not look like
an interactive terminal.
.. versionchanged:: 6.0
Support Unicode output on the Windows console. Click does not
modify ``sys.stdout``, so ``sys.stdout.write()`` and ``print()``
will still not support Unicode.
.. versionchanged:: 4.0
Added the ``color`` parameter.
.. versionadded:: 3.0
Added the ``err`` parameter.
.. versionchanged:: 2.0
Support colors on Windows if colorama is installed.
format_filename(filename: 'str | bytes | os.PathLike[str] | os.PathLike[bytes]', shorten: 'bool' = False) -> 'str'
Format a filename as a string for display. Ensures the filename can be
displayed by replacing any invalid bytes or surrogate escapes in the name
with the replacement character ``�``.
Invalid bytes or surrogate escapes will raise an error when written to a
stream with ``errors="strict"``. This will typically happen with ``stdout``
when the locale is something like ``en_GB.UTF-8``.
Many scenarios *are* safe to write surrogates though, due to PEP 538 and
PEP 540, including:
- Writing to ``stderr``, which uses ``errors="backslashreplace"``.
- The system has ``LANG=C.UTF-8``, ``C``, or ``POSIX``. Python opens
stdout and stderr with ``errors="surrogateescape"``.
- None of ``LANG/LC_*`` are set. Python assumes ``LANG=C.UTF-8``.
- Python is started in UTF-8 mode with ``PYTHONUTF8=1`` or ``-X utf8``.
Python opens stdout and stderr with ``errors="surrogateescape"``.
:param filename: formats a filename for UI display. This will also convert
the filename into unicode without failing.
:param shorten: this optionally shortens the filename to strip of the
path that leads up to it.
get_app_dir(app_name: 'str', roaming: 'bool' = True, force_posix: 'bool' = False) -> 'str'
Returns the config folder for the application. The default behavior
is to return whatever is most appropriate for the operating system.
To give you an idea, for an app called ``"Foo Bar"``, something like
the following folders could be returned:
Mac OS X:
``~/Library/Application Support/Foo Bar``
Mac OS X (POSIX):
``~/.foo-bar``
Unix:
``~/.config/foo-bar``
Unix (POSIX):
``~/.foo-bar``
Windows (roaming):
``C:\Users\<user>\AppData\Roaming\Foo Bar``
Windows (not roaming):
``C:\Users\<user>\AppData\Local\Foo Bar``
.. versionadded:: 2.0
:param app_name: the application name. This should be properly capitalized
and can contain whitespace.
:param roaming: controls if the folder should be roaming or not on Windows.
Has no effect otherwise.
:param force_posix: if this is set to `True` then on any POSIX system the
folder will be stored in the home folder with a leading
dot instead of the XDG config home or darwin's
application support folder.
get_binary_stream(name: "t.Literal['stdin', 'stdout', 'stderr']") -> 't.BinaryIO'
Returns a system stream for byte processing.
:param name: the name of the stream to open. Valid names are ``'stdin'``,
``'stdout'`` and ``'stderr'``
get_text_stream(name: "t.Literal['stdin', 'stdout', 'stderr']", encoding: 'str | None' = None, errors: 'str | None' = 'strict') -> 't.TextIO'
Returns a system stream for text processing. This usually returns
a wrapped stream around a binary stream returned from
:func:`get_binary_stream` but it also can take shortcuts for already
correctly configured streams.
:param name: the name of the stream to open. Valid names are ``'stdin'``,
``'stdout'`` and ``'stderr'``
:param encoding: overrides the detected default encoding.
:param errors: overrides the default error mode.
make_default_short_help(help: 'str', max_length: 'int' = 45) -> 'str'
Returns a condensed version of help string.
:meta private:
make_str(value: 't.Any') -> 'str'
Converts a value into a valid string.
open_file(filename: 'str | os.PathLike[str]', mode: 'str' = 'r', encoding: 'str | None' = None, errors: 'str | None' = 'strict', lazy: 'bool' = False, atomic: 'bool' = False) -> 't.IO[t.Any]'
Open a file, with extra behavior to handle ``'-'`` to indicate
a standard stream, lazy open on write, and atomic write. Similar to
the behavior of the :class:`~click.File` param type.
If ``'-'`` is given to open ``stdout`` or ``stdin``, the stream is
wrapped so that using it in a context manager will not close it.
This makes it possible to use the function without accidentally
closing a standard stream:
.. code-block:: python
with open_file(filename) as f:
...
:param filename: The name or Path of the file to open, or ``'-'`` for
``stdin``/``stdout``.
:param mode: The mode in which to open the file.
:param encoding: The encoding to decode or encode a file opened in
text mode.
:param errors: The error handling mode.
:param lazy: Wait to open the file until it is accessed. For read
mode, the file is temporarily opened to raise access errors
early, then closed until it is read again.
:param atomic: Write to a temporary file and replace the given file
on close.
.. versionadded:: 3.0
safecall(func: 't.Callable[P, R]') -> 't.Callable[P, R | None]'
Wraps a function so that it swallows exceptions.
DATA
R = ~R
WIN = True
binary_streams = {'stderr': <function get_binary_stderr>, 'stdin': <fu...
text_streams = {'stderr': <function get_text_stderr>, 'stdin': <functi...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\click\utils.py
click.version_option
Python Library Documentation: function version_option in module click.decorators
version_option(version: 'str | None' = None, *param_decls: 'str', package_name: 'str | None' = None, prog_name: 'str | None' = None, message: 'str | None' = None, **kwargs: 't.Any') -> 't.Callable[[FC], FC]'
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
:func:`importlib.metadata.version` to get the version for the
``package_name``.
If ``package_name`` is not provided, Click will try to detect it by
inspecting the stack frames. If the detected (or given) name does
not match an installed distribution, Click resolves it as an import
(top-level module) name via
:func:`importlib.metadata.packages_distributions`, so e.g. ``PIL``
resolves to the ``Pillow`` distribution.
:param version: The version number to show. If not provided, Click
will try to detect it.
:param param_decls: One or more option names. Defaults to the single
value ``"--version"``.
:param package_name: The package name to detect the version from. If
not provided, Click will try to detect it.
:param prog_name: The name of the CLI to show in the message. If not
provided, it will be detected from the command.
:param message: The message to show. The values ``%(prog)s``,
``%(package)s``, and ``%(version)s`` are available. Defaults to
``"%(prog)s, version %(version)s"``.
:param kwargs: Extra arguments are passed to :func:`option`.
:raise RuntimeError: ``version`` could not be detected.
.. versionchanged:: 8.0
Add the ``package_name`` parameter, and the ``%(package)s``
value for messages.
.. versionchanged:: 8.0
Use :mod:`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=``.
.. versionchanged:: 8.4.2
When ``package_name`` does not match an installed distribution,
Click now resolves it as an import (top-level module).
click.wrap_text
Python Library Documentation: function wrap_text in module click.formatting
wrap_text(text: 'str', width: 'int' = 78, initial_indent: 'str' = '', subsequent_indent: 'str' = '', preserve_paragraphs: 'bool' = False) -> 'str'
A helper function that intelligently wraps text. By default, it
assumes that it operates on a single paragraph of text but if the
`preserve_paragraphs` parameter is provided it will intelligently
handle paragraphs (defined by two empty lines).
If paragraphs are handled, a paragraph can be prefixed with an empty
line containing the ``\b`` character (``\x08``) to indicate that
no rewrapping should happen in that block.
:param text: the text that should be rewrapped.
:param width: the maximum width for the text.
:param initial_indent: the initial indent that should be placed on the
first line as a string.
:param subsequent_indent: the indent string that should be placed on
each consecutive line.
:param preserve_paragraphs: if this flag is set then the wrapping will
intelligently handle paragraphs.
.. versionchanged:: 8.4.0
Width is measured in visible characters. ANSI escape sequences in
``text``, ``initial_indent``, or ``subsequent_indent`` no longer
count toward the width budget, so styled input wraps based on what
the user sees instead of raw byte length.