hexkit 8.1.0__tar.gz → 8.2.0__tar.gz

{hexkit-8.1.0/src/hexkit.egg-info → hexkit-8.2.0}/PKG-INFO

@@ -1,10 +1,13 @@
 Metadata-Version: 2.4
 Name: hexkit
-Version: 8.1.0
+Version: 8.2.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
 Project-URL: Repository, https://github.com/ghga-de/hexkit
+Project-URL: Documentation, https://ghga-de.github.io/hexkit/
+Project-URL: Release Notes, https://github.com/ghga-de/hexkit/releases
+Project-URL: Issue Tracker, https://github.com/ghga-de/hexkit/issues
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3.10
@@ -23,7 +26,7 @@ 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.13.0; extra == "akafka"
+Requires-Dist: aiokafka[lz4,snappy,zstd]~=0.14.0; extra == "akafka"
 Requires-Dist: jsonschema<5,>=4.25; extra == "akafka"
 Provides-Extra: s3
 Requires-Dist: boto3<2,>=1.42; extra == "s3"
@@ -32,6 +35,8 @@ Provides-Extra: mongodb
 Requires-Dist: pymongo<5,>=4.16; extra == "mongodb"
 Provides-Extra: redis
 Requires-Dist: redis<8,>=7.1; extra == "redis"
+Provides-Extra: vault
+Requires-Dist: hvac<3,>=2.4; extra == "vault"
 Provides-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"
@@ -74,8 +79,11 @@ Requires-Dist: testcontainers[mongo]<5,>=4.14; extra == "test-mongodb"
 Provides-Extra: test-redis
 Requires-Dist: hexkit[redis]; extra == "test-redis"
 Requires-Dist: testcontainers[redis]<5,>=4.14; extra == "test-redis"
+Provides-Extra: test-vault
+Requires-Dist: hexkit[vault]; extra == "test-vault"
+Requires-Dist: testcontainers<5,>=4.14; extra == "test-vault"
 Provides-Extra: test
-Requires-Dist: hexkit[test-akafka,test-mongodb,test-s3]; extra == "test"
+Requires-Dist: hexkit[test-akafka,test-mongodb,test-s3,test-vault]; extra == "test"
 Provides-Extra: all
 Requires-Dist: hexkit[test]; extra == "all"
 Requires-Dist: hexkit[opentelemetry]; extra == "all"

