click 8.2.0__tar.gz → 8.2.2__tar.gz

{click-8.2.0 → click-8.2.2}/CHANGES.rst

@@ -1,5 +1,36 @@
 .. currentmodule:: click
 
+Version 8.2.2
+-------------
+
+Released 2025-07-31
+
+-   Fix reconciliation of `default`, `flag_value` and `type` parameters for
+    flag options, as well as parsing and normalization of environment variables.
+    :issue:`2952` :pr:`2956`
+-   Fix typing issue in ``BadParameter`` and ``MissingParameter`` exceptions for the
+    parameter ``param_hint`` that did not allow for a sequence of string where the
+    underlying functino ``_join_param_hints`` allows for it. :issue:`2777` :pr:`2990`
+-   Use the value of ``Enum`` choices to render their default value in help
+    screen. Refs :issue:`2911` :pr:`3004`
+-   Fix completion for the Z shell (``zsh``) for completion items containing
+    colons. :issue:`2703` :pr:`2846`
+-   Don't include envvar in error hint when not configured. :issue:`2971` :pr:`2972`
+-   Fix a rare race in ``click.testing.StreamMixer``'s finalization that manifested
+    as a ``ValueError`` on close in a multi-threaded test session.
+    :issue:`2993` :pr:`2991`
+
+Version 8.2.1
+-------------
+
+Released 2025-05-20
+
+-   Fix flag value handling for flag options with a provided type. :issue:`2894`
+    :issue:`2897` :pr:`2930`
+-   Fix shell completion for nested groups. :issue:`2906` :pr:`2907`
+-   Flush ``sys.stderr`` at the end of ``CliRunner.invoke``. :issue:`2682`
+-   Fix EOF handling for stdin input in CliRunner. :issue:`2787`
+
 Version 8.2.0
 -------------
 

