docopt2 1.2.0__tar.gz → 1.2.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docopt2
-Version: 1.2.0
+Version: 1.2.1
 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
@@ -53,7 +53,7 @@ Description-Content-Type: text/markdown
   <a href="https://pypi.org/project/docopt2/"><img src="https://img.shields.io/pypi/pyversions/docopt2" alt="Python"></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/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/concepts/design-boundaries/#zero-runtime-dependencies"><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>

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

@@ -17,7 +17,7 @@
   <a href="https://pypi.org/project/docopt2/"><img src="https://img.shields.io/pypi/pyversions/docopt2" alt="Python"></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/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/concepts/design-boundaries/#zero-runtime-dependencies"><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>

{docopt2-1.2.0 → docopt2-1.2.1}/docs/getting-started.md

@@ -6,8 +6,7 @@
 pip install docopt2
 ```
 
-docopt2 has zero runtime dependencies: `[project.dependencies]` is empty, and the core needs nothing
-outside the Python standard library.
+docopt2 has zero runtime dependencies: the core needs nothing outside the Python standard library.
 pydantic support is reflective and optional (`docopt2[pydantic]`).
 
 !!! tip "Coming from the original docopt?"

{docopt2-1.2.0 → docopt2-1.2.1}/docs/guides/examples.md

@@ -66,9 +66,9 @@ checks its happy paths.
 ```python
 generate_examples(doc, count=4, valid=False, seed=7)
 # [['mine', 'set', 'v1', 'v2', '--unknown'],
-#  ['--help', '--unknown'],
 #  ['ship', 'new', 'v3', '--unknown'],
