python_outbox_core.adapters.examples.kafka_routing¶

Kafka partition key routing example.

EDUCATIONAL EXAMPLE - NOT production-ready. Demonstrates “Few Topics + Partition Keys” best practice.

Best Practices (from PRD): - Use 3-10 topics (not hundreds per user/interest) - Route via partition keys (get_partition_key() method) - Filter in consumers (interests, content_type in metadata) - AVOID anti-pattern: separate topics per entity

Classes¶

`PartitionKeyRouter`	Example: Route events to Kafka partitions by key.
`KafkaRoutingFormatter`	Example: CloudEvents formatter with Kafka routing metadata.

Module Contents¶

class python_outbox_core.adapters.examples.kafka_routing.PartitionKeyRouter(topic_prefix: str, default_topic: str = 'domain-events')¶

Example: Route events to Kafka partitions by key.

Uses event.get_partition_key() for consistent partition routing. Same aggregate_id always goes to same partition (ordering).

Example:

>>> router = PartitionKeyRouter(topic_prefix="gridflow")
>>> topic, key = router.route(event)
>>> # topic = "gridflow.domain-events"
>>> # key = "invite-123"  (from aggregate_id)

topic_prefix¶

default_topic = 'domain-events'¶

route(event: python_outbox_core.events.IOutboxEvent) → tuple¶

Determine topic and partition key for event.

Args:: event: Outbox event to route
Returns:: Tuple of (topic_name, partition_key)

class python_outbox_core.adapters.examples.kafka_routing.KafkaRoutingFormatter(source: str, topic_prefix: str = 'app', default_topic: str = 'domain-events')¶

Bases: python_outbox_core.formatters.CloudEventsFormatter

Example: CloudEvents formatter with Kafka routing metadata.

Adds partition key and topic hint to CloudEvent metadata.

Example:

>>> formatter = KafkaRoutingFormatter(
...     source="gridflow-api",
...     topic_prefix="gridflow"
... )
>>> formatted = formatter.format(event)

enrich_metadata(event_data: Dict[str, Any]) → Dict[str, Any]¶: Add Kafka routing metadata to CloudEvent.