Depyler: Python-to-Rust Transpiler ⚡🦀

Compile Python to energy-efficient, memory-safe Rust code
Transitioning off Python to energy-efficient and safe Rust systems

---

🌍 The Energy Crisis of Modern Computing

The Problem: Python's environmental impact is staggering. Research from Google and AWS reveals that interpreted languages like Python consume 10-100x more energy than compiled alternatives, contributing significantly to global carbon emissions.

The Solution: Depyler automatically transpiles Python to high-performance, memory-safe Rust code, delivering massive energy savings without sacrificing developer productivity.

# Transform your Python codebase to energy-efficient Rust
depyler transpile your_script.py -o optimized.rs

# Compile and run the optimized code
rustc optimized.rs -O
./optimized

# Result: 75-85% energy reduction, 5-15x speedup!

---

🎯 Core Features

🔄 Automatic Transpilation

• Type inference: Smart Python type analysis with HIR (High-level Intermediate Representation)
• Memory safety: Automatic borrow checker compliance
• Zero-copy optimization: Eliminates unnecessary allocations
• Annotation Protocol: Structured comments for guiding transpilation strategy

🛡️ Safety Guarantees

• Memory safety: No segfaults, buffer overflows, or memory leaks
• Thread safety: Data race prevention at compile time
• Type safety: Comprehensive type checking and validation
• Bounds checking: Automatic insertion of safety checks where needed

⚡ Performance Optimization

• LLVM backend: State-of-the-art code generation and optimization
• Binary size optimization: LTO, strip, and panic=abort configurations
• Cache-friendly code: Memory layout optimization for modern CPUs
• Energy efficiency: 75-85% reduction in power consumption vs Python

🧪 Testing & Verification

• Property-based testing: Semantic equivalence verification with QuickCheck
• Test coverage: 85%+ coverage across all modules
• Compilation validation: Generated Rust code guaranteed to compile
• Quality gates: PMAT scoring system with TDG < 2.0 requirement

🚀 AWS Lambda Transpilation

• Automatic event type inference: Detects S3, API Gateway, SQS, SNS, DynamoDB, EventBridge patterns
• Cold start optimization: 85-95% reduction through pre-warming and binary optimization
• cargo-lambda integration: Direct deployment to AWS Lambda with optimized builds
• Event type mappings: Automatic Python-to-Rust type conversion for all AWS events
• Performance monitoring: Built-in cold start tracking and memory profiling

🤖 AI Integration

• Model Context Protocol (MCP): Full MCP v1 specification implementation
• AI-powered transpilation: Advanced code analysis and migration assistance
• Intelligent fallback: MCP-based transpilation for complex Python constructs
• Migration complexity analysis: Deep project analysis with migration strategies

🎮 Interactive Playground (🧪 EXPERIMENTAL - UNSTABLE)

⚠️ WARNING: The Interactive Playground is currently EXPERIMENTAL and UNSTABLE. It is not recommended for production use. Features may change or break without notice.

• WebAssembly playground: Zero-configuration browser-based transpiler
• Live transpilation: Real-time Python to Rust conversion as you type
• Energy visualization: See energy savings in real-time
• Annotation suggestions: AI-powered optimization hints

Note: Use DEPYLER_EXPERIMENTAL=true depyler playground to acknowledge the experimental status.

---

🚀 Installation

Quick Install (Recommended)

Linux/macOS

curl -sSfL https://github.com/paiml/depyler/releases/latest/download/install.sh | sh

This will install depyler to ~/.local/bin. Make sure this directory is in your PATH:

export PATH="$HOME/.local/bin:$PATH"

Windows

iwr -useb https://github.com/paiml/depyler/releases/latest/download/install.ps1 | iex

Manual Installation

Download the latest release for your platform:

Platform	Download	Size
Linux (x64)	depyler-linux-amd64.tar.gz	~4.5MB
Linux (ARM64)	depyler-linux-arm64.tar.gz	~4.3MB
macOS (Intel)	depyler-darwin-amd64.tar.gz	~4.6MB
macOS (Apple Silicon)	depyler-darwin-arm64.tar.gz	~4.4MB
Windows (x64)	depyler-windows-amd64.zip	~4.8MB

Extract and add to your PATH:

