macss-modular-api-postgres 0.4.7__tar.gz

macss_modular_api_postgres-0.4.7/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: macss-modular-api-postgres
+Version: 0.4.7
+Summary: Official MACSS Postgres integration package for Python.
+Author: ccisne.dev
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/macss-dev/modular_api
+Project-URL: Repository, https://github.com/macss-dev/modular_api/tree/main/code/py/modular_api_postgres
+Project-URL: Issues, https://github.com/macss-dev/modular_api/issues
+Project-URL: Documentation, https://github.com/macss-dev/modular_api/tree/main/code/py/modular_api_postgres#readme
+Keywords: macss,postgres,database
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# macss-modular-api-postgres
+
+Official MACSS Postgres integration package for Python.
+
+## Quick start
+
+```python
+from modular_api_postgres import DbClient, DbCommand, DbCommandKind, DbConnectionSettings
+
+settings = DbConnectionSettings.from_environment()
+
+client = DbClient(
+    settings=settings,
+    session_provider=my_session_provider,
+    command_executor=my_command_executor,
+    transaction_runner=my_transaction_runner,
+)
+
+result = client.scalar(
+    DbCommand(
+        kind=DbCommandKind.SCALAR,
+        text="select count(*) from users",
+        label="users.count",
+    )
+)
+
+if result.is_success:
+    print(result.value.value)
+else:
+    print(result.failure.message)
+```
+
+See [example/example.py](example/example.py) for a complete in-memory wiring sample.
+
+## Current slice
+
+- normalized Postgres connection defaults and redacted summaries
+- engine-agnostic `DbClient`, `DbRepository`, and transaction contracts
+- explicit lease ownership semantics for package-owned and application-owned sessions
+- health contributor and GraphQL support bundle for higher-level integrations
+- real driver bindings intentionally remain outside this first slice

macss_modular_api_postgres-0.4.7/README.md

@@ -0,0 +1,41 @@
+# macss-modular-api-postgres
+
+Official MACSS Postgres integration package for Python.
+
+## Quick start
+
+```python
+from modular_api_postgres import DbClient, DbCommand, DbCommandKind, DbConnectionSettings
+
+settings = DbConnectionSettings.from_environment()
+
+client = DbClient(
+    settings=settings,
+    session_provider=my_session_provider,
+    command_executor=my_command_executor,
+    transaction_runner=my_transaction_runner,
+)
+
+result = client.scalar(
+    DbCommand(
+        kind=DbCommandKind.SCALAR,
+        text="select count(*) from users",
+        label="users.count",
+    )
+)
+
+if result.is_success:
+    print(result.value.value)
+else:
+    print(result.failure.message)
+```
+
+See [example/example.py](example/example.py) for a complete in-memory wiring sample.
+
+## Current slice
+
+- normalized Postgres connection defaults and redacted summaries
+- engine-agnostic `DbClient`, `DbRepository`, and transaction contracts
+- explicit lease ownership semantics for package-owned and application-owned sessions
+- health contributor and GraphQL support bundle for higher-level integrations
+- real driver bindings intentionally remain outside this first slice

