usage-spec-argparse 1.0.0__py3-none-any.whl

argparse_usage/__init__.py

@@ -0,0 +1,39 @@
+"""Usage spec integration for argparse."""
+
+from __future__ import annotations
+
+import argparse
+
+from usage_spec import Spec, SpecArg, SpecFlag, SpecCommand, SpecChoices, render_kdl, validate_kdl, render_json, generate as core_generate
+
+from .convert import convert_root
+
+__all__ = [
+    "convert_root",
+    "generate",
+    "generate_kdl",
+    "generate_json",
+    "render_kdl",
+    "Spec",
+    "SpecArg",
+    "SpecFlag",
+    "SpecCommand",
+    "SpecChoices",
+]
+
+
+def generate(parser: argparse.ArgumentParser, bin_name: str | None = None) -> str:
+    """Generate usage spec in KDL format from an argparse.ArgumentParser."""
+    spec = convert_root(parser, bin_name)
+    return core_generate(spec, format="kdl", comment="@generated by usage-spec-argparse from argparse metadata")
+
+
+def generate_kdl(parser: argparse.ArgumentParser, bin_name: str | None = None) -> str:
+    """Generate usage spec in KDL format (alias for generate)."""
+    return generate(parser, bin_name)
+
+
+def generate_json(parser: argparse.ArgumentParser, bin_name: str | None = None) -> str:
+    """Generate usage spec in JSON format from an argparse.ArgumentParser."""
+    spec = convert_root(parser, bin_name)
+    return core_generate(spec, format="json")

argparse_usage/convert.py

