Skip to content

17-ecosystem-python.md

Latest commit

 

History

History
65 lines (47 loc) · 2.78 KB

17-ecosystem-python.md

File metadata and controls

65 lines (47 loc) · 2.78 KB
Raw

17. Ecosystem: Python

Persian: fa/docs/17-ecosystem-python.md
Catalog: catalogs/ECOSYSTEM_PYTHON.md

Why Zig here

CPython is excellent for orchestration (FastAPI, Django, data glue). It is often not the right place for tight CPU loops, bulk parsing, or alloc-heavy codecs. Export those kernels as a stable C ABI shared library and call them from Python.

Interop options

Approach Use when
ctypes (shipped: bindings/python) Simple C functions; handbook default
cffi Richer declarations; still C ABI
Extension module (C API) Need Python objects in-process; more coupling
NumPy / buffer protocol Arrays: pass data pointer + nbytes; document who owns memory

See 09 FFI ABI: free Zig allocations only with the matching zbr_free (or use caller-owned buffers).

Framework placement

Client → FastAPI / Django / Flask  (auth, ORM, validation)
              │
              ▼  ctypes / cffi / TurboAPI native_route
         Zig shared library (ReleaseFast hot path)
Pattern Description
Sidecar FFI Keep uvicorn/gunicorn; call zbr_* on hot endpoints
Zig HTTP core Upstream TurboAPI: FastAPI-compatible API with Zig server — cite upstream; do not treat their RPS as ours
Batch worker Celery/RQ worker loads the same .so / .dll

Related real projects

  • zignal / PyPI zignal-processing — image processing in Zig with Python bindings (arrufat/zignal)
  • TurboAPI — Zig HTTP behind a FastAPI-like surface (justrach/turboAPI)

Performance playbook

  1. Profile (cProfile, py-spy, scalene) — move only measured hot spots.
  2. Minimize crossings — batch work; avoid per-element FFI calls.
  3. Zero-copy — memoryview / NumPy contiguous buffers; length + pointer.
  4. Build — narrate ReleaseFast for speed claims; Debug for tests.
  5. Prove locally — .\scripts\microbench-zbr.ps1 and binding tests; never paste TFB/TurboAPI numbers as handbook results.

Anti-patterns: rewriting the ORM in Zig; claiming ASGI framework replacement without measurement; mixing CRT free paths on Windows.

In this repo

Artifact Path
Typed ctypes wrapper bindings/python
Tests pytest via verify scripts
Guide guides/zig-behind-your-api.md

Honest status

Item Status
ctypes + QA gates Shipped
FastAPI sidecar sketch Shipped: examples/domains/python-fastapi-sidecar
Vendoring TurboAPI Out of scope