click.core.Command Class Reference

Inheritance diagram for click.core.Command:

Public Member Functions
None	__init__ (self, str|None name, cabc.MutableMapping[str, t.Any]|None context_settings=None, t.Callable[..., t.Any]|None callback=None, list[Parameter]|None params=None, str|None help=None, str|None epilog=None, str|None short_help=None, str|None options_metavar="[OPTIONS]", bool add_help_option=True, bool no_args_is_help=False, bool hidden=False, bool|str deprecated=False)
dict[str, t.Any]	to_info_dict (self, Context ctx)
str	__repr__ (self)
str	get_usage (self, Context ctx)
list[Parameter]	get_params (self, Context ctx)
None	format_usage (self, Context ctx, HelpFormatter formatter)
list[str]	collect_usage_pieces (self, Context ctx)
list[str]	get_help_option_names (self, Context ctx)
Option|None	get_help_option (self, Context ctx)
_OptionParser	make_parser (self, Context ctx)
str	get_help (self, Context ctx)
str	get_short_help_str (self, int limit=45)
None	format_help (self, Context ctx, HelpFormatter formatter)
None	format_help_text (self, Context ctx, HelpFormatter formatter)
None	format_options (self, Context ctx, HelpFormatter formatter)
None	format_epilog (self, Context ctx, HelpFormatter formatter)
Context	make_context (self, str|None info_name, list[str] args, Context|None parent=None, **t.Any extra)
list[str]	parse_args (self, Context ctx, list[str] args)
t.Any	invoke (self, Context ctx)
list[CompletionItem]	shell_complete (self, Context ctx, str incomplete)
t.NoReturn	main (self, cabc.Sequence[str]|None args=None, str|None prog_name=None, str|None complete_var=None, t.Literal[True] standalone_mode=True, **t.Any extra)
t.Any	main (self, cabc.Sequence[str]|None args=None, str|None prog_name=None, str|None complete_var=None, bool standalone_mode=..., **t.Any extra)
t.Any	main (self, cabc.Sequence[str]|None args=None, str|None prog_name=None, str|None complete_var=None, bool standalone_mode=True, bool windows_expand_args=True, **t.Any extra)
t.Any	__call__ (self, *t.Any args, **t.Any kwargs)

Public Attributes
	name
	callback
	help
	epilog
	options_metavar
	short_help
	add_help_option
	no_args_is_help
	hidden
	deprecated

Static Public Attributes
type	context_class = Context
bool	allow_extra_args = False
bool	allow_interspersed_args = True
bool	ignore_unknown_options = False

Protected Member Functions
None	_main_shell_completion (self, cabc.MutableMapping[str, t.Any] ctx_args, str prog_name, str|None complete_var=None)

Protected Attributes
	_help_option

Detailed Description

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.

Member Function Documentation

__call__()

t.Any click.core.Command.__call__	(		self,
		*t.Any	args,
		**t.Any	kwargs
	)

Alias for :meth:`main`.

_main_shell_completion()

None click.core.Command._main_shell_completion (   self, cabc.MutableMapping[str, t.Any]  ctx_args, str  prog_name, str | None   complete_var = None  )

protected

Check if the shell is asking for tab completion, process
that, then exit early. Called from :meth:`main` before the
program is invoked.

:param prog_name: Name of the executable in the shell.
:param complete_var: Name of the environment variable that holds
    the completion instruction. Defaults to
    ``_{PROG_NAME}_COMPLETE``.

.. versionchanged:: 8.2.0
    Dots (``.``) in ``prog_name`` are replaced with underscores (``_``).

collect_usage_pieces()

list[str] click.core.Command.collect_usage_pieces	(		self,
		Context	ctx
	)

Returns all the pieces that go into the usage line and returns
it as a list of strings.

Reimplemented in click.core.Group.

format_epilog()

None click.core.Command.format_epilog	(		self,
		Context	ctx,
		HelpFormatter	formatter
	)

Writes the epilog into the formatter if it exists.

format_help()

None click.core.Command.format_help	(		self,
		Context	ctx,
		HelpFormatter	formatter
	)

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

None click.core.Command.format_help_text	(		self,
		Context	ctx,
		HelpFormatter	formatter
	)

Writes the help text to the formatter if it exists.

format_options()

None click.core.Command.format_options	(		self,
		Context	ctx,
		HelpFormatter	formatter
	)

Writes all the options into the formatter if they exist.

Reimplemented in click.core.Group.

format_usage()

None click.core.Command.format_usage	(		self,
		Context	ctx,
		HelpFormatter	formatter
	)

Writes the usage line into the formatter.

This is a low-level method called by :meth:`get_usage`.

get_help()

str click.core.Command.get_help	(		self,
		Context	ctx
	)

Formats the help into a string and returns it.

Calls :meth:`format_help` internally.

get_help_option()

Option | None click.core.Command.get_help_option	(		self,
		Context	ctx
	)

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

list[str] click.core.Command.get_help_option_names	(		self,
		Context	ctx
	)

Returns the names for the help option.

get_short_help_str()

str click.core.Command.get_short_help_str	(		self,
		int	limit = 45
	)

Gets short help for the command or makes it by shortening the
long help string.

get_usage()

str click.core.Command.get_usage	(		self,
		Context	ctx
	)

Formats the usage line into a string and returns it.

Calls :meth:`format_usage` internally.

invoke()

t.Any click.core.Command.invoke	(		self,
		Context	ctx
	)

Given a context, this invokes the attached callback (if it exists)
in the right way.

Reimplemented in click.core.Group.

main()

t.Any click.core.Command.main	(		self,
		cabc.Sequence[str] | None	args = None,
		str | None	prog_name = None,
		str | None	complete_var = None,
		bool	standalone_mode = True,
		bool	windows_expand_args = True,
		**t.Any	extra
	)

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

Context click.core.Command.make_context	(		self,
		str | None	info_name,
		list[str]	args,
		Context | None	parent = None,
		**t.Any	extra
	)

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

_OptionParser click.core.Command.make_parser	(		self,
		Context	ctx
	)

Creates the underlying option parser for this command.

shell_complete()

list[CompletionItem] click.core.Command.shell_complete	(		self,
		Context	ctx,
		str	incomplete
	)

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

Reimplemented in click.core.Group.

---

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

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