Metadata-Version: 2.3
Name: argparse-usage
Version: 0.1.1
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

![PyPI - Version](https://img.shields.io/pypi/v/argparse-usage?color=rgb(0%2C%2087%2C%20138))
![GitHub branch status](https://img.shields.io/github/check-runs/acidghost/argparse-usage/main)

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
- [complex_usage.py](examples/complex_usage.py) - Complex CLI with nested subcommands (config, database, deploy)

For information on setting up shell completions, see the [examples README](examples/README.md).

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
