Heaven ⚡ : 
Heaven is the absolute minimal, insanely fast ASGI web framework for Python purists. It doesn't just get out of your way; it vanishes, leaving you with raw performance and total control.
"Mastery in 30 minutes or less. No grey spots, just pure Python."
Why Heaven?
| Feature | Heaven | FastAPI | Flask | Django |
|---|---|---|---|---|
| Learning Curve | 30 Mins | High | Low | Extreme |
| Throughput (measured) | 12,517 req/s | 6,223 req/s | 1,190 req/s | 1,784 req/s |
| Boilerplate | Zero | Medium | Low | Massive |
| Mastery | Complete | Partial | High | Low |
| Background Jobs | Native (Daemons) | External | External | External |
- Stupid Simple: Built for engineers who hate bloat. If you know Python, you already know Heaven.
- Blazing Fast: A thin layer over ASGI, optimized for high-concurrency and low-latency.
- Batteries Included (The right ones): Native support for application mounting, centralized hooks (
.BEFORE/.AFTER), and powerful background Daemons. - Transparent: No magic decorators that hide logic. Just clear, explicit routing.
Performance
Hello-world JSON throughput, one worker process each, default out-of-the-box configuration, generated by the script checked in at benchmarks/compare.py:
| Framework | Served by | Requests/sec | Relative |
|---|---|---|---|
| Heaven 2.0.0 | uvicorn | 12,517 | 1.00x |
| FastAPI 0.141.1 | uvicorn | 6,223 | 0.50x |
| Django 6.0.7 (ASGI) | uvicorn | 1,784 | 0.14x |
| Flask 3.1.3 | gunicorn | 1,190 | 0.10x |
Roughly 2x FastAPI, 7x Django and 10x Flask, measured on the same box: an Intel i5-8350U laptop, Python 3.12, 48 keep-alive connections, median of three 5 second rounds. ASGI apps run under uvicorn[standard], Flask runs under gunicorn's default sync worker. Absolute numbers are hardware-dependent, so reproduce them on yours before quoting:
pip install heaven fastapi flask django 'uvicorn[standard]' gunicorn
python benchmarks/compare.py
Quickstart in 60 Seconds
- Install
$ pip install heaven
- Code
from heaven import App, Request, Response, Context
app = App()
# Centralized Auth / Pre-processing
async def auth(req, res, ctx):
if not req.headers.get('Authorization'):
res.status = 401
res.abort('Unauthorized')
app.BEFORE('/api/*', auth)
# Simple Handler
async def welcome(req, res, ctx):
res.body = {"message": "Welcome to Heaven"}
app.GET('/api/v1/welcome', welcome)
Prefer grouping routes by subject? Register a method with Class#method:
# controllers/orders.py
from heaven import Handler
class Orders(Handler):
async def index(self):
self.res.body = await self.req.app.peek('db').orders()
app.GET('/orders', 'controllers.orders.Orders#index')
self.req, self.res and self.ctx are the same three objects, and Heaven builds one instance per request so self is never shared.
- Protect (Automatic OpenAPI)
from typing import Annotated, TypedDict
class User(TypedDict):
name: Annotated[str, 'min_len=2']
app.schema.POST('/user', expects=User, summary="Create User")
app.DOCS('/docs')
- Fly (CLI) Heaven comes with a beautiful, zero-config CLI.
pip install heaven
# Auto-discovery & run with reload
heaven fly
# Visualize your API structure
heaven routes
- Daemon (Background)
async def pulse(app):
print("Heartbeat...")
return 5 # Run every 5 seconds
app.daemons = pulse
- Run (Standard)
$ uvicorn app:app --reload
- Full Documentation: https://rayattack.github.io/heaven
- PyPi: https://pypi.org/project/heaven
- Source: Github
Contributing
We love builders. See the Contribution Guidelines.
1 maintainer
Metadata
1 maintainer
Release files for heaven 2.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| heaven-2.3.0.tar.gz | 67.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| heaven-2.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 142.1 kB
Release files / heaven-2.3.0.tar.gz
| Download URL | heaven-2.3.0.tar.gz |
|---|---|
| Size | 67.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
44a21a61a32e85b4a80fef3a2514f74585cdcba9c4a6ddd2d7fa7fcd4619a20a
|
|
BLAKE2b-256 checksum How to use checksums |
60282ab5c0b0df50f484914eeed51321d780648808388c57d146e6044b8964db
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.12.3 Linux/7.0.0-29-generic
|
Release files / heaven-2.3.0-py3-none-any.whl
| Download URL | heaven-2.3.0-py3-none-any.whl |
|---|---|
| Size | 74.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d9e79fbc3745b4160ced80d9c5ba204e216dc4770856a635c5e4cc3cc07b3b5d
|
|
BLAKE2b-256 checksum How to use checksums |
367b0f2d4a9f11e187ba3a89d33f4f27f1ef4d6c92868381c4b96b5689dfaba7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.12.3 Linux/7.0.0-29-generic
|
