# Zenith Framework
[](https://badge.fury.io/py/zenithweb)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/nijaru/zenith/actions)
[](https://nijaru.github.io/zenith/)
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
```bash
pip install zenithweb
```
```python
from zenith import Zenith
from zenith import Session # Database session dependency
from zenith.db import ZenithModel # Modern database models
from sqlmodel import Field
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)
# 🎨 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.to_dict() for user in users]}
@app.post("/users")
async def create_user(user_data: dict):
# Clean API: User.create() - no session management!
user = await User.create(**user_data)
return {"user": user.to_dict()}
@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.to_dict()}
# 🏃♂️ Run it
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="127.0.0.1", port=8000)
```
Run with:
```bash
uvicorn main:app --reload
```
## 🎯 Modern DX Features
### 🚀 **Zero-Config Setup**
```python
app = Zenith() # Just works! No complex configuration needed
```
- **Intelligent defaults** - Development vs production auto-detection
- **Automatic middleware** - Security, CORS, logging configured automatically
- **Environment-aware** - Uses `ZENITH_ENV` or sensible detection
### 🏗️ **Intuitive Database Models**
```python
# 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="alice@example.com")
```
- **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**
```python
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**
```python
@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**
- **9,600+ req/s** - Exceptional performance with modern features
- **No performance penalty** - Zero overhead from convenience features
- **Async-first** - Full async/await with Python 3.12+ optimizations
- **Production tested** - 70% middleware retention with full feature stack
### 🛡️ **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:**
- Simple endpoints: **9,557 req/s**
- JSON endpoints: **9,602 req/s**
- With full middleware: **6,694 req/s** (70% 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
**🔥 Modern DX Examples:**
- **[Modern Developer Experience](examples/03-modern-developer-experience.py)** - Complete modern patterns showcase
- **[One-Liner Features](examples/04-one-liner-features.py)** - Convenience methods demonstration
- **[One-liner Features](examples/17-one-liner-features.py)** - `app.add_auth()`, `app.add_admin()`, `app.add_api()`
- **[Zero-config Setup](examples/18-seamless-integration.py)** - Automatic environment detection
**🚀 Complete Examples:**
- [Hello World](examples/00-hello-world.py) - Simple setup (`app = Zenith()`)
- [Basic API](examples/01-basic-routing.py) - Routing and validation
- [Authentication](examples/02-auth-api.py) - JWT authentication
- [WebSocket Chat](examples/07-websocket-chat.py) - Real-time communication
- [Background Jobs](examples/05-background-tasks.py) - Task processing
- [Security Middleware](examples/11-security-middleware.py) - Production security
## CLI Tools
```bash
# Create new project with secure defaults
zen new my-api
# Generate secure SECRET_KEY
zen keygen
# Development server with hot reload
zen dev
# Production server
zen serve --workers 4
```
## Installation
```bash
# Basic installation
pip install zenithweb
# With production dependencies
pip install "zenithweb[production]"
# With development tools
pip install "zenithweb[dev]"
```
## Production Deployment
### Docker
```dockerfile
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
```python
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](docs/guides/contributing/DEVELOPER.md).
```bash
git clone https://github.com/nijaru/zenith.git
cd zenith
pip install -e ".[dev]"
pytest # Run tests
```
## Status
**Latest Version**: v0.0.3
**Python Support**: 3.12-3.13
**Test Suite**: 100% passing (862 tests)
**Performance**: Production-ready with 9,600+ req/s capability
**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](LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "zenithweb",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.12",
"maintainer_email": null,
"keywords": "api, async, database, framework, performance, web, websockets",
"author": null,
"author_email": "Nick Russo <nijaru7@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d0/63/e7ef728b6897a534a2e1e338d25ca0465ee007e620f10d1cd2110af5f214/zenithweb-0.0.6.tar.gz",
"platform": null,
"description": "# Zenith Framework\n\n[](https://badge.fury.io/py/zenithweb)\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 web framework with **intuitive developer experience** and exceptional performance.\n\n> **\ud83c\udfaf Modern DX**: Zero-config setup, database models with chainable queries, one-liner features, and clean architecture patterns - making Python web development incredibly productive.\n\n## What is Zenith?\n\nZenith brings together **exceptional productivity**, **outstanding performance**, and **full type safety**:\n\n- **\ud83d\ude80 Zero-config setup** - `app = Zenith()` just works with intelligent defaults\n- **\ud83c\udfd7\ufe0f Intuitive models** - `User.where(active=True).order_by('-created_at').limit(10)`\n- **\u26a1 One-liner features** - `app.add_auth()`, `app.add_admin()`, `app.add_api()`\n- **\ud83c\udfaf Enhanced DX** - No session management, ZenithModel handles it automatically\n- **\ud83c\udfce\ufe0f Exceptional performance** - 9,600+ req/s with full async support\n- **\ud83d\udee1\ufe0f Production-ready** - Security, monitoring, and middleware built-in\n\n## \ud83d\ude80 Zero-Config Quick Start\n\n```bash\npip install zenithweb\n```\n\n```python\nfrom zenith import Zenith\nfrom zenith import Session # Database session dependency\nfrom zenith.db import ZenithModel # Modern database models\nfrom sqlmodel import Field\nfrom typing import Optional\n\n# \ud83c\udfaf Zero-config setup - just works!\napp = Zenith()\n\n# \u26a1 Add features in one line each\napp.add_auth() # JWT authentication + /auth/login\napp.add_admin() # Admin dashboard at /admin\napp.add_api(\"My API\", \"1.0.0\") # API docs at /docs\n\n# \ud83c\udfd7\ufe0f Modern models with chainable query patterns\nclass User(ZenithModel, table=True):\n id: Optional[int] = Field(primary_key=True)\n name: str = Field(max_length=100)\n email: str = Field(unique=True)\n active: bool = Field(default=True)\n\n# \ud83c\udfa8 Clean routes with enhanced DX\n@app.get(\"/\")\nasync def home():\n return {\"message\": \"Modern DX in Python!\"}\n\n@app.get(\"/users\")\nasync def list_users(): # \u2728 No session management needed!\n # Clean chaining: User.where().order_by().limit()\n users = await User.where(active=True).order_by('-id').limit(10).all()\n return {\"users\": [user.to_dict() for user in users]}\n\n@app.post(\"/users\")\nasync def create_user(user_data: dict):\n # Clean API: User.create() - no session management!\n user = await User.create(**user_data)\n return {\"user\": user.to_dict()}\n\n@app.get(\"/users/{user_id}\")\nasync def get_user(user_id: int):\n # Automatic 404 handling\n user = await User.find_or_404(user_id)\n return {\"user\": user.to_dict()}\n\n# \ud83c\udfc3\u200d\u2642\ufe0f Run it\nif __name__ == \"__main__\":\n import uvicorn\n uvicorn.run(app, host=\"127.0.0.1\", port=8000)\n```\n\nRun with:\n```bash\nuvicorn main:app --reload\n```\n\n## \ud83c\udfaf Modern DX Features\n\n### \ud83d\ude80 **Zero-Config Setup**\n```python\napp = Zenith() # Just works! No complex configuration needed\n```\n- **Intelligent defaults** - Development vs production auto-detection\n- **Automatic middleware** - Security, CORS, logging configured automatically\n- **Environment-aware** - Uses `ZENITH_ENV` or sensible detection\n\n### \ud83c\udfd7\ufe0f **Intuitive Database Models**\n```python\n# Intuitive database operations - seamless chaining!\nusers = await User.where(active=True).order_by('-created_at').limit(10).all()\nuser = await User.find_or_404(123) # Automatic 404 handling\nuser = await User.create(name=\"Alice\", email=\"alice@example.com\")\n```\n- **ZenithModel** - Modern ORM with chainable queries\n- **Automatic sessions** - No manual database session management\n- **Type-safe queries** - Full async support with SQLModel integration\n\n### \u26a1 **One-Liner Features**\n```python\napp.add_auth() # JWT authentication + /auth/login endpoint\napp.add_admin() # Admin dashboard at /admin with health checks\napp.add_api() # API documentation at /docs and /redoc\n```\n- **Instant features** - Complex functionality in single lines\n- **Production-ready** - Each feature includes monitoring and security\n- **Configurable** - Sensible defaults with full customization options\n\n### \ud83c\udfaf **Clean Dependency Injection**\n```python\n@app.get(\"/users\")\nasync def get_users(session: AsyncSession = Session):\n # Simple database session injection\n users = await User.all() # ZenithModel uses the session automatically\n return users\n```\n- **Simple patterns** - `Session` for database, `Auth` for current user\n- **Service injection** - `Inject(ServiceClass)` for business logic\n- **Type-safe** - Full IDE support and autocompletion\n\n### \ud83c\udfce\ufe0f **Exceptional Performance**\n- **9,600+ req/s** - Exceptional performance with modern features\n- **No performance penalty** - Zero overhead from convenience features\n- **Async-first** - Full async/await with Python 3.12+ optimizations\n- **Production tested** - 70% middleware retention with full feature stack\n\n### \ud83d\udee1\ufe0f **Production-Ready**\n- **Security by default** - CSRF, CORS, security headers automatic\n- **Built-in monitoring** - `/health`, `/metrics`, request tracing\n- **Error handling** - Structured errors with proper HTTP status codes\n- **Testing framework** - Comprehensive testing utilities included\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## \ud83d\udcc1 Project Structure\n\nClean organization with zero configuration:\n\n```\nyour-app/\n\u251c\u2500\u2500 main.py # app = Zenith() + routes\n\u251c\u2500\u2500 models.py # ZenithModel classes\n\u251c\u2500\u2500 services.py # Business logic (optional)\n\u251c\u2500\u2500 migrations/ # Database migrations (auto-generated)\n\u2514\u2500\u2500 tests/ # Testing with built-in TestClient\n```\n\n**Or traditional clean architecture:**\n```\nyour-app/\n\u251c\u2500\u2500 main.py # Application entry point\n\u251c\u2500\u2500 models/ # ZenithModel classes\n\u251c\u2500\u2500 services/ # Service classes with @Service decorator\n\u251c\u2500\u2500 routes/ # Route modules (optional)\n\u251c\u2500\u2500 middleware/ # Custom middleware\n\u2514\u2500\u2500 tests/ # Comprehensive test suite\n```\n\n## Performance\n\n**Verified Benchmark Results:**\n- Simple endpoints: **9,557 req/s**\n- JSON endpoints: **9,602 req/s**\n- With full middleware: **6,694 req/s** (70% 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## \ud83d\udcda Examples\n\n**\ud83d\udd25 Modern DX Examples:**\n- **[Modern Developer Experience](examples/03-modern-developer-experience.py)** - Complete modern patterns showcase\n- **[One-Liner Features](examples/04-one-liner-features.py)** - Convenience methods demonstration\n- **[One-liner Features](examples/17-one-liner-features.py)** - `app.add_auth()`, `app.add_admin()`, `app.add_api()`\n- **[Zero-config Setup](examples/18-seamless-integration.py)** - Automatic environment detection\n\n**\ud83d\ude80 Complete Examples:**\n- [Hello World](examples/00-hello-world.py) - Simple setup (`app = Zenith()`)\n- [Basic API](examples/01-basic-routing.py) - Routing and validation\n- [Authentication](examples/02-auth-api.py) - JWT authentication\n- [WebSocket Chat](examples/07-websocket-chat.py) - Real-time communication\n- [Background Jobs](examples/05-background-tasks.py) - Task processing\n- [Security Middleware](examples/11-security-middleware.py) - Production security\n\n## CLI Tools\n\n```bash\n# Create new project with secure defaults\nzen new my-api\n\n# Generate secure SECRET_KEY\nzen keygen\n\n# Development server with hot reload\nzen dev\n\n# Production server\nzen serve --workers 4\n```\n\n## Installation\n\n```bash\n# Basic installation\npip install zenithweb\n\n# With production dependencies\npip install \"zenithweb[production]\"\n\n# With development tools\npip install \"zenithweb[dev]\"\n```\n\n## Production Deployment\n\n### Docker\n```dockerfile\nFROM python:3.12-slim\n\nWORKDIR /app\nCOPY . .\nRUN pip install \"zenithweb[production]\"\n\nCMD [\"uvicorn\", \"main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\"]\n```\n\n### Environment Configuration\n```python\nfrom zenith import Zenith\n\napp = Zenith()\n\n# Environment-specific behavior:\n# development (or dev): Enhanced error reporting, auto-generated secrets\n# production (or prod): Optimized for deployment, requires SECRET_KEY\n# test: Testing mode with rate limiting disabled\n# staging: Production-like with enhanced monitoring\n\n# Manual configuration if needed\nfrom zenith.config import Config\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 automatically set based on ZENITH_ENV\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**Latest Version**: v0.0.3\n**Python Support**: 3.12-3.13\n**Test Suite**: 100% passing (862 tests)\n**Performance**: Production-ready with 9,600+ req/s capability \n**Architecture**: Clean separation with Service system and simple dependency patterns \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 for building APIs with minimal boilerplate",
"version": "0.0.6",
"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": [
"api",
" async",
" database",
" framework",
" performance",
" web",
" websockets"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "410d6fd5a706b25e8a6c6aa51982d04e69624de782b2bee0ec510408c395a766",
"md5": "985bb2b50155ee224a36d6e1c105daf7",
"sha256": "d204ede3be97a92aae64a94719981b18da192b8b674d868f85a2a40ba081f3e1"
},
"downloads": -1,
"filename": "zenithweb-0.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "985bb2b50155ee224a36d6e1c105daf7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.12",
"size": 213664,
"upload_time": "2025-10-06T22:31:56",
"upload_time_iso_8601": "2025-10-06T22:31:56.214351Z",
"url": "https://files.pythonhosted.org/packages/41/0d/6fd5a706b25e8a6c6aa51982d04e69624de782b2bee0ec510408c395a766/zenithweb-0.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d063e7ef728b6897a534a2e1e338d25ca0465ee007e620f10d1cd2110af5f214",
"md5": "0fbecab018073aa7ec95ff68da78cccb",
"sha256": "dc4b8a58f790199cdc09bf9229196aed7f3fd5f67a4813a1e7bf6ae608716f9a"
},
"downloads": -1,
"filename": "zenithweb-0.0.6.tar.gz",
"has_sig": false,
"md5_digest": "0fbecab018073aa7ec95ff68da78cccb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.12",
"size": 261710,
"upload_time": "2025-10-06T22:31:57",
"upload_time_iso_8601": "2025-10-06T22:31:57.450026Z",
"url": "https://files.pythonhosted.org/packages/d0/63/e7ef728b6897a534a2e1e338d25ca0465ee007e620f10d1cd2110af5f214/zenithweb-0.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 22:31:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nijaru",
"github_project": "zenith",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zenithweb"
}
JSON
