dukpyra 0.3.0
Python → C# Backend Framework Compiler with Runtime Type Collection
Requires Python: >=3.8
Keywords: compiler, transpiler, python, csharp, aspnet, backend, framework, research

# 🚀 Dukpyra

**Python → C# Backend Framework Compiler**

Build blazing-fast ASP.NET Core APIs using Python syntax. Dukpyra compiles your Python web routes into production-ready C# code with zero runtime overhead.

```python
# Write Python
@app.get("/users/{id}")
def get_user(id: int):
    return {"id": id, "name": "John Doe"}
```

```csharp
// Get C# automatically
app.MapGet("/users/{id}", (int id) =>
{
    return Results.Ok(new { id = id, name = "John Doe" });
});
```

---

## ✨ Features

- 🎯 **Write Python, Run C#** - Best of both worlds
- ⚡ **Zero Overhead** - Compiled to native C#, no runtime interpreter
- 🔥 **Hot Reload** - Watch mode for instant recompilation
- 🧠 **Runtime Type Collection** - AI-powered type inference from real requests
- 🎨 **Beautiful CLI** - Framework-style developer experience
- 📦 **Hidden Artifacts** - Clean projects, only Python visible
- 🔬 **Research-Based** - Implements academic transpilation techniques

---

## 🎬 Quick Start

### Installation

```bash
pip install dukpyra
```

### Create a New Project

```bash
dukpyra init my-api
cd my-api
```

**Your project:**
```
my-api/
├── main.py          # Your Python routes
├── README.md
└── .dukpyra/        # Hidden C# artifacts
```

### Run Your API

```bash
dukpyra run
```

**You'll see:**
```
╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║   ██████╗ ██╗   ██╗██╗  ██╗██████╗ ██╗   ██╗██████╗  █████╗  ║
║   ██╔══██╗██║   ██║██║ ██╔╝██╔══██╗╚██╗ ██╔╝██╔══██╗██╔══██╗ ║
║   ██║  ██║██║   ██║█████╔╝ ██████╔╝ ╚████╔╝ ██████╔╝███████║ ║
║   ██║  ██║██║   ██║██╔═██╗ ██╔═══╝   ╚██╔╝  ██╔══██╗██╔══██║ ║
║   ██████╔╝╚██████╔╝██║  ██╗██║        ██║   ██║  ██║██║  ██║ ║
║   ╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚═╝        ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝ ║
║                                                               ║
║         Python → C# Backend Framework Compiler               ║
║                    v0.3.0 Research                            ║
╚═══════════════════════════════════════════════════════════════╝

✅ Compiled 1 module(s)

🚀 Starting Production Server
╔═══════════════════════════════════════════════════════════════╗
║  ✅ Server Online                                             ║
║  🌐 http://localhost:5000                                    ║
║  ⚡ Compiled with Dukpyra v0.3.0                              ║
╚═══════════════════════════════════════════════════════════════╝
```

---

## 📖 Example

**`main.py`:**
```python
import dukpyra
app = dukpyra.app()

@app.get("/")
def home():
    return {"message": "Hello from Dukpyra!", "version": "1.0"}

@app.get("/users/{id}")
def get_user(id: int):
    return {"id": id, "name": "John Doe", "active": True}

@app.post("/api/users")
def create_user():
    return {"id": 1, "created": True}
```

**Run it:**
```bash
dukpyra run
```

**Visit:** http://localhost:5000

---

## 🎯 Commands

| Command | Description |
|---------|-------------|
| `dukpyra init [name]` | Create a new project |
| `dukpyra run` | Compile & run with hot reload |
| `dukpyra run --no-watch` | Compile & run once |
| `dukpyra run --port 8000` | Run on custom port |
| `dukpyra profile` | Start profiling server (runtime type collection) |
| `dukpyra show` | View compiled C# code |
| `dukpyra clean` | Clean compiled artifacts |
| `dukpyra build` | Build production binary |

---

## 🔬 Runtime Type Collection

Dukpyra uses **runtime profiling** to infer types from actual HTTP requests, inspired by academic research on transpilation.

**How it works:**
1. Run profiling server: `dukpyra profile`
2. Send test requests to your API
3. Dukpyra observes actual values and infers types
4. Types saved to `.dukpyra/types.json`
5. Next compilation uses runtime data for better C# code

**Example:**
```bash
# Start profiling
dukpyra profile --port 8000

# In another terminal - send requests
curl http://localhost:8000/users/42
curl http://localhost:8000/users/123

# Types collected: user_id = int (from values 42, 123)
```

**Research:** Based on [6] Krivanek & Uttner - "Runtime type collecting and transpilation to a static language"

---

## 🏗️ Architecture

```
Python Source
    ↓
┌──────────────────────┐
│  Scanner             │  1. Lexical Analysis (scanner.py)
└──────────┬───────────┘
           ↓
┌──────────────────────┐
│  Parser              │  2. Syntax Analysis (parser.py)
└──────────┬───────────┘
           ↓
┌──────────────────────┐
│  Semantic Analyzer   │  3. Semantic Analysis (semantic_analyzer.py)
└──────────┬───────────┘
           ↓
┌──────────────────────┐
│  Code Generator      │  4. Target Code Generation (code_generator.py)
└──────────┬───────────┘
           ↓
C# ASP.NET Core
    ↓
dotnet build
    ↓
Production Binary (.dll)
```

