fastapi-restly 0.5.0__py3-none-any.whl

fastapi_restly/schemas/_base.py

@@ -0,0 +1,518 @@
+import functools
+import types
+from datetime import datetime
+from typing import Annotated, Any, Generic, Optional, Union, get_args, get_origin
+
+import pydantic
+from fastapi import HTTPException
+from pydantic.fields import Field, FieldInfo
+from sqlalchemy import select
+from sqlalchemy.exc import NoResultFound
+from sqlalchemy.ext.asyncio.session import AsyncSession as SA_AsyncSession
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.orm.session import Session as SA_Session
+from typing_extensions import TypeVar
+
+
+class BaseSchema(pydantic.BaseModel):
+    """Thin Pydantic base for ORM-facing Restly schemas.
+
+    Equivalent to::
+
+        class BaseSchema(pydantic.BaseModel):
+            model_config = pydantic.ConfigDict(from_attributes=True)
+
+    ``from_attributes=True`` lets Pydantic/FastAPI validate objects by
+    attribute when the schema is used directly. Generated Restly routes still
+    serialize through ``to_response_schema()`` so Restly-specific behavior such
+    as ``WriteOnly`` filtering and relationship-id normalization is applied.
+    """
+
+    model_config = pydantic.ConfigDict(from_attributes=True)
+
+
+class _Marker:
+    def __init__(self, name: str):
+        self.name = name
+
+    def __repr__(self):
+        return f"fr.{self.name}"
+
+
+readonly_marker = _Marker("ReadOnly")
+writeonly_marker = _Marker("WriteOnly")
+
+_T = TypeVar("_T")
+
+ReadOnly = Annotated[_T, readonly_marker, Field(json_schema_extra={"readOnly": True})]
+WriteOnly = Annotated[
+    _T, writeonly_marker, Field(json_schema_extra={"writeOnly": True})
+]
+
+
+class TimestampsSchemaMixin(pydantic.BaseModel):
+    created_at: ReadOnly[datetime]
+    updated_at: ReadOnly[datetime]
+
+
+SQLAlchemyModel = TypeVar(
+    "SQLAlchemyModel", bound=DeclarativeBase, default=DeclarativeBase
+)
+_IDREF_UNSET = object()
+_SCHEMA_RESOURCE_SUFFIX = "Read"
+
+
+@functools.cache
+def _id_type_adapter(id_type: Any) -> pydantic.TypeAdapter[Any]:
+    return pydantic.TypeAdapter(id_type)
+
+
+def _schema_resource_name(model_cls: type[pydantic.BaseModel]) -> str:
+    """Return the resource name used to derive role-specific API schemas."""
+    name = model_cls.__name__
+    if name.endswith(_SCHEMA_RESOURCE_SUFFIX) and len(name) > len(
+        _SCHEMA_RESOURCE_SUFFIX
+    ):
+        return name[: -len(_SCHEMA_RESOURCE_SUFFIX)]
+    return name
+
+
+def _schema_role_name(model_cls: type[pydantic.BaseModel], role: str) -> str:
+    return f"{_schema_resource_name(model_cls)}{role}"
+
+
+class IDSchema(BaseSchema, Generic[SQLAlchemyModel]):
+    """Generic schema useful for serializing only the id of objects.
+    Can be used as IDSchema[MyModel].
+    """
+
+    # Keep this broad so relation-id payloads can target non-int primary keys.
+    id: ReadOnly[Any]
+
+    @classmethod
+    def _get_sql_model_annotation(cls) -> type[DeclarativeBase] | None:
+        # `__pydantic_generic_metadata__` is set on parameterised subclasses;
+        # on the bare `IDSchema` class the "args" tuple may be missing or empty.
+        try:
+            sql_model = cls.__pydantic_generic_metadata__["args"][0]
+        except (KeyError, IndexError, TypeError):
+            return None
+        return sql_model if isinstance(sql_model, type) else None
+
+    @classmethod
+    def _get_sql_model_id_type(cls) -> Any:
+        sql_model = cls._get_sql_model_annotation()
+        if sql_model is None:
+            return None
+
+        for model_cls in sql_model.mro():
+            annotation = getattr(model_cls, "__annotations__", {}).get("id")
+            if annotation is None:
+                continue
+            origin = get_origin(annotation)
+            if origin is not None:
+                args = get_args(annotation)
+                if args:
+                    return args[0]
+            return annotation
+
+        # Fallback: ask the SA mapper. `python_type` raises NotImplementedError
+        # for column types without a Python equivalent (e.g. some user types),
+        # and accessing `__mapper__` may fail with AttributeError if the class
+        # has not been mapped yet.
+        try:
+            return sql_model.__mapper__.primary_key[0].type.python_type
+        except (AttributeError, NotImplementedError, IndexError):
+            return None
+
+    @pydantic.field_validator("id", mode="before", check_fields=False)
+    @classmethod
+    def _coerce_id_to_model_primary_key_type(cls, value: Any) -> Any:
+        id_type = cls._get_sql_model_id_type()
+        if id_type in (None, Any):
+            return value
+        return _id_type_adapter(id_type).validate_python(value)
+
+    def get_sql_model_annotation(self) -> type[SQLAlchemyModel] | None:
+        """
+        Return the annotation on IDSchema when used as:
+
+        foo: IDSchema[Foo]
+
+        This property will return "Foo".
+        """
+        # The runtime introspection returns the bound type; cast through the
+        # generic parameter so callers see the concrete model class.
+        return self._get_sql_model_annotation()  # type: ignore[return-value]
+
+
+class IDRef(IDSchema[SQLAlchemyModel], Generic[SQLAlchemyModel]):
+    """Reference to a row of T by id.
+
+    Wire format is the raw id value (e.g. ``5``); accepts both scalars and
+    ``{"id": N}`` dicts on input. The framework validates the referenced row
+    exists and resolves it to the FK column on the way in.
+
+    Use this for typical REST APIs where you want ``task_id: 5`` on the wire.
+    For JSON-API or React-Admin-style nested wire format ``{"id": N}``, use
+    ``IDSchema[T]`` instead.
+
+        products: list[IDRef[Product]]  # serializes as ["uuid1", "uuid2"]
+    """
+
+    def __init__(self, value: Any = _IDREF_UNSET, **data: Any) -> None:
+        if value is not _IDREF_UNSET:
+            if data:
+                raise TypeError(
+                    "IDRef accepts either a positional id or keyword fields"
+                )
+            data = value if isinstance(value, dict) else {"id": value}
+        super().__init__(**data)
+
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls, core_schema: Any, handler: pydantic.GetJsonSchemaHandler
+    ) -> dict[str, Any]:
+        id_type = cls._get_sql_model_id_type()
+        if id_type in (None, Any):
+            return {}
+        return pydantic.TypeAdapter(id_type).json_schema(
+            mode=getattr(handler, "mode", "validation")
+        )
+
+    @pydantic.model_validator(mode="before")
+    @classmethod
+    def _coerce_scalar(cls, v: Any) -> Any:
+        if not isinstance(v, dict):
+            return {"id": v}
+        return v
+
+    @pydantic.model_serializer
+    def _serialize_flat(self) -> Any:
+        return self.id if hasattr(self, "id") else self
+
+
+async def _async_resolve_ids_to_sqlalchemy_objects(
+    session: SA_AsyncSession, schema_obj: pydantic.BaseModel
+) -> None:
+    """
+    Go over the Pydantic fields and turn any IDSchema objects into SQLAlchemy instances.
+    A database request is made for each IDSchema to look up the related row in the database.
+    If an id is not found in the database `sqlalchemy.orm.exc.NoResultFound` is raised.
+    """
+    # Go over all Pydantic fields and check if any of them are an IDSchema object or
+    # a list of IDSchema objects.
+    for field in schema_obj.model_fields_set:
+        value = getattr(schema_obj, field, None)
+
+        if isinstance(value, IDSchema):
+            sql_model = value.get_sql_model_annotation()
+            if not sql_model:
+                continue
+
+            # Replace the IDSchema object with a SQLAlchemy instance from the database
+            try:
+                sql_model_obj = await session.get_one(sql_model, value.id)
+            except NoResultFound as e:
+                raise HTTPException(
+                    status_code=404, detail=f"Id not found for {field}: {value.id}"
+                ) from e
+            setattr(schema_obj, field, sql_model_obj)
+
+        elif isinstance(value, list) and any(isinstance(i, IDSchema) for i in value):
+            # Assume all IdSchemas are for the same model
+            sql_model = value[0].get_sql_model_annotation()
+            if not sql_model:
+                continue
+
+            # Replace all IDSchema objects with SQLAlchemy instances
+            ids = [obj.id for obj in value]
+            query = select(sql_model).where(sql_model.id.in_(ids))
+            sql_model_objs = list(await session.scalars(query))
+
+            if len(ids) != len(sql_model_objs):
+                missing_ids = set(ids).difference(o.id for o in sql_model_objs)
+                raise HTTPException(
+                    status_code=404, detail=f"Id not found for {field}: {missing_ids}"
+                )
+
+            setattr(schema_obj, field, sql_model_objs)
+
+
+def _resolve_ids_to_sqlalchemy_objects(
+    session: SA_Session, schema_obj: pydantic.BaseModel
+) -> None:
+    """
+    Go over the Pydantic fields and turn any IDSchema objects into SQLAlchemy instances.
+    A database request is made for each IDSchema to look up the related row in the database.
+    If an id is not found in the database `sqlalchemy.orm.exc.NoResultFound` is raised.
+    """
+    # Go over all Pydantic fields and check if any of them are an IDSchema object or
+    # a list of IDSchema objects.
+    for field in schema_obj.model_fields_set:
+        value = getattr(schema_obj, field, None)
+
+        if isinstance(value, IDSchema):
+            sql_model = value.get_sql_model_annotation()
+            if not sql_model:
+                continue
+
+            # Replace the IDSchema object with a SQLAlchemy instance from the database
+            try:
+                sql_model_obj = session.get_one(sql_model, value.id)
+            except NoResultFound as e:
+                raise HTTPException(
+                    status_code=404, detail=f"Id not found for {field}: {value.id}"
+                ) from e
+            setattr(schema_obj, field, sql_model_obj)
+
+        elif isinstance(value, list) and any(isinstance(i, IDSchema) for i in value):
+            # Assume all IdSchemas are for the same model
+            sql_model = value[0].get_sql_model_annotation()
+            if not sql_model:
+                continue
+
+            # Replace all IDSchema objects with SQLAlchemy instances
+            ids = [obj.id for obj in value]
+            query = select(sql_model).where(sql_model.id.in_(ids))
+            sql_model_objs = list(session.scalars(query))
+
+            if len(ids) != len(sql_model_objs):
+                missing_ids = set(ids).difference(o.id for o in sql_model_objs)
+                raise HTTPException(
+                    status_code=404, detail=f"Id not found for {field}: {missing_ids}"
+                )
+
+            setattr(schema_obj, field, sql_model_objs)
+
+
+def get_read_only_fields(model_cls: type[pydantic.BaseModel]) -> list[str]:
+    """Get all fields from a model annotated as ReadOnly[]"""
+    read_only_fields: list[str] = []
+    # Get read-only fields from Annotated metadata
+    for field_name, field_info in model_cls.model_fields.items():
+        metadata = getattr(field_info, "metadata", None)
+        if metadata and readonly_marker in metadata:
+            read_only_fields.append(field_name)
+    return read_only_fields
+
+
+def is_readonly_field(
+    model: pydantic.BaseModel | type[pydantic.BaseModel], field_name: str
+) -> bool:
+    """Check if a specific field is marked as readonly."""
+    if isinstance(model, pydantic.BaseModel):
+        model = model.__class__
+    field_info = model.model_fields.get(field_name)
+    return _is_readonly(field_info)
+
+
+def _is_readonly(field_info: FieldInfo | None) -> bool:
+    if field_info is None:
+        return False
+    metadata = getattr(field_info, "metadata", None)
+    if not metadata:
+        return False
+    return readonly_marker in metadata
+
+
+def _is_writeonly(field_info: FieldInfo | None) -> bool:
+    if field_info is None:
+        return False
+    metadata = getattr(field_info, "metadata", None)
+    if not metadata:
+        return False
+    return writeonly_marker in metadata
+
+
+def get_write_only_fields(model_cls: type[pydantic.BaseModel]) -> list[str]:
+    """Get all fields from a model annotated as WriteOnly[]"""
+    write_only_fields: list[str] = []
+    # Get write-only fields from Annotated metadata
+    for field_name, field_info in model_cls.model_fields.items():
+        if _is_writeonly(field_info):
+            write_only_fields.append(field_name)
+    return write_only_fields
+
+
+def is_writeonly_field(
+    model_cls: pydantic.BaseModel | type[pydantic.BaseModel], field_name: str
+) -> bool:
+    """Check if a specific field is marked as writeonly."""
+    if isinstance(model_cls, pydantic.BaseModel):
+        model_cls = model_cls.__class__
+    field_info = model_cls.model_fields.get(field_name)
+    return _is_writeonly(field_info)
+
+
+def create_model_without_read_only_fields(
+    model_cls: type[pydantic.BaseModel],
+) -> type[pydantic.BaseModel]:
+    """
+    Create a subclass of the given pydantic model class with a new name.
+    """
+    new_model_name = _schema_role_name(model_cls, "Create")
+    new_doc = (model_cls.__doc__ or "") + "\nRead-only fields have been removed."
+
+    # Create a subclass that mixes in OmitReadOnlyMixin
+    new_model_cls = type(
+        new_model_name,
+        (OmitReadOnlyMixin, model_cls),
+        {"__module__": model_cls.__module__, "__doc__": new_doc},
+    )
+
+    return new_model_cls
+
+
+class OmitReadOnlyMixin(pydantic.BaseModel):
+    """
+    Mixin for pydantic models that removes all fields marked as ReadOnly.
+
+    Implementation note: this mutates ``cls.model_fields`` in place and then
+    calls ``model_rebuild(force=True)`` to regenerate the validator/serializer.
+    Pydantic v2 does not officially document mutation of ``model_fields`` as
+    a supported customisation hook, but this approach has been stable since
+    pydantic 2.0 and works on the pinned minimum (``pydantic>=2.11.4``). If
+    a future pydantic release freezes the dict, switch to constructing a new
+    model via ``pydantic.create_model(...)`` over the kept fields. The
+    regression test ``tests/test_pydantic_model_fields_mutation.py`` exercises
+    this contract on the currently-installed pydantic.
+    """
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:
+        super().__pydantic_init_subclass__(**kwargs)
+
+        # Collect readonly fields to delete first
+        readonly_fields = []
+        for name, field_info in cls.model_fields.items():
+            if _is_readonly(field_info):
+                readonly_fields.append(name)
+
+        # Delete readonly fields after iteration is complete
+        for name in readonly_fields:
+            del cls.model_fields[name]
+
+        cls.model_rebuild(force=True)
+
+
+def rebase_with_model_config(
+    base: tuple[type, ...], model_cls: type[pydantic.BaseModel]
+) -> type[pydantic.BaseModel]:
+    def class_body(ns: dict[str, Any]) -> None:
+        ns["model_config"] = model_cls.model_config.copy()
+
+    return types.new_class(
+        f"{model_cls.__name__}ModelConfig", base, exec_body=class_body
+    )
+
+
+def create_model_with_optional_fields(
+    model_cls: type[pydantic.BaseModel],
+) -> type[pydantic.BaseModel]:
+    """
+    Create a subclass of the given pydantic model class with a new name.
+    Read-only fields are removed and all writable fields are made optional with None as default.
+    """
+    new_model_name = _schema_role_name(model_cls, "Update")
+    new_doc = (
+        model_cls.__doc__ or ""
+    ) + "\nRead-only fields have been removed and all fields are optional."
+
+    # Create a subclass that mixes in both OmitReadOnlyMixin and PatchMixin
+    new_model_cls = type(
+        new_model_name,
+        (PatchMixin, OmitReadOnlyMixin, model_cls),
+        {"__module__": model_cls.__module__, "__doc__": new_doc},
+    )
+
+    return new_model_cls
+
+
+class PatchMixin(pydantic.BaseModel):
+    """
+    A mixin for pydantic classes that makes all fields optional and replaces defaults
+    with None.
+
+    Implementation note: like :class:`OmitReadOnlyMixin` this mutates
+    ``cls.model_fields`` (specifically ``FieldInfo.default`` and
+    ``FieldInfo.annotation``) and then calls ``model_rebuild(force=True)``.
+    This relies on pydantic v2 keeping ``FieldInfo`` mutable; verified on the
+    pinned ``pydantic>=2.11.4`` minimum and exercised by
+    ``tests/test_pydantic_model_fields_mutation.py``.
+    """
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:
+        super().__pydantic_init_subclass__(**kwargs)
+
+        for field in cls.model_fields.values():
+            field.default = None
+            # Only wrap if not already Optional, to avoid Optional[Optional[T]]
+            annotation = field.annotation
+            if isinstance(annotation, types.UnionType):
+                # Python 3.10+ `X | Y` syntax - check if None is already a member.
+                # Convert to typing.Optional form so FieldInfo.annotation stays compatible.
+                union_args = get_args(annotation)
+                if type(None) not in union_args:
+                    non_none = [a for a in union_args if a is not type(None)]
+                    inner = (
+                        non_none[0] if len(non_none) == 1 else Union[tuple(non_none)]
+                    )
+                    field.annotation = Optional[inner]  # type: ignore[assignment]
+            else:
+                origin = getattr(annotation, "__origin__", None)
+                if origin is not Union or type(None) not in get_args(annotation):
+                    field.annotation = Optional[annotation]  # type: ignore[assignment]
+
+        cls.model_rebuild(force=True)
+
+
+def getattrs(obj: Any, *attrs: str, default: Any = None) -> Any:
+    """
+    Try access a chain of attributes and return the default if any of the attrs is not defined.
+    """
+    for attr in attrs:
+        if not hasattr(obj, attr):
+            return default
+        obj = getattr(obj, attr)
+    return obj
+
+
+def set_schema_title(schema_cls: type[pydantic.BaseModel]) -> None:
+    """Set the title of a schema class to its name.
+    This is used to make the schema title match the model name in the OpenAPI schema.
+    """
+    schema_cls.model_config["title"] = schema_cls.__name__
+
+
+def get_writable_inputs(
+    schema_obj: pydantic.BaseModel, schema_cls: type[pydantic.BaseModel] | None = None
+) -> dict[str, Any]:
+    """
+    Return a dictionary of field_name: value pairs for writable input fields.
+
+    Filters out:
+    - ReadOnly fields
+    - fields not provided with input (using Pydantic model_fields_set)
+
+    Args:
+        schema_obj: The schema object to extract writable fields from
+        schema_cls: The schema class to check for readonly fields. If None, uses schema_obj.__class__
+
+    Returns:
+        Dictionary mapping field names to their values for writable input fields only
+    """
+    if schema_cls is None:
+        schema_cls = schema_obj.__class__
+
+    updated_fields: dict[str, Any] = {}
+    for field_name, value in schema_obj:
+        if field_name not in schema_obj.model_fields_set:
+            continue
+        # Skip readonly fields
+        if is_readonly_field(schema_cls, field_name):
+            continue
+        updated_fields[field_name] = value
+
+    return updated_fields