argparse-usage 0.1.0__py3-none-any.whl

argparse_usage/__init__.py

@@ -0,0 +1,6 @@
+"""Generate usage specs from Python argparse.ArgumentParser."""
+
+from argparse_usage.generator import generate_usage_spec as generate
+
+__all__ = ["generate"]
+__version__ = "0.1.0"

argparse_usage/generator.py

@@ -0,0 +1,251 @@
+"""Generate usage specs from argparse.ArgumentParser."""
+
+import argparse
+from collections.abc import Iterator
+from typing import Any
+
+from argparse_usage.kdl_utils import escape_string, format_arg, format_flag
+
+
+def _get_all_actions(parser: argparse.ArgumentParser) -> Iterator[argparse.Action]:
+    """Yield all actions from parser and its parent parsers."""
+    # Get parent parsers first
+    parents = getattr(parser, "_parents", None)
+    if parents:
+        for parent in parents:
+            yield from _get_all_actions(parent)
+
+    # Then get actions from this parser
+    for action in parser._actions:
+        yield action
+
+
+def _is_positional(action: argparse.Action) -> bool:
+    """Check if action is a positional argument."""
+    return len(action.option_strings) == 0
+
+
+def _is_flag(action: argparse.Action) -> bool:
+    """Check if action is a flag (optional argument)."""
+    return len(action.option_strings) > 0
+
+
+def _get_flag_names(action: argparse.Action) -> tuple[str | None, str | None]:
+    """Extract short and long flag names from an action."""
+    short = None
+    long = None
+
+    for opt in action.option_strings:
+        if opt.startswith("--"):
+            long = opt
+        elif opt.startswith("-"):
+            short = opt
+
+    return short, long
+
+
+def _get_var_info(nargs: Any) -> tuple[bool, int | None, int | None]:
+    """Extract variadic information from nargs."""
+    if nargs in ("*", "+"):
+        return True, 1 if nargs == "+" else 0, None
+    elif isinstance(nargs, int) and nargs > 1:
+        return True, nargs, nargs
+    elif nargs is None:
+        return False, None, None
+    else:
+        return False, None, None
+
+
+def _convert_action_to_spec(action: argparse.Action) -> str | None:
+    """Convert an argparse Action to usage spec KDL."""
+    # Skip help action
+    if isinstance(action, argparse._HelpAction):
+        return None
+
+    # Skip subparsers action (handled separately)
+    if isinstance(action, argparse._SubParsersAction):
+        return None
+
+    if _is_flag(action):
+        return _convert_flag_to_spec(action)
+    elif _is_positional(action):
+        return _convert_positional_to_spec(action)
+
+    return None
+
+
+def _convert_flag_to_spec(action: argparse.Action) -> str:
+    """Convert a flag action to usage spec KDL."""
+    short, long = _get_flag_names(action)
+    help_text = getattr(action, "help", None)
+    required = getattr(action, "required", False)
+    default = getattr(action, "default", None)
+    choices = getattr(action, "choices", None)
+
+    # Determine action type
+    is_count = isinstance(action, argparse._CountAction)
+    is_store_true = isinstance(action, argparse._StoreTrueAction)
+    is_store_false = isinstance(action, argparse._StoreFalseAction)
+
+    # Get variadic info
+    nargs = getattr(action, "nargs", None)
+    var, var_min, var_max = _get_var_info(nargs)
+
+    # For count actions, default is typically 0
+    if is_count and default is None:
+        default = 0
+
+    # For store_true/false, default is opposite of what would happen
+    if is_store_true and default is None:
+        default = False
+    if is_store_false and default is None:
+        default = True
+
+    # Handle ellipsis notation for variadic flags
+    if var and long:
+        if long.endswith("..."):
+            long = long[:-3]
+        elif nargs in ("*", "+"):
+            # Add ellipsis to long form for variadic
+            long = f"{long}..."
+
+    return format_flag(
+        short=short,
+        long=long,
+        help_text=help_text,
+        required=required,
+        default=default,
+        count=is_count,
+        var=var,
+        var_min=var_min,
+        var_max=var_max,
+        choices=choices,
+    )
+
+
+def _convert_positional_to_spec(action: argparse.Action) -> str:
+    """Convert a positional argument to usage spec KDL."""
+    name = action.dest
+    help_text = getattr(action, "help", None)
+    required = getattr(action, "required", False)
+    default = getattr(action, "default", None)
+    choices = getattr(action, "choices", None)
+
+    # Get variadic info
+    nargs = getattr(action, "nargs", None)
+    var, var_min, var_max = _get_var_info(nargs)
+
+    # Handle optional positionals (nargs='?')
+    if nargs == "?":
+        required = False
+
+    return format_arg(
+        name=name,
+        help_text=help_text,
+        required=required,
+        default=default,
+        var=var,
+        var_min=var_min,
+        var_max=var_max,
+        choices=choices,
+    )
+
+
+def _format_subcommand(name: str, parser: argparse.ArgumentParser) -> str:
+    """Format a subcommand with its spec."""
+    lines = [f"cmd {name} {{"]
+
+    # Add help text if available
+    help_text = getattr(parser, "description", None) or getattr(
+        parser, "_help_text", None
+    )
+    if help_text:
+        lines.append(f"  help={escape_string(help_text)}")
+
+    # Process all actions (skip help and subparsers)
+    for action in parser._actions:
+        if isinstance(action, (argparse._HelpAction, argparse._SubParsersAction)):
+            continue
+
+        spec = _convert_action_to_spec(action)
+        if spec:
+            # Indent each line
+            for line in spec.split("\n"):
+                lines.append(f"  {line}")
+
+    # Handle sub-subcommands
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            for sub_name, sub_parser in action.choices.items():
+                lines.append(_format_subcommand(sub_name, sub_parser))
+
+    lines.append("}")
+    return "\n".join(lines)
+
+
+def generate_usage_spec(
+    parser: argparse.ArgumentParser,
+    name: str | None = None,
+    version: str | None = None,
+    author: str | None = None,
+    bin_name: str | None = None,
+) -> str:
+    """Generate a usage spec KDL string from an ArgumentParser.
+
+    Args:
+        parser: The ArgumentParser instance to convert.
+        name: The friendly name for the CLI (defaults to parser.prog or description).
+        version: The version of the CLI.
+        author: The author of the CLI.
+        bin_name: The binary name (defaults to parser.prog).
+
+    Returns:
+        A KDL-formatted usage spec string.
+    """
+    lines = []
+
+    lines.append("// @generated by argparse-usage from Python argparse")
+    lines.append("")
+
+    if name:
+        lines.append(f"name {escape_string(name)}")
+    elif parser.prog:
+        lines.append(f"name {escape_string(parser.prog)}")
+    elif parser.description:
+        # Try to extract name from description
+        import re
+
+        match = re.match(r"^(\w+)", parser.description)
+        if match:
+            lines.append(f"name {escape_string(match.group(1))}")
+
+    bin_value = bin_name or parser.prog or "cli"
+    lines.append(f"bin {escape_string(bin_value)}")
+
+    if version:
+        lines.append(f"version {escape_string(version)}")
+
+    if author:
+        lines.append(f"author {escape_string(author)}")
+
+    if parser.description:
+        lines.append(f"about {escape_string(parser.description)}")
+
+    lines.append("")
+
+    # Process all actions (skip help and subparsers)
+    for action in parser._actions:
+        if isinstance(action, (argparse._HelpAction, argparse._SubParsersAction)):
+            continue
+
+        spec = _convert_action_to_spec(action)
+        if spec:
+            lines.append(spec)
+
+    # Handle subcommands
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            for name, sub_parser in action.choices.items():
+                lines.append(_format_subcommand(name, sub_parser))
+
+    return "\n".join(lines)

