This release is a pre-release and may not be stable for production use.
felix-client for Python
Python bindings for Felix, built as a wrapper over the Rust client rather than a reimplementation of the protocol.
That distinction is the point. Reconnection, redirect-following, retry
classification and offset bookkeeping are hard to get right and expensive to
get wrong — a second implementation is a second set of subtle bugs in exactly
the places that matter. Here they exist once, in felix-client, and every
language binds to them.
pip install felix-client
Wheels ship compiled, one per platform, covering every Python from 3.9 up — so installing needs no Rust toolchain. Linux (x86-64 and arm64), macOS (Intel and Apple silicon) and Windows x86-64 are covered; anything else builds from the sdist and does need one.
Full documentation: https://docs.getfelix.dev/clients/python/
Two surfaces
Synchronous, for threads and asyncio.to_thread:
import felix
with felix.Client("127.0.0.1:5000", tenant_id="t1", token=tok, ca_file=ca) as client:
client.publish("t1", "default", "events", b"hello")
with client.subscribe("t1", "default", "events") as events:
for event in events:
print(event.payload, event.offset)
Asynchronous, which is what most Python realtime backends want:
client = await felix.AsyncClient.connect(addr, tenant_id="t1", token=tok, ca_file=ca)
async with client:
await client.publish("t1", "default", "events", b"hello")
async with await client.subscribe("t1", "default", "events") as events:
async for event in events:
print(event.payload, event.offset)
Both wrap the same client and fail over identically. The sync one blocks with the GIL released; the async one yields to your event loop.
publish returns the record's log offset once the broker has written it, and
None when it acknowledged earlier than that (ack="none", or a broker that
acks on enqueue), the stream has no log, or the broker is too old to say.
Beyond publish and subscribe
Both surfaces also cover consumer groups (group_poll, the settles including
group_nack_after and group_dead_letter, group_extend, and group_create,
group_seek, group_describe and group_delete, each with a *_stream form
for every shard, sent to the shard's leader by following the broker's redirect;
group_sharded polls every shard through one handle),
cache watches (watch_cache, including retained watches that hand you current
state before live changes, and watch_cache_sharded, which merges a prefix
across every shard), and multi-shard subscriptions (subscribe_sharded, which
opens one subscription per shard and merges them; subscribe(shard=) reads one
named shard). offset_for_time finds the offset a time begins at, and read
returns a page of committed records without subscribing. publish_batch and
publish_records send ordered batches; the latter splits keyed records by
shard and returns a BatchReport saying which pieces landed. Two things catch
people out, so they are worth saying here:
- Publishing without a
key=puts every record on shard 0. The key is what spreads a stream, and a multi-shard stream published without one behaves exactly like a single-shard one. watch_cachewith a prefix reads one shard. Keys sharing a prefix do not share a shard, so watching a whole multi-shard cache meanswatch_cache_sharded.
Both surfaces also have atomic commits: commit(tenant_id, namespace, entity_key, [CommitOp.publish(...) or CommitOp.enqueue(...), CommitOp.put(...), CommitOp.delete(...)]) writes an event and its state changes as one record and
returns a CommitReceipt with the offset, and state_get reads the state back
with that offset as its version. A commit naming a second stream raises
NotOnOwningShardError, and one without exactly one event raises
EventCountError, before anything is sent. See
atomic commits for what atomic covers.
The clients page has the worked examples.
Tokens that expire
A token lasts 15 minutes by default, and a client that outlives one passes
token_provider, a function that returns a fresh token. The client calls it
lazily, one call at a time, when a stream is about to authenticate and the held
token is missing, past two thirds of its life, or was refused. Client takes a
plain function or an async def; AsyncClient takes an async def. token=
is then optional. See Getting and refreshing a
token.
felix.Client(addr, tenant_id="t1", token_provider=fetch_token, ca_file=ca)
TLS
QUIC has no unencrypted mode, so there is always a trust decision — and deliberately no "skip verification" switch, because that is the setting that silently turns a secure deployment insecure. Either the platform trust store (the default) or an explicit CA:
felix.Client(addr, tenant_id=..., token=..., ca_file="/path/to/ca.pem")
A development broker generates a self-signed certificate at startup; set
FELIX_TLS_CERT_EXPORT=/path/ca.pem on the broker and point ca_file at it.
Building
pip install maturin
task python:develop # build and install into the active virtualenv
task python:check # fmt, clippy, build
This crate is deliberately outside the Cargo workspace — an extension module
carries pyo3/extension-module, which cannot be linked into a test binary —
so task python:check is what builds it, not task test.
What is not wrapped
The Rust client has more than this binding wraps. What is left out, and why:
- Subscription counters.
ClusterSubscription::moves,reconnectsandstream_deletedhave no accessor on a subscription, sharded or not. A read in flight holds the handle, so these need their own shared state. A follow-up is planned; a move still shows up as aShardMoveditem on a sharded subscription. A cache watch does exposemoves,reconnects,errorandresume_from. - The single-connection
ClientandPublisherlayer (topology,stream_routing,shard_owners,inspect_shard,supports_*,publish_batch_binary*,connect_with_transport). The binding wrapsClusterClient, which owns those connections and runs the feature checks itself. hand_off_*andHandedon the idempotent producer. They hand back raw futures;publish_batchesis the iterator-shaped equivalent.ClientConfigoptions such aspublishersandtimestamps. They are connection configuration, set once, not calls.
Conformance
The semantics a Felix client must implement are catalogued in
crates/testing/felix-conformance/scenarios.toml, with task conformance:scenarios
to read them and task conformance:verify to check a client's results. That
catalogue — not this README — is the contract, and it is what the next
language's client is gated on.
Metadata
Release files for felix-client 0.7.0rc1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| felix_client-0.7.0rc1.tar.gz | 601.8 kB | With provenance | Details for felix_client-0.7.0rc1.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| felix_client-0.7.0rc1-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details for felix_client-0.7.0rc1-cp39-abi3-win_amd64.whl |
| felix_client-0.7.0rc1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ x86-64 | Details for felix_client-0.7.0rc1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
| felix_client-0.7.0rc1-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ ARM64 | Details for felix_client-0.7.0rc1-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
| felix_client-0.7.0rc1-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details for felix_client-0.7.0rc1-cp39-abi3-macosx_11_0_arm64.whl |
| felix_client-0.7.0rc1-cp39-abi3-macosx_10_12_x86_64.whl | CPython 3.9 | abi3 | macOS 10.12+ x86-64 | Details for felix_client-0.7.0rc1-cp39-abi3-macosx_10_12_x86_64.whl |
Total release size: 43.3 MB
Release files / felix_client-0.7.0rc1.tar.gz
| Download URL | felix_client-0.7.0rc1.tar.gz |
|---|---|
| Size | 601.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9fca6d9730fc28942a3d656c9d049f87c2fc5ef44fc79b7b4d52977501ecdb58
|
|
BLAKE2b-256 checksum How to use checksums |
07b9ece3d1275a03b3d46e5d757c5cb1268c92d6c9c142e65f93113429a1496e
|
| 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 Oct 30, 2026.
Transparency logRelease files / felix_client-0.7.0rc1-cp39-abi3-win_amd64.whl
| Download URL | felix_client-0.7.0rc1-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 8.7 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
c6c917cebd6f087535d3909da88fc272a996b8367ce4b6da825353c901cf9903
|
|
BLAKE2b-256 checksum How to use checksums |
9b83ebd70ee62a588f63bdbfc0ed86f5da8b40512c4cac8fe410b8d6a3d67d3e
|
| 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 Oct 30, 2026.
Transparency logRelease files / felix_client-0.7.0rc1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | felix_client-0.7.0rc1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 8.7 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
ceda239e16404e1dd550c659da34b1a97cde37eda88cc8f3831722abdcaf685e
|
|
BLAKE2b-256 checksum How to use checksums |
2e6e9f281da1d7d6007d9806a290ccaa4845306a92ef3b37793245394ccf2033
|
| 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 Oct 30, 2026.
Transparency logRelease files / felix_client-0.7.0rc1-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | felix_client-0.7.0rc1-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 9.0 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
3d7b119c2e3aff8b2bb6c79de1e22a5fbd96c2cc5f0d4ff2e695ff834191cf04
|
|
BLAKE2b-256 checksum How to use checksums |
986c160b9a85f0779a0582e9e03804cda5f64efe0318a4cff66fbff219e016f8
|
| 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 Oct 30, 2026.
Transparency logRelease files / felix_client-0.7.0rc1-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | felix_client-0.7.0rc1-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.0 MB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
4534e315d145b20ef3adc51e441dd98a51105cc1738a56e17304709ee999e62b
|
|
BLAKE2b-256 checksum How to use checksums |
f05a61a038d8f23fa288fbf57cc45136dcd3717d2d6cb2837de0da3cc232b676
|
| 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 Oct 30, 2026.
Transparency logRelease files / felix_client-0.7.0rc1-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | felix_client-0.7.0rc1-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 8.3 MB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
828e6cab92ced2aacf8822c7cf5802d47b5ddaaa75768f0a14c0a2c3822d205c
|
|
BLAKE2b-256 checksum How to use checksums |
b38104fc5b95fe76af4e6075bc5b4fa3147a23d9d5f17bffd7e835988437e3dd
|
| 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 Oct 30, 2026.
Transparency logSecurity for felix-client 0.7.0rc1
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 6 files in this release have been uploaded with provenance metadata.
Attestation for felix_client-0.7.0rc1.tar.gz
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 Oct 30, 2026.
Transparency logA 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.