philiprehberger-docstring-cli

Automatically generate CLI interfaces from function signatures and docstrings.

Installation

pip install philiprehberger-docstring-cli

Usage

With the @cli decorator

from philiprehberger_docstring_cli import cli

@cli
def greet(name: str, count: int = 1, loud: bool = False):
    """Greet someone by name.

    Args:
        name: The person to greet.
        count: Number of times to greet.
        loud: Whether to shout.
    """
    greeting = f"Hello, {name}!"
    if loud:
        greeting = greeting.upper()
    for _ in range(count):
        print(greeting)

# Call from CLI: python greet.py Alice --count 3 --loud
# Or call normally: greet("Alice", count=3, loud=True)

The decorated function can still be called normally with arguments. When called with no arguments, it parses sys.argv and runs as a CLI command.

Use .cli(argv=[...]) to pass explicit arguments:

greet.cli(["Alice", "--count", "2", "--loud"])

With run()

For one-off usage without decorating:

from philiprehberger_docstring_cli import run

def add(a: int, b: int):
    """Add two numbers.

    Args:
        a: First number.
        b: Second number.
    """
    return a + b

run(add, ["3", "4"])  # prints 7

Adding --version

Pass version="..." to run() to enable a built-in --version flag:

from philiprehberger_docstring_cli import run

def add(a: int, b: int):
    """Add two numbers."""
    return a + b

run(add, version="1.0.0")
# Invoking with --version prints "1.0.0" and exits.

Introspecting commands

Use command_info(fn) to inspect a @cli-decorated (or plain) function without invoking it. Useful for building help screens, completion data, or programmatic command listings.

from philiprehberger_docstring_cli import cli, command_info

@cli
def greet(name: str, count: int = 1):
    """Greet someone by name.

    Args:
        name: The person to greet.
        count: Number of times to greet.
    """
    ...

info = command_info(greet)
# {
#   "name": "greet",
#   "description": "Greet someone by name.",
#   "params": [
#     {"name": "name",  "type": "str", "default": None, "required": True,  "help": "The person to greet."},
#     {"name": "count", "type": "int", "default": 1,    "required": False, "help": "Number of times to greet."},
#   ],
# }

API

Name	Description
cli	Decorator that makes a function callable from the CLI.
run	Run any function as a CLI command without decorating it.
command_info	Introspect a function and return its CLI metadata.

@cli

• Reads type hints to set argument types (int, float, str, etc.)
• Parameters without defaults become positional arguments
• Parameters with defaults become optional --flags
• bool parameters become --flag / --no-flag toggles
• Underscore parameter names are converted to hyphenated flags (dry_run -> --dry-run)
• Google-style docstring Args: sections are used for help text

run(func, argv=None, *, version=None)

• Builds a parser from the function and parses the given argv (or sys.argv[1:])
• Does not require the @cli decorator
• version: when set, the parser accepts --version and prints this string

command_info(func)

• Returns a dict with name, description, and params
• Each entry in params is a dict with name, type, default, required, and help
• Works on @cli-decorated functions as well as plain functions

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT