zenithweb 0.0.11

Modern Python web framework for building APIs with minimal boilerplate

Zenith Framework

A modern Python web framework with intuitive developer experience and exceptional performance.

🎯 Modern DX: Zero-config setup, database models with chainable queries, one-liner features, and clean architecture patterns - making Python web development incredibly productive.

What is Zenith?

Zenith brings together exceptional productivity, outstanding performance, and full type safety:

• 🚀 Zero-config setup - app = Zenith() just works with intelligent defaults
• 🏗️ Intuitive models - User.where(active=True).order_by('-created_at').limit(10)
• ⚡ One-liner features - app.add_auth(), app.add_admin(), app.add_api()
• 🎯 Enhanced DX - No session management, ZenithModel handles it automatically
• 🏎️ Exceptional performance - 9,600+ req/s with full async support
• 🛡️ Production-ready - Security, monitoring, and middleware built-in

🚀 Zero-Config Quick Start

pip install zenithweb

from zenith import Zenith
from zenith import Session  # Database session dependency
from zenith.db import ZenithModel  # Modern database models
from sqlmodel import Field
from pydantic import BaseModel
from typing import Optional

# 🎯 Zero-config setup - just works!
app = Zenith()

# ⚡ Add features in one line each
app.add_auth()    # JWT authentication + /auth/login
app.add_admin()   # Admin dashboard at /admin
app.add_api("My API", "1.0.0")  # API docs at /docs

# 🏗️ Modern models with chainable query patterns
class User(ZenithModel, table=True):
    id: Optional[int] = Field(primary_key=True)
    name: str = Field(max_length=100)
    email: str = Field(unique=True)
    active: bool = Field(default=True)

class UserCreate(BaseModel):
    name: str
    email: str
    active: bool = True

# 🎨 Clean routes with enhanced DX
@app.get("/")
async def home():
    return {"message": "Modern DX in Python!"}

@app.get("/users")
async def list_users():  # ✨ No session management needed!
    # Clean chaining: User.where().order_by().limit()
    users = await User.where(active=True).order_by('-id').limit(10).all()
    return {"users": [user.model_dump() for user in users]}

@app.post("/users")
async def create_user(user_data: UserCreate):
    # Clean API: User.create() - no session management!
    user = await User.create(**user_data.model_dump())
    return {"user": user.model_dump()}

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    # Automatic 404 handling
    user = await User.find_or_404(user_id)
    return {"user": user.model_dump()}

# 🏃‍♂️ Run it
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="127.0.0.1", port=8000)

Run with:

uvicorn main:app --reload

🎯 Modern DX Features

🚀 Zero-Config Setup (for Development)

app = Zenith()  # Just works! No complex configuration needed

• Intelligent defaults - Development uses SQLite, auto-generated dev keys
• Production ready - Set DATABASE_URL and SECRET_KEY env vars for production
• Automatic middleware - Security, CORS, logging configured automatically
• Environment-aware - Uses ZENITH_ENV or intelligent detection

🏗️ Intuitive Database Models

# Intuitive database operations - seamless chaining!
users = await User.where(active=True).order_by('-created_at').limit(10).all()
user = await User.find_or_404(123)  # Automatic 404 handling
user = await User.create(name="Alice", email="[e-mail]")

• ZenithModel - Modern ORM with chainable queries
• Automatic sessions - No manual database session management
• Type-safe queries - Full async support with SQLModel integration

⚡ One-Liner Features

app.add_auth()     # JWT authentication + /auth/login endpoint
app.add_admin()    # Admin dashboard at /admin with health checks
app.add_api()      # API documentation at /docs and /redoc

• Instant features - Complex functionality in single lines
• Production-ready - Each feature includes monitoring and security
• Configurable - Sensible defaults with full customization options

🎯 Clean Dependency Injection

@app.get("/users")
async def get_users(session: AsyncSession = Session):
    # Simple database session injection
    users = await User.all()  # ZenithModel uses the session automatically
    return users

• Simple patterns - Session for database, Auth for current user
• Service injection - Inject(ServiceClass) for business logic
• Type-safe - Full IDE support and autocompletion

🏎️ Exceptional Performance

