python-cqrs 5.0.0__py3-none-any.whl → 5.1.0__py3-none-any.whl

cqrs/__init__.py

@@ -12,6 +12,7 @@ if typing.TYPE_CHECKING:
         SqlAlchemyOutboxedEventRepository,
         rebind_outbox_model,
     )
+    from cqrs.outbox.sqlmodel import SqlModelOutboxedEventRepository
     from cqrs.sqlalchemy_types import (
         Binary16,
         DialectAwareType,
@@ -129,6 +130,7 @@ __all__ = (
     "PydanticResponse",
     "OutboxedEventRepository",
     "SqlAlchemyOutboxedEventRepository",
+    "SqlModelOutboxedEventRepository",
     "EventProducer",
     "EventSerializer",
     "EventCodec",
@@ -187,6 +189,13 @@ _LAZY_SQLALCHEMY = {
     "PayloadBinary": ("cqrs.sqlalchemy_types", "PayloadBinary"),
 }
 
+_LAZY_SQLMODEL = {
+    "SqlModelOutboxedEventRepository": (
+        "cqrs.outbox.sqlmodel",
+        "SqlModelOutboxedEventRepository",
+    ),
+}
+
 
 def __getattr__(name: str) -> typing.Any:
     if name in _LAZY_PYDANTIC:
@@ -201,4 +210,9 @@ def __getattr__(name: str) -> typing.Any:
         # ImportError message is raised by the sqlalchemy modules themselves.
         module = __import__(module_name, fromlist=[attr])
         return getattr(module, attr)
+    if name in _LAZY_SQLMODEL:
+        module_name, attr = _LAZY_SQLMODEL[name]
+        # ImportError message is raised by the sqlmodel modules themselves.
+        module = __import__(module_name, fromlist=[attr])
+        return getattr(module, attr)
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

cqrs/outbox/sqlalchemy.py

@@ -173,11 +173,13 @@ class SqlAlchemyOutboxedEventRepository(repository.OutboxedEventRepository):
         *,
         serializer: EventCodec | None = None,
         event_map: map.OutboxedEventMap | None = None,
+        model: typing.Any = None,
     ):
         self.session = session
         self._compressor = compressor
         self._serializer = serializer or JsonEventSerializer()
         self._event_map = event_map if event_map is not None else map.OutboxedEventMap
+        self._model = OutboxModel if model is None else model
 
     def _resolve_codec(self, event_name: str) -> EventCodec:
         return self._event_map.get_serializer(event_name) or self._serializer
@@ -211,7 +213,7 @@ class SqlAlchemyOutboxedEventRepository(repository.OutboxedEventRepository):
             bytes_payload = self._compressor.compress(bytes_payload)
 
         self.session.add(
-            OutboxModel(
+            self._model(
                 event_id=event.event_id,
                 event_id_bin=event.event_id.bytes,
                 event_name=event.event_name,
@@ -221,7 +223,7 @@ class SqlAlchemyOutboxedEventRepository(repository.OutboxedEventRepository):
             ),
         )
 
-    def _process_events(self, model: OutboxModel) -> repository.OutboxedEvent | None:
+    def _process_events(self, model: typing.Any) -> repository.OutboxedEvent | None:
         event_dict = model.row_to_dict()
         event_name = event_dict["event_name"]
 
@@ -260,8 +262,8 @@ class SqlAlchemyOutboxedEventRepository(repository.OutboxedEventRepository):
         batch_size: int = 100,
         topic: typing.Text | None = None,
     ) -> typing.List[repository.OutboxedEvent]:
-        events: typing.Sequence[OutboxModel] = (
-            (await self.session.execute(OutboxModel.get_batch_query(batch_size, topic))).scalars().all()
+        events: typing.Sequence[typing.Any] = (
+            (await self.session.execute(self._model.get_batch_query(batch_size, topic))).scalars().all()
         )
 
         result = []
@@ -285,7 +287,7 @@ class SqlAlchemyOutboxedEventRepository(repository.OutboxedEventRepository):
         new_status: repository.EventStatus,
     ) -> None:
         await self.session.execute(
-            statement=OutboxModel.update_status_query(outboxed_event_id, new_status),
+            statement=self._model.update_status_query(outboxed_event_id, new_status),
         )
 
     async def commit(self):

cqrs/outbox/sqlmodel.py

@@ -0,0 +1,189 @@
+"""SQLModel outbox: same table, queries, and repository behavior as SQLAlchemy."""
+
+import datetime
+import typing
+import uuid
+
+from cqrs import compressors
+from cqrs.mapping import outbox as map
+from cqrs.outbox import repository
+from cqrs.serializers.protocol import EventCodec
+
+try:
+    from cqrs.outbox.sqlalchemy import (
+        MAX_FLUSH_COUNTER_VALUE,
+        BinaryUUID,
+        OutboxModel as SqlAlchemyOutboxModel,
+        SqlAlchemyOutboxedEventRepository,
+        rebind_outbox_model,
+    )
+
+    import sqlalchemy
+    from sqlalchemy import func
+    from sqlmodel import Field
+    from sqlmodel.ext.asyncio.session import AsyncSession
+
+    from cqrs import sqlalchemy_types
+    from cqrs.sqlmodel_base import CqrsSQLModel, SqlAlchemyExecuteSession
+except ImportError:
+    raise ImportError(
+        "You are trying to use the SQLModel outbox implementation, "
+        "but 'sqlmodel' is not installed. "
+        "Please install it using: pip install python-cqrs[sqlmodel]",
+    ) from None
+
+Base = CqrsSQLModel
+
+DEFAULT_OUTBOX_TABLE_NAME = "outbox"
+
+
+class OutboxModel(Base, table=True):
+    __tablename__ = DEFAULT_OUTBOX_TABLE_NAME  # type: ignore[assignment]
+
+    __table_args__ = (
+        sqlalchemy.UniqueConstraint(
+            "event_id_bin",
+            "event_name",
+            name="event_id_unique_index",
+        ),
+    )
+
+    id: int | None = Field(
+        default=None,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.BigInteger,
+            sqlalchemy.Identity(),
+            primary_key=True,
+            nullable=False,
+            autoincrement=True,
+            comment="Identity",
+        ),
+    )
+    event_id: uuid.UUID = Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy_types.UUIDBinary,
+            nullable=False,
+            comment="Event idempotency id",
+        ),
+    )
+    event_id_bin: bytes = Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy_types.Binary16,
+            nullable=False,
+            comment="Event idempotency id in 16 bit presentation",
+        ),
+    )
+    event_status: repository.EventStatus = Field(
+        default=repository.EventStatus.NEW,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.Enum(repository.EventStatus),
+            nullable=False,
+            default=repository.EventStatus.NEW,
+            comment="Event producing status",
+        ),
+    )
+    flush_counter: int = Field(
+        default=0,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.SmallInteger,
+            nullable=False,
+            default=0,
+            comment="Event producing flush counter",
+        ),
+    )
+    event_name: str = Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.String(255),
+            nullable=False,
+            comment="Event name",
+        ),
+    )
+    topic: str = Field(
+        default="",
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.String(255),
+            nullable=False,
+            default="",
+            comment="Event topic",
+        ),
+    )
+    created_at: datetime.datetime | None = Field(
+        default=None,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.DateTime,
+            nullable=False,
+            server_default=func.now(),
+            comment="Event creation timestamp",
+        ),
+    )
+    payload: bytes = Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy_types.PayloadBinary,
+            nullable=False,
+            comment="Event payload",
+        ),
+    )
+
+    def row_to_dict(self) -> typing.Dict[typing.Text, typing.Any]:
+        table = typing.cast(typing.Any, self).__table__
+        return {column.name: getattr(self, column.name) for column in table.columns}
+
+    @classmethod
+    def get_batch_query(
+        cls,
+        size: int,
+        topic: typing.Text | None = None,
+    ) -> sqlalchemy.Select:
+        query = SqlAlchemyOutboxModel.get_batch_query
+        return query.__func__(cls, size, topic)  # type: ignore[attr-defined]
+
+    @classmethod
+    def update_status_query(
+        cls,
+        outboxed_event_id: int,
+        status: repository.EventStatus,
+    ) -> sqlalchemy.Update:
+        query = SqlAlchemyOutboxModel.update_status_query
+        return query.__func__(cls, outboxed_event_id, status)  # type: ignore[attr-defined]
+
+    @classmethod
+    def status_sorting_case(cls) -> sqlalchemy.Case:
+        query = SqlAlchemyOutboxModel.status_sorting_case
+        return query.__func__(cls)  # type: ignore[attr-defined]
+
+
+class SqlModelOutboxedEventRepository(SqlAlchemyOutboxedEventRepository):
+    """Outbox repository that stores rows as SQLModel ``OutboxModel`` instances.
+
+    Pass a ``sqlmodel.ext.asyncio.session.AsyncSession``. Behavior matches
+    ``SqlAlchemyOutboxedEventRepository``: the same batch query, flush budget,
+    status ordering, codecs, and compressor hooks.
+    """
+
+    def __init__(
+        self,
+        session: AsyncSession,
+        compressor: compressors.Compressor | None = None,
+        *,
+        serializer: EventCodec | None = None,
+        event_map: map.OutboxedEventMap | None = None,
+    ):
+        super().__init__(
+            typing.cast(typing.Any, SqlAlchemyExecuteSession(session)),
+            compressor,
+            serializer=serializer,
+            event_map=event_map,
+            model=OutboxModel,
+        )
+
+
+__all__ = (
+    "AsyncSession",
+    "Base",
+    "BinaryUUID",
+    "DEFAULT_OUTBOX_TABLE_NAME",
+    "MAX_FLUSH_COUNTER_VALUE",
+    "OutboxModel",
+    "SqlModelOutboxedEventRepository",
+    "rebind_outbox_model",
+)

