182 lines
4.1 KiB
Markdown
182 lines
4.1 KiB
Markdown
# 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
|