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/redis_adapter_test.py

@@ -1,6 +1,3 @@
-# pylint: disable=protected-access
-# The above line disables pylint's protected member access warnings for this file,
-# allowing tests to access RedisAdapter's internal methods as needed for integration testing.
 """Integration tests for the RedisAdapter."""
 
 from collections.abc import Generator
@@ -8,6 +5,7 @@ import pytest
 import redis
 from redis.commands.json.path import Path as RedisPath
 from python_repositories.adapters.redis_adapter import RedisAdapter
+from python_repositories.interfaces import JsonRepositoryInterface
 
 
 @pytest.fixture(scope="module")
@@ -50,7 +48,7 @@ def clear_redis(raw_redis_client: redis.Redis) -> None:
 
 def test_should_adhere_to_interface(redis_container: str) -> None:
     """Test that the RedisAdapter adheres to the expected interface."""
-    # Instantiation fails if interface not adhered to
+    assert issubclass(RedisAdapter, JsonRepositoryInterface)
     _ = RedisAdapter()
 
 
@@ -134,7 +132,7 @@ def test_should_get_value(
     # Arrange
     key, data = data_in_redis
     # Act
-    value = redis_adapter._get(key)
+    value = redis_adapter.get(key)
     # Assert
     assert value is not None
     assert value == data
@@ -145,7 +143,7 @@ def test_should_get_none_for_missing_key(
 ) -> None:
     """Test that getting a non-existent key returns None."""
     # Act
-    value = redis_adapter._get("nonexistent_key")
+    value = redis_adapter.get("nonexistent_key")
     # Assert
     assert value is None
 
@@ -159,7 +157,7 @@ def test_should_raise_value_error_on_invalid_get_key(
     # Act & Assert
     for key in invalid_keys:
         with pytest.raises(ValueError):
-            redis_adapter._get(key)  # type: ignore
+            redis_adapter.get(key)  # type: ignore
 
 
 def test_should_raise_connection_error_on_get_when_not_connected(
@@ -170,7 +168,7 @@ def test_should_raise_connection_error_on_get_when_not_connected(
     adapter = RedisAdapter()  # not connected
     # Act & Assert
     with pytest.raises(ConnectionError):
-        adapter._get("some_key")
+        adapter.get("some_key")
 
 
 def test_should_set_value(
@@ -180,12 +178,12 @@ def test_should_set_value(
     """Test that the RedisAdapter can set a value."""
     # Arrange
     key = "test_key"
-    received_data = redis_adapter._get(key)
+    received_data = redis_adapter.get(key)
     assert received_data is None  # Ensure key does not exist
     # Act
-    redis_adapter._set(key, data)
+    redis_adapter.set(key, data)
     # Assert
-    received_data = redis_adapter._get(key)
+    received_data = redis_adapter.get(key)
     assert received_data is not None
     assert received_data == data
 
@@ -198,13 +196,13 @@ def test_should_update_value(
     # Arrange
     key, _ = data_in_redis
     new_data = {"new_key": "new_value"}
-    received_data = redis_adapter._get(key)
+    received_data = redis_adapter.get(key)
     assert received_data is not None
     assert received_data != new_data
     # Act
-    redis_adapter._set(key, new_data)
+    redis_adapter.set(key, new_data)
     # Assert
-    assert redis_adapter._get(key) == new_data
+    assert redis_adapter.get(key) == new_data
 
 
 def test_should_raise_value_error_on_invalid_set_key(
@@ -217,7 +215,7 @@ def test_should_raise_value_error_on_invalid_set_key(
     # Act & Assert
     for key in invalid_keys:
         with pytest.raises(ValueError):
-            redis_adapter._set(key, data)  # type: ignore
+            redis_adapter.set(key, data)  # type: ignore
 
 
 def test_should_raise_value_error_on_invalid_set_data(
@@ -230,7 +228,7 @@ def test_should_raise_value_error_on_invalid_set_data(
     # Act & Assert
     for data in invalid_data:
         with pytest.raises(ValueError):
-            redis_adapter._set(key, data)  # type: ignore
+            redis_adapter.set(key, data)  # type: ignore
 
 
 def test_should_raise_connection_error_on_set_when_not_connected(
@@ -243,7 +241,7 @@ def test_should_raise_connection_error_on_set_when_not_connected(
     key = "test_key"
     # Act & Assert
     with pytest.raises(ConnectionError):
-        adapter._set(key, data)
+        adapter.set(key, data)
 
 
 def test_should_delete_key(
@@ -253,12 +251,12 @@ def test_should_delete_key(
     """Test that deleting a key removes it from Redis."""
     # Arrange
     key, _ = data_in_redis
-    received_data = redis_adapter._get(key)
+    received_data = redis_adapter.get(key)
     assert received_data is not None  # Ensure key exists
     # Act
-    redis_adapter._delete(key)
+    redis_adapter.delete(key)
     # Assert
-    assert redis_adapter._get(key) is None
+    assert redis_adapter.get(key) is None
 
 
 def test_should_raise_value_error_on_invalid_delete_key(
@@ -270,7 +268,7 @@ def test_should_raise_value_error_on_invalid_delete_key(
     # Act & Assert
     for key in invalid_keys:
         with pytest.raises(ValueError):
-            redis_adapter._delete(key)  # type: ignore
+            redis_adapter.delete(key)  # type: ignore
 
 
 def test_should_raise_connection_error_on_delete_when_not_connected(
@@ -281,7 +279,7 @@ def test_should_raise_connection_error_on_delete_when_not_connected(
     adapter = RedisAdapter()
     # Act & Assert
     with pytest.raises(ConnectionError):
-        adapter._delete("some_key")
+        adapter.delete("some_key")
 
 
 def test_should_list_keys(
@@ -289,10 +287,10 @@ def test_should_list_keys(
 ) -> None:
     """Test listing keys matching a pattern returns correct keys."""
     # Arrange
-    redis_adapter._set("key1", {"a": 1})
-    redis_adapter._set("key2", {"b": 2})
+    redis_adapter.set("key1", {"a": 1})
+    redis_adapter.set("key2", {"b": 2})
     # Act
-    keys = redis_adapter._list_keys("key*")
+    keys = redis_adapter.list_keys("key*")
     # Assert
     assert set(keys) == {"key1", "key2"}
 
@@ -306,7 +304,7 @@ def test_should_raise_value_error_on_invalid_list_keys_pattern(
     # Act & Assert
     for pattern in invalid_patterns:
         with pytest.raises(ValueError):
-            redis_adapter._list_keys(pattern)  # type: ignore
+            redis_adapter.list_keys(pattern)  # type: ignore
 
 
 def test_should_raise_connection_error_on_list_keys_when_not_connected(
@@ -317,7 +315,7 @@ def test_should_raise_connection_error_on_list_keys_when_not_connected(
     adapter = RedisAdapter()
     # Act & Assert
     with pytest.raises(ConnectionError):
-        adapter._list_keys("some_pattern")
+        adapter.list_keys("some_pattern")
 
 
 # allows local debugging by running file as script