tar xzf depyler-*.tar.gz
sudo mv depyler /usr/local/bin/

Build from Source

# Prerequisites
# - Rust 1.70+ (install from https://rustup.rs)
# - Python 3.8+ (for testing)

# Clone repository
git clone https://github.com/paiml/depyler.git
cd depyler

# Quick start with Makefile
make quickstart           # Builds and tests everything

# Or manually:
cargo build --release
cargo install --path crates/depyler

# Verify installation
depyler --version

Using the Makefile

Depyler includes a comprehensive Makefile for all common tasks:

# Quick start commands
make quickstart              # Build and test everything
make playground-quickstart   # Start the interactive playground

# Building
make build                   # Build release binary
make build-dev              # Build debug binary
make clean                  # Clean build artifacts

# Testing
make test                   # Run fast tests with coverage
make test-comprehensive     # Run all tests
make bench                  # Run benchmarks

# Playground (v0.3.0+)
make playground             # Build and run playground
make playground-dev         # Run playground in dev mode
make playground-test        # Test playground

# Quality
make lint                   # Run linter
make fmt                    # Format code
make coverage               # Generate coverage report
make validate               # Full validation pipeline

# Help
make help                   # Show all available commands

Interactive Playground (v0.3.0+)

# Quick start the playground
make playground-quickstart

# Or step by step:
make playground-build       # Build WASM module and frontend
make playground-run         # Start the server

# Development mode
make playground-dev         # Hot reload enabled

# Opens browser at http://localhost:5173
# Features:
# - Live transpilation as you type
# - Energy savings visualization  
# - PMAT quality scoring
# - Side-by-side Python/Rust comparison
# - WebAssembly-powered transpilation

---

📊 Supported Python Features

✅ Fully Supported

Feature	Python Example	Notes
Basic Types	int, float, str, bool, None	Direct mapping to Rust types
Collections	List[T], Dict[K,V], Set[T], Tuple[...]	Maps to Vec, HashMap, HashSet, tuples
Functions	def func(a: int) -> int:	Type annotations required
Control Flow	if/elif/else, while, for	Full support with pattern matching
Operators	+, -, *, /, %, **, //	Including augmented assignments
Comparisons	==, !=, <, >, <=, >=	Type-safe comparisons
Boolean Logic	and, or, not	Short-circuit evaluation
String Operations	f-strings, concatenation, slicing	Efficient Rust string handling
List Comprehensions	[x*2 for x in items if x > 0]	Optimized to iterators
Dict Comprehensions	{k: v*2 for k, v in data.items()}	Efficient HashMap construction
Optional Types	Optional[T], `T	None`
Type Unions	Union[int, str]	Limited support via enums
Classes	Basic classes with methods	No inheritance yet
Dataclasses	@dataclass decorators	Converts to Rust structs
Pattern Matching	match statements (3.10+)	Native Rust pattern matching
Context Managers	with statements	RAII pattern conversion
Exceptions	try/except/finally	Converts to Result<T, E>
Lambdas	Simple lambda expressions	Limited to single expressions
Annotations	# @depyler: comments	Transpilation guidance

⚠️ Partially Supported

Feature	Limitation	Workaround
Async/Await	Basic support only	Use sync versions or MCP fallback
Generators	Simple yields only	Convert to iterators manually
Decorators	Limited set supported	Use annotations instead
Multiple Inheritance	Not supported	Use composition
Dynamic Attributes	Not supported	Define all attributes upfront
Metaclasses	Not supported	Use code generation

❌ Not Supported

Feature	Reason	Alternative
eval()/exec()	Security & type safety	Redesign without dynamic execution
globals()/locals()	No runtime reflection	Use explicit passing
__getattr__	Dynamic dispatch	Use explicit methods
Monkey patching	Type safety violation	Use proper inheritance
C Extensions	Binary incompatibility	Rewrite in Rust or use PyO3
Multiple dispatch	Complex type resolution	Use pattern matching

---

🎯 Quick Examples

Basic Function Transpilation

# input.py
def calculate_fibonacci(n: int) -> int:
    """Calculate nth Fibonacci number."""
    if n <= 1:
        return n
    return calculate_fibonacci(n - 1) + calculate_fibonacci(n - 2)

# Transpile to Rust
depyler transpile input.py

