Add public repository interfaces and subclassable adapter CRUD API.

Define split JSON and object repository ABCs, promote adapter methods to public CRUD, add example domain repositories, modernize interface stubs, and make the package installable for tests.

Co-authored-by: Cursor <[email protected]>

python_repositories/interfaces/__init__.py

@@ -2,8 +2,16 @@ from .connection_aware_interface import (
     ConnectionAwareInterface as ConnectionAwareInterface,
 )
 from .context_aware_interface import ContextAwareInterface as ContextAwareInterface
+from .json_repository_interface import (
+    JsonRepositoryInterface as JsonRepositoryInterface,
+)
+from .object_repository_interface import (
+    ObjectRepositoryInterface as ObjectRepositoryInterface,
+)
 
 __all__ = [
     "ConnectionAwareInterface",
     "ContextAwareInterface",
+    "JsonRepositoryInterface",
+    "ObjectRepositoryInterface",
 ]

python_repositories/interfaces/connection_aware_interface.py

@@ -9,15 +9,15 @@ class ConnectionAwareInterface(ABC):
     @abstractmethod
     def connect(self) -> None:
         """Connect to resource."""
-        raise NotImplementedError()
+        ...
 
     @abstractmethod
     def disconnect(self) -> None:
         """Disconnect from resource."""
-        raise NotImplementedError()
+        ...
 
     @property
     @abstractmethod
     def is_connected(self) -> bool:
         """Check if connected to resource."""
-        raise NotImplementedError()
+        ...

python_repositories/interfaces/context_aware_interface.py

@@ -1,4 +1,4 @@
-"""Definition of ConnectionAwareInterface abstract base class."""
+"""Definition of ContextAwareInterface abstract base class."""
 
 from __future__ import annotations
 
@@ -6,16 +6,16 @@ from abc import ABC, abstractmethod
 
 
 class ContextAwareInterface(ABC):
-    """Interface that defined context-related methods."""
+    """Interface that defines context-related methods."""
 
     @abstractmethod
     def __enter__(self) -> ContextAwareInterface:
         """Enter the context."""
-        raise NotImplementedError()
+        ...
 
     @abstractmethod
     def __exit__(
         self, exc_type: type | None, exc_val: object | None, exc_tb: object | None
     ) -> None:
         """Exit the context."""
-        raise NotImplementedError()
+        ...

python_repositories/interfaces/json_repository_interface.py

@@ -0,0 +1,27 @@
+"""Definition of JsonRepositoryInterface abstract base class."""
+
+from abc import ABC, abstractmethod
+
+
+class JsonRepositoryInterface(ABC):
+    """Interface that defines JSON document CRUD methods."""
+
+    @abstractmethod
+    def get(self, key: str) -> dict | None:
+        """Get a JSON object by key."""
+        ...
+
+    @abstractmethod
+    def set(self, key: str, data: dict) -> None:
+        """Set a JSON object by key."""
+        ...
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Delete a JSON object by key."""
+        ...
+
+    @abstractmethod
+    def list_keys(self, pattern: str) -> list[str]:
+        """List keys matching a glob pattern."""
+        ...

python_repositories/interfaces/object_repository_interface.py

@@ -0,0 +1,33 @@
+"""Definition of ObjectRepositoryInterface abstract base class."""
+
+from abc import ABC, abstractmethod
+from io import BytesIO
+
+
+class ObjectRepositoryInterface(ABC):
+    """Interface that defines binary object CRUD methods."""
+
+    @abstractmethod
+    def get(self, object_name: str) -> BytesIO | None:
+        """Get an object by name."""
+        ...
+
+    @abstractmethod
+    def put(
+        self,
+        object_name: str,
+        data: BytesIO,
+        content_type: str = "application/octet-stream",
+    ) -> None:
+        """Put an object by name."""
+        ...
+
+    @abstractmethod
+    def delete(self, object_name: str) -> None:
+        """Delete an object by name."""
+        ...
+
+    @abstractmethod
+    def list_objects(self, prefix: str = "") -> list[str]:
+        """List object names with an optional prefix."""
+        ...