# 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

```bash
pip install stubgen
```

### From source

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

### Using uv (recommended)

```bash
uv pip install stubgen
```

## Usage

### Generate stubs for a single file

```bash
stubgen path/to/module.py
```

### Generate stubs for a directory

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

### Generate stubs recursively

```bash
stubgen path/to/package/ --recursive
```

### Dry run (show what would be generated)

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

### Verbose output

```bash
stubgen path/to/module.py --verbose
```

### Exclude patterns

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

## Configuration

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

### pyproject.toml

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

### stubgen.toml

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

```python
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:

```python
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

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

### Running Tests

```bash
pytest tests/ -v
```

### Linting

```bash
ruff check .
mypy stubgen tests --strict
```

## License

MIT