// output.rs
/// Calculate nth Fibonacci number.
pub fn calculate_fibonacci(n: i32) -> i32 {
    if n <= 1 {
        return n;
    }
    calculate_fibonacci(n - 1) + calculate_fibonacci(n - 2)
}

Using Annotations for Optimization

# matrix.py
# @depyler: optimization_level = "aggressive"
# @depyler: bounds_checking = "disabled"
def matrix_multiply(a: List[List[float]], b: List[List[float]]) -> List[List[float]]:
    """Multiply two matrices."""
    # @depyler: vectorize = true
    rows_a, cols_a = len(a), len(a[0])
    cols_b = len(b[0])
    result = [[0.0] * cols_b for _ in range(rows_a)]
    
    for i in range(rows_a):
        for j in range(cols_b):
            for k in range(cols_a):
                result[i][j] += a[i][k] * b[k][j]
    
    return result

AWS Lambda Transpilation

# lambda_handler.py
import json

def lambda_handler(event, context):
    """Process S3 upload events."""
    for record in event['Records']:
        bucket = record['s3']['bucket']['name']
        key = record['s3']['object']['key']
        print(f"Processing {key} from {bucket}")
    
    return {
        'statusCode': 200,
        'body': json.dumps('Success')
    }

# Convert to Rust Lambda
depyler lambda convert lambda_handler.py --optimize

# Deploy to AWS
cd lambda_handler_lambda/
cargo lambda deploy --iam-role arn:aws:iam::123456789012:role/lambda-role

---

🎮 Interactive Usage

Command Line Interface

# Basic commands
depyler --help                    # Show all available commands
depyler transpile --help          # Help for transpile command
depyler --version                 # Show version information

# File operations
depyler transpile input.py        # Output to input.rs
depyler transpile input.py -o custom.rs  # Custom output name
depyler transpile src/ -o target/ # Directory transpilation

# Analysis and inspection
depyler check input.py            # Compatibility check
depyler analyze input.py          # Complexity analysis
depyler inspect input.py --repr hir  # View internal representation

# Quality and verification
depyler quality-check input.py    # Run quality gates
depyler verify output.rs          # Verify generated code
depyler benchmark input.py        # Performance comparison

# Interactive mode
depyler interactive input.py      # Interactive session
depyler interactive input.py --annotate  # With suggestions

# AWS Lambda commands
depyler lambda analyze handler.py   # Infer AWS event type
depyler lambda convert handler.py   # Convert to Rust Lambda
depyler lambda test lambda_project/ # Test with cargo-lambda
depyler lambda build lambda_project/  # Build optimized binary
depyler lambda deploy lambda_project/ # Deploy to AWS

Real-World Usage Patterns

Pattern 1: Development Workflow

# 1. Write Python code with type hints
vim my_algorithm.py

# 2. Check compatibility 
depyler check my_algorithm.py

# 3. Get annotation suggestions
depyler interactive my_algorithm.py --annotate

# 4. Apply annotations and transpile
depyler transpile my_algorithm.py --verify

# 5. Compile and test
rustc my_algorithm.rs -O
./my_algorithm

Pattern 2: CI/CD Integration

# .github/workflows/python-to-rust.yml
name: Python to Rust Migration
on: [push, pull_request]

jobs:
  transpile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Depyler
        run: curl -sSfL https://github.com/paiml/depyler/releases/latest/download/install.sh | sh
      - name: Transpile Python to Rust
        run: |
          depyler quality-check src/ --enforce
          depyler transpile src/ -o rust_src/
          cd rust_src && cargo test

---

📈 Quality Metrics & Test Coverage

Current Status (v0.2.0)

Metric	Value	Target	Status
Test Coverage	85%+	≥85%	✅
PMAT TDG Score	1.03	1.0-2.0	✅
Cyclomatic Complexity	4	≤20	✅
Documentation Coverage	100%	100%	✅
Clippy Warnings	0	0	✅
Security Vulnerabilities	0	0	✅

Test Suite

# Run full test suite
cargo test --workspace

# Run with coverage
cargo tarpaulin --out Html --output-dir coverage

# Run property-based tests
cargo test --features quickcheck

# Run integration tests
cargo test --test '*' --features integration

# Run benchmarks
cargo bench

