python_outbox_core.events
=========================

.. py:module:: python_outbox_core.events

.. autoapi-nested-parse::

   Base interface for outbox events.

   Best Practices Applied:
   1. ABC for contract enforcement
   2. Pydantic for validation & serialization
   3. Standard event metadata (CloudEvents-inspired)
   4. Type safety with generics
   5. Immutability encouraged (frozen=True optional)

   References:
   - CloudEvents spec: https://cloudevents.io/
   - Domain Event pattern: https://martinfowler.com/eaaDev/DomainEvent.html



Classes
-------

.. autoapisummary::

   python_outbox_core.events.IOutboxEvent


Module Contents
---------------

.. py:class:: IOutboxEvent

   Bases: :py:obj:`pydantic.BaseModel`, :py:obj:`abc.ABC`


   Abstract base for all outbox events.

   Enforces event metadata standards and serialization contract.
   Projects extend this for domain-specific events.

   Metadata fields follow CloudEvents specification for interoperability.


   .. py:attribute:: event_id
      :type:  uuid.UUID

      Unique identifier for this event (idempotency key).



   .. py:attribute:: event_type
      :type:  str

      Event type in reverse-DNS format (e.g. 'com.gridflow.invite.created').



   .. py:attribute:: aggregate_id
      :type:  str

      ID of the aggregate root that produced this event.



   .. py:attribute:: occurred_at
      :type:  datetime.datetime

      When the event occurred (domain time, not system time).



   .. py:attribute:: source
      :type:  str

      Service/application that produced this event (e.g. 'user-service').



   .. py:attribute:: data_version
      :type:  str
      :value: '1.0'


      Event schema version for evolution/compatibility (semver recommended).



   .. py:attribute:: correlation_id
      :type:  uuid.UUID | None
      :value: None


      Links related events across service boundaries.



   .. py:attribute:: causation_id
      :type:  uuid.UUID | None
      :value: None


      ID of the event/command that caused this event.



   .. py:method:: to_message() -> dict[str, Any]
      :abstractmethod:


      Serialize event to Kafka message format.

      Must return a JSON-serializable dict for publishing.
      Override to customize serialization (e.g., omit fields, transform data).



   .. py:method:: get_partition_key() -> str

      Return partition key for Kafka routing.

      Default: aggregate_id (natural partition key).
      Override for custom routing (e.g., user_id, tenant_id).

      Best practice: Use 3-10 topics with partition keys,
      NOT hundreds of topics per entity.

      Returns:
          Partition key string for Kafka producer



   .. py:class:: Config

      Pydantic config for event models.


      .. py:attribute:: json_encoders