felix-client for Python
Felix is a broker that serves streams, work queues and a cache from one replicated log, over QUIC. This is the Python client. It publishes to and reads streams, runs consumer groups, uses the cache and counters, and follows a cluster as brokers fail and shards move. It is a binding over the Rust client, so reconnection, redirects, retry classification and offsets behave as they do there.
Install
pip install felix-client
You import it as felix.
Quick start
Connect, subscribe, publish one record and read it back:
import os
import felix
with felix.Client(
"127.0.0.1:5000", tenant_id="t1", token=os.environ["FELIX_TOKEN"]
) as client:
# Subscribe before publishing: a subscription starts at the stream's tail.
with client.subscribe("t1", "default", "events") as events:
client.publish("t1", "default", "events", b"hello")
event = events.next_event(timeout=5)
if event is None:
raise TimeoutError("no event within 5 seconds")
print(event.payload, event.offset)
To run it you need a running broker, a token for tenant t1, and the stream t1/default/events. The quick start shows how to start a broker, Auth and TLS covers tokens, and felixctl stream create makes the stream.
AsyncClient is the same client for asyncio. Its calls are awaitable and its subscriptions are read with async for:
import os
import felix
async def main() -> None:
async with await felix.AsyncClient.connect(
"127.0.0.1:5000", tenant_id="t1", token=os.environ["FELIX_TOKEN"]
) as client:
async with await client.subscribe("t1", "default", "events") as events:
await client.publish("t1", "default", "events", b"hello")
event = await events.next_event(timeout=5)
if event is None:
raise TimeoutError("no event within 5 seconds")
print(event.payload, event.offset)
Client blocks with the GIL released, which suits threads and scripts. AsyncClient yields to your event loop.
What it covers
- Publish and subscribe, with a log offset on every event of a durable stream
- Sharded streams: routing keys, named shards, and subscribing to every shard
- Consumer groups: poll, acknowledge, retry later, dead letters
- Cache, counters and cache watches
- Atomic commits, conditional writes and head trims
- Idempotent producers, including
hand_off_batchto queue a batch without waiting for the leader - Record headers, and
publisherandtimestamp_microson events - Lease writes (
cache_put_if_lease) - Asking a broker about itself:
inspect_shard,list_subscriptions,topology,shard_owners,stream_routing,cache_shards,supports - Token refresh, cluster discovery, failover and following a shard that moves
Two things in the Rust client are not wrapped: publish_json (Python serializes JSON itself) and a custom quinn transport. A publish without key= puts every record on shard 0.
Configuration
Client(...) and AsyncClient.connect(...) take the same keyword arguments:
| Argument | Meaning |
|---|---|
addrs |
One host:port or a list. Any reachable broker is enough. |
tenant_id |
The tenant to authenticate as. Required. |
token |
A Felix token. |
token_provider |
A function that returns a fresh token. Client takes a plain function or an async def; AsyncClient takes an async def. token is then optional. |
ca_file |
A PEM file of CAs to trust. The system store when omitted. |
server_name |
The name the broker's certificate carries. Default localhost. |
client_cert_file, client_key_file |
The client certificate and its key, as PEM files. |
reconnect_attempts, reconnect_deadline, reconnect_backoff, reconnect_max_backoff |
Retry policy. Times are in seconds. |
publishers, timestamps, record_headers |
Ask brokers for Event.publisher, Event.timestamp_micros, and record headers (on by default). |
tuning |
A ClientTuning with connection pools, windows, queue sizes and timeouts (in seconds). |
TLS is always on, and there is no switch to skip verification. A development broker with a self-signed certificate needs its CA file: set FELIX_TLS_CERT_EXPORT=/path/ca.pem on the broker and pass that path as ca_file. A broker started with FELIX_TLS_CLIENT_CA also requires a client certificate. Give the certificate and its key as two PEM files, both or neither.
A token lasts 15 minutes by default. A process that runs longer passes token_provider so the client can fetch a new one. Auth and TLS lists the same options for every client.
Errors
Every error is a felix.FelixError, with code, retry and detail when the broker sent them:
try:
client.publish("t1", "default", "events", b"hello")
except felix.OutcomeUnknownError:
... # the record may have been written; reconcile before sending it again
except felix.AuthError:
... # the token was refused; retrying will not help
except felix.FelixError as err:
if err.retry in ("retry", "retry_after", "redirect"):
... # nothing was applied
The other classes are ConnectionError, ShardUnavailableError, OverloadedError, NotFoundError, CursorError, CommitError (with NotOnOwningShardError and EventCountError), TrimError and PublishRefusedError. The client already retries what is safe to retry. Do not match on the message text. Errors across clients maps every code to the type each client raises.
Supported platforms
Python 3.9 or newer. Wheels are built for Linux (x86-64 and arm64), macOS (Intel and Apple silicon) and Windows (x86-64), and need no Rust toolchain. Other platforms build from the source distribution, which does.
Documentation
License
Apache-2.0.
Metadata
Release files for felix-client 0.7.2
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.2.tar.gz | 695.1 kB | With provenance | Details for felix_client-0.7.2.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| felix_client-0.7.2-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details for felix_client-0.7.2-cp39-abi3-win_amd64.whl |
| felix_client-0.7.2-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.2-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
| felix_client-0.7.2-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ ARM64 | Details for felix_client-0.7.2-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
| felix_client-0.7.2-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details for felix_client-0.7.2-cp39-abi3-macosx_11_0_arm64.whl |
| felix_client-0.7.2-cp39-abi3-macosx_10_12_x86_64.whl | CPython 3.9 | abi3 | macOS 10.12+ x86-64 | Details for felix_client-0.7.2-cp39-abi3-macosx_10_12_x86_64.whl |
Total release size: 47.3 MB
Release files / felix_client-0.7.2.tar.gz
| Download URL | felix_client-0.7.2.tar.gz |
|---|---|
| Size | 695.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a8da29aff19c5b32dbb8eddd18a4e02f96fadb4451e2900e184b36d3d4723c09
|
|
BLAKE2b-256 checksum How to use checksums |
5e9badd2db8af565835f2cd314c2aafb28b4a3386bca1a30e6a7d1755c2e09b0
|
| 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 logRelease files / felix_client-0.7.2-cp39-abi3-win_amd64.whl
| Download URL | felix_client-0.7.2-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 9.7 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
81f1d631d3fba9b26639b5dd441fef307f63f45af07da49b5a3b4b059771fc13
|
|
BLAKE2b-256 checksum How to use checksums |
442a8768cd880b0495a4ddbf82eb1c88d4b6180090bf05447643435bb1e481a6
|
| 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 logRelease files / felix_client-0.7.2-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | felix_client-0.7.2-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 9.4 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
8ddf4840343102665225dd3c243b95bfc2605e35ad6b172f9df0a6dfd73ebd8f
|
|
BLAKE2b-256 checksum How to use checksums |
4046c0b0f7a2ea74ee91650fcb82235d0da96158902a60491037214ffca98ea0
|
| 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 logRelease files / felix_client-0.7.2-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | felix_client-0.7.2-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 9.8 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
b17ddd46a278b1875faea83e8ce0168b552652afa2e2ad3eb0a4a68913d2fb9e
|
|
BLAKE2b-256 checksum How to use checksums |
c9f59c3309ddf81cddcdc4d162a5c8dc85a2090a72c918cf7ddc57da208fcb46
|
| 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 logRelease files / felix_client-0.7.2-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | felix_client-0.7.2-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.8 MB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
1a39fee95b8ba868ffd62d5b3c15b8e64b37fa909840685137f53e3c3e20df55
|
|
BLAKE2b-256 checksum How to use checksums |
41ec7b0364a26599ae66c3c7e42faf1e0674cb594278d095af8e633aa7350d5f
|
| 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 logRelease files / felix_client-0.7.2-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | felix_client-0.7.2-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 9.0 MB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
fbd75e87c82d5a550968f961e555588584ca664f3d141ba1d74bedbb4c4282ae
|
|
BLAKE2b-256 checksum How to use checksums |
3dc3f72a148a0f6962a4b9d9ed0dc0a4d9bde218dcf6a93cce1327053e9b70fd
|
| 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 logSecurity for felix-client 0.7.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 6 files in this release have been uploaded with provenance metadata.
Attestation for felix_client-0.7.2.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 Nov 12, 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.