python_outbox_core.repository
=============================

.. py:module:: python_outbox_core.repository

.. autoapi-nested-parse::

   Repository interface for outbox persistence.

   Best Practices Applied:
   1. Repository pattern for data access abstraction
   2. Async/await for non-blocking I/O
   3. Batch operations for performance
   4. Pagination support
   5. Compatible with SQLAlchemy's Unit of Work (AsyncSession)

   References:
   - Repository pattern: https://martinfowler.com/eaaCatalog/repository.html
   - Unit of Work: https://martinfowler.com/eaaCatalog/unitOfWork.html



Classes
-------

.. autoapisummary::

   python_outbox_core.repository.IOutboxRepository


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

.. py:class:: IOutboxRepository

   Bases: :py:obj:`abc.ABC`


   Abstract repository for outbox event persistence.

   Implementations use SQLAlchemy AsyncSession for actual DB operations.
   This interface is intentionally minimal - projects extend as needed.


   .. py:method:: add_event(event: python_outbox_core.events.IOutboxEvent) -> None
      :abstractmethod:

      :async:


      Add event to outbox table.

      IMPORTANT: Does NOT commit transaction.
      Caller must commit via AsyncSession for atomicity.

      Args:
          event: Domain event to store in outbox

      Raises:
          DatabaseError: On persistence failures



   .. py:method:: get_unpublished(limit: int = 100, offset: int = 0) -> List[python_outbox_core.events.IOutboxEvent]
      :abstractmethod:

      :async:


      Fetch unpublished events for worker processing.

      Args:
          limit: Max events to return (batch size)
          offset: Pagination offset

      Returns:
          List of unpublished events, ordered by occurred_at ASC



   .. py:method:: mark_published(event_id: uuid.UUID) -> None
      :abstractmethod:

      :async:


      Mark event as successfully published to Kafka.

      Args:
          event_id: ID of the published event

      Raises:
          DatabaseError: On update failures



   .. py:method:: count_unpublished() -> int
      :abstractmethod:

      :async:


      Count pending events for monitoring.

      Used for:
      - Health checks
      - Alerting on lag
      - Capacity planning

      Returns:
          Number of unpublished events



   .. py:method:: mark_failed(event_id: uuid.UUID, error_message: str) -> None
      :abstractmethod:

      :async:


      Mark event as permanently failed (Dead Letter Queue).

      Used when:
      - Event cannot be published after max retries
      - Event payload is invalid
      - Broker rejects the event

      Args:
          event_id: ID of the failed event
          error_message: Why it failed (for debugging)

      Raises:
          DatabaseError: On update failures