# Zenith Framework
[](https://badge.fury.io/py/zenith-web)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/nijaru/zenith/actions)
[](https://nijaru.github.io/zenith/)
A modern Python API framework that prioritizes clean architecture, exceptional performance, and developer experience.
> **🚀 v0.2.1 Release**: Zenith delivers production-ready performance with full Pydantic v2 compatibility and modern Service-based architecture.
## What is Zenith?
Zenith is a modern Python API framework designed for building production-ready applications with clean architecture:
- **Type-safe by design** - Full Pydantic integration with automatic validation
- **Clean architecture** - Business logic organized in Service classes, separate from web concerns
- **Zero-configuration defaults** - Production middleware, monitoring, and security built-in
- **Performance focused** - 8,000+ req/s with async-first architecture and Python optimizations
- **Full-stack ready** - Serve APIs alongside SPAs with comprehensive middleware stack
## Quick Start
```bash
pip install zenith-web
```
```python
from zenith import Zenith, Service, Inject
from pydantic import BaseModel
app = Zenith()
@app.get("/")
async def hello():
return {"message": "Hello, Zenith!"}
# Type-safe request/response models
class UserCreate(BaseModel):
name: str
email: str
class User(BaseModel):
id: int
name: str
email: str
# Business logic in Service classes
class UserService(Service):
def __init__(self):
self.users = {}
self.next_id = 1
async def create_user(self, data: UserCreate) -> User:
user = User(id=self.next_id, name=data.name, email=data.email)
self.users[self.next_id] = user
self.next_id += 1
return user
async def get_user(self, user_id: int) -> User | None:
return self.users.get(user_id)
# Clean dependency injection
@app.post("/users", response_model=User)
async def create_user(user_data: UserCreate, users: UserService = Inject()):
return await users.create_user(user_data)
@app.get("/users/{user_id}", response_model=User)
async def get_user(user_id: int, users: UserService = Inject()):
user = await users.get_user(user_id)
if not user:
raise HTTPException(404, "User not found")
return user
```
Run with:
```bash
uvicorn main:app --reload
```
## Core Features
### 🚀 **Type-Safe Development**
- Automatic request/response validation with Pydantic
- OpenAPI 3.0 documentation generation at `/docs` and `/redoc`
- IDE autocompletion and type checking
- Zero-configuration setup
### 🏗️ **Clean Architecture**
- Business logic organized in Service classes with `Inject()` injection
- Separation of web concerns from business logic
- Type-safe dependency injection without boilerplate
- Built-in support for complex application architectures
### 🔐 **Production-Ready Security**
- JWT authentication with `Auth()`
- CORS, CSRF, security headers middleware
- Rate limiting with memory and Redis backends
- Automatic request correlation IDs
### ⚡ **High Performance**
- **8,000+ req/s** on modern hardware
- **82.6% middleware retention** with full production stack
- Async-first architecture with Python 3.12+ optimizations
- Comprehensive performance monitoring built-in
### 🛠️ **Developer Experience**
- Interactive CLI with code generation: `zen generate api users`
- Built-in testing framework with `TestClient`
- Hot reload development server
- Comprehensive error handling and debugging
### 🔄 **Background Processing**
- Simple background tasks with `BackgroundTasks`
- Production job queue with Redis backend
- Cron-style scheduling: `@schedule(cron="0 9 * * *")`
- Automatic retry with exponential backoff
### 📊 **Monitoring & Observability**
- Health checks: `/health` and `/health/detailed`
- Prometheus metrics: `/metrics`
- Performance profiling decorators
- Request/response logging with structured output
### 🌐 **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
## Architecture
Zenith follows clean architecture principles:
```
your-app/
├── main.py # Application entry point
├── contexts/ # Business logic (Service classes)
├── models/ # Data models (Pydantic)
├── routes/ # API endpoints (optional - can use decorators)
├── middleware/ # Custom middleware
├── migrations/ # Database migrations
└── tests/ # Test suite
```
## Performance
**Verified Benchmark Results (v0.2.1):**
- Simple endpoints: **8,049 req/s**
- JSON endpoints: **9,469 req/s**
- With full middleware: **6,647 req/s** (82.6% retention)
Run your own benchmarks:
```bash
python scripts/run_performance_tests.py --quick
```
*Performance varies by hardware and application complexity.*
## Documentation
- **[Quick Start Guide](docs/tutorial/)** - Get up and running in 5 minutes
- **[API Reference](docs/reference/)** - Complete API documentation
- **[Architecture Guide](docs/reference/spec/ARCHITECTURE.md)** - Framework design patterns
- **[Examples](examples/)** - Real-world usage examples
- **[Contributing](docs/guides/contributing/DEVELOPER.md)** - Development guidelines
## Examples
Complete working examples in the [examples/](examples/) directory:
- [Hello World](examples/00-hello-world.py) - Basic setup
- [Service System](examples/03-context-system.py) - Business logic organization
- [Security Middleware](examples/11-security-middleware.py) - Production security setup
- [Background Jobs](examples/05-background-tasks.py) - Task processing
- [WebSocket Chat](examples/07-websocket-chat.py) - Real-time communication
- [Full Production API](examples/10-complete-production-api/) - Complete example
## CLI Tools
```bash
# Create new project
zen new my-api
# Development server with hot reload
zen server --reload
# Interactive shell with app context
zen shell
# Code generation
zen generate api users "User UserCreate UserUpdate"
zen generate model Product "name:str price:float"
# Database migrations
zen db migrate "add users table"
zen db upgrade
# Testing
zen test --coverage
```
## Installation
```bash
# Basic installation
pip install zenith-web
# With production dependencies
pip install "zenith-web[production]"
# With development tools
pip install "zenith-web[dev]"
```
## Production Deployment
### Docker
```dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install "zenith-web[production]"
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```
### Environment Configuration
```python
from zenith import Zenith
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=os.getenv("DEBUG", "false").lower() == "true"
)
)
```
## Contributing
We welcome contributions! Please see our [Contributing Guide](docs/guides/contributing/DEVELOPER.md).
```bash
git clone https://github.com/nijaru/zenith.git
cd zenith
pip install -e ".[dev]"
pytest # Run tests
```
## Status
**Current Version**: v0.2.1 (stable release)
**Python Support**: 3.12+
**Test Suite**: 100% passing (328/332 tests)
**Performance**: Production-ready with 8,000+ req/s capability
**Architecture**: Clean separation with Service system and dependency injection
Zenith is production-ready with comprehensive middleware, performance optimizations, and clean architecture patterns for modern Python applications.
## License
MIT License. See [LICENSE](LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "zenith-web",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "framework, http3, liveview, quic, realtime, web, websockets",
"author": null,
"author_email": "Nick Russo <nijaru7@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4f/ee/36e74db8e3f11ec7eeb9eea08d486099f927f9c609f3974b836cfbb92df2/zenith_web-0.2.2.tar.gz",
"platform": null,
"description": "# Zenith Framework\n\n[](https://badge.fury.io/py/zenith-web)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/nijaru/zenith/actions)\n[](https://nijaru.github.io/zenith/)\n\nA modern Python API framework that prioritizes clean architecture, exceptional performance, and developer experience.\n\n> **\ud83d\ude80 v0.2.1 Release**: Zenith delivers production-ready performance with full Pydantic v2 compatibility and modern Service-based architecture.\n\n## What is Zenith?\n\nZenith is a modern Python API framework designed for building production-ready applications with clean architecture:\n\n- **Type-safe by design** - Full Pydantic integration with automatic validation\n- **Clean architecture** - Business logic organized in Service classes, separate from web concerns\n- **Zero-configuration defaults** - Production middleware, monitoring, and security built-in\n- **Performance focused** - 8,000+ req/s with async-first architecture and Python optimizations\n- **Full-stack ready** - Serve APIs alongside SPAs with comprehensive middleware stack\n\n## Quick Start\n\n```bash\npip install zenith-web\n```\n\n```python\nfrom zenith import Zenith, Service, Inject\nfrom pydantic import BaseModel\n\napp = Zenith()\n\n@app.get(\"/\")\nasync def hello():\n return {\"message\": \"Hello, Zenith!\"}\n\n# Type-safe request/response models\nclass UserCreate(BaseModel):\n name: str\n email: str\n\nclass User(BaseModel):\n id: int\n name: str\n email: str\n\n# Business logic in Service classes\nclass UserService(Service):\n def __init__(self):\n self.users = {}\n self.next_id = 1\n \n async def create_user(self, data: UserCreate) -> User:\n user = User(id=self.next_id, name=data.name, email=data.email)\n self.users[self.next_id] = user\n self.next_id += 1\n return user\n \n async def get_user(self, user_id: int) -> User | None:\n return self.users.get(user_id)\n\n# Clean dependency injection\n@app.post(\"/users\", response_model=User)\nasync def create_user(user_data: UserCreate, users: UserService = Inject()):\n return await users.create_user(user_data)\n\n@app.get(\"/users/{user_id}\", response_model=User)\nasync def get_user(user_id: int, users: UserService = Inject()):\n user = await users.get_user(user_id)\n if not user:\n raise HTTPException(404, \"User not found\")\n return user\n```\n\nRun with:\n```bash\nuvicorn main:app --reload\n```\n\n## Core Features\n\n### \ud83d\ude80 **Type-Safe Development**\n- Automatic request/response validation with Pydantic\n- OpenAPI 3.0 documentation generation at `/docs` and `/redoc`\n- IDE autocompletion and type checking\n- Zero-configuration setup\n\n### \ud83c\udfd7\ufe0f **Clean Architecture**\n- Business logic organized in Service classes with `Inject()` injection\n- Separation of web concerns from business logic\n- Type-safe dependency injection without boilerplate\n- Built-in support for complex application architectures\n\n### \ud83d\udd10 **Production-Ready Security**\n- JWT authentication with `Auth()`\n- CORS, CSRF, security headers middleware\n- Rate limiting with memory and Redis backends\n- Automatic request correlation IDs\n\n### \u26a1 **High Performance**\n- **8,000+ req/s** on modern hardware\n- **82.6% middleware retention** with full production stack\n- Async-first architecture with Python 3.12+ optimizations\n- Comprehensive performance monitoring built-in\n\n### \ud83d\udee0\ufe0f **Developer Experience**\n- Interactive CLI with code generation: `zen generate api users`\n- Built-in testing framework with `TestClient`\n- Hot reload development server\n- Comprehensive error handling and debugging\n\n### \ud83d\udd04 **Background Processing**\n- Simple background tasks with `BackgroundTasks`\n- Production job queue with Redis backend\n- Cron-style scheduling: `@schedule(cron=\"0 9 * * *\")`\n- Automatic retry with exponential backoff\n\n### \ud83d\udcca **Monitoring & Observability**\n- Health checks: `/health` and `/health/detailed`\n- Prometheus metrics: `/metrics`\n- Performance profiling decorators\n- Request/response logging with structured output\n\n### \ud83c\udf10 **Full-Stack Support**\n- Serve SPAs (React, Vue, SolidJS) with `app.spa(\"dist\")`\n- WebSocket support with connection management\n- Static file serving with caching\n- Database integration with async SQLAlchemy\n\n## Architecture\n\nZenith follows clean architecture principles:\n\n```\nyour-app/\n\u251c\u2500\u2500 main.py # Application entry point\n\u251c\u2500\u2500 contexts/ # Business logic (Service classes)\n\u251c\u2500\u2500 models/ # Data models (Pydantic)\n\u251c\u2500\u2500 routes/ # API endpoints (optional - can use decorators)\n\u251c\u2500\u2500 middleware/ # Custom middleware\n\u251c\u2500\u2500 migrations/ # Database migrations\n\u2514\u2500\u2500 tests/ # Test suite\n```\n\n## Performance\n\n**Verified Benchmark Results (v0.2.1):**\n- Simple endpoints: **8,049 req/s**\n- JSON endpoints: **9,469 req/s** \n- With full middleware: **6,647 req/s** (82.6% retention)\n\nRun your own benchmarks:\n```bash\npython scripts/run_performance_tests.py --quick\n```\n\n*Performance varies by hardware and application complexity.*\n\n## Documentation\n\n- **[Quick Start Guide](docs/tutorial/)** - Get up and running in 5 minutes\n- **[API Reference](docs/reference/)** - Complete API documentation \n- **[Architecture Guide](docs/reference/spec/ARCHITECTURE.md)** - Framework design patterns\n- **[Examples](examples/)** - Real-world usage examples\n- **[Contributing](docs/guides/contributing/DEVELOPER.md)** - Development guidelines\n\n## Examples\n\nComplete working examples in the [examples/](examples/) directory:\n\n- [Hello World](examples/00-hello-world.py) - Basic setup\n- [Service System](examples/03-context-system.py) - Business logic organization\n- [Security Middleware](examples/11-security-middleware.py) - Production security setup\n- [Background Jobs](examples/05-background-tasks.py) - Task processing\n- [WebSocket Chat](examples/07-websocket-chat.py) - Real-time communication\n- [Full Production API](examples/10-complete-production-api/) - Complete example\n\n## CLI Tools\n\n```bash\n# Create new project\nzen new my-api\n\n# Development server with hot reload \nzen server --reload\n\n# Interactive shell with app context\nzen shell\n\n# Code generation\nzen generate api users \"User UserCreate UserUpdate\"\nzen generate model Product \"name:str price:float\"\n\n# Database migrations\nzen db migrate \"add users table\"\nzen db upgrade\n\n# Testing\nzen test --coverage\n```\n\n## Installation\n\n```bash\n# Basic installation\npip install zenith-web\n\n# With production dependencies\npip install \"zenith-web[production]\"\n\n# With development tools\npip install \"zenith-web[dev]\"\n```\n\n## Production Deployment\n\n### Docker\n```dockerfile\nFROM python:3.12-slim\n\nWORKDIR /app\nCOPY . .\nRUN pip install \"zenith-web[production]\"\n\nCMD [\"uvicorn\", \"main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\"]\n```\n\n### Environment Configuration\n```python\nfrom zenith import Zenith\nfrom zenith.config import Config\n\napp = Zenith(\n config=Config(\n database_url=os.getenv(\"DATABASE_URL\"),\n redis_url=os.getenv(\"REDIS_URL\"), \n secret_key=os.getenv(\"SECRET_KEY\"),\n debug=os.getenv(\"DEBUG\", \"false\").lower() == \"true\"\n )\n)\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](docs/guides/contributing/DEVELOPER.md).\n\n```bash\ngit clone https://github.com/nijaru/zenith.git\ncd zenith\npip install -e \".[dev]\"\npytest # Run tests\n```\n\n## Status\n\n**Current Version**: v0.2.1 (stable release) \n**Python Support**: 3.12+ \n**Test Suite**: 100% passing (328/332 tests) \n**Performance**: Production-ready with 8,000+ req/s capability \n**Architecture**: Clean separation with Service system and dependency injection \n\nZenith is production-ready with comprehensive middleware, performance optimizations, and clean architecture patterns for modern Python applications.\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Modern Python web framework with clean architecture and type-safe dependency injection",
"version": "0.2.2",
"project_urls": {
"Documentation": "https://nijaru.github.io/zenith",
"Homepage": "https://github.com/nijaru/zenith",
"Issues": "https://github.com/nijaru/zenith/issues",
"Repository": "https://github.com/nijaru/zenith.git"
},
"split_keywords": [
"framework",
" http3",
" liveview",
" quic",
" realtime",
" web",
" websockets"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eef9bf76b403027bbf5ad07f7c07fce739b40abba29622b61a96f079b972b075",
"md5": "ad99d10b52edbb156d9cb41d1a0990fd",
"sha256": "a354a034fc28c72f99282d608a6276afdb92aada82513a522534b535cc3d76c1"
},
"downloads": -1,
"filename": "zenith_web-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad99d10b52edbb156d9cb41d1a0990fd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 177975,
"upload_time": "2025-09-13T06:01:04",
"upload_time_iso_8601": "2025-09-13T06:01:04.498740Z",
"url": "https://files.pythonhosted.org/packages/ee/f9/bf76b403027bbf5ad07f7c07fce739b40abba29622b61a96f079b972b075/zenith_web-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4fee36e74db8e3f11ec7eeb9eea08d486099f927f9c609f3974b836cfbb92df2",
"md5": "4338a18a9496c79701e3221a44ccbe52",
"sha256": "5e69c58f87161f99719dfaa3b335f821380ccccde6b5b5b6aff5bdca57e84c79"
},
"downloads": -1,
"filename": "zenith_web-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "4338a18a9496c79701e3221a44ccbe52",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 225480,
"upload_time": "2025-09-13T06:01:05",
"upload_time_iso_8601": "2025-09-13T06:01:05.751834Z",
"url": "https://files.pythonhosted.org/packages/4f/ee/36e74db8e3f11ec7eeb9eea08d486099f927f9c609f3974b836cfbb92df2/zenith_web-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-13 06:01:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nijaru",
"github_project": "zenith",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zenith-web"
}
JSON
