typthon/STRICT_TYPING.md

Typthon Strict Typing Vision

Overview

Typthon aims to be a strictly typed variant of Python, bringing compile-time type safety while maintaining Python's readable syntax and developer-friendly features.

Current Status

Foundation Phase: Complete ✅

• Renamed all Py* → Ty* prefixes throughout codebase
• Build system fully functional
• Core interpreter operational
• Ready for type system enhancements

Goals

Short Term

1. Type Annotation Enforcement

   • Make type hints mandatory for function signatures
   • Require explicit types for class attributes
   • Enforce type annotations at module level

2. Compile-Time Type Checking

   • Implement static analysis during compilation
   • Catch type errors before runtime
   • Provide helpful error messages with suggestions

3. Type Inference

   • Infer types where obvious from context
   • Reduce annotation burden for local variables
   • Maintain strictness at API boundaries

Long Term

1. Advanced Type Features

   • Generic types with variance
   • Union and intersection types
   • Literal types
   • Protocol types (structural subtyping)

2. Performance Optimizations

   • Use type information for optimization
   • Eliminate runtime type checks where proven safe
   • Generate specialized code paths

3. Gradual Typing Integration

   • Interoperate with Python libraries
   • Provide clear boundaries between typed/untyped code
   • Support progressive migration from Python

Design Principles

1. Safety First

   • Type errors should be caught at compile time
   • No implicit type conversions that lose information
   • Null safety (no implicit None)

2. Developer Friendly

   • Clear, actionable error messages
   • Minimal annotation burden where types are obvious
   • Helpful IDE integration

3. Python Compatible (Where Possible)

   • Maintain Python syntax for familiarity
   • Support Python libraries with typed wrappers
   • Enable gradual migration path

4. Performance Conscious

   • Use type information to generate faster code
   • Eliminate unnecessary runtime checks
   • Enable AOT compilation opportunities

Proposed Syntax

Mandatory Function Annotations

# ✅ Valid Typthon
def add(x: int, y: int) -> int:
    return x + y

# ❌ Error: Missing type annotations
def add(x, y):
    return x + y

Type Inference for Locals

def process_data(items: list[int]) -> int:
    # Type inferred as int
    total = 0
    
    # Type inferred as int from iteration
    for item in items:
        total += item
    
    return total

Null Safety

from typing import Optional

# Explicit Optional required for nullable values
def find_user(id: int) -> Optional[User]:
    ...

# Must handle None case
user = find_user(42)
if user is not None:
    print(user.name)  # ✅ Safe
else:
    print("Not found")

# ❌ Error: user might be None
print(user.name)

Implementation Plan

Phase 1: Type Analysis Infrastructure

• Build AST analyzer for type annotations
• Implement type representation system
• Create type compatibility checker
• Add error reporting framework

Phase 2: Basic Type Checking

• Enforce function signature types
• Check variable assignments
• Validate return types
• Implement basic type inference

Phase 3: Advanced Features

• Generic type support
• Protocol types
• Union/Intersection types
• Type narrowing

Phase 4: Optimizations

• Use types for code generation
• Eliminate redundant checks
• Enable specialization
• AOT compilation support

Compatibility with Python

Python Library Usage

# Import Python libraries with typed stubs
from typing_extensions import TypedDict
import numpy as np  # With .pyi stub file

# Or use explicit typing at boundary
def process_numpy(arr: np.ndarray[np.float64]) -> float:
    return float(np.mean(arr))  # Explicit cast

Migration Path

1. Start with type stubs for Python libraries
2. Gradually add type annotations to code
3. Enable strict checking per-module
4. Full type safety at boundaries

Benefits

1. Fewer Bugs - Catch errors before they reach production
2. Better Documentation - Types serve as always-up-to-date documentation
3. IDE Support - Better autocomplete, refactoring, navigation
4. Performance - Enable optimizations not possible with dynamic types
5. Confidence - Refactor fearlessly with type checking

References

• Python typing PEPs (PEP 484, 526, 544, 585, 604, 612)
• MyPy static type checker
• TypeScript's approach to gradual typing
• Rust's type system for inspiration on safety
• Swift's type inference strategy

Contributing

Type system design is an ongoing discussion. See:

• GitHub Issues with type-system label
• Design discussions in /docs/design/
• Implementation RFCs

---

Note: This is a living document. The type system design will evolve as we implement and learn. Community feedback is essential to making Typthon both powerful and practical.