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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file heaven-2.1.0.tar.gz.
File metadata
- Download URL: heaven-2.1.0.tar.gz
- Upload date:
- Size: 63.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.1.3 CPython/3.12.3 Linux/7.0.0-28-generic
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3faaf781708faa0493b3c48c4cb24a0bfd071fd3cc5110d47d5dd7f21b3e3279
|
|
| MD5 |
59d94869eac7c9d5dcd3fd1202315a94
|
|
| BLAKE2b-256 |
626901ea1cb9e74df5049695215b63248bb481380eedfc1d27be4b8b56c0d61b
|
File details
Details for the file heaven-2.1.0-py3-none-any.whl.
File metadata
- Download URL: heaven-2.1.0-py3-none-any.whl
- Upload date:
- Size: 70.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.1.3 CPython/3.12.3 Linux/7.0.0-28-generic
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
cc3a47418e3ec2da09a5a398f66145f62770d7be43c5063b7b83446170762a57
|
|
| MD5 |
a5e703c7bc3f3c37575cca7adcdb9102
|
|
| BLAKE2b-256 |
54ca8f2df05ca9b078a78a8409dcb9c934b3e624d98320ae43632baa5dfd84d5
|
