tessl/pypi-pytype

Python type inferencer that analyzes code without requiring explicit type annotations

—

Pending

Overview

Eval results

Files

PyTD Type System

Name: tessl/pypi-pytype
Author: tessl

Python Type Declaration system for representing, manipulating, and optimizing type information. PyTD provides the foundational data structures and algorithms that enable PyType's type inference, stub generation, and type checking capabilities.

Capabilities

Core PyTD Types

Fundamental AST node types that represent Python type declarations and form the building blocks of PyType's type system.

class Node:
    """Base class for all PyTD AST nodes."""
    
class Type(Node):
    """Base marker class for type representation nodes."""

class TypeDeclUnit(Node):
    """
    Top-level module node containing all declarations.
    
    Represents a complete Python module with its type information,
    including classes, functions, constants, and imports.
    """
    
    def __init__(self, name, constants, type_params, classes, functions, aliases, modules):
        """
        Initialize module type declaration.
        
        Parameters:
        - name (str): Module name
        - constants (list): Module-level constants
        - type_params (list): Type parameters  
        - classes (list): Class declarations
        - functions (list): Function declarations
        - aliases (list): Type aliases
        - modules (list): Imported modules
        """

class Constant(Node):
    """
    Module-level constant declaration.
    
    Represents constants defined at module scope with their inferred types.
    """
    
    def __init__(self, name, type):
        """
        Initialize constant declaration.
        
        Parameters:
        - name (str): Constant name
        - type (Type): Inferred type of constant
        """

class Alias(Node):
    """
    Type alias or symbolic link to classes in other modules.
    
    Enables references to types defined elsewhere without full qualification.
    """
    
    def __init__(self, name, type):
        """
        Initialize type alias.
        
        Parameters:
        - name (str): Alias name
        - type (Type): Target type being aliased
        """

class Class(Node):
    """
    Class declaration with methods, properties, and inheritance.
    
    Represents complete class type information including method signatures,
    class hierarchy, and special methods.
    """
    
    def __init__(self, name, metaclass, parents, methods, constants, classes, decorators, slots, template):
        """
        Initialize class declaration.
        
        Parameters:
        - name (str): Class name
        - metaclass (Type): Metaclass type
        - parents (list): Parent class types
        - methods (list): Method declarations
        - constants (list): Class constants
        - classes (list): Nested classes
        - decorators (list): Class decorators
        - slots (list): __slots__ specification
        - template (list): Generic type parameters
        """

class Function(Node):
    """
    Function declaration with signature and type information.
    
    Represents function signatures including parameters, return types,
    and special function properties.
    """
    
    def __init__(self, name, signatures, kind, flags):
        """
        Initialize function declaration.
        
        Parameters:
        - name (str): Function name
        - signatures (list): Function signatures
        - kind (str): Function kind (method, classmethod, staticmethod)
        - flags (int): Function property flags
        """

Type Representation Classes

Specialized classes for representing different kinds of Python types in the PyTD system.

class GenericType(Type):
    """Generic type with type parameters (e.g., List[int])."""
    
class ClassType(Type):
    """Reference to a class type."""
    
class UnionType(Type):
    """Union of multiple types (e.g., int | str)."""
    
class CallableType(Type):
    """Callable type with parameter and return types."""
    
class TupleType(Type):
    """Tuple type with element types."""
    
class LiteralType(Type):
    """Literal type for specific values."""
    
class TypeParameter(Type):
    """Type parameter for generic types."""

PyTD Utilities

Essential utilities for working with PyTD AST structures, including printing, concatenation, and manipulation functions.

def Print(ast, multiline_args=False):
    """
    Pretty print PyTD AST to string representation.
    
    Parameters:
    - ast (Node): PyTD AST node to print
    - multiline_args (bool): Whether to format arguments across multiple lines
    
    Returns:
    str: String representation of the AST
    """

def Concat(*asts):
    """
    Concatenate multiple PyTD ASTs into a single TypeDeclUnit.
    
    Parameters:
    - *asts: Variable number of TypeDeclUnit nodes to concatenate
    
    Returns:
    TypeDeclUnit: Combined AST containing all input declarations
    """

Example usage:

from pytype.pytd import pytd_utils, pytd

# Create function signature
signature = pytd.Signature(
    params=[
        pytd.Parameter("x", pytd.NamedType("int")),
        pytd.Parameter("y", pytd.NamedType("int"))
    ],
    return_type=pytd.NamedType("int")
)

# Create function
func = pytd.Function(
    name="add",
    signatures=[signature],
    kind=pytd.MethodKind.METHOD,
    flags=0
)

# Print the function
print(pytd_utils.Print(func))
# Output: def add(x: int, y: int) -> int: ...

PyTD Optimization

Optimizes PyTD ASTs for performance and correctness, including type simplification, dead code elimination, and union optimization.

def Optimize(ast, builtins, lossy=False, use_abcs=False, max_union=4, remove_mutable=False, can_do_lookup=True):
    """
    Optimize PyTD AST for performance and correctness.
    
    Parameters:
    - ast (TypeDeclUnit): PyTD AST to optimize
    - builtins (TypeDeclUnit): Built-in types for reference
    - lossy (bool): Whether to allow lossy optimizations
    - use_abcs (bool): Whether to use abstract base classes
    - max_union (int): Maximum union size before simplification
    - remove_mutable (bool): Whether to remove mutable types
    - can_do_lookup (bool): Whether type lookups are available
    
    Returns:
    TypeDeclUnit: Optimized PyTD AST
    """

Example usage:

from pytype.pytd import optimize
from pytype import io

# Generate AST from source
source = '''
def process_data(items):
    result = []
    for item in items:
        result.append(item.upper())
    return result
'''

ast = io.generate_pyi_ast(source)

# Optimize the AST
builtins_ast = # ... load builtins
optimized_ast = optimize.Optimize(
    ast, 
    builtins_ast,
    max_union=6,
    use_abcs=True
)

PyTD Visitors

Visitor pattern implementation for traversing and transforming PyTD ASTs, enabling custom analysis and modification operations.

class Visitor:
    """
    Base visitor class for PyTD AST traversal.
    
    Provides generic visitor pattern implementation with pre- and post-order
    traversal hooks for all PyTD node types.
    """
    
    def Visit(self, node):
        """
        Visit a PyTD node and its children.
        
        Parameters:
        - node (Node): PyTD node to visit
        
        Returns:
        Node: Potentially modified node
        """
    
    def VisitTypeDeclUnit(self, node):
        """Visit TypeDeclUnit node."""
        
    def VisitClass(self, node):
        """Visit Class node."""
        
    def VisitFunction(self, node):
        """Visit Function node."""
    
    # ... additional visit methods for each node type

Common visitor implementations include:

class ReplaceTypes(Visitor):
    """Replace specific types throughout AST."""
    
class CollectDependencies(Visitor):
    """Collect type dependencies from AST."""
    
class VerifyVisitor(Visitor):
    """Verify AST correctness and consistency."""

Module and Import Handling

Classes for representing module imports and cross-module type references.

class Module(Node):
    """
    Imported module representation.
    
    Represents a module import with its qualified name and alias.
    """
    
    def __init__(self, module_name, alias=None):
        """
        Initialize module import.
        
        Parameters:
        - module_name (str): Fully qualified module name
        - alias (str, optional): Import alias
        """

Working with PyTD Files

from pytype.pytd import pytd, pytd_utils
from pytype.pyi import parser

# Parse .pyi file to PyTD AST
with open("types.pyi", "r") as f:
    pyi_content = f.read()

ast = parser.parse_string(pyi_content, filename="types.pyi")

# Manipulate the AST
# ... modify classes, functions, etc.

# Convert back to string
pyi_output = pytd_utils.Print(ast)

# Write optimized version
with open("optimized_types.pyi", "w") as f:
    f.write(pyi_output)

Error Handling

PyTD operations can raise various exceptions during AST construction, optimization, and printing:

from pytype.pytd import pytd

try:
    # Create PyTD structures
    ast = pytd.TypeDeclUnit(...)
    optimized = optimize.Optimize(ast, builtins)
    output = pytd_utils.Print(optimized)
except pytd.ParseError as e:
    print(f"PyTD parsing error: {e}")
except Exception as e:
    print(f"PyTD processing error: {e}")

Install with Tessl CLI