swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/database/pagination/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from swiftpy.database.pagination.contracts import (
+    PaginatorContract,
+    SimplePaginatorContract,
+)
+from swiftpy.database.pagination.paginator import Paginator
+from swiftpy.database.pagination.simple_paginator import SimplePaginator
+
+__all__ = [
+    "Paginator",
+    "PaginatorContract",
+    "SimplePaginator",
+    "SimplePaginatorContract",
+]
+

swiftpy/database/pagination/contracts.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any, Protocol, TypeVar
+
+T_co = TypeVar("T_co", covariant=True)
+
+
+class PaginatorContract[T_co](Protocol):
+    items: list[T_co]
+    total: int
+    per_page: int
+    current_page: int
+    last_page: int
+
+    @property
+    def has_more_pages(self) -> bool: ...
+
+    @property
+    def has_previous_page(self) -> bool: ...
+
+    @property
+    def first_item(self) -> int | None: ...
+
+    @property
+    def last_item(self) -> int | None: ...
+
+    def to_dict(self) -> dict[str, Any]: ...
+
+    def __iter__(self) -> Iterator[T_co]: ...
+
+    def __len__(self) -> int: ...
+
+    def __getitem__(self, index: int) -> T_co: ...
+
+
+class SimplePaginatorContract[T_co](Protocol):
+    items: list[T_co]
+    per_page: int
+    current_page: int
+
+    @property
+    def has_more_pages(self) -> bool: ...
+
+    @property
+    def has_previous_page(self) -> bool: ...
+
+    @property
+    def first_item(self) -> int | None: ...
+
+    @property
+    def last_item(self) -> int | None: ...
+
+    def to_dict(self) -> dict[str, Any]: ...
+
+    def __iter__(self) -> Iterator[T_co]: ...
+
+    def __len__(self) -> int: ...
+
+    def __getitem__(self, index: int) -> T_co: ...

