From 30e907c5473a2d01c35f246cd33b9b5faecb7824 Mon Sep 17 00:00:00 2001 From: unknown Date: Mon, 14 Aug 2023 00:27:27 -0700 Subject: [PATCH 1/9] Rough out changes to arguments section. --- .pre-commit-config.yaml | 6 +- CHANGES.rst | 46 ++------ docs/arguments.rst | 227 +++++++++------------------------------- docs/handling_files.rst | 110 +++++++++++++++++++ docs/index.rst | 1 + 5 files changed, 171 insertions(+), 219 deletions(-) create mode 100644 docs/handling_files.rst diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 573a7553b..23df1fe38 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -3,7 +3,7 @@ ci: autoupdate_schedule: monthly repos: - repo: https://github.com/asottile/pyupgrade - rev: v3.10.1 + rev: v3.7.0 hooks: - id: pyupgrade args: ["--py37-plus"] @@ -13,11 +13,11 @@ repos: - id: reorder-python-imports args: ["--application-directories", "src"] - repo: https://github.com/psf/black - rev: 23.7.0 + rev: 23.3.0 hooks: - id: black - repo: https://github.com/PyCQA/flake8 - rev: 6.1.0 + rev: 6.0.0 hooks: - id: flake8 additional_dependencies: diff --git a/CHANGES.rst b/CHANGES.rst index 77dceb568..599394f9a 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,55 +1,25 @@ .. currentmodule:: click -Version 8.1.6 +Version 8.2.0 ------------- -Released 2023-07-18 +Unreleased -- Fix an issue with type hints for ``@click.group()``. :issue:`2558` - - -Version 8.1.5 -------------- - -Released 2023-07-13 - -- Fix an issue with type hints for ``@click.command()``, ``@click.option()``, and - other decorators. Introduce typing tests. :issue:`2558` +- Use modern packaging metadata with ``pyproject.toml`` instead of ``setup.cfg``. + :pr:`326` +- Use ``flit_core`` instead of ``setuptools`` as build backend. Version 8.1.4 ------------- -Released 2023-07-06 +Unreleased - Replace all ``typing.Dict`` occurrences to ``typing.MutableMapping`` for - parameter hints. :issue:`2255` + parameter hints. :issue:`2255` - Improve type hinting for decorators and give all generic types parameters. :issue:`2398` -- Fix return value and type signature of `shell_completion.add_completion_class` - function. :pr:`2421` -- Bash version detection doesn't fail on Windows. :issue:`2461` -- Completion works if there is a dot (``.``) in the program name. :issue:`2166` -- Improve type annotations for pyright type checker. :issue:`2268` -- Improve responsiveness of ``click.clear()``. :issue:`2284` -- Improve command name detection when using Shiv or PEX. :issue:`2332` -- Avoid showing empty lines if command help text is empty. :issue:`2368` -- ZSH completion script works when loaded from ``fpath``. :issue:`2344`. -- ``EOFError`` and ``KeyboardInterrupt`` tracebacks are not suppressed when - ``standalone_mode`` is disabled. :issue:`2380` -- ``@group.command`` does not fail if the group was created with a custom - ``command_class``. :issue:`2416` -- ``multiple=True`` is allowed for flag options again and does not require - setting ``default=()``. :issue:`2246, 2292, 2295` -- Make the decorators returned by ``@argument()`` and ``@option()`` reusable when the - ``cls`` parameter is used. :issue:`2294` -- Don't fail when writing filenames to streams with strict errors. Replace invalid - bytes with the replacement character (``�``). :issue:`2395` -- Remove unnecessary attempt to detect MSYS2 environment. :issue:`2355` -- Remove outdated and unnecessary detection of App Engine environment. :pr:`2554` -- ``echo()`` does not fail when no streams are attached, such as with ``pythonw`` on - Windows. :issue:`2415` -- Argument with ``expose_value=False`` do not cause completion to fail. :issue:`2336` +- Fix return value and type signature of `shell_completion.add_completion_class` function. :pr:`2421` Version 8.1.3 diff --git a/docs/arguments.rst b/docs/arguments.rst index 60b53c558..41611f30b 100644 --- a/docs/arguments.rst +++ b/docs/arguments.rst @@ -5,18 +5,22 @@ Arguments .. currentmodule:: click -Arguments work similarly to :ref:`options ` but are positional. -They also only support a subset of the features of options due to their -syntactical nature. Click will also not attempt to document arguments for -you and wants you to :ref:`document them manually ` -in order to avoid ugly help pages. +Arguments : -Basic Arguments +* are positional in nature +* are very much like a limited version of :ref:`options ` +* but also can take an arbitrary number of inputs +* must be :ref:`documented manually ` + +Useful and often used kwargs are: + +* ``default`` : passes a default +* ``nargs`` : Sets the number of arguments. Set to -1 to take an arbitrary number. + +Basic Argument --------------- -The most basic option is a simple string argument of one value. If no -type is provided, the type of the default value is used, and if no default -value is provided, the type is assumed to be :data:`STRING`. +A minimal :class:`click.Argument` takes the name of function argument. If you just pass it this, it assumes 1 argument, required, no default and string type. Example: @@ -34,161 +38,81 @@ And what it looks like: invoke(touch, args=['foo.txt']) -Variadic Arguments ------------------- -The second most common version is variadic arguments where a specific (or -unlimited) number of arguments is accepted. This can be controlled with -the ``nargs`` parameter. If it is set to ``-1``, then an unlimited number -of arguments is accepted. +Not sure if should include : If no type is provided, the type of the default value is used, and if no default value is provided, the type is assumed to be STRING. -The value is then passed as a tuple. Note that only one argument can be -set to ``nargs=-1``, as it will eat up all arguments. +Multiple Arguments +----------------------------------- -Example: +To set the number of argument use the ``nargs`` kwarg. It can be set to any positive integer and -1. Setting it to -1, makes the number of arguments arbitrary (which is called variadic) and can only be used once. The arguments are then packed as a tuple and passed to the function. .. click:example:: @click.command() - @click.argument('src', nargs=-1) - @click.argument('dst', nargs=1) - def copy(src, dst): + @click.argument('src', nargs=1) + @click.argument('dsts', nargs=-1) + def copy(src, dsts): """Move file SRC to DST.""" - for fn in src: - click.echo(f"move {fn} to folder {dst}") + for destination in dsts: + click.echo(f"Copy {src} to folder {destination}") And what it looks like: .. click:run:: - invoke(copy, args=['foo.txt', 'bar.txt', 'my_folder']) - -Note that this is not how you would write this application. The reason -for this is that in this particular example the arguments are defined as -strings. Filenames, however, are not strings! They might be on certain -operating systems, but not necessarily on all. For better ways to write -this, see the next sections. + invoke(copy, args=['foo.txt', 'usr/david/foo.txt', 'usr/mitsuko/foo.txt']) -.. admonition:: Note on Non-Empty Variadic Arguments +Note this example is not how you would handle files and files paths, since it passes them in as strings. For more see :ref:`handling-files`. - If you come from ``argparse``, you might be missing support for setting - ``nargs`` to ``+`` to indicate that at least one argument is required. +.. admonition:: Note on Required Arguments - This is supported by setting ``required=True``. However, this should - not be used if you can avoid it as we believe scripts should gracefully - degrade into becoming noops if a variadic argument is empty. The - reason for this is that very often, scripts are invoked with wildcard - inputs from the command line and they should not error out if the - wildcard is empty. + It is not recommended, but you may make at least one argument required by setting ``required=True``. It is not recommended since we think command line tools should gracefully degrade into becoming noops. We think this because command line tools are often invoked with wildcard inputs and they should not error out if the wildcard is empty. -.. _file-args: -File Arguments --------------- -Since all the examples have already worked with filenames, it makes sense -to explain how to deal with files properly. Command line tools are more -fun if they work with files the Unix way, which is to accept ``-`` as a -special file that refers to stdin/stdout. +Argument Escape Sequences +--------------------------- -Click supports this through the :class:`click.File` type which -intelligently handles files for you. It also deals with Unicode and bytes -correctly for all versions of Python so your script stays very portable. +If you want to process arguments that look like options, like a file named ``-foo.txt``, you must pass the ``--`` separator first. After you pass the ``--``, you may only pass arguments. This is a common feature for POSIX command line tools. -Example: +Example usage: .. click:example:: @click.command() - @click.argument('input', type=click.File('rb')) - @click.argument('output', type=click.File('wb')) - def inout(input, output): - """Copy contents of INPUT to OUTPUT.""" - while True: - chunk = input.read(1024) - if not chunk: - break - output.write(chunk) - -And what it does: + @click.argument('files', nargs=-1, type=click.Path()) + def touch(files): + """Print all FILES file names.""" + for filename in files: + click.echo(filename) -.. click:run:: +And from the command line: - with isolated_filesystem(): - invoke(inout, args=['-', 'hello.txt'], input=['hello'], - terminate_input=True) - invoke(inout, args=['hello.txt', '-']) +.. click:run:: -File Path Arguments -------------------- + invoke(touch, ['--', '-foo.txt', 'bar.txt']) -In the previous example, the files were opened immediately. But what if -we just want the filename? The naïve way is to use the default string -argument type. The :class:`Path` type has several checks available which raise nice -errors if they fail, such as existence. Filenames in these error messages are formatted -with :func:`format_filename`, so any undecodable bytes will be printed nicely. - -Example: +If you don't like the ``--`` marker, you can set ignore_unknown_options to True to avoid checking unknown options: .. click:example:: - @click.command() - @click.argument('filename', type=click.Path(exists=True)) - def touch(filename): - """Print FILENAME if the file exists.""" - click.echo(click.format_filename(filename)) + @click.command(context_settings={"ignore_unknown_options": True}) + @click.argument('files', nargs=-1, type=click.Path()) + def touch(files): + """Print all FILES file names.""" + for filename in files: + click.echo(filename) -And what it does: +And from the command line: .. click:run:: - with isolated_filesystem(): - with open('hello.txt', 'w') as f: - f.write('Hello World!\n') - invoke(touch, args=['hello.txt']) - println() - invoke(touch, args=['missing.txt']) - - -File Opening Safety -------------------- - -The :class:`FileType` type has one problem it needs to deal with, and that -is to decide when to open a file. The default behavior is to be -"intelligent" about it. What this means is that it will open stdin/stdout -and files opened for reading immediately. This will give the user direct -feedback when a file cannot be opened, but it will only open files -for writing the first time an IO operation is performed by automatically -wrapping the file in a special wrapper. - -This behavior can be forced by passing ``lazy=True`` or ``lazy=False`` to -the constructor. If the file is opened lazily, it will fail its first IO -operation by raising an :exc:`FileError`. - -Since files opened for writing will typically immediately empty the file, -the lazy mode should only be disabled if the developer is absolutely sure -that this is intended behavior. - -Forcing lazy mode is also very useful to avoid resource handling -confusion. If a file is opened in lazy mode, it will receive a -``close_intelligently`` method that can help figure out if the file -needs closing or not. This is not needed for parameters, but is -necessary for manually prompting with the :func:`prompt` function as you -do not know if a stream like stdout was opened (which was already open -before) or a real file that needs closing. - -Starting with Click 2.0, it is also possible to open files in atomic mode by -passing ``atomic=True``. In atomic mode, all writes go into a separate -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. + invoke(touch, ['-foo.txt', 'bar.txt']) Environment Variables --------------------- -Like options, arguments can also grab values from an environment variable. -Unlike options, however, this is only supported for explicitly named -environment variables. +This feature is not recommended since it be confusing to users. Arguments can only pull environment variables from ? explicitly named environment variables. In that case, it can also be a list of different environment variables where the first one is picked. ? Example usage: @@ -207,57 +131,4 @@ And from the command line: with isolated_filesystem(): with open('hello.txt', 'w') as f: f.write('Hello World!') - invoke(echo, env={'SRC': 'hello.txt'}) - -In that case, it can also be a list of different environment variables -where the first one is picked. - -Generally, this feature is not recommended because it can cause the user -a lot of confusion. - -Option-Like Arguments ---------------------- - -Sometimes, you want to process arguments that look like options. For -instance, imagine you have a file named ``-foo.txt``. If you pass this as -an argument in this manner, Click will treat it as an option. - -To solve this, Click does what any POSIX style command line script does, -and that is to accept the string ``--`` as a separator for options and -arguments. After the ``--`` marker, all further parameters are accepted as -arguments. - -Example usage: - -.. click:example:: - - @click.command() - @click.argument('files', nargs=-1, type=click.Path()) - def touch(files): - """Print all FILES file names.""" - for filename in files: - click.echo(filename) - -And from the command line: - -.. click:run:: - - invoke(touch, ['--', '-foo.txt', 'bar.txt']) - -If you don't like the ``--`` marker, you can set ignore_unknown_options to -True to avoid checking unknown options: - -.. click:example:: - - @click.command(context_settings={"ignore_unknown_options": True}) - @click.argument('files', nargs=-1, type=click.Path()) - def touch(files): - """Print all FILES file names.""" - for filename in files: - click.echo(filename) - -And from the command line: - -.. click:run:: - - invoke(touch, ['-foo.txt', 'bar.txt']) + invoke(echo, env={'SRC': 'hello.txt'}) \ No newline at end of file diff --git a/docs/handling_files.rst b/docs/handling_files.rst new file mode 100644 index 000000000..efe6373e9 --- /dev/null +++ b/docs/handling_files.rst @@ -0,0 +1,110 @@ +.. _handling-files: + +Handling Files +================ + +.. currentmodule:: click + +File and files paths are often passed in as arguments. + +.. _file-args: + +File Arguments +-------------- + +Since all the examples have already worked with filenames, it makes sense +to explain how to deal with files properly. Command line tools are more +fun if they work with files the Unix way, which is to accept ``-`` as a +special file that refers to stdin/stdout. + +Click supports this through the :class:`click.File` type which +intelligently handles files for you. It also deals with Unicode and bytes +correctly for all versions of Python so your script stays very portable. + +Example: + +.. click:example:: + + @click.command() + @click.argument('input', type=click.File('rb')) + @click.argument('output', type=click.File('wb')) + def inout(input, output): + """Copy contents of INPUT to OUTPUT.""" + while True: + chunk = input.read(1024) + if not chunk: + break + output.write(chunk) + +And what it does: + +.. click:run:: + + with isolated_filesystem(): + invoke(inout, args=['-', 'hello.txt'], input=['hello'], + terminate_input=True) + invoke(inout, args=['hello.txt', '-']) + +File Path Arguments +------------------- + +In the previous example, the files were opened immediately. But what if +we just want the filename? The naïve way is to use the default string +argument type. The :class:`Path` type has several checks available which raise nice +errors if they fail, such as existence. Filenames in these error messages are formatted +with :func:`format_filename`, so any undecodable bytes will be printed nicely. + +Example: + +.. click:example:: + + @click.command() + @click.argument('filename', type=click.Path(exists=True)) + def touch(filename): + """Print FILENAME if the file exists.""" + click.echo(click.format_filename(filename)) + +And what it does: + +.. click:run:: + + with isolated_filesystem(): + with open('hello.txt', 'w') as f: + f.write('Hello World!\n') + invoke(touch, args=['hello.txt']) + println() + invoke(touch, args=['missing.txt']) + + +File Opening Safety +------------------- + +The :class:`FileType` type has one problem it needs to deal with, and that +is to decide when to open a file. The default behavior is to be +"intelligent" about it. What this means is that it will open stdin/stdout +and files opened for reading immediately. This will give the user direct +feedback when a file cannot be opened, but it will only open files +for writing the first time an IO operation is performed by automatically +wrapping the file in a special wrapper. + +This behavior can be forced by passing ``lazy=True`` or ``lazy=False`` to +the constructor. If the file is opened lazily, it will fail its first IO +operation by raising an :exc:`FileError`. + +Since files opened for writing will typically immediately empty the file, +the lazy mode should only be disabled if the developer is absolutely sure +that this is intended behavior. + +Forcing lazy mode is also very useful to avoid resource handling +confusion. If a file is opened in lazy mode, it will receive a +``close_intelligently`` method that can help figure out if the file +needs closing or not. This is not needed for parameters, but is +necessary for manually prompting with the :func:`prompt` function as you +do not know if a stream like stdout was opened (which was already open +before) or a real file that needs closing. + +Starting with Click 2.0, it is also possible to open files in atomic mode by +passing ``atomic=True``. In atomic mode, all writes go into a separate +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. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index ad965a36b..dfb719fac 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -72,6 +72,7 @@ usage patterns. parameters options arguments + handling_files commands prompts documentation From fb325a48fe501412d87fd716f0ca7d3c682cdda3 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 14 Aug 2023 07:36:52 +0000 Subject: [PATCH 2/9] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/arguments.rst | 18 +++++++++--------- docs/handling_files.rst | 4 ++-- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/arguments.rst b/docs/arguments.rst index 41611f30b..d1af0229f 100644 --- a/docs/arguments.rst +++ b/docs/arguments.rst @@ -5,17 +5,17 @@ Arguments .. currentmodule:: click -Arguments : +Arguments : -* are positional in nature +* are positional in nature * are very much like a limited version of :ref:`options ` -* but also can take an arbitrary number of inputs -* must be :ref:`documented manually ` +* but also can take an arbitrary number of inputs +* must be :ref:`documented manually ` -Useful and often used kwargs are: +Useful and often used kwargs are: * ``default`` : passes a default -* ``nargs`` : Sets the number of arguments. Set to -1 to take an arbitrary number. +* ``nargs`` : Sets the number of arguments. Set to -1 to take an arbitrary number. Basic Argument --------------- @@ -39,7 +39,7 @@ And what it looks like: invoke(touch, args=['foo.txt']) -Not sure if should include : If no type is provided, the type of the default value is used, and if no default value is provided, the type is assumed to be STRING. +Not sure if should include : If no type is provided, the type of the default value is used, and if no default value is provided, the type is assumed to be STRING. Multiple Arguments ----------------------------------- @@ -73,7 +73,7 @@ Note this example is not how you would handle files and files paths, since it pa Argument Escape Sequences --------------------------- -If you want to process arguments that look like options, like a file named ``-foo.txt``, you must pass the ``--`` separator first. After you pass the ``--``, you may only pass arguments. This is a common feature for POSIX command line tools. +If you want to process arguments that look like options, like a file named ``-foo.txt``, you must pass the ``--`` separator first. After you pass the ``--``, you may only pass arguments. This is a common feature for POSIX command line tools. Example usage: @@ -131,4 +131,4 @@ And from the command line: with isolated_filesystem(): with open('hello.txt', 'w') as f: f.write('Hello World!') - invoke(echo, env={'SRC': 'hello.txt'}) \ No newline at end of file + invoke(echo, env={'SRC': 'hello.txt'}) diff --git a/docs/handling_files.rst b/docs/handling_files.rst index efe6373e9..1e9288209 100644 --- a/docs/handling_files.rst +++ b/docs/handling_files.rst @@ -1,6 +1,6 @@ .. _handling-files: -Handling Files +Handling Files ================ .. currentmodule:: click @@ -107,4 +107,4 @@ Starting with Click 2.0, it is also possible to open files in atomic mode by passing ``atomic=True``. In atomic mode, all writes go into a separate 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. \ No newline at end of file +users is modified. From 63c03abb131c86d31377dc9a75e66a628dc0bd89 Mon Sep 17 00:00:00 2001 From: unknown Date: Mon, 14 Aug 2023 00:40:23 -0700 Subject: [PATCH 3/9] Revert random file changes made by git. --- .pre-commit-config.yaml | 6 +++--- CHANGES.rst | 46 ++++++++++++++++++++++++++++++++++------- docs/arguments.rst | 2 -- 3 files changed, 41 insertions(+), 13 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 23df1fe38..573a7553b 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -3,7 +3,7 @@ ci: autoupdate_schedule: monthly repos: - repo: https://github.com/asottile/pyupgrade - rev: v3.7.0 + rev: v3.10.1 hooks: - id: pyupgrade args: ["--py37-plus"] @@ -13,11 +13,11 @@ repos: - id: reorder-python-imports args: ["--application-directories", "src"] - repo: https://github.com/psf/black - rev: 23.3.0 + rev: 23.7.0 hooks: - id: black - repo: https://github.com/PyCQA/flake8 - rev: 6.0.0 + rev: 6.1.0 hooks: - id: flake8 additional_dependencies: diff --git a/CHANGES.rst b/CHANGES.rst index 599394f9a..77dceb568 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,25 +1,55 @@ .. currentmodule:: click -Version 8.2.0 +Version 8.1.6 ------------- -Unreleased +Released 2023-07-18 -- Use modern packaging metadata with ``pyproject.toml`` instead of ``setup.cfg``. - :pr:`326` -- Use ``flit_core`` instead of ``setuptools`` as build backend. +- Fix an issue with type hints for ``@click.group()``. :issue:`2558` + + +Version 8.1.5 +------------- + +Released 2023-07-13 + +- Fix an issue with type hints for ``@click.command()``, ``@click.option()``, and + other decorators. Introduce typing tests. :issue:`2558` Version 8.1.4 ------------- -Unreleased +Released 2023-07-06 - Replace all ``typing.Dict`` occurrences to ``typing.MutableMapping`` for - parameter hints. :issue:`2255` + parameter hints. :issue:`2255` - Improve type hinting for decorators and give all generic types parameters. :issue:`2398` -- Fix return value and type signature of `shell_completion.add_completion_class` function. :pr:`2421` +- Fix return value and type signature of `shell_completion.add_completion_class` + function. :pr:`2421` +- Bash version detection doesn't fail on Windows. :issue:`2461` +- Completion works if there is a dot (``.``) in the program name. :issue:`2166` +- Improve type annotations for pyright type checker. :issue:`2268` +- Improve responsiveness of ``click.clear()``. :issue:`2284` +- Improve command name detection when using Shiv or PEX. :issue:`2332` +- Avoid showing empty lines if command help text is empty. :issue:`2368` +- ZSH completion script works when loaded from ``fpath``. :issue:`2344`. +- ``EOFError`` and ``KeyboardInterrupt`` tracebacks are not suppressed when + ``standalone_mode`` is disabled. :issue:`2380` +- ``@group.command`` does not fail if the group was created with a custom + ``command_class``. :issue:`2416` +- ``multiple=True`` is allowed for flag options again and does not require + setting ``default=()``. :issue:`2246, 2292, 2295` +- Make the decorators returned by ``@argument()`` and ``@option()`` reusable when the + ``cls`` parameter is used. :issue:`2294` +- Don't fail when writing filenames to streams with strict errors. Replace invalid + bytes with the replacement character (``�``). :issue:`2395` +- Remove unnecessary attempt to detect MSYS2 environment. :issue:`2355` +- Remove outdated and unnecessary detection of App Engine environment. :pr:`2554` +- ``echo()`` does not fail when no streams are attached, such as with ``pythonw`` on + Windows. :issue:`2415` +- Argument with ``expose_value=False`` do not cause completion to fail. :issue:`2336` Version 8.1.3 diff --git a/docs/arguments.rst b/docs/arguments.rst index 41611f30b..cef7f04d3 100644 --- a/docs/arguments.rst +++ b/docs/arguments.rst @@ -68,8 +68,6 @@ Note this example is not how you would handle files and files paths, since it pa It is not recommended, but you may make at least one argument required by setting ``required=True``. It is not recommended since we think command line tools should gracefully degrade into becoming noops. We think this because command line tools are often invoked with wildcard inputs and they should not error out if the wildcard is empty. - - Argument Escape Sequences --------------------------- From f0f5ce1bd8fbe1aea5114ad5a3383074ec65ef42 Mon Sep 17 00:00:00 2001 From: unknown Date: Sun, 27 Aug 2023 23:35:15 -0700 Subject: [PATCH 4/9] Fix capitalization. --- docs/arguments.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/arguments.rst b/docs/arguments.rst index 9294bfa2d..10140a790 100644 --- a/docs/arguments.rst +++ b/docs/arguments.rst @@ -5,16 +5,16 @@ Arguments .. currentmodule:: click -Arguments : -* are positional in nature -* are very much like a limited version of :ref:`options ` -* but also can take an arbitrary number of inputs -* must be :ref:`documented manually ` + +* Are positional in nature +* Are very much like a limited version of :ref:`options ` +* But also can take an arbitrary number of inputs +* Must be :ref:`documented manually ` Useful and often used kwargs are: -* ``default`` : passes a default +* ``default`` : Passes a default * ``nargs`` : Sets the number of arguments. Set to -1 to take an arbitrary number. Basic Argument From 424d0e7e41d16307026d039e7e5304dc35a99163 Mon Sep 17 00:00:00 2001 From: unknown Date: Thu, 7 Nov 2024 22:58:20 -0800 Subject: [PATCH 5/9] Rewrite arguments docs more nicely. --- docs/arguments.rst | 22 +++++++++++----------- docs/index.rst | 2 +- docs/parameters.rst | 2 ++ 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/arguments.rst b/docs/arguments.rst index dabbc7ef1..77501c87e 100644 --- a/docs/arguments.rst +++ b/docs/arguments.rst @@ -5,12 +5,11 @@ Arguments .. currentmodule:: click - +Arguments are: * Are positional in nature -* Are very much like a limited version of :ref:`options ` -* But also can take an arbitrary number of inputs -* Must be :ref:`documented manually ` +* Similar to a limited version of :ref:`options ` that can take an arbitrary number of inputs +* :ref:`documented manually ` Useful and often used kwargs are: @@ -39,7 +38,11 @@ And what it looks like: invoke(touch, args=['foo.txt']) -Not sure if should include : If no type is provided, the type of the default value is used, and if no default value is provided, the type is assumed to be STRING. +An argument may be assigned a :ref:`parameter type `. If no type is provided, the type of the default value is used. If no default value is provided, the type is assumed to be STRING. + +.. admonition:: Note on Required Arguments + + It is possible to make an argument required by setting ``required=True``. It is not recommended since we think command line tools should gracefully degrade into becoming no ops. We think this because command line tools are often invoked with wildcard inputs and they should not error out if the wildcard is empty. Multiple Arguments ----------------------------------- @@ -62,16 +65,13 @@ And what it looks like: invoke(copy, args=['foo.txt', 'usr/david/foo.txt', 'usr/mitsuko/foo.txt']) -Note this example is not how you would handle files and files paths, since it passes them in as strings. For more see :ref:`handling-files`. - -.. admonition:: Note on Required Arguments - - It is not recommended, but you may make at least one argument required by setting ``required=True``. It is not recommended since we think command line tools should gracefully degrade into becoming noops. We think this because command line tools are often invoked with wildcard inputs and they should not error out if the wildcard is empty. +.. admonition:: Note on Handling Files. + This is not how you would handle files and files paths, since it passes them in as strings. For more see :ref:`handling-files`. Argument Escape Sequences --------------------------- -If you want to process arguments that look like options, like a file named ``-foo.txt``, you must pass the ``--`` separator first. After you pass the ``--``, you may only pass arguments. This is a common feature for POSIX command line tools. +If you want to process arguments that look like options, like a file named ``-foo.txt`` or ``--foo.txt`` , you must pass the ``--`` separator first. After you pass the ``--``, you may only pass arguments. This is a common feature for POSIX command line tools. Example usage: diff --git a/docs/index.rst b/docs/index.rst index 4f4565ae1..0e75e6a58 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -73,9 +73,9 @@ usage patterns. parameters options arguments - handling_files commands prompts + handling_files documentation complex advanced diff --git a/docs/parameters.rst b/docs/parameters.rst index 7291a68c4..6ce19b6ca 100644 --- a/docs/parameters.rst +++ b/docs/parameters.rst @@ -53,6 +53,8 @@ And what it looks like when run: invoke(multi_echo, ['--times=3', 'index.txt'], prog_name='multi_echo') +.. _parameter-types: + Parameter Types --------------- From e26d89d96abc43cf5b8613f0a239a3131e7a6bb8 Mon Sep 17 00:00:00 2001 From: unknown Date: Thu, 7 Nov 2024 23:03:45 -0800 Subject: [PATCH 6/9] Fix broken admonition block. --- docs/arguments.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/arguments.rst b/docs/arguments.rst index 77501c87e..df3993e00 100644 --- a/docs/arguments.rst +++ b/docs/arguments.rst @@ -66,6 +66,7 @@ And what it looks like: invoke(copy, args=['foo.txt', 'usr/david/foo.txt', 'usr/mitsuko/foo.txt']) .. admonition:: Note on Handling Files. + This is not how you would handle files and files paths, since it passes them in as strings. For more see :ref:`handling-files`. Argument Escape Sequences From 50bfe239e327d0d91c460226fb87489c8a9d6e50 Mon Sep 17 00:00:00 2001 From: unknown Date: Tue, 12 Nov 2024 23:36:44 -0800 Subject: [PATCH 7/9] Cleanup handling files documentation. --- docs/handling-files.rst | 89 ++++++++++++++++++++++++++++++++ docs/handling_files.rst | 110 ---------------------------------------- docs/index.rst | 2 +- src/click/types.py | 11 ++-- 4 files changed, 97 insertions(+), 115 deletions(-) create mode 100644 docs/handling-files.rst delete mode 100644 docs/handling_files.rst diff --git a/docs/handling-files.rst b/docs/handling-files.rst new file mode 100644 index 000000000..df011c29f --- /dev/null +++ b/docs/handling-files.rst @@ -0,0 +1,89 @@ +.. _handling-files: + +Handling Files +================ + +.. currentmodule:: click + +Click has built in features to support file and file path handling. Since files and files paths are recommended to be passed in as arguments, the examples use arguments. + +.. _file-args: + +File Arguments +----------------- + +Click supports working with files with the :class:`File` type. Some notable features are: + +* Support for ``-`` to mean a special file that refers to stdin/stdout. This is common pattern for POSIX command line utilities, for example wget. +* Deals with Unicode and bytes correctly for all versions of Python. + +Example: + +.. click:example:: + + @click.command() + @click.argument('input', type=click.File('rb')) + @click.argument('output', type=click.File('wb')) + def inout(input, output): + """Copy contents of INPUT to OUTPUT.""" + while True: + chunk = input.read(1024) + if not chunk: + break + output.write(chunk) + +And what it does: + +.. click:run:: + + with isolated_filesystem(): + invoke(inout, args=['-', 'hello.txt'], input=['hello'], + terminate_input=True) + invoke(inout, args=['hello.txt', '-']) + +File Path Arguments +---------------------- + +For handling paths, the :class:`Path` type is better than a string. Some notable features are: + +* It can run checks such as does the path exist or is the file executable. +* It also handles formatting error messages with :func:`format_filename` so any undecodable bytes will be printed nicely. + +Example: + +.. click:example:: + + @click.command() + @click.argument('filename', type=click.Path(exists=True)) + def touch(filename): + """Print FILENAME if the file exists.""" + click.echo(click.format_filename(filename)) + +And what it does: + +.. click:run:: + + with isolated_filesystem(): + with open('hello.txt', 'w') as f: + f.write('Hello World!\n') + invoke(touch, args=['hello.txt']) + println() + invoke(touch, args=['missing.txt']) + + +File Opening Behaviors +----------------------------- + +The :class:`File` type attempts to be "intelligent" about when to open a file. Stdin/stdout and files opened for reading will be opened immediately. This will give the user direct feedback when a file cannot be opened. Files opened for writing will only be open on the first IO operation. This is done by automatically wrapping the file in a special wrapper. + +File open behavior can be controlled by the boolean kwarg ``lazy``. If a file is opened lazily: + +* A failure at first IO operation will happen by raising an :exc:`FileError`. +* It can help minimize resource handling confusion. If a file is opened in lazy mode, it will receive a + ``close_intelligently`` method that can help figure out if the file needs closing or not. + This is not needed for parameters, but is necessary for manually prompting with the :func:`prompt` function as you do not know if a stream like stdout was opened (which was already open + before) or a real file that needs closing. + +Since files opened for writing will typically empty the file, the lazy mode should only be disabled if the developer is absolutely sure that this is intended behavior. + +It is also possible to open files in atomic mode by passing ``atomic=True``. In atomic mode, all writes go into a separate 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. diff --git a/docs/handling_files.rst b/docs/handling_files.rst deleted file mode 100644 index 1e9288209..000000000 --- a/docs/handling_files.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. _handling-files: - -Handling Files -================ - -.. currentmodule:: click - -File and files paths are often passed in as arguments. - -.. _file-args: - -File Arguments --------------- - -Since all the examples have already worked with filenames, it makes sense -to explain how to deal with files properly. Command line tools are more -fun if they work with files the Unix way, which is to accept ``-`` as a -special file that refers to stdin/stdout. - -Click supports this through the :class:`click.File` type which -intelligently handles files for you. It also deals with Unicode and bytes -correctly for all versions of Python so your script stays very portable. - -Example: - -.. click:example:: - - @click.command() - @click.argument('input', type=click.File('rb')) - @click.argument('output', type=click.File('wb')) - def inout(input, output): - """Copy contents of INPUT to OUTPUT.""" - while True: - chunk = input.read(1024) - if not chunk: - break - output.write(chunk) - -And what it does: - -.. click:run:: - - with isolated_filesystem(): - invoke(inout, args=['-', 'hello.txt'], input=['hello'], - terminate_input=True) - invoke(inout, args=['hello.txt', '-']) - -File Path Arguments -------------------- - -In the previous example, the files were opened immediately. But what if -we just want the filename? The naïve way is to use the default string -argument type. The :class:`Path` type has several checks available which raise nice -errors if they fail, such as existence. Filenames in these error messages are formatted -with :func:`format_filename`, so any undecodable bytes will be printed nicely. - -Example: - -.. click:example:: - - @click.command() - @click.argument('filename', type=click.Path(exists=True)) - def touch(filename): - """Print FILENAME if the file exists.""" - click.echo(click.format_filename(filename)) - -And what it does: - -.. click:run:: - - with isolated_filesystem(): - with open('hello.txt', 'w') as f: - f.write('Hello World!\n') - invoke(touch, args=['hello.txt']) - println() - invoke(touch, args=['missing.txt']) - - -File Opening Safety -------------------- - -The :class:`FileType` type has one problem it needs to deal with, and that -is to decide when to open a file. The default behavior is to be -"intelligent" about it. What this means is that it will open stdin/stdout -and files opened for reading immediately. This will give the user direct -feedback when a file cannot be opened, but it will only open files -for writing the first time an IO operation is performed by automatically -wrapping the file in a special wrapper. - -This behavior can be forced by passing ``lazy=True`` or ``lazy=False`` to -the constructor. If the file is opened lazily, it will fail its first IO -operation by raising an :exc:`FileError`. - -Since files opened for writing will typically immediately empty the file, -the lazy mode should only be disabled if the developer is absolutely sure -that this is intended behavior. - -Forcing lazy mode is also very useful to avoid resource handling -confusion. If a file is opened in lazy mode, it will receive a -``close_intelligently`` method that can help figure out if the file -needs closing or not. This is not needed for parameters, but is -necessary for manually prompting with the :func:`prompt` function as you -do not know if a stream like stdout was opened (which was already open -before) or a real file that needs closing. - -Starting with Click 2.0, it is also possible to open files in atomic mode by -passing ``atomic=True``. In atomic mode, all writes go into a separate -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. diff --git a/docs/index.rst b/docs/index.rst index 0e75e6a58..08266b160 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -75,7 +75,7 @@ usage patterns. arguments commands prompts - handling_files + handling-files documentation complex advanced diff --git a/src/click/types.py b/src/click/types.py index c310377a0..a70fd58ce 100644 --- a/src/click/types.py +++ b/src/click/types.py @@ -659,12 +659,15 @@ class File(ParamType): will not be held open until first IO. lazy is mainly useful when opening for writing to avoid creating the file until it is needed. - Starting with Click 2.0, files can also be opened atomically in which - case all writes go into a separate 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. + Files can also be opened atomically in which case all writes go into a + separate 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. See :ref:`file-args` for more information. + + .. versionchanged:: 2.0 + Added the ``atomic`` parameter. """ name = "filename" From e835913b9f3b3d276088361633bf28b182270b18 Mon Sep 17 00:00:00 2001 From: unknown Date: Wed, 13 Nov 2024 18:24:43 -0800 Subject: [PATCH 8/9] Clarify environment variables section. --- docs/arguments.rst | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/arguments.rst b/docs/arguments.rst index df3993e00..fd6d1699a 100644 --- a/docs/arguments.rst +++ b/docs/arguments.rst @@ -114,9 +114,10 @@ And from the command line: Environment Variables --------------------- -This feature is not recommended since it be confusing to users. Arguments can only pull environment variables from ? explicitly named environment variables. In that case, it can also be a list of different environment variables where the first one is picked. ? +Arguments can only pull from explicit environment variables, that is the +name of the environment variable(s) must be passed into ``click.argument``. -Example usage: +Example usage checking one environment variable: .. click:example:: @@ -131,6 +132,28 @@ And from the command line: .. click:run:: with isolated_filesystem(): + # Writing the file in the filesystem. with open('hello.txt', 'w') as f: f.write('Hello World!') invoke(echo, env={'SRC': 'hello.txt'}) + + +Example usage checking multiple environment variables: + +.. click:example:: + + @click.command() + @click.argument('src', envvar=['SRC', 'SRC_2'], type=click.File('r')) + def echo(src): + """Print value of SRC environment variable.""" + click.echo(src.read()) + +And from the command line: + +.. click:run:: + + with isolated_filesystem(): + # Writing the file in the filesystem. + with open('hello.txt', 'w') as f: + f.write('Hello World from second variable!') + invoke(echo, env={'SRC_2': 'hello.txt'}) From e0f59be0f51d7b28aad2f2aa868e748f30721782 Mon Sep 17 00:00:00 2001 From: unknown Date: Wed, 13 Nov 2024 20:16:52 -0800 Subject: [PATCH 9/9] More concisely phrase Environment Variables section. --- docs/arguments.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/arguments.rst b/docs/arguments.rst index fd6d1699a..80fa5d386 100644 --- a/docs/arguments.rst +++ b/docs/arguments.rst @@ -114,10 +114,9 @@ And from the command line: Environment Variables --------------------- -Arguments can only pull from explicit environment variables, that is the -name of the environment variable(s) must be passed into ``click.argument``. +Arguments can use environment variables. To do so pass the name of the environment variable(s) into ``click.argument``. -Example usage checking one environment variable: +Checking one environment variable: .. click:example:: @@ -138,7 +137,7 @@ And from the command line: invoke(echo, env={'SRC': 'hello.txt'}) -Example usage checking multiple environment variables: +Checking multiple environment variables: .. click:example::