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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ab-pydantic-patch
-Version: 1.2.2
+Version: 1.2.4
 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
@@ -717,7 +717,8 @@ Applied in this order:
 
 ### Forward references
 
-`pydantic-patch` does not currently support unresolved forward references.
+`pydantic-patch` automatically resolves forward references among already
+imported sibling model classes.
 
 Because the library is type-driven, it needs real Python types when generating
 `Pick`, `Omit`, `Partial`, `Required`, or `Patch` models. This commonly affects
@@ -734,12 +735,15 @@ class Project(SQLModel, table=True):
     milestones: list["ProjectMilestone"] = Relationship(back_populates="project")
 ```
 
-Calling `Patch[Project](...)` before resolving `"ProjectMilestone"` will raise
+Calling `Patch[Project](...)` works when the referenced sibling models have
+already been imported somewhere in the same package/module tree. If the
+referenced model has not been imported yet, import your model package first or
+bind the missing reference manually.
+
+For genuinely missing types, `pydantic-patch` still raises
 `ForwardReferencesNotSupported`.
 
-To fix this, import all related model modules first, bind the missing shallow
-references onto each module, then call `model_rebuild(force=True)` before
-creating the patch model.
+Manual fallback:
 
 ```python
 import my_app.models.project as project_module
@@ -843,6 +847,125 @@ db_session.commit()
 This is especially useful for FastAPI PATCH endpoints backed by SQLModel
 relationships.
 
+### Self-referencing 1..many trees
+
+`pydantic-patch` supports recursive parent/child tree layouts where a model
+contains a list of children of the same model type.
+
+This is useful for quote line items, category trees, bill-of-materials trees,
+nested tasks, comments, folders, and other hierarchical data.
+
+#### Python
+
+```python
+from sqlmodel import Field, Relationship, SQLModel
+
+from ab_core.pydantic_patch.orm_patch import recursive_patch_orm_scalar
+from ab_core.pydantic_patch.patch import Patch, PatchConfig
+
+
+class QuoteLineItem(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    parent_id: int | None = Field(default=None, foreign_key="quote_line_item.id")
+
+    line_item_name: str = ""
+    quoted_base_cost: float = 0.0
+
+    parent: "QuoteLineItem" = Relationship(
+        back_populates="children",
+        sa_relationship_kwargs={
+            "remote_side": "QuoteLineItem.id",
+        },
+    )
+    children: list["QuoteLineItem"] = Relationship(back_populates="parent")
+
+
+QuoteLineItem.model_rebuild(force=True)
+```
+
+For SQLModel relationships, keep the relationship target annotation as
+`"QuoteLineItem"` rather than `"QuoteLineItem | None"` so SQLAlchemy can resolve
+the mapped class name.
+
+#### Transform
+
+```python
+QuoteLineItemPatch = Patch[QuoteLineItem](
+    name="QuoteLineItemPatch",
+    pick={
+        "id",
+        "line_item_name",
+        "quoted_base_cost",
+        "children",
+    },
+    partial={
+        "id",
+        "line_item_name",
+        "quoted_base_cost",
+        "children",
+    },
+    child_models={
+        QuoteLineItem: PatchConfig(
+            pick={
+                "id",
+                "line_item_name",
+                "quoted_base_cost",
+                "children",
+            },
+            partial={
+                "id",
+                "line_item_name",
+                "quoted_base_cost",
+                "children",
+            },
+        ),
+    },
+)
+```
+
+#### Apply to an ORM object graph
+
+```python
+line_item = db_session.get(QuoteLineItem, line_item_id)
+
+patch = QuoteLineItemPatch.model_validate(
+    {
+        "id": line_item_id,
+        "line_item_name": "Colorbond fence",
+        "children": [
+            {
+                "id": 10,
+                "line_item_name": "Colorbond panels",
+                "quoted_base_cost": 725.0,
+            },
+            {
+                "line_item_name": "New gate allowance",
+                "quoted_base_cost": 300.0,
+            },
+        ],
+    }
+)
+
+recursive_patch_orm_scalar(line_item, patch)
+
+db_session.add(line_item)
+db_session.commit()
+```
+
+In this layout:
+
+* child rows with an `id` are patched onto matching existing ORM children
+* child rows without an `id` are treated as new children
+* omitted fields are left unchanged
+* nested `children` can recursively patch deeper descendants
+* the generated recursive patch model can be reused in FastAPI request bodies
+
+For a runnable example, see:
+
+```shell
+uv run python src/ab_core/pydantic_patch/examples/sqlmodel_examples/self_referencing_tree.py
+```
+
 ______________________________________________________________________
 
 ## Formatting and linting

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

