docopt2 1.0.0__py3-none-any.whl

docopt2/__init__.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _package_version
+
+from docopt2._compat import check_compat
+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._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._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,
+)
+from docopt2._stub import generate_stub
+
+# 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",
+]
+
+try:
+    __version__ = _package_version("docopt2")
+except PackageNotFoundError:  # pragma: no cover - only when imported from a source tree with no installed dist
+    __version__ = "0.0.0"

docopt2/__main__.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+from typing import Any
+
+from docopt2 import (
+    Dispatch,
+    __version__,
+    check,
+    check_compat,
+    format_usage,
+    generate_config_template,
+    generate_examples,
+    generate_stub,
+)
+from docopt2._diagnostics import use_color
+from docopt2._errors import DocoptLanguageError
+
+_STYLES = ("dataclass", "typeddict", "cli")
+
+# The tool's own interface is a docopt usage message parsed by docopt2 itself (via Dispatch): the
+# command line is described here, not built imperatively - the library dogfooding its own model.
+_DOC = """\
+docopt2 - typed tooling for docopt usage messages.
+
+Usage:
+  docopt2 stub <source> [--name=<name>] [--style=<style>]
+  docopt2 check <source>
+  docopt2 examples <source> [--count=<n>] [--invalid] [--seed=<n>]
+  docopt2 config-template <source>
+  docopt2 compat <old-source> <new-source>
+  docopt2 fmt <source>
+  docopt2 (-h | --help)
+  docopt2 --version
+
+<source> is a Python file (its module docstring is read, without importing it), a text
+file of raw usage, or - for standard input.
+
+Options:
+  --name=<name>    Class name for the generated schema [default: Args].
+  --style=<style>  Schema style: dataclass, typeddict, or cli [default: dataclass].
+  --count=<n>      How many example invocations to generate [default: 10].
+  --invalid        Generate argument vectors the usage rejects, not ones it accepts.
+  --seed=<n>       Seed the generator for reproducible output.
+  -h --help        Show this help and exit.
+  --version        Show the docopt2 version and exit.
+"""
+
+
+class _CliError(Exception):
+    """A user-facing CLI error (bad --style, no readable usage); reported as ``error: ...``, exit 1."""
+
+
+def _read_usage(source: str) -> str:
+    """Load the usage message from ``source``: stdin (``-``), a ``.py`` module docstring, or a text file."""
+    if source == "-":
+        return sys.stdin.read()
+    path = Path(source)
+    try:
+        text = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as error:
+        raise _CliError(f"{source}: not a UTF-8 text file") from error
+    if path.suffix != ".py":
+        return text
+    docstring = ast.get_docstring(ast.parse(text))
+    if docstring is None:
+        raise _CliError(f"{source}: no module docstring to read a usage message from")
+    return docstring
+
+
+def _run_stub(arguments: Any) -> int:
+    style = arguments["--style"]
+    if style not in _STYLES:
+        raise _CliError(f"--style must be dataclass, typeddict, or cli, not {style!r}")
+    print(generate_stub(_read_usage(arguments["<source>"]), name=arguments["--name"], style=style), end="")
+    return 0
+
+
+def _run_check(arguments: Any) -> int:
+    warnings = check(_read_usage(arguments["<source>"]))
+    for warning in warnings:
+        print(warning.render(color=use_color(sys.stderr)), file=sys.stderr)
+    return 1 if warnings else 0
+
+
+def _as_int(value: str, flag: str) -> int:
+    try:
+        return int(value)
+    except ValueError:
+        raise _CliError(f"{flag} must be an integer, not {value!r}") from None
+
+
+def _run_examples(arguments: Any) -> int:
+    seed = None if arguments["--seed"] is None else _as_int(arguments["--seed"], "--seed")
+    examples = generate_examples(
+        _read_usage(arguments["<source>"]),
+        count=_as_int(arguments["--count"], "--count"),
+        valid=not arguments["--invalid"],
+        seed=seed,
+    )
+    for argv in examples:
+        print(" ".join(argv))
+    return 0
+
+
+def _run_config_template(arguments: Any) -> int:
+    print(generate_config_template(_read_usage(arguments["<source>"])), end="")
+    return 0
+
+
+def _run_compat(arguments: Any) -> int:
+    breaks = check_compat(_read_usage(arguments["<old-source>"]), _read_usage(arguments["<new-source>"]))
+    for entry in breaks:
+        print(entry, file=sys.stderr)
+    return 1 if breaks else 0  # like `check`: silent and 0 when no breakage is found, else the breaks and 1
+
+
+def _run_fmt(arguments: Any) -> int:
+    print(format_usage(_read_usage(arguments["<source>"])), end="")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``docopt2`` console command and ``python -m docopt2``."""
+    app = Dispatch(_DOC)
+    app.on("stub")(_run_stub)
+    app.on("check")(_run_check)
+    app.on("examples")(_run_examples)
+    app.on("config-template")(_run_config_template)
+    app.on("compat")(_run_compat)
+    app.on("fmt")(_run_fmt)
+    try:
+        result: int = app.run(argv, version=__version__, complete=False)
+    except (_CliError, DocoptLanguageError, OSError, SyntaxError, ValueError) as exc:
+        # ValueError also covers generate_stub rejecting a bad --name and a NUL byte in a source file.
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return result
+
+
+if __name__ == "__main__":  # pragma: no cover - module entry point
+    sys.exit(main())

docopt2/_compat.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import re
+
+from docopt2._core import docopt
+from docopt2._errors import DocoptExit, DocoptLanguageError
+from docopt2._generate import _usage_pattern, generate_examples
+from docopt2._parser import Command, Option, Pattern
+
+_MAX_EXAMPLES = 5  # distinct counterexample shapes to report; the report stays scannable, not a wall of argvs
+
+
+def _usable(doc: str, kind: type[Pattern]) -> set[str]:
+    """The names of the leaves of ``kind`` actually usable in ``doc`` (its ``[options]`` shortcut expanded)."""
+    return {leaf.name for leaf in _usage_pattern(doc).flat(kind) if leaf.name is not None}
+
+
+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).
+
+    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.
+    """
+    removed_options = _usable(old_doc, Option) - _usable(new_doc, Option)
+    removed_commands = _usable(old_doc, Command) - _usable(new_doc, Command)
+    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):
+        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):
+            examples.append(f"`{' '.join(argv)}` no longer accepted")
+            if len(examples) >= _MAX_EXAMPLES:
+                break
+    return breaks + 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)

