fila-python

Python client SDK for the Fila message broker.

Installation

pip install fila-python

Usage (Sync)

fromfilaimportClientclient=Client("localhost:5555")
# Enqueue a message.msg_id=client.enqueue("my-queue", {"tenant": "acme"}, b"hello world")
print(f"Enqueued: {msg_id}")
# Consume messages.formsginclient.consume("my-queue"):
print(f"Received: {msg.id} (attempt {msg.attempt_count})")
# Acknowledge successful processing.client.ack("my-queue", msg.id)
client.close()

Usage (Async)

importasynciofromfilaimportAsyncClientasyncdefmain():
asyncwithAsyncClient("localhost:5555") asclient:
msg_id=awaitclient.enqueue("my-queue", {"tenant": "acme"}, b"hello")
asyncformsginawaitclient.consume("my-queue"):
print(f"Received: {msg.id}")
awaitclient.ack("my-queue", msg.id)
asyncio.run(main())

TLS

For servers using certificates from a public CA (e.g., Let's Encrypt), enable TLS with the system trust store:

fromfilaimportClient# TLS using OS system trust store.client=Client("localhost:5555", tls=True)

For servers using a private CA, provide the CA certificate explicitly:

fromfilaimportClient# Read certificates.withopen("ca.pem", "rb") asf:
ca_cert=f.read()
withopen("client.pem", "rb") asf:
client_cert=f.read()
withopen("client-key.pem", "rb") asf:
client_key=f.read()
# TLS with custom CA (server verification).client=Client("localhost:5555", ca_cert=ca_cert)
# Mutual TLS (client + server verification).client=Client(
"localhost:5555",
ca_cert=ca_cert,
client_cert=client_cert,
client_key=client_key,
)

Note: ca_cert implies tls=True -- you don't need to pass both.

API Key Authentication

When the server has API key auth enabled, pass the key to the client:

fromfilaimportClientclient=Client("localhost:5555", api_key="fila_your_api_key_here")
# Combined with TLS:client=Client(
"localhost:5555",
ca_cert=ca_cert,
api_key="fila_your_api_key_here",
)

The API key is sent as authorization: Bearer <key> metadata on every RPC.

API

Client(addr, *, tls=False, ca_cert=None, client_cert=None, client_key=None, api_key=None) / AsyncClient(...)

Connect to a Fila broker. Both support context manager protocol.

client.enqueue(queue, headers, payload) -> str

Enqueue a message. Returns the broker-assigned message ID.

client.consume(queue) -> Iterator[ConsumeMessage]

Open a streaming consumer. Returns an iterator (sync) or async iterator (async) that yields messages as they become available.

client.ack(queue, msg_id)

Acknowledge a successfully processed message. The message is permanently removed.

client.nack(queue, msg_id, error)

Negatively acknowledge a failed message. The message is requeued or routed to the dead-letter queue based on the queue's configuration.

Error Handling

Per-operation exception classes:

fromfilaimportQueueNotFoundError, MessageNotFoundErrortry:
client.enqueue("missing-queue", None, b"test")
exceptQueueNotFoundError:
print("Queue does not exist")
try:
client.ack("my-queue", "missing-id")
exceptMessageNotFoundError:
print("Message does not exist")

License

AGPLv3