{hexkit-8.1.0 → hexkit-8.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [build-system]
 requires = [
-    "setuptools>=80.10",
+    "setuptools>=82",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -23,7 +23,7 @@ classifiers = [
     "Intended Audience :: Developers",
 ]
 name = "hexkit"
-version = "8.1.0"
+version = "8.2.0"
 description = "A Toolkit for Building Microservices using the Hexagonal Architecture"
 dependencies = [
     "opentelemetry-api >=1.39, <2",
@@ -37,7 +37,7 @@ text = "Apache 2.0"
 
 [project.optional-dependencies]
 akafka = [
-    "aiokafka[zstd,lz4,snappy]~=0.13.0",
+    "aiokafka[zstd,lz4,snappy]~=0.14.0",
     "jsonschema >=4.25, <5",
 ]
 s3 = [
@@ -50,6 +50,9 @@ mongodb = [
 redis = [
     "redis >=7.1, <8",
 ]
+vault = [
+    "hvac >=2.4, <3",
+]
 opentelemetry-base = [
     "opentelemetry-sdk >=1.39.1, <2",
     "opentelemetry-exporter-otlp >=1.39.1, <2",
@@ -103,8 +106,12 @@ test-redis = [
     "hexkit[redis]",
     "testcontainers[redis] >=4.14, <5",
 ]
+test-vault = [
+    "hexkit[vault]",
+    "testcontainers >=4.14, <5",
+]
 test = [
-    "hexkit[test-akafka,test-s3,test-mongodb]",
+    "hexkit[test-akafka,test-s3,test-mongodb,test-vault]",
 ]
 all = [
     "hexkit[test]",
@@ -113,6 +120,9 @@ all = [
 
 [project.urls]
 Repository = "https://github.com/ghga-de/hexkit"
+Documentation = "https://ghga-de.github.io/hexkit/"
+"Release Notes" = "https://github.com/ghga-de/hexkit/releases"
+"Issue Tracker" = "https://github.com/ghga-de/hexkit/issues"
 
 [tool.setuptools.packages.find]
 where = [
@@ -235,7 +245,7 @@ source = [
 [tool.tox]
 legacy_tox_ini = """
     [tox]
-    env_list = py3{10,11,12,13}
+    env_list = py3{10,11,12,13}, docs
 
     [gh-actions]
     python =
@@ -244,6 +254,22 @@ legacy_tox_ini = """
         3.12: py312
         3.13: py313
 
+    [testenv:docs]
+    basepython = python3.13
+    allowlist_externals =
+        mv
+        rm
+    deps =
+        --no-deps -r ./lock/requirements-dev.txt
+    commands =
+        rm -rf site/api
+        pdoc -d google -o docs/api hexkit
+        mv docs/api/index.html docs/api/index.md
+        mkdocs build
+        mv docs/api/index.md docs/api/index.html
+        rm -rf site/api
+        mv docs/api site/api
+
     [testenv]
     pass_env =
         TC_HOST

{hexkit-8.1.0 → hexkit-8.2.0}/src/hexkit/config.py

@@ -112,18 +112,16 @@ def config_from_yaml(
     """
 
     def decorator(settings) -> Callable:
-        # settings should be a pydantic BaseSetting,
-        # there is no type hint here to not restrict
-        # autocompletion for attributes of the
-        # modified settings class returned by the
-        # contructor_wrapper
         """The actual decorator function.
 
         Args
             settings (BaseSettings):
                 A pydantic BaseSettings class to be modified.
         """
-        # check if settings inherits from pydantic BaseSettings:
+        # The settings argument should be a pydantic BaseSetting,
+        # there is no type hint here to not restrict autocompletion for attributes
+        # of the modified settings class returned by the constructor_wrapper.
+        # Check if settings inherits from pydantic BaseSettings:
         if not issubclass(settings, BaseSettings):
             raise TypeError(
                 "The specified settings class is not a subclass of pydantic_settings.BaseSettings"
@@ -152,6 +150,7 @@ def config_from_yaml(
                     frozen=True,
                     env_prefix=f"{prefix}_",
                     env_file=(".env", dotenv_prefix / ".env"),
+                    env_nested_delimiter="__",
                 )
 
                 @classmethod

{hexkit-8.1.0 → hexkit-8.2.0}/src/hexkit/protocols/objstorage.py

@@ -195,6 +195,38 @@ class ObjectStorageProtocol(ABC):
             bucket_id=bucket_id, object_id=object_id
         )
 
+    async def list_parts(
+        self,
+        *,
+        bucket_id: str,
+        object_id: str,
+        upload_id: str,
+        max_parts: int | None = None,
+        first_part_no: int | None = None,
+    ) -> list[dict]:
+        """Lists the parts that have been uploaded for a specific multipart upload.
+
+        Specify `max_parts` to return a limited parts list. If not specified, all
+        parts will be returned (up to 10,000).
+
+        Specify `first_part_no` to get parts starting with that part number. If not
+        specified, retrieved parts will start with the first part. Part numbers
+        start at 1, not 0.
+
+        Raises:
+            ValueError if `max_parts` or `first_part_no` are invalid.
+            MultiPartUploadNotFoundError if no upload with `upload_id` exists.
+        """
+        self._validate_bucket_id(bucket_id)
+        self._validate_object_id(object_id)
+        return await self._list_parts(
+            bucket_id=bucket_id,
+            object_id=object_id,
+            upload_id=upload_id,
+            max_parts=max_parts,
+            first_part_no=first_part_no,
+        )
+
     async def get_all_multipart_uploads(self, *, bucket_id: str) -> dict[str, str]:
         """Gets all active multipart uploads for the given bucket ID.
 
@@ -440,6 +472,31 @@ class ObjectStorageProtocol(ABC):
         """
         ...
 
+    @abstractmethod
+    async def _list_parts(
+        self,
+        *,
+        bucket_id: str,
+        object_id: str,
+        upload_id: str,
+        max_parts: int | None = None,
+        first_part_no: int | None = None,
+    ) -> list[dict]:
+        """Lists the parts that have been uploaded for a specific multipart upload.
+
+        Specify `max_parts` to return a limited parts list. If not specified, all
+        parts will be returned (up to 10,000).
+
+        Specify `first_part_no` to get parts starting with that part number. If not
+        specified, retrieved parts will start with the first part. Part numbers
+        start at 1, not 0.
+
+        Raises:
+            ValueError if `max_parts` or `first_part_no` are invalid.
+            MultiPartUploadNotFoundError if no upload with `upload_id` exists.
+        """
+        ...
+
     @abstractmethod
     async def _get_all_multipart_uploads(self, *, bucket_id: str) -> dict[str, str]:
         """Gets all active multipart uploads for the given bucket ID.

{hexkit-8.1.0 → hexkit-8.2.0}/src/hexkit/providers/akafka/provider/daosub.py

@@ -19,7 +19,7 @@
 """
 
 import logging
-from collections.abc import Sequence
+from collections.abc import AsyncGenerator, Sequence
 from contextlib import asynccontextmanager
 
 from aiokafka import AIOKafkaConsumer
@@ -57,7 +57,7 @@ class KafkaOutboxSubscriber(InboundProviderBase):
         translators: Sequence[DaoSubscriberProtocol],
         dlq_publisher: EventPublisherProtocol | None = None,
         kafka_consumer_cls: type[KafkaConsumerCompatible] = AIOKafkaConsumer,
-    ):
+    ) -> AsyncGenerator["KafkaOutboxSubscriber", None]:
         """Setup and teardown an instance of the provider.
 
         Args:

{hexkit-8.1.0 → hexkit-8.2.0}/src/hexkit/providers/akafka/provider/eventsub.py

@@ -331,9 +331,11 @@ class KafkaConsumerCompatible(Protocol):
                 An identifier for the consumer group.
             auto_offset_reset:
                 Can be set to "earliest".
-            key_serializer:
+            enable_auto_commit:
+                Whether to enable auto-committing of offsets.
+            key_deserializer:
                 Function to deserialize the keys into strings.
-            value_serializer:
+            value_deserializer:
                 Function to deserialize the values into strings.
             max_partition_fetch_bytes:
                 Maximum receivable message size

{hexkit-8.1.0 → hexkit-8.2.0}/src/hexkit/providers/akafka/testutils.py

@@ -644,11 +644,11 @@ class KafkaContainerFixture(KafkaContainer):
         """Run the given command in the kafka testcontainer.
 
         Args:
-            - `command`: The full command to run.
-            - `run_in_shell`: If True, will run the command in a shell.
+            command: The full command to run.
+            run_in_shell: If True, will run the command in a shell.
 
         Raises:
-            - `RuntimeError`: when the exit code returned by the command is not zero.
+            RuntimeError: when the exit code returned by the command is not zero.
         """
         cmd = ["sh", "-c", command] if run_in_shell else command
         exit_code, output = self.get_wrapped_container().exec_run(cmd)

{hexkit-8.1.0 → hexkit-8.2.0}/src/hexkit/providers/mongodb/migrations/helpers.py

@@ -13,7 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Prefab functions to help with migrations caused by changes in Hexkit."""
+"""Prefab functions to help with migrations caused by changes in hexkit."""
 
 from collections.abc import Awaitable, Callable
 from datetime import datetime, timezone
@@ -34,7 +34,7 @@ def convert_uuids_and_datetimes_v6(
     uuid_fields: list[str] | None = None,
     date_fields: list[str] | None = None,
 ) -> Callable[[Document], Awaitable[Document]]:
-    """Produce a function to convert a document to the format expected by Hexkit v6.
+    """Produce a function to convert a document to the format expected by hexkit v6.
 
     If `uuid_fields` is provided, it will convert those fields from string to UUID.
     If `date_fields` is provided, it will convert those fields from isoformat strings
@@ -60,7 +60,7 @@ def convert_uuids_and_datetimes_v6(
 
 
 async def convert_outbox_correlation_id_v6(doc: Document) -> Document:
-    """Convert an outbox document's correlation ID to the format expected by Hexkit v6.
+    """Convert an outbox document's correlation ID to the format expected by hexkit v6.
 
     This will only convert the __metadata__.correlation_id to a UUID.
 
@@ -77,7 +77,7 @@ _convert_persistent_event_existing_fields_v6 = convert_uuids_and_datetimes_v6(
 
 
 async def convert_persistent_event_v6(doc: Document) -> Document:
-    """Convert a persistent event document to the format expected by Hexkit v6.
+    """Convert a persistent event document to the format expected by hexkit v6.
 
     This will:
     - convert correlation_id to UUID

{hexkit-8.1.0 → hexkit-8.2.0}/src/hexkit/providers/mongodb/provider/dao.py

@@ -16,7 +16,7 @@
 
 """MongoDB-based provider implementing the DaoFactoryProtocol.
 
-Utilities for testing are located in `./testutils.py`.
+Utilities for testing are located in `../testutils.py`.
 """
 
 from collections.abc import AsyncIterator, Callable, Collection, Mapping

{hexkit-8.1.0 → hexkit-8.2.0}/src/hexkit/providers/mongodb/provider/kvstore.py

@@ -83,9 +83,13 @@ class MongoDbBaseKeyValueStore(ABC, KeyValueStoreProtocol):
             client: An instance of an async MongoDB client.
             config: MongoDB-specific config parameters.
             collection_name: Name of the collection to hold the key-value pairs.
-            **kwargs: Additional arguments specific to subclasses.
+
+        You might be able to pass additional arguments specific to subclasses.
         """
-        args = [str(config)]
+        config_args = ", ".join(
+            f"{k}={v!r}" for k, v in config.model_dump(exclude_defaults=True).items()
+        )
+        args = [f"config=MongoDbConfig({config_args})"]
         if collection_name != DEFAULT_KV_COLLECTION_NAME:
             args.append(f"collection_name={collection_name!r}")
         for key, val in kwargs.items():

{hexkit-8.1.0 → hexkit-8.2.0}/src/hexkit/providers/mongodb/provider/utils.py

@@ -15,7 +15,7 @@
 
 """MongoDB-based provider utilities.
 
-Utilities for testing are located in `./testutils.py`.
+Utilities for testing are located in `../testutils.py`.
 """
 
 from contextlib import contextmanager

{hexkit-8.1.0 → hexkit-8.2.0}/src/hexkit/providers/mongokafka/__init__.py

@@ -21,6 +21,7 @@ from .provider import (
     CHANGE_EVENT_TYPE,
     DELETE_EVENT_TYPE,
     MongoKafkaDaoPublisherFactory,
+    PersistentKafkaEvent,
     PersistentKafkaPublisher,
     document_to_dto,
     dto_to_document,
@@ -31,6 +32,7 @@ __all__ = [
     "DELETE_EVENT_TYPE",
     "MongoKafkaConfig",
     "MongoKafkaDaoPublisherFactory",
+    "PersistentKafkaEvent",
     "PersistentKafkaPublisher",
     "document_to_dto",
     "dto_to_document",

{hexkit-8.1.0 → hexkit-8.2.0}/src/hexkit/providers/mongokafka/provider/daopub.py

@@ -19,7 +19,14 @@
 Requires dependencies of the `akafka` and `mongodb` extras.
 """
 
-from collections.abc import AsyncIterator, Awaitable, Callable, Collection, Mapping
+from collections.abc import (
+    AsyncGenerator,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Collection,
+    Mapping,
+)
 from contextlib import AbstractAsyncContextManager, asynccontextmanager, contextmanager
 from functools import partial
 from typing import Any, Generic
@@ -476,7 +483,7 @@ class MongoKafkaDaoPublisherFactory(DaoPublisherFactoryProtocol[MongoDbIndex]):
         *,
         config: MongoKafkaConfig,
         kafka_producer_cls: type[KafkaProducerCompatible] = AIOKafkaProducer,
-    ):
+    ) -> AsyncGenerator["MongoKafkaDaoPublisherFactory", None]:
         """Setup and teardown an instance of the provider.
         This method will automatically close the DB connection upon exit.
 

{hexkit-8.1.0 → hexkit-8.2.0}/src/hexkit/providers/redis/provider/kvstore.py

@@ -68,7 +68,8 @@ class RedisBaseKeyValueStore(ABC, KeyValueStoreProtocol):
         Args:
             config: Redis-specific config parameters.
             key_prefix: Optional prefix for all keys (e.g., "myapp:users:").
-            **kwargs: Additional arguments specific to subclasses.
+
+        You might be able to pass additional arguments specific to subclasses.
         """
         async with ConfiguredRedisClient(config) as client:
             yield cls(
@@ -92,9 +93,13 @@ class RedisBaseKeyValueStore(ABC, KeyValueStoreProtocol):
             client: An instance of an async Redis client.
             config: Redis-specific config parameters.
             key_prefix: Prefix for all keys to enable logical separation.
-            **kwargs: Additional arguments specific to subclasses.
+
+        You might be able to pass additional arguments specific to subclasses.
         """
-        args = [str(config)]
+        config_args = ", ".join(
+            f"{k}={v!r}" for k, v in config.model_dump(exclude_defaults=True).items()
+        )
+        args = [f"config=RedisConfig({config_args})"]
         if key_prefix != DEFAULT_KV_PREFIX:
             args.append(f"key_prefix={key_prefix!r}")
         for key, val in kwargs.items():

hexkit-8.2.0/src/hexkit/providers/s3/__init__.py

@@ -0,0 +1,36 @@
+# Copyright 2021 - 2026 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 an S3-based providers and associated utilities."""
+
+# shortcuts:
+from hexkit.providers.s3.config import S3Config
+from hexkit.providers.s3.provider import (
+    S3BytesKeyValueStore,
+    S3DtoKeyValueStore,
+    S3JsonKeyValueStore,
+    S3ObjectStorage,
+    S3StrKeyValueStore,
+)
+
+__all__ = [
+    "S3BytesKeyValueStore",
+    "S3Config",
+    "S3DtoKeyValueStore",
+    "S3JsonKeyValueStore",
+    "S3ObjectStorage",
+    "S3StrKeyValueStore",
+]

hexkit-8.2.0/src/hexkit/providers/s3/config.py

@@ -0,0 +1,68 @@
+# Copyright 2021 - 2026 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.
+
+"""S3-specific configuration."""
+
+from pathlib import Path
+
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings
+
+__all__ = ["S3Config"]
+
+
+class S3Config(BaseSettings):
+    """S3-specific config params.
+
+    Inherit your config class from this class if you need to talk
+    to an S3 service in the backend.
+    """
+
+    s3_endpoint_url: str = Field(
+        ..., examples=["http://localhost:4566"], description="URL to the S3 API."
+    )
+    s3_access_key_id: str = Field(
+        ...,
+        examples=["my-access-key-id"],
+        description=(
+            "Part of credentials for login into the S3 service. See:"
+            + " https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html"
+        ),
+    )
+    s3_secret_access_key: SecretStr = Field(
+        ...,
+        examples=["my-secret-access-key"],
+        description=(
+            "Part of credentials for login into the S3 service. See:"
+            + " https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html"
+        ),
+    )
+    s3_session_token: SecretStr | None = Field(
+        None,
+        examples=["my-session-token"],
+        description=(
+            "Part of credentials for login into the S3 service. See:"
+            + " https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html"
+        ),
+    )
+    aws_config_ini: Path | None = Field(
+        None,
+        examples=["~/.aws/config"],
+        description=(
+            "Path to a config file for specifying more advanced S3 parameters."
+            + " This should follow the format described here:"
+            + " https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#using-a-configuration-file"
+        ),
+    )

{hexkit-8.1.0/src/hexkit/providers/s3 → hexkit-8.2.0/src/hexkit/providers/s3/provider}/__init__.py

@@ -14,11 +14,23 @@
 # limitations under the License.
 #
 
-"""Subpackage containing an S3-based provider implementing the ObjectStorageProtocol
-and associated utilities.
+"""Subpackage containing S3-based providers implementing the ObjectStorageProtocol
+and KeyValueStoreProtocol, and associated utilities.
 """
 
 # shortcuts:
-from hexkit.providers.s3.provider import S3Config, S3ObjectStorage
+from .kvstore import (
+    S3BytesKeyValueStore,
+    S3DtoKeyValueStore,
+    S3JsonKeyValueStore,
+    S3StrKeyValueStore,
+)
+from .objstorage import S3ObjectStorage
 
-__all__ = ["S3Config", "S3ObjectStorage"]
+__all__ = [
+    "S3BytesKeyValueStore",
+    "S3DtoKeyValueStore",
+    "S3JsonKeyValueStore",
+    "S3ObjectStorage",
+    "S3StrKeyValueStore",
+]