argparse_usage/kdl_utils.py

@@ -0,0 +1,150 @@
+"""KDL formatting utilities for usage spec generation."""
+
+import argparse
+
+
+def escape_string(value: str) -> str:
+    """Escape a string value for KDL format."""
+    if not value:
+        return '""'
+
+    value = str(value)
+
+    # If string contains special characters, use raw string format r#"..."#
+    needs_raw = any(c in value for c in ['"', "\n", "\r", "\t", "\\"])
+
+    if needs_raw:
+        # Use raw string format to avoid escaping
+        return f'r#"{value}"#'
+    else:
+        return f'"{value}"'
+
+
+def format_flag(
+    short: str | None,
+    long: str | None,
+    help_text: str | None = None,
+    required: bool = False,
+    default: str | bool | int | None = None,
+    count: bool = False,
+    var: bool = False,
+    var_min: int | None = None,
+    var_max: int | None = None,
+    choices: list[str] | None = None,
+    long_help: str | None = None,
+) -> str:
+    """Format a flag definition for KDL spec."""
+    parts = []
+
+    # Build flag name (e.g., "-f --force")
+    flag_names = []
+    if short:
+        flag_names.append(short)
+    if long:
+        flag_names.append(long)
+    flag_str = " ".join(flag_names)
+
+    # Check if we need a block (for complex attributes like choices or long_help)
+    needs_block = choices is not None or (long_help and len(long_help) > 50)
+
+    # Simple attributes (inline)
+    attrs = []
+    if help_text:
+        attrs.append(f"help={escape_string(help_text)}")
+    if required:
+        attrs.append("required=#true")
+    if default is not None and default != argparse.SUPPRESS:
+        if isinstance(default, bool):
+            attrs.append(f"default=#{str(default).lower()}")
+        else:
+            attrs.append(f"default={escape_string(str(default))}")
+    if count:
+        attrs.append("count=#true")
+    if var or var_min is not None or var_max is not None:
+        attrs.append("var=#true")
+        if var_min is not None:
+            attrs.append(f"var_min={var_min}")
+        if var_max is not None:
+            attrs.append(f"var_max={var_max}")
+
+    if needs_block:
+        parts.append(f"flag {escape_string(flag_str)} {{")
+        for attr in attrs:
+            parts.append(f"  {attr}")
+        if long_help:
+            parts.append(f"  long_help={escape_string(long_help)}")
+        if choices:
+            arg_name = long.lstrip("-") if long else "value"
+            parts.append(f'  arg "<{arg_name}>" {{')
+            parts.append(f"    choices {' '.join(escape_string(c) for c in choices)}")
+            parts.append("  }")
+        parts.append("}")
+    else:
+        line = f"flag {escape_string(flag_str)}"
+        if attrs:
+            line += " " + " ".join(attrs)
+        parts.append(line)
+
+    return "\n".join(parts)
+
+
+def format_arg(
+    name: str,
+    help_text: str | None = None,
+    required: bool = True,
+    default: str | None = None,
+    var: bool = False,
+    var_min: int | None = None,
+    var_max: int | None = None,
+    choices: list[str] | None = None,
+    long_help: str | None = None,
+) -> str:
+    """Format an argument definition for KDL spec."""
+    parts = []
+
+    # Build arg name (e.g., "<file>" or "[file]" or "<file>..." or "[file]...")
+    if not var and not var_min and not var_max:
+        arg_name = f"[{name}]" if not required else f"<{name}>"
+    else:
+        # Variadic argument
+        if var_min == 0:
+            # Zero or more -> optional
+            arg_name = f"[{name}]..."
+        else:
+            # One or more -> required
+            arg_name = f"<{name}>..."
+
+    # Check if we need a block (for complex attributes like choices or long_help)
+    needs_block = choices is not None or (long_help and len(long_help) > 50)
+
+    # Simple attributes (inline)
+    attrs = []
+    if help_text:
+        attrs.append(f"help={escape_string(help_text)}")
+    if not required:
+        attrs.append("required=#false")
+    if default is not None and default != argparse.SUPPRESS:
+        attrs.append(f"default={escape_string(str(default))}")
+    if var:
+        attrs.append("var=#true")
+    if var_min is not None:
+        attrs.append(f"var_min={var_min}")
+    if var_max is not None:
+        attrs.append(f"var_max={var_max}")
+
+    if needs_block:
+        parts.append(f"arg {escape_string(arg_name)} {{")
+        for attr in attrs:
+            parts.append(f"  {attr}")
+        if long_help:
+            parts.append(f"  long_help={escape_string(long_help)}")
+        if choices:
+            parts.append(f"  choices {' '.join(escape_string(c) for c in choices)}")
+        parts.append("}")
+    else:
+        line = f"arg {escape_string(arg_name)}"
+        if attrs:
+            line += " " + " ".join(attrs)
+        parts.append(line)
+
+    return "\n".join(parts)

