surreal-orm-lite 0.24.0__tar.gz → 0.24.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/CHANGELOG.md +39 -0
  2. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/PKG-INFO +29 -31
  3. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/README.md +28 -30
  4. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/model_base.py +649 -16
  7. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/.gitignore +0 -0
  8. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/LICENSE +0 -0
  9. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/Makefile +0 -0
  10. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/_sdk.py +0 -0
  11. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/aggregations.py +0 -0
  12. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/auth.py +0 -0
  13. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/changefeed.py +0 -0
  14. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/concurrency.py +0 -0
  15. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/connection_manager.py +0 -0
  16. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/constants.py +0 -0
  17. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/edge.py +0 -0
  18. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/encoding.py +0 -0
  19. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/enum.py +0 -0
  20. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/exceptions.py +0 -0
  21. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/functions.py +0 -0
  22. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/geo.py +0 -0
  23. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/live.py +0 -0
  24. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/model_auth.py +0 -0
  25. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/py.typed +0 -0
  26. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/q.py +0 -0
  27. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/query_set.py +0 -0
  28. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/signals.py +0 -0
  29. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/surql_literal.py +0 -0
  30. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/transaction.py +0 -0
  31. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/types.py +0 -0
  32. {surreal_orm_lite-0.24.0 → surreal_orm_lite-0.24.2}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.24.2] - 2026-10-15
