chore: release v2.1.0 [skip ci]

Reviewed-on: https://gitea.lille-vemmelund.dk/LilleVemmelund/python-repositories/pulls/57

.cursor/rules/pr-after-first-push.mdc

@@ -0,0 +1,58 @@
+---
+description: After first branch push, provide copy-ready PR title and body
+alwaysApply: true
+---
+
+# PR Title and Comment After First Push
+
+The user creates pull requests manually. After the **first push** of a feature branch to remote in a session, always end your response with a copy-ready PR title and PR comment.
+
+## When to provide it
+
+- After the first successful `git push` (or `git push -u origin <branch>`) for a branch in the current task
+- Do **not** create the PR with `gh pr create` unless explicitly asked
+- On later pushes to the same branch, only repeat if the user asks or the change set meaningfully updates what the PR should say
+
+## PR title
+
+- Use a fitting version-bump prefix when changes touch `python_repositories/`:
+  - `[patch]` or `[fix]` — bug fix
+  - `[minor]` or `[feat]` — new feature
+  - `[major]` or `[breaking]` — breaking change
+- Docs-, CI-, or test-only changes: no prefix required
+- Keep the title concise and descriptive
+
+## PR comment format
+
+Provide two separate fenced code blocks the user can copy directly:
+
+1. **PR title** — single line in a code block
+2. **PR comment** — body with `## Summary` and `## Test plan` sections, checklist items reflecting what was actually run
+
+Example structure:
+
+````
+PR title:
+
+```
+[minor] Short description of the change
+```
+
+PR comment:
+
+```
+## Summary
+
+- Bullet points of what changed and why
+
+## Test plan
+
+- [x] Commands or checks that were run
+```
+````
+
+## Notes
+
+- Match the repo PR template ([`.gitea/PULL_REQUEST_TEMPLATE.md`](.gitea/PULL_REQUEST_TEMPLATE.md))
+- Be accurate: only mark test-plan items done if they were run
+- Keep prose clear; the user copies this verbatim into Gitea

.cursor/rules/test-organization.mdc

@@ -0,0 +1,31 @@
+---
+description: Unit test file naming and placement conventions
+globs: tests/**/*.py
+alwaysApply: false
+---
+
+# Test Organization
+
+Unit tests use a one-to-one mapping between source modules and test files.
+
+## Naming
+
+- `python_repositories/<path>/<module>.py` → `tests/unit/<module>_test.py`
+- Test files must end with `_test.py` (enforced by pre-commit `name-tests-test`)
+
+## Placement
+
+- Add tests to the existing `*_test.py` for the module under test
+- Do not create cross-cutting test files (e.g. `structural_typing_test.py`); colocate with the relevant interface/adapter/config test file
+- Shared fixtures → `tests/conftest.py`
+- Module-specific helper classes → the matching test file
+
+## Examples
+
+```
+json_repository_interface.py  →  tests/unit/json_repository_interface_test.py
+redis_adapter.py              →  tests/unit/redis_adapter_test.py
+redis_config.py               →  tests/unit/redis_config_test.py
+```
+
+Integration tests live under `tests/integration/<backend>/` with the same `_test.py` suffix.

CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-07-11
+
+### Summary
+Add runtime-checkable Protocol typing to public interfaces
+
+### Changed
+- 1cbcc1c Merge pull request '[minor] Add runtime-checkable Protocol typing to public interfaces' (#57) from cursor/protocol-abc-interfaces into main
+- a0e5c9d Document test organization and add Cursor workflow rules.
+- 44b15cb Move structural typing tests into interface unit test files.
+- f6ee9a3 Add runtime-checkable Protocol typing to all public interfaces.
+- 0829354 Merge pull request 'Add async future note and remove redundant pytest pythonpath' (#56) from cursor/readme-async-and-test-path-cleanup into main
+- a0d509a Format CHANGELOG.md with Prettier.
+- 9b7b15a Document possible async support and drop redundant pytest pythonpath.
+
+## [2.0.5] - 2026-07-10
+
+### Summary
+
+Allow empty payloads in Redis and MinIO adapters
+
+### Changed
+
+- 6d02f32 Merge pull request '[patch] Allow empty payloads in Redis and MinIO adapters' (#55) from cursor/allow-empty-payloads into main
+- 57b396b Allow empty payloads in Redis and MinIO adapters.
+- 093e538 Merge pull request '[chore] Scope integration fixtures per backend subdirectory' (#54) from cursor/scoped-integration-fixtures into main
+- b28ac6e Scope integration fixtures per backend subdirectory.
+- 6c66fe4 Merge pull request 'Add consumer-facing CHANGELOG.md maintained by release CI' (#53) from cursor/consumer-changelog into main
+- 089a128 Format CHANGELOG.md with Prettier
+- 0a5bd39 Add consumer-facing CHANGELOG.md maintained by release CI.
+- 683ee33 Merge pull request '[chore] add repository URL and Python 3.12 packaging metadata' (#52) from cursor/add-packaging-metadata into main
+- 9df5032 Add repository URL and Python 3.12 packaging metadata.
+- 4f6f33f Merge pull request 'Drop types-redis in favor of redis inline types' (#51) from cursor/drop-types-redis into main
+- 10d43ce Drop types-redis in favor of redis inline types.
+
 ## [2.0.4] - 2026-07-10
 
 ### Summary

README.md

@@ -12,8 +12,14 @@ 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                        |
 
+Each public interface is a `@runtime_checkable` `Protocol` with `@abstractmethod` members. **Subclass an adapter** when you need connection management and shared behavior — explicit subclasses get runtime instantiation guards and inherited default methods (e.g. `scan_keys`). **Type-annotate against an interface** when you want loose coupling — any object with the right methods satisfies the contract for mypy and `isinstance()` checks, without inheriting from this package.
+
 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`. `connect()` is idempotent: calling it while already connected and healthy is a no-op.
 
+## Future direction
+
+The current API is synchronous. Async repository interfaces and adapters may be added in a future release; existing sync usage would remain supported.
+
 ## 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.
@@ -168,6 +174,15 @@ uv run pytest -v                                      # full suite (requires Doc
 
 Integration tests are marked with `@pytest.mark.integration` and require Docker (testcontainers). Backend-specific markers (`needs_redis`, `needs_minio`) let you run only the containers a test module needs. Run unit tests alone for quick local feedback.
 
+### Test organization
+
+Unit tests live in `tests/unit/` and follow a one-to-one naming convention: `<module>_test.py` tests `python_repositories/<module path>.py`. Examples:
+
+- `json_repository_interface.py` → `tests/unit/json_repository_interface_test.py`
+- `redis_adapter.py` → `tests/unit/redis_adapter_test.py`
+
+Add new tests to the existing file for that module rather than creating cross-cutting test files. Shared fixtures belong in `tests/conftest.py`; module-specific helpers may live in the matching test file.
+
 ### CI base image
 
 Gitea Actions jobs use a pre-built image (`python-repositories-ci`) with Python 3.12,

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-repositories"
-version = "2.0.4"
+version = "2.1.0"
 description = "Various python repository interfaces exposed as a python package."
 authors = [
     { name = "Brian Bjarke Jensen", email = "[email protected]" }
@@ -39,7 +39,6 @@ build-backend = "hatchling.build"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-pythonpath = ["."]
 addopts = "--import-mode=importlib"
 markers = [
     "integration: tests requiring Docker containers (deselect with '-m \"not integration\"')",

python_repositories/adapters/minio_adapter.py

@@ -19,7 +19,7 @@ except ImportError as exc:
     ) from exc
 
 
-class MinioAdapter(ObjectRepositoryInterface, ConnectionAwareAdapter):
+class MinioAdapter(ConnectionAwareAdapter, ObjectRepositoryInterface):
     """Minio adapter exposing basic CRUD functionality."""
 
     endpoint_env_var_name: str = "MINIO_ENDPOINT"
@@ -114,12 +114,17 @@ class MinioAdapter(ObjectRepositoryInterface, ConnectionAwareAdapter):
         data: BytesIO,
         content_type: str = "application/octet-stream",
     ) -> None:
-        """Put an object into the Minio bucket."""
+        """Put an object into the Minio bucket.
+
+        Accepts zero-byte ``BytesIO``. A zero-byte object is returned by
+        ``get()`` as an empty buffer, not ``None``. Use ``delete()`` to remove
+        an object entirely.
+        """
         # Check input
         if not isinstance(object_name, str) or len(object_name) == 0:
             raise ValueError("object_name must be a non-empty string")
-        if not isinstance(data, BytesIO) or data.getbuffer().nbytes == 0:
-            raise ValueError("data must be a non-empty BytesIO object")
+        if not isinstance(data, BytesIO):
+            raise ValueError("data must be a BytesIO object")
         if not isinstance(content_type, str) or len(content_type) == 0:
             raise ValueError("content_type must be a non-empty string")
         # Check connection
@@ -143,7 +148,12 @@ class MinioAdapter(ObjectRepositoryInterface, ConnectionAwareAdapter):
         )
 
     def get(self, object_name: str) -> BytesIO | None:
-        """Get an object from the Minio bucket."""
+        """Get an object from the Minio bucket.
+
+        Returns ``None`` when the object does not exist. Returns an empty
+        ``BytesIO`` for a zero-byte object. Use ``value is not None`` to test
+        existence.
+        """
         # Check input
         if not isinstance(object_name, str) or len(object_name) == 0:
             raise ValueError("object_name must be a non-empty string")

python_repositories/adapters/redis_adapter.py

@@ -21,7 +21,7 @@ except ImportError as exc:
     ) from exc
 
 
-class RedisAdapter(JsonRepositoryInterface, ConnectionAwareAdapter):
+class RedisAdapter(ConnectionAwareAdapter, JsonRepositoryInterface):
     """Redis adapter exposing basic CRUD functionality."""
 
     uri_env_var_name: str = "REDIS_URI"
@@ -91,12 +91,17 @@ class RedisAdapter(JsonRepositoryInterface, ConnectionAwareAdapter):
             return False
 
     def set(self, key: str, data: dict[str, Any]) -> None:
-        """Set a JSON object in Redis."""
+        """Set a JSON object in Redis.
+
+        Accepts any dict, including ``{}``. An empty dict creates a key that
+        ``get()`` returns as ``{}``, not ``None``. Use ``delete()`` to remove a
+        key entirely.
+        """
         # Check input
         if not isinstance(key, str) or len(key) == 0:
             raise ValueError("Key must be a non-empty string")
-        if not isinstance(data, dict) or len(data) == 0:
-            raise ValueError("Data must be a non-empty dictionary")
+        if not isinstance(data, dict):
+            raise ValueError("Data must be a dictionary")
         # Check connection
         self._require_connected()
         assert self._client is not None
@@ -105,7 +110,12 @@ class RedisAdapter(JsonRepositoryInterface, ConnectionAwareAdapter):
         self.logger.debug("Set key", key=key, data_keys=list(data.keys()))
 
     def get(self, key: str) -> dict[str, Any] | None:
-        """Get a JSON object from Redis."""
+        """Get a JSON object from Redis.
+
+        Returns ``None`` if the key is absent. Returns ``{}`` if the key exists
+        with an empty JSON object. Use ``value is not None`` to test existence;
+        avoid truthiness checks (``{}`` is falsy).
+        """
         # Check input
         if not isinstance(key, str) or len(key) == 0:
             raise ValueError("Key must be a non-empty string")

python_repositories/interfaces/connection_aware_interface.py

@@ -1,9 +1,11 @@
-"""Definition of ConnectionAwareInterface abstract base class."""
+"""Definition of ConnectionAwareInterface protocol and abstract base class."""
 
-from abc import ABC, abstractmethod
+from abc import abstractmethod
+from typing import Protocol, runtime_checkable
 
 
-class ConnectionAwareInterface(ABC):
+@runtime_checkable
+class ConnectionAwareInterface(Protocol):
     """Interface that defines connection-related methods."""
 
     @abstractmethod

python_repositories/interfaces/context_aware_interface.py

@@ -1,12 +1,13 @@
-"""Definition of ContextAwareInterface abstract base class."""
+"""Definition of ContextAwareInterface protocol and abstract base class."""
 
 from __future__ import annotations
 
-from abc import ABC, abstractmethod
-from typing import Self
+from abc import abstractmethod
+from typing import Protocol, Self, runtime_checkable
 
 
-class ContextAwareInterface(ABC):
+@runtime_checkable
+class ContextAwareInterface(Protocol):
     """Interface that defines context-related methods."""
 
     @abstractmethod

python_repositories/interfaces/json_repository_interface.py

@@ -1,26 +1,37 @@
-"""Definition of JsonRepositoryInterface abstract base class."""
+"""Definition of JsonRepositoryInterface protocol and abstract base class."""
 
-from abc import ABC, abstractmethod
+from abc import abstractmethod
 from collections.abc import Iterator
-from typing import Any
+from typing import Any, Protocol, runtime_checkable
 
 
-class JsonRepositoryInterface(ABC):
+@runtime_checkable
+class JsonRepositoryInterface(Protocol):
     """Interface that defines JSON document CRUD methods."""
 
     @abstractmethod
     def get(self, key: str) -> dict[str, Any] | None:
-        """Get a JSON object by key."""
+        """Get a JSON object by key.
+
+        Returns ``None`` when the key is absent. Returns ``{}`` when the key
+        exists with an empty JSON object. Use ``value is not None`` to test
+        existence; avoid truthiness checks (``{}`` is falsy).
+        """
         ...
 
     @abstractmethod
     def set(self, key: str, data: dict[str, Any]) -> None:
-        """Set a JSON object by key."""
+        """Set a JSON object by key.
+
+        Accepts any dict, including ``{}``. An empty dict creates a key that
+        ``get()`` returns as ``{}``, not ``None``. Use ``delete()`` to remove a
+        key entirely.
+        """
         ...
 
     @abstractmethod
     def delete(self, key: str) -> None:
-        """Delete a JSON object by key."""
+        """Delete a JSON object by key, removing it entirely."""
         ...
 
     @abstractmethod

python_repositories/interfaces/object_repository_interface.py

@@ -1,18 +1,22 @@
-"""Definition of ObjectRepositoryInterface abstract base class."""
+"""Definition of ObjectRepositoryInterface protocol and abstract base class."""
 
-from abc import ABC, abstractmethod
+from abc import abstractmethod
 from io import BytesIO
+from typing import Protocol, runtime_checkable
 
 
-class ObjectRepositoryInterface(ABC):
+@runtime_checkable
+class ObjectRepositoryInterface(Protocol):
     """Interface that defines binary object CRUD methods."""
 
     @abstractmethod
     def get(self, object_name: str) -> BytesIO | None:
         """Get an object by name.
 
-        Returns None when the object does not exist. Raises ConnectionError when
-        not connected. Other backend errors propagate to the caller.
+        Returns ``None`` when the object does not exist. Returns an empty
+        ``BytesIO`` for a zero-byte object. Use ``value is not None`` to test
+        existence. Raises ConnectionError when not connected. Other backend
+        errors propagate to the caller.
         """
         ...
 
@@ -23,12 +27,17 @@ class ObjectRepositoryInterface(ABC):
         data: BytesIO,
         content_type: str = "application/octet-stream",
     ) -> None:
-        """Put an object by name."""
+        """Put an object by name.
+
+        Accepts zero-byte ``BytesIO``. A zero-byte object is returned by
+        ``get()`` as an empty buffer, not ``None``. Use ``delete()`` to remove
+        an object entirely.
+        """
         ...
 
     @abstractmethod
     def delete(self, object_name: str) -> None:
-        """Delete an object by name."""
+        """Delete an object by name, removing it entirely."""
         ...
 
     @abstractmethod

tests/integration/minio/minio_adapter_test.py

@@ -328,6 +328,44 @@ def test_should_raise_value_error_on_invalid_put_data(
             minio_adapter.put(object_name, invalid)  # type: ignore
 
 
+def test_should_put_and_get_empty_bytesio(
+    minio_adapter: MinioAdapter,
+    minio_config: MinioConfig,
+) -> None:
+    """Test that the MinioAdapter can put and get a zero-byte object."""
+    object_name = "empty_object"
+    empty_data = BytesIO()
+    assert minio_adapter.get(object_name) is None
+    minio_adapter.put(object_name, empty_data)
+    received_data = minio_adapter.get(object_name)
+    assert received_data is not None
+    assert same_data(empty_data, received_data)
+    minio_adapter._client.remove_object(minio_config.bucket, object_name)  # type: ignore[union-attr]
+
+
+def test_should_distinguish_missing_object_from_empty_object(
+    minio_adapter: MinioAdapter,
+    minio_config: MinioConfig,
+) -> None:
+    """Test that missing objects and zero-byte objects are distinguishable."""
+    object_name = "empty_object"
+    minio_adapter.put(object_name, BytesIO())
+    assert minio_adapter.get("other_object") is None
+    minio_adapter.delete(object_name)
+    assert minio_adapter.get(object_name) is None
+
+
+def test_should_list_zero_byte_object(
+    minio_adapter: MinioAdapter,
+    minio_config: MinioConfig,
+) -> None:
+    """Test that a zero-byte object appears in object listings."""
+    object_name = "empty_object"
+    minio_adapter.put(object_name, BytesIO())
+    assert object_name in minio_adapter.list_objects()
+    minio_adapter._client.remove_object(minio_config.bucket, object_name)  # type: ignore[union-attr]
+
+
 def test_should_raise_value_error_on_invalid_put_content_type(
     data: BytesIO,
     minio_adapter: MinioAdapter,

tests/integration/redis/redis_adapter_test.py

@@ -190,12 +190,45 @@ def test_should_raise_value_error_on_invalid_set_data(
 ) -> None:
     """Test that the RedisAdapter raises ValueError when setting with invalid data."""
     key = "test_key"
-    invalid_data = ["", 123, None, [], {}]
+    invalid_data = ["", 123, None, []]
     for data in invalid_data:
         with pytest.raises(ValueError):
             redis_adapter.set(key, data)  # type: ignore
 
 
+def test_should_set_and_get_empty_dict(
+    redis_adapter: RedisAdapter,
+) -> None:
+    """Test that the RedisAdapter can set and get an empty dict."""
+    key = "empty_key"
+    assert redis_adapter.get(key) is None
+    redis_adapter.set(key, {})
+    value = redis_adapter.get(key)
+    assert value is not None
+    assert value == {}
+
+
+def test_should_distinguish_missing_key_from_empty_dict(
+    redis_adapter: RedisAdapter,
+) -> None:
+    """Test that missing keys and empty dicts are distinguishable."""
+    key = "empty_key"
+    redis_adapter.set(key, {})
+    assert redis_adapter.get("other_key") is None
+    redis_adapter.delete(key)
+    assert redis_adapter.get(key) is None
+
+
+def test_should_list_empty_dict_key(
+    redis_adapter: RedisAdapter,
+) -> None:
+    """Test that a key with an empty dict appears in key listings."""
+    key = "empty_key"
+    redis_adapter.set(key, {})
+    assert key in redis_adapter.list_keys(key)
+    assert key in list(redis_adapter.scan_keys(key))
+
+
 def test_should_raise_connection_error_on_set_when_not_connected(
     redis_config: RedisConfig,
     data: dict[str, str],

tests/unit/connection_aware_interface_test.py

@@ -7,6 +7,24 @@ from python_repositories.interfaces.connection_aware_interface import (
 )
 
 
+class FakeConnection:
+    """Plain class that satisfies ConnectionAwareInterface without inheritance."""
+
+    def connect(self) -> None:
+        pass
+
+    def disconnect(self) -> None:
+        pass
+
+    def is_connected(self) -> bool:
+        return True
+
+
+def accepts_connection_aware(connection: ConnectionAwareInterface) -> None:
+    """Type-checking hook for ConnectionAwareInterface structural subtyping."""
+    connection.is_connected()
+
+
 def test_instantiation_fails_when_connect_not_implemented() -> None:
     """Test that instantiation fails if connect is not implemented."""
 
@@ -53,3 +71,10 @@ def test_instantiation_fails_when_is_connected_not_implemented() -> None:
 
     with pytest.raises(TypeError):
         _ = Incomplete()  # type: ignore
+
+
+def test_structural_subtyping() -> None:
+    """Test that a plain class satisfies ConnectionAwareInterface structurally."""
+    connection: ConnectionAwareInterface = FakeConnection()
+    accepts_connection_aware(connection)
+    assert isinstance(connection, ConnectionAwareInterface)

tests/unit/context_aware_interface_test.py

@@ -7,6 +7,24 @@ import pytest
 from python_repositories.interfaces.context_aware_interface import ContextAwareInterface
 
 
+class FakeContextManager:
+    """Plain class that satisfies ContextAwareInterface without inheritance."""
+
+    def __enter__(self) -> FakeContextManager:
+        return self
+
+    def __exit__(
+        self, exc_type: type | None, exc_val: object | None, exc_tb: object | None
+    ) -> None:
+        pass
+
+
+def accepts_context_aware(context: ContextAwareInterface) -> None:
+    """Type-checking hook for ContextAwareInterface structural subtyping."""
+    with context:
+        pass
+
+
 def test_instantiation_fails_when_enter_not_implemented() -> None:
     """Test that instantiation fails if __enter__ is not implemented."""
 
@@ -33,3 +51,10 @@ def test_instantiation_fails_when_exit_not_implemented() -> None:
 
     with pytest.raises(TypeError):
         _ = Incomplete()  # type: ignore
+
+
+def test_structural_subtyping() -> None:
+    """Test that a plain class satisfies ContextAwareInterface structurally."""
+    context: ContextAwareInterface = FakeContextManager()
+    accepts_context_aware(context)
+    assert isinstance(context, ContextAwareInterface)

tests/unit/json_repository_interface_test.py

@@ -1,5 +1,6 @@
 """Unit tests for JsonRepositoryInterface."""
 
+from collections.abc import Iterator
 from typing import Any
 
 import pytest
@@ -9,6 +10,36 @@ from python_repositories.interfaces.json_repository_interface import (
 )
 
 
+class InMemoryJsonRepo:
+    """Plain class that satisfies JsonRepositoryInterface without inheritance."""
+
+    def get(self, key: str) -> dict[str, Any] | None:
+        return None
+
+    def set(self, key: str, data: dict[str, Any]) -> None:
+        pass
+
+    def delete(self, key: str) -> None:
+        pass
+
+    def list_keys(self, pattern: str) -> list[str]:
+        return []
+
+    def scan_keys(
+        self,
+        pattern: str,
+        *,
+        count: int | None = None,
+    ) -> Iterator[str]:
+        del count
+        yield from self.list_keys(pattern)
+
+
+def accepts_json_repo(repo: JsonRepositoryInterface) -> None:
+    """Type-checking hook for JsonRepositoryInterface structural subtyping."""
+    repo.get("key")
+
+
 def test_instantiation_fails_when_get_not_implemented() -> None:
     """Test that instantiation fails if get is not implemented."""
 
@@ -104,3 +135,10 @@ def test_scan_keys_defaults_to_list_keys() -> None:
     repository = Complete()
 
     assert list(repository.scan_keys("user")) == ["user-1", "user-2"]
+
+
+def test_structural_subtyping() -> None:
+    """Test that a plain class satisfies JsonRepositoryInterface structurally."""
+    repo: JsonRepositoryInterface = InMemoryJsonRepo()
+    accepts_json_repo(repo)
+    assert isinstance(repo, JsonRepositoryInterface)

tests/unit/object_repository_interface_test.py

@@ -9,6 +9,32 @@ from python_repositories.interfaces.object_repository_interface import (
 )
 
 
+class InMemoryObjectRepo:
+    """Plain class that satisfies ObjectRepositoryInterface without inheritance."""
+
+    def get(self, object_name: str) -> BytesIO | None:
+        return None
+
+    def put(
+        self,
+        object_name: str,
+        data: BytesIO,
+        content_type: str = "application/octet-stream",
+    ) -> None:
+        pass
+
+    def delete(self, object_name: str) -> None:
+        pass
+
+    def list_objects(self, prefix: str = "") -> list[str]:
+        return []
+
+
+def accepts_object_repo(repo: ObjectRepositoryInterface) -> None:
+    """Type-checking hook for ObjectRepositoryInterface structural subtyping."""
+    repo.get("object")
+
+
 def test_instantiation_fails_when_get_not_implemented() -> None:
     """Test that instantiation fails if get is not implemented."""
 
@@ -98,3 +124,10 @@ def test_instantiation_fails_when_list_objects_not_implemented() -> None:
 
     with pytest.raises(TypeError):
         _ = Incomplete()  # type: ignore
+
+
+def test_structural_subtyping() -> None:
+    """Test that a plain class satisfies ObjectRepositoryInterface structurally."""
+    repo: ObjectRepositoryInterface = InMemoryObjectRepo()
+    accepts_object_repo(repo)
+    assert isinstance(repo, ObjectRepositoryInterface)

uv.lock

@@ -1,5 +1,5 @@
 version = 1
-revision = 3
+revision = 2
 requires-python = ">=3.12"
 resolution-markers = [
     "python_full_version >= '3.15'",
@@ -1056,7 +1056,7 @@ wheels = [
 
 [[package]]
 name = "python-repositories"
-version = "2.0.4"
+version = "2.1.0"
 source = { editable = "." }
 dependencies = [
     { name = "python-dotenv" },