argparse_usage-0.1.0.dist-info/METADATA

@@ -0,0 +1,178 @@
+Metadata-Version: 2.3
+Name: argparse-usage
+Version: 0.1.0
+Summary: Generate usage spec KDL files from Python argparse.ArgumentParser
+Author: acidghost
+Author-email: acidghost <1787979+acidghost@users.noreply.github.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# argparse-usage
+
+Generate [usage](https://usage.jdx.dev/) KDL files from Python's `argparse.ArgumentParser`.
+
+This library converts Python `argparse` definitions to the [usage spec format](https://usage.jdx.dev/spec/reference/), enabling automatic generation of:
+
+- Markdown documentation
+- Manpages
+- Shell completions (bash, fish, zsh, powershell, nu)
+
+## Installation
+
+```bash
+pip install argparse-usage
+# or
+uv add argparse-usage
+```
+
+## Usage
+
+```python
+import argparse
+import argparse_usage
+
+# Create your ArgumentParser as usual
+parser = argparse.ArgumentParser(
+    prog='mycli',
+    description='My CLI tool',
+)
+
+parser.add_argument('-v', '--verbose', action='count', default=0, help='Increase verbosity')
+parser.add_argument('-f', '--force', action='store_true', help='Force operation')
+parser.add_argument('files', nargs='+', help='Files to process')
+
+# Add subcommands
+subparsers = parser.add_subparsers(dest='command')
+build_cmd = subparsers.add_parser('build', help='Build project')
+test_cmd = subparsers.add_parser('test', help='Run tests')
+
+# Generate usage spec
+spec = argparse_usage.generate(
+    parser,
+    name='My CLI',
+    version='1.0.0',
+    author='Your Name',
+)
+
+print(spec)
+```
+
+Output:
+
+```kdl
+// @generated by argparse-usage from Python argparse
+
+name "My CLI"
+bin "mycli"
+version "1.0.0"
+author "Your Name"
+about "My CLI tool"
+
+arg "<files>..." help="Files to process" var=#true var_min=1
+
+flag "-v --verbose" help="Increase verbosity" default="0" count=#true
+flag "-f --force" help="Force operation" default=#false
+
+cmd build {
+  // options
+}
+
+cmd test {
+  // options
+}
+```
+
+## Generating Documentation
+
+Save the spec and use the `usage` CLI to generate documentation:
+
+```bash
+# Save spec to file
+python mycli.py --usage-spec > mycli.usage.kdl
+
+# Generate markdown documentation
+usage generate markdown --file mycli.usage.kdl --out-file README.md
+
+# Generate shell completions
+usage generate completion bash mycli --file mycli.usage.kdl > mycli-completion.bash
+```
+
+## Supported Features
+
+### Flags (optional arguments)
+
+| argparse action        | usage spec mapping                                             |
+| ---------------------- | -------------------------------------------------------------- |
+| `action='store_true'`  | `flag "--force" default=#false`                                |
+| `action='store_false'` | `flag "--quiet" default=#true`                                 |
+| `action='count'`       | `flag "-v --verbose" count=#true`                              |
+| `nargs='*'`            | `flag "--files..." var=#true`                                  |
+| `nargs='+'`            | `flag "--tags..." var=#true var_min=1`                         |
+| `choices=[...]`        | `flag "--format" { arg "<format>" { choices "json" "yaml" } }` |
+
+### Arguments (positional)
+
+| argparse nargs         | usage spec mapping                      |
+| ---------------------- | --------------------------------------- |
+| `nargs=None` (default) | `arg "<file>"`                          |
+| `nargs='?'`            | `arg "[file]"`                          |
+| `nargs='*'`            | `arg "[files]..." var=#true`            |
+| `nargs='+'`            | `arg "<files>..." var=#true var_min=1`  |
+| `nargs=N`              | `arg "<coords>..." var_min=N var_max=N` |
+
+### Parent Parsers
+
+Inheritance from parent parsers is supported:
+
+```python
+parent_parser = argparse.ArgumentParser(add_help=False)
+parent_parser.add_argument('-v', '--verbose', action='count')
+
+parser = argparse.ArgumentParser(parents=[parent_parser])
+```
+
+### Subcommands
+
+Nested subcommands are fully supported:
+
+```python
+subparsers = parser.add_subparsers()
+add_cmd = subparsers.add_parser('add')
+add_cmd.add_argument('name')
+```
+
+Output:
+
+```kdl
+cmd add {
+  arg "<name>"
+}
+```
+
+## API Reference
+
+### `generate(parser, name=None, version=None, author=None, bin_name=None)`
+
+Generate a usage spec KDL string from an ArgumentParser.
+
+**Parameters:**
+
+- `parser` (ArgumentParser): The ArgumentParser instance to convert
+- `name` (str, optional): Friendly name for the CLI (defaults to parser.prog)
+- `version` (str, optional): Version of the CLI
+- `author` (str, optional): Author of the CLI
+- `bin_name` (str, optional): Binary name (defaults to parser.prog)
+
+**Returns:**
+
+- `str`: KDL-formatted usage spec string
+
+## Examples
+
+See the [examples/](examples/) directory for complete examples:
+
+- [basic_usage.py](examples/basic_usage.py) - Basic usage with flags, args, and subcommands
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

argparse_usage-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+argparse_usage/__init__.py,sha256=reBHhbeJMGSXH6e01vl4CneZM6FtP_Gs3g51B-hWXHA,180
+argparse_usage/generator.py,sha256=Ofr0M0P2ImcejvsWra52n-FJ0XsnXee9L3ojZ9LPGIk,7560
+argparse_usage/kdl_utils.py,sha256=_n91qL_sNdGA8GcT8rAJq2t_dLbucJ2mC4EKh079H6o,4685
+argparse_usage/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+argparse_usage-0.1.0.dist-info/WHEEL,sha256=mydTeHxOpFHo-DnYhAd_3ATePms-g4rrYvM7wJK8P-U,80
+argparse_usage-0.1.0.dist-info/METADATA,sha256=N8yeQQ8a8tYZ7HpkK9vIQjSjGoYYpzdcF5b6_36Q2hk,4867
+argparse_usage-0.1.0.dist-info/RECORD,,

argparse_usage-0.1.0.dist-info/WHEEL

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