@@ -704,7 +704,8 @@ Applied in this order:
 
 ### Forward references
 
-`pydantic-patch` does not currently support unresolved forward references.
+`pydantic-patch` automatically resolves forward references among already
+imported sibling model classes.
 
 Because the library is type-driven, it needs real Python types when generating
 `Pick`, `Omit`, `Partial`, `Required`, or `Patch` models. This commonly affects
@@ -721,12 +722,15 @@ class Project(SQLModel, table=True):
     milestones: list["ProjectMilestone"] = Relationship(back_populates="project")
 ```
 
-Calling `Patch[Project](...)` before resolving `"ProjectMilestone"` will raise
+Calling `Patch[Project](...)` works when the referenced sibling models have
+already been imported somewhere in the same package/module tree. If the
+referenced model has not been imported yet, import your model package first or
+bind the missing reference manually.
+
+For genuinely missing types, `pydantic-patch` still raises
 `ForwardReferencesNotSupported`.
 
-To fix this, import all related model modules first, bind the missing shallow
-references onto each module, then call `model_rebuild(force=True)` before
-creating the patch model.
+Manual fallback:
 
 ```python
 import my_app.models.project as project_module
@@ -830,6 +834,125 @@ db_session.commit()
 This is especially useful for FastAPI PATCH endpoints backed by SQLModel
 relationships.
 
+### Self-referencing 1..many trees
+
+`pydantic-patch` supports recursive parent/child tree layouts where a model
+contains a list of children of the same model type.
+
+This is useful for quote line items, category trees, bill-of-materials trees,
+nested tasks, comments, folders, and other hierarchical data.
+
+#### Python
+
+```python
+from sqlmodel import Field, Relationship, SQLModel
+
+from ab_core.pydantic_patch.orm_patch import recursive_patch_orm_scalar
+from ab_core.pydantic_patch.patch import Patch, PatchConfig
+
+
+class QuoteLineItem(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    parent_id: int | None = Field(default=None, foreign_key="quote_line_item.id")
+
+    line_item_name: str = ""
+    quoted_base_cost: float = 0.0
+
+    parent: "QuoteLineItem" = Relationship(
+        back_populates="children",
+        sa_relationship_kwargs={
+            "remote_side": "QuoteLineItem.id",
+        },
+    )
+    children: list["QuoteLineItem"] = Relationship(back_populates="parent")
+
+
+QuoteLineItem.model_rebuild(force=True)
+```
+
+For SQLModel relationships, keep the relationship target annotation as
+`"QuoteLineItem"` rather than `"QuoteLineItem | None"` so SQLAlchemy can resolve
+the mapped class name.
+
+#### Transform
+
+```python
+QuoteLineItemPatch = Patch[QuoteLineItem](
+    name="QuoteLineItemPatch",
+    pick={
+        "id",
+        "line_item_name",
+        "quoted_base_cost",
+        "children",
+    },
+    partial={
+        "id",
+        "line_item_name",
+        "quoted_base_cost",
+        "children",
+    },
+    child_models={
+        QuoteLineItem: PatchConfig(
+            pick={
+                "id",
+                "line_item_name",
+                "quoted_base_cost",
+                "children",
+            },
+            partial={
+                "id",
+                "line_item_name",
+                "quoted_base_cost",
+                "children",
+            },
+        ),
+    },
+)
+```
+
+#### Apply to an ORM object graph
+
+```python
+line_item = db_session.get(QuoteLineItem, line_item_id)
+
+patch = QuoteLineItemPatch.model_validate(
+    {
+        "id": line_item_id,
+        "line_item_name": "Colorbond fence",
+        "children": [
+            {
+                "id": 10,
+                "line_item_name": "Colorbond panels",
+                "quoted_base_cost": 725.0,
+            },
+            {
+                "line_item_name": "New gate allowance",
+                "quoted_base_cost": 300.0,
+            },
+        ],
+    }
+)
+
+recursive_patch_orm_scalar(line_item, patch)
+
+db_session.add(line_item)
+db_session.commit()
+```
+
+In this layout:
+
+* child rows with an `id` are patched onto matching existing ORM children
+* child rows without an `id` are treated as new children
+* omitted fields are left unchanged
+* nested `children` can recursively patch deeper descendants
+* the generated recursive patch model can be reused in FastAPI request bodies
+
+For a runnable example, see:
+
+```shell
+uv run python src/ab_core/pydantic_patch/examples/sqlmodel_examples/self_referencing_tree.py
+```
+
 ______________________________________________________________________
 
 ## Formatting and linting

