fastapi-restly 0.5.0__py3-none-any.whl

fastapi_restly/db/_proxy.py

@@ -0,0 +1,42 @@
+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 ..exceptions import RestlyConfigurationError
+from ._globals import _fr_globals
+
+
+@asynccontextmanager
+async def open_async_session() -> AsyncIterator[SA_AsyncSession]:
+    """Open an async database session for use outside of request context.
+
+    Example::
+
+        async with fr.open_async_session() as session:
+            result = await session.execute(select(User))
+    """
+    if _fr_globals.async_make_session is None:
+        raise RestlyConfigurationError(
+            "Call fr.configure() before using open_async_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 RestlyConfigurationError(
+            "Call fr.configure() before using open_session()."
+        )
+    with _fr_globals.make_session() as sess:
+        yield sess

fastapi_restly/db/_session.py

@@ -0,0 +1,275 @@
+from collections.abc import AsyncIterator, Callable, Iterator
+from inspect import signature
+from typing import Annotated, Any, cast
+
+from fastapi import Depends, FastAPI
+from sqlalchemy import Engine, create_engine
+from sqlalchemy.ext.asyncio import AsyncEngine, async_sessionmaker, create_async_engine
+from sqlalchemy.ext.asyncio import AsyncSession as SA_AsyncSession
+from sqlalchemy.orm import Session as SA_Session
+from sqlalchemy.orm import sessionmaker
+
+from .._exception_handlers import register_default_exception_handlers
+from ..exceptions import RestlyConfigurationError
+from ._globals import _fr_globals
+
+try:
+    import orjson
+except ImportError:
+    json_deserializer = None
+    json_serializer = None
+else:
+
+    def orjson_serializer(obj):
+        return orjson.dumps(
+            obj, option=orjson.OPT_NAIVE_UTC | orjson.OPT_NON_STR_KEYS
+        ).decode()
+
+    json_deserializer = orjson.loads
+    json_serializer = orjson_serializer
+
+
+def _setup_async_database_connection(
+    async_database_url: str | None = None,
+    *,
+    async_engine: AsyncEngine | None = None,
+    async_make_session: async_sessionmaker[Any] | None = None,
+) -> async_sessionmaker[Any]:
+    if not async_make_session:
+        if not async_engine:
+            async_engine = create_async_engine(
+                async_database_url,  # type: ignore[arg-type]
+                json_serializer=json_serializer,
+                json_deserializer=json_deserializer,
+            )
+        async_make_session = async_sessionmaker(
+            bind=async_engine, autoflush=False, expire_on_commit=False
+        )
+
+    _fr_globals.async_database_url = async_database_url
+    _fr_globals.async_make_session = async_make_session
+    return async_make_session
+
+
+def _setup_database_connection(
+    database_url: str | None = None,
+    *,
+    engine: Engine | None = None,
+    make_session: sessionmaker[Any] | None = None,
+) -> sessionmaker[Any]:
+    if make_session is None:
+        if engine is None:
+            engine = create_engine(
+                database_url,  # type: ignore[arg-type]
+                json_serializer=json_serializer,
+                json_deserializer=json_deserializer,
+            )
+        make_session = sessionmaker(bind=engine, expire_on_commit=False)
+
+    _fr_globals.database_url = database_url
+    _fr_globals.make_session = make_session
+    return make_session
+
+
+def configure(
+    app: FastAPI | None = None,
+    *,
+    async_database_url: str | None = None,
+    async_engine: AsyncEngine | None = None,
+    async_make_session: async_sessionmaker[Any] | None = None,
+    database_url: str | None = None,
+    engine: Engine | None = None,
+    make_session: sessionmaker[Any] | None = None,
+    session_generator: Callable[[], AsyncIterator[SA_AsyncSession]] | None = None,
+    sync_session_generator: Callable[[], Iterator[SA_Session]] | None = None,
+    commit_session_on_response: bool | None = None,
+    install_default_exception_handlers: bool = True,
+) -> None:
+    """Configure FastAPI-Restly. Call once at startup.
+
+    Pass async parameters (``async_database_url``, ``async_engine``, or
+    ``async_make_session``) to enable async support, sync parameters
+    (``database_url``, ``engine``, or ``make_session``) for sync support,
+    or both if your application uses both.
+
+    Use ``session_generator`` / ``sync_session_generator`` to plug in a
+    custom session factory instead of the built-in one.
+
+    By default, Restly commits built-in request sessions when an endpoint
+    successfully produces a response. Set ``commit_session_on_response=False``
+    to own commit/rollback calls yourself. Leave it unset to keep the current
+    default. Custom session generators always own their transaction lifecycle.
+
+    Pass your :class:`FastAPI` ``app`` to install fastapi-restly's default
+    exception handlers (currently: a translator that turns SQLAlchemy
+    :class:`~sqlalchemy.exc.IntegrityError` into HTTP 409 Conflict). Set
+    ``install_default_exception_handlers=False`` to opt out. If you do not
+    pass ``app`` here, the handlers are registered the first time a view is
+    mounted via :func:`fastapi_restly.include_view` instead.
+    """
+    if not any(
+        (
+            async_database_url is not None,
+            async_engine is not None,
+            async_make_session is not None,
+            database_url is not None,
+            engine is not None,
+            make_session is not None,
+            session_generator is not None,
+            sync_session_generator is not None,
+            commit_session_on_response is not None,
+            app is not None and install_default_exception_handlers,
+        )
+    ):
+        raise TypeError("fr.configure() requires at least one setup argument.")
+
+    if commit_session_on_response is not None:
+        _fr_globals.commit_session_on_response = commit_session_on_response
+    if (
+        async_database_url is not None
+        or async_engine is not None
+        or async_make_session is not None
+    ):
+        _setup_async_database_connection(
+            async_database_url=async_database_url,
+            async_engine=async_engine,
+            async_make_session=async_make_session,
+        )
+    if database_url is not None or engine is not None or make_session is not None:
+        _setup_database_connection(
+            database_url=database_url, engine=engine, make_session=make_session
+        )
+    if session_generator is not None:
+        _fr_globals.session_generator = session_generator
+    if sync_session_generator is not None:
+        _fr_globals.sync_session_generator = sync_session_generator
+    if app is not None and install_default_exception_handlers:
+        register_default_exception_handlers(app)
+
+
+def activate_savepoint_only_mode(
+    make_session: async_sessionmaker[Any] | sessionmaker[Any],
+) -> None:
+    """
+    Intended for use in tests. Puts the session factory into savepoint-only mode so
+    that no test data is ever committed to the database. Each test can roll back
+    instantly by closing the session, leaving the database clean for the next test.
+
+    This is done with "create_savepoint" mode and a wrapper on engine.connect() that
+    begins the outer transaction before the Session can use it.
+    https://docs.sqlalchemy.org/en/20/orm/session_transaction.html#session-external-transaction
+    """
+    engine = _get_sync_engine(make_session)
+
+    # Check if already activated (look for the marker attribute we set)
+    if hasattr(engine.connect, "_original_connect"):
+        return  # Already activated, skip
+
+    original_connect = engine.connect
+
+    def _begin_on_connect():
+        connection = original_connect()
+        connection.begin()
+        return connection
+
+    # Using setattr to silence pyright
+    setattr(_begin_on_connect, "_original_connect", original_connect)
+
+    engine.connect = _begin_on_connect
+    make_session.configure(join_transaction_mode="create_savepoint")
+
+
+def deactivate_savepoint_only_mode(
+    make_session: async_sessionmaker[Any] | sessionmaker[Any],
+) -> None:
+    """
+    Reverts the effect of `activate_savepoint_only_mode`.
+    Restores the original engine.connect and disables savepoint-only mode.
+    """
+    engine = _get_sync_engine(make_session)
+    _begin_on_connect = cast(Any, engine.connect)
+    if hasattr(_begin_on_connect, "_original_connect"):
+        # Restore the original connect that was saved by activate_savepoint_only_mode
+        engine.connect = _begin_on_connect._original_connect
+    # If engine was never activated, there is nothing to restore; this is safe to call
+
+    make_session.configure(join_transaction_mode=None)
+
+
+def get_async_engine() -> AsyncEngine:
+    """Return the async engine registered via configure()."""
+    if _fr_globals.async_make_session is None:
+        raise RestlyConfigurationError(
+            "Call fr.configure() before using get_async_engine()."
+        )
+    return _fr_globals.async_make_session.kw["bind"]
+
+
+def get_engine() -> Engine:
+    """Return the sync engine registered via configure()."""
+    if _fr_globals.make_session is None:
+        raise RestlyConfigurationError(
+            "Call fr.configure() before using get_engine()."
+        )
+    return _fr_globals.make_session.kw["bind"]
+
+
+def _get_sync_engine(make_session: async_sessionmaker[Any] | sessionmaker[Any]) -> Engine:
+    engine = make_session.kw["bind"]
+    if isinstance(engine, AsyncEngine):
+        return engine.sync_engine
+    return engine
+
+
+async def _async_generate_session() -> AsyncIterator[SA_AsyncSession]:
+    """FastAPI dependency for async database session."""
+    if _fr_globals.session_generator is not None:
+        async for session in _fr_globals.session_generator():
+            yield session
+        return
+    if _fr_globals.async_make_session is None:
+        raise RestlyConfigurationError(
+            "Call fr.configure() before using AsyncSessionDep."
+        )
+
+    # FastAPI does not support contextmanagers as dependency directly,
+    # but it does support generators.
+    async with _fr_globals.async_make_session() as session:
+        yield session
+        if _fr_globals.commit_session_on_response and session.is_active:
+            try:
+                await session.commit()
+            except Exception:
+                await session.rollback()
+                raise
+
+
+def _session_dependency(dependency: Callable[..., Any]) -> Any:
+    depends = cast(Callable[..., Any], Depends)
+    if "scope" in signature(Depends).parameters:
+        return depends(dependency, scope="function")
+    return depends(dependency)
+
+
+AsyncSessionDep = Annotated[SA_AsyncSession, _session_dependency(_async_generate_session)]
+
+
+def _generate_session() -> Iterator[SA_Session]:
+    """FastAPI dependency for sync database session."""
+    if _fr_globals.sync_session_generator is not None:
+        yield from _fr_globals.sync_session_generator()
+        return
+    if _fr_globals.make_session is None:
+        raise RestlyConfigurationError("Call fr.configure() before using SessionDep.")
+
+    with _fr_globals.make_session() as session:
+        yield session
+        if _fr_globals.commit_session_on_response and session.is_active:
+            try:
+                session.commit()
+            except Exception:
+                session.rollback()
+                raise
+
+
+SessionDep = Annotated[SA_Session, _session_dependency(_generate_session)]