cqrs/saga/storage/sqlalchemy.py

@@ -145,14 +145,23 @@ class SagaLogModel(Base):
 class _SqlAlchemySagaStorageRun(SagaStorageRun):
     """Scoped run: one session, no commit inside methods; caller calls commit()."""
 
-    def __init__(self, session: AsyncSession) -> None:
+    def __init__(
+        self,
+        session: AsyncSession,
+        execution_model: type[typing.Any] = SagaExecutionModel,
+        log_model: type[typing.Any] = SagaLogModel,
+    ) -> None:
         """
         Initialize the run wrapper with an async SQLAlchemy session.
 
         Parameters:
             session (AsyncSession): The AsyncSession instance scoped to this run, used for all database operations.
+            execution_model: Mapped class for saga execution rows. Defaults to the SQLAlchemy model.
+            log_model: Mapped class for saga log rows. Defaults to the SQLAlchemy model.
         """
         self._session = session
+        self._execution_model = execution_model
+        self._log_model = log_model
 
     async def create_saga(
         self,
@@ -170,7 +179,7 @@ class _SqlAlchemySagaStorageRun(SagaStorageRun):
             name (str): Human-readable name of the saga.
             context (dict[str, Any]): Initial saga context to be stored (will be serialized to the model's JSON column).
         """
-        execution = SagaExecutionModel(
+        execution = self._execution_model(
             id=saga_id,
             name=name,
             status=SagaStatus.PENDING,
@@ -197,20 +206,20 @@ class _SqlAlchemySagaStorageRun(SagaStorageRun):
         Raises:
             SagaConcurrencyError: If an optimistic version check fails (indicating a concurrent modification) or if the saga does not exist when a version was supplied.
         """
-        stmt = sqlalchemy.update(SagaExecutionModel).where(
-            SagaExecutionModel.id == saga_id,
+        stmt = sqlalchemy.update(self._execution_model).where(
+            self._execution_model.id == saga_id,
         )
         if current_version is not None:
-            stmt = stmt.where(SagaExecutionModel.version == current_version)
+            stmt = stmt.where(self._execution_model.version == current_version)
         stmt = stmt.values(
             context=context,
-            version=SagaExecutionModel.version + 1,
+            version=self._execution_model.version + 1,
         )
         result = await self._session.execute(stmt)
         if result.rowcount == 0:  # type: ignore[attr-defined]
             if current_version is not None:
-                check_stmt = sqlalchemy.select(SagaExecutionModel.id).where(
-                    SagaExecutionModel.id == saga_id,
+                check_stmt = sqlalchemy.select(self._execution_model.id).where(
+                    self._execution_model.id == saga_id,
                 )
                 check_result = await self._session.execute(check_stmt)
                 if check_result.scalar_one_or_none():
@@ -240,11 +249,11 @@ class _SqlAlchemySagaStorageRun(SagaStorageRun):
             SagaConcurrencyError: If no row was updated (saga does not exist or was modified concurrently).
         """
         result = await self._session.execute(
-            sqlalchemy.update(SagaExecutionModel)
-            .where(SagaExecutionModel.id == saga_id)
+            sqlalchemy.update(self._execution_model)
+            .where(self._execution_model.id == saga_id)
             .values(
                 status=status,
-                version=SagaExecutionModel.version + 1,
+                version=self._execution_model.version + 1,
             ),
         )
         if result.rowcount == 0:  # pyright: ignore[reportAttributeAccessIssue]
@@ -270,7 +279,7 @@ class _SqlAlchemySagaStorageRun(SagaStorageRun):
             status (SagaStepStatus): The step's outcome status.
             details (str | None): Optional free-form details or error message associated with the step.
         """
-        log_entry = SagaLogModel(
+        log_entry = self._log_model(
             saga_id=saga_id,
             step_name=step_name,
             action=action,
@@ -298,8 +307,8 @@ class _SqlAlchemySagaStorageRun(SagaStorageRun):
         Raises:
             ValueError: If no saga with the given id exists.
         """
-        stmt = sqlalchemy.select(SagaExecutionModel).where(
-            SagaExecutionModel.id == saga_id,
+        stmt = sqlalchemy.select(self._execution_model).where(
+            self._execution_model.id == saga_id,
         )
         if read_for_update:
             stmt = stmt.with_for_update()
@@ -330,7 +339,9 @@ class _SqlAlchemySagaStorageRun(SagaStorageRun):
             is normalized to UTC if not already timezone-aware.
         """
         result = await self._session.execute(
-            sqlalchemy.select(SagaLogModel).where(SagaLogModel.saga_id == saga_id).order_by(SagaLogModel.created_at),
+            sqlalchemy.select(self._log_model)
+            .where(self._log_model.saga_id == saga_id)
+            .order_by(self._log_model.created_at),
         )
         rows = result.scalars().all()
         return [
@@ -367,14 +378,24 @@ class _SqlAlchemySagaStorageRun(SagaStorageRun):
 
 
 class SqlAlchemySagaStorage(ISagaStorage):
-    def __init__(self, session_factory: async_sessionmaker[AsyncSession]):
+    def __init__(
+        self,
+        session_factory: async_sessionmaker[AsyncSession],
+        *,
+        execution_model: type[typing.Any] = SagaExecutionModel,
+        log_model: type[typing.Any] = SagaLogModel,
+    ):
         """
         Initialize the SQLAlchemy-based saga storage with a factory for creating async sessions.
 
         Parameters:
             session_factory (async_sessionmaker[AsyncSession]): Factory that produces new AsyncSession instances used for each storage run and operation.
+            execution_model: Mapped class for saga execution rows. Defaults to the SQLAlchemy model.
+            log_model: Mapped class for saga log rows. Defaults to the SQLAlchemy model.
         """
         self.session_factory = session_factory
+        self._execution_model = execution_model
+        self._log_model = log_model
 
     def create_run(
         self,
@@ -391,7 +412,11 @@ class SqlAlchemySagaStorage(ISagaStorage):
         @contextlib.asynccontextmanager
         async def _run() -> typing.AsyncGenerator[SagaStorageRun, None]:
             async with self.session_factory() as session:
-                run = _SqlAlchemySagaStorageRun(session)
+                run = _SqlAlchemySagaStorageRun(
+                    session,
+                    self._execution_model,
+                    self._log_model,
+                )
                 try:
                     yield run
                 except BaseException:
@@ -422,7 +447,7 @@ class SqlAlchemySagaStorage(ISagaStorage):
         """
         async with self.session_factory() as session:
             try:
-                execution = SagaExecutionModel(
+                execution = self._execution_model(
                     id=saga_id,
                     name=name,
                     status=SagaStatus.PENDING,
@@ -444,14 +469,14 @@ class SqlAlchemySagaStorage(ISagaStorage):
     ) -> None:
         async with self.session_factory() as session:
             try:
-                stmt = sqlalchemy.update(SagaExecutionModel).where(
-                    SagaExecutionModel.id == saga_id,
+                stmt = sqlalchemy.update(self._execution_model).where(
+                    self._execution_model.id == saga_id,
                 )
                 if current_version is not None:
-                    stmt = stmt.where(SagaExecutionModel.version == current_version)
+                    stmt = stmt.where(self._execution_model.version == current_version)
                 stmt = stmt.values(
                     context=context,
-                    version=SagaExecutionModel.version + 1,
+                    version=self._execution_model.version + 1,
                 )
 
                 result = await session.execute(stmt)
@@ -462,8 +487,8 @@ class SqlAlchemySagaStorage(ISagaStorage):
                     # But for now, we assume if rowcount is 0 and we checked version, it's concurrency
                     if current_version is not None:
                         # Double check if saga exists
-                        check_stmt = sqlalchemy.select(SagaExecutionModel.id).where(
-                            SagaExecutionModel.id == saga_id,
+                        check_stmt = sqlalchemy.select(self._execution_model.id).where(
+                            self._execution_model.id == saga_id,
                         )
                         check_result = await session.execute(check_stmt)
                         if check_result.scalar_one_or_none():
@@ -492,11 +517,11 @@ class SqlAlchemySagaStorage(ISagaStorage):
         async with self.session_factory() as session:
             try:
                 await session.execute(
-                    sqlalchemy.update(SagaExecutionModel)
-                    .where(SagaExecutionModel.id == saga_id)
+                    sqlalchemy.update(self._execution_model)
+                    .where(self._execution_model.id == saga_id)
                     .values(
                         status=status,
-                        version=SagaExecutionModel.version + 1,
+                        version=self._execution_model.version + 1,
                     ),
                 )
                 await session.commit()
@@ -514,7 +539,7 @@ class SqlAlchemySagaStorage(ISagaStorage):
     ) -> None:
         async with self.session_factory() as session:
             try:
-                log_entry = SagaLogModel(
+                log_entry = self._log_model(
                     saga_id=saga_id,
                     step_name=step_name,
                     action=action,
@@ -534,8 +559,8 @@ class SqlAlchemySagaStorage(ISagaStorage):
         read_for_update: bool = False,
     ) -> tuple[SagaStatus, dict[str, typing.Any], int]:
         async with self.session_factory() as session:
-            stmt = sqlalchemy.select(SagaExecutionModel).where(
-                SagaExecutionModel.id == saga_id,
+            stmt = sqlalchemy.select(self._execution_model).where(
+                self._execution_model.id == saga_id,
             )
             if read_for_update:
                 stmt = stmt.with_for_update()
@@ -560,9 +585,9 @@ class SqlAlchemySagaStorage(ISagaStorage):
     ) -> list[SagaLogEntry]:
         async with self.session_factory() as session:
             result = await session.execute(
-                sqlalchemy.select(SagaLogModel)
-                .where(SagaLogModel.saga_id == saga_id)
-                .order_by(SagaLogModel.created_at),
+                sqlalchemy.select(self._log_model)
+                .where(self._log_model.saga_id == saga_id)
+                .order_by(self._log_model.created_at),
             )
             rows = result.scalars().all()
 
@@ -596,20 +621,20 @@ class SqlAlchemySagaStorage(ISagaStorage):
         )
         async with self.session_factory() as session:
             stmt = (
-                sqlalchemy.select(SagaExecutionModel.id)
-                .where(SagaExecutionModel.status.in_(recoverable))
-                .where(SagaExecutionModel.recovery_attempts < max_recovery_attempts)
+                sqlalchemy.select(self._execution_model.id)
+                .where(self._execution_model.status.in_(recoverable))
+                .where(self._execution_model.recovery_attempts < max_recovery_attempts)
             )
             if saga_name is not None:
-                stmt = stmt.where(SagaExecutionModel.name == saga_name)
+                stmt = stmt.where(self._execution_model.name == saga_name)
             if stale_after_seconds is not None:
                 threshold = datetime.datetime.now(
                     datetime.timezone.utc,
                 ) - datetime.timedelta(
                     seconds=stale_after_seconds,
                 )
-                stmt = stmt.where(SagaExecutionModel.updated_at < threshold)
-            stmt = stmt.order_by(SagaExecutionModel.updated_at.asc()).limit(limit)
+                stmt = stmt.where(self._execution_model.updated_at < threshold)
+            stmt = stmt.order_by(self._execution_model.updated_at.asc()).limit(limit)
             result = await session.execute(stmt)
             rows = result.scalars().all()
             return [typing.cast(uuid.UUID, row) for row in rows]
@@ -633,13 +658,15 @@ class SqlAlchemySagaStorage(ISagaStorage):
         async with self.session_factory() as session:
             try:
                 values: dict[str, typing.Any] = {
-                    "recovery_attempts": SagaExecutionModel.recovery_attempts + 1,
-                    "version": SagaExecutionModel.version + 1,
+                    "recovery_attempts": self._execution_model.recovery_attempts + 1,
+                    "version": self._execution_model.version + 1,
                 }
                 if new_status is not None:
                     values["status"] = new_status
                 result = await session.execute(
-                    sqlalchemy.update(SagaExecutionModel).where(SagaExecutionModel.id == saga_id).values(**values),
+                    sqlalchemy.update(self._execution_model)
+                    .where(self._execution_model.id == saga_id)
+                    .values(**values),
                 )
                 if result.rowcount == 0:  # type: ignore[attr-defined]
                     raise ValueError(f"Saga {saga_id} not found")
@@ -656,11 +683,11 @@ class SqlAlchemySagaStorage(ISagaStorage):
         async with self.session_factory() as session:
             try:
                 result = await session.execute(
-                    sqlalchemy.update(SagaExecutionModel)
-                    .where(SagaExecutionModel.id == saga_id)
+                    sqlalchemy.update(self._execution_model)
+                    .where(self._execution_model.id == saga_id)
                     .values(
                         recovery_attempts=attempts,
-                        version=SagaExecutionModel.version + 1,
+                        version=self._execution_model.version + 1,
                     ),
                 )
                 if result.rowcount == 0:  # type: ignore[attr-defined]

cqrs/saga/storage/sqlmodel.py

@@ -0,0 +1,203 @@
+"""SQLModel saga storage: same schema and operations as the SQLAlchemy storage."""
+
+import contextlib
+import datetime
+import typing
+import uuid
+
+try:
+    from cqrs.saga.storage.sqlalchemy import (
+        DEFAULT_SAGA_EXECUTION_TABLE_NAME,
+        DEFAULT_SAGA_LOG_TABLE_NAME,
+        SAGA_EXECUTION_TABLE_NAME,
+        SAGA_LOG_TABLE_NAME,
+        SqlAlchemySagaStorage,
+    )
+
+    import sqlalchemy
+    from sqlalchemy import func
+    from sqlalchemy.ext.asyncio import async_sessionmaker
+    from sqlmodel import Field
+    from sqlmodel.ext.asyncio.session import AsyncSession
+
+    from cqrs.saga.storage.enums import SagaStatus, SagaStepStatus
+    from cqrs.sqlalchemy_types import JSONType
+    from cqrs.sqlmodel_base import CqrsSQLModel, SqlAlchemyExecuteSession
+except ImportError:
+    raise ImportError(
+        "You are trying to use the SQLModel saga storage implementation, "
+        "but 'sqlmodel' is not installed. "
+        "Please install it using: pip install python-cqrs[sqlmodel]",
+    ) from None
+
+Base = CqrsSQLModel
+
+
+class SagaExecutionModel(Base, table=True):
+    __tablename__ = SAGA_EXECUTION_TABLE_NAME  # type: ignore[assignment]
+
+    id: uuid.UUID = Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.Uuid,
+            primary_key=True,
+            nullable=False,
+            comment="Saga ID",
+        ),
+    )
+    name: str = Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.String(255),
+            nullable=False,
+            comment="Saga Name",
+        ),
+    )
+    status: SagaStatus = Field(
+        default=SagaStatus.PENDING,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.Enum(SagaStatus),
+            nullable=False,
+            default=SagaStatus.PENDING,
+            comment="Current status of the saga",
+        ),
+    )
+    context: dict[str, typing.Any] = Field(
+        sa_column=sqlalchemy.Column(
+            JSONType,
+            nullable=False,
+            comment="Serialized context",
+        ),
+    )
+    version: int = Field(
+        default=1,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.Integer,
+            nullable=False,
+            default=1,
+            comment="Optimistic locking version",
+        ),
+    )
+    created_at: datetime.datetime | None = Field(
+        default=None,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.DateTime(timezone=True),
+            nullable=False,
+            server_default=func.now(),
+            comment="Creation timestamp",
+        ),
+    )
+    updated_at: datetime.datetime | None = Field(
+        default=None,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.DateTime(timezone=True),
+            nullable=False,
+            server_default=func.now(),
+            onupdate=func.now(),
+            comment="Last update timestamp",
+        ),
+    )
+    recovery_attempts: int = Field(
+        default=0,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.Integer,
+            nullable=False,
+            default=0,
+            server_default=sqlalchemy.text("0"),
+            comment="Number of recovery attempts",
+        ),
+    )
+
+
+class SagaLogModel(Base, table=True):
+    __tablename__ = SAGA_LOG_TABLE_NAME  # type: ignore[assignment]
+
+    id: int | None = Field(
+        default=None,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.BigInteger(),
+            sqlalchemy.Identity(),
+            primary_key=True,
+            nullable=False,
+            autoincrement=True,
+            comment="Log ID",
+        ),
+    )
+    saga_id: uuid.UUID = Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.Uuid,
+            sqlalchemy.ForeignKey(f"{SAGA_EXECUTION_TABLE_NAME}.id"),
+            nullable=False,
+            comment="Saga ID",
+        ),
+    )
+    step_name: str = Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.String(255),
+            nullable=False,
+            comment="Name of the step",
+        ),
+    )
+    action: str = Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.String(50),
+            nullable=False,
+            comment="Action performed (act/compensate)",
+        ),
+    )
+    status: SagaStepStatus = Field(
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.Enum(SagaStepStatus),
+            nullable=False,
+            comment="Status of the step",
+        ),
+    )
+    details: str | None = Field(
+        default=None,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.Text,
+            nullable=True,
+            comment="Additional details or error message",
+        ),
+    )
+    created_at: datetime.datetime | None = Field(
+        default=None,
+        sa_column=sqlalchemy.Column(
+            sqlalchemy.DateTime(timezone=True),
+            nullable=False,
+            server_default=func.now(),
+            comment="Timestamp of the log entry",
+        ),
+    )
+
+
+class SqlModelSagaStorage(SqlAlchemySagaStorage):
+    """Saga storage that persists state in SQLModel tables.
+
+    ``session_factory`` must be an ``async_sessionmaker`` built with
+    ``class_=sqlmodel.ext.asyncio.session.AsyncSession``. Every operation of
+    ``SqlAlchemySagaStorage`` is available, including checkpoint runs via
+    ``create_run``, optimistic locking, and recovery queries.
+    """
+
+    def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
+        @contextlib.asynccontextmanager
+        async def _open() -> typing.AsyncGenerator[SqlAlchemyExecuteSession, None]:
+            async with session_factory() as session:
+                yield SqlAlchemyExecuteSession(session)
+
+        super().__init__(
+            _open,  # type: ignore[arg-type]
+            execution_model=SagaExecutionModel,
+            log_model=SagaLogModel,
+        )
+
+
+__all__ = (
+    "Base",
+    "DEFAULT_SAGA_EXECUTION_TABLE_NAME",
+    "DEFAULT_SAGA_LOG_TABLE_NAME",
+    "SAGA_EXECUTION_TABLE_NAME",
+    "SAGA_LOG_TABLE_NAME",
+    "SagaExecutionModel",
+    "SagaLogModel",
+    "SqlModelSagaStorage",
+)

cqrs/sqlmodel_base.py

@@ -0,0 +1,45 @@
+"""Declarative base shared by the optional SQLModel outbox and saga models."""
+
+import typing
+
+try:
+    from sqlalchemy.ext.asyncio import AsyncSession as SqlAlchemyAsyncSession
+    from sqlalchemy.orm import registry
+    from sqlmodel import SQLModel
+    from sqlmodel.ext.asyncio.session import AsyncSession
+except ImportError:
+    raise ImportError(
+        "You are trying to use the SQLModel integration, "
+        "but 'sqlmodel' is not installed. "
+        "Please install it using: pip install python-cqrs[sqlmodel]",
+    ) from None
+
+cqrs_registry = registry()
+
+
+class CqrsSQLModel(SQLModel, registry=cqrs_registry):
+    """Base for library SQLModel tables.
+
+    Tables live on this class's metadata, not on the application's
+    ``SQLModel.metadata``. Call ``Base.metadata.create_all`` the same way as
+    with the SQLAlchemy models, or rebind the outbox model onto your own base.
+    """
+
+
+class SqlAlchemyExecuteSession:
+    """SQLModel session whose ``execute`` is the SQLAlchemy implementation.
+
+    ``sqlmodel.AsyncSession.execute`` is deprecated in favor of ``exec`` and
+    warns on every call. The outbox and saga storage use Core ``execute``
+    because they need ``Result.rowcount`` and ``scalars()`` unchanged from the
+    SQLAlchemy repositories.
+    """
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    def __getattr__(self, name: str) -> typing.Any:
+        return getattr(self._session, name)
+
+    async def execute(self, statement: typing.Any, params: typing.Any = None, **kwargs: typing.Any) -> typing.Any:
+        return await SqlAlchemyAsyncSession.execute(self._session, statement, params, **kwargs)

{python_cqrs-5.0.0.dist-info → python_cqrs-5.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cqrs
-Version: 5.0.0
+Version: 5.1.0
 Summary: Event-Driven Architecture Framework for Distributed Systems
 Author-email: Vadim Kozyrevskiy <vadikko2@mail.ru>, Dmitry Kutlubaev <kutlubaev00@mail.ru>
 Maintainer-email: Vadim Kozyrevskiy <vadikko2@mail.ru>
@@ -29,6 +29,9 @@ Provides-Extra: pydantic
 Requires-Dist: pydantic==2.*; extra == "pydantic"
 Provides-Extra: sqlalchemy
 Requires-Dist: sqlalchemy[asyncio]==2.0.*; extra == "sqlalchemy"
+Provides-Extra: sqlmodel
+Requires-Dist: sqlmodel>=0.0.22; extra == "sqlmodel"
+Requires-Dist: sqlalchemy[asyncio]==2.0.*; extra == "sqlmodel"
 Provides-Extra: dev
 Requires-Dist: pycln==2.5.0; extra == "dev"
 Requires-Dist: pre-commit==3.8.0; extra == "dev"
@@ -54,6 +57,8 @@ Requires-Dist: dishka>=1.0; extra == "dev"
 Requires-Dist: protobuf>=4.25.8; extra == "dev"
 Requires-Dist: pydantic==2.*; extra == "dev"
 Requires-Dist: sqlalchemy[asyncio]==2.0.*; extra == "dev"
+Requires-Dist: sqlmodel>=0.0.22; extra == "dev"
+Requires-Dist: aiosqlite>=0.20.0; extra == "dev"
 Provides-Extra: examples
 Requires-Dist: fastapi==0.109.*; extra == "examples"
 Requires-Dist: faststream[kafka]==0.5.28; extra == "examples"
@@ -98,9 +103,6 @@ Dynamic: license-file
     <a href="https://codecov.io/gh/vadikko2/python-cqrs">
       <img src="https://img.shields.io/codecov/c/github/vadikko2/python-cqrs?logo=codecov&logoColor=white" alt="Coverage">
     </a>
-    <a href="https://codspeed.io/vadikko2/python-cqrs?utm_source=badge">
-      <img src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" alt="CodSpeed">
-    </a>
     <a href="https://mkdocs.python-cqrs.dev/">
       <img src="https://img.shields.io/badge/docs-mkdocs-blue?logo=readthedocs" alt="Documentation">
     </a>
@@ -113,17 +115,11 @@ Dynamic: license-file
   </p>
 </div>
 
-> [!WARNING]
-> **Breaking Changes in v5.0.0**
->
-> Starting with version 5.0.0, Pydantic support will become optional. The default implementations of `Request`, `Response`, `DomainEvent`, and `NotificationEvent` will be migrated to dataclasses-based implementations.
-
 ## Table of Contents
 
 - [Overview](#overview)
 - [When NOT to use python-cqrs](#when-not-to-use-python-cqrs)
 - [Installation](#installation)
-- [Version Support](#version-support)
 - [Quick Start](#quick-start)
 - [Request and Response Types](#request-and-response-types)
 - [Request Handlers](#request-handlers)
@@ -166,7 +162,7 @@ project ([documentation](https://akhundmurad.github.io/diator/)) with several en
 
 - **Typing:** Pydantic [v2.*](https://docs.pydantic.dev/2.8/) and `IRequest`/`IResponse` interfaces — use Pydantic-based, dataclass-based, or custom Request/Response implementations.
 - **Broker:** Kafka via [aiokafka](https://github.com/aio-libs/aiokafka).
-- **Storage:** SQLAlchemy-based Outbox and Saga storage on MySQL/MariaDB and PostgreSQL.
+- **Storage:** SQLAlchemy and SQLModel outbox and saga storage on MySQL/MariaDB and PostgreSQL.
 - **Integration:** Ready for integration with FastAPI and FastStream.
 - **Documentation:** Built-in Mermaid diagram generation (Sequence and Class diagrams).
 - **Protobuf:** Interface-level support for converting Notification events to Protobuf and back.
@@ -189,11 +185,12 @@ Do not add a Saga for a single `UPDATE` in one service, and do not use a Saga as
 pip install python-cqrs
 ```
 
-Optional extras (5.0+ — pydantic and SQLAlchemy are no longer core dependencies):
+Optional extras (5.0+ — pydantic and SQLAlchemy are no longer core dependencies; SQLModel storage is 5.1+):
 
 ```bash
 pip install "python-cqrs[pydantic]"     # PydanticRequest / Pydantic* events
 pip install "python-cqrs[sqlalchemy]"   # Outbox / Saga SQLAlchemy storage
+pip install "python-cqrs[sqlmodel]"     # Outbox / Saga SQLModel storage
 pip install "python-cqrs[kafka]"        # Kafka broker (aiokafka)
 pip install "python-cqrs[examples]"     # FastAPI, FastStream, uvicorn, etc.
 pip install "python-cqrs[aiobreaker]"   # Circuit breaker for saga fallbacks
@@ -203,37 +200,6 @@ Default `Request` / `Response` / `Event` / `DomainEvent` / `NotificationEvent` a
 are dataclass-based (`DC*`). Use `Pydantic*` types with the pydantic extra when you
 need validation.
 
-### Import paths (5.0+)
-
-| Area | Import |
-|------|--------|
-| Bootstrap | `from cqrs.bootstrap import requests, events, saga` |
-| Mediators | `from cqrs.mediators import RequestMediator, SagaMediator, …` |
-| Handlers | `from cqrs.handlers import RequestHandler, EventHandler, …` |
-| Models | `from cqrs.models import Request, Event, …` / `cqrs.models.pydantic` |
-| Maps | `from cqrs.mapping import RequestMap, EventMap, OutboxedEventMap` |
-| Mermaid | `from cqrs.mermaid import CoRMermaid, SagaMermaid` |
-| Outbox producer | `from cqrs.message_brokers.producer import EventProducer` |
-
-`SagaMediator.execute(...)` replaces the former `SagaMediator.stream(...)`
-(StreamingRequestMediator.stream is unchanged).
-
-## Version Support
-
-| Line | Git branch | What changes |
-|------|------------|--------------|
-| **4.x** | `4.x` | Bug fixes and security only (~12 months after 5.0.0) |
-| **5.x** | `master` | Features and breaking changes |
-
-Stay on 4.x until you migrate:
-
-```bash
-pip install "python-cqrs>=4,<5"
-```
-
-Docs: [4.x](https://mkdocs.python-cqrs.dev/4.0/) and [5.x / latest](https://mkdocs.python-cqrs.dev/latest/) (version switcher after mike deploy). See [SECURITY.md](SECURITY.md) for the support window and vulnerability reporting, and [CONTRIBUTING.md](CONTRIBUTING.md#8-maintaining--fixing-4x) for how to contribute 4.x bugfixes.
-
-A package-level EOL `DeprecationWarning` toward 5.x will be added on the **first 4.x patch after 5.0.0** — not before.
 
 ## Quick Start
 

{python_cqrs-5.0.0.dist-info → python_cqrs-5.1.0.dist-info}/RECORD

@@ -1,8 +1,9 @@
-cqrs/__init__.py,sha256=ay8XdNvYLDqSSpFwcUDbRBggJNTnzYncKu_6qgFakwE,5666
+cqrs/__init__.py,sha256=W9uUGYuGci-4dIdmMUIjaUyJ31-ZyOU0AY0Od4gS_Gg,6170
 cqrs/_dataclass_utils.py,sha256=OqKF3Gifarcj7rjFWUe60BcBrpt0NePgiXbbiuigMdk,3555
 cqrs/circuit_breaker.py,sha256=OEq6N5YK8-uOSXEsC5IfJxPxXOw-UIgjccrlLv22Tgg,2385
 cqrs/generic_utils.py,sha256=DsUq6oCLpZVBkxMmW5cgRrbEcC_DlNTeXuwVv2LPHmI,1571
 cqrs/sqlalchemy_types.py,sha256=VHt8yzlddU2ZdLZ-c2gcS53TnmtQcb2wju8Si5xPfZE,7430
+cqrs/sqlmodel_base.py,sha256=7Cujk82AhBPP_Q1p3qbINN2OxtoC7qSMAwMSZbOmAhU,1674
 cqrs/types.py,sha256=gbHLEPKZloViUJc-jZZ-HhakZvlLxbzk3FT_VTSHOgc,309
 cqrs/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cqrs/adapters/amqp.py,sha256=sKtH9XgVlKPI2-_bGc9CNxbRUi8vydUz3FuwvdSepho,2997
@@ -72,7 +73,8 @@ cqrs/models/response.py,sha256=tc4-L0lHOdsV82ftEDeglj65KODrV1Z0uyG1-49BhM4,2032
 cqrs/outbox/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cqrs/outbox/mock.py,sha256=9sp6OESCqWadnkSQ7tz6C_5FPlXLkVLbQWoP7lbfkz8,2212
 cqrs/outbox/repository.py,sha256=-NsefTE-Zv9fcYEigCSQXVhDwJ8nC7B7JgGkU2S9dZM,2499
-cqrs/outbox/sqlalchemy.py,sha256=F8tlqdVhGuJ4j5jthyoy_RgHmSMNeweXaXDiaBW30-A,10259
+cqrs/outbox/sqlalchemy.py,sha256=toWW-HZBgCoKKb2DHmnLAyCEEq-VoPnVGec3ydEBxxQ,10353
+cqrs/outbox/sqlmodel.py,sha256=w1tOyiR0tV7S8vHx0SQsU0j48yA00zW-ehjBrU8mT7Q,5550
 cqrs/requests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cqrs/requests/fallback.py,sha256=6hysbuxvLti0laveuMMLazIMkjj5VYBxFcY5wkXEXtI,4431
 cqrs/saga/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -89,14 +91,15 @@ cqrs/saga/storage/enums.py,sha256=yOAsPFUBA7wY-_7ft5wtJcS3wXdsAzUHQ-8X0iuMXZA,44
 cqrs/saga/storage/memory.py,sha256=x8Nuib259Z4s-JO4K1bDnUHavwwz1wYf6Oo2p2oh5R0,12836
 cqrs/saga/storage/models.py,sha256=VF-oXCajhwcRZLAhLfvhHq4HRVU7L2WQJLzVfLUxxPg,919
 cqrs/saga/storage/protocol.py,sha256=7k_z49EpABqPq9kAd3R85wPe_yx4hCjEpvWgrW6kNAQ,14031
-cqrs/saga/storage/sqlalchemy.py,sha256=7OENFOOSJ-BgMtFIzzqLCndhMjgKOrik5_iF_WlRpjU,24925
+cqrs/saga/storage/sqlalchemy.py,sha256=uYHorxz-DcaYISLcy_toI1x129MrxYsHOyRNYR2bHzs,26084
+cqrs/saga/storage/sqlmodel.py,sha256=7vdJzAmm2uwaGrlfCjUsf-1ndwoKnBGqPwPP6D3YIjA,6006
 cqrs/serializers/__init__.py,sha256=vzCKkQ-zm4Ua6EKhJ8syTxycjn8QK_Zuvz0M5BvcCqk,378
 cqrs/serializers/default.py,sha256=USVd1dwtgMgMd2FlK8BHtc7B61myzWcosHR4VkYEKB4,2617
 cqrs/serializers/json.py,sha256=HBnay7_Yzb_ap78jaewZbKYtI7eNGArg3qba-gF_PF0,628
 cqrs/serializers/protobuf.py,sha256=phqEgQrhx9jLCFQGz7xr-3QJbgJHQmBLeDCzxD9dAhE,1640
 cqrs/serializers/protocol.py,sha256=lRyzsc_p7c5ZWUnzXPptzd4rSUOOu-yR7KrYWPBVER4,588
-python_cqrs-5.0.0.dist-info/licenses/LICENSE,sha256=eS7m3vXf_ZJ_ZGceKhQUySTjk32aywfCHFFirO4t3qc,1072
-python_cqrs-5.0.0.dist-info/METADATA,sha256=2CxMECUf9A0_3mlE4BmjB1dHmpEuIVJuIZZ7qkg_1jM,51778
-python_cqrs-5.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_cqrs-5.0.0.dist-info/top_level.txt,sha256=ic74ni8Zxy9lirOAcyt4YEKU34e8IlC8RslIQmbWCq0,5
-python_cqrs-5.0.0.dist-info/RECORD,,
+python_cqrs-5.1.0.dist-info/licenses/LICENSE,sha256=eS7m3vXf_ZJ_ZGceKhQUySTjk32aywfCHFFirO4t3qc,1072
+python_cqrs-5.1.0.dist-info/METADATA,sha256=2rNVYMawK8Er2m08BQRen_41j408yK511R1s_2CFcwM,50165
+python_cqrs-5.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_cqrs-5.1.0.dist-info/top_level.txt,sha256=ic74ni8Zxy9lirOAcyt4YEKU34e8IlC8RslIQmbWCq0,5
+python_cqrs-5.1.0.dist-info/RECORD,,