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

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

Total release size: 22.0 MB

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

Download URL zebridge-0.2.11-py3-none-manylinux_2_35_x86_64.whl
Size 8.9 MB
Tags Linux glibc 2.35+ x86-64 Python 3
SHA-256 checksum
How to use checksums
c26a5c5058c77e8e04b1f081acb697058ec6297d8552bd5e251a88df703c0816
BLAKE2b-256 checksum
How to use checksums
48b8fe2f928e3fd02f02d1e5218eacad0efdab204063e6a3bd4a8a75d7df42ba
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 3, 2026.

Transparency log

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

Download URL zebridge-0.2.11-py3-none-manylinux_2_35_aarch64.whl
Size 8.4 MB
Tags Linux glibc 2.35+ ARM64 Python 3
SHA-256 checksum
How to use checksums
1ce622166d417fdc34672c69d612e51060013e7b53040cd9ea45e2189f182a51
BLAKE2b-256 checksum
How to use checksums
4b809efc30a2f63032a07cb9202435aa2d1ee8aaf395bdccc182252556719563
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 3, 2026.

Transparency log

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

Download URL zebridge-0.2.11-py3-none-macosx_13_0_x86_64.whl
Size 2.4 MB
Tags Python 3 macOS 13.0+ x86-64
SHA-256 checksum
How to use checksums
fe3939874c6b83e20d4da27900b62c719e4f46e5e7f618da038432ba45140954
BLAKE2b-256 checksum
How to use checksums
2a957acc7879b5357540a27e6b79e5157db91e8d888f335342b1321ad1fa500f
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 3, 2026.

Transparency log

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

Download URL zebridge-0.2.11-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
632ebd47634013b0bdcb193b3f3479c2f820be0d7ca009e40f4daff305cf9a77
BLAKE2b-256 checksum
How to use checksums
6214bf711533489071907415c5dbd889fdcfbc3e83630a9e9c7e6e58f31165a9
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 3, 2026.

Transparency log

Security for zebridge 0.2.11

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.2.11-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 3, 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