{click-8.2.0 → click-8.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: click
-Version: 8.2.0
+Version: 8.2.2
 Summary: Composable command line interface toolkit
 Maintainer-email: Pallets <contact@palletsprojects.com>
 Requires-Python: >=3.10
@@ -13,13 +13,15 @@ Classifier: Programming Language :: Python
 Classifier: Typing :: Typed
 License-File: LICENSE.txt
 Requires-Dist: colorama; platform_system == 'Windows'
-Project-URL: Changes, https://click.palletsprojects.com/changes/
+Project-URL: Changes, https://click.palletsprojects.com/page/changes/
 Project-URL: Chat, https://discord.gg/pallets
 Project-URL: Documentation, https://click.palletsprojects.com/
 Project-URL: Donate, https://palletsprojects.com/donate
 Project-URL: Source, https://github.com/pallets/click/
 
-# $ click_
+<div align="center"><img src="https://raw.githubusercontent.com/pallets/click/refs/heads/stable/docs/_static/click-name.svg" alt="" height="150"></div>
+
+# Click
 
 Click is a Python package for creating beautiful command line interfaces
 in a composable way with as little code as necessary. It's the "Command

{click-8.2.0 → click-8.2.2}/README.md

@@ -1,4 +1,6 @@
-# $ click_
+<div align="center"><img src="https://raw.githubusercontent.com/pallets/click/refs/heads/stable/docs/_static/click-name.svg" alt="" height="150"></div>
+
+# Click
 
 Click is a Python package for creating beautiful command line interfaces
 in a composable way with as little code as necessary. It's the "Command

click-8.2.2/docs/_static/click-icon.svg

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 500 500" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <rect id="Icon" x="0" y="0" width="500" height="500" style="fill:none;"/>
+    <g>
+        <path d="M448.569,446.761l-66.389,49.07c-3.528,2.565 -8.018,4.169 -12.508,4.169l-136.626,-0c-19.243,-0 -28.223,-23.733 -14.112,-36.562l54.843,-49.07c3.849,-3.528 8.66,-5.452 14.112,-5.452l147.851,-0c20.526,-0 28.865,25.657 12.829,37.845Z" style="fill:#5c549e;fill-rule:nonzero;"/>
+        <path d="M192.956,406.03l-91.404,84.028c-6.415,6.414 -15.074,9.942 -23.734,9.942c-8.659,-0 -17.318,-3.528 -23.733,-9.942c-13.47,-13.47 -13.47,-34.317 0,-47.467l32.713,-36.561l106.158,-0Z" style="fill:#5c549e;fill-rule:nonzero;"/>
+        <path d="M328.299,216.485l-113.855,-102.309l-109.685,-0l124.118,135.343l-124.118,135.343l108.723,-0.321l114.817,-101.988c8.66,-9.301 13.15,-21.167 12.829,-33.355c0.321,-11.225 -4.169,-23.412 -12.829,-32.713Z" style="fill:#5c549e;fill-rule:nonzero;"/>
+        <path d="M191.994,93.97l-91.405,-84.028c-6.414,-6.414 -15.073,-9.942 -23.733,-9.942c-8.659,0 -17.319,3.528 -23.733,9.942c-13.47,13.47 -13.47,34.317 0,47.467l33.034,36.561l105.837,0Z" style="fill:#5c549e;fill-rule:nonzero;"/>
+    </g>
+</svg>

click-8.2.2/docs/_static/click-logo.svg

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 500 500" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <rect id="Logo" x="0" y="0" width="500" height="500" style="fill:none;"/>
+    <g>
+        <path id="Box" d="M500,50l0,400c0,27.596 -22.404,50 -50,50l-400,0c-27.596,0 -50,-22.404 -50,-50l0,-400c0,-27.596 22.404,-50 50,-50l400,0c27.596,0 50,22.404 50,50Z" style="fill:url(#_Linear1);"/>
+        <path id="Shadow" d="M500,432.911l0,17.089c0,27.596 -22.404,50 -50,50l-211.576,0l-105.636,-105.637c3.812,3.641 8.857,5.637 13.903,5.637c5.196,0 10.391,-2.117 14.24,-5.965l54.843,-50.417l-40.218,-0l-12.701,-12.701l65.234,-0.192l68.891,-61.193c5.195,-5.581 7.889,-12.701 7.697,-20.013c0.192,-6.735 -2.502,-14.048 -7.697,-19.628l203.02,203.02Zm-284.804,-276.529l12.124,12.123l-63.503,0l-12.123,-12.123l63.502,0Zm153.945,211.674c9.622,-7.312 4.619,-22.706 -7.697,-22.706l-88.711,-0c-3.271,-0 -6.157,1.154 -8.467,3.271l-32.905,29.442c-8.467,7.697 -3.079,21.937 8.467,21.937l81.975,0c2.694,0 5.388,-0.962 7.505,-2.502l39.833,-29.442Z" style="fill:#493e5e;"/>
+        <g id="Icon">
+            <path d="M369.141,368.056l-39.833,29.442c-2.117,1.54 -4.811,2.502 -7.505,2.502l-81.975,0c-11.546,0 -16.934,-14.24 -8.467,-21.937l32.905,-29.442c2.31,-2.117 5.196,-3.271 8.467,-3.271l88.711,-0c12.316,-0 17.319,15.394 7.697,22.706Z" style="fill:#fff;fill-rule:nonzero;"/>
+            <path d="M215.774,343.618l-54.843,50.417c-3.849,3.848 -9.044,5.965 -14.24,5.965c-5.196,0 -10.391,-2.117 -14.24,-5.965c-8.082,-8.082 -8.082,-20.59 0,-28.48l19.628,-21.937l63.695,-0Z" style="fill:#fff;fill-rule:nonzero;"/>
+            <path d="M296.98,229.891l-68.313,-61.386l-65.812,0l74.471,81.206l-74.471,81.206l65.234,-0.192l68.891,-61.193c5.195,-5.581 7.889,-12.701 7.697,-20.013c0.192,-6.735 -2.502,-14.048 -7.697,-19.628Z" style="fill:#fff;fill-rule:nonzero;"/>
+            <path d="M215.196,156.382l-54.842,-50.417c-3.849,-3.848 -9.045,-5.965 -14.24,-5.965c-5.196,0 -10.392,2.117 -14.24,5.965c-8.082,8.082 -8.082,20.59 -0,28.48l19.82,21.937l63.502,0Z" style="fill:#fff;fill-rule:nonzero;"/>
+        </g>
+    </g>
+    <defs>
+        <linearGradient id="_Linear1" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(3.06162e-14,500,-500,3.06162e-14,267.59,0)"><stop offset="0" style="stop-color:#d8a9ca;stop-opacity:1"/><stop offset="1" style="stop-color:#53519b;stop-opacity:1"/></linearGradient>
+    </defs>
+</svg>

click-8.2.2/docs/_static/click-name.svg

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 679 300" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <g>
+        <path id="Name" d="M410.6,166.725l19.35,0c0,13.6 -3.4,24.05 -10.2,31.35c-6.8,7.3 -16.4,10.95 -28.8,10.95c-27.3,0 -40.95,-16.05 -40.95,-48.15l0,-9c0,-25.3 7,-41.15 21,-47.55c5.5,-2.6 12.15,-3.9 19.95,-3.9c11.4,0 20.675,3.125 27.825,9.375c7.15,6.25 10.725,15.275 10.725,27.075l-19.5,0c-1.1,-5.9 -3.05,-10.35 -5.85,-13.35c-2.8,-3 -7.2,-4.5 -13.2,-4.5c-7,0 -12.2,2.2 -15.6,6.6c-2.4,3.1 -3.8,8.4 -4.2,15.9c-0.2,2.4 -0.3,5.65 -0.3,9.75l0,9.3c0,11.5 1.6,19.35 4.8,23.55c3.3,4.2 8.425,6.3 15.375,6.3c6.95,0 11.75,-1.925 14.4,-5.775c2.65,-3.85 4.375,-9.825 5.175,-17.925Z" style="fill-rule:nonzero;"/>
+        <path d="M464.9,208.125l-19.5,0.15l0,-112.95l19.5,0l0,112.8Z" style="fill-rule:nonzero;"/>
+        <path d="M495.8,89.775c4.7,0 7.75,0.725 9.15,2.175c1.4,1.45 2.1,4.5 2.1,9.15c0,4.65 -0.725,7.7 -2.175,9.15c-1.45,1.45 -4.5,2.175 -9.15,2.175c-4.65,0 -7.7,-0.75 -9.15,-2.25c-1.45,-1.5 -2.175,-4.55 -2.175,-9.15c0,-4.6 0.725,-7.625 2.175,-9.075c1.45,-1.45 4.525,-2.175 9.225,-2.175Zm9.6,118.35l-19.5,0l0,-82.5l19.5,0l0,82.5Z" style="fill-rule:nonzero;"/>
+        <path d="M570.95,176.775l17.7,-0.15c-0.1,0.8 -0.2,2.25 -0.3,4.35c-0.1,2.1 -0.175,3.525 -0.225,4.275c-0.05,0.75 -0.175,1.925 -0.375,3.525c-0.2,1.6 -0.425,2.775 -0.675,3.525c-0.25,0.75 -0.575,1.725 -0.975,2.925c-1.8,5.2 -6.7,9.3 -14.7,12.3c-5.1,1.8 -10.425,2.7 -15.975,2.7c-5.55,-0 -10.575,-0.9 -15.075,-2.7c-4.5,-1.8 -8.05,-4.1 -10.65,-6.9c-5.9,-6.2 -8.85,-17.825 -8.85,-34.875c0,-17.05 2.95,-28.675 8.85,-34.875c2.6,-2.8 6.15,-5.1 10.65,-6.9c4.5,-1.8 9.5,-2.7 15,-2.7c10.8,0 19,2.7 24.6,8.1c5.6,5.4 8.4,12.9 8.4,22.5l-17.7,0c0,-4.4 -1.1,-7.675 -3.3,-9.825c-2.2,-2.15 -6.275,-3.225 -12.225,-3.225c-5.95,-0 -9.9,1.85 -11.85,5.55c-1.95,3.7 -2.925,9.25 -2.925,16.65l0,7.8c0,11.9 2.3,19.2 6.9,21.9c2.1,1.3 4.85,1.95 8.25,1.95c3.4,-0 6.175,-0.325 8.325,-0.975c2.15,-0.65 3.7,-1.775 4.65,-3.375c0.95,-1.6 1.575,-3.175 1.875,-4.725c0.3,-1.55 0.5,-3.825 0.6,-6.825Z" style="fill-rule:nonzero;"/>
+        <path d="M678.65,208.125l-23.4,0l-22.5,-30.3l-8.55,12.15l0,18.15l-19.5,0l0,-112.8l19.5,0l0,71.25l27.3,-40.65l22.05,0l-28.05,38.4l33.15,43.8Z" style="fill-rule:nonzero;"/>
+        <g id="Logo">
+            <path id="Box" d="M300,30l0,240c0,16.557 -13.443,30 -30,30l-240,-0c-16.557,-0 -30,-13.443 -30,-30l0,-240c0,-16.557 13.443,-30 30,-30l240,0c16.557,0 30,13.443 30,30Z" style="fill:url(#_Linear1);"/>
+            <path id="Shadow" d="M300,259.747l0,10.253c0,16.557 -13.443,30 -30,30l-126.946,-0l-63.381,-63.382c2.287,2.184 5.314,3.382 8.342,3.382c3.117,0 6.234,-1.27 8.544,-3.579l32.905,-30.25l-24.131,-0l-7.62,-7.621l39.141,-0.115l41.334,-36.716c3.117,-3.348 4.734,-7.62 4.618,-12.008c0.116,-4.041 -1.501,-8.428 -4.618,-11.776l121.812,121.812Zm-170.882,-165.918l7.274,7.274l-38.102,0l-7.273,-7.274l38.101,0Zm92.367,127.005c5.773,-4.388 2.771,-13.624 -4.619,-13.624l-53.226,-0c-1.963,-0 -3.695,0.693 -5.08,1.963l-19.744,17.665c-5.08,4.618 -1.847,13.162 5.081,13.162l49.185,0c1.616,0 3.233,-0.577 4.503,-1.501l23.9,-17.665Z" style="fill:#493e5e;"/>
+            <g id="Icon">
+                <path d="M221.485,220.834l-23.9,17.665c-1.27,0.924 -2.887,1.501 -4.503,1.501l-49.185,0c-6.928,0 -10.161,-8.544 -5.081,-13.162l19.744,-17.665c1.385,-1.27 3.117,-1.963 5.08,-1.963l53.226,-0c7.39,-0 10.392,9.236 4.619,13.624Z" style="fill:#fff;fill-rule:nonzero;"/>
+                <path d="M129.464,206.171l-32.905,30.25c-2.31,2.309 -5.427,3.579 -8.544,3.579c-3.118,0 -6.235,-1.27 -8.544,-3.579c-4.85,-4.849 -4.85,-12.354 -0,-17.088l11.776,-13.162l38.217,-0Z" style="fill:#fff;fill-rule:nonzero;"/>
+                <path d="M178.188,137.935l-40.988,-36.832l-39.487,0l44.683,48.724l-44.683,48.723l39.141,-0.115l41.334,-36.716c3.117,-3.348 4.734,-7.62 4.618,-12.008c0.116,-4.041 -1.501,-8.428 -4.618,-11.776Z" style="fill:#fff;fill-rule:nonzero;"/>
+                <path d="M129.118,93.829l-32.906,-30.25c-2.309,-2.309 -5.426,-3.579 -8.544,-3.579c-3.117,0 -6.235,1.27 -8.544,3.579c-4.849,4.849 -4.849,12.354 0,17.088l11.893,13.162l38.101,0Z" style="fill:#fff;fill-rule:nonzero;"/>
+            </g>
+        </g>
+    </g>
+    <defs>
+        <linearGradient id="_Linear1" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(1.83697e-14,300,-300,1.83697e-14,160.554,0)"><stop offset="0" style="stop-color:#d8a9ca;stop-opacity:1"/><stop offset="1" style="stop-color:#53519b;stop-opacity:1"/></linearGradient>
+    </defs>
+</svg>

{click-8.2.0 → click-8.2.2}/docs/advanced.rst

@@ -3,12 +3,10 @@ Advanced Patterns
 
 .. currentmodule:: click
 
-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.
+In addition to common functionality, Click offers some advanced features.
 
 .. contents::
-    :depth: 2
+    :depth: 1
     :local:
 
 Callbacks and Eager Options
@@ -110,133 +108,6 @@ also contain the parameter name.
     println()
     invoke(roll, input=["42", "2d12"])
 
-.. _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:
-
-Command Aliases
----------------
-
-Many tools support aliases for commands. For example, you can configure
-``git`` to accept ``git ci`` as alias for ``git commit``. Other tools also
-support auto-discovery for aliases by automatically shortening them.
-
-It's possible to customize :class:`Group` to provide this functionality. As
-explained in :ref:`custom-groups`, a group provides two methods:
-:meth:`~Group.list_commands` and :meth:`~Group.get_command`. In this particular
-case, you only need to override the latter as you generally don't want to
-enumerate the aliases on the help page in order to avoid confusion.
-
-The following example implements a subclass of :class:`Group` that accepts a
-prefix for a command. If there was a command called ``push``, it would accept
-``pus`` as an alias (so long as it was unique):
-
-.. click:example::
-
-    class AliasedGroup(click.Group):
-        def get_command(self, ctx, cmd_name):
-            rv = super().get_command(ctx, cmd_name)
-
-            if rv is not None:
-                return rv
-
-            matches = [
-                x for x in self.list_commands(ctx)
-                if x.startswith(cmd_name)
-            ]
-
-            if not matches:
-                return None
-
-            if len(matches) == 1:
-                return click.Group.get_command(self, ctx, matches[0])
-
-            ctx.fail(f"Too many matches: {', '.join(sorted(matches))}")
-
-        def resolve_command(self, ctx, args):
-            # always return the full command name
-            _, cmd, args = super().resolve_command(ctx, args)
-            return cmd.name, cmd, args
-
-It can be used like this:
-
-.. click:example::
-
-    @click.group(cls=AliasedGroup)
-    def cli():
-        pass
-
-    @cli.command
-    def push():
-        pass
-
-    @cli.command
-    def pop():
-        pass
-
-See the `alias example`_ in Click's repository for another example.
-
-.. _alias example: https://github.com/pallets/click/tree/main/examples/aliases
-
-
 Parameter Modifications
 -----------------------
 
@@ -360,64 +231,6 @@ And what it looks like:
     invoke(cli, prog_name='cli', args=['dist'])
 
 
-.. _callback-evaluation-order:
-
-Callback Evaluation Order
--------------------------
-
-Click works a bit differently than some other command line parsers in that
-it attempts to reconcile the order of arguments as defined by the
-programmer with the order of arguments as defined by the user before
-invoking any callbacks.
-
-This is an important concept to understand when porting complex
-patterns to Click from optparse or other systems.  A parameter
-callback invocation in optparse happens as part of the parsing step,
-whereas a callback invocation in Click happens after the parsing.
-
-The main difference is that in optparse, callbacks are invoked with the raw
-value as it happens, whereas a callback in Click is invoked after the
-value has been fully converted.
-
-Generally, the order of invocation is driven by the order in which the user
-provides the arguments to the script; if there is an option called ``--foo``
-and an option called ``--bar`` and the user calls it as ``--bar
---foo``, then the callback for ``bar`` will fire before the one for ``foo``.
-
-There are three exceptions to this rule which are important to know:
-
-Eagerness:
-    An option can be set to be "eager".  All eager parameters are
-    evaluated before all non-eager parameters, but again in the order as
-    they were provided on the command line by the user.
-
-    This is important for parameters that execute and exit like ``--help``
-    and ``--version``.  Both are eager parameters, but whatever parameter
-    comes first on the command line will win and exit the program.
-
-Repeated parameters:
-    If an option or argument is split up on the command line into multiple
-    places because it is repeated -- for instance, ``--exclude foo --include
-    baz --exclude bar`` -- the callback will fire based on the position of
-    the first option.  In this case, the callback will fire for
-    ``exclude`` and it will be passed both options (``foo`` and
-    ``bar``), then the callback for ``include`` will fire with ``baz``
-    only.
-
-    Note that even if a parameter does not allow multiple versions, Click
-    will still accept the position of the first, but it will ignore every
-    value except the last.  The reason for this is to allow composability
-    through shell aliases that set defaults.
-
-Missing parameters:
-    If a parameter is not defined on the command line, the callback will
-    still fire.  This is different from how it works in optparse where
-    undefined values do not fire the callback.  Missing parameters fire
-    their callbacks at the very end which makes it possible for them to
-    default to values from a parameter that came before.
-
-Most of the time you do not need to be concerned about any of this,
-but it is important to know how it works for some advanced cases.
 
 .. _forwarding-unknown-options:
 
@@ -515,74 +328,6 @@ everything below a subcommand be forwarded to another application than to
 handle some arguments yourself.
 
 
-Global Context Access
----------------------
-
-.. versionadded:: 5.0
-
-Starting with Click 5.0 it is possible to access the current context from
-anywhere within the same thread through the use of the
-:func:`get_current_context` function which returns it.  This is primarily
-useful for accessing the context bound object as well as some flags that
-are stored on it to customize the runtime behavior.  For instance the
-:func:`echo` function does this to infer the default value of the `color`
-flag.
-
-Example usage::
-
-    def get_current_command_name():
-        return click.get_current_context().info_name
-
-It should be noted that this only works within the current thread.  If you
-spawn additional threads then those threads will not have the ability to
-refer to the current context.  If you want to give another thread the
-ability to refer to this context you need to use the context within the
-thread as a context manager::
-
-    def spawn_thread(ctx, func):
-        def wrapper():
-            with ctx:
-                func()
-        t = threading.Thread(target=wrapper)
-        t.start()
-        return t
-
-Now the thread function can access the context like the main thread would
-do.  However if you do use this for threading you need to be very careful
-as the vast majority of the context is not thread safe!  You are only
-allowed to read from the context, but not to perform any modifications on
-it.
-
-
-Detecting the Source of a Parameter
------------------------------------
-
-In some situations it's helpful to understand whether or not an option
-or parameter came from the command line, the environment, the default
-value, or :attr:`Context.default_map`. The
-:meth:`Context.get_parameter_source` method can be used to find this
-out. It will return a member of the :class:`~click.core.ParameterSource`
-enum.
-
-.. click:example::
-
-    @click.command()
-    @click.argument('port', nargs=1, default=8080, envvar="PORT")
-    @click.pass_context
-    def cli(ctx, port):
-        source = ctx.get_parameter_source("port")
-        click.echo(f"Port came from {source.name}")
-
-.. click:run::
-
-    invoke(cli, prog_name='cli', args=['8080'])
-    println()
-    invoke(cli, prog_name='cli', args=[], env={"PORT": "8080"})
-    println()
-    invoke(cli, prog_name='cli', args=[])
-    println()
-
-
 Managing Resources
 ------------------
 

click-8.2.2/docs/click-concepts.rst

@@ -0,0 +1,67 @@
+Click Concepts
+================
+
+This section covers concepts about Click's design.
+
+.. contents::
+    :depth: 1
+    :local:
+
+.. _callback-evaluation-order:
+
+Callback Evaluation Order
+-------------------------
+
+Click works a bit differently than some other command line parsers in that
+it attempts to reconcile the order of arguments as defined by the
+programmer with the order of arguments as defined by the user before
+invoking any callbacks.
+
+This is an important concept to understand when porting complex
+patterns to Click from optparse or other systems.  A parameter
+callback invocation in optparse happens as part of the parsing step,
+whereas a callback invocation in Click happens after the parsing.
+
+The main difference is that in optparse, callbacks are invoked with the raw
+value as it happens, whereas a callback in Click is invoked after the
+value has been fully converted.
+
+Generally, the order of invocation is driven by the order in which the user
+provides the arguments to the script; if there is an option called ``--foo``
+and an option called ``--bar`` and the user calls it as ``--bar
+--foo``, then the callback for ``bar`` will fire before the one for ``foo``.
+
+There are three exceptions to this rule which are important to know:
+
+Eagerness:
+    An option can be set to be "eager".  All eager parameters are
+    evaluated before all non-eager parameters, but again in the order as
+    they were provided on the command line by the user.
+
+    This is important for parameters that execute and exit like ``--help``
+    and ``--version``.  Both are eager parameters, but whatever parameter
+    comes first on the command line will win and exit the program.
+
+Repeated parameters:
+    If an option or argument is split up on the command line into multiple
+    places because it is repeated -- for instance, ``--exclude foo --include
+    baz --exclude bar`` -- the callback will fire based on the position of
+    the first option.  In this case, the callback will fire for
+    ``exclude`` and it will be passed both options (``foo`` and
+    ``bar``), then the callback for ``include`` will fire with ``baz``
+    only.
+
+    Note that even if a parameter does not allow multiple versions, Click
+    will still accept the position of the first, but it will ignore every
+    value except the last.  The reason for this is to allow composability
+    through shell aliases that set defaults.
+
+Missing parameters:
+    If a parameter is not defined on the command line, the callback will
+    still fire.  This is different from how it works in optparse where
+    undefined values do not fire the callback.  Missing parameters fire
+    their callbacks at the very end which makes it possible for them to
+    default to values from a parameter that came before.
+
+Most of the time you do not need to be concerned about any of this,
+but it is important to know how it works for some advanced cases.

{click-8.2.0 → click-8.2.2}/docs/commands-and-groups.rst

@@ -6,11 +6,14 @@ Basic Commands, Groups, Context
 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
+   :depth: 2
    :local:
 
+Commands
+--------------------
+
 Basic Command Example
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^^
 A simple command decorator takes no arguments.
 
 .. click:example::
@@ -24,7 +27,7 @@ A simple command decorator takes no arguments.
     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::
@@ -38,7 +41,7 @@ By default the command is the function name with underscores replaced by dashes.
     invoke(hello, args=['--count', '2',])
 
 Deprecating Commands
----------------------
+^^^^^^^^^^^^^^^^^^^^^^
 To mark a command as deprecated pass in ``deprecated=True``
 
 .. click:example::
@@ -51,8 +54,11 @@ To mark a command as deprecated pass in ``deprecated=True``
 .. click:run::
     invoke(hello, args=['--count', '2',])
 
+Groups
+------------
+
 Basic Group Example
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 A group wraps one or more commands. 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::
@@ -82,7 +88,7 @@ At the command level:
 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::
@@ -101,7 +107,7 @@ To have a name other than the decorated function name as the group name, pass it
     invoke(greeting, args=['say-hello'])
 
 Group Invocation Without Command
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 By default, if a group is passed without a command, the group is not invoked and a command automatically passes ``--help``. To change this, pass ``invoke_without_command=True`` to the group. The context object also includes information about whether or not the group invocation would go to a command nested under it.
 
@@ -127,7 +133,7 @@ By default, if a group is passed without a command, the group is not invoked and
 
 
 Group Separation
---------------------------
+^^^^^^^^^^^^^^^^^^^
 Command :ref:`parameters` attached to a command belong only to that command.
 
 .. click:example::
@@ -162,7 +168,7 @@ This behavior is observable with the ``--help`` option. Suppose we have a group
 - But ``tool --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
-------------------
+^^^^^^^^^^^^^^^^^^^
 :class:`Commands <Command>` are attached to a :class:`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 nested under multiple groups, all the groups under which it is nested must be invoked.
 
 .. click:example::
@@ -189,7 +195,7 @@ Arbitrary Nesting
     invoke(cli, args=['session', 'initdb'])
 
 Lazily Attaching Commands
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Most examples so far have attached the commands to a group immediately, but commands may be registered later. This could be used to split commands into multiple Python modules. Regardless of how they are attached, the commands are invoked identically.
 
 .. click:example::
@@ -218,7 +224,7 @@ Context Object
 The :class:`Context` object is how commands and groups communicate.
 
 Auto Envvar Prefix
---------------------
+^^^^^^^^^^^^^^^^^^^^
 Automatically built environment variables are supported for options only. To enable this feature, the ``auto_envvar_prefix`` parameter needs to be passed to the script that is invoked.  Each command and parameter is then added as an uppercase underscore-separated variable.  If you have a subcommand
 called ``run`` taking an option called ``reload`` and the prefix is ``WEB``, then the variable is ``WEB_RUN_RELOAD``.
 
@@ -267,3 +273,70 @@ the prefix is ``WEB``, then the variable is ``WEB_RUN_SERVER_HOST``.
    invoke(cli, args=['greet',],
           env={'GREETER_GREET_USERNAME': 'John', 'GREETER_DEBUG': 'false'},
           auto_envvar_prefix='GREETER')
+
+Global Context Access
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 5.0
+
+Starting with Click 5.0 it is possible to access the current context from
+anywhere within the same thread through the use of the
+:func:`get_current_context` function which returns it.  This is primarily
+useful for accessing the context bound object as well as some flags that
+are stored on it to customize the runtime behavior.  For instance the
+:func:`echo` function does this to infer the default value of the `color`
+flag.
+
+Example usage::
+
+    def get_current_command_name():
+        return click.get_current_context().info_name
+
+It should be noted that this only works within the current thread.  If you
+spawn additional threads then those threads will not have the ability to
+refer to the current context.  If you want to give another thread the
+ability to refer to this context you need to use the context within the
+thread as a context manager::
+
+    def spawn_thread(ctx, func):
+        def wrapper():
+            with ctx:
+                func()
+        t = threading.Thread(target=wrapper)
+        t.start()
+        return t
+
+Now the thread function can access the context like the main thread would
+do.  However if you do use this for threading you need to be very careful
+as the vast majority of the context is not thread safe!  You are only
+allowed to read from the context, but not to perform any modifications on
+it.
+
+
+Detecting the Source of a Parameter
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In some situations it's helpful to understand whether or not an option
+or parameter came from the command line, the environment, the default
+value, or :attr:`Context.default_map`. The
+:meth:`Context.get_parameter_source` method can be used to find this
+out. It will return a member of the :class:`~click.core.ParameterSource`
+enum.
+
+.. click:example::
+
+    @click.command()
+    @click.argument('port', nargs=1, default=8080, envvar="PORT")
+    @click.pass_context
+    def cli(ctx, port):
+        source = ctx.get_parameter_source("port")
+        click.echo(f"Port came from {source.name}")
+
+.. click:run::
+
+    invoke(cli, prog_name='cli', args=['8080'])
+    println()
+    invoke(cli, prog_name='cli', args=[], env={"PORT": "8080"})
+    println()
+    invoke(cli, prog_name='cli', args=[])
+    println()

{click-8.2.0 → click-8.2.2}/docs/complex.rst

@@ -16,6 +16,10 @@ In a theoretical world of two separate Click command line utilities, they
 could solve this problem by nesting one inside the other.  For instance, the
 web framework could also load the commands for the message queue framework.
 
+.. contents::
+    :depth: 1
+    :local:
+
 Basic Concepts
 --------------