python-cqrs 1.0.0__tar.gz → 2.0.2__tar.gz

{python_cqrs-1.0.0 → python_cqrs-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-cqrs
-Version: 1.0.0
+Version: 2.0.2
 Summary: Python CQRS pattern implementation
 Author-email: Vadim Kozyrevskiy <vadikko2@mail.ru>
 Maintainer-email: Vadim Kozyrevskiy <vadikko2@mail.ru>
@@ -33,12 +33,14 @@ Requires-Dist: pytest-env==0.6.2; extra == "dev"
 Requires-Dist: cryptography==42.0.2; extra == "dev"
 Requires-Dist: asyncmy==0.2.9; extra == "dev"
 Provides-Extra: examples
-Requires-Dist: aiokafka==0.10.0; extra == "examples"
 Requires-Dist: fastapi==0.109.*; extra == "examples"
 Requires-Dist: uvicorn==0.32.0; extra == "examples"
 Requires-Dist: faststream[kafka]==0.5.28; extra == "examples"
 Provides-Extra: kafka
 Requires-Dist: aiokafka==0.10.0; extra == "kafka"
+Requires-Dist: confluent-kafka==2.6.0; extra == "kafka"
+Provides-Extra: protobuf
+Requires-Dist: protobuf==4.25.5; extra == "protobuf"
 
 # Python CQRS pattern implementation with Transaction Outbox supporting
 
@@ -59,7 +61,8 @@ project ([documentation](https://akhundmurad.github.io/diator/)) with several en
 6. Added support for [Transaction Outbox](https://microservices.io/patterns/data/transactional-outbox.html), ensuring
    that `Notification` and `ECST` events are sent to the broker;
 7. FastAPI supporting;
-8. FastStream supporting.
+8. FastStream supporting;
+9. [Protobuf](https://protobuf.dev/) events supporting.
 
 ## Request Handlers
 
@@ -295,6 +298,11 @@ the [documentation](https://github.com/vadikko2/cqrs/blob/master/examples/save_e
 > You can specify the name of the Outbox table using the environment variable `OUTBOX_SQLA_TABLE`.
 > By default, it is set to `outbox`.
 
+> [!TIP]
+> If you use the protobuf events you should specify `OutboxedEventRepository`
+> by [protobuf serialize](https://github.com/vadikko2/cqrs/blob/master/src/cqrs/serializers/protobuf.py). A complete example can be found in
+the [documentation](https://github.com/vadikko2/cqrs/blob/master/examples/save_proto_events_into_outbox.py)
+
 ## Producing Events from Outbox to Kafka
 
 As an implementation of the Transactional Outbox pattern, the SqlAlchemyOutboxedEventRepository is available for use as
@@ -507,4 +515,13 @@ async def hello_world_event_handler(
     await msg.ack()
 ```
 
-A complete example can be found in the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/kafka_event_consuming.py)
+A complete example can be found in
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/kafka_event_consuming.py)
+
+## Protobuf messaging
+
+The `python-cqrs` package supports integration with [protobuf](https://developers.google.com/protocol-buffers/).\
+Protocol buffers are Google’s language-neutral, platform-neutral, extensible mechanism for serializing structured data –
+think XML, but smaller, faster, and simpler. You define how you want your data to be structured once, then you can use
+special generated source code to easily write and read your structured data to and from a variety of data streams and
+using a variety of languages.

{python_cqrs-1.0.0 → python_cqrs-2.0.2}/README.md

@@ -17,7 +17,8 @@ project ([documentation](https://akhundmurad.github.io/diator/)) with several en
 6. Added support for [Transaction Outbox](https://microservices.io/patterns/data/transactional-outbox.html), ensuring
    that `Notification` and `ECST` events are sent to the broker;
 7. FastAPI supporting;
-8. FastStream supporting.
+8. FastStream supporting;
+9. [Protobuf](https://protobuf.dev/) events supporting.
 
 ## Request Handlers
 
@@ -253,6 +254,11 @@ the [documentation](https://github.com/vadikko2/cqrs/blob/master/examples/save_e
 > You can specify the name of the Outbox table using the environment variable `OUTBOX_SQLA_TABLE`.
 > By default, it is set to `outbox`.
 
+> [!TIP]
+> If you use the protobuf events you should specify `OutboxedEventRepository`
+> by [protobuf serialize](https://github.com/vadikko2/cqrs/blob/master/src/cqrs/serializers/protobuf.py). A complete example can be found in
+the [documentation](https://github.com/vadikko2/cqrs/blob/master/examples/save_proto_events_into_outbox.py)
+
 ## Producing Events from Outbox to Kafka
 
 As an implementation of the Transactional Outbox pattern, the SqlAlchemyOutboxedEventRepository is available for use as
@@ -465,4 +471,13 @@ async def hello_world_event_handler(
     await msg.ack()
 ```
 
-A complete example can be found in the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/kafka_event_consuming.py)
+A complete example can be found in
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/kafka_event_consuming.py)
+
+## Protobuf messaging
+
+The `python-cqrs` package supports integration with [protobuf](https://developers.google.com/protocol-buffers/).\
+Protocol buffers are Google’s language-neutral, platform-neutral, extensible mechanism for serializing structured data –
+think XML, but smaller, faster, and simpler. You define how you want your data to be structured once, then you can use
+special generated source code to easily write and read your structured data to and from a variety of data streams and
+using a variety of languages.

{python_cqrs-1.0.0 → python_cqrs-2.0.2}/pyproject.toml

@@ -28,7 +28,7 @@ maintainers = [{name = "Vadim Kozyrevskiy", email = "vadikko2@mail.ru"}]
 name = "python-cqrs"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0"
+version = "2.0.2"
 
 [project.optional-dependencies]
 dev = [
@@ -45,12 +45,18 @@ dev = [
   "asyncmy==0.2.9"
 ]
 examples = [
-  "aiokafka==0.10.0",
   "fastapi==0.109.*",
   "uvicorn==0.32.0",
   "faststream[kafka]==0.5.28"
 ]
-kafka = ["aiokafka==0.10.0"]
+kafka = [
+  "aiokafka==0.10.0",
+  # for SchemaRegistry
+  "confluent-kafka==2.6.0"
+]
+protobuf = [
+  "protobuf==4.25.5"
+]
 
 [project.urls]
 Issues = "https://github.com/vadikko2/python-cqrs/issues"

{python_cqrs-1.0.0 → python_cqrs-2.0.2}/src/cqrs/__init__.py

@@ -1,15 +1,15 @@
-from cqrs.compressors.protocol import Compressor
-from cqrs.compressors.zlib import ZlibCompressor
+from cqrs.compressors import Compressor, ZlibCompressor
 from cqrs.container.di import DIContainer
 from cqrs.container.protocol import Container
 from cqrs.events import EventMap
-from cqrs.events.event import DomainEvent, ECSTEvent, Event, NotificationEvent
+from cqrs.events.event import DomainEvent, Event, NotificationEvent
 from cqrs.events.event_emitter import EventEmitter
 from cqrs.events.event_handler import EventHandler, SyncEventHandler
 from cqrs.mediator import EventMediator, RequestMediator
-from cqrs.outbox.producer import EventProducer
+from cqrs.producer import EventProducer
 from cqrs.outbox.repository import OutboxedEventRepository
 from cqrs.outbox.sqlalchemy import SqlAlchemyOutboxedEventRepository
+from cqrs.outbox.map import OutboxedEventMap
 from cqrs.requests import RequestMap
 from cqrs.requests.request import Request
 from cqrs.requests.request_handler import RequestHandler, SyncRequestHandler
@@ -20,11 +20,11 @@ __all__ = (
     "EventMediator",
     "DomainEvent",
     "NotificationEvent",
-    "ECSTEvent",
     "Event",
     "EventEmitter",
     "EventHandler",
     "EventMap",
+    "OutboxedEventMap",
     "SyncEventHandler",
     "Request",
     "RequestHandler",
@@ -34,8 +34,8 @@ __all__ = (
     "OutboxedEventRepository",
     "SqlAlchemyOutboxedEventRepository",
     "EventProducer",
-    "Compressor",
-    "ZlibCompressor",
     "Container",
     "DIContainer",
+    "Compressor",
+    "ZlibCompressor",
 )

{python_cqrs-1.0.0 → python_cqrs-2.0.2}/src/cqrs/adapters/kafka.py

@@ -4,10 +4,11 @@ import logging
 import typing
 
 import aiokafka
-import orjson
 import retry_async
 from aiokafka import errors
 
+from cqrs.serializers import default
+
 __all__ = (
     "KafkaProducer",
     "kafka_producer_factory",
@@ -40,9 +41,7 @@ SaslMechanism: typing.TypeAlias = typing.Literal[
 logger = logging.getLogger("cqrs")
 logger.setLevel(logging.DEBUG)
 
-
-def _serializer(message: typing.Dict) -> typing.ByteString:
-    return orjson.dumps(message)
+Serializer = typing.Callable[[typing.Any], typing.ByteString | None]
 
 
 class _Singleton(type):
@@ -70,12 +69,12 @@ class KafkaProducer(metaclass=_Singleton):
         if not await self._producer.client.ready(node_id=node_id):
             await self._producer.start()
 
-    async def _produce(self, topic: typing.Text, message: typing.Dict):
+    async def _produce(self, topic: typing.Text, message: typing.Any):
         await self._check_connection()
         logger.debug(f"produce message {message} to topic {topic}")
         await self._producer.send_and_wait(topic, value=message)
 
-    async def produce(self, topic: typing.Text, message: typing.Dict):
+    async def produce(self, topic: typing.Text, message: typing.Any):
         """
         Produces event to kafka broker.
         Tries to reconnect if connect has been lost or has not been opened.
@@ -94,13 +93,14 @@ def kafka_producer_factory(
     retry_delay: int = 1,
     user: typing.Text | None = None,
     password: typing.Text | None = None,
+    value_serializer: Serializer | None = None,
 ) -> KafkaProducer:
     loop = asyncio.get_event_loop()
     asyncio.set_event_loop(loop)
 
     producer = aiokafka.AIOKafkaProducer(
         bootstrap_servers=dsn,
-        value_serializer=_serializer,
+        value_serializer=value_serializer or default.default_serializer,
         security_protocol=security_protocol,
         sasl_mechanism=sasl_mechanism,
         sasl_plain_username=user,

python_cqrs-2.0.2/src/cqrs/compressors/__init__.py

@@ -0,0 +1,4 @@
+from cqrs.compressors.protocol import Compressor
+from cqrs.compressors.zlib import ZlibCompressor
+
+__all__ = ("ZlibCompressor", "Compressor")

python_cqrs-2.0.2/src/cqrs/deserializers/protobuf.py

@@ -0,0 +1,52 @@
+import logging
+import typing
+
+import pydantic
+from confluent_kafka.schema_registry import protobuf
+from google.protobuf.message import Message
+
+import cqrs
+
+logger = logging.getLogger("cqrs")
+
+
+class ProtobufValueDeserializer:
+    """
+    Deserialize protobuf message into CQRS event model.
+    """
+
+    def __init__(
+        self,
+        model: typing.Type[cqrs.NotificationEvent],
+        protobuf_model: typing.Type[Message],
+    ):
+        self._model = model
+        self._protobuf_model = protobuf_model
+
+    def __call__(
+        self,
+        msg: typing.ByteString,
+    ) -> cqrs.NotificationEvent | None:
+        protobuf_deserializer = protobuf.ProtobufDeserializer(
+            self._protobuf_model,
+            {"use.deprecated.format": False},
+        )
+        try:
+            proto_event = protobuf_deserializer(msg, None)
+        except Exception as error:
+            logger.error(
+                f"Error while deserializing protobuf message: {error}",
+            )
+            return
+
+        if proto_event is None:
+            logger.debug("Protobuf message is empty")
+            return
+
+        try:
+            return self._model.model_validate(proto_event)
+        except pydantic.ValidationError as error:
+            logger.error(
+                f"Error while deserializing protobuf message: {error}",
+            )
+            return

{python_cqrs-1.0.0 → python_cqrs-2.0.2}/src/cqrs/events/__init__.py

@@ -1,4 +1,4 @@
-from cqrs.events.event import DomainEvent, ECSTEvent, Event, NotificationEvent
+from cqrs.events.event import DomainEvent, Event, NotificationEvent
 from cqrs.events.event_emitter import EventEmitter
 from cqrs.events.event_handler import EventHandler
 from cqrs.events.map import EventMap
@@ -6,7 +6,6 @@ from cqrs.events.map import EventMap
 __all__ = (
     "Event",
     "DomainEvent",
-    "ECSTEvent",
     "NotificationEvent",
     "EventEmitter",
     "EventHandler",

python_cqrs-2.0.2/src/cqrs/events/event.py

@@ -0,0 +1,59 @@
+import datetime
+import logging
+import os
+import typing
+import uuid
+
+import dotenv
+import pydantic
+
+logger = logging.getLogger("cqrs")
+
+try:
+    from google.protobuf.message import Message  # noqa
+except ImportError:
+    logger.warning(
+        "Please install protobuf dependencies with: `pip install python-cqrs[protobuf]`",
+    )
+
+dotenv.load_dotenv()
+
+DEFAULT_OUTPUT_TOPIC = os.getenv("DEFAULT_OUTPUT_TOPIC", "output_topic")
+
+
+class Event(pydantic.BaseModel, frozen=True):
+    """
+    The base class for events
+    """
+
+
+class DomainEvent(Event, frozen=True):
+    """
+    The base class for domain events
+    """
+
+
+_P = typing.TypeVar("_P", typing.Any, None)
+
+
+class NotificationEvent(Event, typing.Generic[_P], frozen=True):
+    """
+    The base class for notification events
+    """
+
+    event_id: uuid.UUID = pydantic.Field(default_factory=uuid.uuid4)
+    event_timestamp: datetime.datetime = pydantic.Field(
+        default_factory=datetime.datetime.now,
+    )
+    event_name: typing.Text
+    topic: typing.Text = pydantic.Field(default=DEFAULT_OUTPUT_TOPIC)
+
+    payload: _P = pydantic.Field(default=None)
+
+    model_config = pydantic.ConfigDict(from_attributes=True)
+
+    def proto(self) -> "Message":
+        raise NotImplementedError("Method not implemented")
+
+    def __hash__(self):
+        return hash(self.event_id)

{python_cqrs-1.0.0 → python_cqrs-2.0.2}/src/cqrs/events/event_emitter.py

@@ -33,18 +33,17 @@ class EventEmitter:
 
     async def _send_to_broker(
         self,
-        event: event_model.NotificationEvent | event_model.ECSTEvent,
+        event: event_model.NotificationEvent,
     ) -> None:
         """
         Sends event to the message broker.
         """
         if not self._message_broker:
             raise RuntimeError(
-                f"To use {event.event_type}, message_broker argument must be specified.",
+                f"To send event {event}, message_broker argument must be specified.",
             )
 
         message = message_brokers.Message(
-            message_type=event.event_type,
             message_name=type(event).__name__,
             message_id=event.event_id,
             topic=event.topic,
@@ -52,8 +51,7 @@ class EventEmitter:
         )
 
         logger.debug(
-            "Sending %s Event(%s) to message broker %s",
-            event.event_type,
+            "Sending Event(%s) to message broker %s",
             event.event_id,
             type(self._message_broker).__name__,
         )
@@ -85,7 +83,3 @@ class EventEmitter:
     @emit.register
     async def _(self, event: event_model.NotificationEvent) -> None:
         await self._send_to_broker(event)
-
-    @emit.register
-    async def _(self, event: event_model.ECSTEvent) -> None:
-        await self._send_to_broker(event)

{python_cqrs-1.0.0 → python_cqrs-2.0.2}/src/cqrs/message_brokers/protocol.py

@@ -6,11 +6,10 @@ import pydantic
 
 
 class Message(pydantic.BaseModel):
-    message_type: typing.Text = pydantic.Field()
     message_name: typing.Text = pydantic.Field()
     message_id: uuid.UUID = pydantic.Field(default_factory=uuid.uuid4)
     topic: typing.Text
-    payload: typing.Dict
+    payload: typing.Any
 
 
 class MessageBroker(abc.ABC):

python_cqrs-2.0.2/src/cqrs/outbox/map.py

@@ -0,0 +1,24 @@
+import typing
+
+from cqrs.events import event
+
+
+class OutboxedEventMap:
+    _registry: typing.Dict[typing.Text, typing.Type[event.NotificationEvent]] = {}
+
+    @classmethod
+    def register(
+        cls,
+        event_name: typing.Text,
+        event_type: typing.Type[event.NotificationEvent],
+    ) -> None:
+        if event_name in cls._registry:
+            raise KeyError(f"Event with {event_name} already registered")
+        cls._registry[event_name] = event_type
+
+    @classmethod
+    def get(
+        cls,
+        event_name: typing.Text,
+    ) -> typing.Type[event.NotificationEvent] | None:
+        return cls._registry.get(event_name)

python_cqrs-2.0.2/src/cqrs/outbox/mock.py

@@ -0,0 +1,55 @@
+import typing
+
+import cqrs
+from cqrs.outbox import repository
+
+
+class MockOutboxedEventRepository(repository.OutboxedEventRepository[typing.Dict]):
+    COUNTER: typing.ClassVar = 0
+
+    def __init__(self, session_factory: typing.Callable[[], typing.Dict]):
+        self.session = session_factory()
+
+    async def __aenter__(self) -> typing.Dict:
+        return self.session
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        pass
+
+    def add(self, session: typing.Dict, event: cqrs.NotificationEvent) -> None:
+        MockOutboxedEventRepository.COUNTER += 1
+        session[MockOutboxedEventRepository.COUNTER] = repository.OutboxedEvent(
+            id=MockOutboxedEventRepository.COUNTER,
+            event=event,
+            topic=event.topic,
+            status=repository.EventStatus.NEW,
+        )
+
+    async def get_many(
+        self,
+        session: typing.Dict,
+        batch_size: int = 100,
+        topic: typing.Text | None = None,
+    ) -> typing.List[repository.OutboxedEvent]:
+        return list(
+            filter(lambda e: topic == e.topic, session.values())
+            if topic
+            else list(session.values()),
+        )
+
+    async def update_status(
+        self,
+        session: typing.Dict,
+        outboxed_event_id: int,
+        new_status: repository.EventStatus,
+    ):
+        if outboxed_event_id not in session:
+            return
+        if new_status is repository.EventStatus.PRODUCED:
+            del session[outboxed_event_id]
+
+    async def commit(self, session: typing.Dict):
+        pass
+
+    async def rollback(self, session: typing.Dict):
+        pass

{python_cqrs-1.0.0 → python_cqrs-2.0.2}/src/cqrs/outbox/repository.py

@@ -1,12 +1,12 @@
 import abc
 import enum
 import typing
-import uuid
+
+import pydantic
 
 import cqrs
 from cqrs.events import event as ev
 
-Event = typing.TypeVar("Event", ev.NotificationEvent, ev.ECSTEvent, contravariant=True)
 Session = typing.TypeVar("Session")
 
 
@@ -16,15 +16,14 @@ class EventStatus(enum.StrEnum):
     NOT_PRODUCED = "not_produced"
 
 
-class OutboxedEventRepository(abc.ABC, typing.Generic[Session]):
-    def __init__(
-        self,
-        session_factory: typing.Callable[[], Session],
-        compressor: cqrs.Compressor | None = None,
-    ):
-        self._session_factory = session_factory
-        self._compressor = compressor
+class OutboxedEvent(pydantic.BaseModel, frozen=True):
+    id: pydantic.PositiveInt
+    event: cqrs.NotificationEvent
+    topic: typing.Text
+    status: EventStatus
 
+
+class OutboxedEventRepository(abc.ABC, typing.Generic[Session]):
     @abc.abstractmethod
     async def __aenter__(self) -> Session:
         """start transaction"""
@@ -37,28 +36,24 @@ class OutboxedEventRepository(abc.ABC, typing.Generic[Session]):
     def add(
         self,
         session: Session,
-        event: Event,
+        event: ev.NotificationEvent,
     ) -> None:
         """Add an event to the repository."""
 
-    @abc.abstractmethod
-    async def get_one(self, session: Session, event_id: uuid.UUID) -> Event | None:
-        """Get one event from the repository."""
-
     @abc.abstractmethod
     async def get_many(
         self,
         session: Session,
         batch_size: int = 100,
         topic: typing.Text | None = None,
-    ) -> typing.List[Event]:
+    ) -> typing.List[OutboxedEvent]:
         """Get many events from the repository."""
 
     @abc.abstractmethod
     async def update_status(
         self,
         session: Session,
-        event_id: uuid.UUID,
+        outboxed_event_id: int,
         new_status: EventStatus,
     ):
         """Update the event status"""