argparse-usage 0.1.1

Generate usage spec KDL files from Python argparse.ArgumentParser

argparse-usage

Generate usage KDL files from Python's argparse.ArgumentParser.

This library converts Python argparse definitions to the usage spec format, enabling automatic generation of:

• Markdown documentation
• Manpages
• Shell completions (bash, fish, zsh, powershell, nu)

Installation

pip install argparse-usage
# or
uv add argparse-usage

Usage

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:

// @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:

# 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:

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:

subparsers = parser.add_subparsers()
add_cmd = subparsers.add_parser('add')
add_cmd.add_argument('name')

Output:

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/ directory for complete examples:

• basic_usage.py - Basic usage with flags, args, and subcommands
• complex_usage.py - Complex CLI with nested subcommands (config, database, deploy)

For information on setting up shell completions, see the examples README.

Contributing

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