macss_modular_api_postgres-0.4.7/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "macss-modular-api-postgres"
+version = "0.4.7"
+description = "Official MACSS Postgres integration package for Python."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "ccisne.dev" }]
+keywords = ["macss", "postgres", "database"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/macss-dev/modular_api"
+Repository = "https://github.com/macss-dev/modular_api/tree/main/code/py/modular_api_postgres"
+Issues = "https://github.com/macss-dev/modular_api/issues"
+Documentation = "https://github.com/macss-dev/modular_api/tree/main/code/py/modular_api_postgres#readme"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"

macss_modular_api_postgres-0.4.7/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

macss_modular_api_postgres-0.4.7/src/macss_modular_api_postgres.egg-info/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: macss-modular-api-postgres
+Version: 0.4.7
+Summary: Official MACSS Postgres integration package for Python.
+Author: ccisne.dev
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/macss-dev/modular_api
+Project-URL: Repository, https://github.com/macss-dev/modular_api/tree/main/code/py/modular_api_postgres
+Project-URL: Issues, https://github.com/macss-dev/modular_api/issues
+Project-URL: Documentation, https://github.com/macss-dev/modular_api/tree/main/code/py/modular_api_postgres#readme
+Keywords: macss,postgres,database
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# macss-modular-api-postgres
+
+Official MACSS Postgres integration package for Python.
+
+## Quick start
+
+```python
+from modular_api_postgres import DbClient, DbCommand, DbCommandKind, DbConnectionSettings
+
+settings = DbConnectionSettings.from_environment()
+
+client = DbClient(
+    settings=settings,
+    session_provider=my_session_provider,
+    command_executor=my_command_executor,
+    transaction_runner=my_transaction_runner,
+)
+
+result = client.scalar(
+    DbCommand(
+        kind=DbCommandKind.SCALAR,
+        text="select count(*) from users",
+        label="users.count",
+    )
+)
+
+if result.is_success:
+    print(result.value.value)
+else:
+    print(result.failure.message)
+```
+
+See [example/example.py](example/example.py) for a complete in-memory wiring sample.
+
+## Current slice
+
+- normalized Postgres connection defaults and redacted summaries
+- engine-agnostic `DbClient`, `DbRepository`, and transaction contracts
+- explicit lease ownership semantics for package-owned and application-owned sessions
+- health contributor and GraphQL support bundle for higher-level integrations
+- real driver bindings intentionally remain outside this first slice

macss_modular_api_postgres-0.4.7/src/macss_modular_api_postgres.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/macss_modular_api_postgres.egg-info/PKG-INFO
+src/macss_modular_api_postgres.egg-info/SOURCES.txt
+src/macss_modular_api_postgres.egg-info/dependency_links.txt
+src/macss_modular_api_postgres.egg-info/requires.txt
+src/macss_modular_api_postgres.egg-info/top_level.txt
+src/modular_api_postgres/__init__.py
+src/modular_api_postgres/db_client.py
+tests/test_db_client.py
+tests/test_db_conformance.py

macss_modular_api_postgres-0.4.7/src/macss_modular_api_postgres.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

macss_modular_api_postgres-0.4.7/src/macss_modular_api_postgres.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=8.0

macss_modular_api_postgres-0.4.7/src/macss_modular_api_postgres.egg-info/top_level.txt

@@ -0,0 +1 @@
+modular_api_postgres

macss_modular_api_postgres-0.4.7/src/modular_api_postgres/__init__.py

@@ -0,0 +1,53 @@
+"""Public package exports for modular_api_postgres."""
+
+from .db_client import (
+    DbClient,
+    DbCommand,
+    DbCommandExecutor,
+    DbCommandKind,
+    DbConnectionSettings,
+    DbExecutionMetadata,
+    DbExecutionSummary,
+    DbFailure,
+    DbFailureKind,
+    DbGraphqlSupport,
+    DbHealthContributor,
+    DbHealthReport,
+    DbHealthStatus,
+    DbProviderDescription,
+    DbRepository,
+    DbRepositoryContext,
+    DbResult,
+    DbRowSet,
+    DbScalar,
+    DbSessionLease,
+    DbSessionProvider,
+    DbTransactionContext,
+    DbTransactionRunner,
+)
+
+__all__ = [
+    "DbClient",
+    "DbCommand",
+    "DbCommandExecutor",
+    "DbCommandKind",
+    "DbConnectionSettings",
+    "DbExecutionMetadata",
+    "DbExecutionSummary",
+    "DbFailure",
+    "DbFailureKind",
+    "DbGraphqlSupport",
+    "DbHealthContributor",
+    "DbHealthReport",
+    "DbHealthStatus",
+    "DbProviderDescription",
+    "DbRepository",
+    "DbRepositoryContext",
+    "DbResult",
+    "DbRowSet",
+    "DbScalar",
+    "DbSessionLease",
+    "DbSessionProvider",
+    "DbTransactionContext",
+    "DbTransactionRunner",
+]

macss_modular_api_postgres-0.4.7/src/modular_api_postgres/db_client.py

@@ -0,0 +1,425 @@
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Callable, Generic, Mapping, Protocol, TypeVar, cast
+
+S = TypeVar("S")
+T = TypeVar("T")
+R = TypeVar("R")
+_MISSING = object()
+
+
+class DbCommandKind(str, Enum):
+    QUERY = "query"
+    EXECUTE = "execute"
+    BATCH = "batch"
+    SCALAR = "scalar"
+
+
+class DbFailureKind(str, Enum):
+    CONNECTIVITY = "connectivity"
+    TIMEOUT = "timeout"
+    AUTHENTICATION = "authentication"
+    AUTHORIZATION = "authorization"
+    CONSTRAINT = "constraint"
+    CONFLICT = "conflict"
+    NOT_FOUND = "not_found"
+    SERIALIZATION = "serialization"
+    CANCELLED = "cancelled"
+    UNKNOWN = "unknown"
+
+
+class DbHealthStatus(str, Enum):
+    HEALTHY = "healthy"
+    UNHEALTHY = "unhealthy"
+
+
+@dataclass(frozen=True, slots=True)
+class DbConnectionSettings:
+    host: str
+    port: int
+    database: str
+    username: str
+    password: str
+    ssl_mode: str
+    options: Mapping[str, object] = field(default_factory=dict)
+
+    @classmethod
+    def from_environment(
+        cls,
+        environment: Mapping[str, str] | None = None,
+    ) -> DbConnectionSettings:
+        values = os.environ if environment is None else environment
+        raw_port = values.get("MODULAR_API_POSTGRES_PORT", "")
+
+        try:
+            port = int(raw_port)
+        except ValueError:
+            port = 5432
+
+        return cls(
+            host=values.get("MODULAR_API_POSTGRES_HOST", "127.0.0.1"),
+            port=port,
+            database=values.get("MODULAR_API_POSTGRES_DATABASE", "modular_api_graphql_v1"),
+            username=values.get("MODULAR_API_POSTGRES_USERNAME", "postgres"),
+            password=values.get("MODULAR_API_POSTGRES_PASSWORD", "postgres"),
+            ssl_mode=values.get("MODULAR_API_POSTGRES_SSLMODE", "disable"),
+        )
+
+    @property
+    def engine_id(self) -> str:
+        return "postgres"
+
+    @property
+    def redacted_summary(self) -> str:
+        return (
+            f"{self.engine_id}://{self.username}@{self.host}:{self.port}/"
+            f"{self.database}?sslmode={self.ssl_mode}"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DbCommand:
+    kind: DbCommandKind
+    text: str
+    parameters: tuple[object, ...] = field(default_factory=tuple)
+    label: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DbExecutionMetadata:
+    duration: int
+    command_label: str | None = None
+    row_count: int | None = None
+    affected_count: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DbRowSet:
+    rows: list[Mapping[str, object]]
+    metadata: DbExecutionMetadata
+
+
+@dataclass(frozen=True, slots=True)
+class DbExecutionSummary:
+    affected_count: int
+    metadata: DbExecutionMetadata
+
+
+@dataclass(frozen=True, slots=True)
+class DbScalar(Generic[T]):
+    value: T
+    metadata: DbExecutionMetadata
+
+
+@dataclass(frozen=True, slots=True)
+class DbFailure:
+    kind: DbFailureKind
+    code: str
+    message: str
+    retryable: bool
+    transient: bool
+    details: object | None = None
+    cause_summary: str | None = None
+
+
+class DbResult(Generic[T]):
+    def __init__(self, value: object = _MISSING, failure: DbFailure | None = None) -> None:
+        self._value = value
+        self._failure = failure
+
+    @classmethod
+    def success(cls, value: T) -> DbResult[T]:
+        return cls(value=value)
+
+    @classmethod
+    def from_failure(cls, failure: DbFailure) -> DbResult[T]:
+        return cls(failure=failure)
+
+    @property
+    def is_success(self) -> bool:
+        return self._failure is None
+
+    @property
+    def is_failure(self) -> bool:
+        return self._failure is not None
+
+    @property
+    def value(self) -> T:
+        if self._failure is not None or self._value is _MISSING:
+            raise RuntimeError("DbResult does not contain a success value.")
+        return cast(T, self._value)
+
+    @property
+    def failure(self) -> DbFailure:
+        if self._failure is None:
+            raise RuntimeError("DbResult does not contain a failure value.")
+        return self._failure
+
+    def map(self, transform: Callable[[T], R]) -> DbResult[R]:
+        if self.is_failure:
+            return DbResult.from_failure(self.failure)
+        return DbResult.success(transform(self.value))
+
+    def flat_map(self, transform: Callable[[T], DbResult[R]]) -> DbResult[R]:
+        if self.is_failure:
+            return DbResult.from_failure(self.failure)
+        return transform(self.value)
+
+    def map_failure(self, transform: Callable[[DbFailure], DbFailure]) -> DbResult[T]:
+        if self.is_success:
+            return DbResult.success(self.value)
+        return DbResult.from_failure(transform(self.failure))
+
+    def get_or_throw(self, message: str | None = None) -> T:
+        if self.is_failure:
+            raise RuntimeError(message or self.failure.message)
+        return self.value
+
+
+@dataclass(frozen=True, slots=True)
+class DbProviderDescription:
+    engine_id: str
+    database: str
+    redacted_summary: str
+    owns_resources: bool
+
+
+class DbSessionLease(Generic[S]):
+    def __init__(
+        self,
+        *,
+        session: S,
+        owned_by_package: bool,
+        releaser: Callable[[], DbResult[None]],
+    ) -> None:
+        self.session = session
+        self.owned_by_package = owned_by_package
+        self._releaser = releaser
+
+    def release(self) -> DbResult[None]:
+        if not self.owned_by_package:
+            return DbResult.success(None)
+        return self._releaser()
+
+
+class DbSessionProvider(Protocol[S]):
+    def acquire(self) -> DbResult[DbSessionLease[S]]: ...
+
+    def close(self) -> DbResult[None]: ...
+
+    def describe(self) -> DbProviderDescription: ...
+
+
+class DbCommandExecutor(Protocol[S]):
+    def query(self, session: S, command: DbCommand) -> DbResult[DbRowSet]: ...
+
+    def execute(self, session: S, command: DbCommand) -> DbResult[DbExecutionSummary]: ...
+
+    def scalar(self, session: S, command: DbCommand) -> DbResult[DbScalar[object]]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class DbTransactionContext(Generic[S]):
+    settings: DbConnectionSettings
+    session: S
+    command_executor: DbCommandExecutor[S]
+
+    def query(self, command: DbCommand) -> DbResult[DbRowSet]:
+        return self.command_executor.query(self.session, command)
+
+    def execute(self, command: DbCommand) -> DbResult[DbExecutionSummary]:
+        return self.command_executor.execute(self.session, command)
+
+    def scalar(self, command: DbCommand) -> DbResult[DbScalar[T]]:
+        return cast(DbResult[DbScalar[T]], self.command_executor.scalar(self.session, command))
+
+
+class DbTransactionRunner(Protocol[S]):
+    def run(
+        self,
+        context: DbTransactionContext[S],
+        body: Callable[[DbTransactionContext[S]], DbResult[T]],
+    ) -> DbResult[T]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class DbRepositoryContext(Generic[S]):
+    settings: DbConnectionSettings
+    session_provider: DbSessionProvider[S]
+    command_executor: DbCommandExecutor[S]
+    transaction_runner: DbTransactionRunner[S]
+
+
+class DbRepository(Generic[S]):
+    def __init__(self, context: DbRepositoryContext[S]) -> None:
+        self.context = context
+
+    def query(self, command: DbCommand) -> DbResult[DbRowSet]:
+        return _with_lease(
+            self.context.session_provider,
+            lambda lease: self.context.command_executor.query(lease.session, command),
+        )
+
+    def execute(self, command: DbCommand) -> DbResult[DbExecutionSummary]:
+        return _with_lease(
+            self.context.session_provider,
+            lambda lease: self.context.command_executor.execute(lease.session, command),
+        )
+
+    def scalar(self, command: DbCommand) -> DbResult[DbScalar[T]]:
+        return cast(
+            DbResult[DbScalar[T]],
+            _with_lease(
+                self.context.session_provider,
+                lambda lease: self.context.command_executor.scalar(lease.session, command),
+            ),
+        )
+
+    def transaction(self, body: Callable[[DbTransactionContext[S]], DbResult[T]]) -> DbResult[T]:
+        client = DbClient(
+            settings=self.context.settings,
+            session_provider=self.context.session_provider,
+            command_executor=self.context.command_executor,
+            transaction_runner=self.context.transaction_runner,
+        )
+        return client.transaction(body)
+
+
+class DbClient(Generic[S]):
+    def __init__(
+        self,
+        *,
+        settings: DbConnectionSettings,
+        session_provider: DbSessionProvider[S],
+        command_executor: DbCommandExecutor[S],
+        transaction_runner: DbTransactionRunner[S],
+    ) -> None:
+        self.settings = settings
+        self.session_provider = session_provider
+        self.command_executor = command_executor
+        self.transaction_runner = transaction_runner
+
+    def query(self, command: DbCommand) -> DbResult[DbRowSet]:
+        return _with_lease(
+            self.session_provider,
+            lambda lease: self.command_executor.query(lease.session, command),
+        )
+
+    def execute(self, command: DbCommand) -> DbResult[DbExecutionSummary]:
+        return _with_lease(
+            self.session_provider,
+            lambda lease: self.command_executor.execute(lease.session, command),
+        )
+
+    def scalar(self, command: DbCommand) -> DbResult[DbScalar[T]]:
+        return cast(
+            DbResult[DbScalar[T]],
+            _with_lease(
+                self.session_provider,
+                lambda lease: self.command_executor.scalar(lease.session, command),
+            ),
+        )
+
+    def transaction(self, body: Callable[[DbTransactionContext[S]], DbResult[T]]) -> DbResult[T]:
+        lease_result = self.session_provider.acquire()
+        if lease_result.is_failure:
+            return DbResult.from_failure(lease_result.failure)
+
+        lease = lease_result.value
+        context = DbTransactionContext(
+            settings=self.settings,
+            session=lease.session,
+            command_executor=self.command_executor,
+        )
+        result = self.transaction_runner.run(context, body)
+        release_result = lease.release()
+
+        if result.is_failure:
+            return DbResult.from_failure(result.failure)
+        if release_result.is_failure:
+            return DbResult.from_failure(release_result.failure)
+        return result
+
+    def repository_context(self) -> DbRepositoryContext[S]:
+        return DbRepositoryContext(
+            settings=self.settings,
+            session_provider=self.session_provider,
+            command_executor=self.command_executor,
+            transaction_runner=self.transaction_runner,
+        )
+
+    def close(self) -> DbResult[None]:
+        return self.session_provider.close()
+
+    def describe(self) -> DbProviderDescription:
+        return self.session_provider.describe()
+
+
+@dataclass(frozen=True, slots=True)
+class DbHealthReport:
+    status: DbHealthStatus
+    response_time: int
+    redacted_summary: str
+    details: str | None = None
+
+
+class DbHealthContributor(Generic[S]):
+    def __init__(self, *, client: DbClient[S], probe_command: DbCommand | None = None) -> None:
+        self.client = client
+        self.probe_command = probe_command or DbCommand(
+            kind=DbCommandKind.SCALAR,
+            text="SELECT 1",
+            label="db.health",
+        )
+
+    def probe(self) -> DbHealthReport:
+        started_at = time.monotonic()
+        result = self.client.scalar(self.probe_command)
+        response_time = int((time.monotonic() - started_at) * 1000)
+
+        if result.is_success:
+            return DbHealthReport(
+                status=DbHealthStatus.HEALTHY,
+                response_time=response_time,
+                redacted_summary=self.client.describe().redacted_summary,
+            )
+
+        return DbHealthReport(
+            status=DbHealthStatus.UNHEALTHY,
+            response_time=response_time,
+            redacted_summary=self.client.describe().redacted_summary,
+            details=result.failure.code,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DbGraphqlSupport(Generic[S]):
+    catalog_provider: object
+    read_executor: object
+    health_contributor: DbHealthContributor[S]
+    source_digest_factory: object | None = None
+    artifact_loader: object | None = None
+    capability_registration: object | None = None
+
+
+def _with_lease(
+    session_provider: DbSessionProvider[S],
+    operation: Callable[[DbSessionLease[S]], DbResult[T]],
+) -> DbResult[T]:
+    lease_result = session_provider.acquire()
+    if lease_result.is_failure:
+        return DbResult.from_failure(lease_result.failure)
+
+    lease = lease_result.value
+    operation_result = operation(lease)
+    release_result = lease.release()
+
+    if operation_result.is_failure:
+        return DbResult.from_failure(operation_result.failure)
+    if release_result.is_failure:
+        return DbResult.from_failure(release_result.failure)
+    return operation_result

macss_modular_api_postgres-0.4.7/tests/test_db_client.py

@@ -0,0 +1,478 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pytest
+
+from modular_api_postgres import (
+    DbClient,
+    DbCommand,
+    DbCommandKind,
+    DbConnectionSettings,
+    DbExecutionMetadata,
+    DbExecutionSummary,
+    DbFailure,
+    DbFailureKind,
+    DbGraphqlSupport,
+    DbHealthContributor,
+    DbHealthStatus,
+    DbProviderDescription,
+    DbRepository,
+    DbRepositoryContext,
+    DbResult,
+    DbRowSet,
+    DbScalar,
+    DbSessionLease,
+    DbTransactionContext,
+)
+
+
+def test_connection_settings_normalizes_environment_defaults_and_redacts_secrets() -> None:
+    settings = DbConnectionSettings.from_environment(
+        {
+            "MODULAR_API_POSTGRES_HOST": "db.local",
+            "MODULAR_API_POSTGRES_PASSWORD": "super-secret",
+        }
+    )
+
+    assert settings.engine_id == "postgres"
+    assert settings.host == "db.local"
+    assert settings.port == 5432
+    assert settings.database == "modular_api_graphql_v1"
+    assert settings.username == "postgres"
+    assert settings.password == "super-secret"
+    assert settings.ssl_mode == "disable"
+    assert "db.local:5432" in settings.redacted_summary
+    assert "postgres@" in settings.redacted_summary
+    assert "sslmode=disable" in settings.redacted_summary
+    assert "super-secret" not in settings.redacted_summary
+
+
+def test_db_result_supports_map_flat_map_map_failure_and_get_or_throw() -> None:
+    success = DbResult.success(21)
+    failure = DbResult.from_failure(
+        DbFailure(
+            kind=DbFailureKind.TIMEOUT,
+            code="timeout",
+            message="Timed out",
+            retryable=True,
+            transient=True,
+        )
+    )
+
+    assert success.map(lambda value: value * 2).value == 42
+    assert success.flat_map(lambda value: DbResult.success(value + 1)).value == 22
+
+    mapped_failure = failure.map_failure(
+        lambda current: DbFailure(
+            kind=current.kind,
+            code="wrapped_timeout",
+            message=current.message,
+            retryable=current.retryable,
+            transient=current.transient,
+        )
+    )
+
+    assert mapped_failure.failure.code == "wrapped_timeout"
+    assert success.get_or_throw() == 21
+    with pytest.raises(RuntimeError):
+        failure.get_or_throw()
+
+
+def test_client_delegates_query_calls_and_releases_package_owned_leases() -> None:
+    settings = DbConnectionSettings.from_environment()
+    provider = _FakeSessionProvider(settings, session="db-session")
+    executor = _FakeCommandExecutor(
+        row_set=DbRowSet(
+            rows=[{"id": 1}],
+            metadata=DbExecutionMetadata(
+                duration=3,
+                command_label="users.list",
+                row_count=1,
+            ),
+        )
+    )
+    client = DbClient(
+        settings=settings,
+        session_provider=provider,
+        command_executor=executor,
+        transaction_runner=_FakeTransactionRunner(),
+    )
+
+    result = client.query(
+        DbCommand(
+            kind=DbCommandKind.QUERY,
+            text="select id from users",
+            label="users.list",
+        )
+    )
+
+    assert result.is_success is True
+    assert result.value.rows == [{"id": 1}]
+    assert result.value.metadata.row_count == 1
+    assert provider.acquire_count == 1
+    assert provider.release_count == 1
+    assert executor.last_session == "db-session"
+    assert executor.last_command.label == "users.list"
+
+
+def test_client_returns_a_failure_when_session_acquisition_fails() -> None:
+    settings = DbConnectionSettings.from_environment()
+    provider = _FakeSessionProvider(
+        settings,
+        acquire_failure=DbFailure(
+            kind=DbFailureKind.CONNECTIVITY,
+            code="connect_failed",
+            message="Could not connect",
+            retryable=True,
+            transient=True,
+        ),
+    )
+    client = DbClient(
+        settings=settings,
+        session_provider=provider,
+        command_executor=_FakeCommandExecutor(),
+        transaction_runner=_FakeTransactionRunner(),
+    )
+
+    result = client.query(DbCommand(kind=DbCommandKind.QUERY, text="select 1"))
+
+    assert result.is_failure is True
+    assert result.failure.code == "connect_failed"
+
+
+def test_client_returns_a_failure_when_releasing_a_package_owned_lease_fails() -> None:
+    settings = DbConnectionSettings.from_environment()
+    provider = _FakeSessionProvider(
+        settings,
+        release_failure=DbFailure(
+            kind=DbFailureKind.UNKNOWN,
+            code="release_failed",
+            message="Release failed",
+            retryable=False,
+            transient=False,
+        ),
+    )
+    client = DbClient(
+        settings=settings,
+        session_provider=provider,
+        command_executor=_FakeCommandExecutor(),
+        transaction_runner=_FakeTransactionRunner(),
+    )
+
+    result = client.query(DbCommand(kind=DbCommandKind.QUERY, text="select 1"))
+
+    assert result.is_failure is True
+    assert result.failure.code == "release_failed"
+
+
+def test_client_does_not_release_application_owned_leases() -> None:
+    settings = DbConnectionSettings.from_environment()
+    provider = _FakeSessionProvider(settings, owned_by_package=False)
+    executor = _FakeCommandExecutor(
+        execution_summary=DbExecutionSummary(
+            affected_count=1,
+            metadata=DbExecutionMetadata(
+                duration=2,
+                command_label="users.touch",
+                affected_count=1,
+            ),
+        )
+    )
+    client = DbClient(
+        settings=settings,
+        session_provider=provider,
+        command_executor=executor,
+        transaction_runner=_FakeTransactionRunner(),
+    )
+
+    result = client.execute(
+        DbCommand(
+            kind=DbCommandKind.EXECUTE,
+            text="update users set touched = true",
+            label="users.touch",
+        )
+    )
+
+    assert result.is_success is True
+    assert result.value.affected_count == 1
+    assert provider.release_count == 0
+
+
+def test_client_commits_successful_transactions_and_rolls_back_failed_ones() -> None:
+    settings = DbConnectionSettings.from_environment()
+    provider = _FakeSessionProvider(settings)
+    executor = _FakeCommandExecutor(scalar_value=7)
+    runner = _FakeTransactionRunner()
+    client = DbClient(
+        settings=settings,
+        session_provider=provider,
+        command_executor=executor,
+        transaction_runner=runner,
+    )
+
+    success = client.transaction(
+        lambda transaction: transaction.scalar(
+            DbCommand(
+                kind=DbCommandKind.SCALAR,
+                text="select count(*) from users",
+                label="users.count",
+            )
+        ).map(lambda value: value.value)
+    )
+    failure = client.transaction(
+        lambda _transaction: DbResult.from_failure(
+            DbFailure(
+                kind=DbFailureKind.CONFLICT,
+                code="duplicate_key",
+                message="Duplicate key",
+                retryable=False,
+                transient=False,
+            )
+        )
+    )
+
+    assert success.is_success is True
+    assert success.value == 7
+    assert failure.is_failure is True
+    assert failure.failure.code == "duplicate_key"
+    assert runner.commit_count == 1
+    assert runner.rollback_count == 1
+    assert provider.release_count == 2
+
+
+def test_client_describes_its_provider_and_closes_cleanly() -> None:
+    settings = DbConnectionSettings.from_environment()
+    provider = _FakeSessionProvider(settings)
+    client = DbClient(
+        settings=settings,
+        session_provider=provider,
+        command_executor=_FakeCommandExecutor(),
+        transaction_runner=_FakeTransactionRunner(),
+    )
+
+    assert client.describe().engine_id == "postgres"
+    assert client.describe().database == settings.database
+
+    closed = client.close()
+
+    assert closed.is_success is True
+    assert provider.close_count == 1
+
+
+def test_client_propagates_provider_close_failures() -> None:
+    settings = DbConnectionSettings.from_environment()
+    provider = _FakeSessionProvider(
+        settings,
+        close_failure=DbFailure(
+            kind=DbFailureKind.UNKNOWN,
+            code="close_failed",
+            message="Close failed",
+            retryable=False,
+            transient=False,
+        ),
+    )
+    client = DbClient(
+        settings=settings,
+        session_provider=provider,
+        command_executor=_FakeCommandExecutor(),
+        transaction_runner=_FakeTransactionRunner(),
+    )
+
+    closed = client.close()
+
+    assert closed.is_failure is True
+    assert closed.failure.code == "close_failed"
+
+
+def test_repository_helpers_stay_thin_over_the_shared_context() -> None:
+    settings = DbConnectionSettings.from_environment()
+    provider = _FakeSessionProvider(settings)
+    executor = _FakeCommandExecutor(scalar_value=9)
+    context = DbRepositoryContext(
+        settings=settings,
+        session_provider=provider,
+        command_executor=executor,
+        transaction_runner=_FakeTransactionRunner(),
+    )
+    repository = _UserStatsRepository(context)
+
+    result = repository.total_users()
+
+    assert result.is_success is True
+    assert result.value == 9
+    assert executor.last_command.label == "users.count"
+
+
+def test_health_probe_reports_healthy_and_graphql_support_bundles_dependencies() -> None:
+    settings = DbConnectionSettings.from_environment()
+    provider = _FakeSessionProvider(settings)
+    executor = _FakeCommandExecutor(scalar_value=1)
+    client = DbClient(
+        settings=settings,
+        session_provider=provider,
+        command_executor=executor,
+        transaction_runner=_FakeTransactionRunner(),
+    )
+    health_contributor = DbHealthContributor(client=client)
+    support = DbGraphqlSupport(
+        catalog_provider="catalog-provider",
+        read_executor="read-executor",
+        health_contributor=health_contributor,
+    )
+
+    report = health_contributor.probe()
+
+    assert report.status is DbHealthStatus.HEALTHY
+    assert report.redacted_summary == settings.redacted_summary
+    assert report.response_time >= 0
+    assert support.catalog_provider == "catalog-provider"
+    assert support.read_executor == "read-executor"
+    assert support.health_contributor is health_contributor
+
+
+def test_health_probe_reports_unhealthy_when_scalar_execution_fails() -> None:
+    settings = DbConnectionSettings.from_environment()
+    provider = _FakeSessionProvider(settings)
+    executor = _FakeCommandExecutor(
+        failure=DbFailure(
+            kind=DbFailureKind.TIMEOUT,
+            code="timeout",
+            message="Timed out",
+            retryable=True,
+            transient=True,
+        )
+    )
+    client = DbClient(
+        settings=settings,
+        session_provider=provider,
+        command_executor=executor,
+        transaction_runner=_FakeTransactionRunner(),
+    )
+    health_contributor = DbHealthContributor(client=client)
+
+    report = health_contributor.probe()
+
+    assert report.status is DbHealthStatus.UNHEALTHY
+    assert report.details == "timeout"
+
+
+@dataclass(slots=True)
+class _FakeSessionProvider:
+    settings: DbConnectionSettings
+    session: str = "session-1"
+    owned_by_package: bool = True
+    acquire_failure: DbFailure | None = None
+    release_failure: DbFailure | None = None
+    close_failure: DbFailure | None = None
+    acquire_count: int = 0
+    release_count: int = 0
+    close_count: int = 0
+
+    def acquire(self) -> DbResult[DbSessionLease[str]]:
+        self.acquire_count += 1
+        if self.acquire_failure is not None:
+            return DbResult.from_failure(self.acquire_failure)
+
+        return DbResult.success(
+            DbSessionLease(
+                session=self.session,
+                owned_by_package=self.owned_by_package,
+                releaser=self._release,
+            )
+        )
+
+    def close(self) -> DbResult[None]:
+        self.close_count += 1
+        if self.close_failure is not None:
+            return DbResult.from_failure(self.close_failure)
+        return DbResult.success(None)
+
+    def describe(self) -> DbProviderDescription:
+        return DbProviderDescription(
+            engine_id=self.settings.engine_id,
+            database=self.settings.database,
+            redacted_summary=self.settings.redacted_summary,
+            owns_resources=self.owned_by_package,
+        )
+
+    def _release(self) -> DbResult[None]:
+        self.release_count += 1
+        if self.release_failure is not None:
+            return DbResult.from_failure(self.release_failure)
+        return DbResult.success(None)
+
+
+@dataclass(slots=True)
+class _FakeCommandExecutor:
+    row_set: DbRowSet = DbRowSet(
+        rows=[],
+        metadata=DbExecutionMetadata(duration=0),
+    )
+    execution_summary: DbExecutionSummary = DbExecutionSummary(
+        affected_count=0,
+        metadata=DbExecutionMetadata(duration=0),
+    )
+    scalar_value: object | None = None
+    failure: DbFailure | None = None
+    last_session: str | None = None
+    last_command: DbCommand | None = None
+
+    def query(self, session: str, command: DbCommand) -> DbResult[DbRowSet]:
+        self.last_session = session
+        self.last_command = command
+        if self.failure is not None:
+            return DbResult.from_failure(self.failure)
+        return DbResult.success(self.row_set)
+
+    def execute(self, session: str, command: DbCommand) -> DbResult[DbExecutionSummary]:
+        self.last_session = session
+        self.last_command = command
+        if self.failure is not None:
+            return DbResult.from_failure(self.failure)
+        return DbResult.success(self.execution_summary)
+
+    def scalar(self, session: str, command: DbCommand) -> DbResult[DbScalar[object]]:
+        self.last_session = session
+        self.last_command = command
+        if self.failure is not None:
+            return DbResult.from_failure(self.failure)
+        return DbResult.success(
+            DbScalar(
+                value=self.scalar_value,
+                metadata=DbExecutionMetadata(
+                    duration=0,
+                    command_label=command.label,
+                ),
+            )
+        )
+
+
+@dataclass(slots=True)
+class _FakeTransactionRunner:
+    commit_count: int = 0
+    rollback_count: int = 0
+
+    def run(
+        self,
+        context: DbTransactionContext[str],
+        body: callable,
+    ) -> DbResult[object]:
+        result = body(context)
+        if result.is_success:
+            self.commit_count += 1
+        else:
+            self.rollback_count += 1
+        return result
+
+
+class _UserStatsRepository(DbRepository[str]):
+    def total_users(self) -> DbResult[int]:
+        result = self.scalar(
+            DbCommand(
+                kind=DbCommandKind.SCALAR,
+                text="select count(*) from users",
+                label="users.count",
+            )
+        )
+        return result.map(lambda value: int(value.value))

macss_modular_api_postgres-0.4.7/tests/test_db_conformance.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from modular_api_postgres import DbConnectionSettings, DbFailure, DbFailureKind, DbResult
+
+
+def _load_fixture() -> dict[str, object]:
+    return json.loads(
+        (Path(__file__).resolve().parents[3] / "tests" / "fixtures" / "db_client" / "postgres.json").read_text(
+            encoding="utf-8"
+        )
+    )
+
+
+def test_matches_the_shared_postgres_connection_fixture() -> None:
+    fixture = _load_fixture()
+    connection = fixture["connection"]
+    expected = connection["expected"]
+
+    settings = DbConnectionSettings.from_environment(connection["environment"])
+
+    assert settings.engine_id == expected["engineId"]
+    assert settings.host == expected["host"]
+    assert settings.port == expected["port"]
+    assert settings.database == expected["database"]
+    assert settings.username == expected["username"]
+    assert settings.password == expected["password"]
+    assert settings.ssl_mode == expected["sslMode"]
+
+    for fragment in connection["redactedContains"]:
+        assert fragment in settings.redacted_summary
+    for fragment in connection["redactedExcludes"]:
+        assert fragment not in settings.redacted_summary
+
+
+def test_matches_the_shared_db_result_fixture() -> None:
+    fixture = _load_fixture()
+    result_fixture = fixture["result"]
+
+    success = DbResult.success(result_fixture["successValue"])
+    failure = DbResult.from_failure(
+        DbFailure(
+            kind=DbFailureKind.TIMEOUT,
+            code=result_fixture["timeoutCode"],
+            message="Timed out",
+            retryable=True,
+            transient=True,
+        )
+    )
+
+    assert success.map(lambda value: value * 2).value == result_fixture["mappedValue"]
+    assert success.flat_map(lambda value: DbResult.success(value + 1)).value == result_fixture[
+        "flatMappedValue"
+    ]
+
+    mapped_failure = failure.map_failure(
+        lambda current: DbFailure(
+            kind=current.kind,
+            code=result_fixture["wrappedFailureCode"],
+            message=current.message,
+            retryable=current.retryable,
+            transient=current.transient,
+        )
+    )
+
+    assert mapped_failure.failure.code == result_fixture["wrappedFailureCode"]