docopt2 1.0.0__tar.gz → 1.0.2__tar.gz

docopt2-1.0.2/.codecov.yml

@@ -0,0 +1,10 @@
+coverage:
+  status:
+    project:
+      default:
+        target: 100%
+        threshold: 0%
+    patch:
+      default:
+        target: 100%
+        threshold: 0%

{docopt2-1.0.0 → docopt2-1.0.2}/.github/workflows/ci.yml

@@ -46,16 +46,19 @@ jobs:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
 
+      # --locked: a lockfile that has drifted from pyproject.toml is an error. Plain `uv sync` would
+      # silently re-resolve and test a dependency set that is in nobody's checkout.
       - name: Install dependencies
-        run: uv sync
+        run: uv sync --locked
 
       - name: Test with coverage (100% gate)
         if: matrix.coverage
         run: uv run pytest --cov-report=xml
 
+      # --no-cov, not `-o addopts=`: clearing addopts would drop --strict-markers along with coverage.
       - name: Test
         if: '!matrix.coverage'
-        run: uv run pytest -o addopts=
+        run: uv run pytest --no-cov
 
       - name: Upload coverage to Codecov
         if: matrix.coverage
@@ -80,13 +83,13 @@ jobs:
           python-version: "3.14"
 
       - name: Install dependencies
-        run: uv sync --group typecheck
+        run: uv sync --group typecheck --locked
 
       - name: Ruff check
-        run: uv run ruff check src tests
+        run: uv run ruff check src tests tools
 
       - name: Ruff format check
-        run: uv run ruff format --check src tests
+        run: uv run ruff format --check src tests tools
 
       - name: Type check (ty)
         run: uv run ty check
@@ -103,10 +106,38 @@ jobs:
       - name: Type check (pyright, floor target 3.10)
         run: uv run pyright --pythonversion 3.10 src/docopt2
 
+  # The unit tests pin what the generated completion SCRIPTS say; they never run them, and that is exactly
+  # where a completion bug hides. This drives real shells through a pty and a real Tab keypress, and holds
+  # what they offer against the grammar. It is known to fail on an unfixed script, so it guards rather than
+  # decorates. PowerShell exposes its completion engine to code, so it runs on the Windows cell.
+  shells:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+      - name: Install zsh and fish
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends zsh fish
+
+      - name: Complete in a real terminal
+        run: uv run --locked python tools/shell_check.py
+
   ci-ok:
-    needs: [test, lint]
+    needs: [test, lint, shells]
     if: always()
     runs-on: ubuntu-latest
     steps:
       - name: Verify required jobs succeeded
-        run: '[ "${{ needs.test.result }}" = "success" ] && [ "${{ needs.lint.result }}" = "success" ]'
+        run: >-
+          [ "${{ needs.test.result }}" = "success" ]
+          && [ "${{ needs.lint.result }}" = "success" ]
+          && [ "${{ needs.shells.result }}" = "success" ]

docopt2-1.0.2/.github/workflows/nightly.yml

@@ -0,0 +1,32 @@
+name: Nightly
+
+# The gate runs Hypothesis derandomised at 300 examples, deliberately: a PR check that flakes is a check
+# people learn to ignore. The cost is that every run sees the same inputs, so a rare violation can sit
+# there forever. This explores 10,000 randomised examples per property, off the critical path, where a
+# failure is a finding rather than a blocked merge.
+
+on:
+  schedule:
+    - cron: "23 3 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  explore:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+      - name: Property tests, wide and randomised
+        run: uv run --locked pytest --hypothesis-profile=explore -q --no-cov

