python-stub-generator/README.md

Python Type Stub Generator CLI

A CLI tool that automatically generates Python type stub files (.pyi) from untyped Python code using static analysis. It parses Python AST to infer types, function signatures, and class structures, outputting properly formatted stubs compatible with mypy and other type checkers.

Features

• Stub file generation: Parse Python files and generate .pyi stubs with function signatures, classes, and imports
• Recursive directory scanning: Scan directories recursively to find all Python files and generate stubs
• Type inference engine: Infer types from code analysis when explicit annotations are missing
• Config file support: Load type inference rules from pyproject.toml or stubgen.toml
• Interactive mode: Prompt for confirmation on inferred types
• Output customization: Custom output directory, file naming, and stub format options

Installation

Using pip

pip install stubgen

From source

git clone https://github.com/yourusername/python-stub-generator.git
cd python-stub-generator
pip install -e .

Using uv (recommended)

uv pip install stubgen

Usage

Generate stubs for a single file

stubgen path/to/module.py

Generate stubs for a directory

stubgen path/to/package/ -o output/stubs/

Generate stubs recursively

stubgen path/to/package/ --recursive

Dry run (show what would be generated)

stubgen path/to/module.py --dry-run

Verbose output

stubgen path/to/module.py --verbose

Exclude patterns

stubgen path/to/package/ --exclude "tests/*" --exclude "*/__pycache__/*"

Configuration

stubgen can be configured via pyproject.toml or a dedicated stubgen.toml file.

pyproject.toml

[tool.stubgen]
exclude_patterns = ["tests/*", "*/__pycache__/*", "*/.venv/*"]
infer_depth = 3
strict_mode = false
interactive = false

stubgen.toml

[tool.stubgen]
exclude_patterns = ["tests/*", "build/*"]
infer_depth = 5
strict_mode = true
interactive = true

Configuration Options

Option	Type	Default	Description
exclude_patterns	list	["tests/*", "*/__pycache__/*"]	Patterns to exclude from processing
infer_depth	int	3	Depth of type inference
strict_mode	bool	false	Fail on errors
interactive	bool	false	Prompt for type confirmation
output_dir	str	None	Default output directory

Type Inference

stubgen uses several heuristics to infer types:

1. Return type analysis: Analyze return statements to determine return types
2. Default value analysis: Use default parameter values to infer types
3. Docstring parsing: Extract types from Google-style and NumPy-style docstrings
4. Assignment analysis: Track variable assignments to infer types

Example:

def process_items(items, count=10):
    """Process items.
    
    Args:
        items: List of strings to process
        count: Number of items
    
    Returns:
        Processed list
    """
    return items[:count]

Will generate:

def process_items(items: list[str], count: int = ...) -> list[str]: ...

CLI Options

Global Options

• --verbose, -v: Enable verbose output
• --config, -c: Path to configuration file

stubgen Command Options

• --output, -o: Output directory for generated stubs
• --recursive, -r: Recursively process directories (default: True)
• --no-recursive: Disable recursive directory processing
• --exclude, -e: Patterns to exclude (can be specified multiple times)
• --dry-run: Show what would be generated without writing files
• --interactive, -i: Prompt for confirmation on inferred types
• --infer-depth: Depth of type inference (default: 3)

Development

Setup

git clone https://github.com/yourusername/python-stub-generator.git
cd python-stub-generator
pip install -e ".[dev]"

Running Tests

pytest tests/ -v

Linting

ruff check .
mypy stubgen tests --strict

License

MIT