argparse-patterns

Python's built-in argparse module for CLI argument parsing - no external dependencies required.

Overview

Provides comprehensive argparse patterns using only Python standard library. Includes subparsers for nested commands, choices for validation, custom actions, argument groups, and mutually exclusive options.

Instructions

Basic Parser Setup

1. Import argparse and create parser with description
2. Add version info with

   action='version'

3. Set formatter_class for better help formatting
4. Parse arguments with

   parser.parse_args()

Subparsers (Nested Commands)

1. Use

   parser.add_subparsers(dest='command')

   to create command groups
2. Add individual commands with

   subparsers.add_parser('command-name')

3. Each subparser can have its own arguments and options
4. Nest subparsers for multi-level commands (e.g.,

   mycli config get key

   )

Choices and Validation

1. Use

   choices=['opt1', 'opt2']

   to restrict values
2. Implement custom validation with type functions
3. Add validators using argparse types
4. Set defaults with

   default=value

Actions

1. store_true/store_false

   - Boolean flags

2. store_const

   - Store constant value

3. append

   - Collect multiple values

4. count

   - Count flag occurrences

5. version

   - Display version and exit
6. Custom actions with Action subclass

Argument Types

1. Positional arguments - Required by default
2. Optional arguments - Prefix with

   --

   or

   -

3. Type coercion -

   type=int

   ,

   type=float

   ,

   type=pathlib.Path

4. Nargs -

   '?'

   (optional),

   '*'

   (zero or more),

   '+'

   (one or more)

Available Templates

Python Templates

• basic-parser.py - Simple parser with arguments and options
• subparser-pattern.py - Single-level subcommands
• nested-subparser.py - Multi-level nested commands (e.g., git config get)
• choices-validation.py - Argument choices and validation
• boolean-flags.py - Boolean flag patterns
• custom-actions.py - Custom action classes
• mutually-exclusive.py - Mutually exclusive groups
• argument-groups.py - Organizing related arguments
• type-coercion.py - Custom type converters
• variadic-args.py - Variable argument patterns

TypeScript Templates

• argparse-to-commander.ts - argparse patterns translated to commander.js
• argparse-to-yargs.ts - argparse patterns translated to yargs
• parser-comparison.ts - Side-by-side argparse vs Node.js patterns

Available Scripts

• generate-parser.sh - Generate argparse parser from specifications
• validate-parser.sh - Validate parser structure and completeness
• test-parser.sh - Test parser with various argument combinations
• convert-to-click.sh - Convert argparse code to Click decorators

Examples

See

examples/

directory for comprehensive patterns:

• basic-usage.md - Simple CLI with arguments
• subcommands.md - Multi-command CLI (like git, docker)
• nested-commands.md - Deep command hierarchies
• validation-patterns.md - Argument validation strategies
• advanced-parsing.md - Complex parsing scenarios

Common Patterns

Pattern 1: Simple CLI with Options

parser = argparse.ArgumentParser(description='Deploy application')
parser.add_argument('--env', choices=['dev', 'staging', 'prod'], default='dev')
parser.add_argument('--force', action='store_true')
args = parser.parse_args()

Pattern 2: Subcommands (git-like)

parser = argparse.ArgumentParser()
subparsers = parser.add_subparsers(dest='command')

deploy_cmd = subparsers.add_parser('deploy')
deploy_cmd.add_argument('environment')

config_cmd = subparsers.add_parser('config')

Pattern 3: Nested Subcommands (git config get/set)

parser = argparse.ArgumentParser()
subparsers = parser.add_subparsers(dest='command')

config = subparsers.add_parser('config')
config_subs = config.add_subparsers(dest='config_command')

config_get = config_subs.add_parser('get')
config_get.add_argument('key')

config_set = config_subs.add_parser('set')
config_set.add_argument('key')
config_set.add_argument('value')

Pattern 4: Mutually Exclusive Options

group = parser.add_mutually_exclusive_group()
group.add_argument('--json', action='store_true')
group.add_argument('--yaml', action='store_true')

Pattern 5: Custom Validation

def validate_port(value):
    ivalue = int(value)
    if ivalue < 1 or ivalue > 65535:
        raise argparse.ArgumentTypeError(f"{value} is not a valid port")
    return ivalue

parser.add_argument('--port', type=validate_port, default=8080)

Best Practices

1. Always provide help text - Use

   help=

   for every argument
2. Set sensible defaults - Use

   default=

   to avoid None values
3. Use choices for fixed options - Better than manual validation
4. Group related arguments - Use

   add_argument_group()

   for clarity
5. Handle missing subcommands - Check if

   args.command

   is None
6. Use type coercion - Prefer

   type=int

   over manual conversion
7. Provide examples - Use

   epilog=

   for usage examples

Advantages Over External Libraries

• No dependencies - Built into Python standard library
• Stable API - Won't break with updates
• Universal - Works everywhere Python works
• Well documented - Extensive official documentation
• Lightweight - No installation or import overhead

When to Use argparse

Use argparse when:

• Building simple to medium complexity CLIs
• Avoiding external dependencies is important
• Working in restricted environments
• Learning CLI patterns (clear, explicit API)

Consider alternatives when:

• Need decorator-based syntax (use Click/Typer)
• Want type safety and auto-completion (use Typer)
• Rapid prototyping from existing code (use Fire)

Integration

This skill integrates with:

• cli-setup

  agent - Initialize Python CLI projects

• cli-feature-impl

  agent - Implement command logic

• cli-verifier-python

  agent - Validate argparse structure

• click-patterns

  skill - Compare with Click patterns

• typer-patterns

  skill - Compare with Typer patterns

Requirements

• Python 3.7+ (argparse included in standard library)
• No external dependencies required
• Works on all platforms (Windows, macOS, Linux)

---

Purpose: Standard library Python CLI argument parsing patterns Used by: Python CLI projects prioritizing zero dependencies