Quality Gates

All pull requests must pass:

• ✅ 85%+ test coverage across all modules
• ✅ PMAT TDG score between 1.0 and 2.0
• ✅ No cyclomatic complexity above 15
• ✅ All clippy lints resolved
• ✅ Generated Rust code compiles without warnings
• ✅ Property tests pass (semantic equivalence)

---

📚 Documentation

Getting Started

• User Guide - Complete tutorial from installation to advanced usage
• Migration Guide - Step-by-step Python to Rust transition guide
• Playground Guide - Interactive playground documentation
• Examples - Working examples of transpiled code

Technical Reference

• Python-to-Rust Specification - Complete language mapping reference
• Annotation Syntax - Depyler annotation protocol documentation
• CLI Reference - Complete command-line interface documentation
• API Documentation - Rust API documentation

Advanced Topics

• Safety Guarantees - Memory and thread safety analysis
• Performance Benchmarks - Detailed performance comparisons
• Energy Efficiency Analysis - Environmental impact study
• MCP Integration - AI-powered transpilation with Model Context Protocol

AWS Lambda

• Lambda Transpilation Guide - Complete Lambda migration guide
• Lambda Examples - S3 trigger Lambda examples
• Cold Start Optimization - Performance tuning guide

Enterprise Resources

• Adoption Guide - Enterprise deployment strategies
• ROI Calculator - Calculate your cost and energy savings
• Case Studies - Real-world success stories

---

🤝 Contributing

We welcome contributions! Depyler follows the Toyota Way principles for quality-driven development.

Getting Started

1. Fork and clone the repository:

   git clone https://github.com/yourusername/depyler.git
   cd depyler

2. Read development guidelines:

   • CLAUDE.md - Core development principles
   • ROADMAP.md - Current priorities and future plans
   • docs/v02-spec.md - Technical specification

3. Set up development environment:

   # Install Rust toolchain
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   rustup component add clippy rustfmt
   
   # Install development tools
   cargo install cargo-tarpaulin cargo-audit cargo-outdated
   
   # Run initial build and tests
   cargo build
   cargo test

4. Create feature branch:

   git checkout -b feature/your-feature-name

5. Implement changes following quality standards:

   • Write tests first (TDD)
   • Ensure 85%+ coverage for new code
   • Run cargo clippy and fix all warnings
   • Run cargo fmt for consistent formatting
   • Update documentation as needed

6. Run comprehensive tests:

   # Full test suite
   cargo test --workspace --all-features
   
   # Check code quality
   cargo clippy -- -D warnings
   cargo fmt -- --check
   
   # Run property tests
   cargo test --features quickcheck
   
   # Generate coverage report
   cargo tarpaulin --out Html

7. Submit pull request with:

   • Clear description of changes
   • Link to related issues
   • Test results and coverage report
   • Any breaking changes noted

Priority Areas

1. Python Feature Coverage - Expanding supported Python constructs
2. Performance Optimization - Improving transpilation speed and output quality
3. Error Messages - Making errors more helpful and actionable
4. Documentation - Examples, tutorials, and guides
5. IDE Integration - VS Code and PyCharm extensions
6. Verification Properties - Expanding safety guarantees

Development Philosophy

• 自働化 (Jidoka) - Build quality in, never ship broken code
• 現地現物 (Genchi Genbutsu) - Test against real Python projects
• 改善 (Kaizen) - Continuous small improvements
• 反省 (Hansei) - Learn from every bug and failure

Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please:

• Be respectful and constructive in discussions
• Focus on what is best for the community
• Show empathy towards other community members
• Follow the Rust Code of Conduct

---

📜 License

Depyler is dual-licensed under the MIT License - see the LICENSE file for details.

This project includes code from:

• RustPython Parser (MIT License)
• Various Rust crates (see Cargo.toml for full list)

---

🚀 Start Transpiling Today!

# Install Depyler
curl -sSfL https://github.com/paiml/depyler/releases/latest/download/install.sh | sh

# Transpile your first Python file
depyler transpile my_script.py

# See the energy savings!
depyler analyze my_script.py --compare

"The best time to plant a tree was 20 years ago. The second best time is now."
The best time to optimize your code's energy consumption is now. 🌱

---

Report Bug • Request Feature • Join Discussion