ab-pydantic-patch 1.0.0__py3-none-any.whl

ab_core/pydantic_patch/__init__.py

@@ -0,0 +1,25 @@
+"""Pydantic model transformation helpers for pick/omit/partial/required/patch."""
+
+from ab_core.pydantic_patch.omit import Omit, OmitConfig, create_omit_model
+from ab_core.pydantic_patch.partial import Partial, PartialConfig, create_partial_model
+from ab_core.pydantic_patch.patch import Patch, PatchConfig, create_patch_model
+from ab_core.pydantic_patch.pick import Pick, PickConfig, create_pick_model
+from ab_core.pydantic_patch.required import Required, RequiredConfig, create_required_model
+
+__all__ = [
+    "Pick",
+    "PickConfig",
+    "create_pick_model",
+    "Omit",
+    "OmitConfig",
+    "create_omit_model",
+    "Partial",
+    "PartialConfig",
+    "create_partial_model",
+    "Required",
+    "RequiredConfig",
+    "create_required_model",
+    "Patch",
+    "PatchConfig",
+    "create_patch_model",
+]

ab_core/pydantic_patch/core/__init__.py

@@ -0,0 +1 @@
+"""Core internals for pydantic_patch."""

ab_core/pydantic_patch/core/cache.py

@@ -0,0 +1,43 @@
+"""Cache-key helpers for generated pydantic_patch models."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal
+
+from pydantic import BaseModel
+
+OperationName = Literal["pick", "omit", "partial", "required", "patch"]
+
+
+@dataclass(frozen=True)
+class OperationCacheKey:
+    """Hashable key describing a generated model transformation."""
+
+    source_model: type[BaseModel]
+    operation: OperationName
+    fields: tuple[str, ...] | None = None
+    pick: tuple[str, ...] | None = None
+    omit: tuple[str, ...] | None = None
+    partial: tuple[str, ...] | None = None
+    required: tuple[str, ...] | None = None
+    child_models: tuple[tuple[type[BaseModel], "OperationCacheKey"], ...] = ()
+    name: str | None = None
+
+
+def normalise_field_key(fields: frozenset[str] | None) -> tuple[str, ...] | None:
+    """Return a stable tuple form for cache keys built from field sets."""
+    if fields is None:
+        return None
+    return tuple(sorted(fields))
+
+
+def sort_child_keys(
+    child_keys: Mapping[type[BaseModel], OperationCacheKey],
+) -> tuple[tuple[type[BaseModel], OperationCacheKey], ...]:
+    """Return child cache keys in deterministic model-name order."""
+    return tuple(
+        sorted(
+            child_keys.items(),
+            key=lambda item: f"{item[0].__module__}.{item[0].__qualname__}",
+        )
+    )

ab_core/pydantic_patch/core/classproperty.py

@@ -0,0 +1,14 @@
+"""Descriptor that enables read-only class-level properties."""
+
+
+class classproperty:
+    """Wrap a function so it can be accessed like a class property."""
+
+    def __init__(self, func):
+        """Store the wrapped accessor function."""
+        self.func = func
+
+    def __get__(self, obj, owner):
+        """Resolve the property value from the owning class."""
+        # owner is the class itself
+        return self.func(owner)

ab_core/pydantic_patch/core/config.py

@@ -0,0 +1,12 @@
+"""Shared config helpers."""
+
+from collections.abc import Collection
+
+type FieldSet = frozenset[str] | None
+
+
+def normalise_fields(fields: Collection[str] | None) -> FieldSet:
+    """Normalise user-provided field collections into immutable field sets."""
+    if fields is None:
+        return None
+    return frozenset(fields)

ab_core/pydantic_patch/core/errors.py

@@ -0,0 +1,21 @@
+"""Errors raised by pydantic_patch."""
+
+
+class PydanticPatchError(Exception):
+    """Base exception for pydantic_patch errors."""
+
+
+class InvalidPatchFieldError(PydanticPatchError):
+    """Raised when a configured field does not exist on the target model."""
+
+
+class InvalidDiscriminatorError(PydanticPatchError):
+    """Raised when a discriminated-union transformation would break discrimination."""
+
+
+class UnsupportedAnnotationError(PydanticPatchError):
+    """Raised when an annotation cannot be transformed safely."""
+
+
+class ConflictingPatchConfigError(PydanticPatchError):
+    """Raised when operation configuration conflicts with the generated payload."""

ab_core/pydantic_patch/core/fields.py

@@ -0,0 +1,119 @@
+"""Field validation and payload mutation helpers."""
+
+from functools import reduce
+from operator import or_
+from typing import get_args, get_origin
+
+from pydantic import BaseModel
+
+from ab_core.pydantic_patch.core.errors import (
+    ConflictingPatchConfigError,
+    InvalidPatchFieldError,
+)
+from ab_core.pydantic_patch.core.payload import CreateModelField, CreateModelPayload
+from ab_core.pydantic_patch.core.types import Any
+
+
+def get_source_field_names(model: type[BaseModel]) -> set[str]:
+    """Return source field names including SQLModel relationship attributes."""
+    field_names = set(model.model_fields)
+
+    sqlmodel_relationships = getattr(model, "__sqlmodel_relationships__", {})
+    field_names.update(sqlmodel_relationships)
+
+    return field_names
+
+
+def validate_fields_exist_on_model(
+    model: type[BaseModel],
+    fields: frozenset[str] | None,
+    *,
+    operation: str,
+) -> None:
+    """Validate that all configured fields exist on the source model."""
+    if fields is None:
+        return
+
+    available_fields = get_source_field_names(model)
+    missing = sorted(field for field in fields if field not in available_fields)
+
+    if missing:
+        raise InvalidPatchFieldError(
+            f"Unknown field(s) for {operation} on {model.__name__}: {missing}. "
+            f"Available fields: {sorted(available_fields)}."
+        )
+
+
+def validate_fields_exist_in_payload(
+    payload: CreateModelPayload,
+    fields: frozenset[str] | None,
+    *,
+    model: type[BaseModel],
+    operation: str,
+) -> None:
+    """Validate that all configured fields exist in the currently generated payload."""
+    if fields is None:
+        return
+
+    missing = sorted(field for field in fields if field not in payload)
+    if missing:
+        raise ConflictingPatchConfigError(
+            f"Field(s) {missing} cannot be used for {operation} on {model.__name__} "
+            "because they are not present after pick/omit processing. "
+            f"Available payload fields: {sorted(payload)}."
+        )
+
+
+def allows_none(annotation: Any) -> bool:
+    """Return whether an annotation already allows None."""
+    if annotation is None or annotation is type(None):
+        return True
+
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+
+    if origin is None:
+        return False
+
+    return type(None) in args
+
+
+def make_optional(annotation: Any) -> Any:
+    """Return an annotation that allows None."""
+    if allows_none(annotation):
+        return annotation
+
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return annotation
+
+    origin = get_origin(annotation)
+    if origin in (list, dict, tuple):
+        return annotation
+
+    return annotation | None
+
+
+def strip_none(annotation: Any) -> Any:
+    """Remove None from an annotation if it is a union."""
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+
+    if origin is None or type(None) not in args:
+        return annotation
+
+    non_none_args = tuple(arg for arg in args if arg is not type(None))
+    if not non_none_args:
+        return annotation
+    if len(non_none_args) == 1:
+        return non_none_args[0]
+    return reduce(or_, non_none_args)
+
+
+def make_field_optional(annotation: Any, _default: object) -> CreateModelField:
+    """Return a create_model field definition where the field is optional."""
+    return make_optional(annotation), None
+
+
+def make_field_required(annotation: Any, _default: object) -> CreateModelField:
+    """Return a create_model field definition where the field is required."""
+    return strip_none(annotation), ...

ab_core/pydantic_patch/core/operation.py

@@ -0,0 +1,51 @@
+"""Public Required API."""
+
+from typing import cast
+
+from generic_preserver.utils import canonical_key
+from generic_preserver.wrapper import generic_preserver
+from pydantic import BaseModel
+
+from .classproperty import classproperty
+
+
+@generic_preserver
+class Operation[T: BaseModel]:
+    """Create a model where selected fields are required."""
+
+    @classproperty
+    def source_model(cls) -> type[BaseModel]:
+        """Return the source model bound to the generic operation type."""
+        # NOTE: `generic-preserver` allows us to retrieve the type instance passed to the generic class,
+        #       which is how we get the source model.
+        #
+        #       Whilst this is really convenient, `generic-preserver` intended us to access the generic
+        #       arg via self[T]. However, since we are in the `__new__` part of the object instantiation
+        #       lifecycle, the instance (self) has not yet been created, so we cannot access self[T].
+        #
+        #       Instead, we can read the `generic-preserver` state directly from the class (cls) via
+        #       `cls.__generic_map__`. Since the GenericMeta actually creates a new class for each unique
+        #       set of generic args, the `cls` in this context is already the unique class, therefore we
+        #       don't need to worry about conflicts between different generic args.
+        #
+        #       Whilst this isn't ideal, and it should be noted that this isn't how `generic-preserver` is
+        #       intended to be used, it works and allows us to have a really clean API for users of our library,
+        #       so it's a worthwhile tradeoff IMO.
+        #
+        #       It should also be noted that this relies on string serialisation of the generic arg (canonical_key(T))
+        #       to retrieve the source model, which feels a bit hacky, but important to note that this canonical_key
+        #       method comes from the same generic-preserver library, so I don't anticipate it breaking.
+        #
+        #       Just being cautious since we've observed this happening between Python 3.11 and 3.12, where the string
+        #       serialisation of generic args changed from "~T" to "T", respectively.
+        #
+        #       However, since this is an internal implementation detail of our library, we can easily update our code
+        #       to accommodate any changes in the string serialisation of generic args in future versions of Python, so
+        #       it's not a major concern.
+        #
+        generic_map = cast(
+            dict[str, type[BaseModel]],
+            getattr(cls, "__generic_map__", None),
+        )
+        source_model = generic_map[canonical_key(T)]
+        return source_model

ab_core/pydantic_patch/core/payload.py

@@ -0,0 +1,88 @@
+"""Pydantic create_model payload helpers."""
+
+from typing import Annotated, get_args, get_origin, get_type_hints
+
+from pydantic import BaseModel, Discriminator, Field, create_model
+from pydantic.fields import FieldInfo, PydanticUndefined
+
+from ab_core.pydantic_patch.core.types import Any
+
+type CreateModelField = tuple[Any, object]
+type CreateModelPayload = dict[str, CreateModelField]
+
+
+def unwrap_sqlalchemy_mapped(annotation: object) -> object:
+    """Unwrap SQLAlchemy Mapped[T] annotations to T when present."""
+    origin = get_origin(annotation)
+
+    if origin is None:
+        return annotation
+
+    if getattr(origin, "__name__", None) == "Mapped":
+        mapped_args = get_args(annotation)
+        if len(mapped_args) == 1:
+            return mapped_args[0]
+
+    return annotation
+
+
+def clone_field_info(field_info: FieldInfo) -> FieldInfo:
+    """Return a shallow copy of FieldInfo suitable for mutation."""
+    return field_info._copy()  # pyright: ignore[reportPrivateUsage]
+
+
+def _extract_discriminator_metadata(field_info: FieldInfo) -> tuple[Discriminator, ...]:
+    return tuple(item for item in field_info.metadata if isinstance(item, Discriminator))
+
+
+def build_payload_from_model(model: type[BaseModel]) -> CreateModelPayload:
+    """Build a create_model payload from model fields and relationships."""
+    payload: CreateModelPayload = {}
+
+    for field_name, field_info in model.model_fields.items():
+        annotation = field_info.annotation
+        discriminator_metadata = _extract_discriminator_metadata(field_info)
+
+        if discriminator_metadata:
+            annotation = Annotated[annotation, *discriminator_metadata]
+
+        field_copy = clone_field_info(field_info)
+
+        field_copy.default = PydanticUndefined if field_info.is_required() else field_info.default
+
+        payload[field_name] = (annotation, field_copy)
+
+    type_hints = get_type_hints(model, include_extras=True)
+    relationship_names = getattr(model, "__sqlmodel_relationships__", {})
+
+    for relationship_name in relationship_names:
+        if relationship_name in payload:
+            continue
+
+        payload[relationship_name] = (
+            unwrap_sqlalchemy_mapped(type_hints[relationship_name]),
+            Field(default=None),
+        )
+
+    return payload
+
+
+def create_model_from_payload(
+    *,
+    source_model: type[BaseModel],
+    payload: CreateModelPayload,
+    name: str,
+) -> type[BaseModel]:
+    """Create a pydantic model from a prepared payload definition."""
+    created_model = create_model(
+        name,
+        __base__=BaseModel,
+        __module__=source_model.__module__,
+        **payload,
+    )  # ty:ignore[no-matching-overload]
+
+    for field_name, (annotation, _) in payload.items():
+        if get_origin(annotation) is Annotated:
+            created_model.model_fields[field_name].annotation = annotation
+
+    return created_model