{docopt2-1.0.0 → docopt2-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docopt2
-Version: 1.0.0
+Version: 1.0.2
 Summary: Typed successor to docopt: the usage message is the parser spec.
 Project-URL: Homepage, https://github.com/Solganis/docopt2
 Project-URL: Repository, https://github.com/Solganis/docopt2
@@ -11,7 +11,7 @@ License-Expression: MIT
 License-File: LICENSE
 License-File: NOTICE
 Keywords: argument-parser,cli,command-line,docopt,posix,typed,usage
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -49,6 +49,7 @@ Description-Content-Type: text/markdown
 <p align="center">
   <a href="https://github.com/Solganis/docopt2/actions/workflows/ci.yml"><img src="https://github.com/Solganis/docopt2/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://pypi.org/project/docopt2/"><img src="https://img.shields.io/pypi/v/docopt2" alt="PyPI version"></a>
+  <a href="https://pepy.tech/projects/docopt2"><img src="https://static.pepy.tech/badge/docopt2/month" alt="Downloads"></a>
   <a href="https://pypi.org/project/docopt2/"><img src="https://img.shields.io/pypi/pyversions/docopt2" alt="Python"></a>
   <a href="https://codecov.io/gh/Solganis/docopt2"><img src="https://codecov.io/gh/Solganis/docopt2/graph/badge.svg" alt="Coverage"></a>
   <br>
@@ -235,7 +236,7 @@ Usage:
 The same two carets flag a [malformed usage](https://solganis.github.io/docopt2/guides/diagnostics/#a-malformed-usage-at-import-time) at import time - a broken spec fails loudly, not silently - and [a value that will not coerce](https://solganis.github.io/docopt2/guides/diagnostics/#a-value-that-does-not-fit-its-type) to its typed field:
 
 <p align="center">
-  <img src="docs/assets/coercion.png" width="511" alt="A docopt2 error: 'invalid value for --port' with a caret under abc in the argument vector and a second caret under --port=<n> in the usage, plus 'help: abc is not a valid int'">
+  <img src="docs/assets/coercion.png" width="511" alt="A docopt2 error: 'invalid value for --port' with a caret under abc in the argument vector and a second caret under --port=<n> in the usage, plus 'note: abc is not a valid int'">
 </p>
 
 **[Closest usage line.](https://solganis.github.io/docopt2/guides/diagnostics/#the-usage-line-you-were-closest-to)** When several invocations are possible, docopt2 finds the one you got furthest into and carets the single element it still needs - not a generic "no match".

{docopt2-1.0.0 → docopt2-1.0.2}/README.md

@@ -13,6 +13,7 @@
 <p align="center">
   <a href="https://github.com/Solganis/docopt2/actions/workflows/ci.yml"><img src="https://github.com/Solganis/docopt2/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://pypi.org/project/docopt2/"><img src="https://img.shields.io/pypi/v/docopt2" alt="PyPI version"></a>
+  <a href="https://pepy.tech/projects/docopt2"><img src="https://static.pepy.tech/badge/docopt2/month" alt="Downloads"></a>
   <a href="https://pypi.org/project/docopt2/"><img src="https://img.shields.io/pypi/pyversions/docopt2" alt="Python"></a>
   <a href="https://codecov.io/gh/Solganis/docopt2"><img src="https://codecov.io/gh/Solganis/docopt2/graph/badge.svg" alt="Coverage"></a>
   <br>
@@ -199,7 +200,7 @@ Usage:
 The same two carets flag a [malformed usage](https://solganis.github.io/docopt2/guides/diagnostics/#a-malformed-usage-at-import-time) at import time - a broken spec fails loudly, not silently - and [a value that will not coerce](https://solganis.github.io/docopt2/guides/diagnostics/#a-value-that-does-not-fit-its-type) to its typed field:
 
 <p align="center">
-  <img src="docs/assets/coercion.png" width="511" alt="A docopt2 error: 'invalid value for --port' with a caret under abc in the argument vector and a second caret under --port=<n> in the usage, plus 'help: abc is not a valid int'">
+  <img src="docs/assets/coercion.png" width="511" alt="A docopt2 error: 'invalid value for --port' with a caret under abc in the argument vector and a second caret under --port=<n> in the usage, plus 'note: abc is not a valid int'">
 </p>
 
 **[Closest usage line.](https://solganis.github.io/docopt2/guides/diagnostics/#the-usage-line-you-were-closest-to)** When several invocations are possible, docopt2 finds the one you got furthest into and carets the single element it still needs - not a generic "no match".

docopt2-1.0.2/docs/assets/check.txt

@@ -0,0 +1,7 @@
+warning: option `--verbose` is declared but never used
+   |
+   |  in the options:
+   |      --verbose     Extra logging.
+   |      ^^^^^^^^^ declared here
+   |
+   = help: add `--verbose` to a usage line, or add `[options]` to accept it

docopt2-1.0.2/docs/assets/coercion.txt

@@ -0,0 +1,11 @@
+error: invalid value for `--port`
+   |
+   |  in the arguments:
+   |    --port=abc
+   |           ^^^ expected int
+   |
+   |  in the usage:
+   |    Usage: prog --port=<n>
+   |                ^^^^^^^^^^ typed as int
+   |
+   = note: `abc` is not a valid int

docopt2-1.0.2/docs/assets/diagnostic.txt

@@ -0,0 +1,11 @@
+error: unknown option `--forcce`
+   |
+   |  in the arguments:
+   |    push --forcce origin
+   |         ^^^^^^^^ not a known option
+   |
+   |  in the usage:
+   |      git push [--force] <remote>
+   |                ^^^^^^^ `--force` is defined here
+   |
+   = help: did you mean `--force`?

docopt2-1.0.2/docs/assets/rich-help.txt

@@ -0,0 +1,9 @@
+<span class="dt-fg">Serve a directory over HTTP.</span>
+
+<span class="dt-fg dt-b">Usage:</span>
+<span class="dt-fg">  serve [--port=&lt;n&gt;] [--host=&lt;h&gt;] [--log=&lt;lvl&gt;] &lt;root&gt;</span>
+
+<span class="dt-fg dt-b">Options:</span>
+<span class="dt-fg">  </span><span class="dt-help">--port=&lt;n&gt; </span><span class="dt-fg">  Port to bind.</span><span class="dt-dim">  [env: PORT, config: server.port, default: 8080]</span>
+<span class="dt-fg">  </span><span class="dt-help">--host=&lt;h&gt; </span><span class="dt-fg">  Interface to bind.</span><span class="dt-dim">  [env: HOST, default: 127.0.0.1]</span>
+<span class="dt-fg">  </span><span class="dt-help">--log=&lt;lvl&gt;</span><span class="dt-fg">  Log verbosity.</span><span class="dt-dim">  [config: logging.level, default: info]</span>

{docopt2-1.0.0 → docopt2-1.0.2}/docs/getting-started.md

@@ -145,7 +145,7 @@ and exits non-zero. Move a ship, but forget the second coordinate:
 <span class="dt-fg">   |</span><span class="dt-fg">      naval_fate ship &lt;name&gt; move &lt;x&gt; &lt;y&gt; [--speed=&lt;kn&gt;]</span>
 <span class="dt-fg">   |</span><span class="dt-fg">                                      </span><span class="dt-caret">^^^</span><span class="dt-label"> required here</span>
 <span class="dt-fg">   |</span>
-<span class="dt-fg">   = </span><span class="dt-help">help</span><span class="dt-fg">: closest of 6 usage patterns</span></div>
+<span class="dt-fg">   = </span><span class="dt-note">note</span><span class="dt-fg">: of 6 usage patterns, your arguments came closest to this one</span></div>
 
 docopt2 finds the usage line you got closest to and carets the one element it still needs (the full usage
 is printed beneath, trimmed here). Other mismatches - an unknown option, a value that will not fit its

{docopt2-1.0.0 → docopt2-1.0.2}/docs/guides/completion.md

@@ -29,9 +29,19 @@ the usage text. For `prog="naval"`, the bash script is:
 
 ```bash
 _naval_completion() {
+    local -a typed=()
+    local index part
+    for (( index = 1; index < COMP_CWORD; index++ )); do
+        part=${COMP_WORDS[index]}
+        if [[ ${#typed[@]} -gt 0 && ( $part == [:=] || ${COMP_WORDS[index-1]} == [:=] ) ]]; then
+            typed[$(( ${#typed[@]} - 1 ))]+=$part
+        else
+            typed+=("$part")
+        fi
+    done
     local IFS=$'\n'
-    local words="${COMP_WORDS[*]:1:COMP_CWORD-1}"
-    local reply; reply="$(_DOCOPT2_COMPLETE=1 _DOCOPT2_WORDS="$words" "${COMP_WORDS[0]}" | cut -f1)"
+    local words="${typed[*]}"
+    local reply; reply="$(_DOCOPT2_COMPLETE=1 _DOCOPT2_WORDS="$words" "${COMP_WORDS[0]}" 2>/dev/null | cut -f1)"
     COMPREPLY=( $(compgen -W "$reply" -- "${COMP_WORDS[COMP_CWORD]}") )
 }
 complete -F _naval_completion naval
@@ -40,6 +50,12 @@ complete -F _naval_completion naval
 It invokes the command the user typed (`${COMP_WORDS[0]}`), so `naval` must be on `PATH` under the name
 you passed as `prog`.
 
+The loop is not decoration. `COMP_WORDBREAKS` contains `=` and `:`, so bash hands the completion function
+`--port=8080` as three separate words - `--port`, `=`, `8080` - and `host:port` as three more. Passing those
+shards to the program would destroy the parse context and silently return no candidates at all for the rest
+of the line, and `--opt=<value>` is exactly the form the usage DSL teaches. bash emits the separator as its
+own word, so the shards glue back together unambiguously.
+
 ### Installing it
 
 `generate_completion` returns text; how it reaches the shell is up to you. Write it to a file you ship, or

{docopt2-1.0.0 → docopt2-1.0.2}/docs/guides/diagnostics.md

@@ -6,8 +6,11 @@ token, in the argument vector and in the usage that rejected it, with a two-span
 
 Every error, whether the user mistyped an argument or the developer wrote a malformed usage, is lowered
 to one shape: a bold `error:` heading with a one-line summary, then captioned source snippets with
-carets, then optional `note:` and `help:` lines. The static [usage linter](check.md) reuses the same
-grammar with a yellow `warning:` heading, so a warning and a hard error read the same way.
+carets, then optional `note:` and `help:` lines. The two are not interchangeable, and follow rustc's
+split: a `note:` gives context - why the input was rejected, or why this usage line is the one shown - while
+a `help:` proposes a concrete fix, such as a "did you mean". A diagnostic with nothing to suggest carries no
+`help:` at all. The static [usage linter](check.md) reuses the same grammar with a yellow `warning:` heading,
+so a warning and a hard error read the same way.
 
 ## A mismatch at parse time
 
@@ -116,7 +119,7 @@ docopt(doc, "push")
 <span class="dt-fg">   |</span><span class="dt-fg">      git push [--force] &lt;remote&gt;</span>
 <span class="dt-fg">   |</span><span class="dt-fg">                         </span><span class="dt-caret">^^^^^^^^</span><span class="dt-label"> required here</span>
 <span class="dt-fg">   |</span>
-<span class="dt-fg">   = </span><span class="dt-help">help</span><span class="dt-fg">: closest of 3 usage patterns</span></div>
+<span class="dt-fg">   = </span><span class="dt-note">note</span><span class="dt-fg">: of 3 usage patterns, your arguments came closest to this one</span></div>
 
 The snippet shows only the closest line - `git push`, not `commit` or `add` - because the caret is placed
 in *that* line. Typing `git commit` instead carets `--message=<msg>` on the second line; `git deploy prod`
@@ -155,7 +158,7 @@ docopt(doc, "--port=abc", schema=Args)   # raises the diagnostic below
 <span class="dt-fg">   |</span><span class="dt-fg">    Usage: prog --port=&lt;n&gt;</span>
 <span class="dt-fg">   |</span><span class="dt-fg">                </span><span class="dt-caret">^^^^^^^^^^</span><span class="dt-label"> typed as int</span>
 <span class="dt-fg">   |</span>
-<span class="dt-fg">   = </span><span class="dt-help">help</span><span class="dt-fg">: `abc` is not a valid int</span></div>
+<span class="dt-fg">   = </span><span class="dt-note">note</span><span class="dt-fg">: `abc` is not a valid int</span></div>
 
 Only a **user value** gets this two-span treatment. A schema that disagrees with the usage - a field with
 no matching element, an unsupported annotation - is the developer's error, not the user's, and raises

{docopt2-1.0.0 → docopt2-1.0.2}/docs/guides/typed-results.md

@@ -196,7 +196,7 @@ docopt("Usage: prog <port>", "eighty", schema=P)   # raises the diagnostic below
 <span class="dt-fg">   |</span><span class="dt-fg">    Usage: prog &lt;port&gt;</span>
 <span class="dt-fg">   |</span><span class="dt-fg">                </span><span class="dt-caret">^^^^^^</span><span class="dt-label"> typed as int</span>
 <span class="dt-fg">   |</span>
-<span class="dt-fg">   = </span><span class="dt-help">help</span><span class="dt-fg">: `eighty` is not a valid int</span></div>
+<span class="dt-fg">   = </span><span class="dt-note">note</span><span class="dt-fg">: `eighty` is not a valid int</span></div>
 
 A **schema** that disagrees with the usage raises `DocoptLanguageError` (a programmer error, not a user
 one): a field with no matching element, two elements colliding on one field, a non-optional field bound to

{docopt2-1.0.0 → docopt2-1.0.2}/docs/guides/usage-dsl.md

@@ -151,6 +151,11 @@ documents the same source chain, so users see where a value resolves from withou
     an empty `APP_PORT=` never silently overrides the config or the default with an empty string. The same
     holds for a `null` or empty config value.
 
+!!! warning "A config key must name a value, not a table"
+    An option takes one value, so `[config: server]` against `{"server": {"port": 80}}` is a mistake: the
+    key stops one level short. docopt2 says so, with a caret and the keys that would have worked, instead
+    of handing `--server` the string `{'port': 80}`. Scalars, dates and times pass through as written.
+
 ### Generate a config skeleton
 
 Once options declare `[config: key]`, [`generate_config_template`](../reference/config-templates.md) turns

{docopt2-1.0.0 → docopt2-1.0.2}/docs/reference/overview.md

@@ -19,5 +19,3 @@ exported names in `docopt2.__all__`.
   re-exported for drop-in compatibility with the original docopt.
 
 For a task-oriented view, start from the [Guides](../guides/typed-results.md) instead.
-
-<!-- TODO: keep this list in sync with docopt2.__all__ if the public surface changes. -->

{docopt2-1.0.0 → docopt2-1.0.2}/docs/stylesheets/extra.css

@@ -110,6 +110,7 @@
 [data-md-color-scheme="slate"] .docopt2-term .dt-warn  { color: #e3b341; }
 [data-md-color-scheme="slate"] .docopt2-term .dt-label { color: #e3b341; }
 [data-md-color-scheme="slate"] .docopt2-term .dt-help  { color: #56d364; }
+[data-md-color-scheme="slate"] .docopt2-term .dt-note  { color: #56d4dd; }
 [data-md-color-scheme="slate"] .docopt2-term .dt-dim   { color: #8b949e; }
 
 /* Light scheme: GitHub-light surface with the light-theme equivalents. */
@@ -124,4 +125,5 @@
 [data-md-color-scheme="default"] .docopt2-term .dt-warn  { color: #9a6700; }
 [data-md-color-scheme="default"] .docopt2-term .dt-label { color: #9a6700; }
 [data-md-color-scheme="default"] .docopt2-term .dt-help  { color: #1a7f37; }
+[data-md-color-scheme="default"] .docopt2-term .dt-note  { color: #1b7c83; }
 [data-md-color-scheme="default"] .docopt2-term .dt-dim   { color: #57606a; }

{docopt2-1.0.0 → docopt2-1.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docopt2"
-version = "1.0.0"
+version = "1.0.2"
 description = "Typed successor to docopt: the usage message is the parser spec."
 readme = "README.md"
 license = "MIT"
@@ -11,7 +11,7 @@ authors = [
 ]
 keywords = ["docopt", "cli", "command-line", "argument-parser", "usage", "posix", "typed"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Environment :: Console",
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
@@ -73,6 +73,9 @@ dev = [
     "typing_extensions>=4.6",
     # Dev-only: property-based tests (differential vs vanilla docopt, coercion round-trips).
     "hypothesis>=6",
+    # Dev-only: tomllib is stdlib only from 3.11, and without it the config-template round-trip
+    # would go unverified on the 3.10 floor - the one place a skip could hide a defect.
+    "tomli>=2 ; python_version < '3.11'",
 ]
 # Documentation site (mkdocs-material + mkdocstrings). Build-only; not shipped with the
 # package and not part of the zero runtime-dependency guarantee (that concerns
@@ -91,6 +94,8 @@ typecheck = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+# The repo root, so tests can import `tools.screenshots` - the single source of what each screenshot shows.
+pythonpath = ["."]
 # --strict-markers: an unknown @pytest.mark.* is an error, not a silent typo.
 # Coverage is always measured and gated at 100% (line + branch).
 addopts = [

docopt2-1.0.2/src/docopt2/__init__.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docopt2._completion import complete, generate_completion
+from docopt2._core import Arguments, Cli, Dispatch, Source, docopt, parse_tree
+from docopt2._errors import DocoptExit, DocoptLanguageError
+from docopt2._parser import (
+    Argument,
+    BranchPattern,
+    Command,
+    Either,
+    LeafPattern,
+    OneOrMore,
+    Option,
+    Optional,
+    OptionsShortcut,
+    Pattern,
+    Required,
+    Tokens,
+    formal_usage,
+    parse_argv,
+    parse_defaults,
+    parse_pattern,
+    parse_section,
+    transform,
+)
+
+if TYPE_CHECKING:  # real types for the lazily-loaded tooling below, at zero runtime import cost
+    from docopt2._compat import check_compat
+    from docopt2._fmt import format_usage
+    from docopt2._format import format_argv
+    from docopt2._generate import generate_config_template, generate_examples
+    from docopt2._lint import check
+    from docopt2._stub import generate_stub
+
+    __version__: str
+
+# This module is the public facade: it only re-exports names; the runtime (docopt, Cli, Dispatch,
+# Arguments, parse_tree) lives in _core, and the parser primitives (Tokens, formal_usage, parse_*,
+# transform) are re-exported for drop-in compatibility with the original docopt module.
+__all__ = [
+    "Argument",
+    "Arguments",
+    "BranchPattern",
+    "Cli",
+    "Command",
+    "Dispatch",
+    "DocoptExit",
+    "DocoptLanguageError",
+    "Either",
+    "LeafPattern",
+    "OneOrMore",
+    "Option",
+    "Optional",
+    "OptionsShortcut",
+    "Pattern",
+    "Required",
+    "Source",
+    "Tokens",
+    "check",
+    "check_compat",
+    "complete",
+    "docopt",
+    "formal_usage",
+    "format_argv",
+    "format_usage",
+    "generate_completion",
+    "generate_config_template",
+    "generate_examples",
+    "generate_stub",
+    "parse_argv",
+    "parse_defaults",
+    "parse_pattern",
+    "parse_section",
+    "parse_tree",
+    "transform",
+]
+
+# Tooling a plain docopt() call never needs loads on first access, so `import docopt2` stays lean.
+_LAZY_MODULES = {
+    "check": "docopt2._lint",
+    "check_compat": "docopt2._compat",
+    "format_argv": "docopt2._format",
+    "format_usage": "docopt2._fmt",
+    "generate_config_template": "docopt2._generate",
+    "generate_examples": "docopt2._generate",
+    "generate_stub": "docopt2._stub",
+}
+
+
+def __getattr__(name: str) -> object:
+    """Resolve deferred names (PEP 562): the version and the tooling functions, imported only when asked."""
+    if name == "__version__":
+        # importlib.metadata drags in ~22ms of stdlib (email, zipfile, inspect) the parser never needs.
+        from importlib.metadata import PackageNotFoundError, version
+
+        try:
+            return version("docopt2")
+        except PackageNotFoundError:  # pragma: no cover - only from a source tree with no installed dist
+            return "0.0.0"
+    module_name = _LAZY_MODULES.get(name)
+    if module_name is not None:
+        from importlib import import_module
+
+        value = getattr(import_module(module_name), name)
+        globals()[name] = value  # cache: later lookups find it directly and skip __getattr__
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{docopt2-1.0.0 → docopt2-1.0.2}/src/docopt2/_completion.py

@@ -188,35 +188,70 @@ def _function_name(prog: str) -> str:
 
 
 def _render_bash(prog: str, function: str) -> str:
-    # bash completion shows names only, so strip the tab-joined description column with `cut -f1`.
+    # COMP_WORDBREAKS holds `=` and `:`, so bash splits `--opt=value` into three COMP_WORDS. Forwarding the
+    # shards destroys the parse context and kills every later completion; bash emits the separator as its
+    # own word, so the loop glues them back.
+    template = (
+        "__FUNC__() {\n"
+        "    local -a typed=()\n"
+        "    local index part\n"
+        "    for (( index = 1; index < COMP_CWORD; index++ )); do\n"
+        "        part=${COMP_WORDS[index]}\n"
+        "        if [[ ${#typed[@]} -gt 0 && ( $part == [:=] || ${COMP_WORDS[index-1]} == [:=] ) ]]; then\n"
+        "            typed[$(( ${#typed[@]} - 1 ))]+=$part\n"
+        "        else\n"
+        '            typed+=("$part")\n'
+        "        fi\n"
+        "    done\n"
+        "    local IFS=$'\\n'\n"
+        '    local words="${typed[*]}"\n'  # completed tokens, glued back, without the program name
+        '    local reply; reply="$(__TRIGGER__=1 __WORDS__="$words" "${COMP_WORDS[0]}" 2>/dev/null | cut -f1)"\n'
+        '    COMPREPLY=( $(compgen -W "$reply" -- "${COMP_WORDS[COMP_CWORD]}") )\n'
+        "}\n"
+        "complete -F __FUNC__ __PROG__\n"
+    )
     return (
-        f"{function}() {{\n"
-        f"    local IFS=$'\\n'\n"
-        f'    local words="${{COMP_WORDS[*]:1:COMP_CWORD-1}}"\n'  # completed tokens, not the current word
-        f'    local reply; reply="$({_TRIGGER_ENV}=1 {_WORDS_ENV}="$words" "${{COMP_WORDS[0]}}" | cut -f1)"\n'
-        f'    COMPREPLY=( $(compgen -W "$reply" -- "${{COMP_WORDS[COMP_CWORD]}}") )\n'
-        f"}}\n"
-        f"complete -F {function} {prog}\n"
+        template.replace("__PROG__", prog)
+        .replace("__FUNC__", function)
+        .replace("__TRIGGER__", _TRIGGER_ENV)
+        .replace("__WORDS__", _WORDS_ENV)
     )
 
 
 def _render_zsh(prog: str, function: str) -> str:
-    # Split each `name\tdescription` reply line and hand it to `_describe`, which renders the two-column
-    # name/description list and filters by the word being completed. Template, not an f-string, to keep
-    # the brace- and quote-heavy zsh readable.
+    # Commands reply with an empty description, and `_describe` renders one as a dangling `--`, so bare
+    # names go to `compadd` instead. The two groups are added under `if`, not `&&`: an empty group would
+    # otherwise leave a non-zero status and zsh would read that as "nothing matched".
     template = (
         "#compdef __PROG__\n"
         "__FUNC__() {\n"
         '    local joined="${(pj:\\n:)words[2,CURRENT-1]}"\n'  # completed tokens, not the current word
-        "    local -a lines described\n"
+        "    local -a lines described bare\n"
         '    lines=("${(@f)$(__TRIGGER__=1 __WORDS__=$joined ${words[1]})}")\n'
-        "    local line\n"
+        "    local line desc\n"
         "    for line in $lines; do\n"
-        "        described+=(\"${line%%$'\\t'*}:${line#*$'\\t'}\")\n"
+        "        desc=\"${line#*$'\\t'}\"\n"
+        "        if [[ -n $desc ]]; then\n"
+        "            described+=(\"${line%%$'\\t'*}:$desc\")\n"
+        "        else\n"
+        "            bare+=(\"${line%%$'\\t'*}\")\n"
+        "        fi\n"
         "    done\n"
-        "    _describe -t candidates candidate described\n"
+        "    if (( $#described )); then\n"
+        "        _describe -t candidates candidate described\n"
+        "    fi\n"
+        "    if (( $#bare )); then\n"
+        "        compadd -a bare\n"
+        "    fi\n"
         "}\n"
-        "compdef __FUNC__ __PROG__\n"
+        # Autoloaded from `$fpath`, zsh runs this file's body AS the completion function, so a body that
+        # only defines and registers offers nothing on the first Tab. `CURRENT` exists only while the
+        # completion system runs, which tells that install apart from a plain `source`.
+        "if (( ${+CURRENT} )); then\n"
+        '    __FUNC__ "$@"\n'
+        "else\n"
+        "    compdef __FUNC__ __PROG__\n"
+        "fi\n"
     )
     return (
         template.replace("__PROG__", prog)
@@ -232,7 +267,10 @@ def _render_fish(prog: str, function: str) -> str:
         # `commandline -opc` is the completed tokens before the cursor (the partial word is excluded);
         # fish filters the candidates we return by that partial word itself.
         f"    set -l tokens (commandline -opc)\n"
-        f"    env {_TRIGGER_ENV}=1 {_WORDS_ENV}=(string join \\n -- $tokens[2..-1]) $tokens[1]\n"
+        # fish documents that a command substitution splits its output on newlines. A completion function
+        # happens not to re-split today, but that is undocumented; `string collect` states the intent rather
+        # than depending on the accident.
+        f"    env {_TRIGGER_ENV}=1 {_WORDS_ENV}=(string join \\n -- $tokens[2..-1] | string collect) $tokens[1]\n"
         f"end\n"
         f"complete -c {prog} -f -a '({function})'\n"
     )
@@ -244,15 +282,22 @@ def _render_powershell(prog: str, _function: str) -> str:
     template = (
         "Register-ArgumentCompleter -Native -CommandName __PROG__ -ScriptBlock {\n"
         "    param($wordToComplete, $commandAst, $cursorPosition)\n"
-        "    $words = @($commandAst.CommandElements | Select-Object -Skip 1 | ForEach-Object { $_.ToString() })\n"
+        # PowerShell hands over the whole line, so a mid-line Tab would read the tokens right of the cursor.
+        "    $typed = @($commandAst.CommandElements | Where-Object { $_.Extent.EndOffset -le $cursorPosition })\n"
+        # A quoted token arrives with its quotes attached; the program must get the value, not the quoting.
+        "    $words = @($typed | Select-Object -Skip 1 | ForEach-Object {\n"
+        "        if ($_ -is [System.Management.Automation.Language.StringConstantExpressionAst])"
+        " { $_.Value } else { $_.ToString() }\n"
+        "    })\n"
         "    if ($wordToComplete -ne '' -and $words.Count -gt 0) { $words = @($words | Select-Object -SkipLast 1) }\n"
         "    $env:__TRIGGER__ = '1'\n"
         '    $env:__WORDS__ = ($words -join "`n")\n'
         "    try {\n"
-        "        & $commandAst.CommandElements[0].ToString() | ForEach-Object {\n"
+        "        & $commandAst.CommandElements[0].ToString() 2>$null | ForEach-Object {\n"
         '            $parts = $_ -split "`t", 2\n'  # reply line is name`tdescription
         "            $name = $parts[0]\n"
-        '            if ($name -like "$wordToComplete*") {\n'
+        # StartsWith, not -like: a `*` or `[` in the partial word is a literal prefix, not a wildcard.
+        "            if ($name.StartsWith($wordToComplete, [System.StringComparison]::Ordinal)) {\n"
         "                $tip = if ($parts.Count -ge 2 -and $parts[1]) { $parts[1] } else { $name }\n"
         "                [System.Management.Automation.CompletionResult]::new($name, $name, 'ParameterValue', $tip)\n"
         "            }\n"