tempest-fastapi-sdk 0.1.0__py3-none-any.whl

tempest_fastapi_sdk/__init__.py

@@ -0,0 +1,110 @@
+"""tempest-fastapi-sdk — shared FastAPI/SQLAlchemy/Pydantic primitives."""
+
+from tempest_fastapi_sdk.api import (
+    app_exception_handler,
+    register_exception_handlers,
+)
+from tempest_fastapi_sdk.db import (
+    NAMING_CONVENTION,
+    AlembicHelper,
+    AsyncDatabaseManager,
+    BaseModel,
+    BaseRepository,
+)
+from tempest_fastapi_sdk.exceptions import (
+    AppException,
+    ConflictException,
+    ExpiredTokenException,
+    FileTooLargeException,
+    ForbiddenException,
+    InvalidFileTypeException,
+    InvalidTokenException,
+    NotFoundException,
+    UnauthorizedException,
+    ValidationException,
+)
+from tempest_fastapi_sdk.schemas import (
+    BasePaginationFilterSchema,
+    BasePaginationSchema,
+    BaseResponseSchema,
+    BaseSchema,
+)
+from tempest_fastapi_sdk.settings import BaseAppSettings
+from tempest_fastapi_sdk.utils import (
+    CNPJ,
+    CNPJ_PATTERN,
+    CPF,
+    CPF_CNPJ_PATTERN,
+    CPF_PATTERN,
+    PHONE_BR_PATTERN,
+    CPFOrCNPJ,
+    EmailUtils,
+    JWTUtils,
+    PasswordUtils,
+    PhoneBR,
+    UploadUtils,
+    is_valid_cnpj,
+    is_valid_cpf,
+    is_valid_cpf_cnpj,
+    is_valid_phone_br,
+    modify_dict,
+    normalize_cnpj,
+    normalize_cpf,
+    normalize_cpf_cnpj,
+    normalize_phone_br,
+    only_digits,
+    to_utc,
+    utcnow,
+)
+
+__version__: str = "0.1.0"
+
+__all__: list[str] = [
+    "CNPJ",
+    "CNPJ_PATTERN",
+    "CPF",
+    "CPF_CNPJ_PATTERN",
+    "CPF_PATTERN",
+    "NAMING_CONVENTION",
+    "PHONE_BR_PATTERN",
+    "AlembicHelper",
+    "AppException",
+    "AsyncDatabaseManager",
+    "BaseAppSettings",
+    "BaseModel",
+    "BasePaginationFilterSchema",
+    "BasePaginationSchema",
+    "BaseRepository",
+    "BaseResponseSchema",
+    "BaseSchema",
+    "CPFOrCNPJ",
+    "ConflictException",
+    "EmailUtils",
+    "ExpiredTokenException",
+    "FileTooLargeException",
+    "ForbiddenException",
+    "InvalidFileTypeException",
+    "InvalidTokenException",
+    "JWTUtils",
+    "NotFoundException",
+    "PasswordUtils",
+    "PhoneBR",
+    "UnauthorizedException",
+    "UploadUtils",
+    "ValidationException",
+    "__version__",
+    "app_exception_handler",
+    "is_valid_cnpj",
+    "is_valid_cpf",
+    "is_valid_cpf_cnpj",
+    "is_valid_phone_br",
+    "modify_dict",
+    "normalize_cnpj",
+    "normalize_cpf",
+    "normalize_cpf_cnpj",
+    "normalize_phone_br",
+    "only_digits",
+    "register_exception_handlers",
+    "to_utc",
+    "utcnow",
+]

tempest_fastapi_sdk/api/__init__.py

@@ -0,0 +1,11 @@
+"""FastAPI integration primitives exposed at module level."""
+
+from tempest_fastapi_sdk.api.handlers import (
+    app_exception_handler,
+    register_exception_handlers,
+)
+
+__all__: list[str] = [
+    "app_exception_handler",
+    "register_exception_handlers",
+]

