python-cqrs 5.2.0__tar.gz → 5.3.0__tar.gz

{python_cqrs-5.2.0 → python_cqrs-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cqrs
-Version: 5.2.0
+Version: 5.3.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>
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE

{python_cqrs-5.2.0 → python_cqrs-5.3.0}/pyproject.toml

@@ -15,6 +15,7 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
   "dataclass-wizard==0.*",
@@ -29,7 +30,7 @@ maintainers = [{ name = "Vadim Kozyrevskiy", email = "vadikko2@mail.ru" }]
 name = "python-cqrs"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "5.2.0"
+version = "5.3.0"
 
 [project.optional-dependencies]
 aiobreaker = ["aiobreaker>=0.3.0"]

{python_cqrs-5.2.0 → python_cqrs-5.3.0}/src/cqrs/__init__.py

@@ -46,6 +46,14 @@ Outbox on ``cqrs``: ``OutboxedEventRepository``, ``OutboxedEventMap``,
 the ``sqlmodel`` extra. Codecs on ``cqrs``: ``JsonEventSerializer``,
 ``ProtobufEventSerializer`` (extra ``protobuf``).
 
+Inbox on ``cqrs``: ``InboxRepository``, ``InboxMessage``, ``InboxStatus``,
+``InboxMessageMap``, ``InboxProcessor``. ``SqlAlchemyInboxRepository`` and
+``rebind_inbox_model`` are lazy and need the ``sqlalchemy`` extra.
+``SqlModelInboxRepository`` is lazy and needs the ``sqlmodel`` extra.
+Presentation calls ``add`` with a batch. ``InboxProcessor`` reads rows and
+calls the mediator that is already registered. FastAPI and FastStream are
+not imported here.
+
 Brokers are not on ``cqrs``. Kafka is
 ``cqrs.adapters.kafka.kafka_producer_factory`` plus
 ``cqrs.message_brokers.kafka.KafkaMessageBroker`` (extra ``kafka``). AMQP is
@@ -79,6 +87,11 @@ if typing.TYPE_CHECKING:
     )
     from cqrs.models.pydantic import PydanticRequest
     from cqrs.models.pydantic import PydanticResponse