fastapi_restly/exceptions.py

@@ -0,0 +1,12 @@
+"""Public exception hierarchy for FastAPI-Restly."""
+
+
+class RestlyError(Exception):
+    """Base class for FastAPI-Restly framework errors."""
+
+
+class RestlyConfigurationError(RestlyError):
+    """Raised when Restly is used before required configuration is available."""
+
+
+__all__ = ["RestlyConfigurationError", "RestlyError"]

fastapi_restly/models/__init__.py

@@ -0,0 +1,18 @@
+from ._base import (
+    CASCADE_ALL_ASYNC,
+    CASCADE_ALL_DELETE_ORPHAN_ASYNC,
+    DataclassBase,
+    IDBase,
+    IDMixin,
+    TimestampsMixin,
+)
+
+# Public API for ``fastapi_restly.models``.
+__all__ = [
+    "CASCADE_ALL_ASYNC",
+    "CASCADE_ALL_DELETE_ORPHAN_ASYNC",
+    "DataclassBase",
+    "IDBase",
+    "IDMixin",
+    "TimestampsMixin",
+]

fastapi_restly/models/_base.py

@@ -0,0 +1,84 @@
+import enum
+import re
+from datetime import datetime, timezone
+from typing import Any
+
+from sqlalchemy import Enum, func
+from sqlalchemy.orm import (
+    DeclarativeBase,
+    Mapped,
+    MappedAsDataclass,
+    declared_attr,
+    mapped_column,
+)
+
+# Provide an alternative settings for relationship cascade "all" and
+# "all, delete-orphan". The "refresh-expire" cascade will cause
+# issues in an async context. See also:
+# https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html#preventing-implicit-io-when-using-asyncsession
+# `CASCADE_ALL_ASYNC` should be used instead.
+CASCADE_ALL_ASYNC = "save-update, merge, delete, expunge"
+CASCADE_ALL_DELETE_ORPHAN_ASYNC = CASCADE_ALL_ASYNC + ", delete-orphan"
+
+
+def utc_now() -> datetime:
+    """Replacement for the deprecated datetime.utcnow()"""
+    return datetime.now(timezone.utc)
+
+
+class TimestampsMixin(MappedAsDataclass, kw_only=True):
+    """
+    Dataclass mixin adding UTC-aware created_at and updated_at timestamps.
+    """
+
+    created_at: Mapped[datetime] = mapped_column(
+        default_factory=utc_now, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        default_factory=utc_now, onupdate=utc_now, server_default=func.now()
+    )
+
+
+class IDMixin(MappedAsDataclass, kw_only=True):
+    """Dataclass mixin adding an auto-incrementing integer `id` primary key."""
+
+    id: Mapped[int] = mapped_column(init=False, primary_key=True)
+
+
+class TableNameMixin:
+    """Mixin that auto-generates snake_case table names from class names."""
+
+    @declared_attr
+    @classmethod
+    def __tablename__(cls) -> Any:
+        return underscore(cls.__name__)
+
+
+def underscore(name: str) -> str:
+    """Convert CamelCase class name to snake_case table name.
+
+    Handles acronyms correctly: HTTPServer -> http_server, XMLParser -> xml_parser.
+    """
+    # Insert underscore before an uppercase letter that follows a lowercase letter
+    s1 = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", name)
+    # Insert underscore before an uppercase letter that is followed by a lowercase letter
+    # (handles the end of an acronym: "HTTPServer" -> "HTTP_Server")
+    s2 = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", s1)
+    return s2.lower()
+
+
+class DataclassBase(TableNameMixin, MappedAsDataclass, DeclarativeBase, kw_only=True):
+    """SQLAlchemy declarative base with dataclass semantics."""
+
+    type_annotation_map = {
+        # native_enum=False so enums are persisted as strings in the
+        # database, not as Postgres TYPE objects. This prevents
+        # requiring database migrations for every enum change.
+        enum.Enum: Enum(enum.Enum, native_enum=False, length=64)
+    }
+
+
+class IDBase(IDMixin, DataclassBase):
+    """Convenience base: DataclassBase + integer `id` primary key."""
+
+    __abstract__ = True

