From e2f2d84ef0bbcec4f024ea8ea21f3994eddde5f7 Mon Sep 17 00:00:00 2001 From: Edward G Date: Mon, 6 Jan 2025 22:23:15 -0800 Subject: [PATCH] Fill in a lot of missing command and group docs. --- docs/advanced.rst | 63 ++++++++++ docs/commands-and-groups.rst | 220 +++++++++++++++++++++++++++++++++++ docs/commands.rst | 123 +------------------- docs/index.rst | 1 + docs/parameters.rst | 2 + 5 files changed, 292 insertions(+), 117 deletions(-) create mode 100644 docs/commands-and-groups.rst diff --git a/docs/advanced.rst b/docs/advanced.rst index 2911eac55..f0fab20f9 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -7,6 +7,69 @@ In addition to common functionality that is implemented in the library itself, there are countless patterns that can be implemented by extending Click. This page should give some insight into what can be accomplished. +.. contents:: + :depth: 1 + :local: + +.. _custom-groups: + +Custom Groups +------------- + +You can customize the behavior of a group beyond the arguments it accepts by +subclassing :class:`click.Group`. + +The most common methods to override are :meth:`~click.Group.get_command` and +:meth:`~click.Group.list_commands`. + +The following example implements a basic plugin system that loads commands from +Python files in a folder. The command is lazily loaded to avoid slow startup. + +.. code-block:: python + + import importlib.util + import os + import click + + class PluginGroup(click.Group): + def __init__(self, name=None, plugin_folder="commands", **kwargs): + super().__init__(name=name, **kwargs) + self.plugin_folder = plugin_folder + + def list_commands(self, ctx): + rv = [] + + for filename in os.listdir(self.plugin_folder): + if filename.endswith(".py"): + rv.append(filename[:-3]) + + rv.sort() + return rv + + def get_command(self, ctx, name): + path = os.path.join(self.plugin_folder, f"{name}.py") + spec = importlib.util.spec_from_file_location(name, path) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module.cli + + cli = PluginGroup( + plugin_folder=os.path.join(os.path.dirname(__file__), "commands") + ) + + if __name__ == "__main__": + cli() + +Custom classes can also be used with decorators: + +.. code-block:: python + + @click.group( + cls=PluginGroup, + plugin_folder=os.path.join(os.path.dirname(__file__), "commands") + ) + def cli(): + pass .. _aliases: diff --git a/docs/commands-and-groups.rst b/docs/commands-and-groups.rst new file mode 100644 index 000000000..15bd0f44c --- /dev/null +++ b/docs/commands-and-groups.rst @@ -0,0 +1,220 @@ +Basic Commands, Groups, Context +================================ + +.. currentmodule:: click + +Commands and Groups are the building blocks for Click applications. :class:`Command` wraps a function to make it into a cli command. :class:`Group` wraps Commands and Groups to make them into applications. :class:`Context` is how groups and commands communicate. + +.. contents:: + :depth: 1 + :local: + +Basic Command Example +---------------------- +A simple command decorator takes no arguments. + +.. click:example:: + @click.command() + @click.option('--count', default=1) + def hello(count): + for x in range(count): + click.echo("Hello!") + +.. click:run:: + invoke(hello, args=['--count', '2',]) + +Renaming Commands +------------------ +By default the command is the function name with underscores replaced by dashes. To change this pass the desired name into the first positional argument. + +.. click:example:: + @click.command('say-hello') + @click.option('--count', default=1) + def hello(count): + for x in range(count): + click.echo("Hello!") + +.. click:run:: + invoke(hello, args=['--count', '2',]) + +Deprecating Commands +--------------------- +To mark a command as deprecated pass in ``deprecated=True`` + +.. click:example:: + @click.command('say-hello', deprecated=True) + @click.option('--count', default=1) + def hello(count): + for x in range(count): + click.echo("Hello!") + +.. click:run:: + invoke(hello, args=['--count', '2',]) + +Basic Group Example +--------------------- +A group wraps command(s). After being wrapped, the commands are nested under that group. You can see that on the help pages and in the execution. By default, invoking the group with no command shows the help page. + +.. click:example:: + @click.group() + def greeting(): + click.echo('Starting greeting ...') + + @greeting.command('say-hello') + @click.option('--count', default=1) + def hello(count): + for x in range(count): + click.echo("Hello!") + +At the top level: + +.. click:run:: + + invoke(greeting) + +At the command level: + +.. click:run:: + + invoke(greeting, args=['say-hello']) + invoke(greeting, args=['say-hello', '--help']) + +As you can see from the above example, the function wrapped by the group decorator executes unless it is interrupted (for example by calling the help). + +Renaming Groups +----------------- +To have a name other than the decorated function name as the group name, pass it in as the first positional argument. + +.. click:example:: + @click.group('greet_someone') + def greeting(): + click.echo('Starting greeting ...') + + @greeting.command('say-hello') + @click.option('--count', default=1) + def hello(count): + for x in range(count): + click.echo("Hello!") + +.. click:run:: + + invoke(greeting, args=['say-hello']) + +Group Invocation Without Command +-------------------------------- + +By default, a group is not invoked unless a subcommand is passed. In fact, not +providing a command automatically passes ``--help`` by default. This behavior +can be changed by passing ``invoke_without_command=True`` to a group. In that +case, the callback is always invoked instead of showing the help page. The +context object also includes information about whether or not the invocation +would go to a subcommand. + +.. click:example:: + + @click.group(invoke_without_command=True) + @click.pass_context + def cli(ctx): + if ctx.invoked_subcommand is None: + click.echo('I was invoked without subcommand') + else: + click.echo(f"I am about to invoke {ctx.invoked_subcommand}") + + @cli.command() + def sync(): + click.echo('The subcommand') + +.. click:run:: + + invoke(cli, prog_name='tool', args=[]) + invoke(cli, prog_name='tool', args=['sync']) + + + +Group Separation +-------------------------- +Within a group, command :ref:`parameters` attached to a command belong only to that command. + +.. click:example:: + @click.group() + def greeting(): + pass + + @greeting.command() + @click.option('--count', default=1) + def hello(count): + for x in range(count): + click.echo("Hello!") + + @greeting.command() + @click.option('--count', default=1) + def goodbye(count): + for x in range(count): + click.echo("Goodbye!") + +.. click:run:: + + invoke(greeting, args=['hello', '--count', '2']) + invoke(greeting, args=['goodbye', '--count', '2']) + invoke(greeting) + +Additionally parameters for a given group belong only to that group and not to the commands under it. What this means is that options and arguments for a specific command have to be specified *after* the command name itself, but *before* any other command names. + +This behavior is observable with the ``--help`` option. Suppose we have a group called ``tool`` containing a command called ``sub``. + +- ``tool --help`` returns the help for the whole program (listing subcommands). +- ``tool sub --help`` returns the help for the ``sub`` subcommand. +- But ``tool.py --help sub`` treats ``--help`` as an argument for the main program. Click then invokes the callback for ``--help``, which prints the help and aborts the program before click can process the subcommand. + +Arbitrary Nesting +------------------ +Commands are attached to a group. Multiple groups can be attached to another group. Groups containing multiple groups can be attached to a group, and so on. +To invoke a command nest under multiple groups, all the above groups must added. + +.. click:example:: + + @click.group() + def cli(): + pass + + # Not @click so that the group is registered now. + @cli.group() + def session(): + click.echo('Starting session') + + @session.command() + def initdb(): + click.echo('Initialized the database') + + @session.command() + def dropdb(): + click.echo('Dropped the database') + +.. click:run:: + + invoke(cli, args=['session', 'initdb']) + +Lazily Attaching Commands +-------------------------- +Most examples so far have attached the the commands and group immediately, but commands may be registered later. This could be used to split command into multiple Python modules. + +.. click:example:: + + @click.group() + def cli(): + pass + + @click.command() + def initdb(): + click.echo('Initialized the database') + + @click.command() + def dropdb(): + click.echo('Dropped the database') + + cli.add_command(initdb) + cli.add_command(dropdb) + +Context Object +------------------- +The :class:`Context` object ... diff --git a/docs/commands.rst b/docs/commands.rst index 5fe24067f..53a1c3a46 100644 --- a/docs/commands.rst +++ b/docs/commands.rst @@ -1,12 +1,13 @@ -Commands and Groups -=================== +Advanced Groups and Context +============================= .. currentmodule:: click -The structure of a Click application is defined with :class:`Command`, which -defines an individual named command, and :class:`Group`, which defines a nested -collection of commands (or more groups) under a name. +In addition to the capabilities covered in the previous section, Groups have more advanced capabilities that leverage the Context. +.. contents:: + :depth: 1 + :local: Callback Invocation ------------------- @@ -39,26 +40,6 @@ Here is what this looks like: println() invoke(cli, prog_name='tool.py', args=['--debug', 'sync']) -Passing Parameters ------------------- - -Click strictly separates parameters between commands and subcommands. What this -means is that options and arguments for a specific command have to be specified -*after* the command name itself, but *before* any other command names. - -This behavior is already observable with the predefined ``--help`` option. -Suppose we have a program called ``tool.py``, containing a subcommand called -``sub``. - -- ``tool.py --help`` will return the help for the whole program (listing - subcommands). - -- ``tool.py sub --help`` will return the help for the ``sub`` subcommand. - -- But ``tool.py --help sub`` will treat ``--help`` as an argument for the main - program. Click then invokes the callback for ``--help``, which prints the - help and aborts the program before click can process the subcommand. - Nested Handling and Contexts ---------------------------- @@ -144,98 +125,6 @@ obj)`` or ``f(obj)`` depending on whether or not it itself is decorated with This is a very powerful concept that can be used to build very complex nested applications; see :ref:`complex-guide` for more information. - -Group Invocation Without Command --------------------------------- - -By default, a group is not invoked unless a subcommand is passed. In fact, not -providing a command automatically passes ``--help`` by default. This behavior -can be changed by passing ``invoke_without_command=True`` to a group. In that -case, the callback is always invoked instead of showing the help page. The -context object also includes information about whether or not the invocation -would go to a subcommand. - -.. click:example:: - - @click.group(invoke_without_command=True) - @click.pass_context - def cli(ctx): - if ctx.invoked_subcommand is None: - click.echo('I was invoked without subcommand') - else: - click.echo(f"I am about to invoke {ctx.invoked_subcommand}") - - @cli.command() - def sync(): - click.echo('The subcommand') - -.. click:run:: - - invoke(cli, prog_name='tool', args=[]) - invoke(cli, prog_name='tool', args=['sync']) - - -.. _custom-groups: - -Custom Groups -------------- - -You can customize the behavior of a group beyond the arguments it accepts by -subclassing :class:`click.Group`. - -The most common methods to override are :meth:`~click.Group.get_command` and -:meth:`~click.Group.list_commands`. - -The following example implements a basic plugin system that loads commands from -Python files in a folder. The command is lazily loaded to avoid slow startup. - -.. code-block:: python - - import importlib.util - import os - import click - - class PluginGroup(click.Group): - def __init__(self, name=None, plugin_folder="commands", **kwargs): - super().__init__(name=name, **kwargs) - self.plugin_folder = plugin_folder - - def list_commands(self, ctx): - rv = [] - - for filename in os.listdir(self.plugin_folder): - if filename.endswith(".py"): - rv.append(filename[:-3]) - - rv.sort() - return rv - - def get_command(self, ctx, name): - path = os.path.join(self.plugin_folder, f"{name}.py") - spec = importlib.util.spec_from_file_location(name, path) - module = importlib.util.module_from_spec(spec) - spec.loader.exec_module(module) - return module.cli - - cli = PluginGroup( - plugin_folder=os.path.join(os.path.dirname(__file__), "commands") - ) - - if __name__ == "__main__": - cli() - -Custom classes can also be used with decorators: - -.. code-block:: python - - @click.group( - cls=PluginGroup, - plugin_folder=os.path.join(os.path.dirname(__file__), "commands") - ) - def cli(): - pass - - .. _command-chaining: Command Chaining diff --git a/docs/index.rst b/docs/index.rst index 0232587d7..e03f0f660 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -74,6 +74,7 @@ usage patterns. parameters arguments options + commands-and-groups commands documentation prompts diff --git a/docs/parameters.rst b/docs/parameters.rst index 7291a68c4..3caac4780 100644 --- a/docs/parameters.rst +++ b/docs/parameters.rst @@ -1,3 +1,5 @@ +.. _parameters: + Parameters ==========