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"})
  • 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.2

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.2
File Actions
zebridge-0.3.2-py3-none-manylinux_2_35_x86_64.whl Python 3 none Linux glibc 2.35+ x86-64 Details for zebridge-0.3.2-py3-none-manylinux_2_35_x86_64.whl
zebridge-0.3.2-py3-none-manylinux_2_35_aarch64.whl Python 3 none Linux glibc 2.35+ ARM64 Details for zebridge-0.3.2-py3-none-manylinux_2_35_aarch64.whl
zebridge-0.3.2-py3-none-macosx_13_0_x86_64.whl Python 3 none macOS 13.0+ x86-64 Details for zebridge-0.3.2-py3-none-macosx_13_0_x86_64.whl
zebridge-0.3.2-py3-none-macosx_13_0_arm64.whl Python 3 none macOS 13.0+ ARM64 Details for zebridge-0.3.2-py3-none-macosx_13_0_arm64.whl

Total release size: 22.4 MB

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

Download URL zebridge-0.3.2-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
98149fcefe6a8c8e464d5bb85d9698b0c51ce1d2836e95afe89328100008c564
BLAKE2b-256 checksum
How to use checksums
02ceec896d657da7f4424ed2ccf976959551324132decd4f6e1a4af6519be3f0
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 12, 2026.

Transparency log

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

Download URL zebridge-0.3.2-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
d3a173d9db7684e6f41eea75407ddfd558c917d5f6beb46d4f892031c26efeab
BLAKE2b-256 checksum
How to use checksums
d58b4bfa7e717d87c6104ea4c2ca0c329932b75605169bf42a67613519970651
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 12, 2026.

Transparency log

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

Download URL zebridge-0.3.2-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
6a74ea443e98c0f1ef9d565f6e48f73c27d62b428c9809985564408379c1fc22
BLAKE2b-256 checksum
How to use checksums
447e95f99f990edcfd38355ae9e74eaac69a41e096330b21b25f4f4d39c685ae
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 12, 2026.

Transparency log

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

Download URL zebridge-0.3.2-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
5c314760e09924415d1ce1a856a339bf22755e2fa2687bb89494b4e49c9b1d73
BLAKE2b-256 checksum
How to use checksums
8fae6fbf4a0663d2406ca9da15af784923598ad01e0739867653d88b9479ff72
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 12, 2026.

Transparency log

Security for zebridge 0.3.2

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.2-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 12, 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