openframe-adapters-db-postgres 1.1.0__tar.gz → 1.2.0__tar.gz

{openframe_adapters_db_postgres-1.1.0 → openframe_adapters_db_postgres-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openframe-adapters-db-postgres
-Version: 1.1.0
+Version: 1.2.0
 Summary: OpenFrame Microservice Suite — PostgreSQL database adapter.
 Project-URL: Homepage, https://github.com/Furious-Meteors/openframe-adapters
 Project-URL: Documentation, https://furious-meteors.github.io/openframe-adapters/

{openframe_adapters_db_postgres-1.1.0 → openframe_adapters_db_postgres-1.2.0}/openframe/adapters/db/postgres/plugin.py

@@ -22,6 +22,9 @@ Usage via deps.py (unchanged, no plugin needed)::
     repo = PostgresRepository(PostgresSettings())
     traced = TracingProxy(repo, prefix="repository.item")
 """
+# Capability: "persistence"
+# See capability taxonomy:
+# https://furious-meteors.github.io/openframe-core/developer-guide/composition-root/
 from __future__ import annotations
 
 import logging
@@ -44,6 +47,8 @@ class PostgresPlugin:
 
     Capability: "persistence"
 
+    Stability: beta
+
     Lifecycle:
         initialize() — creates the asyncpg connection pool and verifies
                        connectivity via ping(). Raises AdapterConnectionError
@@ -53,10 +58,20 @@ class PostgresPlugin:
 
     The plugin exposes get_repository() after initialization for use
     in the composition root or ApplicationBootstrap.
+
+    By default constructs a plain PostgresRepository. To use a domain-specific
+    subclass, pass it via repository_class::
+
+        registry.register(PostgresPlugin(
+            PostgresSettings(),
+            table="items",
+            id_column="id",
+            repository_class=ItemPostgresRepository,
+        ))
     """
 
     name:       str = "openframe-postgres"
-    version:    str = "1.1.0"
+    version:    str = "1.2.0"
     capability: str = "persistence"
 
     def __init__(
@@ -64,10 +79,31 @@ class PostgresPlugin:
         settings: PostgresSettings,
         table: str = "",
         id_column: str = "id",
+        repository_class: type[PostgresRepository] = PostgresRepository,
     ) -> None:
+        """
+        Args:
+            settings:         PostgresSettings instance.
+            table:            Table name. If omitted the plugin acts as a
+                              connection manager only (no get_repository()).
+            id_column:        Primary key column name. Defaults to "id".
+            repository_class: The PostgresRepository subclass to construct.
+                              Defaults to the base PostgresRepository. Pass a
+                              domain-specific subclass here to get proper
+                              entity mapping through get_repository().
+
+        Raises:
+            TypeError: repository_class is not a subclass of PostgresRepository.
+        """
+        if not (isinstance(repository_class, type) and issubclass(repository_class, PostgresRepository)):
+            raise TypeError(
+                f"repository_class must be a subclass of PostgresRepository, "
+                f"got {repository_class!r}"
+            )
         self._settings = settings
         self._table = table
         self._id_column = id_column
+        self._repository_class = repository_class
         self._repo: PostgresRepository | None = None
         self._status = PluginStatus.REGISTERED
 
@@ -94,7 +130,7 @@ class PostgresPlugin:
         try:
             pool = await get_postgres_pool(self._settings)
             if self._table:
-                self._repo = PostgresRepository(
+                self._repo = self._repository_class(
                     self._settings,
                     table=self._table,
                     id_column=self._id_column,
@@ -117,8 +153,9 @@ class PostgresPlugin:
                     ) from exc
             self._status = PluginStatus.READY
             _logger.info(
-                "PostgresPlugin initialized — %s",
+                "PostgresPlugin initialized — %s (repository_class=%s)",
                 self._settings.database_url.split("@")[-1],
+                self._repository_class.__name__,
             )
         except Exception:
             self._status = PluginStatus.FAILED

{openframe_adapters_db_postgres-1.1.0 → openframe_adapters_db_postgres-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openframe-adapters-db-postgres"
-version = "1.1.0"
+version = "1.2.0"
 description = "OpenFrame Microservice Suite — PostgreSQL database adapter."
 readme = "README.md"
 requires-python = ">=3.11"

{openframe_adapters_db_postgres-1.1.0 → openframe_adapters_db_postgres-1.2.0}/tests/test_plugin.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 
 import pytest
 
-from openframe.adapters.db.postgres import PostgresPlugin, PostgresSettings
+from openframe.adapters.db.postgres import PostgresPlugin, PostgresRepository, PostgresSettings
 from openframe.core.plugins import OpenFramePlugin, PluginContext, PluginStatus
 
 
@@ -46,7 +46,7 @@ def test_postgres_plugin_name(plugin):
 
 
 def test_postgres_plugin_version(plugin):
-    assert plugin.version == "1.1.0"
+    assert plugin.version == "1.2.0"
 
 
 def test_postgres_plugin_capability(plugin):
@@ -177,3 +177,68 @@ async def test_health_returns_failed_when_ping_fails(
     assert result is not None
     assert result.status == PluginStatus.FAILED
     conn_module._pool_cache.clear()
+
+
+# ── repository_class parameter ─────────────────────────────────────────────
+
+def test_plugin_defaults_to_base_repository_class(settings):
+    """Backwards compatibility — no repository_class passed."""
+    plugin = PostgresPlugin(settings, table="items")
+    assert plugin._repository_class is PostgresRepository
+
+
+def test_plugin_accepts_custom_repository_class(settings):
+    class CustomRepo(PostgresRepository):
+        pass
+
+    plugin = PostgresPlugin(settings, table="items", repository_class=CustomRepo)
+    assert plugin._repository_class is CustomRepo
+
+
+def test_plugin_rejects_non_repository_class(settings):
+    """repository_class must be a subclass of PostgresRepository — TypeError if not."""
+    with pytest.raises(TypeError, match="subclass of PostgresRepository"):
+        PostgresPlugin(settings, table="items", repository_class=object)  # type: ignore[arg-type]
+
+
+async def test_initialize_constructs_custom_repository_class(
+    settings, plugin_context, mock_pool, mock_settings
+):
+    """
+    REGRESSION: plugin always constructed the base class, silently discarding
+    domain subclass overrides of entity mapping methods.
+    """
+    import openframe.adapters.db.postgres.connection as conn_module
+
+    class CustomRepo(PostgresRepository):
+        marker = True
+
+    conn_module._pool_cache[mock_settings.database_url] = mock_pool
+    mock_pool.fetchval.return_value = 1
+
+    plugin = PostgresPlugin(mock_settings, table="items", repository_class=CustomRepo)
+    await plugin.initialize(plugin_context)
+
+    repo = plugin.get_repository()
+    assert isinstance(repo, CustomRepo)
+    assert hasattr(repo, "marker")
+    conn_module._pool_cache.clear()
+
+
+async def test_get_repository_returns_subclass_not_base_class(
+    settings, plugin_context, mock_pool, mock_settings
+):
+    """type(repo) must be the subclass, not just isinstance-compatible."""
+    import openframe.adapters.db.postgres.connection as conn_module
+
+    class CustomRepo(PostgresRepository):
+        pass
+
+    conn_module._pool_cache[mock_settings.database_url] = mock_pool
+    mock_pool.fetchval.return_value = 1
+
+    plugin = PostgresPlugin(mock_settings, table="items", repository_class=CustomRepo)
+    await plugin.initialize(plugin_context)
+
+    assert type(plugin.get_repository()) is CustomRepo
+    conn_module._pool_cache.clear()