fastapi-restly 3.0.0rc1__py3-none-any.whl

fastapi_restly/__init__.py

@@ -0,0 +1,131 @@
+# Database layer
+from .db import (
+    AsyncSessionDep,
+    FRGlobals,
+    RestlyContext,
+    SessionDep,
+    activate_savepoint_only_mode,
+    async_open_session,
+    configure,
+    deactivate_savepoint_only_mode,
+    get_async_engine,
+    get_engine,
+    get_fr_globals,
+    open_session,
+    use_fr_globals,
+)
+
+# Model base classes
+from .models import (
+    DataclassBase,
+    IDBase,
+    IDMixin,
+    IDStampsBase,
+    TimestampsMixin,
+    async_get_one_or_create,
+    get_one_or_create,
+)
+
+# List endpoint query parameters
+from .query import apply_list_params, create_list_params_schema
+
+# Schema utilities
+from .schemas import (
+    BaseSchema,
+    IDRef,
+    IDSchema,
+    IDStampsSchema,
+    ReadOnly,
+    TimestampsSchemaMixin,
+    WriteOnly,
+    create_schema_from_model,
+    resolve_ids_to_sqlalchemy_objects,
+)
+
+# Views
+from .views import (
+    AsyncReactAdminView,
+    AsyncRestView,
+    ReactAdminView,
+    RestView,
+    View,
+    async_make_new_object,
+    async_save_object,
+    async_update_object,
+    delete,
+    get,
+    include_view,
+    make_new_object,
+    patch,
+    post,
+    put,
+    route,
+    save_object,
+    update_object,
+)
+
+# Public API surface for fastapi-restly.
+#
+# Anything not listed here is considered internal and may change without
+# warning. Submodule ``__init__.py`` files have their own (narrower)
+# ``__all__`` lists for submodule-level imports such as
+# ``from fastapi_restly.schemas import ReadOnly``.
+__all__ = [
+    # Database — session context managers
+    "async_open_session",
+    "open_session",
+    # Database — FastAPI dependencies
+    "AsyncSessionDep",
+    "SessionDep",
+    # Database — engine access
+    "get_async_engine",
+    "get_engine",
+    # Database — setup & utilities
+    "configure",
+    "activate_savepoint_only_mode",
+    "deactivate_savepoint_only_mode",
+    "RestlyContext",
+    "FRGlobals",
+    "get_fr_globals",
+    "use_fr_globals",
+    # Models
+    "DataclassBase",
+    "IDBase",
+    "IDMixin",
+    "IDStampsBase",
+    "TimestampsMixin",
+    "async_get_one_or_create",
+    "get_one_or_create",
+    # List endpoint query parameters
+    "apply_list_params",
+    "create_list_params_schema",
+    # Schemas
+    "BaseSchema",
+    "IDRef",
+    "IDSchema",
+    "IDStampsSchema",
+    "ReadOnly",
+    "WriteOnly",
+    "TimestampsSchemaMixin",
+    "create_schema_from_model",
+    "resolve_ids_to_sqlalchemy_objects",
+    # Views
+    "RestView",
+    "AsyncRestView",
+    "AsyncReactAdminView",
+    "ReactAdminView",
+    "View",
+    "async_make_new_object",
+    "async_save_object",
+    "async_update_object",
+    "delete",
+    "get",
+    "include_view",
+    "make_new_object",
+    "patch",
+    "post",
+    "put",
+    "route",
+    "save_object",
+    "update_object",
+]

fastapi_restly/_exceptions.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/db/__init__.py

@@ -0,0 +1,48 @@
+from ._globals import (
+    FRGlobals,
+    RestlyContext,
+    fr_globals,
+    get_fr_globals,
+    use_fr_globals,
+)
+from ._proxy import async_open_session, open_session
+from ._session import (
+    AsyncSessionDep,
+    SessionDep,
+    activate_savepoint_only_mode,
+    async_generate_session,
+    configure,
+    deactivate_savepoint_only_mode,
+    generate_session,
+    get_async_engine,
+    get_engine,
+)
+
+# Public API for ``fastapi_restly.db``.
+#
+# ``async_generate_session`` and ``generate_session`` remain importable for
+# advanced users (and existing tests) who plug a custom session generator
+# into ``fr_globals``, but they are not part of the supported public API
+# and may move into a private module in a future release.
+__all__ = [
+    # Session context managers
+    "async_open_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",
+    # Globals
+    "RestlyContext",
+    "FRGlobals",
+    "fr_globals",
+    "get_fr_globals",
+    "use_fr_globals",
+]

fastapi_restly/db/_globals.py

@@ -0,0 +1,92 @@
+from collections.abc import AsyncIterator, Callable, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+
+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:
+    """Container for Restly runtime state.
+
+    Most applications use the default process-wide context by calling
+    ``fr.configure(...)`` directly. Create a ``RestlyContext`` when you need
+    isolated Restly state in the same process, for example for tests or
+    multiple FastAPI apps.
+    """
+
+    __slots__ = (
+        "async_database_url",
+        "async_make_session",
+        "database_url",
+        "make_session",
+        "session_generator",
+        "sync_session_generator",
+    )
+
+    async_database_url: str | None
+    async_make_session: async_sessionmaker[SA_AsyncSession] | None
+    database_url: str | None
+    make_session: sessionmaker[SA_Session] | 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.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)
+
+
+FRGlobals = RestlyContext
+
+
+_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
+
+
+def get_fr_globals() -> FRGlobals:
+    return _get_restly_context()
+
+
+@contextmanager
+def use_fr_globals(globals_obj: FRGlobals) -> Iterator[None]:
+    with globals_obj:
+        yield
+
+
+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()

fastapi_restly/db/_proxy.py

@@ -0,0 +1,37 @@
+from contextlib import asynccontextmanager, contextmanager
+from typing import AsyncIterator, Iterator
+
+from sqlalchemy.ext.asyncio import AsyncSession as SA_AsyncSession
+from sqlalchemy.orm import Session as SA_Session
+
+from ._globals import fr_globals
+
+
+@asynccontextmanager
+async def async_open_session() -> AsyncIterator[SA_AsyncSession]:
+    """Open an async database session for use outside of request context.
+
+    Example::
+
+        async with fr.async_open_session() as session:
+            result = await session.execute(select(User))
+    """
+    if fr_globals.async_make_session is None:
+        raise RuntimeError("Call fr.configure() before using async_open_session().")
+    async with fr_globals.async_make_session() as sess:
+        yield sess
+
+
+@contextmanager
+def open_session() -> Iterator[SA_Session]:
+    """Open a sync database session for use outside of request context.
+
+    Example::
+
+        with fr.open_session() as session:
+            result = session.execute(select(User))
+    """
+    if fr_globals.make_session is None:
+        raise RuntimeError("Call fr.configure() before using open_session().")
+    with fr_globals.make_session() as sess:
+        yield sess