BlackBull¶

BlackBull is a Python web framework with pure-Python implementations of HTTP/1.1, HTTP/2 (with ALPN), WebSocket, gRPC, and an MQTT 5 broker — all on one process, no reverse proxy or sidecar required. No required C extensions outside the standard library, one pip install, one deployable.

Internally it threads its own typed Connection end to end; the ASGI 3.0 interface¹ is kept as an interop boundary, so a BlackBull app also runs unchanged under uvicorn, Hypercorn, or httpx.ASGITransport.

Early Alpha

BlackBull is in Early Alpha. The API may change between MINOR versions per ZeroVer. See Known Limitations for the explicit list of behaviours to expect, and Conformance for the protocol-level test coverage behind the standards-compliance claims.

What you get¶

Routing + middleware in the shape ASGI apps already use, with optional simplified handler signatures that drop (scope, receive, send) boilerplate when you don't need them.
HTTP/1.1, HTTP/2, and WebSocket on the same listener — ALPN negotiates HTTP/2; cleartext h2c is detected on first preface bytes; WebSocket-over-HTTP/2 (RFC 8441) is available as an opt-in.
gRPC and MQTT 5 beside HTTP — app.enable_grpc() serves gRPC (all four RPC shapes, gzip compression) over the same HTTP/2 port; app.add_extension(MQTTExtension(...)) runs a pure-Python MQTT 5 broker on its own port, in the same process.
An edge inference serving shape — SSE token streaming with HTTP/2 multiplexing beside MQTT device ingest and $share/… work queues, in one process that pip installs on ARM with no C toolchain. See Edge inference serving.
Standards conformance — RFC 9112 (HTTP/1.1), RFC 9113 (HTTP/2 — h2spec passes), RFC 6455 (WebSocket — Autobahn passes), RFC 8441 (Extended CONNECT for WebSocket over HTTP/2).
Predictable behaviour under load — per-connection deadline subsystem, per-stream queue depth controls, cooperative event-loop yielding.
Pre-fork multi-worker with SO_REUSEPORT, optional uvloop, hot-reload via watchfiles, AF_UNIX + systemd socket activation.
PEP 561 typed distribution (downstream type-checkers honour the inline annotations).

Install¶

pip install blackbull                        # core
pip install 'blackbull[compression]'         # gzip / brotli / zstandard
pip install 'blackbull[reload]'              # watchfiles for --reload
pip install 'blackbull[speed]'               # uvloop

Hello world¶

from blackbull import BlackBull

app = BlackBull()

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

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

$ python myapp.py
$ curl localhost:8000/
Hello, world!

That's a simplified handler — no scope, receive, send boilerplate, return value becomes the response body. See Your First App for the next steps, or Hello World for the full ASGI-triplet form.

Where to go next¶

Not sure BlackBull fits your project? Why BlackBull? walks through the scenarios where its architectural bets pay off — and where another framework may serve you better.
New to BlackBull? Start with Installation.
Building something? The Guide covers routing, middleware, WebSockets, error handling, HTTP/2, and configuration.
Serving a local model from a small box? Edge inference serving walks the one-process shape end to end, with a runnable example.
Deploying? See Deployment for multi-worker, TLS, AF_UNIX, systemd activation, and reverse-proxy topologies.
Curious about the design? Architecture covers the actor model, protocol ownership, and fault injection; Internals walks the implementation in detail.

ASGI is the async successor to WSGI — a single small interface that lets the same app object speak HTTP and WebSocket without separate adapters. BlackBull apps are ASGI-callable, so any ASGI host can serve them. The reverse direction — hosting a foreign ASGI app (Starlette, Quart, FastAPI) on BlackBull's own server — needs BB_FORCE_ASGI_SCOPE=1, which makes the server emit a plain ASGI scope dict instead of a Connection. ↩