swiftpy/database/pagination/paginator.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Iterator
+from typing import Any
+
+
+class Paginator[T]:
+    """
+    Length-aware paginator presenting a paginated slice of records along with
+    navigation metadata, total counts, and serialization helpers.
+    """
+
+    def __init__(
+        self,
+        items: list[T],
+        total: int,
+        per_page: int,
+        current_page: int,
+        last_page: int | None = None,
+    ) -> None:
+        if isinstance(total, bool) or not isinstance(total, int):
+            raise TypeError("total must be an integer.")
+        if total < 0:
+            raise ValueError("total cannot be negative.")
+
+        if isinstance(per_page, bool) or not isinstance(per_page, int):
+            raise TypeError("per_page must be an integer.")
+        if per_page < 1:
+            raise ValueError("per_page must be >= 1.")
+
+        if isinstance(current_page, bool) or not isinstance(current_page, int):
+            raise TypeError("current_page must be an integer.")
+        if current_page < 1:
+            raise ValueError("current_page must be >= 1.")
+
+        self.items: list[T] = items
+        self.total: int = total
+        self.per_page: int = per_page
+        self.current_page: int = current_page
+
+        if last_page is None:
+            self.last_page = max(1, math.ceil(total / per_page)) if per_page > 0 else 1
+        else:
+            if isinstance(last_page, bool) or not isinstance(last_page, int):
+                raise TypeError("last_page must be an integer.")
+            if last_page < 1:
+                raise ValueError("last_page must be >= 1.")
+            self.last_page = last_page
+
+    @property
+    def has_more_pages(self) -> bool:
+        """Return True if there are pages beyond the current page."""
+        return self.current_page < self.last_page
+
+    @property
+    def has_previous_page(self) -> bool:
+        """Return True if the current page is greater than page 1."""
+        return self.current_page > 1
+
+    @property
+    def first_item(self) -> int | None:
+        """Return the 1-based index of the first record in the current page, or None if empty."""
+        if not self.items:
+            return None
+        return (self.current_page - 1) * self.per_page + 1
+
+    @property
+    def last_item(self) -> int | None:
+        """Return the 1-based index of the last record in the current page, or None if empty."""
+        first = self.first_item
+        if first is None:
+            return None
+        return first + len(self.items) - 1
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize paginator data and metadata into a standard dictionary payload."""
+        serialized_items: list[Any] = []
+        for item in self.items:
+            if hasattr(item, "to_dict") and callable(item.to_dict):
+                serialized_items.append(item.to_dict())
+            elif isinstance(item, dict):
+                serialized_items.append(dict(item))
+            else:
+                serialized_items.append(item)
+
+        return {
+            "data": serialized_items,
+            "current_page": self.current_page,
+            "per_page": self.per_page,
+            "total": self.total,
+            "last_page": self.last_page,
+            "from": self.first_item,
+            "to": self.last_item,
+            "has_more_pages": self.has_more_pages,
+            "has_previous_page": self.has_previous_page,
+        }
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.items)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    def __getitem__(self, index: int) -> T:
+        return self.items[index]
+
+    def __repr__(self) -> str:
+        return (
+            f"<{self.__class__.__name__} page={self.current_page}/{self.last_page} "
+            f"count={len(self.items)} total={self.total}>"
+        )

swiftpy/database/pagination/simple_paginator.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+
+class SimplePaginator[T]:
+    """
+    Lightweight paginator that skips expensive COUNT(*) operations by querying
+    for an extra record (per_page + 1) to determine if additional pages exist.
+    """
+
+    def __init__(
+        self,
+        items: list[T],
+        per_page: int,
+        current_page: int,
+        has_more: bool,
+    ) -> None:
+        if isinstance(per_page, bool) or not isinstance(per_page, int):
+            raise TypeError("per_page must be an integer.")
+        if per_page < 1:
+            raise ValueError("per_page must be >= 1.")
+
+        if isinstance(current_page, bool) or not isinstance(current_page, int):
+            raise TypeError("current_page must be an integer.")
+        if current_page < 1:
+            raise ValueError("current_page must be >= 1.")
+
+        if not isinstance(has_more, bool):
+            raise TypeError("has_more must be a boolean.")
+
+        self.items: list[T] = items
+        self.per_page: int = per_page
+        self.current_page: int = current_page
+        self._has_more: bool = has_more
+
+    @property
+    def has_more_pages(self) -> bool:
+        """Return True if additional pages exist beyond the current page."""
+        return self._has_more
+
+    @property
+    def has_previous_page(self) -> bool:
+        """Return True if the current page is greater than page 1."""
+        return self.current_page > 1
+
+    @property
+    def first_item(self) -> int | None:
+        """Return the 1-based index of the first record in the current page, or None if empty."""
+        if not self.items:
+            return None
+        return (self.current_page - 1) * self.per_page + 1
+
+    @property
+    def last_item(self) -> int | None:
+        """Return the 1-based index of the last record in the current page, or None if empty."""
+        first = self.first_item
+        if first is None:
+            return None
+        return first + len(self.items) - 1
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize simple paginator data and metadata into a standard dictionary payload."""
+        serialized_items: list[Any] = []
+        for item in self.items:
+            if hasattr(item, "to_dict") and callable(item.to_dict):
+                serialized_items.append(item.to_dict())
+            elif isinstance(item, dict):
+                serialized_items.append(dict(item))
+            else:
+                serialized_items.append(item)
+
+        return {
+            "data": serialized_items,
+            "current_page": self.current_page,
+            "per_page": self.per_page,
+            "from": self.first_item,
+            "to": self.last_item,
+            "has_more_pages": self.has_more_pages,
+            "has_previous_page": self.has_previous_page,
+        }
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.items)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    def __getitem__(self, index: int) -> T:
+        return self.items[index]
+
+    def __repr__(self) -> str:
+        return (
+            f"<{self.__class__.__name__} page={self.current_page} "
+            f"count={len(self.items)} has_more={self._has_more}>"
+        )

