fastapi-restly 0.5.0__py3-none-any.whl

fastapi_restly/__init__.py

@@ -0,0 +1,106 @@
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _version
+
+# Database layer
+from .db import (
+    AsyncSessionDep,
+    SessionDep,
+    configure,
+    get_async_engine,
+    get_engine,
+    open_async_session,
+    open_session,
+)
+from .exceptions import RestlyConfigurationError, RestlyError
+
+# Model base classes
+from .models import DataclassBase, IDBase, IDMixin, TimestampsMixin
+
+# List endpoint query parameters
+from .query import apply_list_params, create_list_params_schema
+
+# Schema utilities
+from .schemas import (
+    BaseSchema,
+    IDRef,
+    IDSchema,
+    ReadOnly,
+    TimestampsSchemaMixin,
+    WriteOnly,
+)
+
+# Views
+from .views import (
+    AsyncReactAdminView,
+    AsyncRestView,
+    ListingResult,
+    ReactAdminView,
+    RestView,
+    View,
+    ViewRoute,
+    delete,
+    get,
+    include_view,
+    patch,
+    post,
+    put,
+    route,
+)
+
+try:
+    __version__ = _version("fastapi-restly")
+except _PackageNotFoundError:  # pragma: no cover - only possible from an unpackaged tree
+    __version__ = "0+unknown"
+
+# Public API surface for fastapi-restly.
+#
+# This top-level namespace is the primary public API. Submodule ``__all__``
+# lists may expose additional supported advanced symbols for users working in
+# that subsystem, such as ``from fastapi_restly.views import BaseRestView``.
+__all__ = [
+    "__version__",
+    # Database — session context managers
+    "open_async_session",
+    "open_session",
+    # Database — FastAPI dependencies
+    "AsyncSessionDep",
+    "SessionDep",
+    # Database — engine access
+    "get_async_engine",
+    "get_engine",
+    # Database — setup & utilities
+    "configure",
+    # Exceptions
+    "RestlyError",
+    "RestlyConfigurationError",
+    # Models
+    "DataclassBase",
+    "IDBase",
+    "IDMixin",
+    "TimestampsMixin",
+    # List endpoint query parameters
+    "apply_list_params",
+    "create_list_params_schema",
+    # Schemas
+    "BaseSchema",
+    "IDRef",
+    "IDSchema",
+    "ReadOnly",
+    "WriteOnly",
+    "TimestampsSchemaMixin",
+    # Views
+    "RestView",
+    "AsyncRestView",
+    "ListingResult",
+    "AsyncReactAdminView",
+    "ReactAdminView",
+    "View",
+    "ViewRoute",
+    "delete",
+    "get",
+    "include_view",
+    "patch",
+    "post",
+    "put",
+    "route",
+]

fastapi_restly/_exception_handlers.py

