hare-orm 0.9.0__py3-none-any.whl

hare/contrib/pydantic/creation/relation_field_schemas.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast, get_args
+
+from pydantic import field_validator
+
+from hare import (
+    BackwardForeignKeyRelation,
+    BackwardOneToOneRelation,
+    ForeignKeyFieldInstance,
+    OneToOneFieldInstance,
+)
+from hare.contrib.pydantic.creation.data_field_schemas import DataFieldSchemas
+from hare.contrib.pydantic.creation.generic_foreign_key_schemas import GenericForeignKeySchemas
+from hare.contrib.pydantic.models.pydantic_model import PydanticModel
+from hare.fields.relations.fields.many_to_many_field_instance import ManyToManyFieldInstance
+from hare.query.scopes.row_scopes import RowScopes
+
+if TYPE_CHECKING:
+    from hare.contrib.pydantic.creation.pydantic_model_creator import PydanticModelCreator, StackEntry
+    from hare.models import Model
+
+
+class RelationFieldSchemas:
+    """The fields a model's relations get in the pydantic model: a nested model of the related one, or
+    its key - for a relation to one row, a list for a relation to many, a discriminated union for a
+    generic foreign key."""
+
+    @staticmethod
+    def add_relation_id_names(model: type[Model], names: tuple[str, ...]) -> tuple[str, ...]:
+        """Adds the shadow id field names of every forward FK/O2O named in ``names``.
+
+        Args:
+            model: The Hare model.
+            names: Field names, possibly naming relations.
+
+        Returns:
+            ``names`` followed by the shadow id field names of the relations it names.
+        """
+        relation_id_names: list[str] = []
+        for name in names:
+            field = model._meta.fields_map.get(name)
+            if isinstance(field, ForeignKeyFieldInstance):
+                relation_id_names.extend(field.source_fields)
+        return tuple(names) + tuple(relation_id_names)
+
+    @staticmethod
+    def add_generic_foreign_keys(creator: PydanticModelCreator) -> None:
+        """Puts each generic foreign key of the model in the schema in place of its branches: on
+        output the union of its targets' schemas told apart by ``type``, on input (and with
+        ``relations_as_ids``) ``{"type": "<branch>", <the target's key fields>}``. The field named in
+        ``exclude`` leaves its branches out too; a schema leaving out every branch has no field.
+
+        Args:
+            creator: The creator of the pydantic model.
+        """
+        fields_map = creator._model_class._meta.fields_map
+        for name, generic_field in creator._model_class._meta.generic_foreign_key_fields.items():
+            if not generic_field.branch_names:
+                continue
+            branch_keys = [
+                key
+                for branch_name in generic_field.branch_names
+                for key in (branch_name, *fields_map[branch_name].source_fields)  # type: ignore[attr-defined]
+            ]
+            present_keys = [key for key in branch_keys if key in creator._properties]
+            if not present_keys:
+                continue
+            submodels = {
+                branch_name: RelationFieldSchemas.get_property_model(creator, branch_name)
+                for branch_name in generic_field.branch_names
+                if branch_name in creator._properties
+            }
+            as_keys = (
+                creator._exclude_read_only
+                or creator._relations_as_ids
+                or len(submodels) != len(generic_field.branch_names)
+                or any(submodel is None for submodel in submodels.values())
+            )
+            if as_keys:
+                annotation = GenericForeignKeySchemas.get_key_union(generic_field, creator._fqname)
+            else:
+                annotation = GenericForeignKeySchemas.get_object_union(
+                    generic_field, cast("dict[str, type[PydanticModel]]", submodels), creator._fqname
+                )
+            optional = name in creator._optional or generic_field.default is not None
+            if generic_field.null or optional:
+                annotation = annotation | None
+            # The field takes the place of its first branch property; the others are dropped.
+            first_key = present_keys[0]
+            field_info = GenericForeignKeySchemas.get_field_info(generic_field, optional)
+            creator._properties = {
+                (name if key == first_key else key): ((annotation, field_info) if key == first_key else value)
+                for key, value in creator._properties.items()
+                if key not in branch_keys or key == first_key
+            }
+            creator._generic_field_validators[f"_hare_generic_{name}"] = field_validator(name, mode="before")(
+                GenericForeignKeySchemas.get_validator(generic_field, as_keys=as_keys)
+            )
+
+    @staticmethod
+    def get_property_model(creator: PydanticModelCreator, field_name: str) -> type[PydanticModel] | None:
+        """The schema a relation property of the schema holds - None for anything else.
+
+        Args:
+            creator: The creator of the pydantic model.
+            field_name: The property name.
+
+        Returns:
+            The schema.
+        """
+        value = creator._properties[field_name]
+        annotation = value[0] if isinstance(value, tuple) else value
+        for candidate in (annotation, *get_args(annotation)):
+            if isinstance(candidate, type) and issubclass(candidate, PydanticModel):
+                return candidate
+        return None
+
+    @staticmethod
+    def can_hide_target(
+        field: ForeignKeyFieldInstance[Model] | OneToOneFieldInstance[Model] | BackwardOneToOneRelation[Model],
+    ) -> bool:
+        """Whether reading forward relation ``field`` can give ``None`` for a set key - its target
+        model's default scope (soft delete, tenant, a custom ``Meta.manager`` filter) may hide the
+        row.
+
+        Args:
+            field: The relation field.
+        """
+        if not isinstance(field, (ForeignKeyFieldInstance, OneToOneFieldInstance)):
+            return False
+        related_model = field.related_model
+        return bool(RowScopes.of(related_model))
+
+    @staticmethod
+    def process_single_field_relation(
+        creator: PydanticModelCreator,
+        field_name: str,
+        field: ForeignKeyFieldInstance[Model] | OneToOneFieldInstance[Model] | BackwardOneToOneRelation[Model],
+        json_schema_extra: dict[str, Any],
+    ) -> type[PydanticModel] | None:
+        """The schema of a relation to one row - optional when the relation can be empty.
+
+        Args:
+            creator: The creator of the schema.
+            field_name: The relation's name.
+            field: The relation.
+            json_schema_extra: The field's JSON Schema extras, filled in.
+
+        Returns:
+            The related schema, None when the relation is left out (recursion, cycles).
+        """
+        python_type = field.get_python_type()
+        model: type[PydanticModel] | None = RelationFieldSchemas.get_submodel(creator, python_type, field_name)
+        if model:
+            creator._relational_fields_index.append((field_name, model.__name__))
+            if field.null:
+                json_schema_extra["nullable"] = True
+            if (
+                field.null
+                or field.default is not None
+                or field_name in creator._optional
+                or DataFieldSchemas.is_tenant_field(creator, field_name, field)
+                or RelationFieldSchemas.can_hide_target(field)
+            ):
+                return cast("type[PydanticModel] | None", model | None)
+            return model
+        return None
+
+    @staticmethod
+    def process_many_field_relation(
+        creator: PydanticModelCreator,
+        field_name: str,
+        field: BackwardForeignKeyRelation[Model] | ManyToManyFieldInstance[Model],
+    ) -> type[list[type[PydanticModel]]] | None:
+        python_type = field.related_model
+        model = RelationFieldSchemas.get_submodel(creator, python_type, field_name)
+        if model:
+            creator._relational_fields_index.append((field_name, model.__name__))
+            return list[model]  # type: ignore[valid-type]
+        return None
+
+    @staticmethod
+    def create_submodel(
+        model: type[Model],
+        *,
+        stack: tuple[StackEntry, ...],
+        exclude: tuple[str, ...] = (),
+        include: tuple[str, ...] = (),
+        computed: tuple[str, ...] = (),
+        name: str | None = None,
+        allow_cycles: bool = False,
+        sort_alphabetically: bool | None = None,
+        max_recursion: int,
+        exclude_sensitive: bool = False,
+        relations_as_ids: bool = False,
+    ) -> type[PydanticModel] | None:
+        """The Pydantic submodel of a related model, guarded against cycles of relations."""
+        # Local import: the creator module imports this module.
+        from hare.contrib.pydantic.creation.pydantic_model_creator import PydanticModelCreator
+
+        if not allow_cycles and model in (stack_entry[0] for stack_entry in stack[:-1]):
+            return None
+
+        # Level 0 is the root model itself, so the Nth stack entry (0-indexed) is level N -
+        # reject once level reaches the configured max_recursion, so max_recursion=1 permits
+        # exactly one level of nested submodels.
+        for level, (_, _, parent_max_recursion) in enumerate(stack):
+            if level >= parent_max_recursion:
+                return None
+        creator = PydanticModelCreator(
+            model,
+            exclude=exclude,
+            include=include,
+            computed=computed,
+            name=name,
+            _stack=stack,
+            allow_cycles=allow_cycles,
+            sort_alphabetically=sort_alphabetically,
+            _max_recursion=max_recursion,
+            _as_submodel=True,
+            exclude_sensitive=exclude_sensitive,
+            relations_as_ids=relations_as_ids,
+        )
+        return creator.create_pydantic_model()
+
+    @staticmethod
+    def get_submodel(
+        creator: PydanticModelCreator, related_model: type[Model] | None, field_name: str
+    ) -> type[PydanticModel] | None:
+        """The Pydantic model of a related model.
+
+        Args:
+            creator: The creator of the pydantic model.
+            related_model: The model the relation points at; None leaves the field out.
+            field_name: The relation field's name.
+        """
+
+        if related_model:
+            new_stack = creator._stack + ((creator._model_class, field_name, creator.meta.max_recursion),)
+
+            prefix_length = len(field_name) + 1
+
+            def get_fields_to_carry_on(field_tuple: tuple[str, ...]) -> tuple[str, ...]:
+                return tuple(
+                    str(field_path[prefix_length:])
+                    for field_path in field_tuple
+                    if field_path.startswith(field_name + ".")
+                )
+
+            submodel = RelationFieldSchemas.create_submodel(
+                related_model,
+                exclude=get_fields_to_carry_on(creator.meta.exclude),
+                include=get_fields_to_carry_on(creator.meta.include),
+                computed=get_fields_to_carry_on(creator.meta.computed),
+                stack=new_stack,
+                allow_cycles=creator.meta.allow_cycles,
+                sort_alphabetically=creator.meta.sort_alphabetically,
+                max_recursion=creator.meta.max_recursion,
+                exclude_sensitive=creator._exclude_sensitive,
+                relations_as_ids=creator._relations_as_ids,
+            )
+        else:
+            submodel = None
+
+        if submodel is None:
+            creator.meta.exclude += (field_name,)
+
+        return submodel

