⚠️ WARNING: ALPHA STATUS⚠️ This framework is under active development and is NOT recommended for production use.
- API may change without notice
- No stability guarantees
- Missing critical production features
- Use at your own risk
A modern web framework for Python inspired by FastAPI and Django, designed for high-performance enterprise applications with a focus on Developer Experience (DX).
# Install TurboAPI
pip install turboapi
# Or with uv (recommended)
uv add turboapi# Create a new project
framework new my-project
cd my-project
# Create your first app
framework new-app users
# Run the development server
framework run# apps/users/api.py
from turboapi.web import Controller, Get, Post
from turboapi.security import Authenticate, RequireRole
@Controller("/users")
class UserController:
@Get("/")
async def list_users(self) -> dict:
return {"users": []}
@Post("/")
@Authenticate()
@RequireRole("admin")
async def create_user(self, user_data: dict) -> dict:
return {"message": "User created", "user": user_data}Our documentation is organized in modular sections for easy navigation:
- Product Requirements Document (PRD) - Product vision and requirements
- Technical Design Document (DDT) - Technical architecture and decisions
- Development Roadmap - Development plan and progress
- Quick Start Guide - Installation and first project
- Examples - Practical usage examples
- API Reference - Complete API documentation
- Core System - Dependency injection and configuration
- Web Layer - FastAPI integration and routing
- Data Layer - Database and repository pattern
- Security System - Authentication and authorization
- Observability System - Logging, metrics, and tracing
- Cache System - Caching strategies and decorators
- Task System - Background task processing
- Addons System - Extending the framework
- CLI Tools - Command-line interface
- Troubleshooting - Common issues and solutions
- 🔧 Dependency Injection - Robust and flexible DI container
- ⚙️ Centralized Configuration - Based on
pyproject.toml - 🔍 Automatic Discovery - Intelligent component scanning
- 🌐 Web Decorators - Controllers and endpoints with FastAPI
- 💾 Data Layer - SQLAlchemy with Alembic migrations
- ⚡ Task System - Background task queue
- 🗄️ Cache System - Synchronous, asynchronous and hybrid caching
- 🖥️ CLI Tools - Project and application generation
- 🔑 JWT Authentication - Access and refresh tokens
- 🛡️ Security Middleware - CORS, rate limiting, security headers
- 🎭 RBAC Authorization - Role-based access control
- 🔒 Session Management - Granular session control
- 🔌 OAuth2 Addons - Google, GitHub, Microsoft integration
- 📝 Structured Logging - With
structlogand advanced configuration - 📈 Unified Metrics - OpenTelemetry with Prometheus export
- 🔍 Distributed Tracing - Complete OpenTelemetry integration
- ❤️ Health Checks - Diagnostic endpoints with Pydantic models
- 🔌 APM Addons - New Relic, DataDog, Elastic APM as separate addons
- 📦 Addon System - Modular extensions for APM and OAuth2
- 🎯 Plugin Architecture - Easy integration of third-party services
- ⚙️ Configuration Driven - Enable features through configuration
TurboAPI follows a modular architecture with clear separation of concerns:
src/turboapi/
├── core/ # DI, configuration, discovery
├── web/ # FastAPI integration, routing
├── data/ # Database, migrations, repositories
├── security/ # Authentication, authorization, middleware
├── observability/ # Logging, metrics, tracing, health checks
├── cache/ # Caching system and decorators
├── tasks/ # Background task processing
└── cli/ # Command-line tools
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=src/turboapi
# Run specific test categories
uv run pytest tests/test_security/
uv run pytest tests/test_observability/# Clone the repository
git clone https://github.com/alexmarco/turboapi.git
cd turboapi
# Install dependencies
uv sync
# Run tests
uv run pytest
# Run linting
uv run ruff format .
uv run ruff check . --fix
uv run mypy .Before committing, ensure all quality gates pass:
# 1. Format code
uv run ruff format .
# 2. Fix linting issues
uv run ruff check . --fix
# 3. Type checking
uv run mypy .
# 4. Run tests
uv run pytest- Core Framework (DI, Configuration, Discovery)
- Web Layer (FastAPI Integration, Routing)
- Data Layer (SQLAlchemy, Migrations, Repositories)
- CLI Tools (Project Generation, Commands)
- Task System (Background Processing)
- Cache System (Synchronous, Asynchronous, Hybrid)
- Security System (JWT, RBAC, Middleware, OAuth2)
- Observability System (Logging, Metrics, Tracing, Health Checks)
- Documentation System (Modular Documentation)
- Performance Optimizations
- Advanced Development Tools
- Cloud Integrations (AWS, GCP, Azure)
- Deployment Tools (Docker, Kubernetes)
- Plugin Ecosystem
We welcome contributions! Please see our Contributing Guidelines for details.
- Fork the repository
- Create a feature branch
- Make your changes
- Run quality gates
- Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
- FastAPI - For the excellent web framework foundation
- Django - For architectural inspiration
- Spring Boot - For the developer experience philosophy
- OpenTelemetry - For the observability standards
- 📖 Documentation - Comprehensive guides and references
- 🐛 Issues - Report bugs and request features
- 💬 Discussions - Community discussions
- 📧 Contact - Direct contact for questions
<<<<<<< HEAD