9
+
10
+ Sub-models keep their rich values after a write that returns the row, and a `timedelta` below the
11
+ top level reads the server's duration. No new public API.
12
+
13
+ ### Fixed
14
+
15
+ - **A sub-model's durations, ranges and geometries were written back as plain objects** (#228).
16
+ `save()` without an id, `upsert()`, `refresh()`, `merge()`, `patch()` and the `atomic_*` helpers
17
+ applied the returned row without validation, so a sub-model field (a Pydantic model, a dataclass
18
+ or a `TypedDict`, also inside `list[...]`, `dict[..., ...]` or `X | None`) held the row's `dict`
19
+ with the SDK's values. The next full write (`update()`, `upsert()`) stored their fields
20
+ (`{elapsed: 300000000000}`) instead of SurrealDB's durations, ranges and geometries, warned
21
+ `PydanticSerializationUnexpectedValue`, and the next `get()` of the record failed validation.
22
+ These calls now give a sub-model field the value a read gives: its model instance, with the ORM's
23
+ `Duration`, `timedelta`, `Range` and geometry values inside, so writing the instance back is safe.
24
+ - The returned row goes through the model's validation, as in `get()`, so the model's own
25
+ validators (`field_validator`, `model_validator`, `model_post_init`) run on it too.
26
+ - When the row as a whole does not validate, each sub-model field is validated on its own, except
27
+ one that the model's own validators could reshape; that one, like a value that does not
28
+ validate, is applied as received. These calls raise nothing new.
29
+ - A GeoJSON object stored in a top-level geometry field (the full SurrealDB-ORM's format) now
30
+ becomes the ORM geometry after `refresh()`, `merge()` and `patch()`, as after `get()`.
31
+ - **A `timedelta` below the top level failed to read the server's duration.** A sub-model's
32
+ `timedelta` field, `list[timedelta]`, `dict[str, timedelta]` or `timedelta | str` refused the
33
+ SDK's `Duration` on every read, as before v0.23.0. They now read a `timedelta`, floored to the
34
+ microsecond (declare `Duration` to keep the nanoseconds), in a read and in the row a write
35
+ returns. A row holding many such values is converted in one pass, without mutating the data,
36
+ and the model's own validators (any mode) and `model_post_init` still apply once, even when they
37
+ change the data in place.
38
+
39
+ ### Notes
40
+
41
+ - **Identical on SurrealDB 2.x and 3.x**: the cause was in how the ORM applied the SDK's values,
42
+ not in the server. The README's "Rich values inside sub-models" limitation of section 25 is
43
+ removed, and "After a write that returns the row" describes the new behaviour; top-level `date`,
44
+ `set` and `Range` fields still hold the SDK's value until the record is loaded again.
45
+ - Tested against SurrealDB 3.3.4 and 2.7.0 (the CI pins), plus 3.1.5 for backward compatibility.
46
+
8
47
  ## [0.24.0] - 2026-10-15
9
48
 
10
49
  Geospatial fields: a model can declare geometry fields stored as SurrealDB's native geometries and
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.24.0
3
+ Version: 0.24.2
4
4
  Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
5
5
  Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
6
6
  Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
@@ -2057,10 +2057,12 @@ sub.active_hours # Range(begin=BoundIncluded(value=9), end=BoundExcluded(value=
2057
2057
 
2058
2058
  Optional fields (`ttl: timedelta | None = None`) behave the same. Values nested in containers
2059
2059
  (`list[timedelta]`, `dict[str, date]`, a sub-model's fields) are sent the same way at any depth. On
2060
- reads, a `timedelta` is converted from the SDK's duration in a top-level field only: deeper down
2061
- (`list[timedelta]`, a sub-model's `timedelta` field) it fails validation as it did before v0.23.0,
2062
- so declare `Duration` there, which reads the SDK's value at any depth. A naive `datetime` stays
2063
- naive on the instance and is read back as an aware UTC `datetime`, as before.
2060
+ reads, a `timedelta` is converted from the SDK's duration at any depth too: a top-level field,
2061
+ `list[timedelta]`, `dict[str, timedelta]`, `timedelta | str` or a sub-model's `timedelta` field
2062
+ all read a `timedelta`, floored to the microsecond (declare `Duration` to keep the nanoseconds).
2063
+ Your validators (any mode) and `model_post_init` still apply once to the value read, even when they
2064
+ change it in place. A naive `datetime` stays naive on the instance and is read back as an aware UTC
2065
+ `datetime`, as before.
2064
2066
 
2065
2067
  #### `Duration`
2066
2068
 
@@ -2241,15 +2243,21 @@ await sub.merge(trial=sub.trial + timedelta(days=7)) #
2241
2243
  #### After a write that returns the row
2242
2244
 
2243
2245
  `save()` without an id, `refresh()`, `merge()`, `upsert()`, `patch()` and the `atomic_*` helpers
2244
- apply the row the server returns as received, without validation, as before v0.23.0. `timedelta`,
2245
- `Duration` and geometry fields (since v0.24.0, see [section 25](#25-geospatial-fields)) are
2246
- converted on the way, but `date`, `set` and `Range` fields hold the SDK's value (a midnight
2247
- `datetime`, a `list`, the SDK's `Range`) until the record is loaded again (`get()`, `filter()`, …).
2248
- For top-level fields, writing such an instance back is safe, since those values are stored the
2249
- same way, although Pydantic warns (`PydanticSerializationUnexpectedValue`) about the `date` and
2250
- `set` fields while serialising them. A sub-model field holds the row's `dict` instead: durations,
2251
- ranges and geometries inside it would be written back as plain objects, so read the record again
2252
- first (see [Rich values inside sub-models](#rich-values-inside-sub-models)).
2246
+ apply the row the server returns to the instance. Top-level `timedelta`, `Duration` and geometry
2247
+ fields (since v0.24.0, see [section 25](#25-geospatial-fields)) are converted on the way. A field
2248
+ that holds a sub-model (a Pydantic model, a dataclass or a `TypedDict`, also inside `list[...]`,
2249
+ `dict[..., ...]` or `X | None`) or a `timedelta` below the top level (`list[timedelta]`,
2250
+ `timedelta | str`…) gets the value a read gives: the row goes through the model's validation, the
2251
+ model's own validators included, and a sub-model field holds its model instance, not the row's
2252
+ `dict`, with the ORM's durations, `timedelta`s, ranges and geometries inside. When the row as a
2253
+ whole does not validate, each such field is validated on its own, except one that the model's own
2254
+ validators could reshape (a `field_validator` on that field, a `model_validator`, a
2255
+ `model_post_init`): that one, like a value that does not validate, is applied as received, so
2256
+ these calls never fail on it. Other top-level `date`, `set` and `Range` fields hold the SDK's value
2257
+ (a midnight `datetime`, a `list`, the SDK's `Range`) until the record is loaded again (`get()`,
2258
+ `filter()`, …). Writing such an instance back is safe, sub-models included, since those values are
2259
+ stored the same way, although Pydantic warns (`PydanticSerializationUnexpectedValue`) about the
2260
+ top-level `date` and `set` fields while serialising them.
2253
2261
 
2254
2262
  #### Values the SDK cannot read
2255
2263
 
@@ -2273,8 +2281,10 @@ refused value raises `ValueError` before anything is sent.
2273
2281
 
2274
2282
  Plain `datetime`, `Decimal` and `UUID` annotations work as they do there. The full ORM has no
2275
2283
  `timedelta` or `Range` fields and its `Duration` is a string: `timedelta`, `Duration` and
2276
- `Range[T]` fields are lite additions. The full ORM also validates the rows its writes return,
2277
- where lite converts only durations and geometries (see [After a write that returns the row](#after-a-write-that-returns-the-row)).
2284
+ `Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; lite
2285
+ validates the sub-model, geometry and nested `timedelta` fields of those rows and converts
2286
+ top-level durations, while top-level `date`, `set` and `Range` fields keep the SDK's value (see
2287
+ [After a write that returns the row](#after-a-write-that-returns-the-row)).
2278
2288
 
2279
2289
  ### 25. Geospatial fields
2280
2290
 
@@ -2572,19 +2582,9 @@ for restaurant in await Restaurant.objects().all():
2572
2582
  SurrealDB keeps a GeoJSON dict as a plain object, not a geometry: the full SurrealDB-ORM stores its
2573
2583
  geometry fields that way, and so does any client that writes GeoJSON dicts. `nearby()` skips such
2574
2584
  objects, `geo::*` functions and `geometry<…>` columns refuse them, and no SurrealQL cast turns them
2575
- into geometries. A geometry field reads them (a GeoJSON object validates), and `update()` writes
2576
- the instance back with a native geometry, so loading and updating every record migrates a table.
2577
-
2578
- #### Rich values inside sub-models
2579
-
2580
- After a call that applies the row the server returns (`refresh()`, `upsert()`, `merge()`,
2581
- `patch()`, the `atomic_*` helpers, `save()` with an auto-generated id), a sub-model field holds the
2582
- row's `dict`, as for every type (see [After a write that returns the row](#after-a-write-that-returns-the-row)).
2583
- Geometries, durations and ranges inside it are written back as plain objects by a later `update()`
2584
- or `upsert()`, and the next read of that record fails validation: read the record again with
2585
- `get()` before writing it back. Top-level geometry fields and top-level typed containers
2586
- (`list[GeometryPoint]`) are not affected: they are written back as geometries. A fix is tracked in
2587
- [#228](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/228).
2585
+ into geometries. A geometry field reads them (a GeoJSON object validates, in a read and in the row
2586
+ a write returns), and `update()` writes the instance back with a native geometry, so loading and
2587
+ updating every record migrates a table.
2588
2588
 
2589
2589
  #### Untyped fields
2590
2590
 
@@ -2642,8 +2642,6 @@ writes one: its classes refuse such values, and so does the check of the SDK geo
2642
2642
  `surreal_orm`, `surreal_orm.fields`, `surreal_orm.geo`); `is_geo_field` and `get_geo_info` come
2643
2643
  from `surreal_orm_lite.geo` (the full ORM: `surreal_orm.fields`). There is no
2644
2644
  `surreal_orm_lite.fields` module.
2645
- - **Sub-models after a write that returns the row** keep the row's `dict` (the full ORM validates
2646
- those rows): see [Rich values inside sub-models](#rich-values-inside-sub-models).
2647
2645
 
2648
2646
  ---
2649
2647
 
@@ -2006,10 +2006,12 @@ sub.active_hours # Range(begin=BoundIncluded(value=9), end=BoundExcluded(value=
2006
2006
 
2007
2007
  Optional fields (`ttl: timedelta | None = None`) behave the same. Values nested in containers
2008
2008
  (`list[timedelta]`, `dict[str, date]`, a sub-model's fields) are sent the same way at any depth. On
2009
- reads, a `timedelta` is converted from the SDK's duration in a top-level field only: deeper down
2010
- (`list[timedelta]`, a sub-model's `timedelta` field) it fails validation as it did before v0.23.0,
2011
- so declare `Duration` there, which reads the SDK's value at any depth. A naive `datetime` stays
2012
- naive on the instance and is read back as an aware UTC `datetime`, as before.
2009
+ reads, a `timedelta` is converted from the SDK's duration at any depth too: a top-level field,
2010
+ `list[timedelta]`, `dict[str, timedelta]`, `timedelta | str` or a sub-model's `timedelta` field
2011
+ all read a `timedelta`, floored to the microsecond (declare `Duration` to keep the nanoseconds).
2012
+ Your validators (any mode) and `model_post_init` still apply once to the value read, even when they
2013
+ change it in place. A naive `datetime` stays naive on the instance and is read back as an aware UTC
2014
+ `datetime`, as before.
2013
2015
 
2014
2016
  #### `Duration`
2015
2017
 
@@ -2190,15 +2192,21 @@ await sub.merge(trial=sub.trial + timedelta(days=7)) #
2190
2192
  #### After a write that returns the row
2191
2193
 
2192
2194
  `save()` without an id, `refresh()`, `merge()`, `upsert()`, `patch()` and the `atomic_*` helpers
2193
- apply the row the server returns as received, without validation, as before v0.23.0. `timedelta`,
2194
- `Duration` and geometry fields (since v0.24.0, see [section 25](#25-geospatial-fields)) are
2195
- converted on the way, but `date`, `set` and `Range` fields hold the SDK's value (a midnight
2196
- `datetime`, a `list`, the SDK's `Range`) until the record is loaded again (`get()`, `filter()`, …).
2197
- For top-level fields, writing such an instance back is safe, since those values are stored the
2198
- same way, although Pydantic warns (`PydanticSerializationUnexpectedValue`) about the `date` and
2199
- `set` fields while serialising them. A sub-model field holds the row's `dict` instead: durations,
2200
- ranges and geometries inside it would be written back as plain objects, so read the record again
2201
- first (see [Rich values inside sub-models](#rich-values-inside-sub-models)).
2195
+ apply the row the server returns to the instance. Top-level `timedelta`, `Duration` and geometry
2196
+ fields (since v0.24.0, see [section 25](#25-geospatial-fields)) are converted on the way. A field
2197
+ that holds a sub-model (a Pydantic model, a dataclass or a `TypedDict`, also inside `list[...]`,
2198
+ `dict[..., ...]` or `X | None`) or a `timedelta` below the top level (`list[timedelta]`,
2199
+ `timedelta | str`…) gets the value a read gives: the row goes through the model's validation, the
2200
+ model's own validators included, and a sub-model field holds its model instance, not the row's
2201
+ `dict`, with the ORM's durations, `timedelta`s, ranges and geometries inside. When the row as a
2202
+ whole does not validate, each such field is validated on its own, except one that the model's own
2203
+ validators could reshape (a `field_validator` on that field, a `model_validator`, a
2204
+ `model_post_init`): that one, like a value that does not validate, is applied as received, so
2205
+ these calls never fail on it. Other top-level `date`, `set` and `Range` fields hold the SDK's value
2206
+ (a midnight `datetime`, a `list`, the SDK's `Range`) until the record is loaded again (`get()`,
2207
+ `filter()`, …). Writing such an instance back is safe, sub-models included, since those values are
2208
+ stored the same way, although Pydantic warns (`PydanticSerializationUnexpectedValue`) about the
2209
+ top-level `date` and `set` fields while serialising them.
2202
2210
 
2203
2211
  #### Values the SDK cannot read
2204
2212
 
@@ -2222,8 +2230,10 @@ refused value raises `ValueError` before anything is sent.
2222
2230
 
2223
2231
  Plain `datetime`, `Decimal` and `UUID` annotations work as they do there. The full ORM has no
2224
2232
  `timedelta` or `Range` fields and its `Duration` is a string: `timedelta`, `Duration` and
2225
- `Range[T]` fields are lite additions. The full ORM also validates the rows its writes return,
2226
- where lite converts only durations and geometries (see [After a write that returns the row](#after-a-write-that-returns-the-row)).
2233
+ `Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; lite
2234
+ validates the sub-model, geometry and nested `timedelta` fields of those rows and converts
2235
+ top-level durations, while top-level `date`, `set` and `Range` fields keep the SDK's value (see
2236
+ [After a write that returns the row](#after-a-write-that-returns-the-row)).
2227
2237
 
2228
2238
  ### 25. Geospatial fields
2229
2239
 
@@ -2521,19 +2531,9 @@ for restaurant in await Restaurant.objects().all():
2521
2531
  SurrealDB keeps a GeoJSON dict as a plain object, not a geometry: the full SurrealDB-ORM stores its
2522
2532
  geometry fields that way, and so does any client that writes GeoJSON dicts. `nearby()` skips such
2523
2533
  objects, `geo::*` functions and `geometry<…>` columns refuse them, and no SurrealQL cast turns them
2524
- into geometries. A geometry field reads them (a GeoJSON object validates), and `update()` writes
2525
- the instance back with a native geometry, so loading and updating every record migrates a table.
2526
-
2527
- #### Rich values inside sub-models
2528
-
2529
- After a call that applies the row the server returns (`refresh()`, `upsert()`, `merge()`,
2530
- `patch()`, the `atomic_*` helpers, `save()` with an auto-generated id), a sub-model field holds the
2531
- row's `dict`, as for every type (see [After a write that returns the row](#after-a-write-that-returns-the-row)).
2532
- Geometries, durations and ranges inside it are written back as plain objects by a later `update()`
2533
- or `upsert()`, and the next read of that record fails validation: read the record again with
2534
- `get()` before writing it back. Top-level geometry fields and top-level typed containers
2535
- (`list[GeometryPoint]`) are not affected: they are written back as geometries. A fix is tracked in
2536
- [#228](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/228).
2534
+ into geometries. A geometry field reads them (a GeoJSON object validates, in a read and in the row
2535
+ a write returns), and `update()` writes the instance back with a native geometry, so loading and
2536
+ updating every record migrates a table.
2537
2537
 
2538
2538
  #### Untyped fields
2539
2539
 
@@ -2591,8 +2591,6 @@ writes one: its classes refuse such values, and so does the check of the SDK geo
2591
2591
  `surreal_orm`, `surreal_orm.fields`, `surreal_orm.geo`); `is_geo_field` and `get_geo_info` come
2592
2592
  from `surreal_orm_lite.geo` (the full ORM: `surreal_orm.fields`). There is no
2593
2593
  `surreal_orm_lite.fields` module.
2594
- - **Sub-models after a write that returns the row** keep the row's `dict` (the full ORM validates
2595
- those rows): see [Rich values inside sub-models](#rich-values-inside-sub-models).
2596
2594
 
2597
2595
  ---
2598
2596
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.24.0"
3
+ version = "0.24.2"
4
4
  description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -1,4 +1,4 @@
1
- __version__ = "0.24.0"
1
+ __version__ = "0.24.2"
2
2
 
3
3
  from ._sdk import BoundExcluded, BoundIncluded
4
4
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
@@ -1,4 +1,6 @@
1
1
  import contextlib
2
+ import copy
3
+ import dataclasses
2
4
  import functools
3
5
  import logging
4
6
  import os
@@ -11,7 +13,7 @@ from types import UnionType
11
13
  from typing import TYPE_CHECKING, Any, Self, TypeVar, overload
12
14
 
13
15
  import pydantic
14
- from pydantic import BaseModel, ConfigDict, model_validator
16
+ from pydantic import BaseModel, ConfigDict, ModelWrapValidatorHandler, TypeAdapter, model_validator
15
17
  from pydantic_core import ValidationError
16
18
 
17
19
  from . import encoding as _encoding
@@ -56,6 +58,7 @@ if TYPE_CHECKING:
56
58
  logger = logging.getLogger(__name__)
57
59
 
58
60
  _E = TypeVar("_E", bound="BaseSurrealEdge")
61
+ _V = TypeVar("_V")
59
62
 
60
63
  # Per-class derivations of v0.18.0, computed once on first use. They cannot be built in
61
64
  # ``__init_subclass__``: that runs inside ``type.__new__``, before Pydantic has finished
@@ -65,6 +68,28 @@ _ALIAS_MAPS: dict[type, tuple[dict[str, str], dict[str, str]]] = {}
65
68
  _SERVER_FIELDS: dict[type, frozenset[str]] = {}
66
69
  # The read kinds of v0.23.0 (``BaseSurrealModel._read_kinds``), filled once Pydantic completed the class.
67
70
  _READ_KINDS: dict[type, dict[str, str]] = {}
71
+ # The fields a write sync validates (#228): their annotations (``BaseSurrealModel._sync_fields``) and
72
+ # the adapters built from them on first use, ``None`` for one that cannot be built (``_sync_adapter``).
73
+ _SYNC_FIELDS: dict[type, dict[str, Any]] = {}
74
+ _SYNC_ADAPTERS: dict[type, dict[str, TypeAdapter[Any] | None]] = {}
75
+ # The fields the model's own validators may reshape (``BaseSurrealModel._sync_reshaped``), where a
76
+ # field validated alone would differ from a read (#228).
77
+ _SYNC_RESHAPED: dict[type, frozenset[str]] = {}
78
+ # ``_sync_reshaped()`` of a model whose own validators may reshape every field.
79
+ _ALL_FIELDS: frozenset[str] = frozenset({"*"})
80
+ # The key under which a node of ``_with_sdk_timedeltas``'s trie holds the value that replaces it (#228).
81
+ _LEAF = object()
82
+ # Whether validating a model may run code of the user's on its input (``BaseSurrealModel._runs_input_code``, #228).
83
+ _INPUT_CODE: dict[type, bool] = {}
84
+ # Whether validating a model may refuse the SDK's ``Duration`` where ``set_data`` does not convert it
85
+ # (``BaseSurrealModel._may_refuse_sdk_durations``, #228).
86
+ _MAY_REFUSE_DURATIONS: dict[type, bool] = {}
87
+ # The core schema types of a validator function, which may receive the input itself (``_schema_runs_input_code``).
88
+ _INPUT_FUNCTIONS = frozenset({"function-before", "function-after", "function-wrap", "function-plain"})
89
+
90
+ # ``tuple`` and ``Annotated`` subscripted with annotations known at run time (mypy takes them for types).
91
+ _TUPLE: Any = tuple
92
+ _ANNOTATED: Any = typing.Annotated
68
93
 
69
94
  # Pydantic's metaclass sits between ``__pydantic_init_subclass__`` and the user's ``class``
70
95
  # statement; a warning raised there must skip its frames to land on the user's line (v0.22.0).
@@ -131,6 +156,386 @@ def _read_kind(annotation: Any) -> str | None:
131
156
  return None
132
157
 
133
158
 
159
+ def _annotation_holds(annotation: Any, leaf: Callable[[type], bool], _aliases: frozenset[int] = frozenset()) -> bool:
160
+ """Whether a field annotation holds, at any depth, a class for which ``leaf`` is true.
161
+
162
+ Walks ``Annotated`` (its first argument), unions, the arguments of generic types
163
+ (``list[Sub]``, ``dict[str, Sub]``, ``Sub | None``, ``Range[Sub]``…) and the value of a
164
+ ``type`` alias (each alias once, so a recursive one ends). A string or ``ForwardRef``, the
165
+ values of a ``Literal`` and ``type[...]`` hold none. Used by :func:`_has_structured_type`
166
+ and :func:`_holds_timedelta` (#228).
167
+ """
168
+ origin = typing.get_origin(annotation)
169
+ if origin is typing.Annotated:
170
+ return _annotation_holds(typing.get_args(annotation)[0], leaf, _aliases)
171
+ if origin is typing.Literal or origin is type:
172
+ return False
173
+ if origin is not None:
174
+ return any(_annotation_holds(arg, leaf, _aliases) for arg in typing.get_args(annotation))
175
+ if not isinstance(annotation, type):
176
+ if not hasattr(annotation, "__type_params__") or id(annotation) in _aliases:
177
+ return False
178
+ try:
179
+ value = annotation.__value__ # a ``type`` alias, evaluated lazily
180
+ except Exception:
181
+ return False
182
+ return _annotation_holds(value, leaf, _aliases | {id(annotation)})
183
+ return leaf(annotation)
184
+
185
+
186
+ def _is_structured(cls: type) -> bool:
187
+ """Whether ``cls`` is a ``BaseModel``, a dataclass or a ``TypedDict``.
188
+
189
+ A ``TypedDict`` is recognised by its shape, since ``typing.is_typeddict`` misses
190
+ ``typing_extensions.TypedDict``, the form Pydantic requires before Python 3.12.
191
+ """
192
+ if issubclass(cls, BaseModel) or dataclasses.is_dataclass(cls):
193
+ return True
194
+ return issubclass(cls, dict) and hasattr(cls, "__required_keys__")
195
+
196
+
197
+ def _has_structured_type(annotation: Any) -> bool:
198
+ """Whether a field annotation holds a structured type at any depth: a ``BaseModel``, a dataclass or a ``TypedDict``.
199
+
200
+ See :func:`_annotation_holds` for the walk. Used by :meth:`BaseSurrealModel._sync_fields` (#228).
201
+ """
202
+ return _annotation_holds(annotation, _is_structured)
203
+
204
+
205
+ def _holds_timedelta(annotation: Any) -> bool:
206
+ """Whether a field annotation holds exactly ``timedelta`` at any depth (``list[timedelta]``, ``timedelta | str``…).
207
+
208
+ A ``timedelta`` subclass does not count: Pydantic validates it by instance, so the SDK's
209
+ ``Duration`` is never converted for it (see :func:`_with_sdk_timedeltas`). Used by
210
+ :meth:`BaseSurrealModel._sync_fields` (#228).
211
+ """
212
+ return _annotation_holds(annotation, lambda cls: cls is timedelta)
213
+
214
+
215
+ def _is_input(node: Any, value: Any, copies: Mapping[int, Any] | None) -> bool:
216
+ """Whether ``node``, found in the data, is ``value``, the input of an error, or the SDK ``Duration`` whose copy it is (#228).
217
+
218
+ ``copies`` is the ``memo`` of the deep copy a first run validated instead of the data
219
+ (:func:`_validated_with_sdk_timedeltas`), which maps the ``id`` of each copied object to its copy.
220
+ """
221
+ if node is value:
222
+ return True
223
+ return copies is not None and type(node) is SdkDuration and copies.get(id(node)) is value
224
+
225
+
226
+ def _path_to(
227
+ data: Any, loc: Sequence[int | str], value: Any, copies: Mapping[int, Any] | None = None
228
+ ) -> list[int | str] | None:
229
+ """The keys and indexes that lead from ``data`` to ``value`` along an error's ``loc``, or ``None`` (#228).
230
+
231
+ ``loc`` names ``dict`` keys and ``list`` or ``tuple`` indexes, mixed with the tags Pydantic
232
+ adds for a union member (``"RfSub"``, ``"timedelta"``…), which name nothing in the data: a
233
+ ``str`` that is not a key of the current ``dict``, or that meets a ``list`` or ``tuple``, is
234
+ skipped, and so is the rest of ``loc`` once ``value`` itself is reached. Only plain ``dict``,
235
+ ``list`` and ``tuple`` containers are entered. A path is returned only when it ends on
236
+ ``value`` itself (identity), so a tag that happens to be a key never leads to another value.
237
+ When the error comes from a deep copy of ``data`` (``copies``, see :func:`_is_input`), the
238
+ path must end on the SDK ``Duration`` of ``data`` whose copy ``value`` is.
239
+ """
240
+ path: list[int | str] = []
241
+ node = data
242
+ for part in loc:
243
+ if _is_input(node, value, copies):
244
+ break
245
+ container = type(node)
246
+ key = container is dict and part in node
247
+ index = container in (list, tuple) and type(part) is int and 0 <= part < len(node)
248
+ if key or index:
249
+ node = node[part]
250
+ elif type(part) is str and container in (dict, list, tuple):
251
+ continue
252
+ else:
253
+ return None
254
+ path.append(part)
255
+ return path if _is_input(node, value, copies) else None
256
+
257
+
258
+ def _copy_with(node: Any, items: Mapping[int | str, Any]) -> Any:
259
+ """A copy of the container ``node`` with ``items`` set in it, of the same type: ``dict``, ``list`` or ``tuple`` (#228).
260
+
261
+ The only place :func:`_rebuilt` copies a container, once per container on a converted path;
262
+ ``node`` itself is never mutated, and its other items are kept by identity.
263
+ """
264
+ if type(node) is dict:
265
+ return {**node, **items}
266
+ copied = list(node)
267
+ for index, value in items.items():
268
+ copied[typing.cast(int, index)] = value
269
+ return copied if type(node) is list else tuple(copied)
270
+
271
+
272
+ def _rebuilt(node: Any, trie: Mapping[Any, Any]) -> Any:
273
+ """``node`` with the values the ``trie`` of :func:`_with_sdk_timedeltas` names replaced, in one pass (#228).
274
+
275
+ A ``trie`` node maps a key or index of ``node`` to the ``trie`` of the item found there, or
276
+ holds the new value under ``_LEAF`` when ``node`` itself is replaced. The paths come from
277
+ :func:`_path_to`, so they enter only plain ``dict``, ``list`` and ``tuple`` containers: each
278
+ one on a path is copied once (:func:`_copy_with`), and every item off the paths is kept by
279
+ identity.
280
+ """
281
+ if _LEAF in trie:
282
+ return trie[_LEAF]
283
+ return _copy_with(node, {part: _rebuilt(node[part], child) for part, child in trie.items()})
284
+
285
+
286
+ def _with_sdk_timedeltas(data: Any, error: ValidationError, copies: Mapping[int, Any] | None = None) -> Any:
287
+ """``data`` with the SDK's ``Duration`` values a ``timedelta`` refused converted, or ``None`` when there is none (#228).
288
+
289
+ Pydantic's ``timedelta`` refuses the SDK's ``Duration`` (``time_delta_type``), the value every
290
+ read returns for a SurrealDB ``duration``. For each such error whose input is exactly the SDK's
291
+ class, the input found in ``data`` at the error's ``loc`` (:func:`_path_to`) is replaced by
292
+ ``_timedelta_from_sdk(input)``, floored to the microsecond. The paths are gathered first, then
293
+ ``data`` is rebuilt in one pass (:func:`_rebuilt`): each container on a path is copied once,
294
+ whatever the number of values below it, and ``data`` itself is never mutated. Two errors that
295
+ lead to one position (a union of models with the same field) convert it once. An input that
296
+ rule leaves alone (negative, beyond ``timedelta.max``) and an input the ``loc`` does not lead
297
+ to (a ``mode="before"`` validator rebuilt the data…) are not converted. ``copies``: the error
298
+ comes from a deep copy of ``data`` (see :func:`_path_to`). Never raises.
299
+ """
300
+ try:
301
+ trie: dict[Any, Any] = {}
302
+ for detail in error.errors(include_url=False, include_context=False):
303
+ value = detail.get("input")
304
+ if detail["type"] != "time_delta_type" or type(value) is not SdkDuration:
305
+ continue
306
+ converted = _timedelta_from_sdk(value)
307
+ path = None if converted is value else _path_to(data, detail["loc"], value, copies)
308
+ if path is None:
309
+ continue
310
+ node = trie
311
+ for part in path:
312
+ node = node.setdefault(part, {})
313
+ node.setdefault(_LEAF, converted)
314
+ return _rebuilt(data, trie) if trie else None
315
+ except Exception:
316
+ return None
317
+
318
+
319
+ def _validated_with_sdk_timedeltas(validate: Callable[[Any], _V], data: Any, isolate: bool = False) -> _V:
320
+ """``validate(data)``, run once more with the SDK's durations converted when a ``timedelta`` refused them (#228).
321
+
322
+ A ``timedelta`` below the top level of a model (a sub-model's field, ``list[timedelta]``,
323
+ ``timedelta | str``…) then reads the SDK's ``Duration`` as a top-level one does
324
+ (:meth:`BaseSurrealModel.set_data`), floored to the microsecond. Without such a value
325
+ (:func:`_with_sdk_timedeltas`), the error of ``validate(data)`` is raised; otherwise the second
326
+ run gives the result, so an error then names what is really wrong with the data. ``data``
327
+ itself is never mutated by the conversion.
328
+
329
+ The second run never starts from input the first one may have changed. ``isolate`` says that
330
+ ``validate`` may run code of the user's on its input (:func:`_schema_runs_input_code`), which
331
+ may change ``data`` in place: a ``mode="before"`` validator that reads stored cents as a price,
332
+ or an ``after`` validator or ``model_post_init`` that appends to a list Pydantic passed through
333
+ (``Any``), would then be applied twice. The first run then validates a deep copy of ``data``,
334
+ and the second starts again from ``data``, untouched, converting there only the SDK
335
+ ``Duration`` whose copy the first run refused (:func:`_path_to`), so that code is applied once
336
+ to the result. A value that code moved is not found, and stays refused. Nothing is copied when
337
+ ``data`` holds no SDK ``Duration`` (:func:`_holds_sdk_duration`), since there is nothing to
338
+ convert; when ``data`` cannot be copied, there is no second run, and the error of the first is
339
+ raised, as without the conversion. The accepted residual: on a model with such a ``timedelta``
340
+ and with code of the user's, a first run that succeeds builds the instance from the copy, so
341
+ objects the caller passed are held as copies when the input also holds the SDK's own
342
+ ``Duration`` (reads are unaffected, since the row is the SDK's).
343
+ """
344
+ copies: dict[int, Any] | None = None
345
+ first = data
346
+ if isolate:
347
+ if not _holds_sdk_duration(data):
348
+ return validate(data)
349
+ copies = {}
350
+ try:
351
+ first = copy.deepcopy(data, copies)
352
+ except Exception:
353
+ return validate(data)
354
+ try:
355
+ return validate(first)
356
+ except ValidationError as exc:
357
+ fixed = _with_sdk_timedeltas(data, exc, copies)
358
+ if fixed is None:
359
+ raise
360
+ return validate(fixed)
361
+
362
+
363
+ def _holds_sdk_duration(data: Any) -> bool:
364
+ """Whether ``data`` is the SDK's ``Duration`` or holds one in its plain ``dict``, ``list`` and ``tuple`` containers (#228).
365
+
366
+ At any depth: the places :func:`_with_sdk_timedeltas` can convert one (:func:`_path_to`). The
367
+ walk does not recurse and enters each container once, so a deep or self-referencing value
368
+ cannot exhaust it.
369
+ """
370
+ stack: list[Any] = [data]
371
+ seen: set[int] = set()
372
+ while stack:
373
+ node = stack.pop()
374
+ kind = type(node)
375
+ if kind is SdkDuration:
376
+ return True
377
+ if (kind is dict or kind is list or kind is tuple) and id(node) not in seen:
378
+ seen.add(id(node))
379
+ stack.extend(node.values() if kind is dict else node)
380
+ return False
381
+
382
+
383
+ def _schema_runs_input_code(schema: Any) -> bool:
384
+ """Whether a Pydantic core schema may run code of the user's on its input, at any depth (#228).
385
+
386
+ Every hook that runs code of the user's during validation counts, because a value Pydantic
387
+ passes through (``Any``, ``object``, an arbitrary class) is the input object itself, so even
388
+ code that runs after its field validated receives it. That is a validator function of any mode
389
+ (``before``, ``after``, ``wrap``, ``plain``: a model or field validator, a ``BeforeValidator``
390
+ or ``AfterValidator`` in ``Annotated``, a custom type's validator…), a model with its own
391
+ ``__init__`` or ``model_post_init``, a dataclass with a ``__post_init__``, a callable
392
+ ``Discriminator`` and a ``default_factory`` that takes the validated data (see
393
+ :func:`_node_runs_input_code`). Such code may change a ``dict`` or ``list`` of the input in
394
+ place, which a second validation of that input would apply twice (see
395
+ :func:`_validated_with_sdk_timedeltas`). Every node of the schema is walked, nested models and
396
+ definitions included, except serializers (a ``serialization`` schema), which never see the
397
+ input. The ORM's and Pydantic's own functions do not count (:func:`_is_library_callable`):
398
+ Pydantic's ``model_post_init`` of a model with private attributes, for one. Anything
399
+ unexpected, a schema that is not a ``dict`` included, gives ``True``, the safe answer. Never
400
+ raises.
401
+ """
402
+ if not isinstance(schema, dict):
403
+ return True
404
+ try:
405
+ stack: list[Any] = [schema]
406
+ seen: set[int] = set()
407
+ while stack:
408
+ node = stack.pop()
409
+ if not isinstance(node, dict | list | tuple) or id(node) in seen:
410
+ continue
411
+ seen.add(id(node))
412
+ if not isinstance(node, dict):
413
+ stack.extend(node)
414
+ continue
415
+ if _node_runs_input_code(node):
416
+ return True
417
+ stack.extend(value for key, value in node.items() if key != "serialization")
418
+ return False
419
+ except Exception:
420
+ return True
421
+
422
+
423
+ def _node_runs_input_code(node: dict[str, Any]) -> bool:
424
+ """Whether one node of a core schema runs code of the user's during validation (see :func:`_schema_runs_input_code`).
425
+
426
+ A validator function (``function-before``, ``-after``, ``-wrap`` or ``-plain``) that is not
427
+ library code; a ``model`` with its own ``__init__`` (``custom_init``) or whose ``post_init``
428
+ hook is not library code; a ``dataclass`` whose ``__post_init__`` is not library code; a
429
+ ``tagged-union`` whose discriminator is a callable that is not library code; a ``default`` whose
430
+ ``default_factory`` takes the validated data and is not library code. May raise on an
431
+ unexpected node, which the caller counts as ``True``.
432
+ """
433
+ kind = node.get("type")
434
+ if kind in _INPUT_FUNCTIONS:
435
+ function = node.get("function")
436
+ return not isinstance(function, dict) or not _is_library_callable(function.get("function"))
437
+ if kind == "model":
438
+ post_init = node.get("post_init")
439
+ return bool(node.get("custom_init")) or (
440
+ post_init is not None and not _is_library_callable(getattr(node["cls"], post_init))
441
+ )
442
+ if kind == "dataclass":
443
+ return bool(node.get("post_init")) and not _is_library_callable(node["cls"].__post_init__)
444
+ if kind == "tagged-union":
445
+ discriminator = node.get("discriminator")
446
+ return callable(discriminator) and not _is_library_callable(discriminator)
447
+ if kind == "default":
448
+ return bool(node.get("default_factory_takes_data")) and not _is_library_callable(node.get("default_factory"))
449
+ return False
450
+
451
+
452
+ def _schema_refuses_sdk_durations(schema: Any, cls: type, top_level: Collection[str]) -> bool:
453
+ """Whether validating ``cls`` may refuse the SDK's ``Duration`` where ``set_data`` does not convert it (#228).
454
+
455
+ ``schema`` is the core schema of ``cls`` and ``top_level`` the names of its fields that
456
+ :meth:`BaseSurrealModel.set_data` converts (read kind ``timedelta``). Pydantic refuses the SDK's
457
+ ``Duration`` at a ``timedelta`` node, so the answer is whether the schema holds one anywhere
458
+ except as the direct schema of such a field of ``cls`` (in its own ``model-fields``), reached
459
+ from the field only through ``default`` and ``nullable`` wrappers: ``ttl: timedelta | None`` does
460
+ not count, ``timedelta | str``, ``list[timedelta]``, ``Annotated[timedelta, AfterValidator(…)]``
461
+ and a ``timedelta`` in a sub-model, a dataclass or a ``TypedDict`` do. The ORM's ``Duration``
462
+ and ``Range`` hold no ``timedelta`` node. Every node is walked, nested models and definitions
463
+ included, except serializers (a ``serialization`` schema), which never validate. Anything
464
+ unexpected, a schema that is not a ``dict`` included, gives ``True``, the safe answer. Never
465
+ raises.
466
+ """
467
+ if not isinstance(schema, dict):
468
+ return True
469
+ try:
470
+ allowed: set[int] = set()
471
+ stack: list[Any] = [schema]
472
+ seen: set[int] = set()
473
+ while stack:
474
+ node = stack.pop()
475
+ if not isinstance(node, dict | list | tuple):
476
+ continue
477
+ if isinstance(node, dict) and node.get("type") == "timedelta":
478
+ if id(node) not in allowed:
479
+ return True
480
+ allowed.discard(id(node)) # one field holds it: met again elsewhere, it counts
481
+ continue
482
+ if id(node) in seen:
483
+ continue
484
+ seen.add(id(node))
485
+ if not isinstance(node, dict):
486
+ stack.extend(node)
487
+ continue
488
+ if node.get("type") == "model" and node.get("cls") is cls:
489
+ allowed |= _top_level_timedelta_nodes(node, top_level)
490
+ stack.extend(value for key, value in node.items() if key != "serialization")
491
+ return False
492
+ except Exception:
493
+ return True
494
+
495
+
496
+ def _top_level_timedelta_nodes(model: Mapping[str, Any], top_level: Collection[str]) -> set[int]:
497
+ """The ``id`` of each ``timedelta`` node that is the direct schema of a field in ``top_level`` (#228).
498
+
499
+ ``model`` is the ``model`` node of the class. Its ``model-fields`` sit below the class's own
500
+ ``mode="before"`` validators (``set_data`` among them) and v1 root validators; each field's
501
+ schema is followed through ``default`` and ``nullable`` wrappers only. A field whose schema
502
+ leads anywhere else gives nothing, so its ``timedelta`` node counts
503
+ (:func:`_schema_refuses_sdk_durations`). May raise on an unexpected node, which the caller
504
+ counts as ``True``.
505
+ """
506
+ fields = model["schema"]
507
+ while fields.get("type") in ("function-before", "function-after"):
508
+ fields = fields["schema"]
509
+ if fields.get("type") != "model-fields":
510
+ return set()
511
+ found: set[int] = set()
512
+ for name, field in fields["fields"].items():
513
+ if name not in top_level:
514
+ continue
515
+ node = field["schema"]
516
+ while node.get("type") in ("default", "nullable"):
517
+ node = node["schema"]
518
+ if node.get("type") == "timedelta":
519
+ found.add(id(node))
520
+ return found
521
+
522
+
523
+ def _is_library_callable(func: Any) -> bool:
524
+ """Whether a validator or ``model_post_init`` comes from the ORM, the SDK or Pydantic rather than the user's code.
525
+
526
+ The SDK's own validator is its ``RecordID``'s. Read from the module of the function (a
527
+ ``classmethod`` validator is bound: its ``__func__``;
528
+ a ``functools.partial``: the function it wraps). Pydantic's wrapper of a user
529
+ ``model_post_init`` copies the user's module (``functools.wraps``), so it counts as the user's.
530
+ A callable without a module counts as the user's too. Used by
531
+ :meth:`BaseSurrealModel._sync_reshaped` and :func:`_schema_runs_input_code` (#228).
532
+ """
533
+ while isinstance(func, functools.partial):
534
+ func = func.func
535
+ module = getattr(getattr(func, "__func__", func), "__module__", None)
536
+ return isinstance(module, str) and module.partition(".")[0] in ("surreal_orm_lite", "surrealdb", "pydantic")
537
+
538
+
134
539
  def _own_annotation_names(cls: type) -> set[str]:
135
540
  """Return the names annotated in **this** class's body, ignoring inherited ones.
136
541
 
@@ -426,6 +831,185 @@ class BaseSurrealModel(BaseModel):
426
831
  _READ_KINDS[cls] = kinds
427
832
  return kinds
428
833
 
834
+ @classmethod
835
+ def _sync_fields(cls) -> dict[str, Any]:
836
+ """Return the fields a write sync validates, by Python name, cached per class (#228).
837
+
838
+ ``{"sub": Sub | None, "location": Annotated[GeometryPoint | None, GeoField['point']]}``: every
839
+ field whose annotation holds a structured type at any depth (a ``BaseModel``, a dataclass or a
840
+ ``TypedDict``, alone or in ``list[...]``, ``dict[..., ...]``, ``X | None``…, see
841
+ ``_has_structured_type``), every geometry field (``_read_kind``) and every field holding a
842
+ ``timedelta`` below the top level (``list[timedelta]``, ``timedelta | str``…, see
843
+ ``_holds_timedelta``; a top-level one has its own rule). Each maps to its full
844
+ annotation, ``Annotated`` constraints included (``FieldInfo.rebuild_annotation()``), plus the
845
+ field's discriminator. :meth:`_apply_record` receives rows keyed by column but translates each
846
+ key to its Python name first, so the map needs no column keys. Cached once Pydantic has
847
+ completed the class, like :meth:`_read_kinds`; never mutate the returned dict.
848
+ """
849
+ cached = _SYNC_FIELDS.get(cls)
850
+ if cached is not None:
851
+ return cached
852
+ fields: dict[str, Any] = {}
853
+ for name, info in cls.model_fields.items():
854
+ kind = _read_kind(info.annotation)
855
+ nested_timedelta = kind is None and _holds_timedelta(info.annotation)
856
+ if kind != "geometry" and not nested_timedelta and not _has_structured_type(info.annotation):
857
+ continue
858
+ annotation = info.rebuild_annotation()
859
+ if info.discriminator is not None:
860
+ annotation = _ANNOTATED[annotation, pydantic.Field(discriminator=info.discriminator)]
861
+ fields[name] = annotation
862
+ if cls.__pydantic_complete__:
863
+ _SYNC_FIELDS[cls] = fields
864
+ return fields
865
+
866
+ @classmethod
867
+ def _sync_adapter(cls, name: str) -> TypeAdapter[Any] | None:
868
+ """Return the adapter that validates field ``name`` on a write sync, built on first use and cached per class (#228).
869
+
870
+ ``TypeAdapter(tuple[<annotation>], config=<the model's config>)``: the 1-tuple puts the
871
+ annotation where a field's annotation sits in the model, so a stdlib dataclass or a
872
+ ``TypedDict`` inherits the model's config as it does in a read, and the config is accepted
873
+ whatever the annotation (Pydantic refuses one for a bare ``BaseModel``). ``None`` when the
874
+ field is not in :meth:`_sync_fields` or the adapter cannot be built; an annotation that
875
+ cannot be resolved may also give an adapter that fails on use, which
876
+ :meth:`_validated_on_sync` treats like a value that does not validate. Never raises.
877
+ """
878
+ adapters = _SYNC_ADAPTERS.get(cls)
879
+ if adapters is None:
880
+ adapters = {}
881
+ if cls.__pydantic_complete__:
882
+ _SYNC_ADAPTERS[cls] = adapters
883
+ if name in adapters:
884
+ return adapters[name]
885
+ annotation = cls._sync_fields().get(name)
886
+ adapter: TypeAdapter[Any] | None = None
887
+ if annotation is not None:
888
+ try:
889
+ adapter = TypeAdapter(_TUPLE[annotation], config=typing.cast(ConfigDict, cls.model_config))
890
+ except Exception:
891
+ adapter = None
892
+ adapters[name] = adapter
893
+ return adapter
894
+
895
+ @classmethod
896
+ def _sync_reshaped(cls) -> frozenset[str]:
897
+ """Return the fields the model's own validators may reshape, cached per class (#228).
898
+
899
+ A field validated alone (:meth:`_validated_on_sync`) misses the validators and hooks of the
900
+ model that holds it, which a read runs: a ``field_validator`` (or a v1 ``validator``) aimed
901
+ at the field, and a ``model_validator`` (any mode), a v1 ``root_validator`` or a
902
+ ``model_post_init``, which may reshape any field. The result names the fields of the first
903
+ kind, or is ``_ALL_FIELDS`` when one of the second kind, or a ``field_validator("*")``,
904
+ exists. The ORM's and Pydantic's own (``set_data``, ``check_config``, the ``in_``/``out``
905
+ validators of an edge…) do not count (``_is_library_callable``). Read from
906
+ ``__pydantic_decorators__``; anything unexpected there gives ``_ALL_FIELDS``, the safe
907
+ answer. Cached once Pydantic has completed the class, like :meth:`_sync_fields`.
908
+ """
909
+ cached = _SYNC_RESHAPED.get(cls)
910
+ if cached is not None:
911
+ return cached
912
+ reshaped = _ALL_FIELDS
913
+ try:
914
+ decorators = cls.__pydantic_decorators__
915
+ whole: list[Any] = [*decorators.model_validators.values(), *decorators.root_validators.values()]
916
+ per_field: list[Any] = [*decorators.field_validators.values(), *decorators.validators.values()]
917
+ if all(_is_library_callable(d.func) for d in whole) and _is_library_callable(cls.model_post_init):
918
+ names = {field for d in per_field if not _is_library_callable(d.func) for field in d.info.fields}
919
+ reshaped = _ALL_FIELDS if "*" in names else frozenset(names)
920
+ except Exception:
921
+ reshaped = _ALL_FIELDS
922
+ if cls.__pydantic_complete__:
923
+ _SYNC_RESHAPED[cls] = reshaped
924
+ return reshaped
925
+
926
+ @classmethod
927
+ def _runs_input_code(cls) -> bool:
928
+ """Whether validating this model may run code of the user's on its input, cached per class (#228).
929
+
930
+ :func:`_schema_runs_input_code` of the model's core schema, which holds the validators and
931
+ hooks of its sub-models and of its fields' types too. Every hook that runs code of the user's
932
+ counts, whatever its mode: a pass-through field (``Any``…) hands the input object itself to
933
+ an ``after`` validator or a ``model_post_init``. Such code may change the input in place, so
934
+ the conversion of the SDK's durations below the top level validates a copy first
935
+ (:meth:`_read_nested_timedeltas`). ``True`` while Pydantic has not completed the class (its
936
+ schema is not built yet), and cached only once it has, like :meth:`_sync_fields`.
937
+ """
938
+ cached = _INPUT_CODE.get(cls)
939
+ if cached is not None:
940
+ return cached
941
+ if not cls.__pydantic_complete__:
942
+ return True
943
+ runs = _schema_runs_input_code(cls.__pydantic_core_schema__)
944
+ _INPUT_CODE[cls] = runs
945
+ return runs
946
+
947
+ @classmethod
948
+ def _may_refuse_sdk_durations(cls) -> bool:
949
+ """Whether validating this model may refuse an SDK ``Duration`` that :meth:`set_data` does not convert, cached per class (#228).
950
+
951
+ :func:`_schema_refuses_sdk_durations` of the model's core schema: ``True`` when it holds a
952
+ ``timedelta`` anywhere but as a top-level field ``set_data`` converts, for instance in a
953
+ sub-model, a dataclass, a ``TypedDict``, ``list[timedelta]`` or ``timedelta | str``. Only
954
+ such a model takes the retry of :meth:`_read_nested_timedeltas`; every other one validates
955
+ as before #228, without a copy. ``True`` while Pydantic has not completed the class, and
956
+ cached only once it has, like :meth:`_runs_input_code`.
957
+ """
958
+ cached = _MAY_REFUSE_DURATIONS.get(cls)
959
+ if cached is not None:
960
+ return cached
961
+ if not cls.__pydantic_complete__:
962
+ return True
963
+ kinds = cls._read_kinds()
964
+ top_level = frozenset(name for name in cls.model_fields if kinds.get(name) == "timedelta")
965
+ refuses = _schema_refuses_sdk_durations(cls.__pydantic_core_schema__, cls, top_level)
966
+ _MAY_REFUSE_DURATIONS[cls] = refuses
967
+ return refuses
968
+
969
+ @classmethod
970
+ def _validated_row(cls, record: Mapping[str, Any]) -> Self | None:
971
+ """Return the row validated as a read validates it, or ``None`` when it does not validate (#228).
972
+
973
+ ``model_validate`` of the row, as :meth:`from_db` does: the model's own validators run,
974
+ ``set_data`` and ``model_post_init`` included. It validates a deep copy, since ``set_data``
975
+ rewrites the ``id`` in place and a ``mode="before"`` validator may rewrite nested dicts in
976
+ place: the row stays as received. Any exception (a value that does not validate, a
977
+ validator that raises anything else, a model Pydantic cannot complete) gives ``None``.
978
+ """
979
+ try:
980
+ return cls.model_validate(copy.deepcopy(dict(record)))
981
+ except Exception:
982
+ return None
983
+
984
+ @classmethod
985
+ def _validated_on_sync(cls, name: str, value: Any) -> Any:
986
+ """Return ``value`` validated against field ``name`` alone, else ``value`` itself (#228).
987
+
988
+ The fallback of :meth:`_apply_record` when the whole row does not validate
989
+ (:meth:`_validated_row`). A sub-model's ``dict`` becomes the declared instance, with the
990
+ ORM's durations, ranges and geometries; a stored GeoJSON object in a geometry field becomes
991
+ the ORM's geometry; a ``timedelta`` below the top level reads the SDK's ``Duration``, as in
992
+ a read (``_validated_with_sdk_timedeltas``). That is what a read gives unless the model's
993
+ own validators reshape the field, which a field validated alone cannot run: a field in
994
+ :meth:`_sync_reshaped` gives ``value`` back unchanged. So do a value that does not
995
+ validate, a validator that raises anything else and a field without an adapter (see
996
+ :meth:`_sync_adapter`): never raises. When the model may run code of the user's on its
997
+ input (:meth:`_runs_input_code`), a deep copy of ``value`` is validated, so ``value`` is
998
+ given back as received, never as that code changed it in place.
999
+ """
1000
+ reshaped = cls._sync_reshaped()
1001
+ if reshaped is _ALL_FIELDS or name in reshaped:
1002
+ return value
1003
+ adapter = cls._sync_adapter(name)
1004
+ if adapter is None:
1005
+ return value
1006
+ isolate = cls._runs_input_code()
1007
+ try:
1008
+ received = (copy.deepcopy(value),) if isolate else (value,)
1009
+ return _validated_with_sdk_timedeltas(adapter.validate_python, received, isolate)[0]
1010
+ except Exception:
1011
+ return value
1012
+
429
1013
  @classmethod
430
1014
  def _reject_ambiguous_aliases(cls, forward: Mapping[str, str]) -> None:
431
1015
  """Raise if the alias map is not a bijection between field names and columns.
@@ -653,7 +1237,8 @@ class BaseSurrealModel(BaseModel):
653
1237
  SurrealDB ``duration``) gets a ``timedelta``, floored to the microsecond (v0.23.0). The dict is
654
1238
  copied on that first change, never mutated by it; a value this rule cannot convert (beyond
655
1239
  ``timedelta.max``, a subclass, any other type) is left as received for Pydantic to judge,
656
- so the rule itself never raises.
1240
+ so the rule itself never raises. A ``timedelta`` below the top level reads the SDK's
1241
+ ``Duration`` through :meth:`_read_nested_timedeltas` (#228).
657
1242
  """
658
1243
  if isinstance(data, dict) and "id" in data and isinstance(data["id"], RecordID):
659
1244
  # Only convert to plain string when the id field does not accept RecordID.
@@ -683,6 +1268,32 @@ class BaseSurrealModel(BaseModel):
683
1268
  data[key] = converted
684
1269
  return data
685
1270
 
1271
+ @model_validator(mode="wrap")
1272
+ @classmethod
1273
+ def _read_nested_timedeltas(cls, data: Any, handler: ModelWrapValidatorHandler[Self]) -> Self:
1274
+ """Read the SDK's ``Duration`` in a ``timedelta`` below the top level, as :meth:`set_data` does at the top (#228).
1275
+
1276
+ A sub-model's ``timedelta`` field, ``list[timedelta]``, ``dict[str, timedelta]``,
1277
+ ``timedelta | str``…: Pydantic refuses the SDK's ``Duration`` there, which every read
1278
+ returns for a SurrealDB ``duration``. When the validation fails on such values, it runs
1279
+ once more with each of them converted where Pydantic refused it, floored to the
1280
+ microsecond (see ``_validated_with_sdk_timedeltas``), on a copy: the conversion never
1281
+ mutates the caller's data. A value the top-level rule would leave alone stays refused, and
1282
+ a model without such a value fails as before. A ``wrap`` validator runs outside every
1283
+ ``mode="before"`` one, the model's own included, so they run again on the second try, as do
1284
+ the hooks inside the model: its sub-models' validators of any mode, ``model_post_init``,
1285
+ ``__post_init__``… When the model may run code of the user's on its input
1286
+ (:meth:`_runs_input_code`; every hook counts, since a pass-through field such as ``Any``
1287
+ hands the input object itself to ``after`` code), the first try validates a deep copy of
1288
+ the data and the second starts again from the data as received, so code that changes its
1289
+ input in place is applied once to the result. A model whose validation cannot refuse such a
1290
+ value (:meth:`_may_refuse_sdk_durations`: no ``timedelta`` but top-level ones ``set_data``
1291
+ converts) validates as before #228: ``handler(data)``, nothing checked, copied or retried.
1292
+ """
1293
+ if not cls._may_refuse_sdk_durations():
1294
+ return handler(data)
1295
+ return _validated_with_sdk_timedeltas(handler, data, cls._runs_input_code())
1296
+
686
1297
  async def refresh(self, tx: Transaction | None = None) -> None:
687
1298
  """Refresh the model instance from the database.
688
1299
 
@@ -995,9 +1606,10 @@ class BaseSurrealModel(BaseModel):
995
1606
  raise
996
1607
  # Pull back the fields the SERVER owns — computed fields (DEFINE FIELD … VALUE) and
997
1608
  # `server_fields` entries — so they are readable straight after save().
998
- # Deliberately narrow: applying the whole row here would bypass Pydantic validation
999
- # for every field (see _apply_record), turning nested models into plain dicts. A
1000
- # model that declares neither is untouched, exactly as before v0.14.0.
1609
+ # Deliberately narrow: the instance already holds the values it just wrote, while the
1610
+ # whole row would leave top-level `date`, `set` and `Range` fields with the SDK's
1611
+ # values (see _apply_record). A model that declares neither is untouched, exactly as
1612
+ # before v0.14.0.
1001
1613
  self._apply_record(record, only=self.get_server_fields())
1002
1614
  return self, True
1003
1615
 
@@ -1163,10 +1775,10 @@ class BaseSurrealModel(BaseModel):
1163
1775
  ``None``/empty result is a no-op — callers that must distinguish "no row" from "nothing
1164
1776
  to apply" check first.
1165
1777
 
1166
- Values are written with ``object.__setattr__``, i.e. **without** Pydantic validation, so
1167
- a nested model arrives as the raw ``dict`` the server sent. That is why ``only`` exists:
1168
- a caller that needs just a few known-scalar fields should say so rather than re-applying
1169
- the whole row.
1778
+ Values are written with ``object.__setattr__``, i.e. without validating the instance
1779
+ itself: a frozen field is still updated, and only the fields described below go through
1780
+ validation. That is why ``only`` exists: a caller that needs just a few known fields
1781
+ should say so rather than re-applying the whole row.
1170
1782
 
1171
1783
  A row arrives keyed by **column**, so each key is translated back to its Python field
1172
1784
  name first (v0.18.0). ``only`` is therefore matched on Python names — the same
@@ -1174,10 +1786,21 @@ class BaseSurrealModel(BaseModel):
1174
1786
 
1175
1787
  Top-level ``timedelta`` and ``Duration`` fields get the SDK's ``Duration`` converted
1176
1788
  (v0.23.0), and top-level geometry fields the SDK's geometries, as the ORM's geometry
1177
- classes (v0.24.0; a value the constructors refuse is kept as received). Every other value
1178
- is applied as received: a typed container such as ``list[GeometryPoint]`` keeps the SDK's
1179
- values, which its serializer converts at the next ``model_dump()``, and a sub-model keeps
1180
- the row's dict.
1789
+ classes (v0.24.0). A field that holds a sub-model (a ``BaseModel``, a dataclass or a
1790
+ ``TypedDict``, at any depth of its annotation), a field that holds a ``timedelta`` below
1791
+ the top level (``list[timedelta]``, ``timedelta | str``…) and a geometry field holding
1792
+ anything other than an SDK geometry (a stored GeoJSON object…) get the value a read gives
1793
+ (#228, see :meth:`_sync_fields`): when the row holds such a field, the whole row is
1794
+ validated as :meth:`from_db` validates it, the model's own validators included
1795
+ (:meth:`_validated_row`), and those fields take their validated value. A sub-model field
1796
+ then holds its declared instance, with the ORM's durations, ``timedelta``s, ranges and
1797
+ geometries (:meth:`_read_nested_timedeltas`). When the row does not validate, each such
1798
+ field is validated alone (:meth:`_validated_on_sync`), unless the model's own validators
1799
+ may reshape it, and a value that still does not validate is applied as received, so this
1800
+ never raises. Every other value is applied as received: a typed container of other
1801
+ scalars such as ``list[Duration]`` or ``list[GeometryPoint]`` keeps the SDK's values,
1802
+ which its serializer converts at the next ``model_dump()``, and top-level ``date``,
1803
+ ``set`` and ``Range`` fields hold the SDK's value.
1181
1804
 
1182
1805
  Args:
1183
1806
  only: restrict the copy to these field names. ``None`` (default) applies every field
@@ -1189,9 +1812,12 @@ class BaseSurrealModel(BaseModel):
1189
1812
  return
1190
1813
  allowed = None if only is None else set(only)
1191
1814
  kinds = self._read_kinds()
1815
+ validated = self._sync_fields()
1816
+ values: dict[str, Any] = {}
1817
+ pending: list[str] = []
1192
1818
  for column, value in record.items():
1193
1819
  key = self.to_py_field(column)
1194
- if allowed is not None and key not in allowed:
1820
+ if (allowed is not None and key not in allowed) or not hasattr(self, key):
1195
1821
  continue
1196
1822
  kind = kinds.get(key)
1197
1823
  if kind == "timedelta":
@@ -1200,8 +1826,15 @@ class BaseSurrealModel(BaseModel):
1200
1826
  value = _duration_from_sdk(value)
1201
1827
  elif kind == "geometry":
1202
1828
  value = _geo._geometry_from_sdk(value)
1203
- if hasattr(self, key):
1204
- object.__setattr__(self, key, value)
1829
+ if key in validated and not (kind == "geometry" and (value is None or isinstance(value, _geo.Geometry))):
1830
+ pending.append(key)
1831
+ values[key] = value
1832
+ if pending:
1833
+ row = self._validated_row(record)
1834
+ for key in pending:
1835
+ values[key] = getattr(row, key) if row is not None else self._validated_on_sync(key, values[key])
1836
+ for key, value in values.items():
1837
+ object.__setattr__(self, key, value)
1205
1838
 
1206
1839
  def _sync_after_merge(
1207
1840
  self,