hare/contrib/pydantic/descriptions/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from hare.contrib.pydantic.descriptions.model_description import ModelDescription
+
+__all__ = ["ModelDescription"]

hare/contrib/pydantic/descriptions/computed_field_description.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import dataclasses
+import functools
+from collections.abc import Callable
+from typing import Any
+
+
+@dataclasses.dataclass
+class ComputedFieldDescription:
+    function: Callable[..., Any] | property | functools.cached_property[Any]
+    description: str | None

hare/contrib/pydantic/descriptions/model_description.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any
+
+from hare.fields import Field
+
+if TYPE_CHECKING:
+    from typing import Self
+
+    from hare.models import Model
+
+
+@dataclasses.dataclass
+class ModelDescription:
+    """A model's fields grouped by type, each group in declaration order - what the pydantic
+    model creator builds a schema from. ``ModelDescription.from_model(Book)`` describes a model.
+    """
+
+    #: The model's primary key, as one Field per component - a single-column PK is a 1-item
+    #: list, a composite PK (CompositePrimaryKey) is one entry per component in declared order.
+    pk_fields: list[Field[Any]]
+    #: Every field holding a plain value, except the primary key - the key columns of forward
+    #: relations (``author_id``) included.
+    data_fields: list[Field[Any]] = dataclasses.field(default_factory=list)
+    #: Forward ``ForeignKeyField``s.
+    foreign_key_fields: list[Field[Any]] = dataclasses.field(default_factory=list)
+    #: Backward sides of other models' ``ForeignKeyField``s pointing at this model.
+    backward_foreign_key_fields: list[Field[Any]] = dataclasses.field(default_factory=list)
+    #: Forward ``OneToOneField``s.
+    one_to_one_fields: list[Field[Any]] = dataclasses.field(default_factory=list)
+    #: Backward sides of other models' ``OneToOneField``s pointing at this model.
+    backward_one_to_one_fields: list[Field[Any]] = dataclasses.field(default_factory=list)
+    #: ``ManyToManyField``s, both the declared and the generated reverse ones.
+    many_to_many_fields: list[Field[Any]] = dataclasses.field(default_factory=list)
+
+    @staticmethod
+    def _fields_in(model: type[Model], names: Iterable[str]) -> list[Field[Any]]:
+        return [field for name, field in model._meta.fields_map.items() if name in names]
+
+    @classmethod
+    def from_model(cls, model: type[Model]) -> Self:
+        """Describes a model's fields.
+
+        Args:
+            model: The model; its relations must be initialised (``Hare.init()`` or
+                ``Hare.bind_models()``).
+
+        Returns:
+            The description.
+        """
+        meta = model._meta
+        # The primary key's fields - one or several - are listed here, not among the data fields.
+        primary_key_attribute_names = meta.primary_key_attribute_names
+        # A blind index is hare's own column, written with the encrypted field - its HMAC is no data.
+        blind_index_field_names = set(meta.blind_index_fields.values())
+        return cls(
+            pk_fields=[meta.fields_map[name] for name in primary_key_attribute_names],
+            data_fields=cls._fields_in(
+                model,
+                meta.fields - meta.fetch_fields - set(primary_key_attribute_names) - blind_index_field_names,
+            ),
+            foreign_key_fields=cls._fields_in(model, meta.foreign_key_fields),
+            backward_foreign_key_fields=cls._fields_in(model, meta.backward_foreign_key_fields),
+            one_to_one_fields=cls._fields_in(model, meta.one_to_one_fields),
+            backward_one_to_one_fields=cls._fields_in(model, meta.backward_one_to_one_fields),
+            many_to_many_fields=cls._fields_in(model, meta.many_to_many_fields),
+        )

