hexkit 6.0.0__tar.gz → 7.1.0__tar.gz

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

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: hexkit
-Version: 6.0.0
+Version: 7.1.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
 Classifier: Development Status :: 5 - Production/Stable
 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
@@ -16,41 +15,42 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Intended Audience :: Developers
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: opentelemetry-api<2,>=1.31.1
-Requires-Dist: pydantic<3,>=2.10
-Requires-Dist: pydantic_settings<3,>=2.8
+Requires-Dist: opentelemetry-api<2,>=1.37
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: pydantic_settings<3,>=2.10
 Requires-Dist: PyYAML<7,>=6
 Provides-Extra: akafka
 Requires-Dist: aiokafka[lz4,snappy,zstd]~=0.12.0; extra == "akafka"
-Requires-Dist: jsonschema<5,>=4.23; extra == "akafka"
+Requires-Dist: jsonschema<5,>=4.25; extra == "akafka"
 Provides-Extra: s3
-Requires-Dist: boto3<2,>=1.37; extra == "s3"
-Requires-Dist: botocore<2,>=1.37; extra == "s3"
+Requires-Dist: boto3<2,>=1.40; extra == "s3"
+Requires-Dist: botocore<2,>=1.40; extra == "s3"
 Provides-Extra: mongodb
-Requires-Dist: pymongo<5,>=4.13; extra == "mongodb"
+Requires-Dist: pymongo<5,>=4.15; 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"
-Requires-Dist: opentelemetry-instrumentation>=0.52b1; extra == "opentelemetry-base"
-Requires-Dist: opentelemetry-instrumentation-httpx>=0.52b1; 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"
 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.52b1; extra == "opentelemetry-akafka"
+Requires-Dist: opentelemetry-instrumentation-aiokafka>=0.58b0; 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.52b1; extra == "opentelemetry-mongodb"
+Requires-Dist: opentelemetry-instrumentation-pymongo>=0.58b0; extra == "opentelemetry-mongodb"
 Provides-Extra: opentelemetry-fastapi
 Requires-Dist: hexkit[opentelemetry-base]; extra == "opentelemetry-fastapi"
-Requires-Dist: opentelemetry-instrumentation-fastapi>=0.52b1; extra == "opentelemetry-fastapi"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.58b0; 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.52b1; extra == "opentelemetry-s3"
+Requires-Dist: opentelemetry-instrumentation-botocore>=0.58b0; extra == "opentelemetry-s3"
 Provides-Extra: opentelemetry
 Requires-Dist: hexkit[opentelemetry-akafka]; extra == "opentelemetry"
 Requires-Dist: hexkit[opentelemetry-mongodb]; extra == "opentelemetry"
@@ -58,13 +58,13 @@ Requires-Dist: hexkit[opentelemetry-fastapi]; extra == "opentelemetry"
 Requires-Dist: hexkit[opentelemetry-s3]; extra == "opentelemetry"
 Provides-Extra: test-akafka
 Requires-Dist: hexkit[akafka]; extra == "test-akafka"
-Requires-Dist: testcontainers[kafka]<5,>=4.9; extra == "test-akafka"
+Requires-Dist: testcontainers[kafka]<5,>=4.13; extra == "test-akafka"
 Provides-Extra: test-s3
 Requires-Dist: hexkit[s3]; extra == "test-s3"
-Requires-Dist: testcontainers<5,>=4.9; extra == "test-s3"
+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.9; extra == "test-mongodb"
+Requires-Dist: testcontainers[mongo]<5,>=4.13; extra == "test-mongodb"
 Provides-Extra: test
 Requires-Dist: hexkit[test-akafka,test-mongodb,test-s3]; extra == "test"
 Provides-Extra: all

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

@@ -1,6 +1,6 @@
 [build-system]
 requires = [
-    "setuptools>=80.3",
+    "setuptools>=80.9",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -9,11 +9,10 @@ readme = "README.md"
 authors = [
     { name = "German Human Genome Phenome Archive (GHGA)", email = "contact@ghga.de" },
 ]
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Operating System :: POSIX :: Linux",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -24,12 +23,12 @@ classifiers = [
     "Intended Audience :: Developers",
 ]
 name = "hexkit"
-version = "6.0.0"
+version = "7.1.0"
 description = "A Toolkit for Building Microservices using the Hexagonal Architecture"
 dependencies = [
-    "opentelemetry-api >=1.31.1, <2",
-    "pydantic >=2.10, <3",
-    "pydantic_settings >=2.8, <3",
+    "opentelemetry-api >=1.37, <2",
+    "pydantic >=2.11, <3",
+    "pydantic_settings >=2.10, <3",
     "PyYAML >=6, <7",
 ]
 