• ~10,000 req/s - High performance for JSON endpoints
• ~7,000 req/s - With production middleware stack (71% retention)
• Async-first - Full async/await with Python 3.12+ optimizations
• Production tested - Benchmarked with comprehensive test suite

🛡️ Production-Ready

• Security by default - CSRF, CORS, security headers automatic
• Built-in monitoring - /health, /metrics, request tracing
• Error handling - Structured errors with proper HTTP status codes
• Testing framework - Comprehensive testing utilities included

🌐 Full-Stack Support

• Serve SPAs (React, Vue, SolidJS) with app.spa("dist")
• WebSocket support with connection management
• Static file serving with caching
• Database integration with async SQLAlchemy

📁 Project Structure

Clean organization with zero configuration:

your-app/
├── main.py         # app = Zenith() + routes
├── models.py       # ZenithModel classes
├── services.py     # Business logic (optional)
├── migrations/     # Database migrations (auto-generated)
└── tests/          # Testing with built-in TestClient

Or traditional clean architecture:

your-app/
├── main.py         # Application entry point
├── models/         # ZenithModel classes
├── services/       # Service classes with @Service decorator
├── routes/         # Route modules (optional)
├── middleware/     # Custom middleware
└── tests/          # Comprehensive test suite

Performance

Verified Benchmark Results:

• JSON endpoints: ~10,000 req/s (9,917 req/s measured)
• Simple endpoints: ~8,000 req/s (7,743 req/s measured)
• With middleware: ~7,000 req/s (71% retention, 29% overhead)

Tested on Apple M3 Max, Python 3.12, using performance test suite

Run your own benchmarks:

uv run pytest tests/performance/ -v

Performance varies by hardware, middleware configuration, and application complexity.

Documentation

• Quick Start Guide - Get up and running in 5 minutes
• API Reference - Complete API documentation
• Architecture Guide - Framework design patterns
• Examples - Real-world usage examples
• Contributing - Development guidelines

📚 Examples

🔥 Modern DX Examples:

• Modern Developer Experience - Complete modern patterns showcase
• One-Liner Features - Convenience methods demonstration
• One-liner Features - app.add_auth(), app.add_admin(), app.add_api()
• Zero-config Setup - Automatic environment detection

🚀 Complete Examples:

• Hello World - Simple setup (app = Zenith())
• Basic API - Routing and validation
• Authentication - JWT authentication
• WebSocket Chat - Real-time communication
• Background Jobs - Task processing
• Security Middleware - Production security

CLI Tools

# Create new project with secure defaults
zen new my-api

# Generate secure SECRET_KEY
zen keygen

# Show configuration and environment info
zen config --all

# Generate boilerplate code
zen generate model User
zen generate service UserService
zen generate graphql UserSchema

# Development server with hot reload
zen dev

# Production server
zen serve --workers 4

Installation

# Basic installation
pip install zenithweb

# With production dependencies
pip install "zenithweb[production]"

# With development tools
pip install "zenithweb[dev]"

Production Deployment

Docker

FROM python:3.12-slim

WORKDIR /app
COPY . .
RUN pip install "zenithweb[production]"

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Environment Configuration

from zenith import Zenith

app = Zenith()

# Environment-specific behavior:
# development (or dev): Enhanced error reporting, auto-generated secrets
# production (or prod): Optimized for deployment, requires SECRET_KEY
# test: Testing mode with rate limiting disabled
# staging: Production-like with enhanced monitoring

# Manual configuration if needed
from zenith.config import Config
app = Zenith(
    config=Config(
        database_url=os.getenv("DATABASE_URL"),
        redis_url=os.getenv("REDIS_URL"),
        secret_key=os.getenv("SECRET_KEY")
        # debug automatically set based on ZENITH_ENV
    )
)

Contributing

We welcome contributions! Please see our Contributing Guide.

git clone https://github.com/nijaru/zenith.git
cd zenith
pip install -e ".[dev]"
pytest  # Run tests

Status

Latest Version: v0.0.10 Python Support: 3.12-3.14 Test Suite: 100% passing (900 tests) Performance: ~10,000 req/s JSON endpoints, ~7,000 req/s with middleware Architecture: Clean separation with Service system and simple dependency patterns

Zenith is production-ready with comprehensive middleware, performance optimizations, and clean architecture patterns for modern Python applications.

License

MIT License. See LICENSE for details.