docopt2 1.1.2__tar.gz → 1.2.0__tar.gz

{docopt2-1.1.2 → docopt2-1.2.0}/.github/workflows/ci.yml

@@ -86,10 +86,10 @@ jobs:
         run: uv sync --group typecheck --locked
 
       - name: Ruff check
-        run: uv run ruff check src tests tools
+        run: uv run ruff check src tests tools fuzz benchmarks
 
       - name: Ruff format check
-        run: uv run ruff format --check src tests tools
+        run: uv run ruff format --check src tests tools fuzz benchmarks
 
       - name: Type check (ty)
         run: uv run ty check
@@ -128,6 +128,14 @@ jobs:
         if: runner.os == 'Linux'
         run: sudo apt-get update && sudo apt-get install -y --no-install-recommends zsh fish
 
+      - name: Install nushell
+        # Not in the Ubuntu repos; pinned to the version the completer targets (`commandline complete`
+        # landed in 0.114.0). Drop the release tarball on PATH.
+        if: runner.os == 'Linux'
+        run: |
+          curl -sSfL https://github.com/nushell/nushell/releases/download/0.114.1/nu-0.114.1-x86_64-unknown-linux-gnu.tar.gz | tar xz -C "$HOME"
+          echo "$HOME/nu-0.114.1-x86_64-unknown-linux-gnu" >> "$GITHUB_PATH"
+
       - name: Complete in a real terminal
         run: uv run --locked python tools/shell_check.py
 

docopt2-1.2.0/.github/workflows/codspeed.yml

@@ -0,0 +1,40 @@
+name: CodSpeed
+
+# Continuous performance gate: run the micro-benchmarks (benchmarks/test_perf.py) under CodSpeed's CPU
+# simulation, which measures a deterministic instruction count rather than wall time, so a runner's noise
+# never flakes it. CodSpeed compares each commit to the base and reports a pass/fail on the PR. A public
+# repo uploads over OIDC (id-token), so no token secret is needed - only the CodSpeed GitHub App installed.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  benchmarks:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    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: Run benchmarks under CodSpeed
+        uses: CodSpeedHQ/action@f99becdce5e5d51fd556489ebef684f4ecfd6286 # v4.18.5
+        with:
+          mode: simulation
+          run: uv run --locked --group benchmark pytest benchmarks/ --codspeed --no-cov

docopt2-1.2.0/.github/workflows/fuzz.yml

@@ -0,0 +1,50 @@
+name: Fuzz
+
+# Coverage-guided fuzzing of the public API with atheris, off the PR path. The invariant is the one
+# tests/test_robustness.py states and Hypothesis checks on grammar-shaped input: no entry point may raise
+# anything but DocoptExit / DocoptLanguageError for any input. The Nightly job explores well-formed usage
+# with Hypothesis; this reaches the malformed byte shapes it cannot, under coverage feedback, and a
+# per-input -timeout turns a runaway (a pathological slowdown or an outright hang) into a finding. Unlike
+# Mutation (report-only), a crash or timeout here is a real bug: the job fails and uploads the reproducer,
+# which becomes a committed regression test.
+#
+# Linux only: atheris ships no Windows wheel. Pinned to Python 3.12, which has a prebuilt manylinux wheel.
+
+on:
+  schedule:
+    - cron: "41 4 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  fuzz:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    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: Fuzz the public API for ten minutes
+        run: |
+          mkdir -p fuzz-findings
+          uv run --locked --no-dev --python 3.12 --with atheris \
+            python fuzz/fuzz_docopt.py \
+            -max_total_time=600 -timeout=30 -rss_limit_mb=4096 -artifact_prefix=fuzz-findings/
+
+      - name: Upload any crash or timeout reproducer
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: fuzz-findings
+          path: fuzz-findings/
+          if-no-files-found: ignore

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

