fastapi-restly 0.5.0__py3-none-any.whl

fastapi_restly/views/_openapi.py

@@ -0,0 +1,206 @@
+"""
+Internal OpenAPI post-processing: x-resource-ref annotations.
+
+Called automatically by include_view() — no public API.
+
+FK columns and SQLAlchemy relationship fields backed by IDSchema/IDRef
+are annotated with ``x-resource-ref: "<resource-name>"`` in the generated spec.
+Full nested-object relationships (plain Pydantic model fields) are left untouched.
+"""
+
+import inspect
+import types
+import weakref
+from dataclasses import dataclass
+from typing import Any, Union, get_args, get_origin
+
+import fastapi
+import pydantic
+from sqlalchemy import inspect as sa_inspect
+from sqlalchemy.orm import DeclarativeBase
+
+from ..schemas import IDSchema
+
+_PATCHED_ATTR = "_fr_resource_refs_patched"
+
+
+@dataclass
+class _Entry:
+    model: type[DeclarativeBase]
+    resource_name: str
+    schema: type[pydantic.BaseModel]
+    creation_schema: type[pydantic.BaseModel]
+    update_schema: type[pydantic.BaseModel]
+
+
+_registry: weakref.WeakKeyDictionary[
+    fastapi.FastAPI | fastapi.APIRouter, list[_Entry]
+] = weakref.WeakKeyDictionary()
+
+
+def _register_for_resource_ref(
+    parent_router: fastapi.FastAPI | fastapi.APIRouter, view_cls: type
+) -> None:
+    """Register a view's model→resource mapping and ensure the spec is patched.
+
+    Silently skips views without a SQLAlchemy model (e.g. plain View subclasses).
+    """
+    model = getattr(view_cls, "model", None)
+    if model is None or not (
+        isinstance(model, type) and issubclass(model, DeclarativeBase)
+    ):
+        return
+
+    resource_name = "".join(
+        c.__dict__["prefix"] for c in reversed(view_cls.mro()) if "prefix" in c.__dict__
+    ).lstrip("/")
+
+    entry = _Entry(
+        model=model,
+        resource_name=resource_name,
+        schema=view_cls.schema,
+        creation_schema=view_cls.creation_schema,
+        update_schema=view_cls.update_schema,
+    )
+
+    entries = _registry.get(parent_router)
+    if entries is None:
+        entries = []
+        _registry[parent_router] = entries
+    entries.append(entry)
+
+    # Only the FastAPI app generates the OpenAPI spec; APIRouter parents have
+    # no ``.openapi`` to patch. Views registered on a router lose x-resource-ref
+    # annotations until the framework can walk to a root app, which is a
+    # separate gap.
+    if isinstance(parent_router, fastapi.FastAPI):
+        _ensure_patched(parent_router)
+
+
+def _ensure_patched(app: fastapi.FastAPI) -> None:
+    """Wrap app.openapi() once so annotations are injected on first call."""
+    if getattr(app, _PATCHED_ATTR, False):
+        return
+
+    original_openapi = app.openapi
+
+    def patched_openapi() -> dict[str, Any]:
+        spec = original_openapi()
+        entries = _registry.get(app, [])
+        model_to_resource = {e.model: e.resource_name for e in entries}
+        _annotate_spec(spec, entries, model_to_resource)
+        return spec
+
+    app.openapi = patched_openapi  # type: ignore[method-assign]
+    setattr(app, _PATCHED_ATTR, True)
+
+
+def _is_id_ref_annotation(annotation: Any) -> bool:
+    """Return True if annotation is IDSchema[X], IDRef[X], or list/Optional thereof.
+
+    Returns False for full nested Pydantic model objects — those are not ID references.
+    Concrete user-defined subclasses like ``AuthorRead(IDSchema)`` return False;
+    only parametrized generics like ``IDSchema[Author]`` or ``IDRef[Author]``
+    return True, since those represent model ID references.
+    """
+    origin = get_origin(annotation)
+
+    # Unwrap Optional / Union  (X | None, Optional[X], Union[X, Y])
+    if origin in (Union, types.UnionType):
+        return any(
+            _is_id_ref_annotation(a)
+            for a in get_args(annotation)
+            if a is not type(None)
+        )
+
+    # list[X] — check the element type
+    if origin is list:
+        args = get_args(annotation)
+        return bool(args and _is_id_ref_annotation(args[0]))
+
+    # Check for parametrized IDSchema/IDRef generics.
+    # In Pydantic v2, IDSchema[Author] and IDRef[Author] are concrete classes,
+    # so inspect.isclass() returns True for them too. We distinguish via
+    # __pydantic_generic_metadata__["origin"]:
+    #   - Parametrized: IDSchema[Author]  → origin = IDSchema
+    #   - Parametrized: IDRef[Author] → origin = IDRef
+    #   - User-defined subclass: AuthorRead(IDSchema) → origin = None (not a parametrization)
+    pydantic_meta = getattr(annotation, "__pydantic_generic_metadata__", {})
+    origin_cls = pydantic_meta.get("origin")
+    if inspect.isclass(origin_cls):
+        try:
+            return issubclass(origin_cls, IDSchema)
+        except TypeError:
+            return False
+
+    return False
+
+
+def _field_openapi_key(schema_cls: type[pydantic.BaseModel], field_name: str) -> str:
+    """Return the OpenAPI property key for a field, respecting serialization aliases."""
+    field_info = schema_cls.model_fields.get(field_name)
+    if field_info is None:
+        return field_name
+    if field_info.serialization_alias:
+        return field_info.serialization_alias
+    if field_info.alias:
+        return field_info.alias
+    return field_name
+
+
+def _compute_refs(
+    schema_cls: type[pydantic.BaseModel],
+    model_cls: type[DeclarativeBase],
+    model_to_resource: dict[type[DeclarativeBase], str],
+) -> dict[str, str]:
+    """Return {openapi_property_key: resource_name} for FK columns and ID-ref relationship fields."""
+    result: dict[str, str] = {}
+    try:
+        mapper = sa_inspect(model_cls)
+    except Exception:
+        return result
+
+    for field_name, field_info in schema_cls.model_fields.items():
+        resource_name: str | None = None
+
+        if field_name in mapper.columns:
+            fks = list(mapper.columns[field_name].foreign_keys)
+            if fks:
+                target_table = fks[0].column.table  # Table object identity
+                for m in model_cls.registry.mappers:
+                    if m.local_table is target_table:
+                        resource_name = model_to_resource.get(m.class_)
+                        break
+
+        elif field_name in mapper.relationships:
+            # Only annotate if the schema field carries ID references, not full nested objects.
+            if _is_id_ref_annotation(field_info.annotation):
+                target_model = mapper.relationships[field_name].mapper.class_
+                resource_name = model_to_resource.get(target_model)
+
+        if resource_name is not None:
+            result[_field_openapi_key(schema_cls, field_name)] = resource_name
+
+    return result
+
+
+def _annotate_spec(
+    spec: dict[str, Any],
+    entries: list[_Entry],
+    model_to_resource: dict[type[DeclarativeBase], str],
+) -> None:
+    """Mutate spec in-place, adding x-resource-ref to qualifying properties."""
+    schemas = spec.get("components", {}).get("schemas", {})
+    if not schemas:
+        return
+
+    for entry in entries:
+        refs = _compute_refs(entry.schema, entry.model, model_to_resource)
+        if not refs:
+            continue
+
+        for schema_cls in (entry.schema, entry.creation_schema, entry.update_schema):
+            props = schemas.get(schema_cls.__name__, {}).get("properties", {})
+            for prop_key, resource_name in refs.items():
+                if prop_key in props:
+                    props[prop_key]["x-resource-ref"] = resource_name

