Overview

Relevant source files

• .github/workflows/pre-release.yml
• .gitignore
• README.md
• assets/turbito.png
• python/turboapi/__init__.py
• python/turboapi/sse.py
• socials/linkedin.md
• socials/twitter.md
• tests/test_performance_regression.py
• tests/test_wrk_regression.py
• uv.lock

This document provides a high-level introduction to TurboAPI, a FastAPI-compatible Python web framework that achieves 1.3-3.1x performance improvements (and up to 7x in specific benchmarks) by replacing the Python HTTP stack with a high-performance Zig core. It explains the system's purpose, the hybrid architecture, and how performance optimization is achieved without modifying user code.

For detailed information about specific subsystems, see: Key Features and Benefits and Installation and Quick Start.

What is TurboAPI

TurboAPI is a Python web framework that maintains high API compatibility with FastAPI while replacing performance-critical components—HTTP parsing, routing, and JSON validation—with native Zig implementations. Applications written for FastAPI can often migrate by changing the main application import:

The system consists of three primary layers:

Layer	Technology	Purpose
Python Framework	Python 3.13+	Application logic, decorators, and dependency injection.
Integration Bridge	Python C-API (Zig)	Zero-copy marshaling and async handler dispatch.
Zig Core	turbonet	Multi-threaded HTTP server, Radix tree routing, and std.json parsing.

Sources: README.md14-84 python/turboapi/__init__.py1-57

Hybrid Zig/Python Architecture

TurboAPI moves the "heavy lifting" out of the Python interpreter. While FastAPI processes every request through multiple Python layers (Uvicorn → ASGI → Starlette), TurboAPI handles the entire lifecycle up to the business logic in Zig.

Request Lifecycle Diagram

The following diagram maps the request flow to concrete code entities in both Zig and Python spaces:

Sources: README.md127-164 python/turboapi/native_integration.py1-45

Layer Responsibilities

• Zig Core (turbonet): Manages an 8-thread pool, performs Radix tree route matching, and executes JSON schema validation via the dhi library before the Python GIL is even acquired README.md39-46
• Integration Bridge: Uses the Python C-API to build Python dictionaries directly from Zig-parsed JSON, bypassing json.loads() README.md40-42
• Python Framework: Provides the familiar FastAPI-style interface, including APIRouter, Depends, and security schemes like OAuth2PasswordBearer python/turboapi/__init__.py59-72

Performance Value Proposition

TurboAPI targets the overhead of the Python Global Interpreter Lock (GIL) and slow JSON processing. By using Python 3.13+ free-threading support, it enables true parallelism.

Throughput Benchmarks (req/s)

Based on wrk testing on Apple Silicon with Python 3.14t:

Endpoint	TurboAPI	FastAPI	Speedup
GET /	71,290	10,038	7.1x
GET /items/{id}	65,266	8,666	7.5x
POST /items (JSON)	59,595	8,200	7.2x

Sources: README.md90-112 tests/test_performance_regression.py6-11

Key Optimizations

1. Zero-Copy Responses: Zig calls PyUnicode_AsUTF8() to get a direct pointer to Python string data, writing it straight to the socket without intermediate allocations README.md166-171
2. Native Validation: Using dhi models (a Zig-native Pydantic replacement), validation happens in the Zig core. If a request body is invalid, a 422 error is returned without ever waking up the Python interpreter README.md113-115
3. Handler Fast Paths: At startup, TurboAPI classifies routes into types (e.g., simple_sync, model_sync, body_async). Simple routes bypass complex Python wrappers to reduce latency socials/twitter.md41-53

System Components

The following table bridges the conceptual systems to their primary code locations:

System	Code Entity	File Path
Core Application	TurboAPI class	python/turboapi/native_integration.py44
Data Models	dhi.BaseModel	python/turboapi/native_integration.py62
Routing	APIRouter / Router	python/turboapi/routing.py56
Server-Sent Events	EventSourceResponse	python/turboapi/sse.py62
Extension Build	build_turbonet.py	zig/build_turbonet.py1-50

Sources: python/turboapi/__init__.py43-81 python/turboapi/sse.py62-101

Next Steps

• For a deep dive into performance metrics and specific features like zero-copy, see Key Features and Benefits.
• To set up your environment for Python 3.13 free-threading and Zig 0.15, see Installation and Quick Start.
• For contributors, the Build System and Distribution page details the multi-platform wheel build process.