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/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 b3604e750..7291a68c4 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. 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 (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 filename multiple times.""" + 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