click.core.Option Class Reference

Inheritance diagram for click.core.Option:

Collaboration diagram for click.core.Option:

Public Member Functions
None	__init__ (self, cabc.Sequence[str]|None param_decls=None, bool|str|None show_default=None, bool|str prompt=False, bool|str confirmation_prompt=False, bool prompt_required=True, bool hide_input=False, bool|None is_flag=None, t.Any flag_value=UNSET, bool multiple=False, bool count=False, bool allow_from_autoenv=True, types.ParamType|t.Any|None type=None, str|None help=None, bool hidden=False, bool show_choices=True, bool show_envvar=False, bool|str deprecated=False, **t.Any attrs)
dict[str, t.Any]	to_info_dict (self)
str	get_error_hint (self, Context ctx)
None	add_to_parser (self, _OptionParser parser, Context ctx)
tuple[str, str]|None	get_help_record (self, Context ctx)
types.OptionHelpExtra	get_help_extra (self, Context ctx)
t.Any	prompt_for_value (self, Context ctx)
str|None	resolve_envvar_value (self, Context ctx)
t.Any	value_from_envvar (self, Context ctx)
tuple[t.Any, ParameterSource]	consume_value (self, Context ctx, cabc.Mapping[str, Parameter] opts)
t.Any	process_value (self, Context ctx, t.Any value)
Public Member Functions inherited from click.core.Parameter
str	__repr__ (self)
str	human_readable_name (self)
str	make_metavar (self, Context ctx)
t.Any|None	get_default (self, Context ctx, t.Literal[True] call=True)
t.Any|t.Callable[[], t.Any]|None	get_default (self, Context ctx, bool call=...)
t.Any|t.Callable[[], t.Any]|None	get_default (self, Context ctx, bool call=True)
t.Any	type_cast_value (self, Context ctx, t.Any value)
bool	value_is_missing (self, t.Any value)
tuple[t.Any, list[str]]	handle_parse_result (self, Context ctx, cabc.Mapping[str, t.Any] opts, list[str] args)
list[str]	get_usage_pieces (self, Context ctx)
list[CompletionItem]	shell_complete (self, Context ctx, str incomplete)

Public Attributes
	prompt
	confirmation_prompt
	prompt_required
	hide_input
	hidden
	default
	type
	flag_value
	count
	allow_from_autoenv
	help
	show_default
	show_choices
	show_envvar
	nargs
	secondary_opts
Public Attributes inherited from click.core.Parameter
	name
	opts
	secondary_opts
	required
	callback
	nargs
	multiple
	expose_value
	is_eager
	metavar
	envvar
	deprecated
	param_type_name

Static Public Attributes
str	param_type_name = "option"
Static Public Attributes inherited from click.core.Parameter
str	param_type_name = "parameter"

Protected Member Functions
tuple[str|None, list[str], list[str]]	_parse_decls (self, cabc.Sequence[str] decls, bool expose_value)

Protected Attributes
	_flag_needs_value
Protected Attributes inherited from click.core.Parameter
	_custom_shell_complete

Detailed Description

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.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.

Constructor & Destructor Documentation

__init__()

None click.core.Option.__init__	(		self,
		cabc.Sequence[str] | None	param_decls = None,
		bool | str | None	show_default = None,
		bool | str	prompt = False,
		bool | str	confirmation_prompt = False,
		bool	prompt_required = True,
		bool	hide_input = False,
		bool | None	is_flag = None,
		t.Any	flag_value = UNSET,
		bool	multiple = False,
		bool	count = False,
		bool	allow_from_autoenv = True,
		types.ParamType | t.Any | None	type = None,
		str | None	help = None,
		bool	hidden = False,
		bool	show_choices = True,
		bool	show_envvar = False,
		bool | str	deprecated = False,
		**t.Any	attrs
	)

Reimplemented from click.core.Parameter.

Member Function Documentation

_parse_decls()

tuple[str | None, list[str], list[str]] click.core.Option._parse_decls (   self, cabc.Sequence[str]  decls, bool   expose_value  )

protected

Reimplemented from click.core.Parameter.

add_to_parser()

None click.core.Option.add_to_parser	(		self,
		_OptionParser	parser,
		Context	ctx
	)

Reimplemented from click.core.Parameter.

consume_value()

tuple[t.Any, ParameterSource] click.core.Option.consume_value	(		self,
		Context	ctx,
		cabc.Mapping[str, Parameter]	opts
	)

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:

Reimplemented from click.core.Parameter.

get_error_hint()

str click.core.Option.get_error_hint	(		self,
		Context	ctx
	)

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

Reimplemented from click.core.Parameter.

get_help_record()

tuple[str, str] | None click.core.Option.get_help_record	(		self,
		Context	ctx
	)

Reimplemented from click.core.Parameter.

process_value()

t.Any click.core.Option.process_value	(		self,
		Context	ctx,
		t.Any	value
	)

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:

Reimplemented from click.core.Parameter.

prompt_for_value()

t.Any click.core.Option.prompt_for_value	(		self,
		Context	ctx
	)

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()

str | None click.core.Option.resolve_envvar_value	(		self,
		Context	ctx
	)

: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:

Reimplemented from click.core.Parameter.

to_info_dict()

dict[str, t.Any] click.core.Option.to_info_dict

(

self

)

.. versionchanged:: 8.3.0
    Returns ``None`` for the :attr:`flag_value` if it was not set.

Reimplemented from click.core.Parameter.

value_from_envvar()

t.Any click.core.Option.value_from_envvar	(		self,
		Context	ctx
	)

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:

Reimplemented from click.core.Parameter.

---

The documentation for this class was generated from the following file:

• docs/help/help-venv/lib/python3.12/site-packages/click/core.py