Skip to main content

zebridge (Python)

A ZeBridge client for Python: a local replica that follows PostgreSQL through the bridge, and writes back through it. Pure Python over libzb's C ABI — no ctypes in your code. Which library for which host: DISTRIBUTION.md.

pip install zebridge

The wheels carry libzb for Linux (x86_64, aarch64; glibc 2.35+) and macOS (Apple silicon, Intel; 13+). Python 3.10 or later.

Use

from zebridge import ZeBridge

with ZeBridge(bridge_url="https://zb.example.com", invite=code, tables=["orders"],
              on_change=lambda r: print("changed:", r.get("changed_tables"))) as zb:
    rows = zb.query("SELECT * FROM orders WHERE status = ?", "open")   # list of dicts
    zb.mutate("orders", "UPDATE", {"id": 7}, {"status": "done"})

On a bridge that offers ordering, a write waits by default for this client's previous unsettled write. after names another earlier write instead, and independent waits for none. mutate returns the write's ID (msgId); a write refused before it was queued raises instead. The rules: Ordering a write.

order = zb.mutate("orders", "INSERT", {"id": 8}, {"status": "open"})
zb.mutate("orders", "INSERT", {"id": 9}, {"status": "open"})                       # waits for order 8 (the default)
zb.mutate("orders", "UPDATE", {"id": 8}, {"status": "paid"}, after=order["msgId"])  # waits for order 8 only
zb.mutate("orders", "UPDATE", {"id": 7}, {"note": "gift"}, independent=True)      # waits for nothing
  • The options are the ones every ZeBridge client reads (CLIENTS.md), in camelCase or snake_case (bridge_url is bridgeUrl). A dict works too: ZeBridge({"bridgeUrl": …}).
  • Enrollment. The first run redeems invite at the bridge and keeps the identity next to the replica (identity_path, default <db_path>.identity, mode 0600). Later runs need neither the invite nor a NATS URL, and the JWT renews itself before it expires.
  • The thread. libzb drives a client from one thread; ZeBridge owns it. Any thread may call it. An idle client polls every poll_ms (250 ms); while calls keep coming, the thread serves each one at once and still polls every poll_ms, so a writer in a loop runs at its own pace (measured: 1,700 writes/s, all settled). on_change hears every poll that applied rows, settled writes or brought requests — on the worker thread (calling back into zb from it is fine).
  • Errors raise ZeBridgeError with libzb's words. on_error hears the loop's.
  • Revocation. Once revoked, zb.revoked is true and the loop stops; wipe() removes the rows.
  • Asking a service. request(subject, payload), and ingest to keep the answer's rows in an on-demand table.

A service

A service answers questions that clients ask with request("query.<tenant>.<name>", …). It needs a responder's creds (bridge --mint-responder). Write one handler per question:

from zebridge import ZeBridge

with ZeBridge(nats_url="tls://nats.example.com:4222", creds_path="airports.creds",
              db_path="airports.sqlite3", tables=["airports"]) as zb:

    def by_code(q: dict, tenant: str):
        return zb.query("SELECT * FROM airports WHERE code = ?", q["code"])

    zb.serve(["_default"], {"airport_by_code": by_code}, queue="airports")
    zb.wait()   # until SIGINT or SIGTERM
  • A handler gets the asker's payload and the tenant from the subject (never from the payload), and returns any JSON.
  • A handler that raises answers {"error": "<Type>: <message>"}, so the asker never waits out a timeout.
  • Handlers run on the client's thread, between two polls. Instances with the same queue share the questions.
  • An answer too large for one message goes through the tenant's object store; the asking library fetches it.

Example: examples/10-airports/airport_service.py.

The library

ZB_LIB names libzb's shared library; else a copy bundled in the package (zebridge/lib/), else the repository's own build (cd libzb && zig build -Doptimize=ReleaseFast), else the system's: on Debian and Ubuntu, sudo apt install ./libzb_<version>_<arch>.deb puts it where the loader finds it. ZB_ABI pins the C ABI this package speaks; libzb/python/abi_check.py checks it with the other bindings.

Metadata

Release files for zebridge 0.3.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for zebridge 0.3.3
File Actions
zebridge-0.3.3-py3-none-manylinux_2_35_x86_64.whl Python 3 none Linux glibc 2.35+ x86-64 Details for zebridge-0.3.3-py3-none-manylinux_2_35_x86_64.whl
zebridge-0.3.3-py3-none-manylinux_2_35_aarch64.whl Python 3 none Linux glibc 2.35+ ARM64 Details for zebridge-0.3.3-py3-none-manylinux_2_35_aarch64.whl
zebridge-0.3.3-py3-none-macosx_13_0_x86_64.whl Python 3 none macOS 13.0+ x86-64 Details for zebridge-0.3.3-py3-none-macosx_13_0_x86_64.whl
zebridge-0.3.3-py3-none-macosx_13_0_arm64.whl Python 3 none macOS 13.0+ ARM64 Details for zebridge-0.3.3-py3-none-macosx_13_0_arm64.whl

Total release size: 22.4 MB

Release files / zebridge-0.3.3-py3-none-manylinux_2_35_x86_64.whl

Download URL zebridge-0.3.3-py3-none-manylinux_2_35_x86_64.whl
Size 9.0 MB
Tags Linux glibc 2.35+ x86-64 Python 3
SHA-256 checksum
How to use checksums
6e6ab35a623b3c024053e51d63c49402ff0e52e9ff21ddea96afa7461be38bfa
BLAKE2b-256 checksum
How to use checksums
373723cd682ecf2abd63ceae182132731a654a3bdd4e2f8b46bd834a2e27f227
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / zebridge-0.3.3-py3-none-manylinux_2_35_aarch64.whl

Download URL zebridge-0.3.3-py3-none-manylinux_2_35_aarch64.whl
Size 8.6 MB
Tags Linux glibc 2.35+ ARM64 Python 3
SHA-256 checksum
How to use checksums
d138d312c3f4459df4fb6fd3aec9cc19c08ca44042f6fbdc8131bd81d3893032
BLAKE2b-256 checksum
How to use checksums
5f1a4e9cea5924bfb562b90339583075cc190e0ad137d11f97ffdad939b68e8c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / zebridge-0.3.3-py3-none-macosx_13_0_x86_64.whl

Download URL zebridge-0.3.3-py3-none-macosx_13_0_x86_64.whl
Size 2.5 MB
Tags Python 3 macOS 13.0+ x86-64
SHA-256 checksum
How to use checksums
0b341d14412a8cfc5fa872ad3ccef656f0a88189ec22bada3b61f62b0c900b7d
BLAKE2b-256 checksum
How to use checksums
4275d63d407bcf429c71091fcf9b12ada350cf56e20e41963c32e00144957ae8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / zebridge-0.3.3-py3-none-macosx_13_0_arm64.whl

Download URL zebridge-0.3.3-py3-none-macosx_13_0_arm64.whl
Size 2.3 MB
Tags Python 3 macOS 13.0+ ARM64
SHA-256 checksum
How to use checksums
e5126bfe31b3b30345fb1edb18f647d53cf530cfdb6ec4ec602b4fad3b398af0
BLAKE2b-256 checksum
How to use checksums
f022b1e7901c867e7874416378d989117b5fd4d799aeb0b01c945140d1a9281e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for zebridge 0.3.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 4 files in this release have been uploaded with provenance metadata.

Select from 4 files

Attestation for zebridge-0.3.3-py3-none-manylinux_2_35_x86_64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page