{ab_pydantic_patch-1.2.2 → ab_pydantic_patch-1.2.4}/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.2"
+version = "1.2.4"
 
 [project.optional-dependencies]
 orm = [

{ab_pydantic_patch-1.2.2 → ab_pydantic_patch-1.2.4}/src/ab_core/pydantic_patch/core/computed_field_type_hints.py

@@ -8,7 +8,10 @@ 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.forward_references import (
+    build_type_hints_namespaces,
+    contains_forward_ref,
+)
 from ab_core.pydantic_patch.core.payload_types import CreateModelPayload
 from ab_core.pydantic_patch.core.types import Any
 
@@ -51,6 +54,7 @@ def get_raw_computed_field_return_annotation(
 
 
 def get_resolved_computed_field_return_annotation(
+    model: type[BaseModel],
     computed_field_info: ComputedFieldInfo,
 ) -> Any:
     """Return the resolved computed-field return annotation for payload generation."""
@@ -58,23 +62,42 @@ def get_resolved_computed_field_return_annotation(
         return computed_field_info.return_type
 
     getter = get_computed_field_getter(computed_field_info)
-    resolved_annotations = get_type_hints(getter, include_extras=True)
+    globalns, localns = build_type_hints_namespaces(model)
+
+    resolved_annotations = get_type_hints(
+        getter,
+        globalns=globalns,
+        localns=localns,
+        include_extras=True,
+    )
 
     return resolved_annotations.get("return", Any)
 
 
 def get_computed_field_return_annotation(
+    model: type[BaseModel],
     computed_field_info: ComputedFieldInfo,
 ) -> Any:
     """Return the computed-field return annotation."""
-    return get_resolved_computed_field_return_annotation(computed_field_info)
+    return get_resolved_computed_field_return_annotation(model, computed_field_info)
 
 
 def computed_field_contains_forward_ref(
+    model: type[BaseModel],
     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))
+    raw_annotation = get_raw_computed_field_return_annotation(computed_field_info)
+
+    if not contains_forward_ref(raw_annotation):
+        return False
+
+    try:
+        get_resolved_computed_field_return_annotation(model, computed_field_info)
+    except NameError:
+        return True
+
+    return False
 
 
 def create_computed_field_info(
@@ -104,6 +127,6 @@ def apply_computed_fields_to_payload(
             continue
 
         payload[field_name] = (
-            get_resolved_computed_field_return_annotation(computed_field_info),
+            get_resolved_computed_field_return_annotation(model, computed_field_info),
             create_computed_field_info(computed_field_info),
         )

{ab_pydantic_patch-1.2.2 → ab_pydantic_patch-1.2.4}/src/ab_core/pydantic_patch/core/forward_references.py

@@ -1,4 +1,4 @@
-"""Helpers for detecting and reporting unresolved forward references."""
+"""Helpers for detecting and resolving forward references."""
 
 import sys
 from textwrap import dedent, indent
@@ -52,6 +52,43 @@ def _iter_model_modules(root_model: type[BaseModel]) -> list[str]:
     return sorted(module_name for module_name in module_names if _iter_models_in_module(module_name))
 
 
+def build_model_namespace(root_model: type[BaseModel]) -> dict[str, type[BaseModel]]:
+    """Build a temporary namespace of imported sibling BaseModel classes.
+
+    This is used to resolve string / ForwardRef annotations without requiring
+    developers to manually bind circular model references onto their modules.
+    """
+    return {
+        model.__name__: model
+        for module_name in _iter_model_modules(root_model)
+        for model in _iter_models_in_module(module_name)
+    }
+
+
+def build_type_hints_namespaces(
+    model: type[BaseModel],
+) -> tuple[dict[str, object], dict[str, object]]:
+    """Return globalns/localns for resolving a model's annotations."""
+    module = sys.modules.get(model.__module__)
+    module_globals: dict[str, object] = {}
+
+    if module is not None:
+        module_globals.update(vars(module))
+
+    model_namespace = build_model_namespace(model)
+
+    globalns = {
+        **module_globals,
+        **model_namespace,
+    }
+    localns = {
+        **model_namespace,
+        model.__name__: model,
+    }
+
+    return globalns, localns
+
+
 def unresolved_annotation_names(model: type[BaseModel]) -> list[str]:
     """Collect unresolved forward-reference annotation names for model modules."""
     unresolved: list[str] = []
@@ -91,9 +128,7 @@ def _forward_ref_name(annotation: object) -> str | None:
 
 def _build_resolution_example(root_model: type[BaseModel]) -> str:
     module_names = _iter_model_modules(root_model)
-    models_by_name = {
-        model.__name__: model for module_name in module_names for model in _iter_models_in_module(module_name)
-    }
+    models_by_name = build_model_namespace(root_model)
 
     imports = [f"import {module_name} as {_module_alias(module_name)}" for module_name in module_names]
 
@@ -143,30 +178,25 @@ def build_forward_ref_error_message(
 
     return dedent(
         f"""
-        Forward references are not supported by pydantic-patch until they are resolved.
+        Forward references could not be resolved automatically.
 
-        pydantic-patch is type-driven and needs real Python types when generating
-        Pick/Omit/Partial/Required/Patch models. The model {model.__name__!r} has
-        unresolved forward-reference annotation(s): {sorted(set(unresolved_fields))!r}.
+        pydantic-patch tried to resolve imported sibling BaseModel / SQLModel
+        classes before generating Pick/Omit/Partial/Required/Patch models, but
+        the model {model.__name__!r} still has unresolved forward-reference
+        annotation(s): {sorted(set(unresolved_fields))!r}.
 
-        This usually happens with SQLModel relationships split across modules, where
-        relationship attributes are declared with strings to avoid circular imports.
+        This usually means the referenced model has not been imported anywhere
+        reachable from the root model's package, or the annotation points to a
+        genuinely missing type.
 
         See the resolved SQLModel example here:
         {RESOLVED_EXAMPLE_URL}
 
-        Import every related ORM module first, bind the shallow circular references
-        onto their source modules, then rebuild every affected model before calling
-        Patch[...], Pick[...], Omit[...], Partial[...] or Required[...].
-
-        Suggested fix:
+        Suggested manual fallback:
 
         ```python
 {resolution_example}
         ```
 
-        This setup usually belongs in your models package __init__.py, or in another
-        central models module that imports and prepares all ORM models before patch
-        schemas are generated.
         """
     ).strip()

{ab_pydantic_patch-1.2.2 → ab_pydantic_patch-1.2.4}/src/ab_core/pydantic_patch/core/transform.py

@@ -3,7 +3,7 @@
 from collections.abc import Callable, Mapping
 from functools import reduce
 from operator import or_
-from typing import Annotated, Protocol, Self, TypeVar, get_args, get_origin
+from typing import Annotated, ForwardRef, Protocol, Self, TypeVar, get_args, get_origin
 
 from pydantic import BaseModel
 
@@ -49,6 +49,9 @@ type DiscriminatorChildConfigPreparer[ConfigT: TransformConfig] = Callable[
 ]
 
 _TRANSFORM_MODEL_CACHE: dict[OperationCacheKey, type[BaseModel]] = {}
+_TRANSFORM_BUILD_STACK: list[tuple[type[BaseModel], OperationName, str, str | None]] = []
+_TRANSFORM_BUILD_NAMESPACE: dict[str, type[BaseModel]] = {}
+_TRANSFORM_BUILD_CREATED_MODELS: list[type[BaseModel]] = []
 
 
 def prepare_discriminator_child_config_default[ConfigT: TransformConfig](
@@ -79,6 +82,45 @@ def default_model_name(source_model: type[BaseModel], suffix: str) -> str:
     return f"{source_model.__name__}{suffix}"
 
 
+def transformed_model_name(source_model: type[BaseModel], suffix: str, name: str | None) -> str:
+    """Return the concrete transformed model name."""
+    return name or default_model_name(source_model, suffix)
+
+
+def transform_build_key(
+    source_model: type[BaseModel],
+    operation: OperationName,
+    suffix: str,
+    name: str | None,
+) -> tuple[type[BaseModel], OperationName, str, str | None]:
+    """Return the key used to identify an in-progress transformed model."""
+    return (source_model, operation, suffix, name)
+
+
+def find_active_build_name(
+    source_model: type[BaseModel],
+    operation: OperationName,
+    suffix: str,
+) -> str | None:
+    """Return the active generated model name for a recursive transform."""
+    for active_source_model, active_operation, active_suffix, active_name in reversed(_TRANSFORM_BUILD_STACK):
+        if active_source_model is source_model and active_operation == operation and active_suffix == suffix:
+            return transformed_model_name(active_source_model, active_suffix, active_name)
+
+    return None
+
+
+def rebuild_created_models() -> None:
+    """Resolve generated-model forward references created during recursion."""
+    if not _TRANSFORM_BUILD_NAMESPACE:
+        return
+
+    type_namespace = dict(_TRANSFORM_BUILD_NAMESPACE)
+
+    for model in _TRANSFORM_BUILD_CREATED_MODELS:
+        model.model_rebuild(force=True, _types_namespace=type_namespace)
+
+
 def build_transformed_model(
     source_model: type[BaseModel],
     *,
@@ -92,28 +134,46 @@ def build_transformed_model(
     use_cache: bool,
 ) -> type[BaseModel]:
     """Build a transformed model and recursively transform nested annotations."""
-    assert_no_forward_refs(source_model)
+    build_key = transform_build_key(source_model, operation, suffix, name)
+    is_root_build = not _TRANSFORM_BUILD_STACK
+    _TRANSFORM_BUILD_STACK.append(build_key)
 
-    payload = build_payload_from_model(source_model)
-    payload = mutate_payload(payload, source_model, config)
+    try:
+        assert_no_forward_refs(source_model)
 
-    payload = transform_payload_annotations(
-        payload,
-        config=config,
-        operation=operation,
-        suffix=suffix,
-        mutate_payload=mutate_payload,
-        make_cache_key=make_cache_key,
-        prepare_discriminator_child_config=prepare_discriminator_child_config,
-        use_cache=use_cache,
-    )
+        payload = build_payload_from_model(source_model)
+        payload = mutate_payload(payload, source_model, config)
 
-    model_name = name or default_model_name(source_model, suffix)
-    return create_model_from_payload(
-        source_model=source_model,
-        payload=payload,
-        name=model_name,
-    )
+        payload = transform_payload_annotations(
+            payload,
+            config=config,
+            operation=operation,
+            suffix=suffix,
+            mutate_payload=mutate_payload,
+            make_cache_key=make_cache_key,
+            prepare_discriminator_child_config=prepare_discriminator_child_config,
+            use_cache=use_cache,
+        )
+
+        model_name = transformed_model_name(source_model, suffix, name)
+        transformed_model = create_model_from_payload(
+            source_model=source_model,
+            payload=payload,
+            name=model_name,
+        )
+        _TRANSFORM_BUILD_NAMESPACE[model_name] = transformed_model
+        _TRANSFORM_BUILD_CREATED_MODELS.append(transformed_model)
+
+        return transformed_model
+    finally:
+        _TRANSFORM_BUILD_STACK.pop()
+
+        if is_root_build:
+            try:
+                rebuild_created_models()
+            finally:
+                _TRANSFORM_BUILD_NAMESPACE.clear()
+                _TRANSFORM_BUILD_CREATED_MODELS.clear()
 
 
 def transform_model_cached(
@@ -164,6 +224,10 @@ def transform_model(
     use_cache: bool = True,
 ) -> type[BaseModel]:
     """Transform a model according to an operation configuration."""
+    active_model_name = find_active_build_name(source_model, operation, suffix)
+    if active_model_name is not None:
+        return ForwardRef(active_model_name)
+
     if use_cache:
         return transform_model_cached(
             source_model,

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

@@ -9,13 +9,23 @@ from .computed_field_type_hints import (
     iter_computed_field_infos,
 )
 from .errors import ForwardReferencesNotSupported
-from .forward_references import build_forward_ref_error_message
+from .forward_references import (
+    build_forward_ref_error_message,
+    build_type_hints_namespaces,
+)
 
 
 def get_resolved_type_hints(model: type[BaseModel]) -> dict[str, object]:
-    """Resolve model type hints and raise custom errors on unresolved refs."""
+    """Resolve model type hints and raise custom errors on truly unresolved refs."""
+    globalns, localns = build_type_hints_namespaces(model)
+
     try:
-        return get_type_hints(model, include_extras=True)
+        return get_type_hints(
+            model,
+            globalns=globalns,
+            localns=localns,
+            include_extras=True,
+        )
     except NameError as error:
         raise ForwardReferencesNotSupported(
             build_forward_ref_error_message(
@@ -30,7 +40,7 @@ def unresolved_computed_field_names(model: type[BaseModel]) -> list[str]:
     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)
+        if computed_field_contains_forward_ref(model, computed_field_info)
     )
 
 

{ab_pydantic_patch-1.2.2 → ab_pydantic_patch-1.2.4}/src/ab_core/pydantic_patch/examples/sqlmodel_examples/models/__init__.py

@@ -1,11 +1,13 @@
 from ab_core.pydantic_patch.examples.sqlmodel_examples.models.project import Project
 from ab_core.pydantic_patch.examples.sqlmodel_examples.models.project_milestone import ProjectMilestone
 from ab_core.pydantic_patch.examples.sqlmodel_examples.models.project_task import ProjectTask
+from ab_core.pydantic_patch.examples.sqlmodel_examples.models.quote_line_item import QuoteLineItem
 from ab_core.pydantic_patch.examples.sqlmodel_examples.models.task_comment import TaskComment
 
 __all__ = [
     "Project",
     "ProjectMilestone",
     "ProjectTask",
+    "QuoteLineItem",
     "TaskComment",
 ]

ab_pydantic_patch-1.2.4/src/ab_core/pydantic_patch/examples/sqlmodel_examples/models/quote_line_item.py

@@ -0,0 +1,23 @@
+"""Self-referencing quote line item SQLModel."""
+
+from sqlmodel import Field, Relationship, SQLModel
+
+
+class QuoteLineItem(SQLModel, table=True):
+    """A quote line item that can contain child line items."""
+
+    __tablename__ = "self_referencing_quote_line_item"
+
+    id: int | None = Field(default=None, primary_key=True)
+    parent_id: int | None = Field(default=None, foreign_key="self_referencing_quote_line_item.id")
+
+    line_item_name: str = ""
+    quoted_base_cost: float = 0.0
+
+    parent: "QuoteLineItem" = Relationship(
+        back_populates="children",
+        sa_relationship_kwargs={
+            "remote_side": "QuoteLineItem.id",
+        },
+    )
+    children: list["QuoteLineItem"] = Relationship(back_populates="parent")

ab_pydantic_patch-1.2.4/src/ab_core/pydantic_patch/examples/sqlmodel_examples/self_referencing_tree.py

@@ -0,0 +1,172 @@
+"""Self-referencing SQLModel tree patch example."""
+
+import os
+from contextlib import asynccontextmanager
+from typing import Annotated
+
+from fastapi import Depends as FDepends
+from fastapi import FastAPI, HTTPException
+from sqlalchemy.orm import Session
+
+from ab_core.database.databases import Database
+from ab_core.database.session_context import db_session_sync
+from ab_core.dependency import Depends, inject
+from ab_core.pydantic_patch.examples.sqlmodel_examples.models import QuoteLineItem
+from ab_core.pydantic_patch.orm_patch import recursive_patch_orm_scalar
+from ab_core.pydantic_patch.patch import Patch, PatchConfig
+
+os.environ.setdefault("DATABASE_TYPE", "SQL_ALCHEMY")
+os.environ.setdefault("DATABASE_SQL_ALCHEMY_URL", "sqlite:///./self_referencing_tree.db")
+
+ENTITY_ID = 1
+
+
+QuoteLineItem.model_rebuild(force=True)
+
+
+QuoteLineItemPatch = Patch[QuoteLineItem](
+    name="QuoteLineItemPatch",
+    pick={
+        "id",
+        "line_item_name",
+        "quoted_base_cost",
+        "children",
+    },
+    partial={
+        "id",
+        "line_item_name",
+        "quoted_base_cost",
+        "children",
+    },
+    child_models={
+        QuoteLineItem: PatchConfig(
+            pick={
+                "id",
+                "line_item_name",
+                "quoted_base_cost",
+                "children",
+            },
+            partial={
+                "id",
+                "line_item_name",
+                "quoted_base_cost",
+                "children",
+            },
+        ),
+    },
+)
+
+QuoteLineItemResponse = Patch[QuoteLineItem](
+    name="QuoteLineItemResponse",
+    pick={
+        "id",
+        "line_item_name",
+        "quoted_base_cost",
+        "children",
+    },
+    required={
+        "id",
+    },
+    child_models={
+        QuoteLineItem: PatchConfig(
+            pick={
+                "id",
+                "line_item_name",
+                "quoted_base_cost",
+                "children",
+            },
+            required={
+                "id",
+            },
+        ),
+    },
+)
+
+
+def seed(db: Database) -> None:
+    """Create demo records if they do not already exist."""
+    db.sync_upgrade_db()
+
+    with db.sync_session() as session:
+        if session.get(QuoteLineItem, ENTITY_ID):
+            return
+
+        quote_line_item = QuoteLineItem(
+            id=ENTITY_ID,
+            line_item_name="Fence",
+            quoted_base_cost=1200.0,
+            children=[
+                QuoteLineItem(
+                    id=10,
+                    line_item_name="Panels",
+                    quoted_base_cost=700.0,
+                ),
+                QuoteLineItem(
+                    id=11,
+                    line_item_name="Posts and rails",
+                    quoted_base_cost=500.0,
+                ),
+            ],
+        )
+
+        session.add(quote_line_item)
+        session.commit()
+
+
+@asynccontextmanager
+@inject
+async def lifespan(
+    _app: FastAPI,
+    db: Annotated[Database, Depends(Database, persist=True)],
+):
+    """Run startup seed for the example app lifecycle."""
+    seed(db)
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.get("/line-items/{line_item_id}", response_model=QuoteLineItemResponse)
+def get_line_item(
+    line_item_id: int,
+    db_session: Annotated[Session, FDepends(db_session_sync)],
+) -> QuoteLineItem:
+    """Return a line item tree by id."""
+    line_item = db_session.get(QuoteLineItem, line_item_id)
+
+    if line_item is None:
+        raise HTTPException(status_code=404, detail="Line item not found")
+
+    return line_item
+
+
+@app.patch("/line-items/{line_item_id}", response_model=QuoteLineItemResponse)
+def patch_line_item(
+    line_item_id: int,
+    patch: QuoteLineItemPatch,
+    db_session: Annotated[Session, FDepends(db_session_sync)],
+) -> QuoteLineItem:
+    """Patch a self-referencing line item tree."""
+    line_item = db_session.get(QuoteLineItem, line_item_id)
+
+    if line_item is None:
+        raise HTTPException(status_code=404, detail="Line item not found")
+
+    recursive_patch_orm_scalar(line_item, patch)
+
+    db_session.add(line_item)
+    db_session.flush()
+
+    return line_item
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(
+        app,
+        host="0.0.0.0",
+        port=8000,
+        reload=False,
+    )

{ab_pydantic_patch-1.2.2 → ab_pydantic_patch-1.2.4}/src/ab_core/pydantic_patch/orm_patch.py

@@ -27,11 +27,23 @@ def _provided_values(model: BaseModel) -> dict[str, object]:
     return {name: getattr(model, name) for name in model.model_fields_set}
 
 
-def _patch_scalar_value(instance: Any, key: str, value: Any) -> None:
+def _patch_scalar_value(
+    instance: Any,
+    key: str,
+    value: Any,
+    *,
+    copy_nested_basemodel: bool = False,
+) -> None:
     current_value = getattr(instance, key, None)
 
     if isinstance(current_value, BaseModel) and isinstance(value, BaseModel):
-        recursive_patch_scalar(current_value, value)
+        target_value = current_value.model_copy(deep=True) if copy_nested_basemodel else current_value
+
+        recursive_patch_scalar(target_value, value)
+
+        # Important for ORM scalar JSON/Pydantic fields:
+        # reassign the merged current value so SQLAlchemy sees the column changed.
+        setattr(instance, key, target_value)
         return
 
     setattr(instance, key, value)
@@ -94,7 +106,7 @@ def _recursive_patch_pydantic_scalar(
     instance: BaseModel,
     values: BaseModel,
 ) -> None:
-    target_fields = set(instance.model_fields)
+    target_fields = set(type(instance).model_fields)
 
     for key, value in _provided_values(values).items():
         if key not in target_fields:
@@ -129,7 +141,12 @@ def _recursive_patch_orm_scalar(
         if relationship is None:
             if key not in scalar_attributes:
                 continue
-            _patch_scalar_value(orm_instance, key, value)
+            _patch_scalar_value(
+                orm_instance,
+                key,
+                value,
+                copy_nested_basemodel=True,
+            )
             continue
 
         if value is None: