tessl/pypi-pytype

Python type inferencer that analyzes code without requiring explicit type annotations

—

Pending

Overview

Eval results

Files

CLI Tools

Name: tessl/pypi-pytype
Author: tessl

Complete set of command-line tools for different PyType workflows, from single-file analysis to project-wide type checking and stub generation. These tools provide the primary user interface to PyType's capabilities.

Capabilities

pytype - Project Analysis Tool

Main command-line interface for analyzing entire Python projects with comprehensive configuration options.

pytype [OPTIONS] [FILES...]

Key Options:

--python_version VERSION - Target Python version (e.g., 3.11)
--output DIR - Output directory for generated .pyi files
--check - Check for type errors without generating stubs
--imports_map FILE - Custom import mappings file
--exclude PATTERN - Exclude files matching pattern
--jobs N - Number of parallel processes

Examples:

# Analyze entire project
pytype src/

# Check types without generating stubs
pytype --check --python_version=3.11 src/

# Generate stubs with custom output directory
pytype --output=stubs/ --python_version=3.11 src/

# Parallel analysis with custom imports
pytype --jobs=4 --imports_map=.pytype/imports.txt src/

The pytype tool is implemented in:

# pytype.tools.analyze_project.main
def main():
    """
    Main entry point for project-wide PyType analysis.
    
    Handles command-line argument parsing, project discovery,
    parallel analysis coordination, and result aggregation.
    
    Returns:
    int: Exit code (0 for success, non-zero for errors)
    """

pytype-single - Single File Analysis

Analyzes individual Python files with detailed control over the analysis process.

pytype-single [OPTIONS] FILE

Key Options:

--output FILE - Output .pyi file path
--check - Type check only, no stub generation
--analyze-annotated - Analyze functions with annotations
--quick - Fast analysis mode
--maximum-depth N - Analysis depth limit

Examples:

# Generate stub for single file
pytype-single --output=module.pyi module.py

# Quick type check
pytype-single --check --quick module.py

# Deep analysis with annotations
pytype-single --analyze-annotated --maximum-depth=5 module.py

The pytype-single tool is implemented in:

# pytype.main
def main():
    """
    Main entry point for single-file PyType analysis.
    
    Processes command-line arguments and performs type analysis
    on a single Python file.
    
    Returns:
    int: Exit code (0 for success, non-zero for errors)
    """

def _run_pytype(options):
    """
    Core PyType execution logic.
    
    Parameters:
    - options (Options): Configuration for analysis
    
    Returns:
    Analysis results and error information
    """

pytd - PyTD File Processor

Tool for working with PyTD (Python Type Declaration) files, including validation, optimization, and format conversion.

pytd [OPTIONS] FILE.pytd

Key Options:

--optimize - Optimize PyTD AST
--verify - Verify PyTD correctness
--print - Pretty print PyTD content
--output FILE - Output file for processed PyTD

Examples:

# Optimize PyTD file
pytd --optimize --output=optimized.pytd types.pytd

# Verify PyTD correctness
pytd --verify module.pytd

# Pretty print PyTD content
pytd --print types.pytd

The pytd tool is implemented in:

# pytype.pytd.main
def main():
    """
    Main entry point for PyTD file processing.
    
    Handles PyTD file parsing, optimization, verification,
    and format conversion operations.
    
    Returns:
    int: Exit code (0 for success, non-zero for errors)
    """

def make_parser():
    """
    Create argument parser for pytd tool.
    
    Returns:
    argparse.ArgumentParser: Configured parser for pytd options
    """

merge-pyi - Stub File Merger

Merges .pyi type stub information into Python source files, adding type annotations based on inferred types.

merge-pyi [OPTIONS] SOURCE.py STUB.pyi

Key Options:

--output FILE - Output file with merged annotations
--in-place - Modify source file in place
--no-backup - Don't create backup files
--annotate-only FUNCTIONS - Annotate only specified functions

Examples:

# Merge stub into source file
merge-pyi --output=annotated.py module.py module.pyi

# In-place annotation
merge-pyi --in-place module.py module.pyi

# Annotate specific functions only
merge-pyi --annotate-only="func1,func2" module.py module.pyi

The merge-pyi tool is implemented in:

# pytype.tools.merge_pyi.main
def main(argv=None):
    """
    Main entry point for merging .pyi annotations into source files.
    
    Parameters:
    - argv (list, optional): Command line arguments
    
    Returns:
    int: Exit code (0 for success, non-zero for errors)
    """