fastapi_restly/objects.py

@@ -0,0 +1,144 @@
+from typing import TypeVar as _TypeVar
+
+import pydantic as _pydantic
+from sqlalchemy.ext.asyncio import AsyncSession as _AsyncSession
+from sqlalchemy.orm import DeclarativeBase as _DeclarativeBase
+from sqlalchemy.orm import Session as _Session
+
+from .schemas._base import (
+    _async_resolve_ids_to_sqlalchemy_objects,
+    _resolve_ids_to_sqlalchemy_objects,
+)
+
+_T = _TypeVar("_T", bound=_DeclarativeBase)
+
+
+def build_from_schema(
+    session: _Session,
+    model_cls: type[_T],
+    schema_obj: _pydantic.BaseModel,
+    schema_cls: type[_pydantic.BaseModel] | None = None,
+) -> _T:
+    """Build ``model_cls`` from ``schema_obj`` and add it to ``session``.
+
+    This is the schema-to-ORM mapping primitive. It resolves Restly reference
+    fields, skips read-only inputs, applies schema defaults, and stages the
+    object in the session. It does not flush and does not run view-level
+    ``perform_create`` business logic.
+    """
+    from .views._base import (
+        apply_create_assignments,
+        build_create_plan,
+        validate_resolved_reference_consistency,
+    )
+
+    _resolve_ids_to_sqlalchemy_objects(session, schema_obj)
+    validate_resolved_reference_consistency(model_cls, schema_obj, schema_cls)
+    create_plan = build_create_plan(model_cls, schema_obj, schema_cls)
+    obj = model_cls(**create_plan.kwargs)
+    apply_create_assignments(obj, create_plan.post_assignments)
+    session.add(obj)
+    return obj
+
+
+def apply_schema(
+    session: _Session,
+    obj: _T,
+    schema_obj: _pydantic.BaseModel,
+    schema_cls: type[_pydantic.BaseModel] | None = None,
+) -> _T:
+    """Apply writable fields from ``schema_obj`` to ``obj``.
+
+    This is the schema-to-ORM update primitive. It resolves Restly reference
+    fields and applies only writable inputs. It does not flush and does not run
+    view-level ``perform_update`` business logic.
+    """
+    from .views._base import (
+        apply_update_to_object,
+        validate_resolved_reference_consistency,
+    )
+
+    _resolve_ids_to_sqlalchemy_objects(session, schema_obj)
+    validate_resolved_reference_consistency(type(obj), schema_obj, schema_cls)
+    apply_update_to_object(obj, schema_obj, schema_cls)
+    return obj
+
+
+def save_object(session: _Session, obj: _T) -> _T:
+    """Flush the session and refresh ``obj`` from the database."""
+    session.flush()
+    session.refresh(obj)
+    return obj
+
+
+def delete_object(session: _Session, obj: _DeclarativeBase) -> None:
+    """Delete ``obj`` and flush the session."""
+    session.delete(obj)
+    session.flush()
+
+
+async def async_build_from_schema(
+    session: _AsyncSession,
+    model_cls: type[_T],
+    schema_obj: _pydantic.BaseModel,
+    schema_cls: type[_pydantic.BaseModel] | None = None,
+) -> _T:
+    """Async equivalent of :func:`build_from_schema`."""
+    from .views._base import (
+        apply_create_assignments,
+        build_create_plan,
+        validate_resolved_reference_consistency,
+    )
+
+    await _async_resolve_ids_to_sqlalchemy_objects(session, schema_obj)
+    validate_resolved_reference_consistency(model_cls, schema_obj, schema_cls)
+    create_plan = build_create_plan(model_cls, schema_obj, schema_cls)
+    obj = model_cls(**create_plan.kwargs)
+    apply_create_assignments(obj, create_plan.post_assignments)
+    session.add(obj)
+    return obj
+
+
+async def async_apply_schema(
+    session: _AsyncSession,
+    obj: _T,
+    schema_obj: _pydantic.BaseModel,
+    schema_cls: type[_pydantic.BaseModel] | None = None,
+) -> _T:
+    """Async equivalent of :func:`apply_schema`."""
+    from .views._base import (
+        apply_update_to_object,
+        validate_resolved_reference_consistency,
+    )
+
+    await _async_resolve_ids_to_sqlalchemy_objects(session, schema_obj)
+    validate_resolved_reference_consistency(type(obj), schema_obj, schema_cls)
+    apply_update_to_object(obj, schema_obj, schema_cls)
+    return obj
+
+
+async def async_save_object(session: _AsyncSession, obj: _T) -> _T:
+    """Async equivalent of :func:`save_object`."""
+    await session.flush()
+    await session.refresh(obj)
+    return obj
+
+
+async def async_delete_object(
+    session: _AsyncSession, obj: _DeclarativeBase
+) -> None:
+    """Async equivalent of :func:`delete_object`."""
+    await session.delete(obj)
+    await session.flush()
+
+
+__all__ = [
+    "apply_schema",
+    "async_apply_schema",
+    "async_build_from_schema",
+    "async_delete_object",
+    "async_save_object",
+    "build_from_schema",
+    "delete_object",
+    "save_object",
+]

fastapi_restly/pytest_fixtures.py

@@ -0,0 +1,24 @@
+try:
+    from fastapi_restly._pytest_fixtures import (
+        _shared_connection,
+        restly_app,
+        restly_async_session,
+        restly_client,
+        restly_project_root,
+        restly_session,
+    )
+except ModuleNotFoundError as exc:
+    if exc.name in {"httpx", "pytest"}:
+        raise ModuleNotFoundError(
+            "fastapi_restly.pytest_fixtures requires optional testing dependencies. "
+            'Install them with: pip install "fastapi-restly[testing]"'
+        ) from exc
+    raise
+
+__all__ = [
+    "restly_app",
+    "restly_async_session",
+    "restly_client",
+    "restly_project_root",
+    "restly_session",
+]

fastapi_restly/query/__init__.py

@@ -0,0 +1,13 @@
+from ._impl import (
+    DEFAULT_PAGE_SIZE,
+    MAX_PAGE_SIZE,
+    apply_list_params,
+    create_list_params_schema,
+)
+
+__all__ = [
+    "DEFAULT_PAGE_SIZE",
+    "MAX_PAGE_SIZE",
+    "apply_list_params",
+    "create_list_params_schema",
+]