hare/contrib/pydantic/descriptions/pydantic_meta_data.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import dataclasses
+from typing import TYPE_CHECKING, Any
+
+from pydantic import ConfigDict
+
+if TYPE_CHECKING:
+    from typing import Self
+
+
+@dataclasses.dataclass
+class PydanticMetaData:
+    """The options of a model's Pydantic schemas - what its ``PydanticMeta`` declares, filled in by the defaults."""
+
+    #: If not empty, only fields this property contains will be in the pydantic model
+    include: tuple[str, ...] = ()
+
+    #: Fields listed in this property will be excluded from pydantic model
+    exclude: tuple[str, ...] = dataclasses.field(default_factory=lambda: ("Meta",))
+
+    #: Computed fields can be listed here to use in pydantic model
+    computed: tuple[str, ...] = dataclasses.field(default_factory=tuple)
+
+    #: Use backward relations without annotations - not recommended, it can be huge data
+    #: without control
+    backward_relations: bool = True
+
+    #: Maximum recursion level allowed
+    max_recursion: int = 3
+
+    #: Whether relations may lead back to a model already in the schema - the data then repeats each cycle.
+    #: Use it with ``exclude``/``include`` and a small ``max_recursion``.
+    allow_cycles: bool = False
+
+    #: If we should exclude raw fields (the ones have _id suffixes) of relations
+    exclude_raw_fields: bool = True
+
+    #: Sort fields alphabetically.
+    #: If not set (or ``False``) then leave fields in declaration order
+    sort_alphabetically: bool = False
+
+    #: Allows user to specify custom config for generated model
+    model_config: ConfigDict | None = None
+
+    @staticmethod
+    def _read_meta_fields(source: Any, fallback: PydanticMetaData) -> dict[str, Any]:
+        """Read the 8 shared Meta fields from *source*, falling back to *fallback*'s own value
+        for any attribute *source* doesn't define."""
+
+        def get(attribute_name: str) -> Any:
+            return getattr(source, attribute_name, getattr(fallback, attribute_name))
+
+        return {
+            "include": tuple(get("include")),
+            "exclude": tuple(get("exclude")),
+            "computed": tuple(get("computed")),
+            "backward_relations": bool(get("backward_relations")),
+            "max_recursion": int(get("max_recursion")),
+            "allow_cycles": bool(get("allow_cycles")),
+            "exclude_raw_fields": bool(get("exclude_raw_fields")),
+            "sort_alphabetically": bool(get("sort_alphabetically")),
+        }
+
+    @classmethod
+    def from_pydantic_meta(cls, old_pydantic_meta: Any) -> Self:
+        default_meta = cls()
+        model_config = getattr(old_pydantic_meta, "model_config", default_meta.model_config)
+        return cls(**cls._read_meta_fields(old_pydantic_meta, default_meta), model_config=model_config)
+
+    def construct_pydantic_meta(self, meta_override: type) -> PydanticMetaData:
+        model_config = getattr(meta_override, "model_config", self.model_config)
+        return PydanticMetaData(**self._read_meta_fields(meta_override, self), model_config=model_config)
+
+    def selects(self, name: str) -> bool:
+        """Whether ``include``/``exclude`` put the field ``name`` into the schema.
+
+        A path into a relation in ``include`` (``"author.name"``) selects the relation itself.
+
+        Args:
+            name: The field's name on the model.
+
+        Returns:
+            ``True`` if the field goes into the schema.
+        """
+        if name in self.exclude:
+            return False
+        return not self.include or any(path == name or path.startswith(f"{name}.") for path in self.include)
+
+    @property
+    def model_computed(self) -> tuple[str, ...]:
+        """The computed fields of the model itself - ``computed`` without paths into relations."""
+        return tuple(name for name in self.computed if "." not in name)
+
+    def finalize_meta(
+        self,
+        exclude: tuple[str, ...] = (),
+        include: tuple[str, ...] = (),
+        computed: tuple[str, ...] = (),
+        allow_cycles: bool | None = None,
+        sort_alphabetically: bool | None = None,
+        max_recursion: int | None = None,
+        model_config: ConfigDict | None = None,
+    ) -> PydanticMetaData:
+        """The options with the call's arguments applied - ``exclude``/``include``/``computed`` added to the
+        meta's, the other arguments replacing its values when given.
+
+        Args:
+            exclude: The fields left out.
+            include: The fields kept.
+            computed: The computed fields.
+            allow_cycles: Whether relations may lead back to a model in the schema.
+            sort_alphabetically: Whether the fields are sorted by name.
+            max_recursion: How deep relations are followed.
+            model_config: The Pydantic config of the schema.
+
+        Returns:
+            The options.
+        """
+        _sort_fields: bool = self.sort_alphabetically if sort_alphabetically is None else sort_alphabetically
+        _allow_cycles: bool = self.allow_cycles if allow_cycles is None else allow_cycles
+        _max_recursion: int = self.max_recursion if max_recursion is None else max_recursion
+
+        include = tuple(include) + self.include
+        exclude = tuple(exclude) + self.exclude
+        computed = tuple(computed) + self.computed
+
+        _model_config = ConfigDict()
+        if self.model_config:
+            _model_config.update(self.model_config)
+        if model_config:
+            _model_config.update(model_config)
+
+        return PydanticMetaData(
+            include=include,
+            exclude=exclude,
+            computed=computed,
+            backward_relations=self.backward_relations,
+            max_recursion=_max_recursion,
+            exclude_raw_fields=self.exclude_raw_fields,
+            sort_alphabetically=_sort_fields,
+            allow_cycles=_allow_cycles,
+            model_config=_model_config,
+        )

