Metadata-Version: 2.3
Name: heaven
Version: 2.0.0
Summary: Extremely Stupid Simple, Blazing Fast, Get Out of your way immediately Microframework for building Python Web Applications.
License: MIT
Author: Raymond Ortserga
Author-email: ortserga@gmail.com
Requires-Python: >=3.6,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: aiofiles (>=23.0.0,<24.0.0)
Requires-Dist: jinja2 (>=3.1.0,<4.0.0)
Requires-Dist: orjson (>=3.0.0)
Requires-Dist: pytastic (>=0.4.1)
Requires-Dist: rich (>=13.0.0)
Requires-Dist: uvicorn (>=0.14)
Requires-Dist: websockets (>=12.0)
Description-Content-Type: text/markdown

# Heaven ⚡ : <img src="https://img.shields.io/badge/coverage-95%25-green" />

**Heaven** is the absolute minimal, insanely fast [ASGI](https://asgi.readthedocs.io) 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."

<hr/>

### Why Heaven?

| Feature | Heaven | FastAPI | Flask | Django |
| :--- | :---: | :---: | :---: | :---: |
| **Learning Curve** | 30 Mins | High | Low | Extreme |
| **Throughput** ([measured](#performance)) | 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 |

1. **Stupid Simple**: Built for engineers who hate bloat. If you know Python, you already know Heaven.
2. **Blazing Fast**: A thin layer over ASGI, optimized for high-concurrency and low-latency.
3. **Batteries Included (The right ones)**: Native support for application mounting, centralized hooks (`.BEFORE`/`.AFTER`), and powerful background **Daemons**.
4. **Transparent**: No magic decorators that hide logic. Just clear, explicit routing.

<hr/>

## 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`](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:

```sh
pip install heaven fastapi flask django 'uvicorn[standard]' gunicorn
python benchmarks/compare.py
```

<hr/>

## Quickstart in 60 Seconds

1. **Install** 
```sh
$ pip install heaven
```

2. **Code**
```python
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`:
```python
# 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.

3. **Protect** (Automatic OpenAPI)
```python
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')
```

4. **Fly** (CLI)
Heaven comes with a beautiful, zero-config CLI.
```bash
pip install heaven

# Auto-discovery & run with reload
heaven fly

# Visualize your API structure
heaven routes
```

5. **Daemon** (Background)
```python
async def pulse(app):
    print("Heartbeat...")
    return 5 # Run every 5 seconds

app.daemons = pulse
```

6. **Run** (Standard)
```sh
$ uvicorn app:app --reload
```

<hr/>

- **Full Documentation**: [https://rayattack.github.io/heaven](https://rayattack.github.io/heaven)
- **PyPi**: [https://pypi.org/project/heaven](https://pypi.org/project/heaven)
- **Source**: [Github](https://github.com/rayattack/heaven)

## Contributing

We love builders. See the [Contribution Guidelines](contributions.md).