+    from cqrs.inbox.sqlalchemy import (
+        SqlAlchemyInboxRepository,
+        rebind_inbox_model,
+    )
+    from cqrs.inbox.sqlmodel import SqlModelInboxRepository
     from cqrs.outbox.sqlalchemy import (
         SqlAlchemyOutboxedEventRepository,
         rebind_outbox_model,
@@ -126,6 +139,9 @@ from cqrs.mediators import (
     SagaMediator,
     StreamingRequestMediator,
 )
+from cqrs.inbox.map import InboxMessageMap
+from cqrs.inbox.processor import InboxProcessor
+from cqrs.inbox.repository import InboxMessage, InboxRepository, InboxStatus
 from cqrs.mapping.outbox import OutboxedEventMap
 from cqrs.outbox.repository import (
     EventStatus,
@@ -202,6 +218,13 @@ __all__ = (
     "OutboxedEventRepository",
     "SqlAlchemyOutboxedEventRepository",
     "SqlModelOutboxedEventRepository",
+    "InboxRepository",
+    "InboxMessage",
+    "InboxStatus",
+    "InboxMessageMap",
+    "InboxProcessor",
+    "SqlAlchemyInboxRepository",
+    "SqlModelInboxRepository",
     "EventProducer",
     "EventSerializer",
     "EventCodec",
@@ -220,6 +243,7 @@ __all__ = (
     "Compressor",
     "ZlibCompressor",
     "rebind_outbox_model",
+    "rebind_inbox_model",
     "Saga",
     "SagaStepHandler",
     "SagaStepResult",
@@ -252,6 +276,11 @@ _LAZY_SQLALCHEMY = {
         "SqlAlchemyOutboxedEventRepository",
     ),
     "rebind_outbox_model": ("cqrs.outbox.sqlalchemy", "rebind_outbox_model"),
+    "SqlAlchemyInboxRepository": (
+        "cqrs.inbox.sqlalchemy",
+        "SqlAlchemyInboxRepository",
+    ),
+    "rebind_inbox_model": ("cqrs.inbox.sqlalchemy", "rebind_inbox_model"),
     "DialectAwareType": ("cqrs.sqlalchemy_types", "DialectAwareType"),
     "DialectTypeHandler": ("cqrs.sqlalchemy_types", "DialectTypeHandler"),
     "UUIDBinary": ("cqrs.sqlalchemy_types", "UUIDBinary"),
@@ -265,6 +294,10 @@ _LAZY_SQLMODEL = {
         "cqrs.outbox.sqlmodel",
         "SqlModelOutboxedEventRepository",
     ),
+    "SqlModelInboxRepository": (
+        "cqrs.inbox.sqlmodel",
+        "SqlModelInboxRepository",
+    ),
 }
 
 

python_cqrs-5.3.0/src/cqrs/inbox/__init__.py

@@ -0,0 +1,21 @@
+"""
+Transactional inbox.
+
+[AI Instruction]
+Import ``InboxRepository``, ``InboxMessage``, ``InboxStatus``,
+``InboxMessageMap``, and ``InboxProcessor`` from ``cqrs``. SQLAlchemy and
+SQLModel repositories are lazy. Presentation calls ``add``. A worker calls
+``InboxProcessor``.
+"""
+
+from cqrs.inbox.map import InboxMessageMap
+from cqrs.inbox.processor import InboxProcessor
+from cqrs.inbox.repository import InboxMessage, InboxRepository, InboxStatus
+
+__all__ = (
+    "InboxMessage",
+    "InboxMessageMap",
+    "InboxProcessor",
+    "InboxRepository",
+    "InboxStatus",
+)

python_cqrs-5.3.0/src/cqrs/inbox/map.py

@@ -0,0 +1,201 @@
+"""
+Name registry for inbox messages.
+
+[AI Instruction]
+Register each request or event name before ``InboxRepository.add``. JSON is
+the default codec. A second ``register`` of the same name raises ``KeyError``.
+Prefer an instance when tests must not share the process-global map.
+"""
+
+import functools
+import typing
+
+import orjson
+
+from cqrs.inbox.repository import InboxEntry
+from cqrs.models.event import IEvent
+from cqrs.models.request import IRequest
+
+_KT = typing.TypeVar("_KT")
+
+
+class _JsonMessageSerializer:
+    """JSON codec. Wire format is ``orjson.dumps(message.to_dict())``."""
+
+    def serialize(self, message: InboxEntry) -> bytes:
+        return orjson.dumps(message.to_dict())
+
+    def deserialize(self, payload: bytes, message_type: typing.Type[_KT]) -> _KT:
+        data = orjson.loads(payload)
+        if not isinstance(data, dict):
+            raise TypeError("inbox payload must be a JSON object")
+        return message_type.from_dict(**data)  # type: ignore[attr-defined]
+
+
+class MessageCodec(typing.Protocol):
+    """Serialize and deserialize one inbox message type."""
+
+    def serialize(self, message: InboxEntry) -> bytes: ...
+
+    def deserialize(self, payload: bytes, message_type: typing.Type[typing.Any]) -> typing.Any: ...
+
+
+class _bind_self_or_singleton:
+    """Class access binds the process singleton; instance access binds that map."""
+
+    def __init__(self, func: typing.Callable) -> None:
+        self.func = func
+
+    def __get__(
+        self,
+        obj: typing.Any,
+        objtype: type | None = None,
+    ) -> typing.Callable:
+        target = obj if obj is not None else objtype._singleton()  # type: ignore[union-attr]
+        return functools.partial(self.func, target)
+
+
+def message_name(message: InboxEntry) -> str:
+    """
+    Name stored with the row.
+
+    Notification events use ``event_name``, the same string the outbox stores.
+    Requests and domain events use the class name.
+    """
+
+    event_name = getattr(message, "event_name", None)
+    if isinstance(event_name, str) and event_name:
+        return event_name
+    return type(message).__name__
+
+
+def _type_matches(message_type: type, registered: typing.Any) -> bool:
+    registered_origin = typing.get_origin(registered) or registered
+    if message_type is registered:
+        return True
+    if typing.get_origin(registered) is not None and message_type is registered_origin:
+        return True
+    if isinstance(registered, type) and issubclass(message_type, registered):
+        return True
+    return False
+
+
+class InboxMessageMap:
+    """
+    Registry of inbox message names to request or event types.
+
+    Class-level ``register`` / ``get`` use a process-global singleton.
+    ``InboxMessageMap()`` creates an isolated registry.
+
+    [AI Instruction]
+    Tell the inbox which Python type belongs to a message name. Register
+    before the repository reads or writes that message. JSON is the default.
+    A second registration of the same name raises ``KeyError``. Requests and
+    domain events are registered under the class name. Notification events
+    are registered under ``event_name``.
+    """
+
+    _instance: typing.ClassVar["InboxMessageMap | None"] = None
+
+    def __init__(self) -> None:
+        self._entries: typing.Dict[str, typing.Tuple[typing.Any, MessageCodec | None]] = {}
+
+    @classmethod
+    def _singleton(cls) -> "InboxMessageMap":
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    @_bind_self_or_singleton
+    def register(
+        self,
+        message_name_: str,
+        message_type: typing.Type[InboxEntry],
+        serializer: MessageCodec | None = None,
+    ) -> None:
+        """
+        Bind ``message_name_`` to a request or event class.
+
+        [AI Instruction]
+        Call once at startup. A second registration of the same name raises
+        ``KeyError``. Omit ``serializer`` for JSON.
+        """
+
+        if message_name_ in self._entries:
+            raise KeyError(f"Message {message_name_} already registered")
+        self._entries[message_name_] = (message_type, serializer)
+
+    @_bind_self_or_singleton
+    def get(self, message_name_: str) -> typing.Any | None:
+        """Return the registered type, or ``None`` when the name is unknown."""
+
+        entry = self._entries.get(message_name_)
+        if entry is None:
+            return None
+        return entry[0]
+
+    @_bind_self_or_singleton
+    def get_serializer(self, message_name_: str) -> MessageCodec | None:
+        """Return the codec registered for this name, or ``None`` for JSON."""
+
+        entry = self._entries.get(message_name_)
+        if entry is None:
+            return None
+        return entry[1]
+
+    @_bind_self_or_singleton
+    def deserialize(self, message_name_: str, payload: bytes) -> InboxEntry:
+        """
+        Rebuild a request or event from stored bytes.
+
+        [AI Instruction]
+        ``InboxProcessor`` calls this. An unknown name raises ``KeyError``
+        and does not return a message.
+        """
+
+        entry = self._entries.get(message_name_)
+        if entry is None:
+            raise KeyError(f"Unknown message name {message_name_}")
+        message_type, serializer = entry
+        codec = serializer or _JsonMessageSerializer()
+        return codec.deserialize(payload, message_type)
+
+    @_bind_self_or_singleton
+    def payload_for(self, message: InboxEntry) -> typing.Tuple[str, bytes]:
+        """
+        Return ``(message_name, payload)`` for a registered message.
+
+        Raises ``TypeError`` when the name is missing or the instance type
+        does not match the registration.
+        """
+
+        if not isinstance(message, (IRequest, IEvent)):
+            raise TypeError(f"Unsupported inbox message type {type(message)}")
+        name = message_name(message)
+        registered = self.get(name)
+        if registered is None:
+            raise TypeError(f"Unknown message name for {name}")
+        if not _type_matches(type(message), registered):
+            raise TypeError(
+                f"Message type {type(message)} does not match registered type {registered}",
+            )
+        codec = self.get_serializer(name) or _JsonMessageSerializer()
+        return name, codec.serialize(message)
+
+
+def resolve_message_map(
+    message_map: "InboxMessageMap | None",
+) -> InboxMessageMap:
+    """Use the given instance, or the process singleton when ``message_map`` is omitted."""
+
+    if message_map is None or message_map is InboxMessageMap:
+        return InboxMessageMap._singleton()
+    return message_map
+
+
+__all__ = (
+    "InboxMessageMap",
+    "MessageCodec",
+    "message_name",
+    "resolve_message_map",
+)

python_cqrs-5.3.0/src/cqrs/inbox/memory.py

@@ -0,0 +1,110 @@
+"""In-memory inbox repository for unit tests."""
+
+import contextlib
+import dataclasses
+import datetime
+import typing
+
+from cqrs.inbox.map import InboxMessageMap, resolve_message_map
+from cqrs.inbox.repository import (
+    MAX_FLUSH_COUNTER_VALUE,
+    InboxEntry,
+    InboxMessage,
+    InboxRepository,
+    InboxStatus,
+)
+
+
+class MemoryInboxRepository(InboxRepository):
+    """
+    Process-local inbox.
+
+    ``add`` is visible to ``get_many`` on this instance before ``commit``,
+    matching a session that has flushed and not committed. ``rollback``
+    restores the last ``commit``. ``nested`` snapshots the rows and restores
+    them when the block raises.
+    """
+
+    def __init__(self, message_map: InboxMessageMap | None = None) -> None:
+        self._message_map = resolve_message_map(message_map)
+        self._rows: typing.List[InboxMessage] = []
+        self._checkpoint: typing.List[InboxMessage] = []
+        self._next_id = 1
+
+    async def add(
+        self,
+        messages: typing.Sequence[typing.Tuple[str, InboxEntry]],
+    ) -> typing.List[bool]:
+        if not messages:
+            return []
+        stored = {(row.message_id, row.message_name) for row in self._rows}
+        results: typing.List[bool] = []
+        for message_id, message in messages:
+            name, payload = self._message_map.payload_for(message)
+            key = (message_id, name)
+            if key in stored:
+                results.append(False)
+                continue
+            self._rows.append(
+                InboxMessage(
+                    id=self._next_id,
+                    message_id=message_id,
+                    message_name=name,
+                    status=InboxStatus.NEW,
+                    flush_counter=0,
+                    created_at=datetime.datetime.now(),
+                    payload=payload,
+                ),
+            )
+            self._next_id += 1
+            stored.add(key)
+            results.append(True)
+        return results
+
+    async def get_many(self, batch_size: int = 100) -> typing.List[InboxMessage]:
+        selectable = [
+            row
+            for row in self._rows
+            if row.status in (InboxStatus.NEW, InboxStatus.NOT_PROCESSED)
+            and row.flush_counter < MAX_FLUSH_COUNTER_VALUE
+        ]
+        selectable.sort(key=lambda row: row.id)
+        return selectable[:batch_size]
+
+    async def update_status(self, row_id: int, new_status: InboxStatus) -> None:
+        for index, row in enumerate(self._rows):
+            if row.id != row_id:
+                continue
+            flush_counter = row.flush_counter
+            if new_status is InboxStatus.NOT_PROCESSED:
+                flush_counter += 1
+            self._rows[index] = dataclasses.replace(
+                row,
+                status=new_status,
+                flush_counter=flush_counter,
+            )
+            return
+
+    def nested(self) -> contextlib.AbstractAsyncContextManager[None]:
+        return self._nested()
+
+    @contextlib.asynccontextmanager
+    async def _nested(self) -> typing.AsyncIterator[None]:
+        snapshot = [dataclasses.replace(row) for row in self._rows]
+        next_id = self._next_id
+        try:
+            yield
+        except BaseException:
+            self._rows = snapshot
+            self._next_id = next_id
+            raise
+
+    async def commit(self) -> None:
+        self._checkpoint = [dataclasses.replace(row) for row in self._rows]
+
+    async def rollback(self) -> None:
+        self._rows = [dataclasses.replace(row) for row in self._checkpoint]
+        self._next_id = max((row.id for row in self._rows), default=0) + 1
+
+
+__all__ = ("MemoryInboxRepository",)

python_cqrs-5.3.0/src/cqrs/inbox/processor.py

@@ -0,0 +1,116 @@
+"""
+Read inbox rows and hand them to the mediator that is already registered.
+
+[AI Instruction]
+Run ``InboxProcessor`` in a worker process. It does not replace
+``repository.add`` in a route or a subscriber. ``process`` does not commit.
+The worker commits the business rows and the status together.
+"""
+
+import functools
+import logging
+import typing
+
+from cqrs.inbox.map import InboxMessageMap
+from cqrs.inbox.repository import InboxMessage, InboxRepository, InboxStatus
+from cqrs.models.event import IEvent
+from cqrs.models.request import IRequest
+
+logger = logging.getLogger("cqrs")
+
+
+class InboxProcessor:
+    """
+    Deserialize one inbox row and send it through an existing mediator.
+
+    A ``Request`` goes to ``RequestMediator.send``. An event goes to
+    ``EventMediator.send``. Each row has its own savepoint: success stores
+    ``processed`` inside that savepoint, and a failure stores ``not_processed``
+    on the outer transaction after the savepoint rolls back.
+
+    [AI Instruction]
+    Construct it with the repository for this batch's session, the same
+    ``InboxMessageMap`` that repository uses, and the mediators bootstrap
+    already built. The caller owns the session and the commit. Do not add a
+    handler whose only job is to write the inbox row. The handler that
+    ``send`` runs must not call ``session.commit``.
+    """
+
+    def __init__(
+        self,
+        repository: InboxRepository,
+        message_map: InboxMessageMap,
+        request_mediator: typing.Any | None = None,
+        event_mediator: typing.Any | None = None,
+    ) -> None:
+        self.repository = repository
+        self._map = message_map
+        self._request_mediator = request_mediator
+        self._event_mediator = event_mediator
+
+    async def batch_generator(
+        self,
+        batch_size: int = 100,
+    ) -> typing.AsyncIterator[typing.List[InboxMessage]]:
+        """
+        Yield batches until the caller stops the loop.
+
+        [AI Instruction]
+        Poll forever. Each yield is one ``get_many`` result from the
+        repository passed to ``__init__``. Process every row, then let the
+        caller commit. This generator does not commit and does not end on
+        an empty batch.
+        """
+
+        while True:
+            yield await self.repository.get_many(batch_size=batch_size)
+
+    async def process(self, row: InboxMessage) -> None:
+        """
+        Run one row.
+
+        [AI Instruction]
+        Call this for each row from ``get_many``. The repository is the one
+        passed to ``__init__``. A handler exception rolls back that row's
+        business writes and leaves neighbors in the batch untouched.
+        ``not_processed`` increments ``flush_counter``. The row stays
+        selectable until the counter reaches five.
+        """
+
+        try:
+            message = self._map.deserialize(row.message_name, row.payload)
+            async with self.repository.nested():
+                await self._dispatch(message)
+                await self.repository.update_status(row.id, InboxStatus.PROCESSED)
+        except Exception:
+            logger.exception(
+                "inbox row %s (%s) failed",
+                row.id,
+                row.message_name,
+            )
+            await self.repository.update_status(row.id, InboxStatus.NOT_PROCESSED)
+
+    @typing.overload
+    async def _dispatch(self, message: IRequest) -> None: ...
+
+    @typing.overload
+    async def _dispatch(self, message: IEvent) -> None: ...
+
+    @functools.singledispatchmethod
+    async def _dispatch(self, message: typing.Any) -> None:
+        raise TypeError(f"Unsupported inbox message type {type(message)}")
+
+    @_dispatch.register(IRequest)  # pyright: ignore[reportFunctionMemberAccess]
+    async def _dispatch_request(self, message: IRequest) -> None:
+        if self._request_mediator is None:
+            raise RuntimeError("RequestMediator is not configured")
+        await self._request_mediator.send(message)
+
+    @_dispatch.register(IEvent)  # pyright: ignore[reportFunctionMemberAccess]
+    async def _dispatch_event(self, message: IEvent) -> None:
+        if self._event_mediator is None:
+            raise RuntimeError("EventMediator is not configured")
+        await self._event_mediator.send(message)
+
+
+__all__ = ("InboxProcessor",)