Quickstart: build on the event runtime

If you're starting a new consumer, or don't mind adopting a small framework, pymidil's event runtime gives you retries, dead-lettering, and idempotency out of the box. Telemetry to Observatory comes along for free, and dashboard control is honored automatically.

Before you start

You'll need an API key scoped to telemetry. Any admin can create one under Organization settings → API Keys. Keep it secret and treat it like a password.

1
Install the SDK
pip install "pymidil[auth,aws]"

Write a subscriber

A subscriber is a class with a handle method. Raise RetryableEventError for anything that should be retried. Any other exception sends the event straight to the dead-letter queue:

from pymidil.event import EventSubscriber
from pymidil.event.exceptions import RetryableEventError

class OrderSubscriber(EventSubscriber):
  async def handle(self, event) -> None:
      if upstream_busy():
          raise RetryableEventError("throttled")  # redelivered with backoff
      await process(event)  # any other error → dead-lettered

Wire up a consumer

Create an SQSConsumer pointed at your queue, attach telemetry, and subscribe your handler:

from pymidil.event import SQSConsumer, SQSConsumerEventConfig, TelemetryDispatchHook
from pymidil.event.observability.sinks.http import HttpTelemetrySink

consumer = SQSConsumer(SQSConsumerEventConfig(
  type="sqs",
  queue_url="https://sqs.us-east-1.amazonaws.com/123456789012/orders",
  dlq_url="https://sqs.us-east-1.amazonaws.com/123456789012/orders-dlq",
))
consumer.add_hook(TelemetryDispatchHook(
  HttpTelemetrySink("https://api.midil.io", api_key="mo_your_api_key"),
  source_service="orders-svc",
  broker="sqs",
))
consumer.subscribe(OrderSubscriber())

Dashboard pause/throttle/drain is honored automatically for the built-in consumers, no extra code needed. See [Consumer control](/sdks/python/guides/consumer-control) for how it works.

4
Add idempotency (optional, recommended)
Protect an event type from being processed twice on redelivery:
from pymidil.event.idempotency import IdempotencyPolicy, InMemoryIdempotencyStore consumer.use_idempotency(IdempotencyPolicy(InMemoryIdempotencyStore()))
See [Idempotency & duplicates](/sdks/python/guides/idempotency-and-duplicates) for keying your own events and for a Redis-backed store across multiple instances.
5
Start the consumer
await consumer.start()
6
Check the dashboard
Open Overview. Your first event should appear within moments.

If you'd rather manage several producers/consumers together with named routing instead of wiring each one by hand, EventBus provides that orchestration on top of the same classes. See Examples.

What's next​

What's next