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 <cursoragent@cursor.com>

tests/integration/object_repository_interface_test.py

@@ -0,0 +1,99 @@
+"""Integration tests for ObjectRepositoryInterface."""
+
+from io import BytesIO
+
+import pytest
+from python_repositories.interfaces.object_repository_interface import (
+    ObjectRepositoryInterface,
+)
+
+
+def test_instantiation_fails_when_get_not_implemented() -> None:
+    """Test that instantiation fails if get is not implemented."""
+
+    class Incomplete(ObjectRepositoryInterface):
+        """A class that does not implement get."""
+
+        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 []
+
+    with pytest.raises(TypeError):
+        _ = Incomplete()  # type: ignore
+
+
+def test_instantiation_fails_when_put_not_implemented() -> None:
+    """Test that instantiation fails if put is not implemented."""
+
+    class Incomplete(ObjectRepositoryInterface):
+        """A class that does not implement put."""
+
+        def get(self, object_name: str) -> BytesIO | None:
+            return None
+
+        def delete(self, object_name: str) -> None:
+            pass
+
+        def list_objects(self, prefix: str = "") -> list[str]:
+            return []
+
+    with pytest.raises(TypeError):
+        _ = Incomplete()  # type: ignore
+
+
+def test_instantiation_fails_when_delete_not_implemented() -> None:
+    """Test that instantiation fails if delete is not implemented."""
+
+    class Incomplete(ObjectRepositoryInterface):
+        """A class that does not implement delete."""
+
+        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 list_objects(self, prefix: str = "") -> list[str]:
+            return []
+
+    with pytest.raises(TypeError):
+        _ = Incomplete()  # type: ignore
+
+
+def test_instantiation_fails_when_list_objects_not_implemented() -> None:
+    """Test that instantiation fails if list_objects is not implemented."""
+
+    class Incomplete(ObjectRepositoryInterface):
+        """A class that does not implement list_objects."""
+
+        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
+
+    with pytest.raises(TypeError):
+        _ = Incomplete()  # type: ignore