package-events-bus 0.1.0__tar.gz

package_events_bus-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 FK2.0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package_events_bus-0.1.0/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.3
+Name: package-events-bus
+Version: 0.1.0
+Summary: Una librería para construir microservicios desacoplados en Python usando AWS EventBridge y SQS, donde cada caso de uso maneja su propia cola y se despacha automáticamente mediante handlers tipados.
+License: MIT
+Author: Jose Luis Rosales Meza
+Author-email: jose.rosales@finkargo.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: boto3 (>=1.38.13,<2.0.0)
+Requires-Dist: python-dotenv (>=1.1.0,<2.0.0)
+Requires-Dist: redis (>=5.0,<6.0)
+Description-Content-Type: text/markdown
+
+# 📦 Package Events Bus
+
+Una librería para construir servicios desacoplados en Python usando AWS EventBridge y SQS, donde cada caso de uso maneja su propia cola.
+
+---
+
+## � Tabla de Contenidos
+
+- [📦 Package Events Bus](#-package-events-bus)
+  - [� Tabla de Contenidos](#-tabla-de-contenidos)
+  - [📝 Descripción](#-descripción)
+  - [⚙️ Instalación](#️-instalación)
+  - [🗂️ Estructura del Proyecto](#️-estructura-del-proyecto)
+  - [💡 ¿Cómo usarlo?](#-cómo-usarlo)
+    - [📤 Publicar eventos](#-publicar-eventos)
+    - [📥 Consumir eventos](#-consumir-eventos)
+    - [⚡ ¿Cómo implementar el dispatcher en FastAPI?](#-cómo-implementar-el-dispatcher-en-fastapi)
+    - [🛡️ Opcional: Configuración de Redis para deduplicación](#️-opcional-configuración-de-redis-para-deduplicación)
+  - [⚙️ Variables por Defecto](#️-variables-por-defecto)
+  - [🏷️ Definición de Topics](#️-definición-de-topics)
+  - [🛠️ TODO](#️-todo)
+  - [📝 Buenas Prácticas](#-buenas-prácticas)
+  - [📄 Licencia](#-licencia)
+
+---
+
+## 📝 Descripción
+
+Esta librería permite construir microservicios desacoplados en Python, facilitando la publicación y consumo de eventos a través de AWS EventBridge y SQS. Cada caso de uso maneja su propia cola, permitiendo escalabilidad y mantenibilidad.
+
+---
+
+## ⚙️ Instalación
+
+Instala la librería usando **pip**:
+
+```bash
+pip install package-events-bus
+```
+
+O usando **poetry**:
+
+```bash
+poetry add package-events-bus
+```
+
+---
+
+## 🗂️ Estructura del Proyecto
+
+```
+package_events_bus/
+├── __init__.py
+├── config.py
+├── exceptions.py
+├── .vscode/settings.json
+├── aws/
+│   ├── event_bridge_publisher.py
+│   └── sqs_dispatcher.py
+├── core/
+│   ├── __init__.py
+│   ├── contracts/
+│   │   ├── base_event.py
+│   │   ├── deduplication.py
+│   │   └── handler.py
+│   ├── infrastructure/
+│   │   ├── event_bus_publisher.py
+│   │   ├── event_serializer.py
+│   │   └── redis_deduplication.py
+│   └── runtime/
+│       └── event_register.py
+```
+
+- **/aws:** Implementaciones específicas para servicios de AWS.
+  - **event_bridge_publisher.py:** Publica eventos a AWS EventBridge.
+  - **sqs_dispatcher.py:** Despacha mensajes de colas SQS y procesa eventos.
+
+---
+
+## 💡 ¿Cómo usarlo?
+
+### 📤 Publicar eventos
+
+1. Crea una instancia de `EventBridgePublisher` y llama a `publish` con el evento deseado.
+
+```python
+from events_bus.aws.event_bridge_publisher import EventBridgePublisher
+
+event_bridge_publisher = EventBridgePublisher(
+    bus_name="finkargo-events",
+    source="my.service",
+)
+```
+
+2. Define tu evento heredando de `BaseEvent`:
+   Reemplaza `DisbursementCreatedEvent` con el nombre de tu evento, recuerda sobreescribir el método `to_dict` para serializar los atributos del evento que deseas enviar.
+
+```python
+from events_bus.core.contracts.base_event import BaseEvent
+
+@dataclass
+class DisbursementCreatedEvent(BaseEvent):
+    event_name = 'finkargo.portfolio.1.event.disbursement.created'
+
+    def __init__(self, disbursement):
+        super().__init__(event_name=self.event_name)
+        self.id_disbursement = disbursement.id_disbursement
+
+    def to_dict(self) -> dict:
+        return {
+            'id_disbursement': self.id_disbursement
+        }
+
+    @classmethod
+    def from_dict(cls, event_id: str, occurred_on, attributes: dict) -> "DisbursementCreatedEvent":
+        return cls(disbursement_id=attributes.get('id_disbursement'))
+
+event_bridge_publisher.publish(event=DisbursementCreatedEvent(instance))
+```
+
+---
+
+### 📥 Consumir eventos
+
+1. Hereda de `AsyncHandler` o `SyncHandler` y sobrescribe el método `handle`.
+    El método `handle` recibe el evento como parámetro, recuerda que el evento debe heredar de `BaseEvent`,
+    y el método `from_dict` debe estar implementado para poder deserializar el evento.
+
+    Usa `AsyncHandler` para manejar eventos de forma asíncrona y `SyncHandler` para eventos sincrónicos.
+
+```python
+from events_bus.core import AsyncHandler
+
+class CustomAsyncHandler(AsyncHandler):
+    async def handle(self, data: DisbursementCreatedEvent):
+        print(f"Handling event: {data.event_name}")
+        print(f"Finished handling event: {data.event_name}")
+```
+
+2. Registra el handler en el bus de eventos:
+    Usa `EventHandlerRegister` para registrar el handler y la cola SQS asociada, recuerda que el target debe ser configurado previamente en AWS.
+    Para mas información sobre la configuración de AWS, consulta la [documentación oficial](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-targets.html).
+
+```python
+from events_bus.core import EventHandlerRegister
+from events_bus.aws.sqs_dispatcher import SQSDispatcher
+
+dispatcher = SQSDispatcher()
+EventHandlerRegister.register(
+    queue_url='https://sqs.us-east-1.amazonaws.com/123456789012/my-queue',
+    handler=CustomAsyncHandler()
+)
+```
+
+---
+
+### ⚡ ¿Cómo implementar el dispatcher en FastAPI?
+
+```python
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await dispatcher.start()
+    yield
+    dispatcher.stop()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+---
+
+### 🛡️ Opcional: Configuración de Redis para deduplicación
+
+```python
+from events_bus.core import RedisDeduplication
+from events_bus.aws.sqs_dispatcher import SQSDispatcher
+
+deduplication = RedisDeduplication(
+    url='redis://localhost:6379/0',
+    ttl=3600,
+)
+
+dispatcher = SQSDispatcher(deduplication=deduplication)
+```
+
+> Si no deseas usar Redis, puedes heredar de `BaseDeduplication` e implementar tu propia lógica.
+
+---
+
+## ⚙️ Variables por Defecto
+
+```python
+from events_bus import CONFIG
+CONFIG.set_envs(os.environ, env_file='.env')
+```
+
+Puedes modificar las variables por defecto de la librería usando un archivo `.env` o configurando las variables de entorno directamente. Las variables configurables son:
+
+| Variable                    | Tipo | Por defecto |Descripción                                                                 |
+|-------------------------------|---------|----------------|-------------------------------------------------------------------------------|
+| MAX_NUMBER_OF_MESSAGES         | int     | 5              | Número máximo de mensajes a recibir por llamada.                              |
+| WAIT_TIME_SECONDS              | int     | 10             | Tiempo de espera para recibir mensajes.                                       |
+| VISIBILITY_TIMEOUT             | int     | 30             | Tiempo de visibilidad del mensaje en la cola.                                 |
+| AWS_CLIENT_URL                 | str     | None           | URL del cliente de AWS (útil para LocalStack u otros entornos locales).       |
+| AWS_REGION_NAME                | str     | us-east-1      | Región de AWS.                                                                |
+| SLEEP_BETWEEN_MESSAGES_SECONDS | float   | 0.1            | Tiempo de espera entre mensajes.                                              |
+| ERROR_SLEEP_SECONDS            | int     | 5              | Tiempo de espera en caso de error.                                            |
+
+> ℹ️ **Tip:** Usa `.env` para mantener tu configuración fuera del código fuente.
+
+---
+## 🏷️ Definición de Topics
+
+Los topics deben seguir la convención:
+
+```
+COMPANY.SERVICE.VERSION.MESSAGE_TYPE.RESOURCE_NAME.(EVENT_COMMAND_NAME)
+```
+
+- **COMPANY:** Nombre de la empresa (`Finkargo` para internos).
+- **SERVICE:** Servicio generador del evento.
+- **VERSION:** Versión del topic.
+- **MESSAGE_TYPE:** `command` o `event`.
+- **RESOURCE_NAME:** Entidad relacionada.
+- **EVENT_COMMAND_NAME:** Verbo en pasado para eventos (`created`), infinitivo para comandos (`create`).
+
+**Regex de validación:**
+
+```
+TOPIC_REGEX = "^[a-zA-Z0-9_]+\.[a-zA-Z0-9_]+\.\d+\.(command|event)\.[a-zA-Z0-9_]+\.[a-zA-Z0-9_]+$"
+```
+
+Basado en: [Topics Definition | AsyncApi](https://github.com/fmvilas/topic-definition)
+
+---
+
+## 🛠️ TODO
+
+- [ ]  Mejorar el control de excepciones en la publicación de eventos.
+- [ ]  Agregar más ejemplos de integración con otros frameworks.
+- [ ]  Documentar casos de uso avanzados.
+- [ ]  Implementar métricas y logging para los eventos publicados y consumidos.
+- [ ]  Añadir pruebas unitarias y de integración.
+- [ ]  Mejorar la documentación en inglés y español.
+
+---
+
+## 📝 Buenas Prácticas
+
+- Usa nombres de eventos claros y consistentes.
+- Implementa deduplicación para evitar procesar eventos repetidos.
+- Mantén tus handlers simples y enfocados en una sola responsabilidad.
+- Documenta tus eventos y handlers.
+
+---
+## 📄 Licencia
+
+Este proyecto está bajo la licencia MIT.
+
+

package_events_bus-0.1.0/README.md

@@ -0,0 +1,258 @@
+# 📦 Package Events Bus
+
+Una librería para construir servicios desacoplados en Python usando AWS EventBridge y SQS, donde cada caso de uso maneja su propia cola.
+
+---
+
+## � Tabla de Contenidos
+
+- [📦 Package Events Bus](#-package-events-bus)
+  - [� Tabla de Contenidos](#-tabla-de-contenidos)
+  - [📝 Descripción](#-descripción)
+  - [⚙️ Instalación](#️-instalación)
+  - [🗂️ Estructura del Proyecto](#️-estructura-del-proyecto)
+  - [💡 ¿Cómo usarlo?](#-cómo-usarlo)
+    - [📤 Publicar eventos](#-publicar-eventos)
+    - [📥 Consumir eventos](#-consumir-eventos)
+    - [⚡ ¿Cómo implementar el dispatcher en FastAPI?](#-cómo-implementar-el-dispatcher-en-fastapi)
+    - [🛡️ Opcional: Configuración de Redis para deduplicación](#️-opcional-configuración-de-redis-para-deduplicación)
+  - [⚙️ Variables por Defecto](#️-variables-por-defecto)
+  - [🏷️ Definición de Topics](#️-definición-de-topics)
+  - [🛠️ TODO](#️-todo)
+  - [📝 Buenas Prácticas](#-buenas-prácticas)
+  - [📄 Licencia](#-licencia)
+
+---
+
+## 📝 Descripción
+
+Esta librería permite construir microservicios desacoplados en Python, facilitando la publicación y consumo de eventos a través de AWS EventBridge y SQS. Cada caso de uso maneja su propia cola, permitiendo escalabilidad y mantenibilidad.
+
+---
+
+## ⚙️ Instalación
+
+Instala la librería usando **pip**:
+
+```bash
+pip install package-events-bus
+```
+
+O usando **poetry**:
+
+```bash
+poetry add package-events-bus
+```
+
+---
+
+## 🗂️ Estructura del Proyecto
+
+```
+package_events_bus/
+├── __init__.py
+├── config.py
+├── exceptions.py
+├── .vscode/settings.json
+├── aws/
+│   ├── event_bridge_publisher.py
+│   └── sqs_dispatcher.py
+├── core/
+│   ├── __init__.py
+│   ├── contracts/
+│   │   ├── base_event.py
+│   │   ├── deduplication.py
+│   │   └── handler.py
+│   ├── infrastructure/
+│   │   ├── event_bus_publisher.py
+│   │   ├── event_serializer.py
+│   │   └── redis_deduplication.py
+│   └── runtime/
+│       └── event_register.py
+```
+
+- **/aws:** Implementaciones específicas para servicios de AWS.
+  - **event_bridge_publisher.py:** Publica eventos a AWS EventBridge.
+  - **sqs_dispatcher.py:** Despacha mensajes de colas SQS y procesa eventos.
+
+---
+
+## 💡 ¿Cómo usarlo?
+
+### 📤 Publicar eventos
+
+1. Crea una instancia de `EventBridgePublisher` y llama a `publish` con el evento deseado.
+
+```python
+from events_bus.aws.event_bridge_publisher import EventBridgePublisher
+
+event_bridge_publisher = EventBridgePublisher(
+    bus_name="finkargo-events",
+    source="my.service",
+)
+```
+
+2. Define tu evento heredando de `BaseEvent`:
+   Reemplaza `DisbursementCreatedEvent` con el nombre de tu evento, recuerda sobreescribir el método `to_dict` para serializar los atributos del evento que deseas enviar.
+
+```python
+from events_bus.core.contracts.base_event import BaseEvent
+
+@dataclass
+class DisbursementCreatedEvent(BaseEvent):
+    event_name = 'finkargo.portfolio.1.event.disbursement.created'
+
+    def __init__(self, disbursement):
+        super().__init__(event_name=self.event_name)
+        self.id_disbursement = disbursement.id_disbursement
+
+    def to_dict(self) -> dict:
+        return {
+            'id_disbursement': self.id_disbursement
+        }
+
+    @classmethod
+    def from_dict(cls, event_id: str, occurred_on, attributes: dict) -> "DisbursementCreatedEvent":
+        return cls(disbursement_id=attributes.get('id_disbursement'))
+
+event_bridge_publisher.publish(event=DisbursementCreatedEvent(instance))
+```
+
+---
+
+### 📥 Consumir eventos
+
+1. Hereda de `AsyncHandler` o `SyncHandler` y sobrescribe el método `handle`.
+    El método `handle` recibe el evento como parámetro, recuerda que el evento debe heredar de `BaseEvent`,
+    y el método `from_dict` debe estar implementado para poder deserializar el evento.
+
+    Usa `AsyncHandler` para manejar eventos de forma asíncrona y `SyncHandler` para eventos sincrónicos.
+
+```python
+from events_bus.core import AsyncHandler
+
+class CustomAsyncHandler(AsyncHandler):
+    async def handle(self, data: DisbursementCreatedEvent):
+        print(f"Handling event: {data.event_name}")
+        print(f"Finished handling event: {data.event_name}")
+```
+
+2. Registra el handler en el bus de eventos:
+    Usa `EventHandlerRegister` para registrar el handler y la cola SQS asociada, recuerda que el target debe ser configurado previamente en AWS.
+    Para mas información sobre la configuración de AWS, consulta la [documentación oficial](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-targets.html).
+
+```python
+from events_bus.core import EventHandlerRegister
+from events_bus.aws.sqs_dispatcher import SQSDispatcher
+
+dispatcher = SQSDispatcher()
+EventHandlerRegister.register(
+    queue_url='https://sqs.us-east-1.amazonaws.com/123456789012/my-queue',
+    handler=CustomAsyncHandler()
+)
+```
+
+---
+
+### ⚡ ¿Cómo implementar el dispatcher en FastAPI?
+
+```python
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await dispatcher.start()
+    yield
+    dispatcher.stop()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+---
+
+### 🛡️ Opcional: Configuración de Redis para deduplicación
+
+```python
+from events_bus.core import RedisDeduplication
+from events_bus.aws.sqs_dispatcher import SQSDispatcher
+
+deduplication = RedisDeduplication(
+    url='redis://localhost:6379/0',
+    ttl=3600,
+)
+
+dispatcher = SQSDispatcher(deduplication=deduplication)
+```
+
+> Si no deseas usar Redis, puedes heredar de `BaseDeduplication` e implementar tu propia lógica.
+
+---
+
+## ⚙️ Variables por Defecto
+
+```python
+from events_bus import CONFIG
+CONFIG.set_envs(os.environ, env_file='.env')
+```
+
+Puedes modificar las variables por defecto de la librería usando un archivo `.env` o configurando las variables de entorno directamente. Las variables configurables son:
+
+| Variable                    | Tipo | Por defecto |Descripción                                                                 |
+|-------------------------------|---------|----------------|-------------------------------------------------------------------------------|
+| MAX_NUMBER_OF_MESSAGES         | int     | 5              | Número máximo de mensajes a recibir por llamada.                              |
+| WAIT_TIME_SECONDS              | int     | 10             | Tiempo de espera para recibir mensajes.                                       |
+| VISIBILITY_TIMEOUT             | int     | 30             | Tiempo de visibilidad del mensaje en la cola.                                 |
+| AWS_CLIENT_URL                 | str     | None           | URL del cliente de AWS (útil para LocalStack u otros entornos locales).       |
+| AWS_REGION_NAME                | str     | us-east-1      | Región de AWS.                                                                |
+| SLEEP_BETWEEN_MESSAGES_SECONDS | float   | 0.1            | Tiempo de espera entre mensajes.                                              |
+| ERROR_SLEEP_SECONDS            | int     | 5              | Tiempo de espera en caso de error.                                            |
+
+> ℹ️ **Tip:** Usa `.env` para mantener tu configuración fuera del código fuente.
+
+---
+## 🏷️ Definición de Topics
+
+Los topics deben seguir la convención:
+
+```
+COMPANY.SERVICE.VERSION.MESSAGE_TYPE.RESOURCE_NAME.(EVENT_COMMAND_NAME)
+```
+
+- **COMPANY:** Nombre de la empresa (`Finkargo` para internos).
+- **SERVICE:** Servicio generador del evento.
+- **VERSION:** Versión del topic.
+- **MESSAGE_TYPE:** `command` o `event`.
+- **RESOURCE_NAME:** Entidad relacionada.
+- **EVENT_COMMAND_NAME:** Verbo en pasado para eventos (`created`), infinitivo para comandos (`create`).
+
+**Regex de validación:**
+
+```
+TOPIC_REGEX = "^[a-zA-Z0-9_]+\.[a-zA-Z0-9_]+\.\d+\.(command|event)\.[a-zA-Z0-9_]+\.[a-zA-Z0-9_]+$"
+```
+
+Basado en: [Topics Definition | AsyncApi](https://github.com/fmvilas/topic-definition)
+
+---
+
+## 🛠️ TODO
+
+- [ ]  Mejorar el control de excepciones en la publicación de eventos.
+- [ ]  Agregar más ejemplos de integración con otros frameworks.
+- [ ]  Documentar casos de uso avanzados.
+- [ ]  Implementar métricas y logging para los eventos publicados y consumidos.
+- [ ]  Añadir pruebas unitarias y de integración.
+- [ ]  Mejorar la documentación en inglés y español.
+
+---
+
+## 📝 Buenas Prácticas
+
+- Usa nombres de eventos claros y consistentes.
+- Implementa deduplicación para evitar procesar eventos repetidos.
+- Mantén tus handlers simples y enfocados en una sola responsabilidad.
+- Documenta tus eventos y handlers.
+
+---
+## 📄 Licencia
+
+Este proyecto está bajo la licencia MIT.
+

package_events_bus-0.1.0/events_bus/__init__.py

@@ -0,0 +1,4 @@
+from .config import Config
+
+
+CONFIG = Config()

package_events_bus-0.1.0/events_bus/aws/event_bridge_publisher.py

@@ -0,0 +1,43 @@
+import boto3
+
+from .. import CONFIG
+from ..core import (EventBusPublisher, BaseEvent,
+                    EventJsonSerializerDeserializer)
+
+
+class EventBridgePublisher(EventBusPublisher):
+    def __init__(self, bus_name: str, source: str):
+        self.client = boto3.client('events',
+                                   region_name=CONFIG.AWS_REGION_NAME,
+                                   endpoint_url=CONFIG.AWS_CLIENT_URL)
+        self.bus_name = bus_name
+        self.source = source
+
+    def publish(self, event: BaseEvent):
+        """Publish a single event to the EventBridge bus."""
+        # TODO: Add try/except for publish
+        self.client.put_events(
+            Entries=[
+                {
+                    'Source': self.source,
+                    'DetailType': event.event_name,
+                    'Detail': EventJsonSerializerDeserializer.serialize(event),
+                    'EventBusName': self.bus_name,
+                }
+            ]
+        )
+
+    def publish_batch(self, events: list[BaseEvent]):
+        """Publish a batch of events to the EventBridge bus."""
+        # TODO: Add try/except for publish_batch
+        entries = []
+        for event in events:
+            entries.append(
+                {
+                    'Source': self.source,
+                    'DetailType': event.event_name,
+                    'Detail': EventJsonSerializerDeserializer.serialize(event),
+                    'EventBusName': self.bus_name,
+                }
+            )
+        self.client.put_events(Entries=entries)

package_events_bus-0.1.0/events_bus/aws/sqs_dispatcher.py

@@ -0,0 +1,136 @@
+import boto3
+import asyncio
+import logging
+import traceback
+
+from .. import CONFIG
+from ..core import (EventHandlerRegistry, BaseHandler,
+                    EventJsonSerializerDeserializer, AsyncHandler,
+                    SyncHandler, BaseDeduplication)
+from ..exceptions import (HandlerExecutionError, DeserializationEventError)
+
+
+class SQSDispatcher:
+    """Dispatcher for handling events from AWS SQS queues.
+    This class is responsible for polling SQS queues, deserializing events,
+    executing handlers, and managing deduplication of events.
+    """  # noqa: E501
+
+    def __init__(self, deduplication: BaseDeduplication = None):
+        """
+        Initialize the SQSDispatcher.
+        Args:
+            deduplication (BaseDeduplication, optional): An instance of a deduplication strategy.
+                If provided, it will be used to check for duplicate events.
+                Defaults to None. Can be an instance of `RedisDeduplication`
+                or any other class that implements the `BaseDeduplication` interface.. Example:
+                    >>> from events_bus.core.infrastructure.redis_deduplication import RedisDeduplication
+                    >>> deduplication = RedisDeduplication(url='redis://localhost:6379/0')
+                    >>> dispatcher = SQSDispatcher(deduplication=deduplication)
+        """  # noqa: E501
+        self.client = boto3.client('sqs',
+                                   region_name=CONFIG.AWS_REGION_NAME,
+                                   endpoint_url=CONFIG.AWS_CLIENT_URL)
+        self._stop_event = asyncio.Event()
+        self.deduplication = deduplication
+
+    def stop(self):
+        self._stop_event.set()
+
+    async def start(self):
+        """Start the SQS dispatcher.
+        This method initializes the SQS client and starts polling the queues
+        registered in the `EventHandlerRegistry`. It creates a separate task
+        for each queue to handle events concurrently.
+        """  # noqa: E501
+        for queue_url, handler in EventHandlerRegistry.get_handlers().items():
+            task = asyncio.create_task(self._poll_queue(queue_url, handler))  # noqa: E501
+            task.add_done_callback(self._handle_task_exception)
+
+    def consume(self):
+        """Consume messages from the SQS queues.
+        """
+        for queue_url, handler in EventHandlerRegistry.get_handlers().items():
+            task = asyncio.create_task(self._execute(queue_url, handler))
+            task.add_done_callback(self._handle_task_exception)
+
+    def _handle_task_exception(self, task: asyncio.Task):
+        try:
+            exc = task.exception()
+            if exc:
+                logging.error(
+                    f"An error occurred in task {task.get_name()}: {exc}")
+        except asyncio.CancelledError:
+            logging.info(f"The task {task.get_name()} was cancelled.")
+
+    async def _poll_queue(self, queue_url, handler: BaseHandler):  # noqa: E501
+        while not self._stop_event.is_set():
+            await self._execute(
+                queue_url=queue_url,
+                handler=handler
+            )
+
+    async def _execute(self, queue_url, handler: BaseHandler):
+        event_name = None
+        try:
+            response = await asyncio.to_thread(
+                self.client.receive_message,
+                QueueUrl=queue_url,
+                MaxNumberOfMessages=CONFIG.MAX_NUMBER_OF_MESSAGES,
+                WaitTimeSeconds=CONFIG.WAIT_TIME_SECONDS,
+                VisibilityTimeout=CONFIG.VISIBILITY_TIMEOUT,
+            )
+
+            for msg in response.get('Messages', []):
+                event_name = await self._process_message(queue_url, msg, handler)   # noqa: E50
+                await asyncio.sleep(CONFIG.SLEEP_BETWEEN_MESSAGES_SECONDS)
+        except (Exception, HandlerExecutionError, DeserializationEventError):  # noqa: E501
+            logging.error(traceback.format_exc())
+            logging.error(
+                f"""Error processing message from queue {queue_url}\n 'EventName': {event_name}"""  # noqa: E501
+            )
+            await asyncio.sleep(CONFIG.ERROR_SLEEP_SECONDS)  # noqa: E501
+
+    async def _execute_handler(self, handler: BaseHandler, event, event_name: str):  # noqa: E501
+        try:
+            if isinstance(handler, AsyncHandler):
+                await handler.handle(event)
+            elif isinstance(handler, SyncHandler):
+                await asyncio.to_thread(handler.handle, event)
+            else:
+                raise TypeError(
+                    f"Handler {handler.__class__.__name__} is not a valid handler type."  # noqa: E501
+                )
+        except Exception as e:
+            raise HandlerExecutionError(
+                handler=handler,
+                event_name=event_name
+            ) from e
+
+    async def _process_message(self,
+                               queue_url: str,
+                               msg: dict,
+                               handler: BaseHandler) -> str:
+        """Process a single message from the SQS queue."""
+        event = EventJsonSerializerDeserializer.deserialize(
+            event_json=msg['Body'],
+            handler=handler
+        )
+        event_name = event.event_name
+
+        if self.deduplication and self.deduplication.is_duplicate(event.event_id):  # noqa: E501
+            logging.info(
+                f"Duplicate event detected: {event.event_id} for handler {handler.__class__.__name__}"  # noqa: E501
+            )
+            return
+        await self._execute_handler(handler, event, event_name)
+
+        if self.deduplication:
+            self.deduplication.mark_as_processed(event.event_id)
+
+        await asyncio.to_thread(
+            self.client.delete_message,
+            QueueUrl=queue_url,
+            ReceiptHandle=msg['ReceiptHandle']
+        )
+        return event_name

package_events_bus-0.1.0/events_bus/config.py

@@ -0,0 +1,36 @@
+import os
+from os import _Environ
+import dotenv
+
+
+class Config:
+    def __init__(self,
+                 envs: _Environ[str] = None,
+                 env_file: str = 'localhost.env',):
+        self.__envs = envs
+        self.__env_file = env_file
+        self.__load()
+
+    def set_envs(self, envs: _Environ[str], env_file: str = None):
+        """Set the environment variables."""
+        self.__envs = envs
+        if env_file is not None:
+            self.__env_file = env_file
+        self.__load()
+
+    def __load(self):
+        if self.__envs is None:
+            dotenv.load_dotenv(self.__env_file)
+            self.__envs = os.environ
+        self.MAX_NUMBER_OF_MESSAGES = int(
+            self.__envs.get('MAX_NUMBER_OF_MESSAGES', 5))
+        self.WAIT_TIME_SECONDS = int(
+            self.__envs.get('WAIT_TIME_SECONDS', 10))
+        self.VISIBILITY_TIMEOUT = int(
+            self.__envs.get('VISIBILITY_TIMEOUT', 30))
+        self.AWS_CLIENT_URL = self.__envs.get('AWS_CLIENT_URL', None)
+        self.AWS_REGION_NAME = self.__envs.get('AWS_REGION_NAME', 'us-east-1')
+        self.SLEEP_BETWEEN_MESSAGES_SECONDS = int(
+            self.__envs.get('SLEEP_BETWEEN_MESSAGES_SECONDS', 0.1))
+        self.ERROR_SLEEP_SECONDS = int(
+            self.__envs.get('ERROR_SLEEP_SECONDS', 5))

package_events_bus-0.1.0/events_bus/core/__init__.py

@@ -0,0 +1,19 @@
+from .contracts.base_event import BaseEvent
+from .contracts.deduplication import BaseDeduplication
+from .contracts.handler import (BaseHandler, SyncHandler, AsyncHandler)
+from .infrastructure.event_bus_publisher import EventBusPublisher
+from .infrastructure.event_serializer import EventJsonSerializerDeserializer
+from .runtime.event_register import EventHandlerRegistry
+
+
+__all__ = [
+    "BaseEvent",
+    "EventHandlerRegistry",
+    "EventBusPublisher",
+    "EventJsonSerializerDeserializer",
+    "EventRegistry",
+    "BaseHandler",
+    "SyncHandler",
+    "AsyncHandler",
+    "BaseDeduplication"
+]

package_events_bus-0.1.0/events_bus/core/contracts/base_event.py

@@ -0,0 +1,52 @@
+import uuid
+from datetime import (datetime, timezone)
+from abc import ABC, abstractmethod
+
+
+__TOPIC_REGEX = r'^[a-zA-Z0-9_]+\.[a-zA-Z0-9_]+\.\d+\.(command|event)\.[a-zA-Z0-9_]+\.[a-zA-Z0-9_]+$'  # noqa: E501
+
+
+class BaseEvent(ABC):
+    """
+    Base class for all events.
+
+    This class defines the interface for all events in the system.
+    It provides methods to convert events to and from dictionaries,
+    and to get the event type.
+
+    Attributes:
+        event_name (str): The fully qualified name of the event topic.
+            Must follow the format:
+                [company].[service].[version].[message_type].[resource_name].[event_command_name]
+            Where:
+                - company (str): Name of the company (e.g., 'finkargo').
+                - service (str): Name of the service emitting the event (e.g., 'portfolio', 'documents').
+                - version (int): Numeric version of the event (e.g., 1, 2).
+                - message_type (str): Either 'command' or 'event'.
+                - resource_name (str): The resource/entity the event is related to (e.g., 'disbursement').
+                - event_command_name (str):
+                    - If message_type is 'event': must be a verb in past tense (e.g., 'created', 'updated', 'deleted').
+                    - If message_type is 'command': must be a verb in infinitive form (e.g., 'create', 'send').
+        event_id (str): A unique identifier for the event.
+
+        occurred_on (datetime): The timestamp indicating when the event occurred.
+
+    """     # noqa: E501
+
+    def __init__(self,
+                 event_name: str,
+                 event_id: str | None = None,
+                 occurred_on: datetime | None = None):
+        self.event_name = event_name
+        self.event_id = uuid.uuid4().hex if event_id is None else event_id
+        self.occurred_on = datetime.now(
+            tz=timezone.utc) if occurred_on is None else occurred_on
+
+    @abstractmethod
+    def to_dict(self) -> dict:
+        pass
+
+    @classmethod
+    @abstractmethod
+    def from_dict(cls, event_id: str, occurred_on: datetime, attributes: dict) -> "BaseEvent":  # noqa: E501
+        pass

package_events_bus-0.1.0/events_bus/core/contracts/deduplication.py

@@ -0,0 +1,42 @@
+from abc import ABC
+
+
+class BaseDeduplication(ABC):
+    """
+    Abstract base class for deduplication strategies.
+    This class defines the interface for deduplication strategies.
+    Subclasses should implement the `is_duplicate` method to check for duplicates
+    and the `mark_as_processed` method to mark events as processed.
+    Attributes:
+        event_id (str): The unique identifier for the event.
+        This is used to identify events and check for duplicates.
+    """  # noqa: E501
+
+    def __init__(self):
+        """
+        Initialize the BaseDeduplication instance.
+        This method is called when an instance of a subclass is created.
+        It can be used to set up any necessary resources or configurations.
+        """
+        pass
+
+    def is_duplicate(self, event_id: str) -> bool:
+        """
+        Check if the given event ID is a duplicate.
+
+        Args:
+            event_id (str): The event ID to check for duplication.
+
+        Returns:
+            bool: True if the event ID is a duplicate, False otherwise.
+        """
+        pass
+
+    def mark_as_processed(self, event_id: str):
+        """
+        Mark the given event ID as processed.
+
+        Args:
+            event_id (str): The event ID to mark as processed.
+        """
+        pass

package_events_bus-0.1.0/events_bus/core/contracts/handler.py

@@ -0,0 +1,52 @@
+from abc import ABC, abstractmethod
+
+from .. import BaseEvent
+
+
+class BaseHandler(ABC):
+    """
+    Abstract base class for event handlers.
+    This class defines the interface for handling events.
+    Subclasses should implement the `handle` method to process the event.
+    Attributes:
+        event_type (type[BaseEvent]):
+        The type of event that this handler can process.
+    """
+    @abstractmethod
+    def handle(self, data: BaseEvent) -> None:
+        """Handle the event.
+        Args:
+            data (BaseEvent): The event data to handle.
+        """
+        pass
+
+
+class SyncHandler(BaseHandler):
+    """
+    Synchronous event handler.
+    This class implements the `handle` method to process events synchronously.
+    """
+
+    def handle(self, data: BaseEvent) -> None:
+        """Handle the event synchronously.
+        Args:
+            data (BaseEvent): The event data to handle.
+        """
+        pass
+
+
+class AsyncHandler(BaseHandler):
+    """
+    Asynchronous event handler.
+    This class implements the `handle` method to process events asynchronously.
+    """
+
+    async def handle(self, data: BaseEvent) -> None:
+        """Handle the event asynchronously.
+        Args:
+            data (BaseEvent): The event data to handle.
+        """
+        pass
+        # Implement asynchronous event handling logic here
+        # For example, you can process the event data and perform actions
+        # based on the event type and data.

package_events_bus-0.1.0/events_bus/core/infrastructure/event_bus_publisher.py

@@ -0,0 +1,30 @@
+from abc import ABC, abstractmethod
+
+from .. import BaseEvent
+
+
+class EventBusPublisher(ABC):
+    """Abstract base class for event bus publishers.
+    This class defines the interface for publishing events to an event bus.
+    Subclasses should implement the `publish` and `publish_batch` methods
+    to publish events to the appropriate event bus
+    (e.g., RabbitMQ, Kafka, EventBridge, etc.).
+    """
+
+    @abstractmethod
+    def publish(self, event: BaseEvent) -> None:
+        """Publish an event to the event bus.
+        This method should be implemented by subclasses to publish the event
+        to the appropriate event bus
+        (e.g., RabbitMQ, Kafka, EventBridge, etc.).
+        """
+        pass
+
+    @abstractmethod
+    def publish_batch(self, events: list[BaseEvent]) -> None:
+        """Publish a batch of events to the event bus.
+        This method should be implemented by subclasses to publish the events
+        to the appropriate event bus
+        (e.g., RabbitMQ, Kafka, EventBridge, etc.).
+        """
+        pass

package_events_bus-0.1.0/events_bus/core/infrastructure/event_serializer.py

@@ -0,0 +1,112 @@
+import json
+from datetime import datetime
+from typing import get_type_hints
+
+from .. import (BaseEvent, BaseHandler)
+from ...exceptions import DeserializationEventError
+
+
+class EventJsonSerializerDeserializer:
+    """A class for serializing and deserializing events to and from JSON
+    format. This class provides methods to convert event objects to JSON
+    strings and to create event objects from JSON strings.
+    """
+
+    @staticmethod
+    def serialize(event: type[BaseEvent]) -> str:
+        """Convert an event object to a JSON string.
+        Args:
+            event (BaseEvent): The event object to serialize.
+        Returns:
+            str: The JSON string representation of the event.
+        """
+        if not isinstance(event, BaseEvent):
+            raise TypeError(
+                f"Expected an instance of BaseEvent, got {type(event)}"
+            )
+        return json.dumps(
+            {
+                'data': {
+                    'id': event.event_id,
+                    'type': event.event_name,
+                    'occurred_on': event.occurred_on.isoformat(),
+                    'attributes': event.to_dict(),
+                }
+            },
+            default=str,
+        )
+
+    @staticmethod
+    def deserialize(event_json: str, handler: BaseHandler) -> BaseEvent:
+        """Convert a JSON string to an event object.
+        Args:
+            event_json (str): The JSON string to deserialize.
+            handler (BaseHandler): The handler to determine the event type.
+        Returns:
+            BaseEvent: The event object created from the JSON string.
+        """
+        if not isinstance(event_json, str):
+            raise TypeError(
+                f"Expected a JSON string, got {type(event_json)}"
+            )
+        try:
+            json_obj = json.loads(event_json)
+        except json.JSONDecodeError as e:
+            raise ValueError(
+                f"Invalid JSON format: {e.msg}"
+            ) from e
+        if 'detail' not in json_obj or 'data' not in json_obj['detail']:
+            raise ValueError(
+                "Invalid JSON format: 'detail' or 'data' key not found."
+            )
+        data = EventJsonSerializerDeserializer._validate_and_extract_data(json_obj)  # noqa: E501
+        attributes = data['attributes']
+        event_id = data['id']
+        occurred_on = datetime.fromisoformat(data['occurred_on'])
+        event_class = EventJsonSerializerDeserializer._get_event_type_from_handler(handler)  # noqa: E501
+        try:
+            return event_class.from_dict(
+                attributes=attributes,
+                event_id=event_id,
+                occurred_on=occurred_on,
+            )
+        except Exception as e:
+            raise DeserializationEventError(handler) from e
+
+    @staticmethod
+    def _get_event_type_from_handler(handler: BaseHandler) -> type[BaseEvent]:  # noqa: E501
+        """Get the event type from the handler."""
+        if not isinstance(handler, BaseHandler):
+            raise TypeError(
+                f"Expected an instance of BaseHandler, got {type(handler)}"
+            )
+        cls = handler.__class__
+
+        method = getattr(cls, 'handle', None)
+        if method is None:
+            raise ValueError(
+                f"Handler {cls.__name__} does not have a 'handle' method.")
+
+        type_hints = get_type_hints(method)
+        event = type_hints.get('data', None)
+        if not issubclass(event, BaseEvent):
+            raise ValueError(
+                f"Handler {cls.__name__} does not handle a valid BaseEvent type."  # noqa: E501
+            )
+        return event
+
+    @staticmethod
+    def _validate_and_extract_data(json_obj: dict) -> dict:
+        """Validate and extract data from the detail dictionary."""
+        if 'detail' not in json_obj or 'data' not in json_obj['detail']:
+            raise ValueError(
+                'Invalid JSON format: "detail" or "data" key not found.'  # noqa: E501
+            )
+        data = json_obj['detail']['data']
+        missing_keys = [key for key in ['attributes',
+                                        'id', 'occurred_on'] if key not in data]  # noqa: E501
+        if missing_keys:
+            raise ValueError(
+               'Invalid JSON format: Missing keys in "data": ' + ', '.join(missing_keys)  # noqa: E501
+            )
+        return data

package_events_bus-0.1.0/events_bus/core/infrastructure/redis_deduplication.py

@@ -0,0 +1,30 @@
+import redis
+from ..contracts.deduplication import BaseDeduplication
+
+
+class RedisDeduplication(BaseDeduplication):
+    """
+    Deduplication strategy using Redis.
+    This class implements the deduplication strategy using Redis as the backend.
+    It checks for duplicates and marks events as processed using Redis.
+    """  # noqa: E501
+
+    def __init__(self, url: str, ttl: int = 3600):
+        """
+        Initialize the RedisDeduplication instance.
+        Args:
+            url (str): The Redis server URL. This should be a valid Redis URL
+            in the format 'redis://[:password]@hostname:port/db_number'.
+            Review the Redis documentation for more details on the URL format.
+            ttl (int): Time to live for the event in seconds.
+            Default is 3600 seconds (1 hour).
+        """
+        super().__init__()
+        self.redis_client = redis.Redis.from_url(url)
+        self.ttl = ttl
+
+    def is_duplicate(self, event_id: str) -> bool:
+        return self.redis_client.exists(event_id) > 0
+
+    def mark_as_processed(self, event_id: str):
+        self.redis_client.set(event_id, "processed", ex=self.ttl)

package_events_bus-0.1.0/events_bus/core/runtime/event_register.py

@@ -0,0 +1,28 @@
+from .. import BaseHandler
+
+
+class EventHandlerRegistry:
+    """Registry for event handlers.
+    This class is responsible for registering event handlers and
+    providing access to them.
+    """
+    _registry: dict[str, BaseHandler] = {}
+
+    @classmethod
+    def register(cls, queue_url: str, handler: BaseHandler):
+        """Register an event handler with the registry.
+        Args:
+            queue_url (str): The URL of the queue to which the handler is
+            associated.
+            handler (BaseHandler): The event handler to register.
+        """
+        cls._registry[queue_url] = handler
+
+    @classmethod
+    def get_handlers(cls) -> dict[str, BaseHandler]:
+        """Get all registered event handlers.
+        Returns:
+            dict[str, BaseHandler]: A dictionary mapping queue URLs to
+            their associated event handlers.
+        """
+        return cls._registry

package_events_bus-0.1.0/events_bus/exceptions.py

@@ -0,0 +1,31 @@
+from .core.contracts.handler import BaseHandler
+
+
+class HandlerExecutionError(BaseException):
+    """
+    Exception raised when an event handler fails to execute.
+    """
+
+    def __init__(self, handler: BaseHandler, event_name: str):
+        super().__init__()
+        self.handler = handler
+        self.event_name = event_name
+
+    def __str__(self):
+        return (
+            f"Error processing event {self.event_name} with handler "
+            f"{self.handler.__class__.__name__}"
+        )
+
+
+class DeserializationEventError(BaseException):
+    """
+    Exception raised when an event cannot be deserialized.
+    """
+
+    def __init__(self, handler: BaseHandler):
+        super().__init__()
+        self.handler = handler
+
+    def __str__(self):
+        return f'Error deserializing event with handler {self.handler.__class__.__name__}'  # noqa: E501

package_events_bus-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[tool.poetry]
+name = "package-events-bus"
+version = "0.1.0"
+description = "Una librería para construir microservicios desacoplados en Python usando AWS EventBridge y SQS, donde cada caso de uso maneja su propia cola y se despacha automáticamente mediante handlers tipados."
+authors = ["Jose Luis Rosales Meza <jose.rosales@finkargo.com>"]
+license = "MIT"
+readme = "README.md"
+
+[[tool.poetry.packages]]
+include = "events_bus"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+boto3 = "^1.38.13"
+python-dotenv = "^1.1.0"
+redis = "^5.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"