chore: release v0.4.1 [skip ci]

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

README.md

@@ -12,6 +12,8 @@ Subclass an adapter in your own repository to add domain-specific methods while
 | **Adapters**     | Technology-specific base classes (`RedisAdapter`, `MinioAdapter`) |
 | **Your project** | Subclass an adapter and add domain methods                        |
 
+Connection adapters expose `connect()`, `disconnect()`, and `is_connected()`. The latter verifies backend reachability with a cached health probe (default TTL: 1 second). Subclasses may override `health_check_ttl_seconds`.
+
 ## 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.

pyproject.toml

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

python_repositories/__init__.py

@@ -2,10 +2,10 @@
 
 from __future__ import annotations
 
-import importlib
 from typing import TYPE_CHECKING
 
 # Interfaces are always available; they have no optional backend dependencies.
+from . import adapters
 from .interfaces import (
     ConnectionAwareInterface,
     ContextAwareInterface,
@@ -13,34 +13,24 @@ from .interfaces import (
     ObjectRepositoryInterface,
 )
 
-# Adapters are imported only for static type checkers; runtime loading is deferred below.
+# Adapters are imported only for static type checkers; runtime loading is delegated below.
 if TYPE_CHECKING:
-    from .adapters.minio_adapter import MinioAdapter
-    from .adapters.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.
-_LAZY_EXPORTS = {
-    "RedisAdapter": (".adapters.redis_adapter", "RedisAdapter"),
-    "MinioAdapter": (".adapters.minio_adapter", "MinioAdapter"),
-}
+    from .adapters.minio_adapter import MinioAdapter as MinioAdapter
+    from .adapters.redis_adapter import RedisAdapter as RedisAdapter
 
 __all__ = [
     "ConnectionAwareInterface",
     "ContextAwareInterface",
     "JsonRepositoryInterface",
     "ObjectRepositoryInterface",
-    "RedisAdapter",
-    "MinioAdapter",
+    *adapters.__all__,
 ]
 
 
 def __getattr__(name: str) -> object:
-    """Load adapters on first access so the base package installs without redis/minio."""
-    if name in _LAZY_EXPORTS:
-        module_path, attr = _LAZY_EXPORTS[name]
-        module = importlib.import_module(module_path, __package__)
-        return getattr(module, attr)
+    """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}")
 
 

python_repositories/adapters/__init__.py

@@ -9,10 +9,14 @@ 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"),
@@ -25,6 +29,7 @@ __all__ = [
 
 
 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__)
@@ -33,4 +38,5 @@ def __getattr__(name: str) -> object:
 
 
 def __dir__() -> list[str]:
+    """Expose lazy adapter names in tab completion and dir()."""
     return sorted(__all__)

python_repositories/adapters/connection_aware_adapter.py

@@ -0,0 +1,80 @@
+"""Shared connection lifecycle behavior for repository adapters."""
+
+from __future__ import annotations
+
+import time
+from abc import abstractmethod
+from typing import Self
+
+import structlog
+
+from python_repositories.interfaces import (
+    ConnectionAwareInterface,
+    ContextAwareInterface,
+)
+
+
+class ConnectionAwareAdapter(ConnectionAwareInterface, ContextAwareInterface):
+    """Base adapter with context-manager and TTL-cached connection health checks."""
+
+    health_check_ttl_seconds: float = 1.0
+    connection_name: str = ""
+
+    def __init__(self) -> None:
+        self.logger = structlog.get_logger(self.__class__.__name__)
+        self._health_check_at: float | None = None
+        self._health_check_ok: bool = False
+
+    def __enter__(self) -> Self:
+        """Enter the context."""
+        self.connect()
+        return self
+
+    def __exit__(
+        self, exc_type: type | None, exc_val: object | None, exc_tb: object | None
+    ) -> None:
+        """Exit the context."""
+        ctx_info = {"exc_type": exc_type, "exc_val": exc_val, "exc_tb": exc_tb}
+        if any(
+            (
+                exc_type is not None,
+                exc_val is not None,
+                exc_tb is not None,
+            ),
+        ):
+            self.logger.error("Error while exiting context", **ctx_info)
+        self.disconnect()
+
+    def _invalidate_health_cache(self) -> None:
+        self._health_check_at = None
+        self._health_check_ok = False
+
+    @abstractmethod
+    def _is_client_ready(self) -> bool:
+        """Return True when internal state is sufficient for a probe."""
+
+    @abstractmethod
+    def _probe_connection(self) -> bool:
+        """Backend-specific liveness check; called only when client is ready."""
+
+    def is_connected(self) -> bool:
+        """Check if connected to the backend."""
+        if not self._is_client_ready():
+            return False
+        now = time.monotonic()
+        if self._health_check_at is not None:
+            seconds_since_last_health_check = now - self._health_check_at
+            cache_is_fresh = (
+                seconds_since_last_health_check < self.health_check_ttl_seconds
+            )
+            if cache_is_fresh:
+                return self._health_check_ok
+        result = self._probe_connection()
+        self._health_check_at = now
+        self._health_check_ok = result
+        self.logger.debug("Connection status", connected=result)
+        return result
+
+    def _require_connected(self) -> None:
+        if not self.is_connected():
+            raise ConnectionError(f"Not connected to {self.connection_name}")

python_repositories/adapters/minio_adapter.py

@@ -3,15 +3,13 @@
 from __future__ import annotations
 import os
 from io import BytesIO
-from typing import Self
-import structlog
+
 from python_utils import check_env
 
-from python_repositories.interfaces import (
-    ConnectionAwareInterface,
-    ContextAwareInterface,
-    ObjectRepositoryInterface,
+from python_repositories.adapters.connection_aware_adapter import (
+    ConnectionAwareAdapter,
 )
+from python_repositories.interfaces import ObjectRepositoryInterface
 
 try:
     import minio
@@ -22,11 +20,7 @@ except ImportError as exc:
     ) from exc
 
 
-class MinioAdapter(
-    ObjectRepositoryInterface,
-    ContextAwareInterface,
-    ConnectionAwareInterface,
-):
+class MinioAdapter(ObjectRepositoryInterface, ConnectionAwareAdapter):
     """Minio adapter exposing basic CRUD functionality."""
 
     endpoint_env_var_name: str = "MINIO_ENDPOINT"
@@ -34,13 +28,10 @@ class MinioAdapter(
     secret_key_env_var_name: str = "MINIO_SECRET_KEY"
     bucket_env_var_name: str = "MINIO_BUCKET"
     chunk_size: int = 5 * 2**20  # 5 MiB
+    connection_name: str = "Minio"
 
     def __init__(self) -> None:
-        # Setup logger
-        self.logger = structlog.get_logger(
-            self.__class__.__name__,
-        )
-        # Check environment variables
+        super().__init__()
         check_env(
             {
                 self.endpoint_env_var_name,
@@ -49,36 +40,19 @@ class MinioAdapter(
                 self.bucket_env_var_name,
             },
         )
-        # Prepare internal variables
         self._client: minio.Minio | None = None
         self._bucket_name: str | None = None
 
-    def __enter__(self) -> Self:
-        """Enter the context."""
-        self.connect()
-        return self
-
-    def __exit__(
-        self, exc_type: type | None, exc_val: object | None, exc_tb: object | None
-    ) -> None:
-        """Exit the context."""
-        ctx_info = {"exc_type": exc_type, "exc_val": exc_val, "exc_tb": exc_tb}
-        if any(
-            (
-                exc_type is not None,
-                exc_val is not None,
-                exc_tb is not None,
-            ),
-        ):
-            self.logger.error("Error while exiting context", **ctx_info)
-        self.disconnect()
+    def _is_client_ready(self) -> bool:
+        return self._client is not None and self._bucket_name is not None
 
     def connect(self) -> None:
         """Connect to the Minio server."""
-        # Stop if already connected
-        if self.is_connected:
+        if self._client is not None and self.is_connected():
             self.logger.info("Already connected to Minio")
             return
+        if self._client is not None:
+            self.disconnect()
         # Prepare arguments
         endpoint = str(os.getenv(self.endpoint_env_var_name))
         access_key = str(os.getenv(self.access_key_env_var_name))
@@ -103,6 +77,7 @@ class MinioAdapter(
         # Persist information
         self._client = client
         self._bucket_name = bucket
+        self._invalidate_health_cache()
 
     def disconnect(self) -> None:
         """Disconnect from the Minio server."""
@@ -111,13 +86,14 @@ class MinioAdapter(
         # Reset client
         self._client = None
         self._bucket_name = None
+        self._invalidate_health_cache()
 
-    @property
-    def is_connected(self) -> bool:
-        """Check if connected to Minio server."""
-        res = self._client is not None
-        self.logger.debug(res)
-        return res
+    def _probe_connection(self) -> bool:
+        assert self._client is not None and self._bucket_name is not None
+        try:
+            return bool(self._client.bucket_exists(self._bucket_name))
+        except Exception:  # pylint: disable=broad-except
+            return False
 
     def put(
         self,
@@ -134,8 +110,8 @@ 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 self._bucket_name is None or not self.is_connected:
-            raise ConnectionError("Not connected to Minio")
+        self._require_connected()
+        assert self._client is not None and self._bucket_name is not None
         # Prepare buffer for reading
         num_bytes = data.getbuffer().nbytes
         data.seek(0)
@@ -159,8 +135,8 @@ 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 self._bucket_name is None or not self.is_connected:
-            raise ConnectionError("Not connected to Minio")
+        self._require_connected()
+        assert self._client is not None and self._bucket_name is not None
         # Get data from bucket
         # N.B. bucket name is set when connecting
         try:
@@ -194,8 +170,8 @@ 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 self._bucket_name is None or not self.is_connected:
-            raise ConnectionError("Not connected to Minio")
+        self._require_connected()
+        assert self._client is not None and self._bucket_name is not None
         # Delete object from bucket
         # N.B. bucket name is set when connecting
         self._client.remove_object(
@@ -213,8 +189,8 @@ 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 self._bucket_name is None or not self.is_connected:
-            raise ConnectionError("Not connected to Minio")
+        self._require_connected()
+        assert self._client is not None and self._bucket_name is not None
         # List objects in bucket
         objects = self._client.list_objects(
             bucket_name=self._bucket_name,

python_repositories/adapters/redis_adapter.py

@@ -1,17 +1,15 @@
 """Definition of RedisAdapter class."""
 
 from __future__ import annotations
-from typing import Self, cast
+from typing import cast
 import os
-import structlog
 
 from python_utils import check_env
 
-from python_repositories.interfaces import (
-    ConnectionAwareInterface,
-    ContextAwareInterface,
-    JsonRepositoryInterface,
+from python_repositories.adapters.connection_aware_adapter import (
+    ConnectionAwareAdapter,
 )
+from python_repositories.interfaces import JsonRepositoryInterface
 
 try:
     import redis
@@ -23,50 +21,29 @@ except ImportError as exc:
     ) from exc
 
 
-class RedisAdapter(
-    JsonRepositoryInterface,
-    ContextAwareInterface,
-    ConnectionAwareInterface,
-):
+class RedisAdapter(JsonRepositoryInterface, ConnectionAwareAdapter):
     """Redis adapter exposing basic CRUD functionality."""
 
     uri_env_var_name: str = "REDIS_URI"
     path: str = "."  # JSON root path, updated in __init__
     encoding: str = "UTF-8"
+    connection_name: str = "Redis"
 
     def __init__(self) -> None:
-        # Setup logger
-        self.logger = structlog.get_logger(
-            self.__class__.__name__,
-        )
-        # Check environment variables
+        super().__init__()
         check_env(self.uri_env_var_name)
-        # Prepare internal variables
         self._client: redis.Redis | None = None
         self.path: str = RedisPath.root_path()
 
-    def __enter__(self) -> Self:
-        """Enter the context."""
-        self.connect()
-        return self
-
-    def __exit__(
-        self, exc_type: type | None, exc_val: object | None, exc_tb: object | None
-    ) -> None:
-        """Exit the context."""
-        ctx_info = {"exc_type": exc_type, "exc_val": exc_val, "exc_tb": exc_tb}
-        if any(
-            (
-                exc_type is not None,
-                exc_val is not None,
-                exc_tb is not None,
-            ),
-        ):
-            self.logger.error("Error while exiting context", **ctx_info)
-        self.disconnect()
+    def _is_client_ready(self) -> bool:
+        return self._client is not None
 
     def connect(self) -> None:
         """Connect to the Redis server."""
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+            self._invalidate_health_cache()
         # Prepare arguments
         uri = str(os.getenv(self.uri_env_var_name))
         # Connect client
@@ -81,6 +58,7 @@ class RedisAdapter(
             raise ConnectionError(f"Could not connect to Redis at {uri}") from exc
         # Persist client
         self._client = client
+        self._invalidate_health_cache()
 
     def disconnect(self) -> None:
         """Disconnect from the Redis server."""
@@ -89,13 +67,14 @@ class RedisAdapter(
             self._client.close()
         # Reset client
         self._client = None
+        self._invalidate_health_cache()
 
-    @property
-    def is_connected(self) -> bool:
-        """Check if connected to Redis server."""
-        res = self._client is not None
-        self.logger.debug(res)
-        return res
+    def _probe_connection(self) -> bool:
+        assert self._client is not None
+        try:
+            return bool(self._client.ping())
+        except (redis.ConnectionError, redis.TimeoutError):
+            return False
 
     def set(self, key: str, data: dict) -> None:
         """Set a JSON object in Redis."""
@@ -105,8 +84,8 @@ class RedisAdapter(
         if not isinstance(data, dict) or len(data) == 0:
             raise ValueError("Data must be a non-empty dictionary")
         # Check connection
-        if self._client is None or not self.is_connected:
-            raise ConnectionError("Not connected to Redis")
+        self._require_connected()
+        assert self._client is not None
         # Set data
         self._client.json().set(key, self.path, data)
         self.logger.debug(f"Set {key} to {data}")
@@ -117,8 +96,8 @@ class RedisAdapter(
         if not isinstance(key, str) or len(key) == 0:
             raise ValueError("Key must be a non-empty string")
         # Check connection
-        if self._client is None or not self.is_connected:
-            raise ConnectionError("Not connected to Redis")
+        self._require_connected()
+        assert self._client is not None
         # Get data
         data = cast(
             dict | None,
@@ -133,8 +112,8 @@ class RedisAdapter(
         if not isinstance(key, str) or len(key) == 0:
             raise ValueError("Key must be a non-empty string")
         # Check connection
-        if self._client is None or not self.is_connected:
-            raise ConnectionError("Not connected to Redis")
+        self._require_connected()
+        assert self._client is not None
         # Delete data
         self._client.json().delete(key)
         self.logger.debug(f"Deleted {key}")
@@ -145,8 +124,8 @@ class RedisAdapter(
         if not isinstance(pattern, str) or len(pattern) == 0:
             raise ValueError("Pattern must be a non-empty string")
         # Check connection
-        if self._client is None or not self.is_connected:
-            raise ConnectionError("Not connected to Redis")
+        self._require_connected()
+        assert self._client is not None
         # List keys
         keys_raw = cast(
             list[bytes],

python_repositories/interfaces/connection_aware_interface.py

@@ -16,8 +16,10 @@ class ConnectionAwareInterface(ABC):
         """Disconnect from resource."""
         ...
 
-    @property
     @abstractmethod
     def is_connected(self) -> bool:
-        """Check if connected to resource."""
+        """Return whether the adapter has an active, reachable connection.
+
+        Implementations may perform a cached network probe to verify liveness.
+        """
         ...

tests/integration/connection_aware_interface_test.py

@@ -15,7 +15,6 @@ def test_instantiation_fails_when_connect_not_implemented() -> None:
         def disconnect(self) -> None:
             pass
 
-        @property
         def is_connected(self) -> bool:
             return False
 
@@ -32,7 +31,6 @@ def test_instantiation_fails_when_disconnect_not_implemented() -> None:
         def connect(self) -> None:
             pass
 
-        @property
         def is_connected(self) -> bool:
             return False
 

tests/integration/minio_adapter_test.py

@@ -115,7 +115,7 @@ def test_should_have_logger_when_instantiated() -> None:
 def test_should_not_be_connected_when_instantiated() -> None:
     """Test that the MinioAdapter is not connected when instantiated."""
     adapter = MinioAdapter()
-    assert not adapter.is_connected
+    assert not adapter.is_connected()
 
 
 def test_should_log_info_when_already_connected(
@@ -137,7 +137,7 @@ def test_should_raise_connection_error_when_unable_to_connect(
     adapter = MinioAdapter()
     with pytest.raises(ConnectionError):
         adapter.connect()
-    assert not adapter.is_connected
+    assert not adapter.is_connected()
 
 
 def test_should_log_info_when_creating_expected_bucket(
@@ -163,7 +163,7 @@ def test_should_log_error_on_exception_during_exit(
     """Test that the MinioAdapter logs an error if an exception occurs during __exit__."""
     try:
         with MinioAdapter() as adapter:
-            assert adapter.is_connected
+            assert adapter.is_connected()
             raise ValueError("Simulated error")
     except ValueError:
         pass  # Expected

tests/integration/redis_adapter_test.py

@@ -9,7 +9,7 @@ from python_repositories.interfaces import JsonRepositoryInterface
 
 
 @pytest.fixture(scope="module")
-def data() -> Generator[dict[str, str]]:
+def data() -> Generator[dict[str, str], None, None]:
     """Provide a sample data dictionary for tests."""
     yield {"foo": "bar"}
 
@@ -18,7 +18,7 @@ def data() -> Generator[dict[str, str]]:
 def data_in_redis(
     raw_redis_client: redis.Redis,
     data: dict[str, str],
-) -> Generator[tuple[str, dict[str, str]]]:
+) -> Generator[tuple[str, dict[str, str]], None, None]:
     """Fixture to set up a known value in Redis before each test."""
     key = "test_key"
     path = RedisPath.root_path()
@@ -31,7 +31,7 @@ def data_in_redis(
 
 
 @pytest.fixture(scope="module")
-def redis_adapter(redis_container: str) -> Generator[RedisAdapter]:
+def redis_adapter(redis_container: str) -> Generator[RedisAdapter, None, None]:
     """Fixture to provide a connected RedisAdapter instance."""
     adapter = RedisAdapter()
     adapter.connect()
@@ -63,7 +63,7 @@ def test_should_not_be_connected_when_instantiated(redis_container: str) -> None
     """Test that the RedisAdapter is not connected when instantiated."""
     adapter = RedisAdapter()
     assert adapter._client is None
-    assert not adapter.is_connected
+    assert not adapter.is_connected()
 
 
 def test_should_raise_connection_error_when_unable_to_connect(
@@ -77,7 +77,7 @@ def test_should_raise_connection_error_when_unable_to_connect(
     with pytest.raises(ConnectionError):
         adapter.connect()
     assert adapter._client is None
-    assert not adapter.is_connected
+    assert not adapter.is_connected()
 
 
 def test_connect_raises_connection_error_when_unable_to_ping(
@@ -109,7 +109,7 @@ def test_should_log_error_on_exception_during_exit(
     """Test that the RedisAdapter logs an error when an exception occurs during context exit."""
     try:
         with RedisAdapter() as adapter:
-            assert adapter.is_connected
+            assert adapter.is_connected()
             raise ValueError("Simulated error")
     except ValueError:
         pass  # Expected

tests/unit/connection_health_test.py

@@ -0,0 +1,184 @@
+"""Tests for TTL-cached connection health checks on adapters."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+import redis
+
+from python_repositories.adapters.minio_adapter import MinioAdapter
+from python_repositories.adapters.redis_adapter import RedisAdapter
+
+
+@pytest.fixture
+def redis_adapter(monkeypatch: pytest.MonkeyPatch) -> RedisAdapter:
+    monkeypatch.setenv("REDIS_URI", "redis://localhost:6379")
+    return RedisAdapter()
+
+
+@pytest.fixture
+def minio_adapter(monkeypatch: pytest.MonkeyPatch) -> MinioAdapter:
+    monkeypatch.setenv("MINIO_ENDPOINT", "localhost:9000")
+    monkeypatch.setenv("MINIO_ACCESS_KEY", "minioadmin")
+    monkeypatch.setenv("MINIO_SECRET_KEY", "minioadmin")
+    monkeypatch.setenv("MINIO_BUCKET", "test-bucket")
+    return MinioAdapter()
+
+
+class TestRedisConnectionHealth:
+    def test_not_connected_when_no_client(self, redis_adapter: RedisAdapter) -> None:
+        assert not redis_adapter.is_connected()
+
+    def test_connected_when_probe_succeeds(self, redis_adapter: RedisAdapter) -> None:
+        mock_client = MagicMock(spec=redis.Redis)
+        mock_client.ping.return_value = True
+        redis_adapter._client = mock_client
+
+        assert redis_adapter.is_connected()
+        mock_client.ping.assert_called_once()
+
+    def test_stale_connection_when_probe_fails(
+        self, redis_adapter: RedisAdapter
+    ) -> None:
+        mock_client = MagicMock(spec=redis.Redis)
+        mock_client.ping.side_effect = redis.ConnectionError("connection lost")
+        redis_adapter._client = mock_client
+
+        assert not redis_adapter.is_connected()
+
+    def test_cache_hit_avoids_second_probe(self, redis_adapter: RedisAdapter) -> None:
+        mock_client = MagicMock(spec=redis.Redis)
+        mock_client.ping.return_value = True
+        redis_adapter._client = mock_client
+
+        with patch(
+            "python_repositories.adapters.connection_aware_adapter.time.monotonic",
+            return_value=100.0,
+        ):
+            assert redis_adapter.is_connected()
+            assert redis_adapter.is_connected()
+
+        mock_client.ping.assert_called_once()
+
+    def test_cache_miss_runs_probe_again(self, redis_adapter: RedisAdapter) -> None:
+        mock_client = MagicMock(spec=redis.Redis)
+        mock_client.ping.return_value = True
+        redis_adapter._client = mock_client
+
+        with patch(
+            "python_repositories.adapters.connection_aware_adapter.time.monotonic",
+            side_effect=[100.0, 102.0],
+        ):
+            assert redis_adapter.is_connected()
+            assert redis_adapter.is_connected()
+
+        assert mock_client.ping.call_count == 2
+
+    def test_disconnect_clears_cache(self, redis_adapter: RedisAdapter) -> None:
+        mock_client = MagicMock(spec=redis.Redis)
+        mock_client.ping.return_value = True
+        redis_adapter._client = mock_client
+
+        with patch(
+            "python_repositories.adapters.connection_aware_adapter.time.monotonic",
+            return_value=100.0,
+        ):
+            assert redis_adapter.is_connected()
+
+        redis_adapter.disconnect()
+        redis_adapter._client = mock_client
+
+        with patch(
+            "python_repositories.adapters.connection_aware_adapter.time.monotonic",
+            return_value=100.0,
+        ):
+            assert redis_adapter.is_connected()
+
+        assert mock_client.ping.call_count == 2
+
+
+class TestMinioConnectionHealth:
+    def test_not_connected_when_no_client(self, minio_adapter: MinioAdapter) -> None:
+        assert not minio_adapter.is_connected()
+
+    def test_not_connected_when_bucket_name_missing(
+        self, minio_adapter: MinioAdapter
+    ) -> None:
+        minio_adapter._client = MagicMock()
+        minio_adapter._bucket_name = None
+
+        assert not minio_adapter.is_connected()
+
+    def test_connected_when_probe_succeeds(self, minio_adapter: MinioAdapter) -> None:
+        mock_client = MagicMock()
+        mock_client.bucket_exists.return_value = True
+        minio_adapter._client = mock_client
+        minio_adapter._bucket_name = "test-bucket"
+
+        assert minio_adapter.is_connected()
+        mock_client.bucket_exists.assert_called_once_with("test-bucket")
+
+    def test_stale_connection_when_probe_fails(
+        self, minio_adapter: MinioAdapter
+    ) -> None:
+        mock_client = MagicMock()
+        mock_client.bucket_exists.side_effect = Exception("connection lost")
+        minio_adapter._client = mock_client
+        minio_adapter._bucket_name = "test-bucket"
+
+        assert not minio_adapter.is_connected()
+
+    def test_cache_hit_avoids_second_probe(self, minio_adapter: MinioAdapter) -> None:
+        mock_client = MagicMock()
+        mock_client.bucket_exists.return_value = True
+        minio_adapter._client = mock_client
+        minio_adapter._bucket_name = "test-bucket"
+
+        with patch(
+            "python_repositories.adapters.connection_aware_adapter.time.monotonic",
+            return_value=100.0,
+        ):
+            assert minio_adapter.is_connected()
+            assert minio_adapter.is_connected()
+
+        mock_client.bucket_exists.assert_called_once()
+
+    def test_cache_miss_runs_probe_again(self, minio_adapter: MinioAdapter) -> None:
+        mock_client = MagicMock()
+        mock_client.bucket_exists.return_value = True
+        minio_adapter._client = mock_client
+        minio_adapter._bucket_name = "test-bucket"
+
+        with patch(
+            "python_repositories.adapters.connection_aware_adapter.time.monotonic",
+            side_effect=[100.0, 102.0],
+        ):
+            assert minio_adapter.is_connected()
+            assert minio_adapter.is_connected()
+
+        assert mock_client.bucket_exists.call_count == 2
+
+    def test_disconnect_clears_cache(self, minio_adapter: MinioAdapter) -> None:
+        mock_client = MagicMock()
+        mock_client.bucket_exists.return_value = True
+        minio_adapter._client = mock_client
+        minio_adapter._bucket_name = "test-bucket"
+
+        with patch(
+            "python_repositories.adapters.connection_aware_adapter.time.monotonic",
+            return_value=100.0,
+        ):
+            assert minio_adapter.is_connected()
+
+        minio_adapter.disconnect()
+        minio_adapter._client = mock_client
+        minio_adapter._bucket_name = "test-bucket"
+
+        with patch(
+            "python_repositories.adapters.connection_aware_adapter.time.monotonic",
+            return_value=100.0,
+        ):
+            assert minio_adapter.is_connected()
+
+        assert mock_client.bucket_exists.call_count == 2

tests/unit/optional_dependencies_test.py

@@ -4,15 +4,19 @@ 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
-from python_repositories import JsonRepositoryInterface
+
+_ROOT = Path(__file__).resolve().parents[2]
 
 
 def _block_backend_import(blocked_prefix: str) -> Callable[..., ModuleType]:
@@ -33,10 +37,23 @@ def _block_backend_import(blocked_prefix: str) -> Callable[..., ModuleType]:
 
 
 def test_base_import_does_not_load_adapters() -> None:
-    """Interfaces are available without loading adapter modules."""
-    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
+    """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:
@@ -93,3 +110,10 @@ def test_top_level_lazy_import_propagates_minio_import_error() -> None:
     ):
         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"

uv.lock

@@ -1053,7 +1053,7 @@ wheels = [
 
 [[package]]
 name = "python-repositories"
-version = "0.3.1"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "python-utils" },