From c438e1a14f325808f3e87b4ebc3ad7fbacac8439 Mon Sep 17 00:00:00 2001 From: unknown Date: Sat, 12 Aug 2023 00:54:46 -0700 Subject: [PATCH 1/3] Clean up parameters intro. --- docs/arguments.rst | 3 ++ docs/parameters.rst | 112 +++++++++++++++++++++----------------------- 2 files changed, 56 insertions(+), 59 deletions(-) diff --git a/docs/arguments.rst b/docs/arguments.rst index 60b53c558..5b877d82e 100644 --- a/docs/arguments.rst +++ b/docs/arguments.rst @@ -183,6 +183,9 @@ 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. + +.. _environment-variables: + Environment Variables --------------------- diff --git a/docs/parameters.rst b/docs/parameters.rst index b3604e750..260a18931 100644 --- a/docs/parameters.rst +++ b/docs/parameters.rst @@ -3,39 +3,60 @@ Parameters .. currentmodule:: click -Click supports two types of parameters for scripts: options and arguments. -There is generally some confusion among authors of command line scripts of -when to use which, so here is a quick overview of the differences. As its -name indicates, an option is optional. While arguments can be optional -within reason, they are much more restricted in how optional they can be. - -To help you decide between options and arguments, the recommendation is -to use arguments exclusively for things like going to subcommands or input -filenames / URLs, and have everything else be an option instead. - -Differences ------------ - -Arguments can do less than options. The following features are only -available for options: - -* automatic prompting for missing input -* act as flags (boolean or otherwise) -* option values can be pulled from environment variables, arguments can not -* options are fully documented in the help page, arguments are not - (:ref:`this is intentional ` as arguments - might be too specific to be automatically documented) - -On the other hand arguments, unlike options, can accept an arbitrary number -of arguments. Options can strictly ever only accept a fixed number of -arguments (defaults to 1), or they may be specified multiple times using -:ref:`multiple-options`. +Click supports only two types of parameters for scripts (by design): options and arguments. + +Options +---------------- + +* are optional. +* Recommended to use for everything except subcommands, urls, or files. +* Can take a fixed number of arguments. The default is 1. They may be specified multiple times using :ref:`multiple-options`. +* Are fully documented by the help page. +* Have automatic prompting for missing input. +* Can act as flags (boolean or otherwise). +* Can be pulled from environment variables. + +Arguments +---------------- + +* are optional with in reason, but not entirely so. +* Recommended to use for subcommands, urls, or files. +* Can take an arbitrary number of arguments. +* Are not fully documented by the help page since they may be too specific to be automatically documented. How to document args is covered in :ref:`documenting args section `. +* Can be pulled from environment variables but only explicitly named ones. See :ref:`environment-variables` for further explanation. + +.. _parameter_names: + +Parameter Names +--------------- + +Parameters (both options and arguments) have a name that will be used as +the Python argument name when calling the decorated function with +values. + +.. click:example:: + + @click.command() + @click.argument('filename') + @click.option('-t', '--times', type=int) + def multi_echo(filename, times): + """Print value of SRC environment variable.""" + for x in range(times): + click.echo(filename) + +In the above example the argument's name is ``filename``. The name must match the python arg name. To provide a different name for use in help text, see :ref:`doc-meta-variables`. +The option's names are ``-t`` and ``--times``. More names are available for options and are covered in :ref:`options`. + +And what it looks like when run: + +.. click:run:: + + invoke(multi_echo, ['--times=3', 'index.txt'], prog_name='multi_echo') Parameter Types --------------- -Parameters can be of different types. Types can be implemented with -different behavior and some are supported out of the box: +The supported parameter types are: ``str`` / :data:`click.STRING`: The default parameter type which indicates unicode strings. @@ -74,37 +95,10 @@ different behavior and some are supported out of the box: .. autoclass:: DateTime :noindex: -Custom parameter types can be implemented by subclassing -:class:`click.ParamType`. For simple cases, passing a Python function that -fails with a `ValueError` is also supported, though discouraged. - -.. _parameter_names: - -Parameter Names ---------------- - -Parameters (both options and arguments) have a name that will be used as -the Python argument name when calling the decorated function with -values. - -Arguments take only one positional name. To provide a different name for -use in help text, see :ref:`doc-meta-variables`. - -Options can have many names that may be prefixed with one or two dashes. -Names with one dash are parsed as short options, names with two are -parsed as long options. If a name is not prefixed, it is used as the -Python argument name and not parsed as an option name. Otherwise, the -first name with a two dash prefix is used, or the first with a one dash -prefix if there are none with two. The prefix is removed and dashes are -converted to underscores to get the Python argument name. - - -Implementing Custom Types -------------------------- +How to Implement Custom Types +------------------------------- -To implement a custom type, you need to subclass the :class:`ParamType` -class. Override the :meth:`~ParamType.convert` method to convert the -value from a string to the correct type. +To implement a custom type, you need to subclass the :class:`ParamType` class. For simple cases, passing a Python function that fails with a `ValueError` is also supported, though discouraged. Override the :meth:`~ParamType.convert` method to convert the value from a string to the correct type. The following code implements an integer type that accepts hex and octal numbers in addition to normal integers, and converts them into regular From 8d6604cbb349d5fc0e060f0c50fe4e0df51e3864 Mon Sep 17 00:00:00 2001 From: unknown Date: Sat, 12 Aug 2023 16:43:57 -0700 Subject: [PATCH 2/3] Fix a few typos. --- docs/documentation.rst | 2 +- docs/parameters.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/documentation.rst b/docs/documentation.rst index 349acfb83..da0aaa148 100644 --- a/docs/documentation.rst +++ b/docs/documentation.rst @@ -36,7 +36,7 @@ And what it looks like: .. _documenting-arguments: Documenting Arguments -~~~~~~~~~~~~~~~~~~~~~ +---------------------- :func:`click.argument` does not take a ``help`` parameter. This is to follow the general convention of Unix tools of using arguments for only diff --git a/docs/parameters.rst b/docs/parameters.rst index 260a18931..ca7dcb6ac 100644 --- a/docs/parameters.rst +++ b/docs/parameters.rst @@ -22,15 +22,15 @@ Arguments * are optional with in reason, but not entirely so. * Recommended to use for subcommands, urls, or files. * Can take an arbitrary number of arguments. -* Are not fully documented by the help page since they may be too specific to be automatically documented. How to document args is covered in :ref:`documenting args section `. -* Can be pulled from environment variables but only explicitly named ones. See :ref:`environment-variables` for further explanation. +* Are not fully documented by the help page since they may be too specific to be automatically documented. For more see :ref:`documenting-arguments`. +* Can be pulled from environment variables but only explicitly named ones. For more see :ref:`environment-variables`. .. _parameter_names: Parameter Names --------------- -Parameters (both options and arguments) have a name that will be used as +Parameters (options and arguments) have a name that will be used as the Python argument name when calling the decorated function with values. @@ -40,7 +40,7 @@ values. @click.argument('filename') @click.option('-t', '--times', type=int) def multi_echo(filename, times): - """Print value of SRC environment variable.""" + """Print value filename multiple times.""" for x in range(times): click.echo(filename) From 2d5225441aa03cccca3c9c070ebea31ce18af68b Mon Sep 17 00:00:00 2001 From: unknown Date: Sun, 27 Aug 2023 16:43:20 -0700 Subject: [PATCH 3/3] Fix capitalization. --- docs/parameters.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/parameters.rst b/docs/parameters.rst index ca7dcb6ac..7291a68c4 100644 --- a/docs/parameters.rst +++ b/docs/parameters.rst @@ -8,7 +8,7 @@ Click supports only two types of parameters for scripts (by design): options an Options ---------------- -* are optional. +* Are optional. * Recommended to use for everything except subcommands, urls, or files. * Can take a fixed number of arguments. The default is 1. They may be specified multiple times using :ref:`multiple-options`. * Are fully documented by the help page. @@ -19,7 +19,7 @@ Options Arguments ---------------- -* are optional with in reason, but not entirely so. +* Are optional with in reason, but not entirely so. * Recommended to use for subcommands, urls, or files. * Can take an arbitrary number of arguments. * Are not fully documented by the help page since they may be too specific to be automatically documented. For more see :ref:`documenting-arguments`.