tempest_fastapi_sdk/api/handlers.py

@@ -0,0 +1,59 @@
+"""FastAPI exception handlers for ``AppException`` and friends."""
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from tempest_fastapi_sdk.exceptions.base import AppException
+
+
+async def app_exception_handler(
+    request: Request,
+    exc: AppException,
+) -> JSONResponse:
+    """Serialize an :class:`AppException` to the SDK JSON envelope.
+
+    Emits the shape::
+
+        {
+            "detail": "<message>",
+            "code": "<machine-readable code>",
+            "details": {...}
+        }
+
+    Args:
+        request (Request): The incoming HTTP request. Unused — kept
+            for signature compatibility with FastAPI handlers.
+        exc (AppException): The exception raised.
+
+    Returns:
+        JSONResponse: The serialized response.
+    """
+    del request
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "detail": exc.detail,
+            "code": exc.code,
+            "details": exc.details,
+        },
+        headers=exc.headers,
+    )
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """Register the SDK's exception handlers on a FastAPI app.
+
+    Wires :class:`AppException` to :func:`app_exception_handler` so
+    every subclass returned by routers, services and repositories is
+    serialized consistently.
+
+    Args:
+        app (FastAPI): The FastAPI application to wire.
+    """
+    app.add_exception_handler(AppException, app_exception_handler)  # type: ignore[arg-type]
+
+
+__all__: list[str] = [
+    "app_exception_handler",
+    "register_exception_handlers",
+]

tempest_fastapi_sdk/db/__init__.py

@@ -0,0 +1,14 @@
+"""Database primitives exposed at module level."""
+
+from tempest_fastapi_sdk.db.connection import AsyncDatabaseManager
+from tempest_fastapi_sdk.db.migrations import AlembicHelper
+from tempest_fastapi_sdk.db.model import NAMING_CONVENTION, BaseModel
+from tempest_fastapi_sdk.db.repository import BaseRepository
+
+__all__: list[str] = [
+    "NAMING_CONVENTION",
+    "AlembicHelper",
+    "AsyncDatabaseManager",
+    "BaseModel",
+    "BaseRepository",
+]

tempest_fastapi_sdk/db/_alembic_templates/__init__.py

@@ -0,0 +1 @@
+"""Bundled Alembic templates loaded via importlib.resources."""

tempest_fastapi_sdk/db/_alembic_templates/env.py.template

