Depyler API Documentation

Core Library API

depyler-core

The core transpilation engine providing Python AST to Rust HIR conversion.

DepylerPipeline

Main transpilation pipeline orchestrating the conversion process.

use depyler_core::DepylerPipeline;

let pipeline = DepylerPipeline::new();
let rust_code = pipeline.transpile(python_source)?;

Methods:

• new() -> Self - Create new pipeline with default configuration
• transpile(&self, source: &str) -> Result<String> - Transpile Python source to Rust
• transpile_with_options(&self, source: &str, options: TranspileOptions) -> Result<String> - Transpile with custom options
• verify(&self, rust_code: &str) -> Result<VerificationResult> - Verify generated Rust code

TranspileOptions

Configuration for transpilation behavior.

use depyler_core::TranspileOptions;

let options = TranspileOptions::builder()
    .verification_level(VerificationLevel::Strict)
    .optimize_level(OptimizeLevel::Release)
    .target_edition(Edition::Rust2021)
    .build();

Fields:

• verification_level: VerificationLevel - Verification strictness (None, Basic, Strict)
• optimize_level: OptimizeLevel - Optimization level (Debug, Release, Size)
• target_edition: Edition - Target Rust edition
• preserve_comments: bool - Preserve Python comments in output
• generate_tests: bool - Generate test modules for functions

depyler-hir

High-level Intermediate Representation for Python-to-Rust conversion.

HirModule

Root HIR structure representing a Python module.

use depyler_hir::{HirModule, HirFunction, HirClass};

let module = HirModule {
    name: "my_module".to_string(),
    imports: vec![],
    functions: vec![function],
    classes: vec![],
    globals: vec![],
};

HirFunction

HIR representation of a Python function.

use depyler_hir::{HirFunction, HirParam, Type};

let function = HirFunction {
    name: "calculate".to_string(),
    params: vec![
        HirParam {
            name: "x".to_string(),
            ty: Type::Int,
            default: None,
        }
    ],
    ret_type: Type::Int,
    body: HirBlock { statements: vec![] },
    properties: FunctionProperties::default(),
};

Type

Type system for HIR nodes.

use depyler_hir::Type;

// Basic types
Type::Int           // i64
Type::Float         // f64
Type::String        // String
Type::Bool          // bool
Type::Unit          // ()

// Container types
Type::List(Box::new(Type::Int))              // Vec<i64>
Type::Dict(Box::new(Type::String), Box::new(Type::Int))  // HashMap<String, i64>
Type::Option(Box::new(Type::String))          // Option<String>
Type::Result(Box::new(Type::Int), Box::new(Type::String)) // Result<i64, String>

depyler-analyzer

Static analysis and type inference for Python code.

Analyzer

Performs static analysis on Python AST.

use depyler_analyzer::{Analyzer, AnalysisResult};

let analyzer = Analyzer::new();
let result = analyzer.analyze(python_ast)?;

// Access inferred types
let var_type = result.get_type("variable_name");

// Check for errors
for error in result.errors() {
    println!("Analysis error: {}", error);
}

TypeInferencer

Type inference engine for Python code.

use depyler_analyzer::TypeInferencer;

let mut inferencer = TypeInferencer::new();
inferencer.add_annotation("x", Type::Int);
let inferred = inferencer.infer_expr(expr)?;

depyler-verify

Property verification for generated Rust code.

PropertyVerifier

Verifies safety properties of generated code.

use depyler_verify::{PropertyVerifier, Property};

let verifier = PropertyVerifier::new();
let properties = vec![
    Property::NoUseAfterFree,
    Property::NoDataRaces,
    Property::BorrowCheckerCompliant,
];

let result = verifier.verify_properties(&hir_module, &properties)?;
if result.is_safe() {
    println!("All properties verified!");
}

VerificationLevel

Strictness levels for verification.

use depyler_verify::VerificationLevel;

VerificationLevel::None    // Skip verification
VerificationLevel::Basic   // Type checking only
VerificationLevel::Strict  // Full property verification

Agent Mode API

depyler-agent

Background daemon for continuous transpilation.

Agent

Main agent controller.

use depyler_agent::{Agent, AgentConfig};

let config = AgentConfig::default();
let agent = Agent::new(config)?;

// Start agent
agent.start().await?;

// Add project to monitor
agent.add_project("/path/to/project", vec!["**/*.py"]).await?;

// Get status
let status = agent.status().await?;

// Stop agent
agent.stop().await?;

AgentConfig

Agent configuration structure.

use depyler_agent::AgentConfig;

let config = AgentConfig {
    port: 3000,
    host: "127.0.0.1".to_string(),
    auto_transpile: true,
    watch_debounce: Duration::from_millis(500),
    max_workers: 4,
    log_level: "info".to_string(),
};

depyler-mcp

Model Context Protocol server implementation.

McpServer

MCP server for Claude Code integration.

use depyler_mcp::{McpServer, McpTool};

let server = McpServer::new(agent)?;

// Register tools
server.register_tool(McpTool::TranspilePythonFile);
server.register_tool(McpTool::MonitorPythonProject);

// Start server
server.listen("127.0.0.1:3000").await?;

MCP Tools

Available MCP tools for transpilation operations.

use depyler_mcp::tools::*;

