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

sqlalchemy_foundation_kit/base/serialization.py

@@ -0,0 +1,98 @@
+"""JSON serialization utilities for SQLAlchemy."""
+
+from __future__ import annotations
+
+import decimal
+import logging
+
+from ._optional import require_optional
+
+logger = logging.getLogger(__name__)
+
+
+def _default_json_encoder(obj: object) -> str:
+    """JSON encoder for types not supported by orjson.
+
+    Handles special types like decimal.Decimal that orjson doesn't support natively.
+
+    Args:
+        obj: The object to encode.
+
+    Returns:
+        String representation of the object.
+
+    Raises:
+        TypeError: If the object type is not supported.
+
+    Examples:
+        >>> from decimal import Decimal
+        >>> _default_json_encoder(Decimal("123.45"))
+        '123.45'
+        >>> _default_json_encoder(object())
+        Traceback (most recent call last):
+        ...
+        TypeError
+    """
+    if isinstance(obj, decimal.Decimal):
+        return str(obj)
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+def _json_serializer(obj: object) -> str:
+    """High-performance JSON serializer using orjson.
+
+    Provides fast JSON serialization with fallback handling for types
+    like decimal.Decimal via the default encoder.
+
+    Args:
+        obj: The object to serialize.
+
+    Returns:
+        UTF-8 encoded JSON string.
+
+    Raises:
+        ImportError: If orjson is not installed.
+
+    Examples:
+        >>> _json_serializer({"key": "value"})
+        '{"key":"value"}'
+    """
+    orjson = require_optional("orjson", "json")
+
+    try:
+        return orjson.dumps(obj, default=_default_json_encoder).decode("utf-8")  # type: ignore[no-any-return]
+    except (TypeError, ValueError) as e:
+        logger.exception("Failed to serialize %s to JSON", type(obj).__name__)
+        raise TypeError(f"Cannot serialize {type(obj).__name__} to JSON: {e}") from e
+
+
+def configure_orjson_serialization() -> dict[str, object]:
+    """Configure orjson serialization for SQLAlchemy engine.
+
+    Returns:
+        Dictionary with json_serializer and json_deserializer configured.
+
+    Raises:
+        ImportError: If orjson is not installed.
+
+    Examples:
+        >>> config = configure_orjson_serialization()
+        >>> "json_serializer" in config
+        True
+        >>> "json_deserializer" in config
+        True
+    """
+    orjson = require_optional("orjson", "json")
+
+    return {
+        "json_serializer": _json_serializer,
+        "json_deserializer": orjson.loads,
+    }
+
+
+__all__ = [
+    "configure_orjson_serialization",
+]
+
+# Note: _default_json_encoder and _json_serializer are private internal helpers
+# used by configure_orjson_serialization(). They are not part of the public API.

sqlalchemy_foundation_kit/base/types.py

