chore: release v0.3.2 [skip ci]

Reviewed-on: https://gitea.lille-vemmelund.dk/brian/python-repositories/pulls/19

.gitea/workflows/test.yml

@@ -40,9 +40,20 @@ jobs:
           PR_NUMBER: ${{ github.event.pull_request.number }}
           CI_RUNNER_TOKEN: ${{ secrets.CI_RUNNER_TOKEN }}
         run: |
-          COVERAGE=$(cat coverage.txt)
+          PAYLOAD=$(python3 -c '
-          COMMENT_BODY="**Test Coverage Report:**\n\`\`\`\n$COVERAGE\n\`\`\`"
+          import json
-          curl -s -X POST "$API_URL/repos/$REPO_OWNER/$REPO_NAME/issues/$PR_NUMBER/comments" \
+          import pathlib
+
+          coverage = pathlib.Path("coverage.txt").read_text()
+          print(
+              json.dumps(
+                  {
+                      "body": f"**Test Coverage Report:**\n```\n{coverage}\n```",
+                  }
+              )
+          )
+          ')
+          curl -sf -X POST "$API_URL/repos/$REPO_OWNER/$REPO_NAME/issues/$PR_NUMBER/comments" \
             -H "Authorization: token $CI_RUNNER_TOKEN" \
             -H "Content-Type: application/json" \
-            -d "{\"body\": \"$COMMENT_BODY\"}"
+            -d "$PAYLOAD"

.gitignore

@@ -173,4 +173,3 @@ cython_debug/
 
 # PyPI configuration file
 .pypirc
-

.pre-commit-config.yaml

@@ -24,6 +24,8 @@ repos:
     rev: v1.8.0
     hooks:
       - id: mypy
+        additional_dependencies:
+          - types-redis
 
   # Python syntax modernization with pyupgrade
   - repo: https://github.com/asottile/pyupgrade

README.md

@@ -14,6 +14,8 @@ Subclass an adapter in your own repository to add domain-specific methods while
 
 ## Optional dependencies
 
+Repository **interfaces** import with the base package. **Adapters** require the matching extra; importing an adapter without its extra raises `ImportError` with install instructions.
+
 Install with the extras you need:
 
 ```bash

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-repositories"
-version = "0.3.1"
+version = "0.3.2"
 description = "Various python repository interfaces exposed as a python package."
 authors = [
     { name = "Brian Bjarke Jensen", email = "[email protected]" }

python_repositories/__init__.py

@@ -1,6 +1,11 @@
 """python_repositories: Unified repository interfaces and adapters."""
 
-from .adapters import MinioAdapter, RedisAdapter
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# Interfaces are always available; they have no optional backend dependencies.
+from . import adapters
 from .interfaces import (
     ConnectionAwareInterface,
     ContextAwareInterface,
@@ -8,11 +13,27 @@ from .interfaces import (
     ObjectRepositoryInterface,
 )
 
+# Adapters are imported only for static type checkers; runtime loading is delegated below.
+if TYPE_CHECKING:
+    from .adapters.minio_adapter import MinioAdapter as MinioAdapter
+    from .adapters.redis_adapter import RedisAdapter as RedisAdapter
+
 __all__ = [
     "ConnectionAwareInterface",
     "ContextAwareInterface",
     "JsonRepositoryInterface",
     "ObjectRepositoryInterface",
-    "RedisAdapter",
+    *adapters.__all__,
-    "MinioAdapter",
 ]
+
+
+def __getattr__(name: str) -> object:
+    """Delegate adapter lookups to adapters; lazy loading is defined there."""
+    if name in adapters.__all__:
+        return getattr(adapters, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Expose lazy adapter names in tab completion and dir()."""
+    return sorted(__all__)

python_repositories/adapters/__init__.py

@@ -4,10 +4,39 @@ Adapters for various backend repositories (e.g., Redis, Minio).
 This module exposes concrete implementations for repository interfaces.
 """
 
-from .redis_adapter import RedisAdapter
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+# Adapters are imported only for static type checkers; runtime loading is deferred below.
+if TYPE_CHECKING:
     from .minio_adapter import MinioAdapter
+    from .redis_adapter import RedisAdapter
+
+# Map public adapter names to their defining module and class.
+# Each adapter module fails fast with an install hint if its extra is missing.
+# When adding a new adapter, update this dict and __all__ only.
+_LAZY_EXPORTS = {
+    "RedisAdapter": (".redis_adapter", "RedisAdapter"),
+    "MinioAdapter": (".minio_adapter", "MinioAdapter"),
+}
 
 __all__ = [
     "RedisAdapter",
     "MinioAdapter",
 ]
+
+
+def __getattr__(name: str) -> object:
+    """Load an adapter on first access so the base package installs without backend clients."""
+    if name in _LAZY_EXPORTS:
+        module_path, attr = _LAZY_EXPORTS[name]
+        module = importlib.import_module(module_path, __package__)
+        return getattr(module, attr)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Expose lazy adapter names in tab completion and dir()."""
+    return sorted(__all__)

python_repositories/adapters/minio_adapter.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 import os
 from io import BytesIO
-from importlib.util import find_spec
 from typing import Self
 import structlog
 from python_utils import check_env
@@ -14,9 +13,13 @@ from python_repositories.interfaces import (
     ObjectRepositoryInterface,
 )
 
-# Handle optional dependencies
+try:
-if find_spec("minio") is not None:
     import minio
+except ImportError as exc:
+    raise ImportError(
+        "MinIO support requires the minio extra. "
+        "Install with: pip install python-repositories[minio]"
+    ) from exc
 
 
 class MinioAdapter(
@@ -112,7 +115,7 @@ class MinioAdapter(
     @property
     def is_connected(self) -> bool:
         """Check if connected to Minio server."""
-        res = bool(isinstance(self._client, minio.Minio))
+        res = self._client is not None
         self.logger.debug(res)
         return res
 
@@ -131,7 +134,7 @@ class MinioAdapter(
         if not isinstance(content_type, str) or len(content_type) == 0:
             raise ValueError("content_type must be a non-empty string")
         # Check connection
-        if self._client is None or not self.is_connected:
+        if self._client is None or self._bucket_name is None or not self.is_connected:
             raise ConnectionError("Not connected to Minio")
         # Prepare buffer for reading
         num_bytes = data.getbuffer().nbytes
@@ -156,7 +159,7 @@ class MinioAdapter(
         if not isinstance(object_name, str) or len(object_name) == 0:
             raise ValueError("object_name must be a non-empty string")
         # Check connection
-        if self._client is None or not self.is_connected:
+        if self._client is None or self._bucket_name is None or not self.is_connected:
             raise ConnectionError("Not connected to Minio")
         # Get data from bucket
         # N.B. bucket name is set when connecting
@@ -191,7 +194,7 @@ class MinioAdapter(
         if not isinstance(object_name, str) or len(object_name) == 0:
             raise ValueError("object_name must be a non-empty string")
         # Check connection
-        if self._client is None or not self.is_connected:
+        if self._client is None or self._bucket_name is None or not self.is_connected:
             raise ConnectionError("Not connected to Minio")
         # Delete object from bucket
         # N.B. bucket name is set when connecting
@@ -210,7 +213,7 @@ class MinioAdapter(
             raise ValueError("prefix must be a string")
         # Check connection
         # N.B. bucket name is set when connecting
-        if self._client is None or not self.is_connected:
+        if self._client is None or self._bucket_name is None or not self.is_connected:
             raise ConnectionError("Not connected to Minio")
         # List objects in bucket
         objects = self._client.list_objects(

python_repositories/adapters/redis_adapter.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 from typing import Self, cast
-from importlib.util import find_spec
 import os
 import structlog
 
@@ -14,10 +13,14 @@ from python_repositories.interfaces import (
     JsonRepositoryInterface,
 )
 
-# Handle optional dependencies
+try:
-if find_spec("redis") is not None:
     import redis
     from redis.commands.json.path import Path as RedisPath
+except ImportError as exc:
+    raise ImportError(
+        "Redis support requires the redis extra. "
+        "Install with: pip install python-repositories[redis]"
+    ) from exc
 
 
 class RedisAdapter(
@@ -90,7 +93,7 @@ class RedisAdapter(
     @property
     def is_connected(self) -> bool:
         """Check if connected to Redis server."""
-        res = bool(isinstance(self._client, redis.Redis))
+        res = self._client is not None
         self.logger.debug(res)
         return res
 

tests/integration/conftest.py

@@ -1,16 +1,19 @@
 """Integration tests configuration."""
 
+import logging
 import os
 from collections.abc import Generator
+
 import pytest
 import redis
 import structlog
-import logging
 from minio import Minio
-
-from testcontainers.redis import RedisContainer
 from testcontainers.minio import MinioContainer
 
+from tests.integration.redis_container_test import REDIS_PORT, RedisTestContainer
+
+collect_ignore = ["redis_container_test.py"]
+
 MINIO_ACCESS_KEY = "minioadmin"
 MINIO_SECRET_KEY = "minioadmin"
 MINIO_BUCKET = "test-bucket"
@@ -37,16 +40,16 @@ def configure_logging() -> None:
 
 
 @pytest.fixture(scope="session")
-def redis_container() -> Generator[str]:
+def redis_container() -> Generator[str, None, None]:
     """Set up a Redis container for testing and yield the Redis URI."""
     # Start container
-    container = RedisContainer(
+    container = RedisTestContainer(
         image="redis/redis-stack:7.2.0-v0",
     )
     container.start()
     # Set environment variable for Redis URI
     redis_host = container.get_container_host_ip()
-    redis_port = container.get_exposed_port(6379)
+    redis_port = container.get_exposed_port(REDIS_PORT)
     redis_uri = f"redis://{redis_host}:{redis_port}"
 
     yield redis_uri
@@ -56,7 +59,7 @@ def redis_container() -> Generator[str]:
 
 
 @pytest.fixture(scope="session")
-def minio_container() -> Generator[dict[str, str]]:
+def minio_container() -> Generator[dict[str, str], None, None]:
     """Set up a Minio container for testing and yield the Minio URI."""
     # Start container
     container = MinioContainer(
@@ -86,7 +89,7 @@ def minio_container() -> Generator[dict[str, str]]:
 def set_environment_variables(
     redis_container: str,
     minio_container: dict[str, str],
-) -> Generator[dict[str, str]]:
+) -> Generator[dict[str, str], None, None]:
     """Set environment variables needed for tests."""
     # Build environment variables dictionary
     env_vars = {"REDIS_URI": redis_container}
@@ -103,7 +106,7 @@ def set_environment_variables(
 
 
 @pytest.fixture(scope="session")
-def raw_redis_client(redis_container: str) -> Generator[redis.Redis]:
+def raw_redis_client(redis_container: str) -> Generator[redis.Redis, None, None]:
     """Provide a raw Redis client connected to the test Redis container."""
     # Connect client
     client = redis.Redis.from_url(
@@ -119,7 +122,7 @@ def raw_redis_client(redis_container: str) -> Generator[redis.Redis]:
 
 
 @pytest.fixture(scope="session")
-def raw_minio_client(minio_container: dict[str, str]) -> Generator[Minio]:
+def raw_minio_client(minio_container: dict[str, str]) -> Generator[Minio, None, None]:
     """Provide a raw Minio client connected to the test Minio container."""
     # Connect client
     client = Minio(

tests/integration/minio_adapter_test.py

@@ -9,6 +9,7 @@ import random
 import os
 import logging
 from minio import S3Error
+from urllib3.response import BaseHTTPResponse
 from python_repositories.adapters.minio_adapter import MinioAdapter
 from python_repositories.interfaces import ObjectRepositoryInterface
 
@@ -42,7 +43,7 @@ def same_data(
 
 
 @pytest.fixture(scope="module")
-def data() -> Generator[BytesIO]:
+def data() -> Generator[BytesIO, None, None]:
     """Provide a sample data bytes for tests."""
     # Generate random bytes
     random_bytes = random.randbytes(2**21)  # 2 MiB
@@ -53,7 +54,7 @@ def data() -> Generator[BytesIO]:
 def data_in_minio(
     raw_minio_client: Minio,
     data: BytesIO,
-) -> Generator[tuple[str, BytesIO]]:
+) -> Generator[tuple[str, BytesIO], None, None]:
     """Fixture to set up a known value in Minio before each test."""
     object_name = "test_object"
     bucket_name = str(os.getenv("MINIO_BUCKET"))
@@ -77,7 +78,7 @@ def data_in_minio(
 
 
 @pytest.fixture(scope="module")
-def minio_adapter() -> Generator[MinioAdapter]:
+def minio_adapter() -> Generator[MinioAdapter, None, None]:
     """Fixture to provide a connected MinioAdapter instance."""
     adapter = MinioAdapter()
     adapter.connect()
@@ -234,12 +235,12 @@ def test_should_log_warning_when_getting_nonexistent_object(
     adapter = MinioAdapter()
     adapter._client = MagicMock(spec=Minio)
     adapter._client.get_object.side_effect = S3Error(
-        code="NoSuchKey",
+        MagicMock(spec=BaseHTTPResponse),
-        message="",
+        "NoSuchKey",
-        resource="",
+        "",
-        request_id="",
+        "",
-        host_id="",
+        "",
-        response="",
+        "",
         bucket_name="test-bucket",
         object_name="missing-object",
     )
@@ -264,12 +265,12 @@ def test_should_log_error_when_getting_with_s3error_other_than_no_such_key(
     adapter = MinioAdapter()
     adapter._client = MagicMock(spec=Minio)
     other_s3error = S3Error(
-        code="UnhandledError",
+        MagicMock(spec=BaseHTTPResponse),
-        message="",
+        "UnhandledError",
-        resource="",
+        "",
-        request_id="",
+        "",
-        host_id="",
+        "",
-        response="",
+        "",
         bucket_name="test-bucket",
         object_name="missing-object",
     )

tests/integration/redis_container_test.py

@@ -0,0 +1,36 @@
+"""Redis test container without testcontainers' deprecated wait decorator."""
+
+from typing import Any, cast
+
+import redis
+from testcontainers.core.container import DockerContainer
+from testcontainers.core.waiting_utils import WaitStrategy, WaitStrategyTarget
+
+REDIS_PORT = 6379
+
+
+class _RedisPingWaitStrategy(WaitStrategy):
+    def __init__(self) -> None:
+        super().__init__()
+        self.with_transient_exceptions(redis.exceptions.ConnectionError)
+
+    def wait_until_ready(self, container: WaitStrategyTarget) -> None:
+        redis_container = cast("RedisTestContainer", container)
+        if not self._poll(lambda: redis_container.get_client().ping()):
+            raise redis.exceptions.ConnectionError("Could not connect to Redis")
+
+
+class RedisTestContainer(DockerContainer):
+    """Redis container using wait strategies instead of the deprecated decorator."""
+
+    def __init__(self, image: str, port: int = REDIS_PORT) -> None:
+        super().__init__(image, _wait_strategy=_RedisPingWaitStrategy())
+        self.port = port
+        self.with_exposed_ports(self.port)
+
+    def get_client(self, **kwargs: Any) -> redis.Redis:
+        return redis.Redis(
+            host=self.get_container_host_ip(),
+            port=self.get_exposed_port(self.port),
+            **kwargs,
+        )

tests/unit/optional_dependencies_test.py

@@ -0,0 +1,119 @@
+"""Tests for optional dependency import behavior."""
+
+from __future__ import annotations
+
+import builtins
+import importlib
+import os
+import subprocess
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from pathlib import Path
+from types import ModuleType
+from unittest.mock import patch
+
+import pytest
+
+import python_repositories
+
+_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _block_backend_import(blocked_prefix: str) -> Callable[..., ModuleType]:
+    real_import = builtins.__import__
+
+    def fake_import(
+        name: str,
+        globals: Mapping[str, object] | None = None,
+        locals: Mapping[str, object] | None = None,
+        fromlist: Sequence[str] = (),
+        level: int = 0,
+    ) -> ModuleType:
+        if name == blocked_prefix or name.startswith(f"{blocked_prefix}."):
+            raise ImportError(f"No module named '{name}'")
+        return real_import(name, globals, locals, fromlist, level)
+
+    return fake_import
+
+
+def test_base_import_does_not_load_adapters() -> None:
+    """Base package import does not eagerly load backend adapter modules."""
+    script = """
+import sys
+from python_repositories import JsonRepositoryInterface
+
+assert JsonRepositoryInterface is not None
+assert "python_repositories.adapters.redis_adapter" not in sys.modules
+assert "python_repositories.adapters.minio_adapter" not in sys.modules
+"""
+    result = subprocess.run(
+        [sys.executable, "-c", script],
+        cwd=_ROOT,
+        env={**os.environ, "PYTHONPATH": str(_ROOT)},
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0, result.stderr or result.stdout
+
+
+def test_lazy_adapter_load_succeeds_when_extra_present() -> None:
+    """Adapters load when their optional dependencies are installed."""
+    from python_repositories import MinioAdapter, RedisAdapter
+
+    assert RedisAdapter.__name__ == "RedisAdapter"
+    assert MinioAdapter.__name__ == "MinioAdapter"
+
+
+def test_redis_adapter_import_error_without_extra() -> None:
+    """Missing redis extra raises ImportError with install hint."""
+    import python_repositories.adapters.redis_adapter as redis_adapter_module
+
+    with patch.object(builtins, "__import__", new=_block_backend_import("redis")):
+        with pytest.raises(ImportError, match=r"python-repositories\[redis\]"):
+            importlib.reload(redis_adapter_module)
+
+    importlib.reload(redis_adapter_module)
+
+
+def test_minio_adapter_import_error_without_extra() -> None:
+    """Missing minio extra raises ImportError with install hint."""
+    import python_repositories.adapters.minio_adapter as minio_adapter_module
+
+    with patch.object(builtins, "__import__", new=_block_backend_import("minio")):
+        with pytest.raises(ImportError, match=r"python-repositories\[minio\]"):
+            importlib.reload(minio_adapter_module)
+
+    importlib.reload(minio_adapter_module)
+
+
+def test_top_level_lazy_import_propagates_redis_import_error() -> None:
+    """Top-level RedisAdapter access surfaces adapter import errors."""
+    with patch(
+        "importlib.import_module",
+        side_effect=ImportError(
+            "Redis support requires the redis extra. "
+            "Install with: pip install python-repositories[redis]"
+        ),
+    ):
+        with pytest.raises(ImportError, match=r"python-repositories\[redis\]"):
+            _ = python_repositories.RedisAdapter
+
+
+def test_top_level_lazy_import_propagates_minio_import_error() -> None:
+    """Top-level MinioAdapter access surfaces adapter import errors."""
+    with patch(
+        "importlib.import_module",
+        side_effect=ImportError(
+            "MinIO support requires the minio extra. "
+            "Install with: pip install python-repositories[minio]"
+        ),
+    ):
+        with pytest.raises(ImportError, match=r"python-repositories\[minio\]"):
+            _ = python_repositories.MinioAdapter
+
+
+def test_adapters_subpackage_lazy_import_succeeds() -> None:
+    """Adapter subpackage imports delegate to the same lazy loader."""
+    from python_repositories.adapters import RedisAdapter
+
+    assert RedisAdapter.__name__ == "RedisAdapter"