@@ -0,0 +1,57 @@
+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
+
+  # A red nightly is a real property violation, not noise (unlike the Mutation survivors), yet it is off
+  # the merge path, so nothing surfaces it - a failure sat unseen for days. On failure open, or bump, a
+  # single tracking issue so it is visible without anyone watching the schedule.
+  notify:
+    needs: explore
+    if: failure()
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - name: Open or bump the tracking issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          title="Nightly wide-hypothesis run is failing"
+          number=$(gh issue list --repo "$REPO" --state open --search "$title in:title" --json number --jq '.[0].number // empty')
+          if [ -n "$number" ]; then
+            gh issue comment "$number" --repo "$REPO" --body "Still failing: $RUN_URL"
+          else
+            gh issue create --repo "$REPO" --title "$title" \
+              --body "The scheduled wide Hypothesis run (10k examples) failed - it catches divergences the 300-example gate misses. Run: $RUN_URL"
+          fi

{docopt2-1.1.2 → docopt2-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docopt2
-Version: 1.1.2
+Version: 1.2.0
 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 :: 5 - Production/Stable
+Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -47,20 +47,16 @@ Description-Content-Type: text/markdown
 </p>
 
 <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://github.com/Solganis/docopt2/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Solganis/docopt2/ci.yml?branch=main&amp;label=CI" alt="CI"></a>
+  <a href="https://codecov.io/gh/Solganis/docopt2"><img src="https://codecov.io/gh/Solganis/docopt2/graph/badge.svg" alt="Coverage"></a>
   <a href="https://pypi.org/project/docopt2/"><img src="https://img.shields.io/pypi/v/docopt2" alt="PyPI version"></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>
   <a href="https://pepy.tech/projects/docopt2"><img src="https://static.pepy.tech/badge/docopt2/month" alt="Downloads"></a>
   <br>
-  <a href="https://solganis.github.io/docopt2/"><img src="https://img.shields.io/badge/Docs-online-black" alt="Documentation"></a>
-  <a href="https://docs.astral.sh/ruff/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
-  <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv"></a>
-  <a href="https://github.com/astral-sh/ty"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json" alt="ty"></a>
-  <a href="https://scorecard.dev/viewer/?uri=github.com/Solganis/docopt2"><img src="https://api.scorecard.dev/projects/github.com/Solganis/docopt2/badge" alt="OpenSSF Scorecard"></a>
-  <br>
-  <img src="https://img.shields.io/badge/runtime%20deps-0-2ea043" alt="zero runtime dependencies, pydantic support optional">
-  <img src="https://img.shields.io/badge/type--checked-ty%20%7C%20mypy%20%7C%20pyright-2ea043" alt="the typed API is checked by ty, mypy --strict, and pyright">
+  <a href="https://solganis.github.io/docopt2/concepts/design-boundaries/"><img src="https://img.shields.io/badge/runtime%20deps-0-2ea043" alt="zero runtime dependencies, pydantic support optional"></a>
+  <a href="https://solganis.github.io/docopt2/guides/typed-results/"><img src="https://img.shields.io/badge/type--checked-ty%20%7C%20mypy%20%7C%20pyright-2ea043" alt="the typed API is checked by ty, mypy --strict, and pyright"></a>
+  <a href="https://solganis.github.io/docopt2/"><img src="https://img.shields.io/badge/docs-online-black" alt="Documentation"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/Solganis/docopt2"><img src="https://img.shields.io/ossf-scorecard/github.com/Solganis/docopt2?label=OpenSSF%20Scorecard" alt="OpenSSF Scorecard"></a>
 </p>
 
 ---
@@ -95,7 +91,7 @@ Route each subcommand to its own handler - no <code>if args[...]</code> ladder.
 </td>
 <td valign="top">
 <a href="#shell-completion"><b>Shell completion</b></a><br>
-Tab-completion that knows your grammar: bash, zsh, fish, PowerShell.
+Tab-completion that knows your grammar: bash, zsh, fish, PowerShell, nushell.
 </td>
 </tr>
 <tr>
@@ -274,6 +270,7 @@ app.run()   # parse argv, call the matched command's handler
   <a href="https://www.zsh.org/"><img src="https://img.shields.io/badge/zsh-F15A24?logo=zsh&logoColor=white" alt="zsh"></a>
   <a href="https://fishshell.com/"><img src="https://img.shields.io/badge/fish-34C534?logo=fishshell&logoColor=white" alt="fish"></a>
   <a href="https://learn.microsoft.com/powershell/"><img src="https://img.shields.io/badge/PowerShell-5391FE" alt="PowerShell"></a>
+  <a href="https://www.nushell.sh/"><img src="https://img.shields.io/badge/nushell-4E9A06?logo=nushell&logoColor=white" alt="nushell"></a>
 </p>
 
 Generate the completion script for your shell; Tab then narrows to exactly what is valid at the cursor -<br>

{docopt2-1.1.2 → docopt2-1.2.0}/README.md

@@ -11,20 +11,16 @@
 </p>
 
 <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://github.com/Solganis/docopt2/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Solganis/docopt2/ci.yml?branch=main&amp;label=CI" alt="CI"></a>
+  <a href="https://codecov.io/gh/Solganis/docopt2"><img src="https://codecov.io/gh/Solganis/docopt2/graph/badge.svg" alt="Coverage"></a>
   <a href="https://pypi.org/project/docopt2/"><img src="https://img.shields.io/pypi/v/docopt2" alt="PyPI version"></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>
   <a href="https://pepy.tech/projects/docopt2"><img src="https://static.pepy.tech/badge/docopt2/month" alt="Downloads"></a>
   <br>
-  <a href="https://solganis.github.io/docopt2/"><img src="https://img.shields.io/badge/Docs-online-black" alt="Documentation"></a>
-  <a href="https://docs.astral.sh/ruff/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
-  <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv"></a>
-  <a href="https://github.com/astral-sh/ty"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json" alt="ty"></a>
-  <a href="https://scorecard.dev/viewer/?uri=github.com/Solganis/docopt2"><img src="https://api.scorecard.dev/projects/github.com/Solganis/docopt2/badge" alt="OpenSSF Scorecard"></a>
-  <br>
-  <img src="https://img.shields.io/badge/runtime%20deps-0-2ea043" alt="zero runtime dependencies, pydantic support optional">
-  <img src="https://img.shields.io/badge/type--checked-ty%20%7C%20mypy%20%7C%20pyright-2ea043" alt="the typed API is checked by ty, mypy --strict, and pyright">
+  <a href="https://solganis.github.io/docopt2/concepts/design-boundaries/"><img src="https://img.shields.io/badge/runtime%20deps-0-2ea043" alt="zero runtime dependencies, pydantic support optional"></a>
+  <a href="https://solganis.github.io/docopt2/guides/typed-results/"><img src="https://img.shields.io/badge/type--checked-ty%20%7C%20mypy%20%7C%20pyright-2ea043" alt="the typed API is checked by ty, mypy --strict, and pyright"></a>
+  <a href="https://solganis.github.io/docopt2/"><img src="https://img.shields.io/badge/docs-online-black" alt="Documentation"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/Solganis/docopt2"><img src="https://img.shields.io/ossf-scorecard/github.com/Solganis/docopt2?label=OpenSSF%20Scorecard" alt="OpenSSF Scorecard"></a>
 </p>
 
 ---
@@ -59,7 +55,7 @@ Route each subcommand to its own handler - no <code>if args[...]</code> ladder.
 </td>
 <td valign="top">
 <a href="#shell-completion"><b>Shell completion</b></a><br>
-Tab-completion that knows your grammar: bash, zsh, fish, PowerShell.
+Tab-completion that knows your grammar: bash, zsh, fish, PowerShell, nushell.
 </td>
 </tr>
 <tr>
@@ -238,6 +234,7 @@ app.run()   # parse argv, call the matched command's handler
   <a href="https://www.zsh.org/"><img src="https://img.shields.io/badge/zsh-F15A24?logo=zsh&logoColor=white" alt="zsh"></a>
   <a href="https://fishshell.com/"><img src="https://img.shields.io/badge/fish-34C534?logo=fishshell&logoColor=white" alt="fish"></a>
   <a href="https://learn.microsoft.com/powershell/"><img src="https://img.shields.io/badge/PowerShell-5391FE" alt="PowerShell"></a>
+  <a href="https://www.nushell.sh/"><img src="https://img.shields.io/badge/nushell-4E9A06?logo=nushell&logoColor=white" alt="nushell"></a>
 </p>
 
 Generate the completion script for your shell; Tab then narrows to exactly what is valid at the cursor -<br>

docopt2-1.2.0/benchmarks/test_perf.py

@@ -0,0 +1,53 @@
+# CodSpeed regression gate: micro-benchmarks of docopt2's own hot paths, measured commit-over-commit under
+# CPU simulation. Run manually with `uv run --group benchmark pytest benchmarks/ --codspeed --no-cov`; the
+# CodSpeed CI job runs the same. Not collected by the default suite (testpaths=tests), so it never gates on
+# the machine's noise - only CodSpeed's simulated instruction count does.
+from __future__ import annotations
+
+import dataclasses
+
+from docopt2 import complete, docopt
+
+# A git/naval-shaped CLI: subcommands, a variadic, a default, and two mutex groups.
+NAVAL = """Usage:
+  naval ship new <name>...
+  naval ship <name> move <x> <y> [--speed=<kn>]
+  naval mine (set | remove) <x> <y> [--moored | --drifting]
+  naval --help
+
+Options:
+  --speed=<kn>  Speed in knots [default: 10].
+  --moored      Moored (anchored) mine.
+  --drifting    Drifting mine.
+"""
+
+# Eight optionals on one line: exercises the _combine search that the match budget bounds - a guard against
+# a regression in the matcher's cost.
+MANY_OPTIONALS = "usage: prog [-a] [-b] [-c] [-d] [-e] [-f] [-g] [-h] <src> <dst>"
+
+TYPED_DOC = "Usage: app <host> <port> [--verbose] [--retries=<n>]"
+
+
+@dataclasses.dataclass
+class Config:
+    host: str
+    port: int
+    verbose: bool
+    retries: int
+
+
+def test_single_shot_parse_and_match(benchmark):
+    # The realistic per-invocation cost: parse the usage and match one argv (docopt2 reparses every call).
+    benchmark(lambda: docopt(NAVAL, ["ship", "Titanic", "move", "1", "2", "--speed=20"], help=False))
+
+
+def test_match_many_optionals(benchmark):
+    benchmark(lambda: docopt(MANY_OPTIONALS, ["-a", "-c", "-e", "in.txt", "out.txt"], help=False))
+
+
+def test_typed_binding_and_coercion(benchmark):
+    benchmark(lambda: docopt(TYPED_DOC, ["localhost", "8080", "--verbose", "--retries=3"], schema=Config, help=False))
+
+
+def test_completion_latency(benchmark):
+    benchmark(lambda: complete(NAVAL, ["ship"]))

{docopt2-1.1.2 → docopt2-1.2.0}/docs/concepts/design-boundaries.md

@@ -118,7 +118,7 @@ the surrounding program or a dedicated library, layered on top of the parsed res
 
 The typed surface is plain typing with no runtime cost. The [`Cli`](../reference/cli.md) base class is
 the only decorator-shaped sugar, and it is deliberately a base class rather than a method-injecting
-decorator so the result keeps real static types under ty, mypy, and pyright.
+decorator, so the result keeps real static types a type checker can see instead of degrading to `Any`.
 
 Typing is a layer over the drop-in core, not a rewrite of it. The same `docopt()` call runs the same
 parse; passing `schema=` adds one final bind step that coerces the string values to the field types you

{docopt2-1.1.2 → docopt2-1.2.0}/docs/guides/completion.md

@@ -1,7 +1,7 @@
 # Shell completion
 
 `generate_completion` emits a context-aware completion script for the CLI described by your usage, for
-bash, zsh, fish, and PowerShell - the same four Typer supports, and one more than Click. The script carries no grammar of
+bash, zsh, fish, PowerShell, and nushell. The script carries no grammar of
 its own: it delegates every Tab back to your program, whose [`docopt`](../reference/docopt.md) call
 resolves the candidates from the usage. This guide covers generating and installing that script, and
 computing the candidates directly with `complete()`.
@@ -15,7 +15,7 @@ script = generate_completion(doc, prog="naval", shell="bash")
 ```
 
 The signature is `generate_completion(doc, prog, shell="bash") -> str`. `shell` is one of `"bash"`,
-`"zsh"`, `"fish"`, or `"powershell"`; any other value raises `ValueError`, as does a `prog` that is not a
+`"zsh"`, `"fish"`, `"powershell"`, or `"nushell"`; any other value raises `ValueError`, as does a `prog` that is not a
 plain command name (letters, digits, `.`, `_`, `-`). A malformed `doc` fails here, loudly, rather than
 silently at Tab time.
 
@@ -67,6 +67,7 @@ have the program print it, then load it with the shell's standard mechanism:
 | zsh | `"zsh"` | `source` it from `~/.zshrc`, or save it as `_naval` on your `$fpath`. |
 | fish | `"fish"` | Save it as `~/.config/fish/completions/naval.fish`. |
 | PowerShell | `"powershell"` | Dot-source it from your `$PROFILE`. |
+| nushell | `"nushell"` | Save it under a name that is **not** `naval.nu` (a module cannot export a command of its own name), then `use naval-completions.nu *` from your config, or drop it in a `$nu.vendor-autoload-dirs` directory. Needs nushell 0.108+. |
 
 !!! note
     Each Tab is a full launch of your program, so its startup cost (imports and so on) is the completion

docopt2-1.2.0/fuzz/docopt.dict

@@ -0,0 +1,31 @@
+# libFuzzer dictionary of docopt usage-grammar tokens. Without it the fuzzer almost never synthesises the
+# word "usage:" from random bytes, so it bounces off the section detector; with it, libFuzzer splices these
+# in during mutation and reaches the pattern matcher, coercion and the Options parser. "\x00" is the harness
+# separator between the usage message and the argv tokens (see fuzz_docopt.py).
+"usage:"
+"Usage:"
+"options:"
+"Options:"
+"arguments:"
+"Arguments:"
+"[options]"
+"[default: 1]"
+"[env: VAR]"
+"[config: k.v]"
+"--help"
+"--version"
+"-h"
+"--"
+"..."
+" | "
+"["
+"]"
+"("
+")"
+"<arg>"
+"ARG"
+"=<val>"
+"prog "
+"\x0a"
+"\x0a  "
+"\x00"

docopt2-1.2.0/fuzz/fuzz_docopt.py

@@ -0,0 +1,81 @@
+# Coverage-guided fuzzing of the public API with atheris (Linux/macOS only; there is no Windows wheel).
+# The invariant is the one tests/test_robustness.py states and Hypothesis checks on grammar-shaped input:
+# no entry point may raise anything but its own DocoptExit / DocoptLanguageError for ANY input. Hypothesis
+# only ever builds well-formed usage; atheris reaches the malformed shapes it cannot - unbalanced brackets,
+# NUL bytes, an option line run into its description - from arbitrary bytes under coverage feedback, and the
+# libFuzzer -timeout turns a runaway (a pathological slowdown or an outright hang) into a reported finding.
+#
+# atheris has no Windows wheel; run on Linux/macOS. The Fuzz workflow is the canonical invocation (corpus
+# seeds + dict + flags); replay a saved reproducer with:  python fuzz/fuzz_docopt.py <reproducer-file>
+from __future__ import annotations
+
+import contextlib
+import sys
+
+import atheris
+
+with atheris.instrument_imports():
+    from docopt2 import (
+        DocoptExit,
+        DocoptLanguageError,
+        check,
+        complete,
+        docopt,
+        format_usage,
+        generate_completion,
+        generate_config_template,
+        generate_examples,
+        generate_stub,
+        parse_tree,
+    )
+
+# DocoptExit (a SystemExit subclass, and the --help path) and DocoptLanguageError are the only errors the
+# public API may raise. Anything else escaping is the finding. Mirrors _OWN_ERRORS in test_robustness.py so
+# the fuzzer and the property suite can never disagree on what "correct" means.
+_OWN_ERRORS = (DocoptExit, DocoptLanguageError, SystemExit)
+
+# Every public entry point, driven with help and completion off so a fuzzed `--help` cannot exit the
+# process mid-run. One input exercises all of them. check_compat is deliberately absent: it runs docopt()
+# once per generated sample against argvs IT builds from the (fuzzer-maximised) grammar, so it manufactures
+# a slow-but-bounded run that is a property of the sample count, not a defect - its own logic is
+# deterministic and unit-tested. The runtime surface it shares (docopt, generate_examples) is fuzzed here.
+_ENTRY_POINTS = (
+    lambda doc, argv: docopt(doc, argv, help=False, complete=False),
+    lambda doc, argv: check(doc),
+    lambda doc, argv: format_usage(doc),
+    lambda doc, argv: generate_stub(doc),
+    lambda doc, argv: generate_examples(doc, count=2, seed=0),
+    lambda doc, argv: generate_config_template(doc),
+    lambda doc, argv: generate_completion(doc, "prog"),
+    lambda doc, argv: complete(doc, argv),
+    lambda doc, argv: parse_tree(doc),
+)
+
+
+def test_one_input(data: bytes) -> None:
+    """Split the bytes on NUL into a usage message and argv tokens, then drive every entry point.
+
+    A plain split (rather than atheris.FuzzedDataProvider) keeps the encoding transparent: a seed file that
+    is a real usage message decodes back to itself, so the corpus in fuzz/corpus and the docopt.dict tokens
+    actually steer the fuzzer into the parser instead of leaving it to guess the word ``usage:`` from noise.
+    """
+    usage_bytes, *argv_bytes = data.split(b"\x00")
+    doc = usage_bytes.decode("utf-8", "replace")
+    # Cap the token count: the matcher is linear per step but each step scans the argv, so an ambiguous
+    # pattern against a many-hundred-token argv is bounded-but-slow. A real invocation is short (a long
+    # `<files>...` glob is the OneOrMore path, which stays linear), so 32 tokens covers the shapes worth
+    # fuzzing without letting the harness manufacture a slow run out of an unrealistic argv.
+    argv = [token.decode("utf-8", "replace") for token in argv_bytes[:32]]
+    for entry in _ENTRY_POINTS:
+        with contextlib.suppress(*_OWN_ERRORS):
+            entry(doc, argv)
+
+
+def main() -> None:
+    """libFuzzer entry: flags (-max_total_time, -timeout, -artifact_prefix, ...) come in on sys.argv."""
+    atheris.Setup(sys.argv, test_one_input)
+    atheris.Fuzz()
+
+
+if __name__ == "__main__":
+    main()

{docopt2-1.1.2 → docopt2-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docopt2"
-version = "1.1.2"
+version = "1.2.0"
 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 :: 5 - Production/Stable",
+    "Development Status :: 4 - Beta",
     "Environment :: Console",
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
@@ -96,6 +96,11 @@ typecheck = [
 mutation = [
     "mutmut>=3.3.1",
 ]
+# Performance regression gate. Own group: pytest-codspeed is only needed by the CodSpeed CI job and a
+# manual `pytest benchmarks/ --codspeed`, not by the suite every contributor runs.
+benchmark = [
+    "pytest-codspeed>=5",
+]
 
 [tool.mutmut]
 source_paths = ["src/docopt2/"]

{docopt2-1.1.2 → docopt2-1.2.0}/src/docopt2/__main__.py

@@ -59,7 +59,9 @@ def _read_usage(source: str) -> str:
         return sys.stdin.read()
     path = Path(source)
     try:
-        text = path.read_text(encoding="utf-8")
+        # utf-8-sig, not utf-8: a leading BOM (Windows editors add one) is stripped, exactly as Python
+        # does for a source file it runs - otherwise `ast.parse` chokes on the U+FEFF a .py starts with.
+        text = path.read_text(encoding="utf-8-sig")
     except UnicodeDecodeError as error:
         raise _CliError(f"{source}: not a UTF-8 text file") from error
     if path.suffix != ".py":

{docopt2-1.1.2 → docopt2-1.2.0}/src/docopt2/_compat.py

@@ -34,35 +34,58 @@ def check_compat(old_doc: str, new_doc: str, *, samples: int = 300) -> list[str]
     """Report backward-incompatible changes from ``old_doc`` to ``new_doc``, most reliable part first.
 
     Every entry is a *definite* break - an invocation the old usage accepts that the new one rejects: a
-    removed option or command (named, structural), or a concrete argument vector the new grammar no longer
-    accepts (found by sampling the old grammar's accepted set and replaying it against the new).
+    removed option, a removed command, or a concrete argument vector the new grammar no longer accepts
+    (found by sampling the old grammar's accepted set and replaying it against the new).
 
     An empty list means **no break was found**, not a proof of compatibility: the accepted set is infinite
     and only ``samples`` invocations are checked, so read it like a passing test ("no breakage detected"),
     never as a guarantee. It never claims "compatible" - it only surfaces breaks it can prove.
     """
+    old_examples = generate_examples(old_doc, count=samples, seed=0)
     removed_options = _spellings(old_doc) - _spellings(new_doc)
-    removed_commands = _usable(old_doc, Command) - _usable(new_doc, Command)
+    # A command literal absent from new is only a break if it actually rejects something. `(add|rm) <p>`
+    # generalized to `<cmd> <p>` drops the `add`/`rm` literals, yet new accepts every old invocation (they
+    # match `<cmd>`). Report a command only when a sampled old invocation that used it is rejected by new.
+    gone = _usable(old_doc, Command) - _usable(new_doc, Command)
+    removed_commands = {name for name in gone if _command_removal_breaks(new_doc, name, old_examples)}
     breaks = [f"option `{name}` removed" for name in sorted(removed_options)]
     breaks += [f"command `{name}` removed" for name in sorted(removed_commands)]
     removed = removed_options | removed_commands
     seen_shapes: set[tuple[str, ...]] = set()
     examples: list[str] = []
-    for argv in generate_examples(old_doc, count=samples, seed=0):
+    for argv in old_examples:
         shape = tuple(re.sub(r"v\d+", "<val>", token) for token in argv)  # collapse placeholder values
         if shape in seen_shapes or _explained(argv, removed):  # one example per shape; skip structural repeats
             seen_shapes.add(shape)
             continue
         seen_shapes.add(shape)
-        try:
-            docopt(new_doc, argv, help=False, complete=False)
-        except (DocoptExit, DocoptLanguageError):
+        if _rejects(new_doc, argv):
             examples.append(f"`{' '.join(argv)}` no longer accepted")
             if len(examples) >= _MAX_EXAMPLES:
                 break
     return breaks + examples
 
 
+def _rejects(doc: str, argv: list[str]) -> bool:
+    """Whether ``doc`` refuses ``argv`` (the shape a break takes: old accepted it, new does not)."""
+    try:
+        docopt(doc, argv, help=False, complete=False)
+    except (DocoptExit, DocoptLanguageError):
+        return True
+    return False
+
+
+def _command_removal_breaks(new_doc: str, name: str, old_examples: list[list[str]]) -> bool:
+    """Whether dropping the command literal ``name`` rejects some invocation the old grammar accepted.
+
+    False when new absorbed the command into a positional (it still accepts those invocations); True when
+    the command is genuinely gone. ``generate_examples`` emits positional values as ``v1``, ``v2``... and
+    a command only by its name, so a command literal appears in a sampled argv iff it matched as that
+    command - a plain ``name in argv`` is enough. Bounded by the sampled examples, like the rest.
+    """
+    return any(name in argv and _rejects(new_doc, argv) for argv in old_examples)
+
+
 def _explained(argv: list[str], removed: set[str]) -> bool:
     """Whether the argv uses a removed option or command - so a named structural break already covers it."""
     return any(token.split("=", 1)[0] in removed or token in removed for token in argv)