hexkit 2.2.0__tar.gz → 3.0.1__tar.gz

{hexkit-2.2.0 → hexkit-3.0.1}/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+   Copyright 2021 - 2024 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");

{hexkit-2.2.0 → hexkit-3.0.1}/MANIFEST.in

@@ -1 +1,2 @@
+include src/hexkit/py.typed
 include src/hexkit/providers/s3/test_files/*.yaml

{hexkit-2.2.0/src/hexkit.egg-info → hexkit-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hexkit
-Version: 2.2.0
+Version: 3.0.1
 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
@@ -10,6 +10,7 @@ Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
 Classifier: Topic :: Software Development :: Libraries
@@ -21,8 +22,8 @@ Requires-Dist: pydantic<3,>=2
 Requires-Dist: pydantic_settings<3,>=2
 Requires-Dist: PyYAML<7,>=6.0
 Provides-Extra: akafka
-Requires-Dist: aiokafka~=0.8.0; extra == "akafka"
-Requires-Dist: jsonschema<5,>=4.17.3; extra == "akafka"
+Requires-Dist: aiokafka~=0.10.0; extra == "akafka"
+Requires-Dist: jsonschema<5,>=4.21; extra == "akafka"
 Provides-Extra: s3
 Requires-Dist: boto3<2,>=1.26.50; extra == "s3"
 Requires-Dist: botocore<2,>=1.29.50; extra == "s3"

{hexkit-2.2.0 → hexkit-3.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [build-system]
 requires = [
-    "setuptools>=67.7.2",
+    "setuptools>=69",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -16,13 +16,14 @@ classifiers = [
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
     "License :: OSI Approved :: Apache Software License",
     "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
     "Topic :: Software Development :: Libraries",
     "Intended Audience :: Developers",
 ]
 name = "hexkit"
-version = "2.2.0"
+version = "3.0.1"
 description = "A Toolkit for Building Microservices using the Hexagonal Architecture"
 dependencies = [
     "pydantic >=2, <3",
@@ -35,8 +36,8 @@ text = "Apache 2.0"
 
 [project.optional-dependencies]
 akafka = [
-    "aiokafka~=0.8.0",
-    "jsonschema >=4.17.3, <5",
+    "aiokafka~=0.10.0",
+    "jsonschema >=4.21, <5",
 ]
 s3 = [
     "boto3 >=1.26.50, <2",
@@ -96,8 +97,9 @@ fixable = [
     "D",
 ]
 ignore = [
-    "E",
-    "W",
+    "E111",
+    "E114",
+    "E116",
     "PLW",
     "RUF001",
     "RUF010",
@@ -111,6 +113,7 @@ ignore = [
     "D107",
     "D206",
     "D300",
+    "UP040",
 ]
 select = [
     "C90",
@@ -170,7 +173,7 @@ check_untyped_defs = true
 no_site_packages = false
 
 [tool.pytest.ini_options]
-minversion = "7.1"
+minversion = "8.0"
 asyncio_mode = "strict"
 
 [tool.coverage.paths]
@@ -181,4 +184,22 @@ source = [
 ]
 
 [tool.tox]
-legacy_tox_ini = "    [tox]\n    min_version = 4.0\n    env_list =\n        py39\n        py311\n\n    [testenv]\n    pass_env=\n        TC_HOST\n        DOCKER_HOST\n    deps =\n        --no-deps -r ./lock/requirements-dev.txt\n    commands = pytest ./tests {posargs}\n"
+legacy_tox_ini = """
+    [tox]
+    env_list = py3{9,12}
+
+    [gh-actions]
+    python =
+        3.9: py39
+        3.10: py310
+        3.11: py311
+        3.12: py312
+
+    [testenv]
+    pass_env =
+        TC_HOST
+        DOCKER_HOST
+    deps =
+        --no-deps -r ./lock/requirements-dev.txt
+    commands = pytest {posargs}
+"""

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/__main__.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/base.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/config.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/correlation.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/custom_types.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/log.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/protocols/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/protocols/dao.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");

hexkit-2.2.0/src/hexkit/protocols/dao_outbox.py → hexkit-3.0.1/src/hexkit/protocols/daopub.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");
@@ -34,7 +34,7 @@ from hexkit.protocols.dao import (
 )
 
 
-class DaoOutbox(DaoNaturalId[Dto], typing.Protocol[Dto]):
+class DaoPublisher(DaoNaturalId[Dto], typing.Protocol[Dto]):
     """A Data Access Object (DAO) that automatically publishes changes according to the
     outbox pattern.
     """
@@ -50,7 +50,7 @@ class DaoOutbox(DaoNaturalId[Dto], typing.Protocol[Dto]):
         ...
 
 
-class DaoOutboxFactoryProtocol(DaoFactoryBase, ABC):
+class DaoPublisherFactoryProtocol(DaoFactoryBase, ABC):
     """A protocol describing a factory to produce Data Access Objects (DAO) objects
     which automatically publish changes according to the outbox pattern.
     """
@@ -65,7 +65,7 @@ class DaoOutboxFactoryProtocol(DaoFactoryBase, ABC):
         dto_to_event: Callable[[Dto], JsonObject],
         event_topic: str,
         autopublish: bool = True,
-    ) -> DaoOutbox[Dto]:
+    ) -> DaoPublisher[Dto]:
         """Constructs an Outbox DAO for interacting with resources in a database.
 
         Args:
@@ -88,7 +88,7 @@ class DaoOutboxFactoryProtocol(DaoFactoryBase, ABC):
                 Whether to automatically publish changes. Defaults to True.
 
         Returns:
-            A DAO of type DaoOutbox, which requires ID specification upon resource
+            A DAO of type DaoPublisher, which requires ID specification upon resource
             creation.
 
         Raises:
@@ -123,7 +123,7 @@ class DaoOutboxFactoryProtocol(DaoFactoryBase, ABC):
         dto_to_event: Callable[[Dto], JsonObject],
         event_topic: str,
         autopublish: bool,
-    ) -> DaoOutbox[Dto]:
+    ) -> DaoPublisher[Dto]:
         """*To be implemented by the provider. Input validation is done outside of this
         method.*
         """

hexkit-3.0.1/src/hexkit/protocols/daosub.py

@@ -0,0 +1,60 @@
+# Copyright 2021 - 2024 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 protocol for consuming events published through the DaoPublisherFactoryProtocol."""
+
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+Dto = TypeVar("Dto", bound=BaseModel)
+
+
+class DtoValidationError(ValueError):
+    """Raised when the payload of a received event was not formatted as expected."""
+
+
+class DaoSubscriberProtocol(ABC, Generic[Dto]):
+    """A protocol for consuming events published through the DaoPublisherFactoryProtocol.
+
+    In addition to the methods described below, implementations shall expose the
+    the following attributes:
+            event_topic:
+                The name of the topic from which updates for the given resource are
+                consumed.
+            dto_model:
+                A pydantic model representing the data transfer object (DTO) for the
+                payload of changed events.
+
+    If the upstream provider using this protocol fails to convert the payload of a
+    change event to the expected DTO model, it should raise a DtoValidationError.
+    """
+
+    event_topic: str
+    dto_model: type[Dto]
+
+    @abstractmethod
+    async def changed(self, resource_id: str, update: Dto) -> None:
+        """Consume a change event (created or updated) for the resource with the given
+        ID.
+        """
+        ...
+
+    @abstractmethod
+    async def deleted(self, resource_id: str) -> None:
+        """Consume an event indicating the deletion of the resource with the given ID."""
+        ...

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/protocols/eventpub.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/protocols/eventsub.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");
@@ -45,27 +45,47 @@ class EventSubscriberProtocol(ABC):
     topics_of_interest: list[Ascii]
     types_of_interest: list[Ascii]
 
-    async def consume(self, *, payload: JsonObject, type_: Ascii, topic: Ascii) -> None:
+    async def consume(
+        self,
+        *,
+        payload: JsonObject,
+        type_: Ascii,
+        topic: Ascii,
+        key: Ascii,
+    ) -> None:
         """Receive an event of interest and process it according to its type.
 
         Args:
-            payload (JsonObject): The data/payload to send with the event.
-            type_ (str): The type of the event.
-            topic (str): Name of the topic the event was published to.
+            payload: The data/payload to send with the event.
+            type_: The type of the event.
+            topic: Name of the topic the event was published to.
+            key: A key used for routing the event.
         """
         check_ascii(type_, topic)
-        await self._consume_validated(payload=payload, type_=type_, topic=topic)
+
+        if key:
+            check_ascii(key)
+
+        await self._consume_validated(
+            payload=payload, type_=type_, topic=topic, key=key
+        )
 
     @abstractmethod
     async def _consume_validated(
-        self, *, payload: JsonObject, type_: Ascii, topic: Ascii
+        self,
+        *,
+        payload: JsonObject,
+        type_: Ascii,
+        topic: Ascii,
+        key: Ascii,
     ) -> None:
         """
-        Receive and process an event with already validated topic and type.
+        Receive and process an event with already validated topic, type, and key.
 
         Args:
-            payload (JsonObject): The data/payload to send with the event.
-            type_ (str): The type of the event.
-            topic (str): Name of the topic the event was published to.
+            payload: The data/payload to send with the event.
+            type_: The type of the event.
+            topic: Name of the topic the event was published to.
+            key: A key used for routing the event.
         """
         ...

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/protocols/objstorage.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/providers/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");

{hexkit-2.2.0 → hexkit-3.0.1}/src/hexkit/providers/akafka/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2021 - 2023 Universität Tübingen, DKFZ, EMBL, and Universität zu Köln
+# Copyright 2021 - 2024 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");
@@ -19,10 +19,16 @@ They correspond to the `EventPublisherProtocol` and `EventSubscriberProtocol`,
 respectively.
 """
 
+from .config import KafkaConfig
 from .provider import (
-    KafkaConfig,
     KafkaEventPublisher,
     KafkaEventSubscriber,
+    KafkaOutboxSubscriber,
 )
 
-__all__ = ["KafkaEventPublisher", "KafkaEventSubscriber", "KafkaConfig"]
+__all__ = [
+    "KafkaEventPublisher",
+    "KafkaEventSubscriber",
+    "KafkaConfig",
+    "KafkaOutboxSubscriber",
+]

hexkit-3.0.1/src/hexkit/providers/akafka/config.py

@@ -0,0 +1,78 @@
+# Copyright 2021 - 2024 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.
+#
+
+"""Apache Kafka specific configuration."""
+
+from typing import Literal
+
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings
+
+
+class KafkaConfig(BaseSettings):
+    """Config parameters needed for connecting to Apache Kafka."""
+
+    service_name: str = Field(
+        ...,
+        examples=["my-cool-special-service"],
+        description="The name of the (micro-)service from which messages are published.",
+    )
+    service_instance_id: str = Field(
+        ...,
+        examples=["germany-bw-instance-001"],
+        description=(
+            "A string that uniquely identifies this instance across all instances of"
+            + " this service. A globally unique Kafka client ID will be created by"
+            + " concatenating the service_name and the service_instance_id."
+        ),
+    )
+    kafka_servers: list[str] = Field(
+        ...,
+        examples=[["localhost:9092"]],
+        description="A list of connection strings to connect to Kafka bootstrap servers.",
+    )
+    kafka_security_protocol: Literal["PLAINTEXT", "SSL"] = Field(
+        default="PLAINTEXT",
+        description="Protocol used to communicate with brokers. "
+        + "Valid values are: PLAINTEXT, SSL.",
+    )
+    kafka_ssl_cafile: str = Field(
+        default="",
+        description="Certificate Authority file path containing certificates"
+        + " used to sign broker certificates. If a CA is not specified, the default"
+        + " system CA will be used if found by OpenSSL.",
+    )
+    kafka_ssl_certfile: str = Field(
+        default="",
+        description="Optional filename of client certificate, as well as any"
+        + " CA certificates needed to establish the certificate's authenticity.",
+    )
+    kafka_ssl_keyfile: str = Field(
+        default="", description="Optional filename containing the client private key."
+    )
+    kafka_ssl_password: SecretStr = Field(
+        default="",
+        description="Optional password to be used for the client private key.",
+    )
+    generate_correlation_id: bool = Field(
+        default=True,
+        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."
+        ),
+    )

hexkit-3.0.1/src/hexkit/providers/akafka/provider/__init__.py

@@ -0,0 +1,38 @@
+# Copyright 2021 - 2024 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 Apache Kafka-specific providers.
+
+Require dependencies of the `akafka` extra.
+"""
+
+from .daosub import KafkaOutboxSubscriber
+from .eventpub import KafkaEventPublisher
+from .eventsub import (
+    ConsumerEvent,
+    KafkaEventSubscriber,
+    get_header_value,
+    headers_as_dict,
+)
+
+__all__ = [
+    "KafkaEventPublisher",
+    "KafkaEventSubscriber",
+    "ConsumerEvent",
+    "get_header_value",
+    "headers_as_dict",
+    "KafkaOutboxSubscriber",
+]