def parse_args(argv):
    """
    Parse command line arguments for merge-pyi tool.
    
    Parameters:
    - argv (list): Command line arguments
    
    Returns:
    Parsed arguments object
    """

annotate-ast - AST Annotator

Adds type annotations directly to Python AST nodes based on PyType's inference results.

annotate-ast [OPTIONS] FILE.py

Key Options:

--output FILE - Output file with annotated AST
--python-version VERSION - Target Python version
--preserve-existing - Keep existing annotations

Examples:

# Annotate AST with inferred types
annotate-ast --output=annotated.py module.py

# Preserve existing annotations
annotate-ast --preserve-existing module.py

The annotate-ast tool is implemented in:

# pytype.tools.annotate_ast.main
def main():
    """
    Main entry point for AST annotation.
    
    Analyzes Python source and adds type annotations
    directly to AST nodes based on inference results.
    
    Returns:
    int: Exit code (0 for success, non-zero for errors)
    """

def annotate_source(src, ast_factory, options):
    """
    Annotate source code with type information.
    
    Parameters:
    - src (str): Python source code
    - ast_factory: AST creation factory
    - options (Options): Analysis configuration
    
    Returns:
    Annotated AST with type information
    """

pyxref - Cross-Reference Generator

Generates cross-reference information from Python projects, creating indexes of symbol definitions and usage.

pyxref [OPTIONS] [FILES...]

Key Options:

--output DIR - Output directory for cross-reference data
--format FORMAT - Output format (json, html, text)
--include-builtin - Include built-in symbol references

Examples:

# Generate cross-reference data
pyxref --output=xref/ --format=json src/

# HTML cross-reference with builtins
pyxref --output=docs/ --format=html --include-builtin src/

The pyxref tool is implemented in:

# pytype.tools.xref.main
def main():
    """
    Main entry point for cross-reference generation.
    
    Analyzes Python projects and generates comprehensive
    cross-reference information for symbols and their usage.
    
    Returns:
    int: Exit code (0 for success, non-zero for errors)
    """

Common Usage Patterns

CI/CD Integration

#!/bin/bash
# CI script for type checking

# Quick type check for pull requests
if [ "$CI_PULL_REQUEST" = "true" ]; then
    pytype --check --quick --jobs=2 src/
else
    # Full analysis for main branch
    pytype --output=stubs/ --python-version=3.11 src/
fi

Development Workflow

# 1. Initial project setup
pytype --output=.pytype/pyi/ src/

# 2. Check specific file during development
pytype-single --check --quick src/mymodule.py

# 3. Generate updated stubs after changes
pytype-single --output=.pytype/pyi/mymodule.pyi src/mymodule.py

# 4. Merge annotations for release
merge-pyi --output=src/mymodule_annotated.py src/mymodule.py .pytype/pyi/mymodule.pyi

Large Project Analysis

# Parallel analysis with custom configuration
pytype \
  --jobs=8 \
  --python-version=3.11 \
  --output=stubs/ \
  --imports-map=.pytype/imports.txt \
  --exclude="**/test_*.py" \
  --exclude="**/conftest.py" \
  src/

Stub Generation Pipeline

#!/bin/bash
# Generate and optimize stubs

# 1. Generate initial stubs
pytype --output=raw_stubs/ src/

# 2. Optimize PyTD files
for file in raw_stubs/*.pyi; do
    pytd --optimize --output="optimized_stubs/$(basename "$file")" "$file"
done

# 3. Verify optimized stubs
for file in optimized_stubs/*.pyi; do
    pytd --verify "$file" || echo "Verification failed for $file"
done

Exit Codes

All PyType CLI tools use consistent exit codes:

0 - Success, no errors found
1 - Type errors found (when using --check)
2 - Command-line argument errors
3 - File not found or permission errors
4 - Internal PyType errors
5 - Python version compatibility errors

Configuration Files

CLI tools support configuration through:

.pytype/ directory for project settings
pyproject.toml for PEP 518 configuration
Command-line arguments (highest priority)

Example .pytype/imports.txt:

# Custom import mappings
mypackage.internal mypackage._internal
external_lib /path/to/external/stubs

Integration with Other Tools

# Integration with mypy
pytype --output=stubs/ src/ && mypy --check-untyped-defs src/

# Integration with black formatter
pytype-single module.py && black module.py

# Integration with pytest
pytype --check src/ && pytest tests/

Install with Tessl CLI