@@ -0,0 +1,72 @@
+"""Custom SQLAlchemy types."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, TypeVar
+
+from pydantic import TypeAdapter, ValidationError
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.types import TypeDecorator
+
+T = TypeVar("T")
+logger = logging.getLogger(__name__)
+
+
+# Convenience alias for raw JSON dict columns.
+# Use this when you don't need Pydantic validation — e.g. ``Mapped[GenericJSONDict]``.
+GenericJSONDict = dict[str, Any]
+
+
+class PydanticJSONB(TypeDecorator):
+    """SQLAlchemy TypeDecorator for Pydantic models stored as JSONB.
+
+    Validates and serializes values against the supplied Pydantic-compatible type
+    on both write and read paths. A ``model_type`` is **required** — if you need
+    raw dict storage without validation, use SQLAlchemy's built-in ``JSONB`` directly
+    (or the :data:`GenericJSONDict` alias).
+    """
+
+    impl = JSONB
+    cache_ok = True
+
+    def __init__(self, model_type: type[T], *args: Any, **kwargs: Any) -> None:
+        """Initialize the type decorator.
+
+        Args:
+            model_type: Pydantic model class (or any type compatible with
+                ``pydantic.TypeAdapter``) used to validate and serialize values.
+        """
+        self.model_type = model_type
+        self.adapter: TypeAdapter[T] = TypeAdapter(model_type)
+        super().__init__(*args, **kwargs)
+
+    def process_bind_param(self, value: Any, dialect: Any) -> Any:
+        if value is None:
+            return None
+
+        # Validate before dump to avoid Pydantic serialization warnings when value
+        # is a dict (e.g. from model_dump()). This ensures value matches the expected
+        # schema and converts it to a model instance if needed.
+        validated = self.adapter.validate_python(value)
+        return self.adapter.dump_python(validated, mode="json")
+
+    def process_result_value(self, value: Any, dialect: Any) -> Any:
+        if value is None:
+            return None
+
+        try:
+            return self.adapter.validate_python(value)
+        except ValidationError:
+            logger.warning(
+                "Validation error while loading %s from JSONB. Using raw data. "
+                "This may indicate legacy data that doesn't match current schema.",
+                self.model_type,
+            )
+            return value
+
+
+__all__ = [
+    "GenericJSONDict",
+    "PydanticJSONB",
+]

sqlalchemy_foundation_kit/config/__init__.py

@@ -0,0 +1,17 @@
+"""Database configuration module."""
+
+from __future__ import annotations
+
+from .postgres import (
+    ConnectionSettingsProtocol,
+    PoolSettingsProtocol,
+    PostgresSettingsProtocol,
+    QuerySettingsProtocol,
+)
+
+__all__ = [
+    "ConnectionSettingsProtocol",
+    "PoolSettingsProtocol",
+    "PostgresSettingsProtocol",
+    "QuerySettingsProtocol",
+]

sqlalchemy_foundation_kit/config/postgres.py

@@ -0,0 +1,177 @@
+"""PostgreSQL configuration."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class PasswordLike(Protocol):
+    """Protocol for secret string types.
+
+    Allows ``ConnectionSettingsProtocol.password`` to accept either plain ``str``
+    or SecretStr-like objects without forcing pydantic dependency in core layer.
+
+    Implementations:
+        - pydantic.SecretStr
+        - pydantic_settings.SecretStr
+        - str (plain string)
+
+    Examples:
+        Using with Pydantic SecretStr:
+            >>> from pydantic import SecretStr
+            >>> password: PasswordLike = SecretStr("secret123")
+            >>> password.get_secret_value()
+            'secret123'
+
+        Using with plain string (no get_secret_value method):
+            >>> password_plain: PasswordLike = "plain_password"
+            >>> # Note: plain str doesn't have get_secret_value()
+            >>> # Protocol usage requires runtime type checking
+
+    Security:
+        Always use SecretStr-like types in production to prevent accidental logging.
+    """
+
+    def get_secret_value(self) -> str:
+        """Return the underlying secret value as plain text.
+
+        Returns:
+            Decrypted/unwrapped secret value.
+
+        Security:
+            This method exposes the secret. Use carefully and never log the result.
+
+        Examples:
+            >>> from pydantic import SecretStr
+            >>> secret = SecretStr("my-password")
+            >>> secret.get_secret_value()
+            'my-password'
+        """
+        ...
+
+
+class ConnectionSettingsProtocol(Protocol):
+    """Protocol for PostgreSQL connection settings.
+
+    Defines connection parameters required for establishing database connections.
+
+    Attributes:
+        host: PostgreSQL server hostname or IP address.
+        port: PostgreSQL server port number.
+        user: Database username for authentication.
+        password: Database password — either a plain ``str`` or a SecretStr-like object
+            implementing ``get_secret_value()``.
+        database: Target database name.
+    """
+
+    host: str
+    port: int
+    user: str
+    password: PasswordLike | str
+    database: str
+
+
+class PoolSettingsProtocol(Protocol):
+    """Protocol for PostgreSQL connection pool settings.
+
+    Defines pool configuration for SQLAlchemy engine connection management.
+
+    Attributes:
+        kind: Connection pool implementation (queue, static, etc.).
+        size: Number of connections to maintain in pool.
+        max_overflow: Additional connections allowed when pool exhausted.
+        pre_ping: Test connection health before checkout.
+        recycle: Recycle connections after N seconds.
+        timeout: Timeout for acquiring connection from pool.
+
+    Examples:
+        >>> pool: PoolSettingsProtocol = ...
+        >>> if pool.size > 100:
+        ...     logger.warning("Large pool size detected")
+    """
+
+    kind: str | type
+    size: int | None
+    max_overflow: int | None
+    pre_ping: bool
+    recycle: int | None
+    timeout: float | None
+
+
+class QuerySettingsProtocol(Protocol):
+    """Protocol for PostgreSQL query execution settings.
+
+    Defines query behavior, caching, and transaction isolation configuration.
+
+    Attributes:
+        echo: Enable SQL statement logging.
+        statement_cache_size: Prepared statement cache size.
+        prepared_statement_cache_size: Server-side prepared statement cache size.
+        isolation_level: Transaction isolation level.
+
+    Examples:
+        >>> query: QuerySettingsProtocol = ...
+        >>> if query.echo:
+        ...     logger.info("SQL echo enabled")
+    """
+
+    echo: bool
+    statement_cache_size: int | None
+    prepared_statement_cache_size: int | None
+    isolation_level: str | None
+
+
+class PostgresSettingsProtocol(Protocol):
+    """Protocol for PostgreSQL configuration.
+
+    Organized protocol with grouped settings for connection, pool, and query configuration.
+
+    Attributes:
+        connection: Connection parameters (host, port, user, database).
+        pool: Connection pool settings.
+        query: Query execution and transaction settings.
+        application_name: Application identifier for connections.
+        db_schema: Optional PostgreSQL schema name.
+        use_orjson_serialization: Enable orjson for JSON operations.
+        jit: JIT compilation setting (PgBouncer compatibility).
+
+    Examples:
+        Implementing the protocol:
+            >>> class MyConfig:
+            ...     connection: ConnectionSettingsProtocol
+            ...     pool: PoolSettingsProtocol
+            ...     query: QuerySettingsProtocol
+            ...     application_name: str = "my-app"
+            ...     db_schema: str | None = None
+            ...     use_orjson_serialization: bool = True
+            ...     jit: str | None = "off"
+            ...
+            ...     def to_dsn(self) -> str:
+            ...         return f"postgresql://{self.connection.user}@{self.connection.host}..."
+
+        Using the protocol:
+            >>> def create_engine(config: PostgresSettingsProtocol):
+            ...     dsn = config.to_dsn()
+            ...     pool_size = config.pool.pool_size
+            ...     echo = config.query.echo
+    """
+
+    connection: ConnectionSettingsProtocol
+    pool: PoolSettingsProtocol
+    query: QuerySettingsProtocol
+    application_name: str
+    db_schema: str | None
+    use_orjson_serialization: bool
+    jit: str | None
+
+    def to_dsn(self) -> str:
+        """Convert config to DSN string.
+
+        Returns PostgreSQL connection string in format:
+        postgresql+asyncpg://user:password@host:port/database
+
+        Examples:
+            >>> config.to_dsn()
+            'postgresql+asyncpg://user:***@localhost:5432/mydb'
+        """
+        ...

