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.1

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

Total release size: 22.4 MB

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

Download URL zebridge-0.3.1-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
7341aa5f0cb1f7d712add02795abacf52f1f3190c501478899ff7676e3770198
BLAKE2b-256 checksum
How to use checksums
69957c4b8c3c668669010253d6c44155b4b2f3c4d67b72ab80d971efd5a37a8c
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.1-py3-none-manylinux_2_35_aarch64.whl

Download URL zebridge-0.3.1-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
5ce82301e5bbdedce8bc5ba4a5d48dea4d7ee3aa0e0c3594c57f24a5662f6fbb
BLAKE2b-256 checksum
How to use checksums
f1805ae539d28445cf303c133bf9309f704e2c91633c356ae7bef4c6785ab548
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.1-py3-none-macosx_13_0_x86_64.whl

Download URL zebridge-0.3.1-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
87eafb27a79966fc0f195090c6eeaf6000a7f08ecab8e26a3e334e4305ea9f34
BLAKE2b-256 checksum
How to use checksums
672d86539f457bfabea01a2b830e3f19a0b6f80218985108a1962603315346e1
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.1-py3-none-macosx_13_0_arm64.whl

Download URL zebridge-0.3.1-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
fa2d84484c922620aa1b06724b1a92791683c04e26418e099fbd7382342cbb7b
BLAKE2b-256 checksum
How to use checksums
8eb702399771750ae0d2e9c23e7c4b29632bf552d5a70470357dd0c3b2f5b84e
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.1

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.1-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