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.4.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| heaven-2.4.2.tar.gz | 69.7 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| heaven-2.4.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 146.0 kB
Release files / heaven-2.4.2.tar.gz
| Download URL | heaven-2.4.2.tar.gz |
|---|---|
| Size | 69.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f29a6aaac2fc57c3e4d00940e9d256826c5cc32a5fb039c2a0745e4abc0f61d7
|
|
BLAKE2b-256 checksum How to use checksums |
49d14b5223c437413bdb697fe83d3976a972d154323f74e75e9a53de237603ca
|
| 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-38-generic
|
Release files / heaven-2.4.2-py3-none-any.whl
| Download URL | heaven-2.4.2-py3-none-any.whl |
|---|---|
| Size | 76.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ca75901930dd1df4005a4e7ef971dae852093b3622f720ab014dca9f16282a1b
|
|
BLAKE2b-256 checksum How to use checksums |
4fe5ebe0a1c87a9bf88801c693d8501327428101baa350288a50b291d0cd332f
|
| 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-38-generic
|
Security for heaven 2.4.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
