sqlalchemy-foundation-kit 0.0.0__py3-none-any.whl

sqlalchemy_foundation_kit/contrib/dependency_injector/metrics.py

@@ -0,0 +1,85 @@
+"""Metrics containers for dependency-injector."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from ...protocols import PostgresMetricsProtocol
+from .._metrics_utils import _infra_metrics_prefix
+from ._base import BaseDIContainer
+from ._deps import providers
+
+
+@runtime_checkable
+class PrometheusMetricsSettingsProtocol(Protocol):
+    """Protocol for general prometheus metrics settings."""
+
+    @property
+    def prefix(self) -> str | None:
+        """Metric prefix."""
+        ...
+
+    @property
+    def enabled(self) -> bool:
+        """Whether metrics are enabled."""
+        ...
+
+
+@runtime_checkable
+class PostgresMetricsSettingsProtocol(Protocol):
+    """Protocol for Postgres settings that have metrics_enabled flag."""
+
+    @property
+    def metrics_enabled(self) -> bool:
+        """Whether infrastructure metrics are enabled."""
+        ...
+
+
+try:
+    from ...contrib.metrics import PostgresMetrics
+
+    def _create_postgres_metrics(
+        metrics_settings: PrometheusMetricsSettingsProtocol,
+        default_prefix: str | None,
+        postgres_settings: PostgresMetricsSettingsProtocol | None,
+    ) -> PostgresMetricsProtocol | None:
+        """Create Postgres metrics if enabled."""
+        if postgres_settings is None or not postgres_settings.metrics_enabled:
+            return None
+        return PostgresMetrics(prefix=_infra_metrics_prefix(default_prefix))
+
+    class PrometheusMetricsContainer(BaseDIContainer):
+        """Container for Prometheus PostgreSQL metrics.
+
+        Provides:
+        - postgres_metrics: PostgreSQL metrics collector implementing PostgresMetricsProtocol.
+
+        Configuration:
+            - metrics_settings: General prometheus metrics settings (PrometheusMetricsSettingsProtocol).
+            - default_prefix: Default prefix for infrastructure metrics (str | None).
+            - postgres_settings: PostgreSQL settings with metrics_enabled flag (PostgresMetricsSettingsProtocol).
+        """
+
+        # Configuration
+        metrics_settings = providers.Dependency()  # type: ignore[misc,var-annotated]
+        default_prefix = providers.Dependency()  # type: ignore[misc,var-annotated]
+        postgres_settings = providers.Dependency(default=None)  # type: ignore[misc,var-annotated]
+
+        # Postgres metrics
+        postgres_metrics = providers.Singleton(  # type: ignore[misc,var-annotated]
+            _create_postgres_metrics,
+            metrics_settings=metrics_settings,
+            default_prefix=default_prefix,
+            postgres_settings=postgres_settings,
+        )
+
+except ImportError:  # pragma: no cover
+    PrometheusMetricsContainer = None  # type: ignore[misc,assignment]
+    _create_postgres_metrics = None  # type: ignore[misc,assignment]
+
+
+__all__ = [
+    "PostgresMetricsSettingsProtocol",
+    "PrometheusMetricsContainer",
+    "PrometheusMetricsSettingsProtocol",
+]

sqlalchemy_foundation_kit/contrib/di/__init__.py

@@ -0,0 +1,21 @@
+"""Dishka dependency injection providers."""
+
+from __future__ import annotations
+
+from ._base import BaseDishkaProvider
+from .database import (
+    AsyncDatabaseProvider,
+    AsyncUnitOfWorkProvider,
+    RetryConfig,
+    retry_async_connection,
+)
+from .metrics import PrometheusPostgresMetricsProvider
+
+__all__ = [
+    "AsyncDatabaseProvider",
+    "AsyncUnitOfWorkProvider",
+    "BaseDishkaProvider",
+    "PrometheusPostgresMetricsProvider",
+    "RetryConfig",
+    "retry_async_connection",
+]

sqlalchemy_foundation_kit/contrib/di/_base.py

@@ -0,0 +1,27 @@
+"""Base Dishka provider with automatic dependency checking."""
+
+from __future__ import annotations
+
+from ._deps import Provider, check_dishka
+
+
+class BaseDishkaProvider(Provider):
+    """Base provider that checks dishka availability on subclass creation.
+
+    All Dishka providers should inherit from this class instead of directly
+    from dishka.Provider. This ensures consistent error messages when dishka
+    is not installed.
+    """
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        """Check dishka availability when creating a subclass."""
+        super().__init_subclass__(**kwargs)
+        check_dishka()
+
+    def __init__(self) -> None:
+        """Check dishka availability when instantiating."""
+        check_dishka()
+        super().__init__()
+
+
+__all__ = ["BaseDishkaProvider"]

sqlalchemy_foundation_kit/contrib/di/_deps.py

@@ -0,0 +1,32 @@
+"""Shared dishka dependency helpers.
+
+Centralizes the dishka import boilerplate and availability check so each
+provider module doesn't have to repeat it.
+"""
+
+from __future__ import annotations
+
+try:
+    from dishka import Provider, Scope, provide
+
+    HAS_DISHKA = True
+except ImportError:
+    HAS_DISHKA = False
+    Provider = object  # type: ignore[misc,assignment]
+    Scope = None  # type: ignore[misc,assignment]
+    provide = None  # type: ignore[misc,assignment]
+
+
+def check_dishka() -> None:
+    """Raise ImportError if dishka is not installed.
+
+    Raises:
+        ImportError: If dishka is not available.
+    """
+    if not HAS_DISHKA:
+        raise ImportError(
+            "dishka is required for providers. Install it with: pip install 'sqlalchemy-foundation-kit[dishka]'"
+        )
+
+
+__all__ = ["HAS_DISHKA", "Provider", "Scope", "check_dishka", "provide"]

sqlalchemy_foundation_kit/contrib/di/database.py

@@ -0,0 +1,169 @@
+"""Database providers for dishka."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+
+from sqlalchemy import text
+from sqlalchemy.exc import SQLAlchemyError
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from ...config import PostgresSettingsProtocol
+from ...protocols import PostgresMetricsProtocol
+from ...session import (
+    DEFAULT_HEALTHCHECK_QUERY,
+    DEFAULT_RETRY_CONFIG,
+    AsyncSessionManager,
+    RetryConfig,
+    create_async_session_manager,
+    retry_async_connection,
+)
+from ...uow import (
+    AsyncSQLAlchemyUnitOfWork,
+    AsyncSQLAlchemyUowTransaction,
+    AsyncUnitOfWork,
+)
+from ._base import BaseDishkaProvider
+from ._deps import Scope, provide
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncDatabaseProvider(BaseDishkaProvider):
+    """Provider for database dependencies.
+
+    Provides:
+        - ``AsyncSessionManager``: Manages database connections and engine lifecycle.
+        - ``async_sessionmaker[AsyncSession]``: Factory for creating database sessions.
+
+    Note: ``PostgresMetricsProtocol`` must be provided by a separate provider
+    (e.g., :class:`PrometheusPostgresMetricsProvider`) or registered in the container.
+    If you don't want metrics, simply don't register such a provider.
+
+    Customization:
+        - Pass ``healthcheck_query=None`` to skip the startup connectivity check.
+        - Pass a custom :class:`RetryConfig` to tune startup retry behaviour.
+        - Subclass and override :meth:`create_session_manager` to fully customize
+          how the manager is constructed (e.g., to pass ``extra_server_settings``,
+          ``connection_class``, or ``on_engine_created``).
+    """
+
+    scope = Scope.APP
+
+    def __init__(
+        self,
+        healthcheck_query: str | None = DEFAULT_HEALTHCHECK_QUERY,
+        retry_config: RetryConfig = DEFAULT_RETRY_CONFIG,
+    ) -> None:
+        """Initialize provider.
+
+        Args:
+            healthcheck_query: SQL executed at startup to verify connectivity.
+                Pass ``None`` to skip the healthcheck entirely.
+            retry_config: Retry behavior for the startup healthcheck.
+        """
+        super().__init__()
+        self._healthcheck_query = healthcheck_query
+        self._retry_config = retry_config
+
+    def create_session_manager(
+        self,
+        postgres_config: PostgresSettingsProtocol,
+        metrics: PostgresMetricsProtocol | None,
+    ) -> AsyncSessionManager[AsyncSession]:
+        """Build an ``AsyncSessionManager`` for the given config.
+
+        Override this hook to customize session manager construction — for example,
+        to pass ``extra_server_settings``, a custom ``connection_class``, or an
+        ``on_engine_created`` callback for OpenTelemetry instrumentation.
+
+        Args:
+            postgres_config: PostgreSQL configuration.
+            metrics: Optional metrics collector.
+
+        Returns:
+            Configured ``AsyncSessionManager``.
+        """
+        return create_async_session_manager(postgres_config, metrics=metrics)
+
+    @provide
+    async def get_session_manager(
+        self,
+        postgres_config: PostgresSettingsProtocol,
+        metrics: PostgresMetricsProtocol | None = None,
+    ) -> AsyncIterator[AsyncSessionManager[AsyncSession]]:
+        """Provide database session manager."""
+        manager = self.create_session_manager(postgres_config, metrics)
+
+        if self._healthcheck_query is not None:
+            query = self._healthcheck_query
+
+            async def test_connection() -> None:
+                async with manager.session_maker() as session:
+                    await session.execute(text(query))
+
+            await retry_async_connection(
+                connect_func=test_connection,
+                service_name="PostgreSQL",
+                config=self._retry_config,
+            )
+
+        try:
+            yield manager
+        finally:
+            try:
+                await manager.aclose()
+                logger.info("Database session manager closed successfully")
+            except SQLAlchemyError as e:
+                logger.warning("Error closing database session manager: %s", e)
+
+    @provide
+    def get_session_maker(self, session_manager: AsyncSessionManager[AsyncSession]) -> async_sessionmaker[AsyncSession]:
+        """Provide session maker."""
+        return session_manager.session_maker  # type: ignore[no-any-return]
+
+
+class AsyncUnitOfWorkProvider(BaseDishkaProvider):
+    """Provider for Unit of Work.
+
+    Provides:
+        - ``AsyncUnitOfWork``: Standardized interface for database transactions.
+
+    Note: UoW is APP-scoped because it's stateless — it only holds a reference to
+    ``session_maker`` (factory). Real database connections are created only when calling
+    ``uow.transaction()``, and are properly closed after the context manager exits.
+
+    Customization:
+        Override :meth:`create_uow` to use a custom transaction class
+        (e.g., one that exposes domain repositories as lazy properties).
+    """
+
+    scope = Scope.APP
+
+    def create_uow(
+        self,
+        session_maker: async_sessionmaker[AsyncSession],
+    ) -> AsyncUnitOfWork[AsyncSQLAlchemyUowTransaction]:
+        """Construct the UoW instance. Override to inject a custom transaction class."""
+        return AsyncSQLAlchemyUnitOfWork(session_maker, transaction_factory=AsyncSQLAlchemyUowTransaction)
+
+    @provide
+    def get_uow(
+        self,
+        session_maker: async_sessionmaker[AsyncSession],
+    ) -> AsyncUnitOfWork[AsyncSQLAlchemyUowTransaction]:
+        """Provide Unit of Work.
+
+        Returns a stateless UoW instance that can be safely reused.
+        Each call to ``uow.transaction()`` creates a new database session/connection.
+        """
+        return self.create_uow(session_maker)
+
+
+__all__ = [
+    "AsyncDatabaseProvider",
+    "AsyncUnitOfWorkProvider",
+    "RetryConfig",
+    "retry_async_connection",
+]

