ab-pydantic-patch 1.2.0__tar.gz → 1.2.2__tar.gz

{ab_pydantic_patch-1.2.0 → ab_pydantic_patch-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ab-pydantic-patch
-Version: 1.2.0
+Version: 1.2.2
 Summary: Python Pydantic support of TypeScript-style utility types, including Partial, Required, Pick, and Omit. Useful for PATCH endpoints driven from BaseModel / SQLModel classes.
 Author-email: Matt Coulter <mattcoul7@gmail.com>
 License-File: LICENSE
@@ -603,6 +603,71 @@ class HouseholdPatch(BaseModel):
 
 ---
 
+### Computed Fields
+
+`pydantic-patch` supports Pydantic `@computed_field` values in generated models.
+
+Computed fields are treated like regular fields for transformation purposes, so they can be selected, omitted, made optional, or made required using `Pick`, `Omit`, `Partial`, `Required`, and `Patch`.
+
+#### Python
+
+**Before**
+
+```python
+from pydantic import BaseModel, computed_field
+
+
+class User(BaseModel):
+    first_name: str
+    last_name: str
+
+    @computed_field
+    @property
+    def full_name(self) -> str:
+        return f"{self.first_name} {self.last_name}"
+```
+
+---
+
+**Transform**
+
+```python
+UserDisplay = Pick[User](fields={"full_name"})
+
+UserPatch = Patch[User](
+    pick={"first_name", "full_name"},
+    partial={"first_name"},
+    required={"full_name"},
+)
+```
+
+---
+
+**After (conceptual)**
+
+```python
+class UserDisplay(BaseModel):
+    full_name: str
+
+
+class UserPatch(BaseModel):
+    first_name: str | None = None
+    full_name: str
+```
+
+---
+
+Computed fields become part of the generated model payload, which means they:
+
+* participate in `pick` / `omit`
+* can be made optional with `partial`
+* can be forced required with `required`
+* work recursively inside nested transformed models
+
+When using `recursive_patch_orm_scalar(...)`, computed fields from patch payloads are ignored unless they correspond to real mapped ORM scalar attributes or relationships.
+
+---
+
 ## Additional Notes
 
 ### Caching

{ab_pydantic_patch-1.2.0 → ab_pydantic_patch-1.2.2}/README.md

@@ -590,6 +590,71 @@ class HouseholdPatch(BaseModel):
 
 ---
 
+### Computed Fields
+
+`pydantic-patch` supports Pydantic `@computed_field` values in generated models.
+
+Computed fields are treated like regular fields for transformation purposes, so they can be selected, omitted, made optional, or made required using `Pick`, `Omit`, `Partial`, `Required`, and `Patch`.
+
+#### Python
+
+**Before**
+
+```python
+from pydantic import BaseModel, computed_field
+
+
+class User(BaseModel):
+    first_name: str
+    last_name: str
+
+    @computed_field
+    @property
+    def full_name(self) -> str:
+        return f"{self.first_name} {self.last_name}"
+```
+
+---
+
+**Transform**
+
+```python
+UserDisplay = Pick[User](fields={"full_name"})
+
+UserPatch = Patch[User](
+    pick={"first_name", "full_name"},
+    partial={"first_name"},
+    required={"full_name"},
+)
+```
+
+---
+
+**After (conceptual)**
+
+```python
+class UserDisplay(BaseModel):
+    full_name: str
+
+
+class UserPatch(BaseModel):
+    first_name: str | None = None
+    full_name: str
+```
+
+---
+
+Computed fields become part of the generated model payload, which means they:
+
+* participate in `pick` / `omit`
+* can be made optional with `partial`
+* can be forced required with `required`
+* work recursively inside nested transformed models
+
+When using `recursive_patch_orm_scalar(...)`, computed fields from patch payloads are ignored unless they correspond to real mapped ORM scalar attributes or relationships.
+
+---
+
 ## Additional Notes
 
 ### Caching

{ab_pydantic_patch-1.2.0 → ab_pydantic_patch-1.2.2}/pyproject.toml

@@ -28,7 +28,7 @@ description = "Python Pydantic support of TypeScript-style utility types, includ
 name = "ab-pydantic-patch"
 readme = "README.md"
 requires-python = ">=3.12,<4.0"
-version = "1.2.0"
+version = "1.2.2"
 
 [project.optional-dependencies]
 orm = [

ab_pydantic_patch-1.2.2/src/ab_core/pydantic_patch/core/computed_field_type_hints.py

@@ -0,0 +1,109 @@
+"""Computed-field type-hint and payload helpers."""
+
+from collections.abc import Callable, Iterator
+from functools import cached_property
+from inspect import get_annotations
+from typing import cast, get_type_hints
+
+from pydantic import BaseModel, Field
+from pydantic.fields import ComputedFieldInfo, FieldInfo, PydanticUndefined
+
+from ab_core.pydantic_patch.core.forward_references import contains_forward_ref
+from ab_core.pydantic_patch.core.payload_types import CreateModelPayload
+from ab_core.pydantic_patch.core.types import Any
+
+
+def iter_computed_field_infos(
+    model: type[BaseModel],
+) -> Iterator[tuple[str, ComputedFieldInfo]]:
+    """Yield computed-field names and metadata for a model."""
+    yield from model.model_computed_fields.items()
+
+
+def get_computed_field_getter(
+    computed_field_info: ComputedFieldInfo,
+) -> Callable[..., object]:
+    """Return the underlying getter function for a computed field."""
+    wrapped_property = computed_field_info.wrapped_property
+
+    if isinstance(wrapped_property, property):
+        if wrapped_property.fget is None:
+            raise TypeError("Computed field property does not define a getter.")
+        return wrapped_property.fget
+
+    if isinstance(wrapped_property, cached_property):
+        return wrapped_property.func
+
+    raise TypeError(f"Unsupported computed field wrapper type: {type(wrapped_property).__name__}.")
+
+
+def get_raw_computed_field_return_annotation(
+    computed_field_info: ComputedFieldInfo,
+) -> object:
+    """Return the raw computed-field return annotation without evaluating strings."""
+    if computed_field_info.return_type is not PydanticUndefined:
+        return computed_field_info.return_type
+
+    getter = get_computed_field_getter(computed_field_info)
+    annotations = get_annotations(getter, eval_str=False)
+
+    return annotations.get("return", PydanticUndefined)
+
+
+def get_resolved_computed_field_return_annotation(
+    computed_field_info: ComputedFieldInfo,
+) -> Any:
+    """Return the resolved computed-field return annotation for payload generation."""
+    if computed_field_info.return_type is not PydanticUndefined:
+        return computed_field_info.return_type
+
+    getter = get_computed_field_getter(computed_field_info)
+    resolved_annotations = get_type_hints(getter, include_extras=True)
+
+    return resolved_annotations.get("return", Any)
+
+
+def get_computed_field_return_annotation(
+    computed_field_info: ComputedFieldInfo,
+) -> Any:
+    """Return the computed-field return annotation."""
+    return get_resolved_computed_field_return_annotation(computed_field_info)
+
+
+def computed_field_contains_forward_ref(
+    computed_field_info: ComputedFieldInfo,
+) -> bool:
+    """Return whether a computed field has an unresolved return annotation."""
+    return contains_forward_ref(get_raw_computed_field_return_annotation(computed_field_info))
+
+
+def create_computed_field_info(
+    computed_field_info: ComputedFieldInfo,
+) -> FieldInfo:
+    """Create a concrete pydantic field definition from a computed field."""
+    return cast(
+        FieldInfo,
+        Field(
+            default=PydanticUndefined,
+            alias=computed_field_info.alias,
+            title=computed_field_info.title,
+            description=computed_field_info.description,
+            examples=computed_field_info.examples,
+            json_schema_extra=computed_field_info.json_schema_extra,
+        ),
+    )
+
+
+def apply_computed_fields_to_payload(
+    model: type[BaseModel],
+    payload: CreateModelPayload,
+) -> None:
+    """Insert computed fields into a create_model payload."""
+    for field_name, computed_field_info in iter_computed_field_infos(model):
+        if field_name in payload:
+            continue
+
+        payload[field_name] = (
+            get_resolved_computed_field_return_annotation(computed_field_info),
+            create_computed_field_info(computed_field_info),
+        )

ab_pydantic_patch-1.2.2/src/ab_core/pydantic_patch/core/field_type_hints.py

@@ -0,0 +1,62 @@
+"""Pydantic model-field type-hint and payload helpers."""
+
+from collections.abc import Iterator
+from typing import Annotated, get_origin
+
+from pydantic import BaseModel, Discriminator
+from pydantic.fields import FieldInfo, PydanticUndefined
+
+from ab_core.pydantic_patch.core.payload_types import CreateModelPayload
+from ab_core.pydantic_patch.core.types import Any
+
+
+def iter_model_field_infos(
+    model: type[BaseModel],
+) -> Iterator[tuple[str, FieldInfo]]:
+    """Yield concrete pydantic model-field names and metadata."""
+    yield from model.model_fields.items()
+
+
+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 discriminator metadata attached to a field."""
+    return tuple(item for item in field_info.metadata if isinstance(item, Discriminator))
+
+
+def get_model_field_annotation(
+    field_name: str,
+    field_info: FieldInfo,
+    resolved_type_hints: dict[str, object],
+) -> Any:
+    """Return the resolved annotation for a normal pydantic model field."""
+    annotation: Any = resolved_type_hints.get(field_name, field_info.annotation)
+    discriminator_metadata = extract_discriminator_metadata(field_info)
+
+    if discriminator_metadata and get_origin(annotation) is not Annotated:
+        return Annotated[annotation, *discriminator_metadata]
+
+    return annotation
+
+
+def create_model_field_info(field_info: FieldInfo) -> FieldInfo:
+    """Create the field info to use in a generated payload."""
+    field_copy = clone_field_info(field_info)
+    field_copy.default = PydanticUndefined if field_info.is_required() else field_info.default
+    return field_copy
+
+
+def apply_model_fields_to_payload(
+    model: type[BaseModel],
+    resolved_type_hints: dict[str, object],
+    payload: CreateModelPayload,
+) -> None:
+    """Insert normal pydantic model fields into a create_model payload."""
+    for field_name, field_info in iter_model_field_infos(model):
+        payload[field_name] = (
+            get_model_field_annotation(field_name, field_info, resolved_type_hints),
+            create_model_field_info(field_info),
+        )

{ab_pydantic_patch-1.2.0 → ab_pydantic_patch-1.2.2}/src/ab_core/pydantic_patch/core/fields.py

@@ -6,22 +6,24 @@ from typing import get_args, get_origin
 
 from pydantic import BaseModel
 
+from ab_core.pydantic_patch.core.computed_field_type_hints import iter_computed_field_infos
 from ab_core.pydantic_patch.core.errors import (
     ConflictingPatchConfigError,
     InvalidPatchFieldError,
 )
+from ab_core.pydantic_patch.core.field_type_hints import iter_model_field_infos
+from ab_core.pydantic_patch.core.orm_type_hints import iter_orm_relationship_names
 from ab_core.pydantic_patch.core.payload_types 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
+    """Return transformable source field names."""
+    return {
+        *(field_name for field_name, _ in iter_model_field_infos(model)),
+        *(field_name for field_name, _ in iter_computed_field_infos(model)),
+        *iter_orm_relationship_names(model),
+    }
 
 
 def validate_fields_exist_on_model(

ab_pydantic_patch-1.2.2/src/ab_core/pydantic_patch/core/orm_type_hints.py

@@ -0,0 +1,54 @@
+"""SQLModel relationship type-hint and payload helpers."""
+
+from collections.abc import Iterator
+from typing import get_args, get_origin
+
+from pydantic import BaseModel, Field
+
+from ab_core.pydantic_patch.core.types import Any
+
+from .payload_types import CreateModelPayload
+
+
+def iter_orm_relationship_names(model: type[BaseModel]) -> Iterator[str]:
+    """Yield SQLModel relationship field names for a model."""
+    yield from getattr(model, "__sqlmodel_relationships__", {})
+
+
+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 get_orm_relationship_annotation(
+    relationship_name: str,
+    resolved_type_hints: dict[str, Any],
+) -> object:
+    """Return the resolved annotation for a SQLModel relationship."""
+    return unwrap_sqlalchemy_mapped(resolved_type_hints[relationship_name])
+
+
+def apply_orm_relationships_to_payload(
+    model: type[BaseModel],
+    resolved_type_hints: dict[str, Any],
+    payload: CreateModelPayload,
+) -> None:
+    """Insert SQLModel relationship fields into a create_model payload."""
+    for relationship_name in iter_orm_relationship_names(model):
+        if relationship_name in payload:
+            continue
+
+        payload[relationship_name] = (
+            get_orm_relationship_annotation(relationship_name, resolved_type_hints),
+            Field(default=None),
+        )

ab_pydantic_patch-1.2.2/src/ab_core/pydantic_patch/core/payload.py

@@ -0,0 +1,44 @@
+"""Pydantic create_model payload aggregation helpers."""
+
+from typing import Annotated, get_origin
+
+from pydantic import BaseModel, create_model
+
+from .computed_field_type_hints import apply_computed_fields_to_payload
+from .field_type_hints import apply_model_fields_to_payload
+from .orm_type_hints import apply_orm_relationships_to_payload
+from .payload_types import CreateModelPayload
+from .type_hints import get_resolved_type_hints
+
+
+def build_payload_from_model(model: type[BaseModel]) -> CreateModelPayload:
+    """Build a create_model payload from fields, computed fields, and relationships."""
+    payload: CreateModelPayload = {}
+    resolved_type_hints = get_resolved_type_hints(model)
+
+    apply_model_fields_to_payload(model, resolved_type_hints, payload)
+    apply_computed_fields_to_payload(model, payload)
+    apply_orm_relationships_to_payload(model, resolved_type_hints, payload)
+
+    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

{ab_pydantic_patch-1.2.0 → ab_pydantic_patch-1.2.2}/src/ab_core/pydantic_patch/core/type_hints.py

@@ -4,6 +4,10 @@ from typing import get_type_hints
 
 from pydantic import BaseModel
 
+from .computed_field_type_hints import (
+    computed_field_contains_forward_ref,
+    iter_computed_field_infos,
+)
 from .errors import ForwardReferencesNotSupported
 from .forward_references import build_forward_ref_error_message
 
@@ -21,6 +25,25 @@ def get_resolved_type_hints(model: type[BaseModel]) -> dict[str, object]:
         ) from error
 
 
+def unresolved_computed_field_names(model: type[BaseModel]) -> list[str]:
+    """Return computed fields with unresolved return annotations."""
+    return sorted(
+        field_name
+        for field_name, computed_field_info in iter_computed_field_infos(model)
+        if computed_field_contains_forward_ref(computed_field_info)
+    )
+
+
 def assert_no_forward_refs(model: type[BaseModel]) -> None:
     """Raise only when forward references cannot actually be resolved."""
     get_resolved_type_hints(model)
+
+    unresolved_computed_fields = unresolved_computed_field_names(model)
+
+    if unresolved_computed_fields:
+        raise ForwardReferencesNotSupported(
+            build_forward_ref_error_message(
+                model=model,
+                unresolved_fields=unresolved_computed_fields,
+            )
+        )

ab_pydantic_patch-1.2.2/src/ab_core/pydantic_patch/examples/pydantic_examples/pydantic_computed_fields.py

@@ -0,0 +1,139 @@
+"""Pydantic computed-field patch example."""
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, computed_field
+
+from ab_core.pydantic_patch.orm_patch import recursive_patch_scalar
+from ab_core.pydantic_patch.patch import Patch
+
+ENTITY_ID = 1
+
+
+# =========================
+# MODELS
+# =========================
+
+
+class User(BaseModel):
+    id: int
+    first_name: str
+    last_name: str
+    age: int
+
+    @computed_field
+    @property
+    def full_name(self) -> str:
+        """Return the user's full name."""
+        return f"{self.first_name} {self.last_name}"
+
+    @computed_field
+    @property
+    def is_adult(self) -> bool:
+        """Return whether the user is an adult."""
+        return self.age >= 18
+
+
+# =========================
+# PATCH MODEL
+# =========================
+
+UserPatch = Patch[User](
+    pick={
+        "first_name",
+        "last_name",
+        "full_name",
+    },
+    partial={
+        "first_name",
+        "last_name",
+    },
+    required={
+        "full_name",
+    },
+)
+
+
+# =========================
+# STORE
+# =========================
+
+USERS: dict[int, User] = {}
+
+
+def seed() -> None:
+    USERS.setdefault(
+        ENTITY_ID,
+        User(
+            id=ENTITY_ID,
+            first_name="Monique",
+            last_name="Kuhn",
+            age=28,
+        ),
+    )
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI):
+    seed()
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+# =========================
+# API
+# =========================
+
+
+@app.get("/users/{user_id}", response_model=User)
+def get_user(user_id: int) -> User:
+    user = USERS.get(user_id)
+
+    if user is None:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    return user
+
+
+@app.patch("/users/{user_id}", response_model=User)
+def patch_user(
+    user_id: int,
+    patch: UserPatch,
+) -> User:
+    user = USERS.get(user_id)
+
+    if user is None:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    recursive_patch_scalar(user, patch)
+
+    return user
+
+
+# =========================
+# RUN
+# =========================
+
+
+def get_module_path(file_path: str) -> str:
+    parts = Path(file_path).resolve().with_suffix("").relative_to(Path.cwd()).parts
+
+    if parts[0] == "src":
+        parts = parts[1:]
+
+    return ".".join(parts)
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(
+        f"{get_module_path(__file__)}:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=False,
+    )

ab_pydantic_patch-1.2.2/src/ab_core/pydantic_patch/examples/sqlmodel_examples/models/user.py

@@ -0,0 +1,33 @@
+"""SQLModel computed-field patch example."""
+
+from pydantic import computed_field
+from sqlmodel import Field, SQLModel
+
+ENTITY_ID = 1
+
+
+# =========================
+# MODELS
+# =========================
+
+
+class User(SQLModel, table=True):
+    __tablename__ = "computed_field_user"
+
+    id: int | None = Field(default=None, primary_key=True)
+
+    first_name: str
+    last_name: str
+    email: str
+
+    @computed_field
+    @property
+    def full_name(self) -> str:
+        """Return the user's full name."""
+        return f"{self.first_name} {self.last_name}"
+
+    @computed_field
+    @property
+    def email_domain(self) -> str:
+        """Return the email domain portion."""
+        return self.email.split("@")[-1]