python_outbox_core.repository

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

IOutboxRepository

Abstract repository for outbox event persistence.

Module Contents

class python_outbox_core.repository.IOutboxRepository

Bases: 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.

abstract add_event(event: python_outbox_core.events.IOutboxEvent) → None
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

abstract get_unpublished(limit: int = 100, offset: int = 0) → List[python_outbox_core.events.IOutboxEvent]
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

abstract mark_published(event_id: uuid.UUID) → None
Async:

Mark event as successfully published to Kafka.

Args:

event_id: ID of the published event

Raises:

DatabaseError: On update failures

abstract count_unpublished() → int
Async:

Count pending events for monitoring.

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

Returns:

Number of unpublished events

abstract mark_failed(event_id: uuid.UUID, error_message: str) → None
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