@@ -0,0 +1,73 @@
+"""Alembic environment script.
+
+Generated by tempest-fastapi-sdk. Edit the metadata import below
+when your project moves the BaseModel re-export.
+"""
+
+import asyncio
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+# >>> tempest-fastapi-sdk: metadata import (edit if needed) <<<
+__METADATA_IMPORT__
+# >>> end tempest-fastapi-sdk block <<<
+
+config = context.config
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode, emitting SQL to stdout."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+        compare_server_default=True,
+        render_as_batch=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    """Configure and run migrations against an open connection."""
+    context.configure(
+        connection=connection,
+        target_metadata=target_metadata,
+        compare_type=True,
+        compare_server_default=True,
+        render_as_batch=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    """Build the async engine and dispatch migrations."""
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode against the configured database."""
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

tempest_fastapi_sdk/db/connection.py

@@ -0,0 +1,257 @@
+"""Async database manager with engine/session lifecycle helpers."""
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from sqlalchemy import text
+from sqlalchemy.engine import make_url
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.pool import Pool
+
+from tempest_fastapi_sdk.db.model import BaseModel
+
+
+class AsyncDatabaseManager:
+    """Manage the async SQLAlchemy engine and session lifecycle.
+
+    Handles engine creation tailored to the database backend (SQLite
+    gets ``check_same_thread=False`` by default, everything else
+    gets a pooled config), session factory construction, and table
+    create/drop helpers. Designed to be instantiated once per
+    application and reused across requests.
+
+    Backend detection uses ``sqlalchemy.engine.make_url`` so URLs
+    like ``sqlite+aiosqlite://...`` are matched precisely without
+    relying on substring tricks.
+
+    Attributes:
+        db_url (str): The database connection URL.
+        is_sqlite (bool): Whether the URL targets a SQLite backend.
+    """
+
+    def __init__(
+        self,
+        db_url: str,
+        *,
+        echo: bool = False,
+        pool_size: int = 10,
+        max_overflow: int = 20,
+        pool_recycle: int = 3600,
+        connect_args: dict[str, Any] | None = None,
+        poolclass: type[Pool] | None = None,
+        **engine_kwargs: Any,
+    ) -> None:
+        """Initialize the manager (does not open connections yet).
+
+        Args:
+            db_url (str): The database connection URL.
+            echo (bool): Whether to emit SQL to stdout.
+            pool_size (int): Number of permanent connections in the
+                pool. Ignored for SQLite URLs.
+            max_overflow (int): Extra connections allowed above the
+                pool size. Ignored for SQLite URLs.
+            pool_recycle (int): Recycle connections older than this
+                many seconds. Ignored for SQLite URLs.
+            connect_args (dict[str, Any] | None): Driver-level
+                arguments forwarded to ``create_async_engine``
+                (e.g. ``{"ssl": "require"}`` for asyncpg). SQLite
+                always receives ``check_same_thread=False`` unless
+                explicitly overridden here.
+            poolclass (type[Pool] | None): Override SQLAlchemy's
+                default pool class. Useful for tests
+                (``poolclass=NullPool``) or specialized topologies.
+            **engine_kwargs: Any additional keyword arguments are
+                passed through to ``create_async_engine`` verbatim.
+        """
+        self.db_url: str = db_url
+        self.is_sqlite: bool = make_url(db_url).get_backend_name() == "sqlite"
+        self._echo: bool = echo
+        self._pool_size: int = pool_size
+        self._max_overflow: int = max_overflow
+        self._pool_recycle: int = pool_recycle
+        self._connect_args: dict[str, Any] = dict(connect_args or {})
+        self._poolclass: type[Pool] | None = poolclass
+        self._engine_kwargs: dict[str, Any] = engine_kwargs
+        self._engine: AsyncEngine | None = None
+        self._session_maker: async_sessionmaker[AsyncSession] | None = None
+
+    @property
+    def is_connected(self) -> bool:
+        """Whether the engine is currently initialized.
+
+        Returns:
+            bool: ``True`` if :meth:`connect` has been called and
+            :meth:`disconnect` has not.
+        """
+        return self._engine is not None
+
+    async def connect(self) -> None:
+        """Create the engine and session factory if they don't exist.
+
+        Idempotent — calling twice is a no-op.
+        """
+        if self._engine is not None:
+            return
+
+        kwargs: dict[str, Any] = {"echo": self._echo, **self._engine_kwargs}
+        connect_args = dict(self._connect_args)
+
+        if self.is_sqlite:
+            connect_args.setdefault("check_same_thread", False)
+        else:
+            kwargs.setdefault("pool_pre_ping", True)
+            kwargs.setdefault("pool_recycle", self._pool_recycle)
+            kwargs.setdefault("pool_size", self._pool_size)
+            kwargs.setdefault("max_overflow", self._max_overflow)
+
+        if connect_args:
+            kwargs["connect_args"] = connect_args
+        if self._poolclass is not None:
+            kwargs["poolclass"] = self._poolclass
+
+        self._engine = create_async_engine(self.db_url, **kwargs)
+        self._session_maker = async_sessionmaker(
+            self._engine,
+            expire_on_commit=False,
+            class_=AsyncSession,
+        )
+
+    async def disconnect(self) -> None:
+        """Dispose the engine and clear the session factory.
+
+        Safe to call multiple times.
+        """
+        if self._engine is not None:
+            await self._engine.dispose()
+            self._engine = None
+            self._session_maker = None
+
+    def _require_session_maker(self) -> async_sessionmaker[AsyncSession]:
+        """Return the session maker, raising if uninitialized.
+
+        Returns:
+            async_sessionmaker[AsyncSession]: The configured factory.
+
+        Raises:
+            RuntimeError: If :meth:`connect` has not run yet.
+        """
+        if self._session_maker is None:
+            raise RuntimeError(
+                "AsyncDatabaseManager is not connected. "
+                "Call await manager.connect() before using sessions."
+            )
+        return self._session_maker
+
+    async def get_session(self) -> AsyncSession:
+        """Return a new ``AsyncSession`` bound to the engine.
+
+        Lazy-connects on first use. The caller is responsible for
+        closing the session (use :meth:`get_session_context` for
+        managed lifecycle).
+
+        Returns:
+            AsyncSession: A new session.
+        """
+        if self._engine is None:
+            await self.connect()
+        return self._require_session_maker()()
+
+    @asynccontextmanager
+    async def get_session_context(self) -> AsyncGenerator[AsyncSession]:
+        """Yield a session that auto-commits on exit and rolls back on error.
+
+        Yields:
+            AsyncSession: A managed session.
+
+        Raises:
+            Exception: Re-raises whatever the caller raised inside
+                the ``async with`` block, after rolling back.
+        """
+        if self._engine is None:
+            await self.connect()
+        session = self._require_session_maker()()
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+        finally:
+            await session.close()
+
+    async def session_dependency(self) -> AsyncGenerator[AsyncSession]:
+        """FastAPI dependency yielding one session per request.
+
+        Use as ``Depends(db.session_dependency)``. Differs from
+        :meth:`get_session_context` in that it does **not** commit on
+        success — commits are the responsibility of the service /
+        repository layer. The session is closed when the request
+        scope ends; failures bubble up unchanged.
+
+        Yields:
+            AsyncSession: A request-scoped session.
+        """
+        if self._engine is None:
+            await self.connect()
+        session = self._require_session_maker()()
+        try:
+            yield session
+        finally:
+            await session.close()
+
+    async def health_check(self) -> bool:
+        """Return whether a trivial ``SELECT 1`` succeeds.
+
+        Suitable for ``/health`` endpoints. Swallows every exception
+        and returns ``False`` so callers can branch on the result
+        without dealing with driver-specific error types.
+
+        Returns:
+            bool: ``True`` when the database responded with ``1``,
+            ``False`` on any failure.
+        """
+        try:
+            if self._engine is None:
+                await self.connect()
+            async with self._require_session_maker()() as session:
+                result = await session.execute(text("SELECT 1"))
+                return result.scalar() == 1
+        except Exception:
+            return False
+
+    async def create_tables(self) -> None:
+        """Issue ``CREATE TABLE`` for every model registered on ``BaseModel``.
+
+        Intended for tests and local development. Production schemas
+        should be managed by Alembic (see
+        :class:`tempest_fastapi_sdk.db.migrations.AlembicHelper`).
+        """
+        if self._engine is None:
+            await self.connect()
+        if self._engine is None:
+            raise RuntimeError("Engine is not connected.")
+        async with self._engine.begin() as conn:
+            await conn.run_sync(BaseModel.metadata.create_all)
+
+    async def drop_tables(self) -> None:
+        """Issue ``DROP TABLE`` for every model registered on ``BaseModel``.
+
+        Intended for tests and local development.
+        """
+        if self._engine is None:
+            await self.connect()
+        if self._engine is None:
+            raise RuntimeError("Engine is not connected.")
+        async with self._engine.begin() as conn:
+            await conn.run_sync(BaseModel.metadata.drop_all)
+
+
+__all__: list[str] = [
+    "AsyncDatabaseManager",
+]