fastapi_restly/views/_react_admin.py

@@ -0,0 +1,393 @@
+"""
+React Admin compatible views for fastapi-restly.
+
+Implements the ra-data-simple-rest wire contract for list:
+- response body: plain JSON array
+- sort:   sort=["field","ASC|DESC"]
+- range:  range=[start, end]  (both inclusive, e.g. [0,24] = 25 items)
+- filter: filter={"field":"value"} or filter={"id":[1,2,3]} for getMany
+- Content-Range: items 0-24/315
+"""
+
+import json
+from typing import Any, ClassVar, Protocol, Sequence, cast
+
+import fastapi
+import pydantic
+import sqlalchemy
+from sqlalchemy import func, select
+from sqlalchemy.orm import DeclarativeBase, RelationshipProperty
+
+from ..schemas import BaseSchema
+from ._async import AsyncRestView
+from ._base import _annotate, get, put
+from ._sync import RestView
+
+#: Default page size used when the react-admin client does not send a `range`
+#: query parameter. Override per-view via ``default_page_size``.
+DEFAULT_REACT_ADMIN_PAGE_SIZE = 25
+
+
+# ---------------------------------------------------------------------------
+# Query parsing helpers (standalone, analogous to query/_impl.py)
+# ---------------------------------------------------------------------------
+
+
+def parse_react_admin_sort(sort_raw: str | None) -> tuple[str, str] | None:
+    """
+    Parse a react-admin sort query parameter.
+
+    Expected: '["field","ASC"]' or '["field","DESC"]'
+    Returns (field, direction) or None if absent.
+    Raises HTTPException 400 on malformed input.
+    """
+    if not sort_raw:
+        return None
+    try:
+        parsed = json.loads(sort_raw)
+    except json.JSONDecodeError:
+        raise fastapi.HTTPException(400, "Invalid sort parameter: must be a JSON array")
+    if not isinstance(parsed, list) or len(parsed) != 2:
+        raise fastapi.HTTPException(
+            400, "Invalid sort parameter: must be [field, direction]"
+        )
+    field, direction = parsed
+    if not isinstance(field, str) or direction not in ("ASC", "DESC"):
+        raise fastapi.HTTPException(
+            400, "Invalid sort parameter: direction must be 'ASC' or 'DESC'"
+        )
+    return field, direction
+
+
+def parse_react_admin_range(
+    range_raw: str | None, default_page_size: int = DEFAULT_REACT_ADMIN_PAGE_SIZE
+) -> tuple[int, int]:
+    """
+    Parse a react-admin range query parameter.
+
+    Expected: '[0,24]' (both inclusive).
+    Returns (start, end). Defaults to (0, default_page_size - 1) if absent.
+    Raises HTTPException 400 on malformed input.
+    """
+    if not range_raw:
+        return 0, default_page_size - 1
+    try:
+        parsed = json.loads(range_raw)
+    except json.JSONDecodeError:
+        raise fastapi.HTTPException(
+            400, "Invalid range parameter: must be a JSON array"
+        )
+    if not isinstance(parsed, list) or len(parsed) != 2:
+        raise fastapi.HTTPException(
+            400, "Invalid range parameter: must be [start, end]"
+        )
+    start, end = parsed
+    if not isinstance(start, int) or not isinstance(end, int):
+        raise fastapi.HTTPException(
+            400, "Invalid range parameter: values must be integers"
+        )
+    return start, end
+
+
+def parse_react_admin_filter(filter_raw: str | None) -> dict:
+    """
+    Parse a react-admin filter query parameter.
+
+    Expected: '{"field":"value"}' or '{"id":[1,2,3]}' for getMany.
+    Returns a dict. Defaults to {} if absent.
+    Raises HTTPException 400 on malformed input.
+    """
+    if not filter_raw:
+        return {}
+    try:
+        parsed = json.loads(filter_raw)
+    except json.JSONDecodeError:
+        raise fastapi.HTTPException(
+            400, "Invalid filter parameter: must be a JSON object"
+        )
+    if not isinstance(parsed, dict):
+        raise fastapi.HTTPException(
+            400, "Invalid filter parameter: must be a JSON object"
+        )
+    return parsed
+
+
+def _resolve_column(
+    model: type[DeclarativeBase], schema_cls: Any, field_name: str
+) -> Any:
+    """
+    Resolve a field name to a SQLAlchemy column.
+
+    Checks model attributes directly, then falls back to schema alias resolution.
+    Raises HTTPException 400 if the field cannot be resolved.
+    """
+    col = getattr(model, field_name, None)
+    if col is not None:
+        if hasattr(col, "property") and isinstance(col.property, RelationshipProperty):
+            raise fastapi.HTTPException(
+                400, f"Cannot sort or filter by relationship field: {field_name!r}"
+            )
+        return col
+
+    if schema_cls is not None:
+        for name, field in schema_cls.model_fields.items():
+            if field.alias == field_name:
+                col = getattr(model, name, None)
+                if col is not None:
+                    return col
+
+    raise fastapi.HTTPException(400, f"Unknown filter field: {field_name!r}")
+
+
+def _coerce_value(col: Any, value: Any) -> Any:
+    """Coerce a filter value to the column's Python type if needed.
+
+    Handles cases such as UUID strings that must be converted to uuid.UUID
+    objects before being passed to SQLAlchemy's type processor.
+    """
+    try:
+        py_type = col.type.python_type
+    except NotImplementedError:
+        return value
+    if not isinstance(value, py_type):
+        try:
+            return py_type(value)
+        except (ValueError, TypeError):
+            raise fastapi.HTTPException(
+                400, f"Invalid filter value for {col.key!r}: {value!r}"
+            )
+    return value
+
+
+def _apply_react_admin_filters(
+    query: sqlalchemy.Select,
+    model: type[DeclarativeBase],
+    schema_cls: Any,
+    filters: dict,
+) -> sqlalchemy.Select:
+    """Apply a react-admin filter dict to a select query."""
+    for key, value in filters.items():
+        col = _resolve_column(model, schema_cls, key)
+        if isinstance(value, list):
+            coerced = [_coerce_value(col, v) for v in value]
+            query = query.where(col.in_(coerced))
+        else:
+            query = query.where(col == _coerce_value(col, value))
+    return query
+
+
+def apply_react_admin_query(
+    query: sqlalchemy.Select,
+    model: type[DeclarativeBase],
+    schema_cls: Any,
+    sort: tuple[str, str] | None,
+    start: int,
+    end: int,
+    filters: dict,
+) -> sqlalchemy.Select:
+    """
+    Apply filter, sort, and range (limit/offset) to a select query.
+
+    This is the main query transformation entry point, analogous to
+    :func:`fastapi_restly.query.apply_list_params` for the standard REST dialect.
+    """
+    query = _apply_react_admin_filters(query, model, schema_cls, filters)
+
+    if sort:
+        field, direction = sort
+        col = _resolve_column(model, schema_cls, field)
+        order_fn = sqlalchemy.desc if direction == "DESC" else sqlalchemy.asc
+        query = query.order_by(order_fn(col))
+    else:
+        id_col = getattr(model, "id", None)
+        if id_col is not None:
+            query = query.order_by(id_col)
+
+    query = query.limit(end - start + 1).offset(start)
+    return query
+
+
+# ---------------------------------------------------------------------------
+# Shared implementation mixin
+# ---------------------------------------------------------------------------
+
+
+class _ReactAdminViewProtocol(Protocol):
+    request: fastapi.Request
+    model: ClassVar[type[DeclarativeBase]]
+    schema: ClassVar[type[pydantic.BaseModel]]
+    update_schema: ClassVar[type[pydantic.BaseModel]]
+    id_type: ClassVar[type[Any]]
+    default_page_size: ClassVar[int | None]
+    listing: ClassVar[Any]
+    put: ClassVar[Any]
+
+    def get_react_admin_range_unit(self) -> str: ...
+    def get_relationship_loader_options(self) -> list[Any]: ...
+    def to_response_schema(self, obj: Any) -> pydantic.BaseModel: ...
+
+    @classmethod
+    def before_include_view(cls) -> None: ...
+
+
+class _ReactAdminMixin:
+    """
+    Shared transport helpers for react-admin views.
+
+    This is an implementation detail shared by ReactAdminView and
+    AsyncReactAdminView. User-facing customization should happen by
+    subclassing one of those concrete view classes.
+
+    Set :attr:`default_page_size` on a subclass to change the implicit page
+    size used when the client does not send a ``range`` query parameter.
+
+    Type annotations on the mixin methods use ``_ReactAdminViewProtocol`` to
+    make the expected ``RestView`` surface explicit to static checkers.
+    """
+
+    #: Implicit page size when no ``range`` parameter is sent. Override per-view.
+    default_page_size: ClassVar[int | None] = DEFAULT_REACT_ADMIN_PAGE_SIZE
+
+    def get_react_admin_range_unit(self) -> str:
+        """Return the unit string used in the Content-Range header."""
+        return "items"
+
+    def _parse_react_admin_params(
+        self,
+    ) -> tuple[tuple[str, str] | None, tuple[int, int], dict]:
+        """Parse sort, range, and filter from the current request query string."""
+        view = cast(_ReactAdminViewProtocol, self)
+        params = view.request.query_params
+        default_page_size = view.default_page_size or DEFAULT_REACT_ADMIN_PAGE_SIZE
+        sort = parse_react_admin_sort(params.get("sort"))
+        start, end = parse_react_admin_range(
+            params.get("range"), default_page_size=default_page_size
+        )
+        filters = parse_react_admin_filter(params.get("filter"))
+        return sort, (start, end), filters
+
+    def _serialize_items(self, items: Sequence[Any]) -> list[dict]:
+        """Serialize ORM objects to JSON-compatible dicts via the view's response schema."""
+        view = cast(_ReactAdminViewProtocol, self)
+        return [
+            view.to_response_schema(obj).model_dump(mode="json", by_alias=True)
+            for obj in items
+        ]
+
+    def _build_react_admin_list_response(
+        self,
+        serialized_items: list[dict],
+        total: int,
+        start: int,
+        end: int,
+    ) -> fastapi.Response:
+        """Build a JSON array response with a Content-Range header."""
+        view = cast(_ReactAdminViewProtocol, self)
+        unit = view.get_react_admin_range_unit()
+        last = start + len(serialized_items) - 1 if serialized_items else start
+        return fastapi.Response(
+            content=json.dumps(serialized_items),
+            media_type="application/json",
+            headers={
+                "Content-Range": f"{unit} {start}-{last}/{total}",
+                "Access-Control-Expose-Headers": "Content-Range",
+            },
+        )
+
+    def _build_count_query(self, filters: dict) -> sqlalchemy.Select:
+        """Count query: filters only, no sort or pagination."""
+        view = cast(_ReactAdminViewProtocol, self)
+        base = sqlalchemy.select(view.model)
+        filtered = _apply_react_admin_filters(base, view.model, view.schema, filters)
+        return select(func.count()).select_from(filtered.subquery())
+
+    def _build_listing_query(
+        self,
+        sort: tuple[str, str] | None,
+        start: int,
+        end: int,
+        filters: dict,
+    ) -> sqlalchemy.Select:
+        """List query: filters, sort, and range applied."""
+        view = cast(_ReactAdminViewProtocol, self)
+        base = sqlalchemy.select(view.model)
+        loader_options = view.get_relationship_loader_options()
+        if loader_options:
+            base = base.options(*loader_options)
+        return apply_react_admin_query(
+            base, view.model, view.schema, sort, start, end, filters
+        )
+
+    @classmethod
+    def before_include_view(cls) -> None:
+        cast(Any, super()).before_include_view()
+        view_cls = cast(type[_ReactAdminViewProtocol], cls)
+        # Override the listing return annotation set by BaseRestView to Response,
+        # since we return a raw Response with Content-Range header.
+        if hasattr(view_cls, "listing"):
+            _annotate(view_cls.listing, return_annotation=fastapi.Response)
+        # Annotate the PUT handler with the same schema/types as PATCH.
+        if hasattr(view_cls, "put"):
+            _annotate(
+                view_cls.put,
+                return_annotation=view_cls.schema,
+                schema_obj=view_cls.update_schema,
+                id=view_cls.id_type,
+            )
+
+
+# ---------------------------------------------------------------------------
+# Concrete view classes
+# ---------------------------------------------------------------------------
+
+
+class AsyncReactAdminView(_ReactAdminMixin, AsyncRestView):
+    """
+    AsyncRestView that speaks the ra-data-simple-rest wire contract.
+
+    Use this instead of AsyncRestView when your frontend is react-admin
+    with ra-data-simple-rest.
+    """
+
+    @get("/")
+    async def listing(self) -> Any:
+        sort, (start, end), filters = self._parse_react_admin_params()
+        total = int(await self.session.scalar(self._build_count_query(filters)) or 0)
+        items = (
+            await self.session.scalars(
+                self._build_listing_query(sort, start, end, filters)
+            )
+        ).all()
+        return self._build_react_admin_list_response(
+            self._serialize_items(items), total, start, end
+        )
+
+    @put("/{id}")
+    async def put(self, id: Any, schema_obj: Any) -> Any:
+        obj = await self.perform_update(id, schema_obj)
+        return self.to_response_schema(obj)
+
+
+class ReactAdminView(_ReactAdminMixin, RestView):
+    """
+    RestView that speaks the ra-data-simple-rest wire contract.
+
+    Use this instead of RestView when your frontend is react-admin
+    with ra-data-simple-rest.
+    """
+
+    @get("/")
+    def listing(self) -> Any:
+        sort, (start, end), filters = self._parse_react_admin_params()
+        total = int(self.session.scalar(self._build_count_query(filters)) or 0)
+        items = self.session.scalars(
+            self._build_listing_query(sort, start, end, filters)
+        ).all()
+        return self._build_react_admin_list_response(
+            self._serialize_items(items), total, start, end
+        )
+
+    @put("/{id}")
+    def put(self, id: Any, schema_obj: Any) -> Any:
+        obj = self.perform_update(id, schema_obj)
+        return self.to_response_schema(obj)