swiftpy/database/pool.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import ssl
+from typing import Any
+
+import asyncpg
+
+from swiftpy.core.config import Config, ConfigurationError
+
+logger = logging.getLogger("swiftpy.database.pool")
+
+
+def _create_ssl_context(
+    cafile: str | None,
+    *,
+    verify_mode: ssl.VerifyMode,
+    check_hostname: bool,
+) -> ssl.SSLContext:
+    """Create an SSLContext while translating file/SSL errors into ConfigurationError."""
+    try:
+        ctx = ssl.create_default_context(cafile=cafile)
+    except (OSError, ssl.SSLError, ValueError) as exc:
+        raise ConfigurationError(
+            f"Failed to load database SSL CA configuration (cafile={cafile!r}): {exc}"
+        ) from exc
+    ctx.check_hostname = check_hostname
+    ctx.verify_mode = verify_mode
+    return ctx
+
+
+def _build_ssl_context(
+    ssl_opt: Any,
+    ssl_ca_file: str | None = None,
+) -> ssl.SSLContext | bool:
+    """
+    Build an ssl.SSLContext or boolean flag for asyncpg from configuration.
+    Supported modes: disable, require, verify-ca, verify-full.
+    Boolean True (or string 'true') maps to 'require' with a warning for backward compatibility.
+    """
+    if ssl_opt is False or ssl_opt is None:
+        return False
+
+    cafile = ssl_ca_file if ssl_ca_file else None
+
+    if ssl_opt is True:
+        logger.warning(
+            "Database SSL configured with boolean True; mapping to 'require' "
+            "(encrypted connection without certificate verification). "
+            "Prefer explicit 'verify-full' or 'verify-ca' in production."
+        )
+        return _create_ssl_context(
+            cafile, verify_mode=ssl.CERT_NONE, check_hostname=False
+        )
+
+    if isinstance(ssl_opt, ssl.SSLContext):
+        return ssl_opt
+
+    if isinstance(ssl_opt, str):
+        mode = ssl_opt.strip().lower()
+        if mode in ("", "disable", "false", "0", "off", "no"):
+            return False
+        if mode in ("true", "1", "yes", "on"):
+            logger.warning(
+                "Database SSL configured with boolean string %r; mapping to 'require' "
+                "(encrypted connection without certificate verification). "
+                "Prefer explicit 'verify-full' or 'verify-ca' in production.",
+                ssl_opt,
+            )
+            return _create_ssl_context(
+                cafile, verify_mode=ssl.CERT_NONE, check_hostname=False
+            )
+        if mode == "require":
+            return _create_ssl_context(
+                cafile, verify_mode=ssl.CERT_NONE, check_hostname=False
+            )
+        if mode == "verify-ca":
+            return _create_ssl_context(
+                cafile, verify_mode=ssl.CERT_REQUIRED, check_hostname=False
+            )
+        if mode == "verify-full":
+            return _create_ssl_context(
+                cafile, verify_mode=ssl.CERT_REQUIRED, check_hostname=True
+            )
+
+    raise ConfigurationError(
+        f"Unsupported database SSL mode: {ssl_opt!r}. "
+        "Expected one of: disable, require, verify-ca, verify-full."
+    )
+
+
+class DatabasePool:
+    """Manages the application-wide asyncpg connection pool."""
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+        self._pool: asyncpg.Pool | None = None
+        self._init_lock = asyncio.Lock()
+
+    @property
+    def is_initialized(self) -> bool:
+        """Return whether the underlying asyncpg pool has been initialized."""
+        return self._pool is not None
+
+    async def init(self) -> asyncpg.Pool:
+        """
+        Initialize the asyncpg connection pool utilizing the injected Config repository.
+        Idempotent and safe under concurrent calls.
+        """
+        if self._pool is not None:
+            return self._pool
+
+        async with self._init_lock:
+            if self._pool is not None:
+                return self._pool
+
+            default_conn = str(self.config.get("database.default", "postgresql"))
+            conn_path = f"database.connections.{default_conn}"
+
+            user = str(self.config.get(f"{conn_path}.user", "postgres"))
+            raw_password = self.config.get(f"{conn_path}.password", "")
+            password = "" if raw_password is None else str(raw_password)
+
+            app_env = str(
+                self.config.get("app.env") or self.config.get("env") or "development"
+            ).lower()
+            debug_val = (
+                self.config.get("app.debug")
+                if self.config.get("app.debug") is not None
+                else self.config.get("debug")
+            )
+            is_production = app_env in ("production", "prod")
+            is_debug = bool(debug_val) if debug_val is not None else not is_production
+
+            if not password:
+                if is_production or not is_debug:
+                    raise ConfigurationError(
+                        f"Database connection '{default_conn}' has an empty password "
+                        "while running in non-debug/production mode. Set DB_PASSWORD explicitly."
+                    )
+                logger.warning(
+                    "Database connection '%s' (user=%r) is using an empty password in debug mode.",
+                    default_conn,
+                    user,
+                )
+
+            ca_file_raw = self.config.get(
+                f"{conn_path}.ssl_ca_file"
+            ) or self.config.get("database.ssl_ca_file")
+            ssl_ca_file = str(ca_file_raw).strip() if ca_file_raw else None
+            ssl_arg = _build_ssl_context(
+                self.config.get(f"{conn_path}.ssl", "disable"),
+                ssl_ca_file=ssl_ca_file,
+            )
+
+            statement_timeout = float(
+                self.config.get("database.timeouts.statement", 30.0)
+            )
+            tx_timeout_raw = self.config.get("database.timeouts.transaction", None)
+            settings: dict[str, str] = {}
+            if statement_timeout > 0:
+                settings["statement_timeout"] = str(int(statement_timeout * 1000))
+            if tx_timeout_raw is not None:
+                tx_timeout = float(tx_timeout_raw)
+                if tx_timeout > 0:
+                    settings["idle_in_transaction_session_timeout"] = str(
+                        int(tx_timeout * 1000)
+                    )
+            server_settings: dict[str, str] | None = settings or None
+
+            self._pool = await asyncpg.create_pool(
+                host=str(self.config.get(f"{conn_path}.host", "127.0.0.1")),
+                port=int(self.config.get(f"{conn_path}.port", 5432)),
+                database=str(self.config.get(f"{conn_path}.database", "swiftpy")),
+                user=user,
+                password=password,
+                ssl=ssl_arg,
+                min_size=int(self.config.get("database.pool.min_size", 5)),
+                max_size=int(self.config.get("database.pool.max_size", 20)),
+                max_queries=int(self.config.get("database.pool.max_queries", 50000)),
+                max_inactive_connection_lifetime=float(
+                    self.config.get(
+                        "database.pool.max_inactive_connection_lifetime", 300.0
+                    )
+                ),
+                command_timeout=float(
+                    self.config.get("database.pool.command_timeout", 60.0)
+                ),
+                timeout=float(self.config.get("database.timeouts.connect", 10.0)),
+                server_settings=server_settings,
+            )
+            return self._pool
+
+    def get_pool(self) -> asyncpg.Pool:
+        """Return the active connection pool instance."""
+        if self._pool is None:
+            raise RuntimeError(
+                "Database pool is not initialized. Ensure it is initialized during application startup hooks."
+            )
+        return self._pool
+
+    async def close(self, timeout: float = 5.0) -> None:
+        """Gracefully shutdown the connection pool with a timeout fallback to terminate()."""
+        if self._pool is not None:
+            pool = self._pool
+            self._pool = None
+            try:
+                await asyncio.wait_for(pool.close(), timeout=timeout)
+            except TimeoutError:
+                logger.warning(
+                    "Database pool close timed out after %.2fs; terminating active connections.",
+                    timeout,
+                )
+                pool.terminate()
+
+
+__all__ = ["DatabasePool", "_build_ssl_context"]