@@ -0,0 +1,226 @@
+"""Convert argparse.ArgumentParser to usage spec."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from usage_spec import Spec, SpecArg, SpecFlag, SpecCommand, SpecChoices
+
+# Action class names that represent boolean flags
+_BOOL_ACTION_NAMES = frozenset({
+    "_StoreTrueAction",
+    "_StoreFalseAction",
+})
+
+# Action class names that represent count flags
+_COUNT_ACTION_NAMES = frozenset({
+    "_CountAction",
+})
+
+# Action class names for subparsers
+_SUBPARSERS_ACTION_NAMES = frozenset({
+    "_SubParsersAction",
+    "SubParsersAction",
+})
+
+# Built-in flag names to skip
+_BUILTIN_FLAG_NAMES = frozenset({"help", "version"})
+
+
+def _is_bool_action(action: argparse.Action) -> bool:
+    return type(action).__name__ in _BOOL_ACTION_NAMES
+
+
+def _is_count_action(action: argparse.Action) -> bool:
+    return type(action).__name__ in _COUNT_ACTION_NAMES
+
+
+def _is_subparsers_action(action: argparse.Action) -> bool:
+    return type(action).__name__ in _SUBPARSERS_ACTION_NAMES
+
+
+def _is_optional(action: argparse.Action) -> bool:
+    return bool(action.option_strings)
+
+
+def _extract_short_long(option_strings: list[str]) -> tuple[str, str]:
+    short = ""
+    long = ""
+    for opt in option_strings:
+        if opt.startswith("--"):
+            long = opt[2:]
+        elif opt.startswith("-"):
+            short = opt[1:]
+    return short, long
+
+
+def _convert_arg(action: argparse.Action) -> SpecArg:
+    nargs = action.nargs
+    # Use argparse's own 'required' attribute for positional args
+    required = getattr(action, "required", True)
+    # Variadic: nargs is '*' or '+' or argparse.REMAINDER
+    variadic = nargs in ("*", "+", argparse.REMAINDER) if nargs else False
+
+    result = SpecArg(
+        name=action.dest or action.metavar or "",
+        help=action.help if action.help != argparse.SUPPRESS else "",
+        required=required,
+        var=variadic,
+        hide=action.help == argparse.SUPPRESS,
+        default=[str(action.default)] if action.default not in (None, argparse.SUPPRESS) else [],
+        choices=None,
+    )
+
+    if action.choices:
+        result.choices = SpecChoices(values=[str(c) for c in action.choices])
+
+    return result
+
+
+def _convert_flag(action: argparse.Action) -> SpecFlag:
+    short, long = _extract_short_long(action.option_strings)
+    is_bool = _is_bool_action(action)
+    is_count = _is_count_action(action)
+    is_store_false = type(action).__name__ == "_StoreFalseAction"
+
+    flag = SpecFlag(
+        short=short,
+        long=long,
+        help=action.help if action.help != argparse.SUPPRESS else "",
+        help_long="",
+        required=bool(action.required) if hasattr(action, "required") else False,
+        hide=action.help == argparse.SUPPRESS,
+        global_=False,
+        count=is_count,
+        var=bool(action.nargs and action.nargs in ("*", "+")),
+        negate=f"--{long}" if is_store_false else "",
+        deprecated="",
+        default=[],
+        default_bool=None,
+        env="",
+        arg=None,
+    )
+
+    # Non-boolean, non-count options have an argument
+    if not is_bool and not is_count:
+        arg_name = (long or short).replace("-", "_").upper()
+        flag.arg = SpecArg(
+            name=arg_name,
+            help="",
+            required=flag.required,
+            var=flag.var,
+            hide=False,
+            default=[],
+            choices=None,
+        )
+
+        if action.choices:
+            flag.arg.choices = SpecChoices(values=[str(c) for c in action.choices])
+
+    # Default values
+    if action.default not in (None, argparse.SUPPRESS, True, False):
+        if is_bool or is_count:
+            pass  # skip for booleans
+        else:
+            flag.default = [str(action.default)]
+    elif action.default is True:
+        flag.default_bool = True
+    # False defaults are omitted for booleans
+
+    return flag
+
+
+def _get_subcommand_helps(parser: argparse.ArgumentParser) -> dict[str, str]:
+    """Extract help texts from subparsers' _choices_actions."""
+    helps: dict[str, str] = {}
+    for action in parser._actions:
+        if _is_subparsers_action(action) and hasattr(action, "_choices_actions"):
+            for ca in action._choices_actions:
+                if ca.dest and ca.help:
+                    helps[ca.dest] = ca.help
+    return helps
+
+
+def _convert_command(parser: argparse.ArgumentParser, help_override: str = "") -> SpecCommand:
+    name = parser.prog
+    # Strip parent prefix from name (e.g. "app sub" -> "sub")
+    if " " in name:
+        name = name.rsplit(" ", 1)[-1]
+
+    # Use help_override from _choices_actions if available, otherwise description
+    cmd_help = help_override or parser.description or ""
+
+    sc = SpecCommand(
+        name=name,
+        help=cmd_help,
+        help_long="",
+        hide=False,
+        deprecated="",
+        aliases=[],
+        subcommand_required=False,
+        flags=[],
+        args=[],
+        cmds=[],
+    )
+
+    sub_helps = _get_subcommand_helps(parser)
+
+    for action in parser._actions:
+        if _is_optional(action):
+            action_name = _extract_short_long(action.option_strings)[1] or _extract_short_long(action.option_strings)[0]
+            if action_name in _BUILTIN_FLAG_NAMES:
+                continue
+            sc.flags.append(_convert_flag(action))
+        elif _is_subparsers_action(action):
+            if hasattr(action, "choices") and action.choices:
+                for sub_name, sub_parser in action.choices.items():
+                    sc.cmds.append(_convert_command(sub_parser, sub_helps.get(sub_name, "")))
+        else:
+            sc.args.append(_convert_arg(action))
+
+    # subcommand_required: has subcommands but no positional args
+    if sc.cmds and not sc.args:
+        sc.subcommand_required = True
+
+    return sc
+
+
+def convert_root(parser: argparse.ArgumentParser, bin_name: str | None = None) -> Spec:
+    """Convert an argparse.ArgumentParser to a Spec object."""
+    name = bin_name or parser.prog
+
+    spec = Spec(
+        name=name,
+        bin=name,
+        version="",
+        about=parser.description or "",
+        long=parser.epilog or "",
+        usage=parser.usage or "",
+        flags=[],
+        args=[],
+        cmds=[],
+    )
+
+    sub_helps = _get_subcommand_helps(parser)
+
+    for action in parser._actions:
+        if _is_optional(action):
+            action_name = _extract_short_long(action.option_strings)[1] or _extract_short_long(action.option_strings)[0]
+            # Extract version string before skipping
+            if action_name == "version" and hasattr(action, "version"):
+                spec.version = action.version or ""
+                continue
+            # Skip built-in flags
+            if action_name in _BUILTIN_FLAG_NAMES:
+                continue
+            spec.flags.append(_convert_flag(action))
+        elif _is_subparsers_action(action):
+            if hasattr(action, "choices") and action.choices:
+                for sub_name, sub_parser in action.choices.items():
+                    spec.cmds.append(_convert_command(sub_parser, sub_helps.get(sub_name, "")))
+        else:
+            # Positional argument
+            spec.args.append(_convert_arg(action))
+
+    return spec