// Transpile single file
let result = transpile_python_file(TranspileFileRequest {
    file_path: "/path/to/file.py".to_string(),
    verify: true,
    optimize: false,
}).await?;

// Monitor project
let result = monitor_python_project(MonitorProjectRequest {
    project_path: "/path/to/project".to_string(),
    patterns: vec!["**/*.py".to_string()],
    auto_transpile: true,
}).await?;

// Get status
let status = get_transpilation_status(StatusRequest {
    project_path: Some("/path/to/project".to_string()),
}).await?;

// Verify Rust code
let result = verify_rust_code(VerifyRequest {
    rust_code: generated_code,
    level: VerificationLevel::Strict,
}).await?;

// Analyze compatibility
let result = analyze_python_compatibility(AnalyzeRequest {
    file_path: "/path/to/file.py".to_string(),
}).await?;

CLI API

Command Line Interface

# Core transpilation
depyler transpile <file.py> [options]
  --output, -o <file.rs>    Output file (default: stdout)
  --verify                   Enable verification
  --optimize                 Enable optimizations
  --quiet, -q               Suppress output

# Agent commands
depyler agent start [options]
  --port <port>             Server port (default: 3000)
  --foreground              Run in foreground
  --debug                   Enable debug logging

depyler agent stop
depyler agent status
depyler agent restart

depyler agent add-project <path> [options]
  --patterns <patterns>     File patterns to watch
  --auto                    Enable auto-transpilation

depyler agent remove-project <path>
depyler agent list-projects

# Utility commands
depyler analyze <file.py>    Analyze Python compatibility
depyler verify <file.rs>     Verify Rust code
depyler version              Show version information

Error Types

TranspileError

Main error type for transpilation failures.

use depyler_core::TranspileError;

match pipeline.transpile(source) {
    Ok(rust_code) => println!("{}", rust_code),
    Err(TranspileError::UnsupportedFeature(feature)) => {
        eprintln!("Unsupported Python feature: {}", feature);
    }
    Err(TranspileError::TypeError(msg)) => {
        eprintln!("Type error: {}", msg);
    }
    Err(e) => eprintln!("Transpilation failed: {}", e),
}

Error Variants

• TranspileError::ParseError(String) - Python parsing failed
• TranspileError::UnsupportedFeature(String) - Unsupported Python construct
• TranspileError::TypeError(String) - Type inference/checking error
• TranspileError::OwnershipError(String) - Ownership inference failed
• TranspileError::VerificationError(String) - Property verification failed
• TranspileError::IoError(std::io::Error) - File I/O error

Examples

Basic Transpilation

use depyler_core::DepylerPipeline;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let python_code = r#"
def fibonacci(n: int) -> int:
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)
"#;

    let pipeline = DepylerPipeline::new();
    let rust_code = pipeline.transpile(python_code)?;
    
    println!("{}", rust_code);
    Ok(())
}

Agent Integration

use depyler_agent::{Agent, AgentConfig};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = AgentConfig {
        port: 3000,
        auto_transpile: true,
        watch_debounce: Duration::from_millis(500),
        ..Default::default()
    };

    let agent = Agent::new(config)?;
    agent.start().await?;

    // Monitor Python project
    agent.add_project(
        "/home/user/my_python_project",
        vec!["**/*.py", "!**/__pycache__/**"]
    ).await?;

    // Keep running
    tokio::signal::ctrl_c().await?;
    agent.stop().await?;
    
    Ok(())
}

Custom Verification

use depyler_verify::{PropertyVerifier, Property};
use depyler_hir::HirModule;

fn verify_module(module: &HirModule) -> Result<(), Box<dyn std::error::Error>> {
    let verifier = PropertyVerifier::new();
    
    let properties = vec![
        Property::NoUseAfterFree,
        Property::NoDataRaces,
        Property::BorrowCheckerCompliant,
        Property::NoMemoryLeaks,
    ];

    let result = verifier.verify_properties(module, &properties)?;
    
    for violation in result.violations() {
        eprintln!("Property violation: {}", violation);
    }

    if result.is_safe() {
        println!("Module verified as safe!");
    }

    Ok(())
}

Performance Considerations

Transpilation Performance

• Throughput: >10MB/s for typical Python code
• Memory: O(n) where n is source size
• Parallelization: Multiple files transpiled concurrently

Agent Performance

• File watching: Uses efficient OS-specific APIs (inotify/FSEvents/ReadDirectoryChangesW)
• Debouncing: Configurable delay to batch rapid changes
• Worker pool: Configurable number of transpilation workers

Optimization Tips

1. Use type annotations - Reduces inference overhead
2. Enable caching - Agent caches transpilation results
3. Tune debounce interval - Balance responsiveness vs CPU usage
4. Selective monitoring - Use specific file patterns
5. Batch operations - Process multiple files together

Thread Safety

All public APIs are thread-safe and can be used from multiple threads:

• DepylerPipeline - Immutable, safe to share
• Agent - Uses Arc<Mutex<>> internally
• McpServer - Async-safe with Tokio
• PropertyVerifier - Stateless, safe to share

Version Compatibility

• Rust: 1.70.0 or later required
• Python: Targets Python 3.8+ syntax
• MCP: Compatible with MCP 1.0 specification
• Claude Code: Tested with Claude Desktop 1.0+

---

For more examples and detailed usage, see the examples directory in the repository.