hexkit 5.4.1__tar.gz → 6.0.0__tar.gz

{hexkit-5.4.1/src/hexkit.egg-info → hexkit-6.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexkit
-Version: 5.4.1
+Version: 6.0.0
 Summary: A Toolkit for Building Microservices using the Hexagonal Architecture
 Author-email: "German Human Genome Phenome Archive (GHGA)" <contact@ghga.de>
 License: Apache 2.0
@@ -30,7 +30,7 @@ Provides-Extra: s3
 Requires-Dist: boto3<2,>=1.37; extra == "s3"
 Requires-Dist: botocore<2,>=1.37; extra == "s3"
 Provides-Extra: mongodb
-Requires-Dist: motor<4,>=3.7; extra == "mongodb"
+Requires-Dist: pymongo<5,>=4.13; extra == "mongodb"
 Provides-Extra: opentelemetry-base
 Requires-Dist: opentelemetry-sdk<2,>=1.31.1; extra == "opentelemetry-base"
 Requires-Dist: opentelemetry-exporter-otlp<2,>=1.31.1; extra == "opentelemetry-base"
@@ -177,7 +177,7 @@ Additionally, the following convenience command is available inside the devconta
 (type it in the integrated terminal of VS Code):
 - `dev_install` - install the lib with all development dependencies and pre-commit hooks
 (please run that if you are starting the devcontainer for the first time
-or if added any python dependencies to the [`./setup.cfg`](./setup.cfg))
+or if added any python dependencies to the [`./pyproject.toml`](./pyproject.toml))
 
 If you prefer not to use vscode, you could get a similar setup (without the editor
 specific features) by running the following commands:

{hexkit-5.4.1 → hexkit-6.0.0}/README.md

@@ -103,7 +103,7 @@ Additionally, the following convenience command is available inside the devconta
 (type it in the integrated terminal of VS Code):
 - `dev_install` - install the lib with all development dependencies and pre-commit hooks
 (please run that if you are starting the devcontainer for the first time
-or if added any python dependencies to the [`./setup.cfg`](./setup.cfg))
+or if added any python dependencies to the [`./pyproject.toml`](./pyproject.toml))
 
 If you prefer not to use vscode, you could get a similar setup (without the editor
 specific features) by running the following commands:

{hexkit-5.4.1 → hexkit-6.0.0}/pyproject.toml

@@ -24,7 +24,7 @@ classifiers = [
     "Intended Audience :: Developers",
 ]
 name = "hexkit"
