click 8.2.1__tar.gz → 8.2.2__tar.gz

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

@@ -1,5 +1,25 @@
 .. 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
 -------------
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: click
-Version: 8.2.1
+Version: 8.2.2
 Summary: Composable command line interface toolkit
 Maintainer-email: Pallets <contact@palletsprojects.com>
 Requires-Python: >=3.10
@@ -19,7 +19,9 @@ 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.1 → 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.1 → click-8.2.2}/docs/conf.py

@@ -51,7 +51,7 @@ html_sidebars = {
 }
 singlehtml_sidebars = {"index": ["project.html", "localtoc.html", "ethicalads.html"]}
 html_static_path = ["_static"]
-html_favicon = "_static/click-icon.png"
-html_logo = "_static/click-logo-sidebar.png"
+html_favicon = "_static/click-icon.svg"
+html_logo = "_static/click-logo.svg"
 html_title = f"Click Documentation ({version})"
 html_show_sourcelink = False

click-8.2.2/docs/contrib.md

@@ -0,0 +1,45 @@
+(contrib)=
+
+# click-contrib
+
+As the user number of Click grows, more and more major feature requests are
+made. To users, it may seem reasonable to include those features with Click;
+however, many of them are experimental or aren't practical to support
+generically. Maintainers have to choose what is reasonable to maintain in Click
+core.
+
+The [click-contrib](https://github.com/click-contrib/) GitHub organization exists as a place to collect third-party
+packages that extend Click's features. It is also meant to ease the effort of
+searching for such extensions.
+
+Please note that the quality and stability of those packages may be different
+from Click itself. While published under a common organization, they are still
+separate from Click and the Pallets maintainers.
+
+## Third-party projects
+
+Other projects that extend Click's features are available outside the
+[click-contrib](https://github.com/click-contrib/) organization.
+
+Some of the most popular and actively maintained are listed below:
+
+| Project                                                 | Description                                                                          | Popularity                                                                                             | Activity                                                                                                    |
+|---------------------------------------------------------|--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
+| [Typer](https://github.com/fastapi/typer)               | Use Python type hints to create CLI apps.                                            | ![GitHub stars](https://img.shields.io/github/stars/fastapi/typer?label=%20&style=flat-square)         | ![Last commit](https://img.shields.io/github/last-commit/fastapi/typer?label=%20&style=flat-square)         |
+| [rich-click](https://github.com/ewels/rich-click)       | Format help output with Rich.                                                        | ![GitHub stars](https://img.shields.io/github/stars/ewels/rich-click?label=%20&style=flat-square)      | ![Last commit](https://img.shields.io/github/last-commit/ewels/rich-click?label=%20&style=flat-square)      |
+| [click-app](https://github.com/simonw/click-app)        | Cookiecutter template for creating new CLIs.                                         | ![GitHub stars](https://img.shields.io/github/stars/simonw/click-app?label=%20&style=flat-square)      | ![Last commit](https://img.shields.io/github/last-commit/simonw/click-app?label=%20&style=flat-square)      |
+| [Cloup](https://github.com/janluke/cloup)               | Adds option groups, constraints, command aliases, help themes, suggestions and more. | ![GitHub stars](https://img.shields.io/github/stars/janluke/cloup?label=%20&style=flat-square)         | ![Last commit](https://img.shields.io/github/last-commit/janluke/cloup?label=%20&style=flat-square)         |
+| [Click Extra](https://github.com/kdeldycke/click-extra) | Cloup + colorful `--help`, `--config`, `--show-params`, `--verbosity` options, etc.  | ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/click-extra?label=%20&style=flat-square) | ![Last commit](https://img.shields.io/github/last-commit/kdeldycke/click-extra?label=%20&style=flat-square) |
+
+```{note}
+To make it into the list above, a project:
+
+- must be actively maintained (at least one commit in the last year)
+- must have a reasonable number of stars (at least 20)
+
+If you have a project that meets these criteria, please open a pull request
+to add it to the list.
+
+If a project is no longer maintained or does not meet the criteria above,
+please open a pull request to remove it from the list.
+```

click-8.2.1/docs/documentation.rst → click-8.2.2/docs/documentation.md

@@ -1,17 +1,17 @@
-Help Pages
-===================
+# Help Pages
 
-.. currentmodule:: click
+```{currentmodule} click
+```
 
 Click makes it very easy to document your command line tools. For most things Click automatically generates help pages for you. By design the text is customizable, but the layout is not.
 
-Help Texts
---------------
+## Help Texts
 
 Commands and options accept help arguments. For commands, the docstring of the function is automatically used if provided.
 
 Simple example:
 
+```{eval-rst}
 .. click:example::
 
     @click.command()
@@ -26,17 +26,18 @@ Simple example:
                 click.echo("Hello!")
 
 .. click:run::
-
     invoke(hello, args=['--help'])
+```
 
+## Command Short Help
 
-Command Short Help
-------------------
-
-For subcommands, a short help snippet is generated. By default, it's the first sentence of the docstring. If too long, then it will ellipsize what cannot be fit on a single line with ``...``.  The short help snippet can also be overridden with ``short_help``:
+For subcommands, a short help snippet is generated. By default, it's the first sentence of the docstring. If too long, then it will ellipsize what cannot be fit on a single line with `...`. The short help snippet can also be overridden with `short_help`:
 
+```{eval-rst}
 .. click:example::
 
+    import click
+
     @click.group()
     def cli():
         """A simple command line tool."""
@@ -45,39 +46,39 @@ For subcommands, a short help snippet is generated. By default, it's the first s
     def init():
         """Initializes the repository."""
 
-
 .. click:run::
-
     invoke(cli, args=['--help'])
+```
 
-Command Epilog Help
--------------------
+## Command Epilog Help
 
 The help epilog is printed at the end of the help and is useful for showing example command usages or referencing additional help resources.
 
+```{eval-rst}
 .. click:example::
 
+    import click
+
     @click.command(
-    	epilog='See https://example.com for more details',
-  	)
+        epilog='See https://example.com for more details',
+        )
     def init():
         """Initializes the repository."""
 
-
 .. click:run::
-
     invoke(init, args=['--help'])
+```
 
-.. _documenting-arguments:
+(documenting-arguments)=
 
-Documenting Arguments
-----------------------
+## Documenting Arguments
 
-:class:`click.argument` does not take a ``help`` parameter. This follows the Unix Command Line Tools convention of using arguments only for necessary things and documenting them in the command help text
+{class}`click.argument` does not take a `help` parameter. This follows the Unix Command Line Tools convention of using arguments only for necessary things and documenting them in the command help text
 by name. This should then be done via the docstring.
 
 A brief example:
 
+```{eval-rst}
 .. click:example::
 
     @click.command()
@@ -86,13 +87,13 @@ A brief example:
         """Print FILENAME."""
         click.echo(filename)
 
-
 .. click:run::
-
     invoke(touch, args=['--help'])
+```
 
 Or more explicitly:
 
+```{eval-rst}
 .. click:example::
 
     @click.command()
@@ -105,14 +106,14 @@ Or more explicitly:
         click.echo(filename)
 
 .. click:run::
-
     invoke(touch, args=['--help'])
+```
 
+## Showing Defaults
 
-Showing Defaults
----------------------------
-To control the appearance of defaults pass ``show_default``.
+To control the appearance of defaults pass `show_default`.
 
+```{eval-rst}
 .. click:example::
 
     @click.command()
@@ -121,11 +122,12 @@ To control the appearance of defaults pass ``show_default``.
         click.echo('.' * n)
 
 .. click:run::
-
     invoke(dots, args=['--help'])
+```
 
-For single option boolean flags, the default remains hidden if the default value is False even if show default is true.
+For single option boolean flags, the default remains hidden if the default value is False, even if show default is set to true.
 
+```{eval-rst}
 .. click:example::
 
     @click.command()
@@ -140,16 +142,18 @@ For single option boolean flags, the default remains hidden if the default value
             click.echo('-' * n)
 
 .. click:run::
-
    invoke(dots, args=['--help'])
+```
 
+## Click's Wrapping Behavior
 
-Click's Wrapping Behavior
-----------------------------
 Click's default wrapping ignores single new lines and rewraps the text based on the width of the terminal, to a maximum of 80 characters. In the example notice how the second grouping of three lines is rewrapped into a single paragraph.
 
+```{eval-rst}
 .. click:example::
 
+    import click
+
     @click.command()
     def cli():
         """
@@ -164,17 +168,20 @@ Click's default wrapping ignores single new lines and rewraps the text based on
         """
 
 .. click:run::
-
     invoke(cli, args=['--help'])
+```
 
-Escaping Click's Wrapping
----------------------------
-Sometimes Click's wrapping can be a problem, such as when showing code examples where newlines are significant. This behavior can be escaped on a per-paragraph basis by adding a line with only ``\b`` . The ``\b`` is removed from the rendered help text.
+## Escaping Click's Wrapping
+
+Sometimes Click's wrapping can be a problem, such as when showing code examples where new lines are significant. This behavior can be escaped on a per-paragraph basis by adding a line with only `\b` . The `\b` is removed from the rendered help text.
 
 Example:
 
+```{eval-rst}
 .. click:example::
 
+    import click
+
     @click.command()
     def cli():
         """First paragraph.
@@ -188,28 +195,27 @@ Example:
         that will be rewrapped again.
         """
 
-
 .. click:run::
-
     invoke(cli, args=['--help'])
+```
 
-To change the rendering maximum width, pass ``max_content_width`` when calling the command.
+To change the rendering maximum width, pass `max_content_width` when calling the command.
 
-.. code-block:: python
+```bash
+cli(max_content_width=120)
+```
 
-    cli(max_content_width=120)
+## Truncating Help Texts
 
-.. _doc-meta-variables:
-
-Truncating Help Texts
----------------------
-
-Click gets :class:`Command` help text from the docstring. If you do not want to include part of the docstring, add the ``\f`` escape marker to have Click truncate the help text after the marker.
+Click gets {class}`Command` help text from the docstring. If you do not want to include part of the docstring, add the `\f` escape marker to have Click truncate the help text after the marker.
 
 Example:
 
+```{eval-rst}
 .. click:example::
 
+    import click
+
     @click.command()
     def cli():
         """First paragraph.
@@ -219,15 +225,16 @@ Example:
         """
 
 .. click:run::
-
     invoke(cli, args=['--help'])
+```
 
+(doc-meta-variables)=
 
-Placeholder / Meta Variable
------------------------------
+## Placeholder / Meta Variable
 
-The default placeholder variable (`meta variable <https://en.wikipedia.org/wiki/Metasyntactic_variable#IETF_Requests_for_Comments>`_) in the help pages is the parameter name in uppercase with underscores. This can be changed for Commands and Parameters with the ``options_metavar`` and  ``metavar`` kwargs.
+The default placeholder variable ([meta variable](https://en.wikipedia.org/wiki/Metasyntactic_variable#IETF_Requests_for_Comments)) in the help pages is the parameter name in uppercase with underscores. This can be changed for Commands and Parameters with the `options_metavar` and `metavar` kwargs.
 
+```{eval-rst}
 .. click:example::
 
     # This controls entry on the usage line.
@@ -240,28 +247,31 @@ The default placeholder variable (`meta variable <https://en.wikipedia.org/wiki/
         for x in range(count):
             click.echo(f"Hello {name}!")
 
-Example:
+# Example usage:
 
 .. click:run::
-
     invoke(hello, args=['--help'])
 
-Help Parameter Customization
-----------------------------
-Help parameters are automatically added by Click for any command. The default is ``--help`` but can be override by the context setting :attr:`~Context.help_option_names`. Click also performs automatic conflict resolution on the default help parameter so if a command itself implements a parameter named ``help`` then the default help will not be run.
+```
+
+## Help Parameter Customization
+
+Help parameters are automatically added by Click for any command. The default is `--help` but can be overridden by the context setting {attr}`~Context.help_option_names`. Click also performs automatic conflict resolution on the default help parameter, so if a command itself implements a parameter named `help` then the default help will not be run.
 
-This example changes the default parameters to ``-h`` and ``--help``
-instead of just ``--help``:
+This example changes the default parameters to `-h` and `--help`
+instead of just `--help`:
 
+```{eval-rst}
 .. click:example::
 
+    import click
+
     CONTEXT_SETTINGS = dict(help_option_names=['-h', '--help'])
 
     @click.command(context_settings=CONTEXT_SETTINGS)
     def cli():
         pass
 
-
 .. click:run::
-
     invoke(cli, ['-h'])
+```

{click-8.2.1 → click-8.2.2}/docs/entry-points.rst

@@ -2,7 +2,7 @@ Packaging Entry Points
 ======================
 
 It's recommended to write command line utilities as installable packages with
-entry points instead telling users to run ``python hello.py``.
+entry points instead of telling users to run ``python hello.py``.
 
 A distribution package is a ``.whl`` file you install with pip or another Python
 installer. You use a ``pyproject.toml`` file to describe the project and how it
@@ -55,7 +55,7 @@ Contents of ``pyproject.toml``:
     ]
 
     [project.scripts]
-    hello = "hello:cli"
+    hello = "hello.hello:cli"
 
     [build-system]
     requires = ["flit_core<4"]

{click-8.2.1 → click-8.2.2}/docs/index.rst

@@ -3,10 +3,9 @@
 Welcome to Click
 ================
 
-.. image:: _static/click-logo.png
+.. image:: _static/click-name.svg
     :align: center
-    :scale: 50%
-    :target: https://palletsprojects.com/p/click/
+    :height: 200px
 
 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
@@ -58,7 +57,7 @@ You can get the library directly from PyPI::
     pip install click
 
 Documentation
--------------
+==============
 
 .. toctree::
    :maxdepth: 2
@@ -66,7 +65,7 @@ Documentation
    faqs
 
 Tutorials
-^^^^^^^^^^^^^
+------------
 .. toctree::
    :maxdepth: 1
 
@@ -74,15 +73,16 @@ Tutorials
    virtualenv
 
 How to Guides
-^^^^^^^^^^^^^
+---------------
 .. toctree::
    :maxdepth: 1
 
    entry-points
    setuptools
+   support-multiple-versions
 
 Conceptual Guides
-^^^^^^^^^^^^^^^^^^^
+-------------------
 .. toctree::
    :maxdepth: 1
 
@@ -90,7 +90,7 @@ Conceptual Guides
    click-concepts
 
 General Reference
-^^^^^^^^^^^^^^^^^^^
+--------------------
 
 .. toctree::
    :maxdepth: 1
@@ -116,7 +116,7 @@ General Reference
    wincmd
 
 API Reference
-^^^^^^^^^^^^^^^
+-------------------
 
 .. toctree::
    :maxdepth: 2
@@ -124,7 +124,7 @@ API Reference
    api
 
 About Project
--------------------
+===============
 
 * This documentation is structured according to `Diataxis <https://diataxis.fr/>`_
 

{click-8.2.1 → click-8.2.2}/docs/options.md

@@ -152,8 +152,8 @@ To make an option take multiple values, pass in `nargs`. Note only a fixed numbe
 
 ## Multi Value Options as Tuples
 
-:::{versionadded} 4.0
-:::
+```{versionadded} 4.0
+```
 
 As you can see that by using `nargs` set to a specific number each item in
 the resulting tuple is of the same type. This might not be what you want.
@@ -289,8 +289,8 @@ If a forward slash(`/`) is contained in your option name already, you can split
         click.echo(f"debug={debug}")
 ```
 
-:::{versionchanged} 6.0
-:::
+```{versionchanged} 6.0
+```
 
 If you want to define an alias for the second option only, then you will need to use leading whitespace to disambiguate the format string.
 
@@ -368,6 +368,31 @@ If a list is passed to `envvar`, the first environment variable found is picked.
 
 ```
 
+Variable names are:
+ - [Case-insensitive on Windows but not on other platforms](https://github.com/python/cpython/blob/aa9eb5f757ceff461e6e996f12c89e5d9b583b01/Lib/os.py#L777-L789).
+ - Not stripped of whitespaces and should match the exact name provided to the `envvar` argument.
+
+For flag options, there is two concepts to consider: the activation of the flag driven by the environment variable, and the value of the flag if it is activated.
+
+The environment variable need to be interpreted, because values read from them are always strings. We need to transform these strings into boolean values that will determine if the flag is activated or not.
+
+Here are the rules used to parse environment variable values for flag options:
+   - `true`, `1`, `yes`, `on`, `t`, `y` are interpreted as activating the flag
+   - `false`, `0`, `no`, `off`, `f`, `n` are interpreted as deactivating the flag
+   - The presence of the environment variable without value is interpreted as deactivating the flag
+   - Empty strings are interpreted as deactivating the flag
+   - Values are case-insensitive, so the `True`, `TRUE`, `tRuE` strings are all activating the flag
+   - Values are stripped of leading and trailing whitespaces before being interpreted, so the `" True "` string is transformed to `"true"` and so activates the flag
+   - If the flag option has a `flag_value` argument, passing that value in the environment variable will activate the flag, in addition to all the cases described above
+   - Any other value is interpreted as deactivating the flag
+
+.. caution::
+    For boolean flags with a pair of values, the only recognized environment variable is the one provided to the `envvar` argument.
+
+    So an option defined as `--flag\--no-flag`, with a `envvar="FLAG"` parameter, there is no magical `NO_FLAG=<anything>` variable that is recognized. Only the `FLAG=<anything>` environment variable is recognized.
+
+Once the status of the flag has been determine to be activated or not, the `flag_value` is used as the value of the flag if it is activated. If the flag is not activated, the value of the flag is set to `None` by default.
+
 ## Multiple Options from Environment Values
 
 As options can accept multiple values, pulling in such values from
@@ -432,8 +457,8 @@ providing only the option's flag without a value will either show a
 prompt or use its `flag_value`.
 
 Setting `is_flag=False, flag_value=value` tells Click that the option
-can still be passed a value, but only if the flag is given the
-`flag_value`.
+can still be passed a value, but if only the flag is given, the
+value will be `flag_value`.
 
 ```{eval-rst}
 .. click:example::