BlackBull¶
BlackBull is a Python web framework that speaks the
ASGI 3.0
interface1, 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.
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,gzipcompression) 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 thatpip 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, optionaluvloop, hot-reload viawatchfiles, 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 behind-nginx topologies.
- Curious about the design? Architecture covers the actor model, protocol ownership, and fault injection; Internals walks the implementation in detail.