z4j-fastapi
The FastAPI framework adapter for z4j.
Adds the z4j agent into your FastAPI app via a single
z4j_lifespan(...) passed to FastAPI(lifespan=...). Auto-discovers
the engine adapter you have installed (Celery, RQ, Dramatiq, Huey,
arq, TaskIQ) and streams every task lifecycle event to z4j. Operator
control actions flow back the same channel.
Compatibility
- FastAPI 0.95+ (no upper cap)
- Python 3.11+
Pair with an engine adapter (z4j-celery, z4j-rq, z4j-dramatiq, z4j-huey, z4j-arq, z4j-taskiq); each engine adapter carries its own upstream floor.
Full per-adapter matrix at https://z4j.dev/reference/compatibility/.
What it ships
- One-line install, pass
z4j_lifespan(...)toFastAPI(lifespan=...)and the agent connects on the next uvicorn worker boot - Engine auto-discovery, picks up whichever z4j engine adapter is installed alongside; cross-stack combos (FastAPI + arq, FastAPI + Celery) are first-class
@z4j_metadecorator, optional per-task annotations (priority="critical",tags=["billing"],deadline_ms=5000) for dashboard filtering and SLO display- Service-user safe, auto-relocates the local outbound buffer
to
$TMPDIR/z4j-{uid}when$HOMEis unwritable (uvicorn under a service account, distroless images, etc.)
Install
pip install z4j-fastapi z4j-celery z4j-celerybeat
Wire it into your app:
from fastapi import FastAPI
from z4j_fastapi import z4j_lifespan
# reads Z4J_TOKEN, Z4J_BRAIN_URL, Z4J_PROJECT_ID from env
app = FastAPI(lifespan=z4j_lifespan())
Pass explicit config as kwargs
(z4j_lifespan(brain_url=..., token=..., project_id=...)) instead of
env vars if you prefer. Apps that already own their lifespan can wrap
it via inner_lifespan=; apps that cannot use lifespan at all can
call install_z4j(app) instead.
Mint the agent token from the dashboard's Agents page.
Reliability
- No exception from the agent ever propagates back into FastAPI request handlers or your worker code.
- Events buffer locally when z4j is unreachable; your application never blocks on network I/O.
Documentation
Full docs at z4j.dev/frameworks/fastapi/.
License
Apache-2.0, see LICENSE.
Links
- Homepage: https://z4j.com
- Documentation: https://z4j.dev
- PyPI: https://pypi.org/project/z4j-fastapi/
- Issues: https://github.com/z4jdev/z4j-fastapi/issues
- Changelog: CHANGELOG.md
- Security: security@z4j.com (see SECURITY.md)
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file z4j_fastapi-1.8.0.tar.gz.
File metadata
- Download URL: z4j_fastapi-1.8.0.tar.gz
- Upload date:
- Size: 24.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bd78569a9ccae6835258452141b140ee8101939af607ff5d3e5de97415e6f078
|
|
| MD5 |
7c6243ed9311e1ec5555250392bb731f
|
|
| BLAKE2b-256 |
92154801d4075b91104046207b392eb4818db6354e9790ee94de1d9e628c3b58
|
File details
Details for the file z4j_fastapi-1.8.0-py3-none-any.whl.
File metadata
- Download URL: z4j_fastapi-1.8.0-py3-none-any.whl
- Upload date:
- Size: 20.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
86062a2cc8a83afc8a5ed25b4d0ed4c580ea58edc2cc1aa5e6619b0e0a7d9e5b
|
|
| MD5 |
c5d009c1592636785f567141c795b4b9
|
|
| BLAKE2b-256 |
6e92a12056245c27cfca3f5c6319ba4ea8002fd25a3313e34933f21d791ceb4f
|
