Install¶
Requirements¶
- CPython 3.14. The free-threaded build (
python3.14t) is the primary target and runs several worker loops; the standard build runs one. -
Linux, macOS or Windows. Wheels are published for both interpreter builds: x86-64 and ARM on Linux (manylinux 2.28) and macOS (11 or newer), and x86-64 on Windows. Elsewhere pip builds from the source distribution, which needs a Rust toolchain.
Windows is a development platform here rather than a deployment one: the suites run on it on both interpreter builds, and everything works, but nothing is measured there and no benchmark on this site comes from it. A worker loop on Windows is a selector loop and so watches at most 512 sockets, which bounds what handlers on one loop may hold open — outbound connections, mostly — rather than the connections the server accepts. - Redis, only for durable topics:
pip install oxbrook redis. - PyJWT, only forJWT:pip install 'oxbrook[auth]'.
With uv, a free-threaded environment is one command:
Check which build is running with oxbrook --version.
Versions¶
Oxbrook is alpha. While the version is 0.x:
- a patch release (
0.1.1) fixes bugs and never changes the API; - a minor release (
0.2.0) may change the API, and lists every change that breaks existing code under Breaking in the changelog.
Pin a minor version, oxbrook~=0.2.0, to take fixes without changes. 1.0
will mean the API is committed to.
From source¶
Building from the repository needs a Rust toolchain, uv, and Docker if the suites should cover durable topics:
git clone https://github.com/ishangavidusha/oxbrook
cd oxbrook
make venvs # .venv (free-threaded 3.14t) and .venv-gil (standard 3.14)
make build # maturin develop --release into both
make run # examples/hello.py
On Windows, where there is no make, the same three steps are:
uv venv --python 3.14t .venv
uv pip install --python .venv/Scripts/python.exe maturin
.venv/Scripts/maturin.exe develop --release
Rebuild after any change to src/; the make targets that need it already
do. The contributing guide covers the test suites and conventions.
First app¶
from oxbrook import App, Request
app = App(title="Notes", version="1.0.0")
@app.get("/notes/{note_id}")
async def read_note(_: Request, note_id: int):
"""Read one note by its id."""
return {"id": note_id, "title": "hello"}
if __name__ == "__main__":
app.run(port=8000)
Installing Oxbrook puts two commands on the environment's path, oxbrook and
its short form oxb. See Running a server for what they do.
That gives you, without further configuration:
GET /notes/1returning JSON, andHEADon the same path422forGET /notes/abc, produced in Rust before Python is woken405with anAllowheader forDELETE /notes/1GET /openapi.jsonand a documentation page atGET /docsPOST /mcpspeaking the Model Context Protocol, exposing nothing until a route asks to be exposed
Services¶
Services run in containers rather than on the host.
make up # start redis and postgres
make down # stop them and remove their volumes
make stack # build the app image and run two nodes against one redis
Handler rules¶
Handlers are async def, or a plain def on a route declared
blocking=True. An undeclared synchronous handler is a TypeError at
registration rather than a surprise at runtime, because a blocking call on a
worker loop stalls every request that loop is carrying.