Skip to content

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 interface1 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.

Serving and interoperability

  • HTTP/1.1, prior-knowledge h2c and WebSocket upgrades share the HTTP listener. HTTP/2 over TLS uses ALPN; RFC 8441 WebSocket streams are opt-in.
  • gRPC uses HTTP/2 on that listener. MQTT uses an extension and its own listener, with one worker owning broker state.
  • Native handlers and middleware use Connection. External-ASGI hosting converts at the boundary; use BB_FORCE_ASGI_SCOPE=1 to serve a foreign ASGI app on BlackBull's server.
  • See Conformance for coverage and Security model for default resource bounds.

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 states implementation invariants and code ownership.

  1. 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. ↩