-version = "5.4.1"
+version = "6.0.0"
 description = "A Toolkit for Building Microservices using the Hexagonal Architecture"
 dependencies = [
     "opentelemetry-api >=1.31.1, <2",
@@ -46,7 +46,7 @@ s3 = [
     "botocore >=1.37, <2",
 ]
 mongodb = [
-    "motor >=3.7, <4",
+    "pymongo >=4.13, <5",
 ]
 opentelemetry-base = [
     "opentelemetry-sdk >=1.31.1, <2",

{hexkit-5.4.1 → hexkit-6.0.0}/src/hexkit/correlation.py

@@ -17,19 +17,24 @@
 """Utilities related to correlation IDs"""
 
 import logging
+from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 from contextvars import ContextVar
+from typing import Any
 from uuid import UUID, uuid4
 
+from pydantic import UUID4
+
 from hexkit.utils import set_context_var
 
 log = logging.getLogger(__name__)
 
-correlation_id_var: ContextVar[str] = ContextVar("correlation_id", default="")
+correlation_id_var: ContextVar[UUID4] = ContextVar("correlation_id")
 
 __all__ = [
     "CorrelationIdContextError",
     "InvalidCorrelationIdError",
+    "correlation_id_from_str",
     "get_correlation_id",
     "new_correlation_id",
     "set_correlation_id",
@@ -42,36 +47,46 @@ class CorrelationIdContextError(RuntimeError):
     """Raised when the correlation ID ContextVar is unexpectedly not set."""
 
     def __init__(self):
-        super().__init__("No correlation ID has been set.")
+        super().__init__("Correlation ID not set")
 
 
 class InvalidCorrelationIdError(RuntimeError):
     """Raised when a correlation ID fails validation."""
 
-    def __init__(self, *, correlation_id: str):
-        message = f"Invalid correlation ID found: '{correlation_id}'"
+    def __init__(self, *, correlation_id: Any):
+        message = f"Invalid correlation ID: {correlation_id!r}"
         super().__init__(message)
 
 
-def new_correlation_id() -> str:
+def new_correlation_id() -> UUID4:
     """Generates a new correlation ID."""
-    return str(uuid4())
+    return uuid4()
 
 
-def validate_correlation_id(correlation_id: str):
-    """Raises an error if the correlation ID is invalid.
+def validate_correlation_id(correlation_id: Any):
+    """Validate the correlation ID.
 
     Raises:
-        InvalidCorrelationIdError: If the correlation ID is empty or invalid.
+        InvalidCorrelationIdError: If the correlation ID is not a UUID.
+    """
+    if not isinstance(correlation_id, UUID):
+        raise InvalidCorrelationIdError(correlation_id=correlation_id)
+
+
+def correlation_id_from_str(correlation_id: str) -> UUID4:
+    """Convert a string to a UUID4.
+
+    Raises:
+        InvalidCorrelationIdError: If the string is not a valid UUID.
     """
     try:
-        UUID(correlation_id)
+        return UUID(correlation_id)
     except ValueError as err:
         raise InvalidCorrelationIdError(correlation_id=correlation_id) from err
 
 
 @asynccontextmanager
-async def set_correlation_id(correlation_id: str):
+async def set_correlation_id(correlation_id: UUID4):
     """Set the given correlation ID for the life of the context.
 
     Raises:
@@ -85,7 +100,7 @@ async def set_correlation_id(correlation_id: str):
 
 
 @asynccontextmanager
-async def set_new_correlation_id():
+async def set_new_correlation_id() -> AsyncGenerator[UUID4, None]:
     """Set a new correlation ID for the life of the context."""
     correlation_id = new_correlation_id()
 
@@ -94,17 +109,19 @@ async def set_new_correlation_id():
         yield correlation_id
 
 
-def get_correlation_id() -> str:
+def get_correlation_id() -> UUID4:
     """Get the correlation ID.
 
     This should only be called when the correlation ID ContextVar is expected to be set.
 
     Raises:
         CorrelationIdContextError: when the correlation ID ContextVar is not set.
-        InvalidCorrelationIdError: when the correlation ID is invalid.
+        InvalidCorrelationIdError: when the correlation ID is set but invalid.
     """
-    if not (correlation_id := correlation_id_var.get()):
-        raise CorrelationIdContextError()
+    try:
+        correlation_id = correlation_id_var.get()
+    except LookupError as err:
+        raise CorrelationIdContextError() from err
 
     validate_correlation_id(correlation_id)
 

{hexkit-5.4.1 → hexkit-6.0.0}/src/hexkit/log.py

@@ -24,9 +24,7 @@ from typing import Any, Literal, Optional
 from pydantic import Field
 from pydantic_settings import BaseSettings
 
-from hexkit.correlation import (
-    correlation_id_var,
-)
+from hexkit.correlation import correlation_id_var
 
 __all__ = [
     "JsonFormatter",

{hexkit-5.4.1 → hexkit-6.0.0}/src/hexkit/protocols/eventpub.py

@@ -19,6 +19,9 @@
 from abc import ABC, abstractmethod
 from collections.abc import Mapping
 from typing import Optional
+from uuid import UUID, uuid4
+
+from pydantic import UUID4
 
 from hexkit.custom_types import Ascii, JsonObject
 from hexkit.utils import check_ascii
@@ -27,13 +30,14 @@ from hexkit.utils import check_ascii
 class EventPublisherProtocol(ABC):
     """A protocol for publishing events to an event broker."""
 
-    async def publish(
+    async def publish(  # noqa: PLR0913
         self,
         *,
         payload: JsonObject,
         type_: Ascii,
         key: Ascii,
         topic: Ascii,
+        event_id: Optional[UUID4] = None,
         headers: Optional[Mapping[str, str]] = None,
     ) -> None:
         """Publish an event.
@@ -43,8 +47,16 @@ class EventPublisherProtocol(ABC):
         - `type_` (str): The event type. ASCII characters only.
         - `key` (str): The event type. ASCII characters only.
         - `topic` (str): The event type. ASCII characters only.
+        - `event_id` (UUID4, optional): An optional event ID. If not provided, a new
+          one will be generated.
         - `headers`: Additional headers to attach to the event.
         """
+        if event_id:
+            if not isinstance(event_id, UUID):
+                raise TypeError(f"event_id must be a UUID, got {type(event_id)}")
+        else:
+            event_id = uuid4()
+
         check_ascii(type_, key, topic)
         if headers is None:
             headers = {}
@@ -54,17 +66,19 @@ class EventPublisherProtocol(ABC):
             type_=type_,
             key=key,
             topic=topic,
+            event_id=event_id,
             headers=headers,
         )
 
     @abstractmethod
-    async def _publish_validated(
+    async def _publish_validated(  # noqa: PLR0913
         self,
         *,
         payload: JsonObject,
         type_: Ascii,
         key: Ascii,
         topic: Ascii,
+        event_id: UUID4,
         headers: Mapping[str, str],
     ) -> None:
         """Publish an event with already validated topic and type.
@@ -74,6 +88,7 @@ class EventPublisherProtocol(ABC):
         - `type_` (str): The event type. ASCII characters only.
         - `key` (str): The event type. ASCII characters only.
         - `topic` (str): The event type. ASCII characters only.
+        - `event_id` (UUID): The event ID.
         - `headers`: Additional headers to attach to the event.
         """
         ...

{hexkit-5.4.1 → hexkit-6.0.0}/src/hexkit/protocols/eventsub.py

@@ -20,6 +20,8 @@ from abc import ABC, abstractmethod
 from collections.abc import Mapping
 from datetime import datetime
 
+from pydantic import UUID4
+
 from hexkit.custom_types import Ascii, JsonObject
 from hexkit.utils import check_ascii
 
@@ -54,6 +56,7 @@ class EventSubscriberProtocol(ABC):
         type_: Ascii,
         topic: Ascii,
         key: Ascii,
+        event_id: UUID4,
     ) -> None:
         """Receive an event of interest and process it according to its type.
 
@@ -62,6 +65,7 @@ class EventSubscriberProtocol(ABC):
             type_: The type of the event.
             topic: Name of the topic the event was published to.
             key: A key used for routing the event.
+            event_id: The unique identifier of the event.
         """
         check_ascii(type_, topic)
 
@@ -69,7 +73,7 @@ class EventSubscriberProtocol(ABC):
             check_ascii(key)
 
         await self._consume_validated(
-            payload=payload, type_=type_, topic=topic, key=key
+            payload=payload, type_=type_, topic=topic, key=key, event_id=event_id
         )
 
     @abstractmethod
@@ -80,6 +84,7 @@ class EventSubscriberProtocol(ABC):
         type_: Ascii,
         topic: Ascii,
         key: Ascii,
+        event_id: UUID4,
     ) -> None:
         """
         Receive and process an event with already validated topic, type, and key.
@@ -89,6 +94,7 @@ class EventSubscriberProtocol(ABC):
             type_: The type of the event.
             topic: Name of the topic the event was published to.
             key: A key used for routing the event.
+            event_id: The unique identifier of the event.
         """
         ...
 
@@ -114,6 +120,7 @@ class DLQSubscriberProtocol(ABC):
         type_: Ascii,
         topic: Ascii,
         key: Ascii,
+        event_id: UUID4,
         timestamp: datetime,
         headers: Mapping[str, str],
     ) -> None:
@@ -124,6 +131,7 @@ class DLQSubscriberProtocol(ABC):
             type_: The type of the event.
             topic: Name of the topic the event was published to.
             key: A key used for routing the event.
+            event_id: The unique identifier of the event.
             timestamp: The timestamp assigned by either the publisher or the broker.
             headers: The event headers containing important metadata.
         """
@@ -137,6 +145,7 @@ class DLQSubscriberProtocol(ABC):
             type_=type_,
             topic=topic,
             key=key,
+            event_id=event_id,
             timestamp=timestamp,
             headers=headers,
         )
@@ -149,6 +158,7 @@ class DLQSubscriberProtocol(ABC):
         type_: Ascii,
         topic: Ascii,
         key: Ascii,
+        event_id: UUID4,
         timestamp: datetime,
         headers: Mapping[str, str],
     ) -> None:
@@ -160,6 +170,7 @@ class DLQSubscriberProtocol(ABC):
             type_: The type of the event.
             topic: Name of the topic the event was published to.
             key: A key used for routing the event.
+            event_id: The unique identifier of the event.
             timestamp: The timestamp assigned by either the publisher or the broker.
             headers: The event headers containing important metadata.
         """

{hexkit-5.4.1 → hexkit-6.0.0}/src/hexkit/providers/akafka/config.py

@@ -74,8 +74,8 @@ class KafkaConfig(BaseSettings):
         examples=[True, False],
         description=(
             "A flag, which, if False, will result in an error when trying to publish an"
-            + " event without a valid correlation ID set for the context. If True, the a"
-            + " newly correlation ID will be generated and used in the event header."
+            + " event without a valid correlation ID set for the context. If True, a"
+            + " new correlation ID will be generated and used in the event header."
         ),
     )
     kafka_max_message_size: PositiveInt = Field(

{hexkit-5.4.1 → hexkit-6.0.0}/src/hexkit/providers/akafka/provider/eventpub.py

@@ -30,12 +30,12 @@ from typing import Any, Callable, Optional, Protocol
 from uuid import UUID
 
 from aiokafka import AIOKafkaProducer
+from pydantic import UUID4
 
 from hexkit.correlation import (
     CorrelationIdContextError,
     get_correlation_id,
     new_correlation_id,
-    validate_correlation_id,
 )
 from hexkit.custom_types import Ascii, JsonObject, KafkaCompressionType
 from hexkit.protocols.eventpub import EventPublisherProtocol
@@ -45,7 +45,7 @@ from hexkit.providers.akafka.provider.utils import (
     generate_ssl_context,
 )
 
-RESERVED_HEADERS = ["type", "correlation_id"]
+RESERVED_HEADERS = ["type", "correlation_id", "event_id"]
 
 
 class KafkaProducerCompatible(Protocol):
@@ -171,13 +171,14 @@ class KafkaEventPublisher(EventPublisherProtocol):
             return value.isoformat()
         raise TypeError(f"Object of type {type(value)} is not JSON serializable")
 
-    async def _publish_validated(
+    async def _publish_validated(  # noqa: PLR0913
         self,
         *,
         payload: JsonObject,
         type_: Ascii,
         key: Ascii,
         topic: Ascii,
+        event_id: UUID4,
         headers: Mapping[str, str],
     ) -> None:
         """Publish an event with already validated topic and type.
@@ -187,6 +188,7 @@ class KafkaEventPublisher(EventPublisherProtocol):
         - `type_` (str): The event type. ASCII characters only.
         - `key` (str): The event key. ASCII characters only.
         - `topic` (str): The event topic. ASCII characters only.
+        - `event_id` (UUID): The event ID.
         - `headers`: Additional headers to attach to the event.
         """
         try:
@@ -196,25 +198,37 @@ class KafkaEventPublisher(EventPublisherProtocol):
                 raise
 
             correlation_id = new_correlation_id()
-            logging.info("Generated new correlation ID: %s", correlation_id)
-
-        validate_correlation_id(correlation_id)
+            logging.info("Generated new correlation ID: %s.", correlation_id)
 
         # Create a shallow copy of the headers
-        headers_copy = dict(headers)
+        headers_copy = dict(headers)  # used for validation and logging only
 
-        # Check and log warnings for reserved headers
-        for header in RESERVED_HEADERS:
-            log_msg = (
-                f"The '{header}' header shouldn't be supplied, but was. Overwriting."
-            )
-            if header in headers_copy:
-                logging.warning(log_msg, extra={header: headers_copy[header]})
+        overrides = {
+            header: headers_copy[header]
+            for header in RESERVED_HEADERS
+            if header in headers_copy
+        }
 
         headers_copy["type"] = type_
-        headers_copy["correlation_id"] = correlation_id
+        headers_copy["event_id"] = str(event_id)
+        headers_copy["correlation_id"] = str(correlation_id)
         encoded_headers_list = [(k, v.encode("ascii")) for k, v in headers_copy.items()]
 
+        # Log warnings for any reserved headers that were overridden
+        for header, old_value in overrides.items():
+            log_msg = (
+                f"The '{header}' header shouldn't be supplied, but was."
+                f" Overwriting old value ({old_value}) with {headers_copy[header]}."
+            )
+            logging.warning(log_msg, extra={header: old_value})
+
         await self._producer.send_and_wait(
             topic, key=key, value=payload, headers=encoded_headers_list
         )
+        logging.info(
+            "Published event: topic=%s, type=%s, key=%s, event_id=%s.",
+            topic,
+            type_,
+            key,
+            event_id,
+        )