blackbull 0.34.0

Async ASGI 3.0 framework with a from-scratch HTTP/1.1 parser, HTTP/2 frame layer, and WebSocket codec. HPACK delegates to the hpack library.

BlackBull

⚠ Early Alpha — API may break between MINOR versions. Conformance evidence: docs/about/conformance.md. Things to know before adopting: KNOWN_LIMITATIONS.md.

Async ASGI 3.0 framework with pure-Python HTTP/1.1, HTTP/2 framing, and WebSocket implementations. HPACK header compression delegates to the hpack library (re-implementing a conformant HPACK encoder/decoder is a project of its own); everything else, including the ASGI server, event loop integration, prioritisation, push, flow control, and stream actor, is BlackBull's own code. Single deployable, no third-party C extensions in the protocol stack.

Why BlackBull

• One package, one process — the framework is the server. No separate ASGI runner; app.run() opens the socket and serves.
• Pure-Python protocol stack for HTTP/1.1 (RFC 9112) parser, HTTP/2 (RFC 9113) frame layer + flow control + RFC 9218 prioritisation + push, and WebSocket (RFC 6455) codec. HPACK (RFC 7541) is the one exception — see headline above.
• Pure-Python identity — uvloop is available as an optional [speed] extra. The single third-party dependency in the protocol stack is hpack, also pure Python.
• Conformance-tested against h2spec, Autobahn, and a differential nginx fuzz corpus.
• Modern Python — requires 3.11+, full type hints, PEP 561 typed distribution.

Install

pip install blackbull
pip install 'blackbull[compression]'   # add brotli + zstandard codecs
pip install 'blackbull[speed]'         # add uvloop event loop
pip install 'blackbull[reload]'        # add watchfiles for --reload

Hello, world

from blackbull import BlackBull

app = BlackBull()

@app.route(path='/')
async def hello():
    return "Hello, world!"

if __name__ == '__main__':
    app.run(port=8000)

Run it:

python app.py              # HTTP/1.1 on :8000

Or via the bundled CLI:

blackbull app:app --bind 0.0.0.0:8000

Simplified handlers

Route handlers may return a str, bytes, dict, or Response; path parameters are coerced to the annotation type:

@app.route(path='/tasks/{task_id:int}')
async def get_task(task_id: int):
    return {"id": task_id, "title": "..."}

Drop down to full ASGI (scope, receive, send) whenever you need it — routes accept either shape.

TLS + HTTP/2

app.run(port=8443, certfile='cert.pem', keyfile='key.pem')

ALPN negotiates h2 automatically; HTTP/1.1 clients fall back via the same socket.

WebSocket

from http import HTTPMethod
from blackbull.utils import Scheme

@app.route(path='/ws', methods=[HTTPMethod.GET], scheme=Scheme.websocket)
async def ws_echo(scope, receive, send):
    await receive()                              # websocket.connect
    await send({'type': 'websocket.accept'})
    while True:
        msg = await receive()
        if msg['type'] == 'websocket.disconnect':
            break
        if msg['type'] == 'websocket.receive':
            await send({'type': 'websocket.send',
                        'text': msg.get('text') or ''})

Built-in middleware

Compose via app.use(...) or per-route middlewares=[...]:

Middleware	What it does
Compression	Negotiates br / zstd / gzip from Accept-Encoding
StaticFiles	Serves files from a directory under a URL prefix
Cache	Per-worker LRU + ETag / Cache-Control honouring
Session	Signed-cookie sessions (HMAC-SHA256)
CORS	Preflight + actual-request header injection
TrustedProxy	Rewrites scope['client'] / scope['scheme'] from proxy headers

OpenAPI / Swagger UI

app.enable_openapi()   # publishes /openapi.json and /docs

Auto-generates an OpenAPI 3.1 spec from route signatures, path-param converters, docstrings, and @dataclass annotations on body parameters. Dataclass-typed bodies are also deserialized at runtime — async def h(body: CreateTask): ... receives a constructed instance, no manual json.loads.

Examples

Example	Demonstrates
examples/SimpleTaskManager/	REST API + HTML UI, middleware pipeline, route groups, SQLite, Bearer token auth
examples/ChatServer/	WebSocket, SSE, long polling side by side; Session + Compression + custom auth
examples/typed_routes_ok.py	{param:converter} syntax, url_path_for

Documentation

• Guide: docs/guide.md
• Architecture: docs/ActorDesign.md
• Changelog: CHANGELOG.md

Versioning

BlackBull uses ZeroVer prior to a 1.0 commitment. MINOR advances at each sprint close; PATCH is for bug fixes and harness work between sprints. See CHANGELOG.md for the full release history.

License

Apache License 2.0 — © TOKUJI.