sqlalchemy_foundation_kit/contrib/__init__.py

@@ -0,0 +1,5 @@
+"""Optional contrib integrations for external dependencies."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

sqlalchemy_foundation_kit/contrib/_metrics_utils.py

@@ -0,0 +1,19 @@
+"""Shared helpers for metrics providers."""
+
+from __future__ import annotations
+
+
+def _infra_metrics_prefix(default_prefix: str | None) -> str | None:
+    """Resolve prefix from the app (``get_default_prefix`` → ``str | None``).
+
+    ``None`` or whitespace-only string means no prefix for underlying metrics classes.
+    This intentionally does **not** read ``PrometheusMetricsSettingsProtocol.prefix`` so
+    service-level ``METRICS__PREFIX`` can target business metrics only.
+    """
+    if default_prefix is None:
+        return None
+    stripped = default_prefix.strip()
+    return stripped if stripped else None
+
+
+__all__ = ["_infra_metrics_prefix"]

sqlalchemy_foundation_kit/contrib/dependency_injector/__init__.py

@@ -0,0 +1,27 @@
+"""dependency-injector containers."""
+
+from __future__ import annotations
+
+from ._base import BaseDIContainer
+from .database import (
+    AsyncDatabaseResourceProvider,
+    DatabaseContainer,
+    RetryConfig,
+    retry_async_connection,
+)
+from .metrics import (
+    PostgresMetricsSettingsProtocol,
+    PrometheusMetricsContainer,
+    PrometheusMetricsSettingsProtocol,
+)
+
+__all__ = [
+    "AsyncDatabaseResourceProvider",
+    "BaseDIContainer",
+    "DatabaseContainer",
+    "PostgresMetricsSettingsProtocol",
+    "PrometheusMetricsContainer",
+    "PrometheusMetricsSettingsProtocol",
+    "RetryConfig",
+    "retry_async_connection",
+]

sqlalchemy_foundation_kit/contrib/dependency_injector/_base.py

@@ -0,0 +1,27 @@
+"""Base dependency-injector container with automatic dependency checking."""
+
+from __future__ import annotations
+
+from ._deps import check_dependency_injector, containers
+
+
+class BaseDIContainer(containers.DeclarativeContainer):  # type: ignore[misc,name-defined]
+    """Base container that checks dependency-injector availability on subclass creation.
+
+    All dependency-injector containers should inherit from this class instead of directly
+    from containers.DeclarativeContainer. This ensures consistent error messages when
+    dependency-injector is not installed.
+    """
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        """Check dependency-injector availability when creating a subclass."""
+        super().__init_subclass__(**kwargs)
+        check_dependency_injector()
+
+    def __init__(self, *args: object, **kwargs: object) -> None:
+        """Check dependency-injector availability when instantiating."""
+        check_dependency_injector()
+        super().__init__(*args, **kwargs)
+
+
+__all__ = ["BaseDIContainer"]

sqlalchemy_foundation_kit/contrib/dependency_injector/_deps.py

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

sqlalchemy_foundation_kit/contrib/dependency_injector/database.py

@@ -0,0 +1,196 @@
+"""Database containers for dependency-injector."""
+
+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 BaseDIContainer
+from ._deps import providers
+
+logger = logging.getLogger(__name__)
+
+
+async def _create_session_manager_resource(
+    postgres_config: PostgresSettingsProtocol,
+    metrics: PostgresMetricsProtocol | None,
+    healthcheck_query: str | None,
+    retry_config: RetryConfig,
+) -> AsyncIterator[AsyncSessionManager[AsyncSession]]:
+    """Resource factory: build manager, run healthcheck, yield, then close."""
+    manager = create_async_session_manager(postgres_config, metrics=metrics)
+
+    if healthcheck_query is not None:
+        query = 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=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)
+
+
+def _get_session_maker(
+    session_manager: AsyncSessionManager[AsyncSession],
+) -> async_sessionmaker[AsyncSession]:
+    """Factory: extract session_maker from session_manager."""
+    return session_manager.session_maker
+
+
+def _create_uow(
+    session_maker: async_sessionmaker[AsyncSession],
+) -> AsyncUnitOfWork[AsyncSQLAlchemyUowTransaction]:
+    """Factory: create Unit of Work from session_maker."""
+    return AsyncSQLAlchemyUnitOfWork(session_maker, transaction_factory=AsyncSQLAlchemyUowTransaction)
+
+
+class DatabaseContainer(BaseDIContainer):
+    """Container for database dependencies.
+
+    Provides:
+        - ``session_manager``: Manages database connections and engine lifecycle.
+        - ``session_maker``: Factory for creating database sessions.
+        - ``uow``: Unit of Work for database transactions.
+
+    Configuration:
+        - ``postgres_config``: PostgreSQL configuration (``PostgresSettingsProtocol``).
+        - ``metrics``: Optional metrics collector (``PostgresMetricsProtocol``).
+        - ``healthcheck_query``: SQL executed at startup (default: ``"SELECT 1"``, ``None`` to skip).
+        - ``retry_config``: Retry behavior for healthcheck (default: ``RetryConfig()``).
+    """
+
+    # Configuration
+    postgres_config = providers.Dependency()  # type: ignore[misc,var-annotated]
+    metrics = providers.Dependency(default=None)  # type: ignore[misc,var-annotated]
+
+    # Healthcheck configuration
+    healthcheck_query = providers.Object(DEFAULT_HEALTHCHECK_QUERY)  # type: ignore[misc,var-annotated]
+    retry_config = providers.Object(DEFAULT_RETRY_CONFIG)  # type: ignore[misc,var-annotated]
+
+    # Session manager (resource: handles lifecycle)
+    session_manager = providers.Resource(  # type: ignore[misc,var-annotated]
+        _create_session_manager_resource,
+        postgres_config=postgres_config,
+        metrics=metrics,
+        healthcheck_query=healthcheck_query,
+        retry_config=retry_config,
+    )
+
+    # Session maker
+    session_maker = providers.Factory(  # type: ignore[misc,var-annotated]
+        _get_session_maker,
+        session_manager=session_manager,
+    )
+
+    # Unit of Work
+    uow = providers.Singleton(  # type: ignore[misc,var-annotated]
+        _create_uow,
+        session_maker=session_maker,
+    )
+
+
+class AsyncDatabaseResourceProvider:
+    """Helper class for managing database session manager lifecycle.
+
+    Use this when you need manual control over session manager lifecycle —
+    for example in tests or when not using dependency-injector containers.
+
+    Examples:
+        >>> provider = AsyncDatabaseResourceProvider(config, metrics)
+        >>> manager = await provider.start()
+        >>> # Use manager...
+        >>> await provider.stop()
+    """
+
+    def __init__(
+        self,
+        postgres_config: PostgresSettingsProtocol,
+        metrics: PostgresMetricsProtocol | None = None,
+        healthcheck_query: str | None = DEFAULT_HEALTHCHECK_QUERY,
+        retry_config: RetryConfig = DEFAULT_RETRY_CONFIG,
+    ) -> None:
+        """Initialize provider.
+
+        Args:
+            postgres_config: PostgreSQL configuration.
+            metrics: Optional metrics collector.
+            healthcheck_query: SQL executed at startup to verify connectivity.
+                Pass ``None`` to skip the healthcheck entirely.
+            retry_config: Retry behavior for healthcheck.
+        """
+        self._postgres_config = postgres_config
+        self._metrics = metrics
+        self._healthcheck_query = healthcheck_query
+        self._retry_config = retry_config
+        self._manager: AsyncSessionManager[AsyncSession] | None = None
+
+    async def start(self) -> AsyncSessionManager[AsyncSession]:
+        """Start session manager and perform healthcheck."""
+        manager = create_async_session_manager(self._postgres_config, metrics=self._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,
+            )
+
+        self._manager = manager
+        return manager
+
+    async def stop(self) -> None:
+        """Stop session manager and close connections."""
+        if self._manager is not None:
+            try:
+                await self._manager.aclose()
+                logger.info("Database session manager closed successfully")
+            except SQLAlchemyError as e:
+                logger.warning("Error closing database session manager: %s", e)
+            finally:
+                self._manager = None
+
+
+__all__ = [
+    "AsyncDatabaseResourceProvider",
+    "DatabaseContainer",
+    "RetryConfig",
+    "retry_async_connection",
+]