usage_spec_argparse-1.0.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: usage-spec-argparse
+Version: 1.0.0
+Summary: Generates usage spec for CLIs written with argparse
+License-Expression: MIT
+Keywords: argparse,cli,kdl,shell-completion,usage
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: usage-spec
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# usage-spec-argparse
+
+Generates [usage spec](https://usage.jdx.dev) for CLIs written with [argparse](https://docs.python.org/3/library/argparse.html).
+
+## Install
+
+```sh
+pip install usage-spec-argparse
+```
+
+## Usage
+
+```python
+import argparse
+from argparse_usage import generate
+
+parser = argparse.ArgumentParser(prog="mycli", description="My CLI tool")
+parser.add_argument("-v", "--verbose", action="store_true", help="Enable verbose output")
+parser.add_argument("-f", "--file", help="Input file")
+parser.add_argument("--no-color", action="store_false", help="Disable colored output")
+
+print(generate(parser))
+```
+
+## API
+
+### `generate(parser, bin_name=None)`
+
+Generates a usage spec in KDL format from an `argparse.ArgumentParser`.
+
+### `generate_kdl(parser, bin_name=None)`
+
+Alias for `generate()`.
+
+### `generate_json(parser, bin_name=None)`
+
+Generates a usage spec in JSON format.
+
+### `convert_root(parser, bin_name=None)`
+
+Converts an `argparse.ArgumentParser` to the `Spec` data structure.
+
+## Supported Features
+
+| argparse Feature | Usage Spec Mapping |
+|---|---|
+| `prog` | `name` / `bin` |
+| `--version` action | `version` |
+| `description` | `about` |
+| `epilog` | `long_about` |
+| `add_argument()` (optional) | `flag` |
+| `add_argument()` (positional) | `arg` |
+| `required=True` | `flag required=#true` |
+| `action="store_true"/"store_false"` | Boolean flag (no arg) |
+| `action="store_false"` | `negate` |
+| `action="count"` | `count=#true` |
+| `nargs="?"` | `required=#false` |
+| `nargs="*"/"+"` | `var=#true` |
+| `choices=[...]` | `choices` |
+| `default=...` | `default` |
+| `help=SUPPRESS` | `hide=#true` |
+| `add_subparsers()` | `cmd` (recursive) |
+| Non-runnable subcommand groups | `subcommand_required=#true` |
+
+## License
+
+MIT

usage_spec_argparse-1.0.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+argparse_usage/__init__.py,sha256=CRyyK06_Wl59WfyeSVBiTCCcRhtrAqOY3SXhBhbVZZE,1228
+argparse_usage/convert.py,sha256=qQZ1-V5uZ8dq1p7GGa4sG1evAknQU0QAtqOcyu_4tSg,7178
+usage_spec_argparse-1.0.0.dist-info/METADATA,sha256=5mnohy3BmfNQgOiUxP3_Ls_2BP2WNZD9YUr9mrW3pkU,2512
+usage_spec_argparse-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+usage_spec_argparse-1.0.0.dist-info/RECORD,,

usage_spec_argparse-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any