---

## 📁 Project Structure

```
dukpyra-compiler/
├── dukpyra/                      # Core Compiler
│   ├── scanner.py                # 1️⃣ Scanner (Lexical Analysis)
│   ├── parser.py                 # 2️⃣ Parser (Syntax Analysis)
│   ├── ast.py                    # AST Node Definitions
│   ├── semantic_analyzer.py      # 3️⃣ Semantic Analyzer
│   ├── code_generator.py         # 4️⃣ Code Generator
│   ├── runtime.py                # Runtime Type Profiler
│   ├── cli.py                    # CLI Commands
│   ├── templates/                # Jinja2 Templates
│   └── __init__.py               # Package Entry Point
├── tests/                        # Unit Tests
│   ├── test_scanner.py
│   ├── test_parser.py
│   ├── test_semantic_analyzer.py
│   ├── test_code_generator.py
│   └── ...
├── examples/                     # Example APIs
├── setup.py                      # Package Setup
├── requirements.txt              # Dependencies
└── README.md
```

**Compiler:** ~2,780 lines of Python
**Test Coverage:** ~85%

---

## 🎨 Features in Detail

### Supported Syntax

**HTTP Methods:**
```python
@app.get("/path")       # GET
@app.post("/path")      # POST
@app.put("/path")       # PUT
@app.delete("/path")    # DELETE
@app.patch("/path")     # PATCH
```

**Path Parameters:**
```python
@app.get("/users/{user_id}/posts/{post_id}")
def get_user_post(user_id: int, post_id: int):
    return {"user_id": user_id, "post_id": post_id}
```

**Data Models:**
```python
class User:
    id: int
    name: str
    email: str

@app.post("/api/users")
def create_user(user: User):
    return {"id": user.id, "created": True}
```

**List Comprehensions → LINQ:**
```python
@app.get("/api/squares")
def get_squares():
    return {"squares": [x * x for x in [1, 2, 3, 4, 5]]}

# Compiles to:
# new[] { 1, 2, 3, 4, 5 }.Select(x => x * x).ToList()
```

---

## 📦 What You Get

**Python Files:**
- `main.py` - Your routes
- `models.py` - Data models  
- `.gitignore` - Ignores .dukpyra/

**Hidden Artifacts (`.dukpyra/`):**
- `compiled/Program.cs` - Generated C#
- `compiled/dukpyra.csproj` - .NET project
- `bin/` - Compiled binaries
- `types.json` - Runtime type data

**Like Elysia/Next.js** - Users only see source code, artifacts are hidden!

---

## 🔧 Requirements

- Python 3.8+
- .NET SDK 8.0+
- FastAPI + Uvicorn (optional, for runtime profiling)

**Install .NET:**
```bash
# macOS/Linux
https://dotnet.microsoft.com/download

# Check installation
dotnet --version
```

---

## 🚀 Production Deployment

**Build optimized binary:**
```bash
dukpyra build --release
```

**Run in production:**
```bash
cd .dukpyra/bin/Release/net8.0
dotnet dukpyra.dll
```

**Or use Docker:**
```dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:8.0
COPY .dukpyra/bin/Release/net8.0 /app
WORKDIR /app
ENTRYPOINT ["dotnet", "dukpyra.dll"]
```

---

## 🔬 Research & Academic Foundation

Dukpyra implements techniques from modern compiler research:

1. **Runtime Type Collection**  
   [6] Krivanek & Uttner - "Runtime type collecting and transpilation to a static language"

2. **User-Guided "Last Mile" Construction**  
   [4] DuoGlot (Bo Wang et al.) - Raw C# injection for complex logic

3. **Template-Based Code Generation**  
   [5] Robert Eikermann et al. - Separation of transformation logic and templates

4. **Rule-Driven AST Rewriting**  
   [1] Lachaux et al. - Accurate translation via rule-based transformation

---

## 📊 Performance

**Compilation Speed:**
- ~40 routes in ~2 seconds
- Incremental compilation with watch mode

**Runtime:**
- **Zero Python overhead** - Pure C# execution
- Native ASP.NET Core performance
- ~10x faster than Python equivalents

---

## 🤝 Contributing

Contributions welcome! This is a research project exploring transpilation techniques.

**Development:**
```bash
git clone https://github.com/yourusername/dukpyra
cd dukpyra
pip install -e .
pytest tests/
```

---

## 📄 License

MIT License

---

## 🌟 Why Dukpyra?

- **Python Simplicity + C# Performance** = Best of both worlds
- **No Runtime Overhead** - Fully compiled, not interpreted
- **Production Ready** - Generates industry-standard ASP.NET Core
- **Beautiful DX** - Framework-level developer experience
- **Research-Backed** - Academic techniques in practice

---

**Built with ❤️ by the Dukpyra Team**

*Dukpyra (ดุกพระ) - Thai word meaning "compiler/translator"*