taskferry-events

Portable pub/sub and fan-out event delivery. Ships alongside Taskferry, the portable execution layer. Plain Python, no Django required.

An Event declares that something happened and may have zero or more consumers — the opposite of a Task, which is one operation to run. Modeled on CloudEvents.

pip install taskferry-events            # in-memory bus
pip install taskferry-events[gcp]       # + Google Cloud Pub/Sub

Usage

from taskferry_events import Event, publishers

publishers["default"].publish(
    Event(type="file.uploaded", source="urn:svc:uploads", data={"file_id": "42"})
)

Fan-out with the in-process bus:

from taskferry_events import InMemoryEventBus, Event

bus = InMemoryEventBus()
bus.subscribe(lambda e: print("billing", e.data), event_type="order.placed")
bus.subscribe(lambda e: print("analytics", e.data))  # sees everything
bus.publish(Event(type="order.placed", source="urn:shop", data={"total": 10}))

Configure a provider publisher (lazy — no SDK imported until first use):

from taskferry_events import publishers

publishers.configure(
    {
        "default": {
            "factory": "taskferry_events.adapters.gcp:make_pubsub_publisher",
            "project": "my-proj",
            "topic": "domain-events",
            "ordering": True,
        },
    }
)

Task vs Event

Task  → one operation to execute       (~1 consumer)
Event → a fact that happened           (0..N consumers, fan-out)

Capabilities

Adapters advertise what they support (fanout, ordering, delivery_retry, dead_letter, filtering, replay, retention). Requesting replay on a backend that lacks it raises UnsupportedCapabilityError.

Roadmap: NATS, RabbitMQ.

Delivery semantics

At-least-once with possible duplicates (ADR-0010). Consumers must be idempotent.

License

Apache-2.0.