-#  ['ship', 'new', 'v4', 'v5', '--unknown']]
+#  ['ship', 'new', 'v4', 'v5', '--unknown'],
+#  ['ship', 'new', 'v6', '--unknown']]
 ```
 
 Every one of these raises [`DocoptExit`](../reference/exceptions.md) when passed to `docopt`.

{docopt2-1.2.0 → docopt2-1.2.1}/docs/guides/round-trip.md

@@ -41,8 +41,8 @@ typed. The canonical form is fixed and predictable:
 
 A result that no usage pattern can reproduce raises `ValueError` rather than return a wrong argv. That is a
 hand-built or inconsistent mapping, or a degenerate grammar in which one value is reachable through
-differently-shaped positions (`(<name> | <name> ...)`, `(-a | -b)...`, `[<name>] <path> <name>`) - a shape
-whose argv is genuinely ambiguous, so there is no single canonical form to return.
+differently-shaped positions (`(-a | -b)...`, `[<name>] <path> <name>`) - a shape whose argv is genuinely
+ambiguous, so there is no single canonical form to return.
 
 ## What it is for
 

{docopt2-1.2.0 → docopt2-1.2.1}/docs/index.md

@@ -11,10 +11,9 @@ it corrects three of the original's parsing bugs
 Diagnostics come with it. Everything else - typed results, linting, stubs, completion, dispatch - is opt-in.
 
 !!! note "Zero dependencies"
-    The core needs nothing outside the Python standard library: `[project.dependencies]` is empty. (It uses
-    `typing_extensions` for `Required`/`NotRequired` on Python 3.10 if you happen to have it installed, and
-    works without it.) pydantic support is optional and reflective (`pip install docopt2[pydantic]`), needed
-    only when you pass a pydantic model as a schema; the Hypothesis strategy needs `docopt2[hypothesis]`.
+    The core runs on the standard library alone - nothing to install, nothing to audit. pydantic and
+    Hypothesis are optional extras (`docopt2[pydantic]`, `docopt2[hypothesis]`), used only when you pass a
+    pydantic model as a schema or reach for the Hypothesis strategy.
 
 ## Why docopt2
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "docopt2"
-version = "1.2.0"
+version = "1.2.1"
 description = "Typed successor to docopt: the usage message is the parser spec."
 readme = "README.md"
 license = "MIT"

{docopt2-1.2.0 → docopt2-1.2.1}/src/docopt2/_parser.py

@@ -28,10 +28,13 @@ ErrorType: TypeAlias = type[DocoptExit] | type[DocoptLanguageError]
 # (the budget below), because this per-node cap alone still compounds to minutes on a malformed pattern.
 MATCH_LIMIT = 200_000
 
-# MATCH_LIMIT is per Either, so nested alternatives still multiply it (200k per node -> minutes on a
-# malformed pattern). This budgets the WHOLE match instead: one shared ceiling across every Either, so an
-# adversarial argv rejects in bounded time. A legitimate usage materializes at most a few dozen outcomes
-# (measured across the corpus and generated argvs), so the ceiling is never approached in real use.
+# The global budget bounds docopt()'s whole match with one shared ceiling: an adversarial or malformed
+# pattern, whose `_combine` DFS backtracks exponentially when no complete match exists, rejects in bounded
+# time. It stays a small FIXED number because `Either.matches` yields lazily (greedy-first, materializing its
+# sorted tail only if a caller backtracks past it): an honest match threads a single greedy path - a few
+# hundred descents even for a long `<files>...` argv - so it never approaches the ceiling. Only a search with
+# no complete match, forced to explore its full 2**n fan, reaches it. (An EAGER Either that materialized every
+# outcome to sort them made an honest match's descents grow with argv and false-rejected a real 200-file CLI.)
 _match_budget: contextvars.ContextVar[list[int] | None] = contextvars.ContextVar("docopt2_match_budget", default=None)
 
 
@@ -66,9 +69,10 @@ def _spend_budget() -> None:
 
     Charged per ``_combine`` descent - the exponential engine - so a DFS that dead-ends WITHOUT yielding
     (many optionals before an unmatchable required tail explores 2**n branches, none of them an outcome) is
-    bounded too. Counting descents, not per-descent work, is what keeps a genuine match cheap: matching a
-    long ``<files>...`` glob is a handful of descents (the repetition is iterative), so it never approaches
-    the ceiling, while an adversarial pattern's exponential fan-out does. A no-op when no budget is set.
+    bounded too. A genuine match is cheap because ``Either`` yields greedy-first without materializing its
+    fan (see :meth:`Either.matches`), so an honest match threads one greedy path - a few hundred descents even
+    over a long ``<files>...`` glob - while an adversarial pattern's 2**n fan-out reaches the cap. A no-op when
+    no budget is set.
     """
     budget = _match_budget.get()
     if budget is not None:
@@ -484,10 +488,28 @@ class Either(BranchPattern):
     """Exactly one branch must match; the one leaving the fewest leaves wins."""
 
     def matches(self, left: list[Pattern], collected: list[Pattern]) -> Iterator[MatchOutcome]:
-        lazy = (outcome for child in self.children for outcome in child.matches(left, collected))
-        outcomes = list(_bounded(lazy))
-        # the fewest-leaves-left branch wins first, matching the greedy matcher's choice
-        yield from sorted(outcomes, key=lambda outcome: len(outcome[0]))
+        # Greedy-first, lazily. Each branch yields its own fewest-left outcome first, so the global
+        # fewest-left - the greedy result the matcher wants - is the min over the branches' first outcomes.
+        # Yield it WITHOUT materializing the rest: a caller that takes only the greedy outcome (the common
+        # case, and every complete match) stops here, so an honest match never builds the whole fan. The
+        # eager `sorted(list(all))` this replaces made that fan grow with argv and false-rejected long CLIs.
+        streams = [child.matches(left, collected) for child in self.children]
+        firsts = [next(stream, None) for stream in streams]
+        live = [index for index, outcome in enumerate(firsts) if outcome is not None]
+        if not live:
+            return
+        best_index = min(live, key=lambda index: len(cast("MatchOutcome", firsts[index])[0]))
+        yield cast("MatchOutcome", firsts[best_index])
+
+        def _rest() -> Iterator[MatchOutcome]:
+            # Every outcome except the one already yielded, in the branch order the eager version listed
+            # them, so `[best] + sorted(_rest())` reproduces `sorted(all)` exactly - tie order included.
+            for index, (first, stream) in enumerate(zip(firsts, streams, strict=True)):
+                if first is not None and index != best_index:
+                    yield first
+                yield from stream
+
+        yield from sorted(_bounded(_rest()), key=lambda outcome: len(outcome[0]))
 
 
 def _accumulate_occurrences(node: Pattern, counts: dict[Pattern, int], multiplier: int) -> None:

{docopt2-1.2.0 → docopt2-1.2.1}/tests/test_property_differential.py

@@ -163,6 +163,32 @@ def test_an_ambiguous_alternation_branch_choice_stays_compatible(doc, argv):
     _assert_compatible(doc, argv)
 
 
+# A DEEP but honest argv - the kind a CI invocation produces, not an adversary: two options repeated many
+# times plus a long variadic file list. An EAGER `Either` that materialized its whole outcome fan to sort it
+# made an honest match's cost grow with argv, so a real 20-flag, 200-file run reached the match budget and
+# was falsely rejected (1.1.3-1.2.0). `Either` now yields greedy-first lazily, threading one greedy path, so
+# vanilla-accepted argvs stay accepted. Sizes exceed the old fixed budget - the regression's own trigger.
+_DEEP_DOC = """Usage:
+  prog run [--verbose] [--jobs=<n>] [--tag=<t>]... [--exclude=<e>]... <suite> <files>...
+  prog report (html | json) [--out=<p>]
+"""
+
+
+def _deep_argv(tags: int, excludes: int, files: int) -> list[str]:
+    return [
+        "run",
+        *[f"--tag=t{index}" for index in range(tags)],
+        *[f"--exclude=e{index}" for index in range(excludes)],
+        "smoke",
+        *[f"f{index}" for index in range(files)],
+    ]
+
+
+@pytest.mark.parametrize(("tags", "excludes", "files"), [(20, 20, 150), (30, 10, 200), (12, 12, 300)])
+def test_a_deep_honest_argv_is_not_falsely_rejected(tags, excludes, files):
+    _assert_compatible(_DEEP_DOC, _deep_argv(tags, excludes, files))
+
+
 # A PRISTINE oracle: the module above is deliberately patched with docopt2's two fixes, so it can no
 # longer see them. These tests need the original as shipped.
 _pristine_spec = importlib.util.spec_from_file_location("docopt_pristine", _oracle_path)

{docopt2-1.2.0 → docopt2-1.2.1}/tests/test_robustness.py

@@ -173,3 +173,17 @@ def test_an_ambiguous_pattern_does_not_hang_on_a_long_argv():
     with pytest.raises(DocoptExit):
         docopt2.docopt(doc, argv, help=False)
     assert_that(time.perf_counter() - start).described_as("matching a 2**24-ambiguous argv").is_less_than(3.0)
+
+
+def test_an_exponential_pattern_with_a_long_argv_still_rejects_in_bounded_time():
+    # The subtler cousin: many optional flags before a MISSING required option, then a long file tail. The
+    # optionals' 2**n dead-ends fail at the missing option before they reach the files, so the fan is
+    # independent of the argv - but the long argv would inflate an argv-scaled budget past that fan and let it
+    # run for tens of seconds. The whole match stays on ONE fixed ceiling, so it rejects fast regardless.
+    flags = " ".join(f"[-{chr(97 + index)}]" for index in range(24))
+    doc = f"usage: prog {flags} --need <files>..."
+    argv = [f"-{chr(97 + index)}" for index in range(24)] + [f"f{index}" for index in range(300)]
+    start = time.perf_counter()
+    with pytest.raises(DocoptExit):
+        docopt2.docopt(doc, argv, help=False)
+    assert_that(time.perf_counter() - start).described_as("an exponential pattern with a long argv").is_less_than(3.0)

{docopt2-1.2.0 → docopt2-1.2.1}/uv.lock

@@ -314,7 +314,7 @@ toml = [
 
 [[package]]
 name = "docopt2"
-version = "1.2.0"
+version = "1.2.1"
 source = { editable = "." }
 
 [package.optional-dependencies]