sqlalchemy_foundation_kit/contrib/di/metrics.py

@@ -0,0 +1,71 @@
+"""Metrics providers for dishka."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from ...protocols import PostgresMetricsProtocol
+from .._metrics_utils import _infra_metrics_prefix
+from ._base import BaseDishkaProvider
+from ._deps import Scope, provide
+
+
+@runtime_checkable
+class PrometheusMetricsSettingsProtocol(Protocol):
+    """Protocol for general prometheus metrics settings."""
+
+    @property
+    def prefix(self) -> str | None:
+        """Metric prefix."""
+        ...
+
+    @property
+    def enabled(self) -> bool:
+        """Whether metrics are enabled."""
+        ...
+
+
+@runtime_checkable
+class PostgresMetricsSettingsProtocol(Protocol):
+    """Protocol for Postgres settings that have metrics_enabled flag."""
+
+    @property
+    def metrics_enabled(self) -> bool:
+        """Whether infrastructure metrics are enabled."""
+        ...
+
+
+class BaseMetricsProvider(BaseDishkaProvider):
+    """Base provider for metrics with helper for optional infra name prefix."""
+
+    scope = Scope.APP
+
+
+try:
+    from ...contrib.metrics import PostgresMetrics
+
+    class PrometheusPostgresMetricsProvider(BaseMetricsProvider):
+        """Provider for Prometheus PostgreSQL metrics."""
+
+        @provide
+        def get_metrics(
+            self,
+            metrics: PrometheusMetricsSettingsProtocol,
+            default_prefix: str | None,
+            postgres: PostgresMetricsSettingsProtocol | None = None,
+        ) -> PostgresMetricsProtocol | None:
+            """Provide Postgres metrics implementing PostgresMetricsProtocol."""
+            if postgres is None or not postgres.metrics_enabled:
+                return None
+            return PostgresMetrics(prefix=_infra_metrics_prefix(default_prefix))
+
+except ImportError:  # pragma: no cover
+    PrometheusPostgresMetricsProvider = None  # type: ignore[misc,assignment]
+
+
+__all__ = [
+    "BaseMetricsProvider",
+    "PostgresMetricsSettingsProtocol",
+    "PrometheusMetricsSettingsProtocol",
+    "PrometheusPostgresMetricsProvider",
+]

sqlalchemy_foundation_kit/contrib/metrics/__init__.py

@@ -0,0 +1,7 @@
+"""Prometheus metrics integration."""
+
+from __future__ import annotations
+
+from .postgres import PostgresMetrics
+
+__all__ = ["PostgresMetrics"]

sqlalchemy_foundation_kit/contrib/metrics/postgres.py

@@ -0,0 +1,149 @@
+"""Postgres metrics using prometheus-client."""
+
+from __future__ import annotations
+
+import re
+
+try:
+    from prometheus_client import Counter, Gauge, Histogram
+
+    HAS_PROMETHEUS = True
+except ImportError:
+    HAS_PROMETHEUS = False
+
+# Default buckets for connection checkout duration (seconds)
+CONNECTION_CHECKOUT_BUCKETS: tuple[float, ...] = (
+    0.001,
+    0.005,
+    0.01,
+    0.025,
+    0.05,
+    0.1,
+    0.25,
+    0.5,
+    1.0,
+    2.5,
+    5.0,
+)
+
+
+def _check_prometheus() -> None:
+    """Check if prometheus-client is installed."""
+    if not HAS_PROMETHEUS:
+        raise ImportError(
+            "prometheus-client is required for PostgresMetrics. "
+            "Install it with: pip install 'sqlalchemy-foundation-kit[metrics]'"
+        )
+
+
+class PostgresMetrics:
+    """Postgres connection pool metrics.
+
+    Metrics:
+        - postgres_db_pool_size: Current database connection pool size.
+        - postgres_db_pool_checked_out: Number of connections currently checked out.
+        - postgres_db_pool_overflow: Number of connections over pool_size (within max_overflow).
+        - postgres_db_connection_checkout_duration_seconds: Time to acquire connection from pool.
+        - postgres_db_connection_timeouts_total: Number of connection checkout timeouts.
+        - postgres_db_connection_errors_total: Number of connection errors.
+
+    Labels:
+        - error_type: Type of connection error (for errors_total).
+    """
+
+    def __init__(self, prefix: str | None = None) -> None:
+        """Initialize postgres metrics.
+
+        Args:
+            prefix: Metric name prefix.
+
+        Raises:
+            ImportError: If prometheus-client is not installed.
+        """
+        _check_prometheus()
+
+        self.pool_size = Gauge(
+            _make_metric_name("postgres_db_pool_size", prefix),
+            "Current database connection pool size",
+        )
+        self.pool_checked_out = Gauge(
+            _make_metric_name("postgres_db_pool_checked_out", prefix),
+            "Number of database connections currently checked out",
+        )
+        self.pool_overflow = Gauge(
+            _make_metric_name("postgres_db_pool_overflow", prefix),
+            "Number of connections over pool_size (within max_overflow)",
+        )
+        self.connection_checkout_duration = Histogram(
+            _make_metric_name("postgres_db_connection_checkout_duration_seconds", prefix),
+            "Time to acquire connection from pool",
+            buckets=list(CONNECTION_CHECKOUT_BUCKETS),
+        )
+        self.connection_timeouts_total = Counter(
+            _make_metric_name("postgres_db_connection_timeouts_total", prefix),
+            "Number of connection checkout timeouts",
+        )
+        self.connection_errors_total = Counter(
+            _make_metric_name("postgres_db_connection_errors_total", prefix),
+            "Number of connection errors",
+            ["error_type"],
+        )
+
+    def record_pool_stats(
+        self,
+        pool_size: int,
+        pool_checked_out: int,
+        pool_overflow: int,
+    ) -> None:
+        """Record database connection pool statistics."""
+        self.pool_size.set(float(pool_size))
+        self.pool_checked_out.set(float(pool_checked_out))
+        self.pool_overflow.set(float(pool_overflow))
+
+    def record_checkout(
+        self,
+        duration: float,
+    ) -> None:
+        """Record a database connection checkout from the pool."""
+        self.connection_checkout_duration.observe(duration)
+
+    def record_error(
+        self,
+        error_type: str,
+        is_timeout: bool = False,
+    ) -> None:
+        """Record a database connection or execution error."""
+        self.connection_errors_total.labels(error_type=error_type).inc()
+        if is_timeout:
+            self.connection_timeouts_total.inc()
+
+
+_PREFIX_PATTERN: re.Pattern[str] = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+
+def _make_metric_name(name: str, prefix: str | None = None) -> str:
+    """Make metric name with optional prefix.
+
+    Prefix must follow Prometheus naming conventions (^[a-zA-Z_][a-zA-Z0-9_]*$).
+
+    Args:
+        name: Base metric name.
+        prefix: Optional prefix for the metric.
+
+    Returns:
+        The combined metric name.
+
+    Raises:
+        ValueError: If the prefix is invalid.
+    """
+    if prefix:
+        if not _PREFIX_PATTERN.match(prefix):
+            raise ValueError(
+                f"Invalid metric prefix: '{prefix}'. "
+                "Prefixes must start with a letter or underscore and contain only letters, numbers, or underscores."
+            )
+        return f"{prefix}_{name}"
+    return name
+
+
+__all__ = ["PostgresMetrics"]

sqlalchemy_foundation_kit/contrib/settings/__init__.py

@@ -0,0 +1,19 @@
+"""Pydantic Settings integration."""
+
+from __future__ import annotations
+
+from .postgres import (
+    BasePostgresConfig,
+    BasePostgresMigrationsConfig,
+    ConnectionSettings,
+    PoolSettings,
+    QuerySettings,
+)
+
+__all__ = [
+    "BasePostgresConfig",
+    "BasePostgresMigrationsConfig",
+    "ConnectionSettings",
+    "PoolSettings",
+    "QuerySettings",
+]