Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

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_batch to queue a batch without waiting for the leader
  • Record headers, and publisher and timestamp_micros on 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.8.0rc1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for felix-client 0.8.0rc1
File Size Uploaded Provenance Actions
felix_client-0.8.0rc1.tar.gz 717.8 kB With provenance Details for felix_client-0.8.0rc1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for felix-client 0.8.0rc1
File Actions
felix_client-0.8.0rc1-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for felix_client-0.8.0rc1-cp39-abi3-win_amd64.whl
felix_client-0.8.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.8.0rc1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
felix_client-0.8.0rc1-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.9 abi3 Linux glibc 2.17+ ARM64 Details for felix_client-0.8.0rc1-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
felix_client-0.8.0rc1-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for felix_client-0.8.0rc1-cp39-abi3-macosx_11_0_arm64.whl
felix_client-0.8.0rc1-cp39-abi3-macosx_10_12_x86_64.whl CPython 3.9 abi3 macOS 10.12+ x86-64 Details for felix_client-0.8.0rc1-cp39-abi3-macosx_10_12_x86_64.whl

Total release size: 47.6 MB

Release files / felix_client-0.8.0rc1.tar.gz

Download URL felix_client-0.8.0rc1.tar.gz
Size 717.8 kB
Tags Source
SHA-256 checksum
How to use checksums
e2e8a4a633c5ab5f7efa5bcb54eaa9e07dfb18f3c9d383cf753f15d0dc7d45f1
BLAKE2b-256 checksum
How to use checksums
7ad47539537e628dd9b8349b7d9f18e62b55222d3e2eb7142e6ad20efd94f3ad
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 20, 2026.

Transparency log

Release files / felix_client-0.8.0rc1-cp39-abi3-win_amd64.whl

Download URL felix_client-0.8.0rc1-cp39-abi3-win_amd64.whl
Size 9.7 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
a8cba42bb4b4d6984a8a044e6e6e876d20cda6e8611cebdda9a3a33ad0b7f074
BLAKE2b-256 checksum
How to use checksums
d4142f974891fe5d60afa87a8a809cf74c2160af0950c5280adf9e0148e39558
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 20, 2026.

Transparency log

Release files / felix_client-0.8.0rc1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL felix_client-0.8.0rc1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 9.5 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
35aa9378cb6c31f2c8d806c56efc98eecadac33ff17bfc5fb824b0bc1b7a3402
BLAKE2b-256 checksum
How to use checksums
2c9e9184dbf3c4899a76a567a57fb3312181a7f2943737d2f3e2dcc3bcac7255
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 20, 2026.

Transparency log

Release files / felix_client-0.8.0rc1-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL felix_client-0.8.0rc1-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 9.9 MB
Tags CPython 3.9 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
0c596145dc59272b88e869bd55c6c5e920a3f22eaba54d9785acd555f957a52e
BLAKE2b-256 checksum
How to use checksums
5960d083194755d69da0c11334befc318f54d72921b59e15e439e3e29105031e
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 20, 2026.

Transparency log

Release files / felix_client-0.8.0rc1-cp39-abi3-macosx_11_0_arm64.whl

Download URL felix_client-0.8.0rc1-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
30c8245e4b0d8144f71450dd5ad9e086a63a437627abc3c84a5c309821e3870e
BLAKE2b-256 checksum
How to use checksums
a40d9f5cd2153a3b65cdce92e6e5a90192c69921abfa1708e521e83fdde7139a
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 20, 2026.

Transparency log

Release files / felix_client-0.8.0rc1-cp39-abi3-macosx_10_12_x86_64.whl

Download URL felix_client-0.8.0rc1-cp39-abi3-macosx_10_12_x86_64.whl
Size 9.1 MB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
ea27838c33423e6e7955ae2c762c0d92e2403b86d664b193eaa991b21226b5b3
BLAKE2b-256 checksum
How to use checksums
e22332f764895229a3fa9818a16483a14e3ac57576832b5e000e84a8d7b633a9
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 20, 2026.

Transparency log

Security for felix-client 0.8.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.

Select from 6 files

Attestation for felix_client-0.8.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 Nov 20, 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