@@ -0,0 +1,194 @@
+"""Default FastAPI exception handlers installed by fastapi-restly.
+
+Currently this module provides a translation layer from SQLAlchemy
+:class:`~sqlalchemy.exc.IntegrityError` (unique-constraint, foreign-key,
+not-null, and check-constraint violations) into a clean HTTP 409 Conflict
+response. Without this handler, an ``IntegrityError`` bubbles up to FastAPI
+and turns into a 500 Internal Server Error, which is misleading for clients
+(the server is fine; the request conflicts with the current state of the
+resource).
+
+The handler is installed automatically by :func:`fastapi_restly.configure`
+and as a fallback by :func:`fastapi_restly.include_view`. Users can opt out
+by calling ``fr.configure(install_default_exception_handlers=False)`` or by
+registering their own handler for ``IntegrityError`` *before* the framework
+gets a chance to install one.
+
+The detail-message extraction is best-effort: it understands the most common
+PostgreSQL SQLSTATE codes (via psycopg's ``orig.pgcode``) and the SQLite
+error-message conventions. For unrecognised dialects/messages we fall back
+to a generic conflict message that includes a truncated version of the
+underlying error text.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from sqlalchemy.exc import IntegrityError
+
+# Maximum length of original-error text we are willing to echo back. Keeps
+# response bodies sane and avoids accidentally leaking long SQL strings.
+_MAX_ORIG_TEXT_LENGTH = 500
+
+# Marker stored on ``app.state`` so we know we've already installed our
+# handlers on this FastAPI instance. Public so it is easy to inspect from
+# tests or user code.
+_HANDLERS_INSTALLED_FLAG = "_fr_default_exception_handlers_installed"
+
+
+# ---------------------------------------------------------------------------
+# Detail extraction
+# ---------------------------------------------------------------------------
+
+
+# PostgreSQL SQLSTATE codes — see
+# https://www.postgresql.org/docs/current/errcodes-appendix.html (class 23
+# "Integrity Constraint Violation").
+_PG_SQLSTATE_DETAILS: dict[str, str] = {
+    "23505": "Unique constraint violated",
+    "23503": "Foreign key constraint violated",
+    "23502": "Not-null constraint violated",
+    "23514": "Check constraint violated",
+    "23000": "Integrity constraint violated",
+    "23001": "Restrict violation",
+    "23P01": "Exclusion constraint violated",
+}
+
+
+def _extract_postgres_detail(orig: Any) -> str | None:
+    """Return a user-facing detail message for a Postgres-driver error.
+
+    Looks at ``orig.pgcode`` (set by psycopg / psycopg2 / asyncpg-via-psycopg)
+    and, when available, ``orig.diag.constraint_name`` /
+    ``orig.diag.column_name`` to enrich the message.
+    """
+    pgcode = getattr(orig, "pgcode", None)
+    if not pgcode:
+        return None
+
+    base = _PG_SQLSTATE_DETAILS.get(pgcode)
+    if base is None:
+        return None
+
+    # ``diag`` is a psycopg-specific attribute holding fielded error info.
+    diag = getattr(orig, "diag", None)
+    constraint_name = getattr(diag, "constraint_name", None) if diag else None
+    column_name = getattr(diag, "column_name", None) if diag else None
+
+    if pgcode == "23505" and constraint_name:
+        return f"{base}: {constraint_name}"
+    if pgcode == "23503" and constraint_name:
+        return f"{base}: {constraint_name}"
+    if pgcode == "23502" and column_name:
+        return f"{base} on column {column_name!r}"
+    if pgcode == "23514" and constraint_name:
+        return f"{base}: {constraint_name}"
+    return base
+
+
+# Mapping from SQLite error-message prefixes to a clean detail message.
+# SQLite's IntegrityError.args[0] (and ``str(orig)``) follow predictable
+# patterns, e.g. ``"UNIQUE constraint failed: user.username"``.
+_SQLITE_PREFIX_DETAILS: tuple[tuple[str, str], ...] = (
+    ("UNIQUE constraint failed:", "Unique constraint violated"),
+    ("FOREIGN KEY constraint failed", "Foreign key constraint violated"),
+    ("NOT NULL constraint failed:", "Not-null constraint violated"),
+    ("CHECK constraint failed:", "Check constraint violated"),
+    ("PRIMARY KEY must be unique", "Unique constraint violated (primary key)"),
+)
+
+
+def _extract_sqlite_detail(orig: Any) -> str | None:
+    """Return a user-facing detail message for a SQLite-driver error."""
+    text = str(orig).strip()
+    if not text:
+        return None
+
+    for prefix, base in _SQLITE_PREFIX_DETAILS:
+        if not text.startswith(prefix):
+            continue
+        # Try to surface the column / constraint info that SQLite tacks on
+        # after the colon. ``UNIQUE constraint failed: user.username`` →
+        # ``"Unique constraint violated on user.username"``.
+        remainder = text[len(prefix) :].strip().lstrip(":").strip()
+        if remainder:
+            return f"{base} on {remainder}"
+        return base
+    return None
+
+
+def _build_integrity_detail(exc: IntegrityError) -> str:
+    """Build a clean HTTP 409 detail message from a SQLAlchemy IntegrityError.
+
+    Best-effort across dialects:
+
+    * PostgreSQL — switches on ``exc.orig.pgcode`` (SQLSTATE class 23).
+    * SQLite — pattern-matches ``str(exc.orig)`` against known prefixes.
+    * Anything else — returns a generic fallback that includes a truncated
+      copy of the original error text so the body is still useful for
+      debugging without being huge.
+    """
+    orig = getattr(exc, "orig", None)
+    if orig is not None:
+        pg_detail = _extract_postgres_detail(orig)
+        if pg_detail is not None:
+            return pg_detail
+
+        sqlite_detail = _extract_sqlite_detail(orig)
+        if sqlite_detail is not None:
+            return sqlite_detail
+
+    # Generic fallback. Prefer the original driver error text (it's usually
+    # the most informative); truncate so we don't dump a giant SQL statement.
+    raw = str(orig) if orig is not None else str(exc)
+    raw = raw.strip()
+    if len(raw) > _MAX_ORIG_TEXT_LENGTH:
+        raw = raw[:_MAX_ORIG_TEXT_LENGTH] + "...(truncated)"
+
+    base = "Conflict with current state of the resource"
+    if raw:
+        return f"{base}: {raw}"
+    return base
+
+
+# ---------------------------------------------------------------------------
+# The handler & registration helper
+# ---------------------------------------------------------------------------
+
+
+def integrity_error_handler(request: Request, exc: Exception) -> JSONResponse:
+    """Translate a SQLAlchemy IntegrityError into HTTP 409 Conflict.
+
+    Signature uses ``Exception`` rather than ``IntegrityError`` to satisfy
+    Starlette's exception-handler typing; we narrow at runtime.
+    """
+    assert isinstance(exc, IntegrityError)  # noqa: S101 - registered for IntegrityError only
+    detail = _build_integrity_detail(exc)
+    return JSONResponse(status_code=409, content={"detail": detail})
+
+
+def register_default_exception_handlers(app: FastAPI) -> None:
+    """Idempotently install fastapi-restly default exception handlers on ``app``.
+
+    * Skips if a handler for :class:`IntegrityError` is already registered on
+      ``app`` — we always defer to the user.
+    * Skips if we have already installed handlers on this ``app`` instance
+      (so calling from both :func:`fastapi_restly.configure` and
+      :func:`fastapi_restly.include_view` is safe).
+    """
+    if getattr(app.state, _HANDLERS_INSTALLED_FLAG, False):
+        return
+
+    # Respect a user-registered handler if one is already in place.
+    if IntegrityError in app.exception_handlers:
+        setattr(app.state, _HANDLERS_INSTALLED_FLAG, True)
+        return
+
+    app.add_exception_handler(IntegrityError, integrity_error_handler)
+    setattr(app.state, _HANDLERS_INSTALLED_FLAG, True)
+
+
+__all__ = ["integrity_error_handler", "register_default_exception_handlers"]

fastapi_restly/_pytest_fixtures.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+import traceback
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, AsyncIterator, Iterator
+from unittest.mock import MagicMock, patch
+
+import alembic
+import alembic.command
+import alembic.config
+import pytest
+from fastapi import FastAPI
+from sqlalchemy.ext.asyncio import AsyncConnection
+from sqlalchemy.ext.asyncio import AsyncSession as SA_AsyncSession
+from sqlalchemy.orm import Session as SA_Session
+
+from .db import activate_savepoint_only_mode
+from .db._globals import _fr_globals, _get_restly_context
+
+if TYPE_CHECKING:
+    from .testing._client import RestlyTestClient
+
+try:
+    import pytest_asyncio
+except ModuleNotFoundError as exc:
+    if exc.name != "pytest_asyncio":
+        raise
+    pytest_asyncio = None
+
+_TESTING_EXTRA_MESSAGE = (
+    "fastapi_restly.pytest_fixtures requires optional testing dependencies. "
+    'Install them with: pip install "fastapi-restly[testing]"'
+)
+
+
+@pytest.fixture(scope="session")
+def restly_project_root() -> Path:
+    """Return the project root directory."""
+    # Try to find the project root by looking for pyproject.toml
+    current = Path.cwd()
+    while current != current.parent:
+        if (current / "pyproject.toml").exists():
+            return current
+        current = current.parent
+    raise Exception("Could not find a pyproject.toml to establish project root")
+
+
+def _run_alembic_upgrade(project_root: Path) -> None:
+    # Only run alembic migrations if the alembic directory exists
+    alembic_dir = project_root / "alembic"
+    if not alembic_dir.exists():
+        return  # Skip if no alembic directory
+
+    # restly_project_root owns discovery; this helper only builds Alembic config.
+    alembic_cfg = alembic.config.Config(project_root / "alembic.ini")
+    alembic_cfg.set_main_option("script_location", str(alembic_dir))
+    try:
+        alembic.command.upgrade(alembic_cfg, "head")
+    except Exception as exc:
+        tb = traceback.format_exc()
+        pytest.exit(
+            f"Alembic migrations failed: {exc}\n\nTraceback:\n{tb}", returncode=1
+        )
+
+
+def _activate_savepoint_only_mode_sessions() -> None:
+    # Only run if database connections are set up
+    if not _fr_globals.async_make_session and not _fr_globals.make_session:
+        return  # Skip if no database connections
+
+    if _fr_globals.async_make_session:
+        activate_savepoint_only_mode(_fr_globals.async_make_session)
+    if _fr_globals.make_session:
+        activate_savepoint_only_mode(_fr_globals.make_session)
+
+
+@pytest.fixture
+def _shared_connection():
+    # Sync tests need a sync sessionmaker, but async-only projects should still
+    # be able to use the restly_async_session fixture without one.
+    if not _fr_globals.make_session:
+        yield None
+        return
+
+    engine = _fr_globals.make_session.kw["bind"]
+    with engine.connect() as conn:
+        yield conn
+
+
+if pytest_asyncio is None:
+
+    @pytest.fixture
+    def restly_async_session(_shared_connection) -> None:  # pyright: ignore[reportRedeclaration]
+        # The else-branch defines the real async fixture; this stub only
+        # runs when the optional ``pytest_asyncio`` extra isn't installed.
+        # Pyright cannot model mutually exclusive module-level branches.
+        raise ModuleNotFoundError(_TESTING_EXTRA_MESSAGE, name="pytest_asyncio")
+
+else:
+
+    @pytest_asyncio.fixture
+    async def restly_async_session(_shared_connection) -> AsyncIterator[SA_AsyncSession]:
+        """
+        Pytest fixture providing a database session with savepoint-based isolation.
+
+        Each test runs inside a savepoint. At the end of the test, the savepoint is
+        rolled back, leaving the database clean for the next test.
+
+        NOTE: Calling session.rollback() inside a test rolls back to the last savepoint
+        (created by each patched commit()), NOT to the start of the test. This differs
+        from production behavior. To undo all changes in a test, use session.rollback()
+        after each commit(), but be aware that data added before the last commit() is
+        still visible.
+        """
+        # Only run if database connections are set up
+        if not _fr_globals.async_make_session:
+            pytest.skip("Database connection not set up")
+
+        async_engine = _fr_globals.async_make_session.kw["bind"]
+
+        @asynccontextmanager
+        async def get_bound_async_connection():
+            if _shared_connection is None:
+                async with async_engine.connect() as async_conn:
+                    yield async_conn
+                return
+
+            async_conn = AsyncConnection(
+                async_engine, sync_connection=_shared_connection
+            )
+            async with async_conn:
+                yield async_conn
+
+        async with get_bound_async_connection() as async_conn:
+            async with _fr_globals.async_make_session(bind=async_conn) as sess:
+                class AsyncSessionContext:
+                    def __init__(self, *, flush_on_success: bool) -> None:
+                        self.flush_on_success = flush_on_success
+
+                    async def __aenter__(self):
+                        await sess.begin_nested()
+                        return sess
+
+                    async def __aexit__(self, exc_type, exc_value, tb):
+                        if self.flush_on_success and exc_type is None:
+                            await sess.flush()
+                        return False  # re-raise any exception
+
+                mock_sessionmaker = MagicMock()
+                mock_sessionmaker.side_effect = lambda *args, **kwargs: (
+                    AsyncSessionContext(flush_on_success=False)
+                )
+                # session.begin() is used as a context manager (async with
+                # session.begin():). Return the same isolated session and flush
+                # pending changes after successful explicit transaction blocks.
+                mock_sessionmaker.begin.side_effect = lambda *args, **kwargs: (
+                    AsyncSessionContext(flush_on_success=True)
+                )
+
+                async def passthrough_exit(self, exc_type, exc_value, traceback):
+                    await sess.flush()
+                    return False  # re-raise any exception
+
+                async def patched_commit(self):
+                    await sess.flush()
+                    await sess.begin_nested()
+
+                globals_obj = _get_restly_context()
+                original_async_make_session = globals_obj.async_make_session
+                globals_obj.async_make_session = mock_sessionmaker
+                try:
+                    with (
+                        patch.object(SA_AsyncSession, "__aexit__", passthrough_exit),
+                        patch.object(SA_AsyncSession, "commit", patched_commit),
+                    ):
+                        yield sess
+                finally:
+                    globals_obj.async_make_session = original_async_make_session
+
+
+@pytest.fixture
+def restly_session(_shared_connection) -> Iterator[SA_Session]:
+    """
+    Pytest fixture providing a database session with savepoint-based isolation.
+
+    Each test runs inside a savepoint. At the end of the test, the savepoint is
+    rolled back, leaving the database clean for the next test.
+
+    NOTE: Calling session.rollback() inside a test rolls back to the last savepoint
+    (created by each patched commit()), NOT to the start of the test. This differs
+    from production behavior. To undo all changes in a test, use session.rollback()
+    after each commit(), but be aware that data added before the last commit() is
+    still visible.
+    """
+    # Only run if database connections are set up
+    if not _fr_globals.make_session:
+        pytest.skip("Database connection not set up")
+
+    with _fr_globals.make_session(bind=_shared_connection) as sess:
+
+        def begin_nested():
+            sess.begin_nested()
+            return sess
+
+        mock_sessionmaker = MagicMock()
+        mock_sessionmaker.side_effect = begin_nested
+        # session.begin() is used as a context manager (with session.begin():)
+        # We need it to also return our savepoint session so explicit transaction
+        # blocks work correctly with our isolation mechanism
+        mock_sessionmaker.begin.return_value.__enter__.side_effect = begin_nested
+
+        def exit_nested(exc_type, exc_value, tb):
+            if exc_type is None:
+                sess.flush()
+            return False  # re-raise any exception
+
+        def passthrough_exit(self, exc_type, exc_value, traceback):
+            sess.flush()
+            return False  # re-raise any exception
+
+        def patched_commit(self):
+            sess.flush()
+            sess.begin_nested()
+
+        globals_obj = _get_restly_context()
+        original_make_session = globals_obj.make_session
+        globals_obj.make_session = mock_sessionmaker
+        try:
+            with (
+                patch.object(SA_Session, "__exit__", passthrough_exit),
+                patch.object(SA_Session, "commit", patched_commit),
+            ):
+                mock_sessionmaker.begin.return_value.__exit__.side_effect = exit_nested
+                yield sess
+        finally:
+            globals_obj.make_session = original_make_session
+
+
+@pytest.fixture
+def restly_app() -> FastAPI:
+    """Create a FastAPI app instance for testing."""
+    return FastAPI()
+
+
+@pytest.fixture
+def restly_client(restly_app) -> RestlyTestClient:
+    """Create a RestlyTestClient instance for testing."""
+    try:
+        from .testing._client import RestlyTestClient
+    except ModuleNotFoundError as exc:
+        if exc.name == "httpx":
+            raise ModuleNotFoundError(_TESTING_EXTRA_MESSAGE, name="httpx") from exc
+        raise
+
+    return RestlyTestClient(restly_app)

fastapi_restly/db/__init__.py

@@ -0,0 +1,31 @@
+from ._proxy import open_async_session, open_session
+from ._session import (
+    AsyncSessionDep,
+    SessionDep,
+    activate_savepoint_only_mode,
+    configure,
+    deactivate_savepoint_only_mode,
+    get_async_engine,
+    get_engine,
+)
+
+# Public API for ``fastapi_restly.db``.
+#
+# Session generator internals live in private modules; use ``configure`` to
+# configure the process-wide Restly runtime state.
+__all__ = [
+    # Session context managers
+    "open_async_session",
+    "open_session",
+    # FastAPI dependencies
+    "AsyncSessionDep",
+    "SessionDep",
+    # Engine access
+    "get_async_engine",
+    "get_engine",
+    # Setup
+    "configure",
+    # Savepoint mode
+    "activate_savepoint_only_mode",
+    "deactivate_savepoint_only_mode",
+]

fastapi_restly/db/_globals.py

@@ -0,0 +1,76 @@
+from collections.abc import AsyncIterator, Callable, Iterator
+from contextvars import ContextVar, Token
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession as SA_AsyncSession
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlalchemy.orm import Session as SA_Session
+from sqlalchemy.orm import sessionmaker
+
+
+class RestlyContext:
+    """Private container for Restly runtime state used by tests and internals."""
+
+    __slots__ = (
+        "async_database_url",
+        "async_make_session",
+        "commit_session_on_response",
+        "database_url",
+        "make_session",
+        "session_generator",
+        "sync_session_generator",
+    )
+
+    async_database_url: str | None
+    async_make_session: async_sessionmaker[Any] | None
+    commit_session_on_response: bool
+    database_url: str | None
+    make_session: sessionmaker[Any] | None
+    session_generator: Callable[[], AsyncIterator[SA_AsyncSession]] | None
+    sync_session_generator: Callable[[], Iterator[SA_Session]] | None
+
+    def __init__(self) -> None:
+        self.async_database_url = None
+        self.async_make_session = None
+        self.commit_session_on_response = True
+        self.database_url = None
+        self.make_session = None
+        self.session_generator = None
+        self.sync_session_generator = None
+
+    def __enter__(self) -> "RestlyContext":
+        token = _restly_context_ctx.set(self)
+        _restly_context_token_stack.set(_restly_context_token_stack.get() + (token,))
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        token_stack = _restly_context_token_stack.get()
+        if not token_stack:
+            raise RuntimeError("RestlyContext was exited without being entered.")
+        token = token_stack[-1]
+        _restly_context_token_stack.set(token_stack[:-1])
+        _restly_context_ctx.reset(token)
+
+
+_default_context = RestlyContext()
+_restly_context_ctx: ContextVar[RestlyContext | None] = ContextVar(
+    "fastapi_restly_context", default=None
+)
+_restly_context_token_stack: ContextVar[tuple[Token[RestlyContext | None], ...]] = (
+    ContextVar("fastapi_restly_context_token_stack", default=())
+)
+
+
+def _get_restly_context() -> RestlyContext:
+    return _restly_context_ctx.get() or _default_context
+
+
+class _FRGlobalsProxy:
+    def __getattr__(self, name: str):
+        return getattr(_get_restly_context(), name)
+
+    def __setattr__(self, name: str, value):
+        setattr(_get_restly_context(), name, value)
+
+
+_fr_globals = _FRGlobalsProxy()