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

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

Total release size: 22.4 MB

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

Download URL zebridge-0.3.0-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
f26aae89f29b911d5ed70621b4643668de6e82858e5a87455c138d88e9b4df89
BLAKE2b-256 checksum
How to use checksums
5121ad9125b7ff5cdbd71a243624dd79fed3c1c42e38f629a8ac6b19200473bf
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.0-py3-none-manylinux_2_35_aarch64.whl

Download URL zebridge-0.3.0-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
8e8cc8e059add1ade3c0c9d37510df63721e04a40fd9531ca602c333e79dfa11
BLAKE2b-256 checksum
How to use checksums
17c1a886c23175e4cbdaf9c440a24de3a783a4dd83cedf56f9031e35d32675a9
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.0-py3-none-macosx_13_0_x86_64.whl

Download URL zebridge-0.3.0-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
1a012b9a4d27c7fdadca58199bbf0ce62e96eafac5918a1470a48bcd6c0547ac
BLAKE2b-256 checksum
How to use checksums
5399910b9e37667173b14d0b5b36064dd7b43cc1a7788845215f60499056644a
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.0-py3-none-macosx_13_0_arm64.whl

Download URL zebridge-0.3.0-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
153b5bba024614f51b0d9d1eab04260cd60801ae1bcddd0388760cedd3163f2c
BLAKE2b-256 checksum
How to use checksums
73b8481e183ce5d966304dbd2aabe82d476cfa0306f3789354ebd51188b78b24
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.0

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