hare/contrib/pydantic/enums.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class FetchedFieldCheck(StrEnum):
+    """What ``PydanticModel`` checks a schema field is loaded by on a model instance."""
+
+    #: A forward or backward one-to-one relation, or a foreign key: its instance was fetched.
+    RELATED_INSTANCE = "related_instance"
+    #: A to-many relation: its rows were fetched.
+    RELATED_ROWS = "related_rows"

hare/contrib/pydantic/models/__init__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from hare.contrib.pydantic.models.pydantic_list_model import PydanticListModel
+from hare.contrib.pydantic.models.pydantic_model import PydanticModel
+
+__all__ = [
+    "PydanticModel",
+    "PydanticListModel",
+]

hare/contrib/pydantic/models/pydantic_list_model.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import RootModel
+
+from hare.query.queryset import QuerySet
+
+if TYPE_CHECKING:
+    from typing import Self
+
+    from hare.models import Model
+
+
+class PydanticListModel(RootModel[Any]):
+    """Pydantic BaseModel for a list of Hare models.
+
+    Provides extra methods on top of Pydantic's own model properties
+    (https://docs.pydantic.dev/latest/concepts/models/#model-methods-and-properties).
+    """
+
+    @classmethod
+    async def from_queryset(cls, queryset: QuerySet[Model]) -> Self:
+        """Returns a serializable pydantic model instance that contains a list of models, from
+        the provided queryset.
+
+        This will prefetch all the relations automatically.
+
+        Args:
+            queryset: a queryset on the model this PydanticListModel is based on.
+        """
+        submodel = cls.model_config["submodel"]  # type: ignore[typeddict-item]
+        fetch_fields = submodel._get_fetch_fields()
+        return cls.model_validate(submodel._validate_prefetched(list(await queryset.prefetch_related(*fetch_fields))))