docopt2/_completion.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+import itertools
+import os
+import re
+from typing import TYPE_CHECKING, cast
+
+from docopt2._errors import DocoptExit, DocoptLanguageError
+from docopt2._parser import (
+    MATCH_LIMIT,
+    Argument,
+    Command,
+    Either,
+    LeafPattern,
+    OneOrMore,
+    Option,
+    Optional,
+    OptionsShortcut,
+    Pattern,
+    Required,
+    Tokens,
+    _option_chunks,
+    expand_options_shortcut,
+    formal_usage,
+    parse_argv,
+    parse_defaults,
+    parse_pattern,
+    single_usage_section,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator, Sequence
+
+# Environment protocol shared with the generated shell scripts: when completion fires, the script
+# sets these variables and re-invokes the program, whose docopt() call answers with the candidates.
+_TRIGGER_ENV = "_DOCOPT2_COMPLETE"
+_WORDS_ENV = "_DOCOPT2_WORDS"
+
+
+# --- the resolver: which tokens may legally come next -------------------------------------------
+
+
+def _frontier(node: Pattern, left: list[Pattern], *, block: bool) -> Iterator[tuple[list[Pattern], set[Pattern], bool]]:
+    """Yield ``(remaining, frontier, blocks)`` per partial-consumption path; a token sequence is a
+    valid prefix iff some path leaves ``remaining == []``.
+
+    ``frontier`` is the leaves that could match the NEXT token. An option floats (offerable, and the
+    path proceeds past it, non-blocking); an unfilled positional/command sets ``blocks`` to ``block``,
+    so the command pass (``block=True``) stops at the next positional while the option pass
+    (``block=False``) floats past it to reach later options. A present positional that fails is dead.
+    """
+    if isinstance(node, LeafPattern):
+        position, matched = node.single_match(left)
+        if matched is not None and position is not None:
+            yield left[:position] + left[position + 1 :], set(), False  # already typed; consume it
+        elif isinstance(node, Option):
+            yield left, {node}, False  # floats: offerable next, sequence proceeds (deferred)
+        elif not any(type(leaf) is Argument for leaf in left):
+            yield left, {node}, block  # unfilled positional/command (only options, if any, remain)
+        return
+    if isinstance(node, Either):
+        for child in node.children:
+            yield from _frontier(child, left, block=block)
+        return
+    if isinstance(node, OneOrMore):
+        for remaining, frontier, blocks in _frontier(node.children[0], left, block=block):
+            yield remaining, frontier, blocks
+            if not frontier and len(remaining) < len(left):  # consumed one and progressed: may repeat
+                yield from _frontier(node, remaining, block=block)
+        return
+    if isinstance(node, (Optional, OptionsShortcut)):
+        yield from _frontier_seq(node.children, left, optional=True, block=block)
+        return
+    yield from _frontier_seq(cast("Required", node).children, left, optional=False, block=block)
+
+
+def _frontier_seq(
+    children: list[Pattern], left: list[Pattern], *, optional: bool, block: bool
+) -> Iterator[tuple[list[Pattern], set[Pattern], bool]]:
+    if not children:
+        yield left, set(), False
+        return
+    head, rest = children[0], children[1:]
+    for remaining, frontier, blocks in _frontier(head, left, block=block):
+        if blocks:  # an unfilled required positional; stop, do not advance past it
+            yield remaining, frontier, True
+        else:  # head consumed input or floated past; advance, carrying its frontier along
+            for tail_remaining, tail_frontier, tail_blocks in _frontier_seq(
+                rest, remaining, optional=optional, block=block
+            ):
+                yield tail_remaining, frontier | tail_frontier, tail_blocks
+    if optional:  # an optional child may be skipped entirely
+        yield from _frontier_seq(rest, left, optional=optional, block=block)
+
+
+def _resolve(doc: str, typed: list[str]) -> list[str]:
+    """Names (commands and options) that may legally follow the already-typed ``typed`` tokens."""
+    options = parse_defaults(doc)
+    pattern = parse_pattern(formal_usage(single_usage_section(doc)), options)
+    expand_options_shortcut(pattern, options)
+    base = parse_argv(Tokens(list(typed)), list(options))
+    after_separator = "--" in typed and not any(leaf.name == "--" for leaf in pattern.flat(Command))
+    # Command pass: the typed positionals only (options and `--` stripped), positionals blocking so
+    # only the next command in order is offered. Bounded, so an exponential-skip pattern cannot hang.
+    positionals: list[Pattern] = [leaf for leaf in base if type(leaf) is Argument and leaf.value != "--"]
+    command_paths = itertools.islice(_frontier(pattern, positionals, block=True), MATCH_LIMIT)
+    command_frontiers = [frontier for remaining, frontier, _b in command_paths if remaining == []]
+    if not command_frontiers:
+        return []  # the typed positionals cannot be consumed - not a valid prefix, nothing to complete
+    names: set[str] = {
+        cast("str", leaf.name) for frontier in command_frontiers for leaf in frontier if type(leaf) is Command
+    }
+    if after_separator:
+        return sorted(names)  # options are not parsed after a POSIX `--` separator
+    # Option pass: over the full prefix, positionals do NOT block, so the walk floats past unfilled
+    # positionals to every reachable unconsumed option (repeats return via `...`); dead branches prune.
+    for remaining, frontier, _b in itertools.islice(_frontier(pattern, base, block=False), MATCH_LIMIT):
+        if remaining == []:
+            names.update(str(leaf.long or leaf.short) for leaf in frontier if isinstance(leaf, Option))
+    return sorted(names)
+
+
+def complete(doc: str, words: Sequence[str]) -> list[str]:
+    """Return the completion candidates for the last (cursor) word of ``words``.
+
+    Earlier tokens are consumed against the usage pattern; the command literals and option names
+    (never positional values) that could legally come next are returned, filtered to the partial
+    word. A malformed doc or a prefix ending mid-option-argument yields no candidates, never raises.
+    """
+    tokens = list(words)
+    incomplete = tokens[-1] if tokens else ""
+    typed = tokens[:-1]
+    try:
+        candidates = _resolve(doc, typed)
+    except (DocoptLanguageError, DocoptExit, RecursionError):
+        # a malformed doc, a prefix ending mid-option-argument, or a pathologically deep pattern:
+        # complete nothing rather than raising into the shell
+        return []
+    return [name for name in candidates if name.startswith(incomplete)]
+
+
+def _describe(doc: str) -> dict[str, str]:
+    """Map each option name (long and short) to its help text from the ``Options:`` block(s).
+
+    This is the same right-hand column ``Option.parse`` reads for ``[default: ...]``, kept here for
+    completion tooltips instead of discarded. Options with no description, and commands (which have no
+    description column), simply get no entry, so their completion candidate shows without a tooltip.
+    """
+    descriptions: dict[str, str] = {}
+    for chunk in _option_chunks(doc):
+        option = Option.parse(chunk)
+        _, _, text = chunk.strip().partition("  ")
+        # Collapse wrapped continuation lines and stray tabs to single spaces: a newline or tab in
+        # the text would split the `name\tdescription` reply line the shells rely on, injecting a
+        # bogus candidate. join(split()) also trims the ends before the trailing period is dropped.
+        text = " ".join(text.split()).rstrip(".").strip()
+        for name in (option.long, option.short):
+            if name is not None:
+                descriptions[name] = text
+    return descriptions
+
+
+def reply_to_completion_request(doc: str) -> str | None:
+    """If a completion request is in the environment, return its reply, else None.
+
+    Each reply line is ``name\\tdescription`` (the description may be empty). The request var holds the
+    completed tokens before the cursor; only a :func:`generate_completion` script sets it, so a normal
+    run returns None. Shells that show descriptions (zsh, fish, PowerShell) render the second column;
+    bash keeps the name only.
+    """
+    if os.environ.get(_TRIGGER_ENV) is None:
+        return None
+    raw = os.environ.get(_WORDS_ENV, "")
+    words = raw.split("\n") if raw else []
+    try:
+        descriptions = _describe(doc)
+    except DocoptLanguageError:
+        descriptions = {}  # a malformed Options section must not raise into the shell on Tab
+    return "\n".join(f"{name}\t{descriptions.get(name, '')}" for name in complete(doc, [*words, ""]))
+
+
+# --- shell scripts: thin callbacks that ask the program at completion time ----------------------
+
+
+def _function_name(prog: str) -> str:
+    """A shell-function-safe identifier derived from the program name."""
+    return "_" + re.sub(r"\W", "_", prog) + "_completion"
+
+
+def _render_bash(prog: str, function: str) -> str:
+    # bash completion shows names only, so strip the tab-joined description column with `cut -f1`.
+    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"
+    )
+
+
+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.
+    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"
+        '    lines=("${(@f)$(__TRIGGER__=1 __WORDS__=$joined ${words[1]})}")\n'
+        "    local line\n"
+        "    for line in $lines; do\n"
+        "        described+=(\"${line%%$'\\t'*}:${line#*$'\\t'}\")\n"
+        "    done\n"
+        "    _describe -t candidates candidate described\n"
+        "}\n"
+        "compdef __FUNC__ __PROG__\n"
+    )
+    return (
+        template.replace("__PROG__", prog)
+        .replace("__FUNC__", function)
+        .replace("__TRIGGER__", _TRIGGER_ENV)
+        .replace("__WORDS__", _WORDS_ENV)
+    )
+
+
+def _render_fish(prog: str, function: str) -> str:
+    return (
+        f"function {function}\n"
+        # `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"
+        f"end\n"
+        f"complete -c {prog} -f -a '({function})'\n"
+    )
+
+
+def _render_powershell(prog: str, _function: str) -> str:
+    # PowerShell script blocks are brace-heavy, so build from a template with plain placeholders
+    # rather than an f-string that would need every `{`/`}` doubled.
+    template = (
+        "Register-ArgumentCompleter -Native -CommandName __PROG__ -ScriptBlock {\n"
+        "    param($wordToComplete, $commandAst, $cursorPosition)\n"
+        "    $words = @($commandAst.CommandElements | Select-Object -Skip 1 | ForEach-Object { $_.ToString() })\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"
+        '            $parts = $_ -split "`t", 2\n'  # reply line is name`tdescription
+        "            $name = $parts[0]\n"
+        '            if ($name -like "$wordToComplete*") {\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"
+        "        }\n"
+        "    } finally {\n"
+        "        Remove-Item Env:__TRIGGER__ -ErrorAction SilentlyContinue\n"
+        "        Remove-Item Env:__WORDS__ -ErrorAction SilentlyContinue\n"
+        "    }\n"
+        "}\n"
+    )
+    return template.replace("__PROG__", prog).replace("__TRIGGER__", _TRIGGER_ENV).replace("__WORDS__", _WORDS_ENV)
+
+
+_RENDERERS: dict[str, Callable[[str, str], str]] = {
+    "bash": _render_bash,
+    "zsh": _render_zsh,
+    "fish": _render_fish,
+    "powershell": _render_powershell,
+}
+
+
+def generate_completion(doc: str, prog: str, shell: str = "bash") -> str:
+    """Return a context-aware shell completion script for the CLI described by ``doc``.
+
+    ``shell`` is one of ``"bash"``, ``"zsh"``, ``"fish"`` or ``"powershell"`` - the same four Click
+    and Typer emit. The script is a thin callback: at each Tab it re-invokes the program with a
+    completion request in the environment, and the program's :func:`docopt` call resolves the
+    tokens legal at the cursor from the usage grammar (so suggestions narrow to the matched
+    subcommand's options and arguments, not a flat global list).
+
+    A docopt program answers the script's requests by default; a program that does not want this
+    passes ``docopt(..., complete=False)`` to opt out.
+    """
+    if shell not in _RENDERERS:
+        supported = ", ".join(sorted(_RENDERERS))
+        raise ValueError(f"unsupported shell: {shell!r}; expected one of {supported}")
+    # The script interpolates `prog` into shell/PowerShell source that is sourced or eval'd, so a
+    # name with metacharacters (`;`, `$()`, spaces, quotes) would inject or corrupt it. Require a
+    # plain command name.
+    if not re.fullmatch(r"[A-Za-z0-9._-]+", prog):
+        raise ValueError(f"prog {prog!r} must be a plain command name (letters, digits, . _ -)")
+    # Validate the docstring up front so a malformed usage fails loudly here, not silently at Tab.
+    single_usage_section(doc)
+    return _RENDERERS[shell](prog, _function_name(prog))