hexkit 7.2.0__tar.gz → 7.3.0__tar.gz

{hexkit-7.2.0/src/hexkit.egg-info → hexkit-7.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexkit
-Version: 7.2.0
+Version: 7.3.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
@@ -18,39 +18,45 @@ Classifier: Intended Audience :: Developers
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: opentelemetry-api<2,>=1.37
-Requires-Dist: pydantic<3,>=2.11
-Requires-Dist: pydantic_settings<3,>=2.10
+Requires-Dist: opentelemetry-api<2,>=1.39
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: pydantic_settings<3,>=2.12
 Requires-Dist: PyYAML<7,>=6
 Provides-Extra: akafka
-Requires-Dist: aiokafka[lz4,snappy,zstd]~=0.12.0; extra == "akafka"
+Requires-Dist: aiokafka[lz4,snappy,zstd]~=0.13.0; extra == "akafka"
 Requires-Dist: jsonschema<5,>=4.25; extra == "akafka"
 Provides-Extra: s3
-Requires-Dist: boto3<2,>=1.40; extra == "s3"
-Requires-Dist: botocore<2,>=1.40; extra == "s3"
+Requires-Dist: boto3<2,>=1.42; extra == "s3"
+Requires-Dist: botocore<2,>=1.42; extra == "s3"
 Provides-Extra: mongodb
 Requires-Dist: pymongo<5,>=4.15; extra == "mongodb"
+Provides-Extra: redis
+Requires-Dist: redis<8,>=7.1; extra == "redis"
 Provides-Extra: opentelemetry-base
-Requires-Dist: opentelemetry-sdk<2,>=1.37.0; extra == "opentelemetry-base"
-Requires-Dist: opentelemetry-exporter-otlp<2,>=1.37.0; extra == "opentelemetry-base"
-Requires-Dist: opentelemetry-instrumentation>=0.58b0; extra == "opentelemetry-base"
-Requires-Dist: opentelemetry-instrumentation-httpx>=0.58b0; extra == "opentelemetry-base"
-Requires-Dist: opentelemetry-distro>=0.58b0; extra == "opentelemetry-base"
+Requires-Dist: opentelemetry-sdk<2,>=1.39.1; extra == "opentelemetry-base"
+Requires-Dist: opentelemetry-exporter-otlp<2,>=1.39.1; extra == "opentelemetry-base"
+Requires-Dist: opentelemetry-instrumentation>=0.60b1; extra == "opentelemetry-base"
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.60b1; extra == "opentelemetry-base"
+Requires-Dist: opentelemetry-distro>=0.60b1; extra == "opentelemetry-base"
 Provides-Extra: opentelemetry-akafka
 Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-akafka"
 Requires-Dist: hexkit[akafka]; extra == "opentelemetry-akafka"
-Requires-Dist: opentelemetry-instrumentation-aiokafka>=0.58b0; extra == "opentelemetry-akafka"
+Requires-Dist: opentelemetry-instrumentation-aiokafka>=0.60b1; extra == "opentelemetry-akafka"
 Provides-Extra: opentelemetry-mongodb
 Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-mongodb"
 Requires-Dist: hexkit[mongodb]; extra == "opentelemetry-mongodb"
-Requires-Dist: opentelemetry-instrumentation-pymongo>=0.58b0; extra == "opentelemetry-mongodb"
+Requires-Dist: opentelemetry-instrumentation-pymongo>=0.60b1; extra == "opentelemetry-mongodb"
 Provides-Extra: opentelemetry-fastapi
 Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-fastapi"
-Requires-Dist: opentelemetry-instrumentation-fastapi>=0.58b0; extra == "opentelemetry-fastapi"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.60b1; extra == "opentelemetry-fastapi"
 Provides-Extra: opentelemetry-s3
 Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-s3"
 Requires-Dist: hexkit[s3]; extra == "opentelemetry-s3"
-Requires-Dist: opentelemetry-instrumentation-botocore>=0.58b0; extra == "opentelemetry-s3"
+Requires-Dist: opentelemetry-instrumentation-botocore>=0.60b1; extra == "opentelemetry-s3"
+Provides-Extra: opentelemetry-redis
+Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-redis"
+Requires-Dist: hexkit[redis]; extra == "opentelemetry-redis"
+Requires-Dist: opentelemetry-instrumentation-redis>=0.60b1; extra == "opentelemetry-redis"
 Provides-Extra: opentelemetry
 Requires-Dist: hexkit[opentelemetry-akafka]; extra == "opentelemetry"
 Requires-Dist: hexkit[opentelemetry-mongodb]; extra == "opentelemetry"
@@ -65,6 +71,9 @@ Requires-Dist: testcontainers<5,>=4.13; extra == "test-s3"
 Provides-Extra: test-mongodb
 Requires-Dist: hexkit[mongodb]; extra == "test-mongodb"
 Requires-Dist: testcontainers[mongo]<5,>=4.13; extra == "test-mongodb"
+Provides-Extra: test-redis
+Requires-Dist: hexkit[redis]; extra == "test-redis"
+Requires-Dist: testcontainers[redis]<5,>=4.13; extra == "test-redis"
 Provides-Extra: test
 Requires-Dist: hexkit[test-akafka,test-mongodb,test-s3]; extra == "test"
 Provides-Extra: all

{hexkit-7.2.0 → hexkit-7.3.0}/pyproject.toml

@@ -23,12 +23,12 @@ classifiers = [
     "Intended Audience :: Developers",
 ]
 name = "hexkit"
-version = "7.2.0"
+version = "7.3.0"
 description = "A Toolkit for Building Microservices using the Hexagonal Architecture"
 dependencies = [
-    "opentelemetry-api >=1.37, <2",
-    "pydantic >=2.11, <3",
-    "pydantic_settings >=2.10, <3",
+    "opentelemetry-api >=1.39, <2",
+    "pydantic >=2.12, <3",
+    "pydantic_settings >=2.12, <3",
     "PyYAML >=6, <7",
 ]
 
@@ -37,41 +37,49 @@ text = "Apache 2.0"
 
 [project.optional-dependencies]
 akafka = [
-    "aiokafka[zstd,lz4,snappy]~=0.12.0",
+    "aiokafka[zstd,lz4,snappy]~=0.13.0",
     "jsonschema >=4.25, <5",
 ]
 s3 = [
-    "boto3 >=1.40, <2",
-    "botocore >=1.40, <2",
+    "boto3 >=1.42, <2",
+    "botocore >=1.42, <2",
 ]
 mongodb = [
     "pymongo >=4.15, <5",
 ]
+redis = [
+    "redis >=7.1, <8",
+]
 opentelemetry-base = [
-    "opentelemetry-sdk >=1.37.0, <2",
-    "opentelemetry-exporter-otlp >=1.37.0, <2",
-    "opentelemetry-instrumentation >=0.58b0",
-    "opentelemetry-instrumentation-httpx >=0.58b0",
-    "opentelemetry-distro >=0.58b0",
+    "opentelemetry-sdk >=1.39.1, <2",
+    "opentelemetry-exporter-otlp >=1.39.1, <2",
+    "opentelemetry-instrumentation >=0.60b1",
+    "opentelemetry-instrumentation-httpx >=0.60b1",
+    "opentelemetry-distro >=0.60b1",
 ]
 opentelemetry-akafka = [
     "hexkit[opentelemetry-base]",
     "hexkit[akafka]",
-    "opentelemetry-instrumentation-aiokafka >=0.58b0",
+    "opentelemetry-instrumentation-aiokafka >=0.60b1",
 ]
 opentelemetry-mongodb = [
     "hexkit[opentelemetry-base]",
     "hexkit[mongodb]",
-    "opentelemetry-instrumentation-pymongo >=0.58b0",
+    "opentelemetry-instrumentation-pymongo >=0.60b1",
 ]
 opentelemetry-fastapi = [
     "hexkit[opentelemetry-base]",
-    "opentelemetry-instrumentation-fastapi >=0.58b0",
+    "opentelemetry-instrumentation-fastapi >=0.60b1",
 ]
 opentelemetry-s3 = [
     "hexkit[opentelemetry-base]",
     "hexkit[s3]",
-    "opentelemetry-instrumentation-botocore >=0.58b0",
+    "opentelemetry-instrumentation-botocore >=0.60b1",
+]
+opentelemetry-redis = [
+    "hexkit[opentelemetry-base]",
+    "hexkit[redis]",
+    "opentelemetry-instrumentation-redis >=0.60b1",
 ]
 opentelemetry = [
     "hexkit[opentelemetry-akafka]",
@@ -91,6 +99,10 @@ test-mongodb = [
     "hexkit[mongodb]",
     "testcontainers[mongo] >=4.13, <5",
 ]
+test-redis = [
+    "hexkit[redis]",
+    "testcontainers[redis] >=4.13, <5",
+]
 test = [
     "hexkit[test-akafka,test-s3,test-mongodb]",
 ]

{hexkit-7.2.0 → hexkit-7.3.0}/src/hexkit/correlation.py

@@ -63,13 +63,13 @@ def new_correlation_id() -> UUID4:
     return uuid4()
 
 
-def validate_correlation_id(correlation_id: Any):
+def validate_correlation_id(correlation_id: Any) -> None:
     """Validate the correlation ID.
 
     Raises:
-        InvalidCorrelationIdError: If the correlation ID is not a UUID.
+        InvalidCorrelationIdError: If the correlation ID is not a UUID4.
     """
-    if not isinstance(correlation_id, UUID):
+    if not isinstance(correlation_id, UUID) or correlation_id.version != 4:
         raise InvalidCorrelationIdError(correlation_id=correlation_id)
 
 
@@ -77,13 +77,18 @@ 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.
+        InvalidCorrelationIdError: If the string is not a valid UUID4.
     """
     try:
-        return UUID(correlation_id)
+        converted_id = UUID(correlation_id)
     except ValueError as err:
         raise InvalidCorrelationIdError(correlation_id=correlation_id) from err
 
+    if converted_id.version != 4:
+        raise InvalidCorrelationIdError(correlation_id=correlation_id)
+
+    return converted_id
+
 
 @asynccontextmanager
 async def set_correlation_id(correlation_id: UUID4):

hexkit-7.3.0/src/hexkit/protocols/kvstore.py

@@ -0,0 +1,55 @@
+# Copyright 2021 - 2025 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# for the German Human Genome-Phenome Archive (GHGA)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""Protocol supporting key-value store operations."""
+
+from typing import Generic, Protocol, TypeVar
+
+V = TypeVar("V")
+
+
+class KeyValueStoreProtocol(Protocol, Generic[V]):
+    """A protocol for a key-value store."""
+
+    async def get(self, key: str, default: V | None = None) -> V | None:
+        """Retrieve the value for the given key.
+
+        Returns the specified default value if there is no such value in the store.
+        """
+        pass
+
+    async def set(self, key: str, value: V) -> None:
+        """Set the value for the given key.
+
+        Providers must reject storing a value of None if they
+        support a value domain V that can contain such values.
+        """
+        pass
+
+    async def delete(self, key: str) -> None:
+        """Delete the value for the given key.
+
+        Does nothing if there is no such value in the store.
+        """
+        pass
+
+    async def exists(self, key: str) -> bool:
+        """Check if the given key exists.
+
+        Default implementation for classes inheriting from this protocol.
+        Providers can use something more efficient.
+        """
+        return (await self.get(key)) is not None

hexkit-7.3.0/src/hexkit/providers/mongodb/__init__.py

@@ -0,0 +1,41 @@
+# Copyright 2021 - 2025 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# for the German Human Genome-Phenome Archive (GHGA)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""Subpackage containing MongoDB-based providers and related utilities."""
+
+from .config import MongoDbConfig
+from .provider import (
+    ConfiguredMongoClient,
+    MongoDbBytesKeyValueStore,
+    MongoDbDao,
+    MongoDbDaoFactory,
+    MongoDbDtoKeyValueStore,
+    MongoDbJsonKeyValueStore,
+    MongoDbStrKeyValueStore,
+    translate_pymongo_errors,
+)
+
+__all__ = [
+    "ConfiguredMongoClient",
+    "MongoDbBytesKeyValueStore",
+    "MongoDbConfig",
+    "MongoDbDao",
+    "MongoDbDaoFactory",
+    "MongoDbDtoKeyValueStore",
+    "MongoDbJsonKeyValueStore",
+    "MongoDbStrKeyValueStore",
+    "translate_pymongo_errors",
+]

hexkit-7.3.0/src/hexkit/providers/mongodb/config.py

@@ -0,0 +1,55 @@
+# Copyright 2021 - 2025 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# for the German Human Genome-Phenome Archive (GHGA)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""MongoDB specific configuration."""
+
+from pydantic import Field, MongoDsn, PositiveInt, Secret
+from pydantic_settings import BaseSettings
+
+__all__ = ["MongoDbConfig"]
+
+
+class MongoDbConfig(BaseSettings):
+    """Configuration parameters for connecting to a MongoDB server.
+
+    Inherit your config class from this class if your application uses MongoDB.
+    """
+
+    mongo_dsn: Secret[MongoDsn] = Field(
+        ...,
+        examples=["mongodb://localhost:27017"],
+        description=(
+            "MongoDB connection string. Might include credentials."
+            + " For more information see:"
+            + " https://naiveskill.com/mongodb-connection-string/"
+        ),
+    )
+    db_name: str = Field(
+        ...,
+        examples=["my-database"],
+        description="Name of the database located on the MongoDB server.",
+    )
+    mongo_timeout: PositiveInt | None = Field(
+        default=None,
+        examples=[300, 600, None],
+        description=(
+            "Timeout in seconds for API calls to MongoDB. The timeout applies to all steps"
+            + " needed to complete the operation, including server selection, connection"
+            + " checkout, serialization, and server-side execution. When the timeout"
+            + " expires, PyMongo raises a timeout exception. If set to None, the"
+            + " operation will not time out (default MongoDB behavior)."
+        ),
+    )

{hexkit-7.2.0 → hexkit-7.3.0}/src/hexkit/providers/mongodb/migrations/_manager.py

@@ -27,7 +27,7 @@ from pymongo import AsyncMongoClient
 from pymongo.asynchronous.database import AsyncDatabase
 from pymongo.errors import DuplicateKeyError
 
-from hexkit.providers.mongodb import MongoDbConfig
+from hexkit.providers.mongodb.config import MongoDbConfig
 from hexkit.providers.mongodb.provider import ConfiguredMongoClient
 
 from ._utils import MigrationDefinition, Reversible

hexkit-7.3.0/src/hexkit/providers/mongodb/provider/__init__.py

@@ -0,0 +1,52 @@
+# Copyright 2021 - 2025 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# for the German Human Genome-Phenome Archive (GHGA)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""A subpackage containing all MongoDB-specific providers.
+
+Require dependencies of the `mongodb` extra.
+"""
+
+from .client import ConfiguredMongoClient
+from .dao import (
+    MongoDbDao,
+    MongoDbDaoFactory,
+    get_single_hit,
+    replace_id_field_in_find_mapping,
+    validate_find_mapping,
+)
+from .kvstore import (
+    MongoDbBytesKeyValueStore,
+    MongoDbDtoKeyValueStore,
+    MongoDbJsonKeyValueStore,
+    MongoDbStrKeyValueStore,
+)
+from .utils import document_to_dto, dto_to_document, translate_pymongo_errors
+
+__all__ = [
+    "ConfiguredMongoClient",
+    "MongoDbBytesKeyValueStore",
+    "MongoDbDao",
+    "MongoDbDaoFactory",
+    "MongoDbDtoKeyValueStore",
+    "MongoDbJsonKeyValueStore",
+    "MongoDbStrKeyValueStore",
+    "document_to_dto",
+    "dto_to_document",
+    "get_single_hit",
+    "replace_id_field_in_find_mapping",
+    "translate_pymongo_errors",
+    "validate_find_mapping",
+]

hexkit-7.3.0/src/hexkit/providers/mongodb/provider/client.py

@@ -0,0 +1,102 @@
+# Copyright 2021 - 2025 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# for the German Human Genome-Phenome Archive (GHGA)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Client used for the MongoDB providers."""
+
+from typing import TypeVar
+
+from pymongo import AsyncMongoClient, MongoClient
+
+from hexkit.providers.mongodb.config import MongoDbConfig
+
+ClientType = TypeVar("ClientType", AsyncMongoClient, MongoClient)
+
+__all__ = ["ConfiguredMongoClient"]
+
+
+class ConfiguredMongoClient:
+    """A context manager for a configured MongoDB client, sync or async.
+
+    Usage:
+        ```python
+        from hexkit.providers.mongodb import MongoDbConfig, ConfiguredMongoClient
+
+        with ConfiguredMongoClient(config=MongoDbConfig(...)) as client:
+            # Use the client here
+            pass
+
+        async with ConfiguredMongoClient(config=MongoDbConfig(...)) as client:
+            # Use the async client here
+            pass
+
+        # Client is automatically closed after exiting the context manager
+    """
+
+    config: MongoDbConfig
+
+    def __init__(self, *, config: MongoDbConfig):
+        self._config = config
+
+    async def __aenter__(self) -> AsyncMongoClient:
+        """Enter a context manager and return the _asynchronous_ MongoDB client."""
+        self._async_client = self.get_client(
+            config=self._config, client_cls=AsyncMongoClient
+        )
+        return self._async_client
+
+    async def __aexit__(self, exc_type_, exc_value, exc_tb):
+        """Close the async MongoDB client."""
+        await self._async_client.close()
+
+    def __enter__(self) -> MongoClient:
+        """Enter a context manager and return the _synchronous_ MongoDB client."""
+        self._client = self.get_client(config=self._config, client_cls=MongoClient)
+        return self._client
+
+    def __exit__(self, exc_type_, exc_value, exc_tb):
+        """Close the synchronous MongoDB client."""
+        self._client.close()
+
+    @classmethod
+    def get_client(
+        cls,
+        *,
+        config: MongoDbConfig,
+        client_cls: type[ClientType],
+    ) -> ClientType:
+        """Creates a configured MongoDB client based on the provided configuration,
+        with the timeout, uuid representation, and timezone awareness set.
+
+        *Does not* automatically close the client!
+
+        Args:
+            config: MongoDB-specific configuration parameters.
+            client_cls: The class of the MongoDB client to instantiate.
+
+        Returns:
+            A MongoDB client instance configured with the provided parameters.
+        """
+        timeout_ms = (
+            int(config.mongo_timeout * 1000)
+            if config.mongo_timeout is not None
+            else None
+        )
+
+        return client_cls(
+            str(config.mongo_dsn.get_secret_value()),
+            timeoutMS=timeout_ms,
+            uuidRepresentation="standard",
+            tz_aware=True,
+        )