@@ -39,39 +38,40 @@ text = "Apache 2.0"
 [project.optional-dependencies]
 akafka = [
     "aiokafka[zstd,lz4,snappy]~=0.12.0",
-    "jsonschema >=4.23, <5",
+    "jsonschema >=4.25, <5",
 ]
 s3 = [
-    "boto3 >=1.37, <2",
-    "botocore >=1.37, <2",
+    "boto3 >=1.40, <2",
+    "botocore >=1.40, <2",
 ]
 mongodb = [
-    "pymongo >=4.13, <5",
+    "pymongo >=4.15, <5",
 ]
 opentelemetry-base = [
-    "opentelemetry-sdk >=1.31.1, <2",
-    "opentelemetry-exporter-otlp >=1.31.1, <2",
-    "opentelemetry-instrumentation >=0.52b1",
-    "opentelemetry-instrumentation-httpx >=0.52b1",
+    "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-akafka = [
     "hexkit[opentelemetry-base]",
     "hexkit[akafka]",
-    "opentelemetry-instrumentation-aiokafka >=0.52b1",
+    "opentelemetry-instrumentation-aiokafka >=0.58b0",
 ]
 opentelemetry-mongodb = [
     "hexkit[opentelemetry-base]",
     "hexkit[mongodb]",
-    "opentelemetry-instrumentation-pymongo >=0.52b1",
+    "opentelemetry-instrumentation-pymongo >=0.58b0",
 ]
 opentelemetry-fastapi = [
     "hexkit[opentelemetry-base]",
-    "opentelemetry-instrumentation-fastapi >=0.52b1",
+    "opentelemetry-instrumentation-fastapi >=0.58b0",
 ]
 opentelemetry-s3 = [
     "hexkit[opentelemetry-base]",
     "hexkit[s3]",
-    "opentelemetry-instrumentation-botocore >=0.52b1",
+    "opentelemetry-instrumentation-botocore >=0.58b0",
 ]
 opentelemetry = [
     "hexkit[opentelemetry-akafka]",
@@ -81,15 +81,15 @@ opentelemetry = [
 ]
 test-akafka = [
     "hexkit[akafka]",
-    "testcontainers[kafka] >=4.9, <5",
+    "testcontainers[kafka] >=4.13, <5",
 ]
 test-s3 = [
     "hexkit[s3]",
-    "testcontainers >=4.9, <5",
+    "testcontainers >=4.13, <5",
 ]
 test-mongodb = [
     "hexkit[mongodb]",
-    "testcontainers[mongo] >=4.9, <5",
+    "testcontainers[mongo] >=4.13, <5",
 ]
 test = [
     "hexkit[test-akafka,test-s3,test-mongodb]",
@@ -102,9 +102,6 @@ all = [
 [project.urls]
 Repository = "https://github.com/ghga-de/hexkit"
 
-[project.entry-points.opentelemetry_distro]
-hexkit_distro = "hexkit.opentelemetry:HexkitDistro"
-
 [tool.setuptools.packages.find]
 where = [
     "src",
@@ -125,7 +122,7 @@ src = [
     "examples",
     "scripts",
 ]
-target-version = "py39"
+target-version = "py310"
 
 [tool.ruff.lint]
 fixable = [
@@ -212,7 +209,7 @@ check_untyped_defs = true
 no_site_packages = false
 
 [tool.pytest.ini_options]
-minversion = "8.3"
+minversion = "8.4"
 asyncio_mode = "strict"
 asyncio_default_fixture_loop_scope = "function"
 
@@ -226,11 +223,10 @@ source = [
 [tool.tox]
 legacy_tox_ini = """
     [tox]
-    env_list = py3{9,12,13}
+    env_list = py3{10,11,12,13}
 
     [gh-actions]
     python =
-        3.9: py39
         3.10: py310
         3.11: py311
         3.12: py312
@@ -242,5 +238,7 @@ legacy_tox_ini = """
         DOCKER_HOST
     deps =
         --no-deps -r ./lock/requirements-dev.txt
-    commands = pytest {posargs}
+    commands =
+        py310: pip install --no-deps backports.asyncio.runner==1.2.0 exceptiongroup==1.3.0 tomli==2.2.1
+        pytest {posargs}
 """

{hexkit-6.0.0 → hexkit-7.1.0}/src/hexkit/config.py

@@ -16,8 +16,9 @@
 """Config parsing functionality based on pydantic's BaseSettings"""
 
 import os
+from collections.abc import Callable
 from pathlib import Path
-from typing import Callable, Final, Optional
+from typing import Final
 
 from pydantic_settings import (
     BaseSettings,
@@ -33,7 +34,7 @@ DEFAULT_CONFIG_PREFIX: Final = "ghga_services"
 class ConfigYamlDoesNotExist(RuntimeError):
     """Thrown when the context manager is used out of context."""
 
-    def __init__(self, path: Path, specified_via: Optional[str] = None):
+    def __init__(self, path: Path, specified_via: str | None = None):
         message = (
             "The config yaml " + ""
             if specified_via is None
@@ -42,7 +43,7 @@ class ConfigYamlDoesNotExist(RuntimeError):
         super().__init__(message)
 
 
-def get_default_config_yaml(prefix: str) -> Optional[Path]:
+def get_default_config_yaml(prefix: str) -> Path | None:
     """Get the path to the default config function.
 
     Args:
@@ -122,7 +123,7 @@ def config_from_yaml(
             )
 
         def constructor_wrapper(
-            config_yaml: Optional[Path] = None,
+            config_yaml: Path | None = None,
             **kwargs,
         ):
             """A wrapper for constructing a pydantic BaseSetting with modified sources

{hexkit-6.0.0 → hexkit-7.1.0}/src/hexkit/custom_types.py

@@ -18,29 +18,27 @@
 
 from collections.abc import Mapping, Sequence
 from datetime import date, datetime
-from typing import Any, Literal, Union
+from typing import Any, Literal
 from uuid import UUID
 
 # A type for fields that can be used as identifiers (primary keys).
-ID = Union[int, str, UUID]
+ID = int | str | UUID
 
 # This is intended to type objects that are assumed to be JSON serializable.
 # (Scalar types as well as arrays are excluded from the above assumption,
 # and we serialize date, datetime and UUID objects to JSON as strings.)
 JsonObject = Mapping[
     str,
-    Union[
-        int,
-        float,
-        str,
-        bool,
-        date,
-        datetime,
-        UUID,
-        Sequence[Any],
-        Mapping[str, Any],
-        None,
-    ],
+    int
+    | float
+    | str
+    | bool
+    | date
+    | datetime
+    | UUID
+    | Sequence[Any]
+    | Mapping[str, Any]
+    | None,
 ]
 
 

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

@@ -19,7 +19,7 @@
 import json
 from datetime import datetime, timezone
 from logging import Formatter, Logger, LogRecord, StreamHandler, addLevelName, getLogger
-from typing import Any, Literal, Optional
+from typing import Any, Literal
 
 from pydantic import Field
 from pydantic_settings import BaseSettings
@@ -61,7 +61,7 @@ class LoggingConfig(BaseSettings):
             + " this service. This is included in log messages."
         ),
     )
-    log_format: Optional[str] = Field(
+    log_format: str | None = Field(
         default=None,
         examples=[
             "%(timestamp)s - %(service)s - %(level)s - %(message)s",
@@ -166,7 +166,7 @@ class RecordCompiler(StreamHandler):
         return super().handle(record)
 
 
-def configure_logging(*, config: LoggingConfig, logger: Optional[Logger] = None):
+def configure_logging(*, config: LoggingConfig, logger: Logger | None = None):
     """Set up logging.
 
     Configures the root logger by default, but can be used to configure a specific

hexkit-7.1.0/src/hexkit/opentelemetry.py

@@ -0,0 +1,76 @@
+# 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.
+"""OpenTelemetry specific configuration code. This is gated behind the opentelemetry extra."""
+
+import logging
+import os
+from typing import Annotated
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.environment_variables import OTEL_SDK_DISABLED
+from opentelemetry.sdk.resources import SERVICE_NAME, Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.trace.sampling import ParentBasedTraceIdRatio
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+logger = logging.getLogger(__name__)
+
+
+class OpenTelemetryConfig(BaseSettings):
+    """OpenTelemetry specific configuration options"""
+
+    enable_opentelemetry: bool = Field(
+        default=False,
+        description="If set to true, this will run necessary setup code."
+        "If set to false, environment variables are set that should also effectively "
+        "disable autoinstrumentation.",
+    )
+    otel_trace_sampling_rate: Annotated[float, Field(strict=True, ge=0, le=1)] = Field(
+        default=1.0,
+        description="Determines which proportion of spans should be sampled. "
+        "A value of 1.0 means all and is equivalent to the previous behaviour. "
+        "Setting this to 0 will result in no spans being sampled, but this does not "
+        "automatically set `enable_opentelemetry` to False.",
+    )
+
+
+def configure_opentelemetry(*, service_name: str, config: OpenTelemetryConfig):
+    """Configure all needed parts of OpenTelemetry.
+
+    Setup of the TracerProvider is done programmatically, while disabling OpenTelemetry
+    sets the corresponding environment variable.
+    """
+    if config.enable_opentelemetry:
+        resource = Resource(attributes={SERVICE_NAME: service_name})
+        # Replace the default static sampler with a probabilistic one that honors parent
+        # span sampling decisions
+        # This should consistently yield full traces within a service but not necessarily
+        # across service boundaries
+        # With the default sampling rate, behaviour does not change, but this allows to
+        # introduce head sampling by adjusting a config option on the service side later on
+        sampler = ParentBasedTraceIdRatio(rate=config.otel_trace_sampling_rate)
+
+        # Initialize service specific TracerProvider
+        trace_provider = TracerProvider(resource=resource, sampler=sampler)
+        processor = BatchSpanProcessor(OTLPSpanExporter())
+        trace_provider.add_span_processor(processor)
+        trace.set_tracer_provider(trace_provider)
+    else:
+        # Currently OTEL_SDK_DISABLED doesn't seem to be honored by all implementations yet
+        # It seems to be working well enough for the Python implementation.
+        os.environ[OTEL_SDK_DISABLED] = "true"

{hexkit-6.0.0 → hexkit-7.1.0}/src/hexkit/protocols/dao.py

@@ -23,7 +23,7 @@ from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator, Collection, Mapping
 from contextlib import AbstractAsyncContextManager
 from functools import partial
-from typing import Any, Optional, TypeVar
+from typing import Any, TypeVar
 from uuid import uuid4
 
 from pydantic import BaseModel, Field
@@ -268,7 +268,7 @@ class DaoFactoryBase:
         cls,
         *,
         dto_model: type[Dto],
-        fields_to_index: Optional[Collection[str]],
+        fields_to_index: Collection[str] | None,
     ) -> None:
         """Checks that all provided fields are present in the dto_model.
         Raises IndexFieldsInvalidError otherwise.
@@ -289,7 +289,7 @@ class DaoFactoryBase:
         *,
         dto_model: type[Dto],
         id_field: str,
-        fields_to_index: Optional[Collection[str]],
+        fields_to_index: Collection[str] | None,
     ) -> None:
         """Validates the input parameters of the get_dao method."""
         cls._validate_dto_model_id(dto_model=dto_model, id_field=id_field)
@@ -309,7 +309,7 @@ class DaoFactoryProtocol(DaoFactoryBase, ABC):
         name: str,
         dto_model: type[Dto],
         id_field: str,
-        fields_to_index: Optional[Collection[str]] = None,
+        fields_to_index: Collection[str] | None = None,
     ) -> Dao[Dto]:
         """Constructs a DAO for interacting with resources in a database.
 
@@ -354,7 +354,7 @@ class DaoFactoryProtocol(DaoFactoryBase, ABC):
         name: str,
         dto_model: type[Dto],
         id_field: str,
-        fields_to_index: Optional[Collection[str]],
+        fields_to_index: Collection[str] | None,
     ) -> Dao[Dto]:
         """*To be implemented by the provider. Input validation is done outside of this
         method.*

{hexkit-6.0.0 → hexkit-7.1.0}/src/hexkit/protocols/daopub.py

@@ -23,8 +23,7 @@ of the outbox pattern.
 
 import typing
 from abc import ABC, abstractmethod
-from collections.abc import Collection
-from typing import Callable, Optional
+from collections.abc import Callable, Collection
 
 from hexkit.custom_types import JsonObject
 from hexkit.protocols.dao import (
@@ -61,8 +60,8 @@ class DaoPublisherFactoryProtocol(DaoFactoryBase, ABC):
         name: str,
         dto_model: type[Dto],
         id_field: str,
-        fields_to_index: Optional[Collection[str]] = None,
-        dto_to_event: Callable[[Dto], Optional[JsonObject]],
+        fields_to_index: Collection[str] | None = None,
+        dto_to_event: Callable[[Dto], JsonObject | None],
         event_topic: str,
         autopublish: bool = True,
     ) -> DaoPublisher[Dto]:
@@ -121,8 +120,8 @@ class DaoPublisherFactoryProtocol(DaoFactoryBase, ABC):
         name: str,
         dto_model: type[Dto],
         id_field: str,
-        fields_to_index: Optional[Collection[str]],
-        dto_to_event: Callable[[Dto], Optional[JsonObject]],
+        fields_to_index: Collection[str] | None,
+        dto_to_event: Callable[[Dto], JsonObject | None],
         event_topic: str,
         autopublish: bool,
     ) -> DaoPublisher[Dto]:

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

@@ -18,7 +18,6 @@
 
 from abc import ABC, abstractmethod
 from collections.abc import Mapping
-from typing import Optional
 from uuid import UUID, uuid4
 
 from pydantic import UUID4
@@ -37,8 +36,8 @@ class EventPublisherProtocol(ABC):
         type_: Ascii,
         key: Ascii,
         topic: Ascii,
-        event_id: Optional[UUID4] = None,
-        headers: Optional[Mapping[str, str]] = None,
+        event_id: UUID4 | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> None:
         """Publish an event.