surreal-orm-lite 0.24.1__tar.gz → 0.24.3__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 (33) hide show
  1. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/CHANGELOG.md +95 -0
  2. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/PKG-INFO +100 -63
  3. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/README.md +99 -62
  4. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/_sdk.py +25 -1
  7. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/connection_manager.py +9 -0
  8. surreal_orm_lite-0.24.3/src/surreal_orm_lite/decoding.py +338 -0
  9. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/encoding.py +19 -27
  10. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/geo.py +4 -0
  11. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/model_base.py +649 -16
  12. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/surql_literal.py +11 -7
  13. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/.gitignore +0 -0
  14. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/LICENSE +0 -0
  15. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/Makefile +0 -0
  16. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/aggregations.py +0 -0
  17. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/auth.py +0 -0
  18. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/changefeed.py +0 -0
  19. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/concurrency.py +0 -0
  20. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/constants.py +0 -0
  21. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/edge.py +0 -0
  22. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/enum.py +0 -0
  23. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/exceptions.py +0 -0
  24. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/functions.py +0 -0
  25. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/live.py +0 -0
  26. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/model_auth.py +0 -0
  27. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/py.typed +0 -0
  28. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/q.py +0 -0
  29. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/query_set.py +0 -0
  30. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/signals.py +0 -0
  31. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/transaction.py +0 -0
  32. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/types.py +0 -0
  33. {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,101 @@ 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.3] - 2026-10-15
9
+
10
+ The clients the ORM opens now read the values the surrealdb SDK 2.0.0 cannot decode (zero
11
+ durations, SurrealDB 3.x native sets, degenerate geometries), and a zero duration can be stored.
12
+ No new public API.
13
+
14
+ ### Fixed
15
+
16
+ - **Some values SurrealDB returns could not be read** (#235). The surrealdb SDK 2.0.0 cannot
17
+ decode a zero duration, a SurrealDB 3.x native set (a `TYPE set<…>` column on SurrealDB 3.3) or
18
+ a degenerate geometry another client wrote (a line of fewer than 2 points, alone or inside
19
+ another geometry, or a polygon ring of fewer than 4 points): one such value failed the whole
20
+ response it was in. The clients the ORM opens (`SurrealDBConnectionManager.get_client()`,
21
+ `ephemeral_client()`) now read them, over WebSocket, HTTP and embedded connections, and later
22
+ calls on the same client keep working:
23
+ - a zero duration reads as zero: `timedelta(0)` or `Duration(0)` in a typed field, the SDK's
24
+ `Duration(0)` in an untyped one;
25
+ - a native set reads as a Python `set`, which `set[X]` and `frozenset[X]` fields validate, or as
26
+ a `list` when its items are unhashable (record ids, objects, nested sets) or two of them are
27
+ equal in Python, like `1` and `true`: every item the server holds comes back;
28
+ - a degenerate geometry reads as its GeoJSON dict, such as
29
+ `{"type": "LineString", "coordinates": [[1.0, 2.0]]}`, in an untyped field, `raw_query()` and
30
+ live notifications; a geometry field refuses it with a `ValidationError` naming the field.
31
+
32
+ Every other value reads exactly as the SDK reads it, and a malformed value still raises the
33
+ SDK's error. The values go through a hook around the SDK's own CBOR decoder, installed only on
34
+ the ORM's clients and only while the installed SDK cannot decode them: the SDK's modules are not
35
+ modified, and an `AsyncSurreal` client the application builds itself keeps the SDK's behaviour.
36
+ Written back through the ORM (`merge()`, or `update()`, which rewrites the whole row), a native
37
+ set is stored as an array, unless its column is `TYPE set<…>`, and a degenerate geometry's dict
38
+ as a plain object, on both lines.
39
+
40
+ - **A zero duration was refused** since v0.23.0 (`ValueError` for a field, a filter value or a
41
+ bound parameter, `TypeError` from `live()`), because the SDK could not read it back. The ORM's
42
+ clients now read it, so `timedelta(0)` and `Duration(0)` are written, filtered and read back like
43
+ any other duration, on both lines; filter "longer than zero" with `__gt=Duration(0)`. The refusal
44
+ remains only for an SDK that reads no zero duration and whose decoder the ORM cannot hook.
45
+ Upgrade note: a record the ORM writes can now hold a zero duration, which a reader that does not
46
+ go through the ORM's clients cannot read (an `AsyncSurreal` client the application builds itself,
47
+ another service on the SDK 2.0.0).
48
+
49
+ ### Notes
50
+
51
+ - **SurrealDB 2.x vs 3.x**: zero durations and degenerate geometries read the same on both lines.
52
+ Native sets exist only on 3.x: on 3.3 a `TYPE set<…>` column stores a `set[X]` field's array as a
53
+ native set, which now reads back as the declared set; 3.1 still refuses an array in such a
54
+ column, so declare `array<…>` columns to support 3.1. On 2.x the column holds an array, as
55
+ before.
56
+ - The README's "Values the SDK cannot read", "Geometries the SDK cannot read" and "Sets" sections,
57
+ the refusals table and the 2.x/3.x row for `TYPE set<…>` columns describe the new behaviour; the
58
+ v0.23.0 rich field types notebook stores and reads back a zero duration.
59
+ - A later SDK reads zero durations and native sets itself
60
+ ([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)); the hook then leaves
61
+ them to it.
62
+ - Tested against SurrealDB 3.3.4 and 2.7.0 (the CI pins), plus 3.1.5 for backward compatibility.
63
+
64
+ ## [0.24.2] - 2026-10-15
65
+
66
+ Sub-models keep their rich values after a write that returns the row, and a `timedelta` below the
67
+ top level reads the server's duration. No new public API.
68
+
69
+ ### Fixed
70
+
71
+ - **A sub-model's durations, ranges and geometries were written back as plain objects** (#228).
72
+ `save()` without an id, `upsert()`, `refresh()`, `merge()`, `patch()` and the `atomic_*` helpers
73
+ applied the returned row without validation, so a sub-model field (a Pydantic model, a dataclass
74
+ or a `TypedDict`, also inside `list[...]`, `dict[..., ...]` or `X | None`) held the row's `dict`
75
+ with the SDK's values. The next full write (`update()`, `upsert()`) stored their fields
76
+ (`{elapsed: 300000000000}`) instead of SurrealDB's durations, ranges and geometries, warned
77
+ `PydanticSerializationUnexpectedValue`, and the next `get()` of the record failed validation.
78
+ These calls now give a sub-model field the value a read gives: its model instance, with the ORM's
79
+ `Duration`, `timedelta`, `Range` and geometry values inside, so writing the instance back is safe.
80
+ - The returned row goes through the model's validation, as in `get()`, so the model's own
81
+ validators (`field_validator`, `model_validator`, `model_post_init`) run on it too.
82
+ - When the row as a whole does not validate, each sub-model field is validated on its own, except
83
+ one that the model's own validators could reshape; that one, like a value that does not
84
+ validate, is applied as received. These calls raise nothing new.
85
+ - A GeoJSON object stored in a top-level geometry field (the full SurrealDB-ORM's format) now
86
+ becomes the ORM geometry after `refresh()`, `merge()` and `patch()`, as after `get()`.
87
+ - **A `timedelta` below the top level failed to read the server's duration.** A sub-model's
88
+ `timedelta` field, `list[timedelta]`, `dict[str, timedelta]` or `timedelta | str` refused the
89
+ SDK's `Duration` on every read, as before v0.23.0. They now read a `timedelta`, floored to the
90
+ microsecond (declare `Duration` to keep the nanoseconds), in a read and in the row a write
91
+ returns. A row holding many such values is converted in one pass, without mutating the data,
92
+ and the model's own validators (any mode) and `model_post_init` still apply once, even when they
93
+ change the data in place.
94
+
95
+ ### Notes
96
+
97
+ - **Identical on SurrealDB 2.x and 3.x**: the cause was in how the ORM applied the SDK's values,
98
+ not in the server. The README's "Rich values inside sub-models" limitation of section 25 is
99
+ removed, and "After a write that returns the row" describes the new behaviour; top-level `date`,
100
+ `set` and `Range` fields still hold the SDK's value until the record is loaded again.
101
+ - Tested against SurrealDB 3.3.4 and 2.7.0 (the CI pins), plus 3.1.5 for backward compatibility.
102
+
8
103
  ## [0.24.0] - 2026-10-15
9
104
 
10
105
  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.1
3
+ Version: 0.24.3
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
 
@@ -2197,10 +2199,10 @@ both lines.
2197
2199
 
2198
2200
  #### Sets
2199
2201
 
2200
- `set[X]`/`frozenset[X]` fields are stored as arrays. On SurrealDB 3.x a `TYPE set<…>` column
2201
- holds a native set that the surrealdb SDK 2.0.0 cannot read (every read of the column fails with an
2202
- SDK decoding error), and 3.1 refuses an array in it; declare such columns `array<…>`, optionally
2203
- with `VALUE $value.distinct()`:
2202
+ `set[X]`/`frozenset[X]` fields are stored as arrays. On SurrealDB 3.3 a `TYPE set<…>` column
2203
+ stores the array as a native set, which the field reads back as the declared set (see
2204
+ [Values the SDK cannot read](#values-the-sdk-cannot-read)), but 3.1 refuses an array in it; to
2205
+ support 3.1, declare such columns `array<…>`, optionally with `VALUE $value.distinct()`:
2204
2206
 
2205
2207
  ```sql
2206
2208
  DEFINE FIELD tags ON subscription TYPE array<string> VALUE $value.distinct();
@@ -2216,22 +2218,28 @@ Every value the ORM sends (a field, a filter value, a `call_function()` argument
2216
2218
  variable) goes through the same check. A value SurrealDB would reject is refused before anything
2217
2219
  is sent, with a plain `ValueError` that says why, never re-wrapped in a `SurrealDbError`:
2218
2220
 
2219
- | Value | Raised |
2220
- | ----------------------------------------------------------------------------------------------- | ---------------------------- |
2221
- | A negative duration (a `timedelta`, the SDK's `Duration`) | `ValueError` |
2222
- | A duration of `2**64` seconds or more | `ValueError` |
2223
- | A zero duration, while the installed SDK cannot read one back (SDK 2.0.0) | `ValueError` |
2224
- | A finite `Decimal` whose integer part, rounded, exceeds `2**96 - 1` | `ValueError` |
2225
- | An `int` outside the signed 64-bit range | `ValueError` (use `Decimal`) |
2226
- | A `Range` side that is neither `BoundIncluded`/`BoundExcluded` nor an open side | `ValueError` |
2227
- | `id__in=Range(…)`, `id__not_in=Range(…)`, or the same on an edge's `in`/`out` | `ValueError` |
2228
- | `atomic_increment(field, <a duration>)` | `TypeError` (use `merge()`) |
2229
- | In a live filter, a zero, negative or oversized duration, or a range bound with no literal form | `TypeError` from `live()` |
2230
- | A `Duration` or `Range` field given a value it does not accept | Pydantic's `ValidationError` |
2231
-
2232
- For a zero duration, store `None` instead (declare the field optional) and filter "longer than
2233
- zero" with `__gte=Duration(1)`. `atomic_increment()` adds numbers only: SurrealDB 2.x ignores `+=`
2234
- with a duration, so the ORM refuses it on both lines; set the new value with `merge()`:
2221
+ | Value | Raised |
2222
+ | ----------------------------------------------------------------------------------------- | ---------------------------- |
2223
+ | A negative duration (a `timedelta`, the SDK's `Duration`) | `ValueError` |
2224
+ | A duration of `2**64` seconds or more | `ValueError` |
2225
+ | A zero duration, if neither the SDK nor the ORM reads one back (never with SDK 2.0.0) | `ValueError` |
2226
+ | A finite `Decimal` whose integer part, rounded, exceeds `2**96 - 1` | `ValueError` |
2227
+ | An `int` outside the signed 64-bit range | `ValueError` (use `Decimal`) |
2228
+ | A `Range` side that is neither `BoundIncluded`/`BoundExcluded` nor an open side | `ValueError` |
2229
+ | `id__in=Range(…)`, `id__not_in=Range(…)`, or the same on an edge's `in`/`out` | `ValueError` |
2230
+ | `atomic_increment(field, <a duration>)` | `TypeError` (use `merge()`) |
2231
+ | In a live filter, a negative or oversized duration, or a range bound with no literal form | `TypeError` from `live()` |
2232
+ | A `Duration` or `Range` field given a value it does not accept | Pydantic's `ValidationError` |
2233
+
2234
+ A zero duration (`timedelta(0)`, `Duration(0)`) is written, filtered and read back like any
2235
+ other, on both lines: the surrealdb SDK 2.0.0 cannot read one, but the clients the ORM opens do
2236
+ (see [Values the SDK cannot read](#values-the-sdk-cannot-read)); in the one case where nothing
2237
+ reads it back, a live filter refuses it with `TypeError` too. Since v0.24.3 the ORM stores zero
2238
+ durations, so a record it writes can hold one that a reader outside its clients cannot read: an
2239
+ `AsyncSurreal` client the application builds itself, or another service on the SDK 2.0.0. Filter
2240
+ "longer than zero" with `__gt=Duration(0)` or `__gte=Duration(1)`. `atomic_increment()` adds
2241
+ numbers only: SurrealDB 2.x ignores `+=` with a duration, so the ORM refuses it on both lines; set
2242
+ the new value with `merge()`:
2235
2243
 
2236
2244
  ```python
2237
2245
  nonzero = await Subscription.objects().filter(trial__gte=Duration(1)).exec() # longer than zero
@@ -2241,25 +2249,50 @@ await sub.merge(trial=sub.trial + timedelta(days=7)) #
2241
2249
  #### After a write that returns the row
2242
2250
 
2243
2251
  `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)).
2252
+ apply the row the server returns to the instance. Top-level `timedelta`, `Duration` and geometry
2253
+ fields (since v0.24.0, see [section 25](#25-geospatial-fields)) are converted on the way. A field
2254
+ that holds a sub-model (a Pydantic model, a dataclass or a `TypedDict`, also inside `list[...]`,
2255
+ `dict[..., ...]` or `X | None`) or a `timedelta` below the top level (`list[timedelta]`,
2256
+ `timedelta | str`…) gets the value a read gives: the row goes through the model's validation, the
2257
+ model's own validators included, and a sub-model field holds its model instance, not the row's
2258
+ `dict`, with the ORM's durations, `timedelta`s, ranges and geometries inside. When the row as a
2259
+ whole does not validate, each such field is validated on its own, except one that the model's own
2260
+ validators could reshape (a `field_validator` on that field, a `model_validator`, a
2261
+ `model_post_init`): that one, like a value that does not validate, is applied as received, so
2262
+ these calls never fail on it. Other top-level `date`, `set` and `Range` fields hold the SDK's value
2263
+ (a midnight `datetime`, a `list`, the SDK's `Range`) until the record is loaded again (`get()`,
2264
+ `filter()`, …). Writing such an instance back is safe, sub-models included, since those values are
2265
+ stored the same way, although Pydantic warns (`PydanticSerializationUnexpectedValue`) about the
2266
+ top-level `date` and `set` fields while serialising them.
2253
2267
 
2254
2268
  #### Values the SDK cannot read
2255
2269
 
2256
- The surrealdb SDK 2.0.0 cannot decode a zero duration or a SurrealDB 3.x native set. The ORM never
2257
- sends a zero duration and sends sets as arrays, but a record another client wrote, or a
2258
- `TYPE set<…>` column on SurrealDB 3.3 (see [Sets](#sets)), may hold one: reading it fails with an
2259
- SDK decoding error. A later SDK lifts both limits
2260
- ([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)). A degenerate geometry
2261
- another client wrote (a 1-point line, a ring of fewer than 4 points) cannot be read either: see
2262
- [Geometries the SDK cannot read](#geometries-the-sdk-cannot-read).
2270
+ The surrealdb SDK 2.0.0 cannot decode a zero duration, a SurrealDB 3.x native set (a
2271
+ `TYPE set<…>` column on SurrealDB 3.3, see [Sets](#sets)) or a degenerate geometry (see
2272
+ [Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)): one such value fails the whole
2273
+ response it is in. The clients the ORM opens read them anyway, through a hook around the SDK's own
2274
+ CBOR decoder that handles only these values; everything else reads exactly as the SDK reads it:
2275
+
2276
+ - a zero duration reads as zero: `timedelta(0)` or `Duration(0)` in a typed field, the SDK's
2277
+ `Duration(0)` in an untyped one;
2278
+ - a native set reads as a Python `set`, which `set[X]` and `frozenset[X]` fields validate, or as a
2279
+ `list` when its items are unhashable (record ids, objects, nested sets) or two of them are equal
2280
+ in Python, like `1` and `true`: every item the server holds comes back.
2281
+
2282
+ Written back through the ORM (`merge(v=row.v)`, or `update()`, which rewrites the whole row, the
2283
+ untouched fields included), a zero duration stays a duration, but a native set is stored as an
2284
+ array, like every set the ORM writes, unless its column is `TYPE set<…>` (see [Sets](#sets)), and
2285
+ a degenerate geometry as a plain object (see
2286
+ [Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)). In an untyped field, `update()`
2287
+ flattens the SDK's `Duration(0)` into an object, like any SDK value there
2288
+ ([#222](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/222)).
2289
+
2290
+ The hook is installed only while the installed SDK cannot decode these values, and only on the
2291
+ ORM's own clients (`SurrealDBConnectionManager.get_client()`, `ephemeral_client()`). An
2292
+ `AsyncSurreal` client the application builds itself keeps the SDK's behaviour and fails on them.
2293
+ A later SDK reads zero durations and native sets itself
2294
+ ([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)), and the hook then
2295
+ leaves them to it.
2263
2296
 
2264
2297
  #### Authentication
2265
2298
 
@@ -2273,8 +2306,10 @@ refused value raises `ValueError` before anything is sent.
2273
2306
 
2274
2307
  Plain `datetime`, `Decimal` and `UUID` annotations work as they do there. The full ORM has no
2275
2308
  `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)).
2309
+ `Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; lite
2310
+ validates the sub-model, geometry and nested `timedelta` fields of those rows and converts
2311
+ top-level durations, while top-level `date`, `set` and `Range` fields keep the SDK's value (see
2312
+ [After a write that returns the row](#after-a-write-that-returns-the-row)).
2278
2313
 
2279
2314
  ### 25. Geospatial fields
2280
2315
 
@@ -2572,19 +2607,9 @@ for restaurant in await Restaurant.objects().all():
2572
2607
  SurrealDB keeps a GeoJSON dict as a plain object, not a geometry: the full SurrealDB-ORM stores its
2573
2608
  geometry fields that way, and so does any client that writes GeoJSON dicts. `nearby()` skips such
2574
2609
  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).
2610
+ into geometries. A geometry field reads them (a GeoJSON object validates, in a read and in the row
2611
+ a write returns), and `update()` writes the instance back with a native geometry, so loading and
2612
+ updating every record migrates a table.
2588
2613
 
2589
2614
  #### Untyped fields
2590
2615
 
@@ -2609,10 +2634,24 @@ in type-checked code, use the aliases or the classes.
2609
2634
 
2610
2635
  #### Geometries the SDK cannot read
2611
2636
 
2612
- A degenerate geometry written by another client (a 1-point line, a ring of fewer than 4 points)
2613
- cannot be read by the surrealdb SDK 2.0.0: the read fails with an SDK decoding error. The ORM never
2614
- writes one: its classes refuse such values, and so does the check of the SDK geometries it sends
2615
- (see [Decimal coordinates of SDK geometries](#decimal-coordinates-of-sdk-geometries)).
2637
+ A degenerate geometry written by another client (a line of fewer than 2 points, alone or inside
2638
+ another geometry, or a polygon ring of fewer than 4 points) cannot be decoded by the surrealdb SDK
2639
+ 2.0.0, nor by its 3.0 pre-releases. The clients the ORM opens read it as its GeoJSON dict, such as
2640
+ `{"type": "LineString", "coordinates": [[1.0, 2.0]]}`; a multi-geometry or a collection holding
2641
+ one reads as GeoJSON as a whole (see
2642
+ [Values the SDK cannot read](#values-the-sdk-cannot-read) for where this applies):
2643
+
2644
+ - an untyped field (`Any`, `dict`), `raw_query()` and live notifications give that dict;
2645
+ - a geometry field refuses it with a `ValidationError` naming the field, since the ORM's geometry
2646
+ classes refuse degenerate values: `get()` raises it, and `filter().exec()` and `raw_query()`
2647
+ return such rows as dicts, as for any row that does not validate.
2648
+
2649
+ The ORM never writes one: its classes refuse such values, and so does the check of the SDK
2650
+ geometries it sends (see [Decimal coordinates of SDK geometries](#decimal-coordinates-of-sdk-geometries)).
2651
+ Written back, the dict an untyped field holds is stored as a plain object, not a geometry, on both
2652
+ lines, like any GeoJSON dict (see [Migrating stored GeoJSON](#migrating-stored-geojson)):
2653
+ `merge(v=row.v)` does it, and so does `update()` after a change to another field, since it
2654
+ rewrites the whole row.
2616
2655
 
2617
2656
  #### Coming from the full SurrealDB-ORM
2618
2657
 
@@ -2642,8 +2681,6 @@ writes one: its classes refuse such values, and so does the check of the SDK geo
2642
2681
  `surreal_orm`, `surreal_orm.fields`, `surreal_orm.geo`); `is_geo_field` and `get_geo_info` come
2643
2682
  from `surreal_orm_lite.geo` (the full ORM: `surreal_orm.fields`). There is no
2644
2683
  `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
2684
 
2648
2685
  ---
2649
2686
 
@@ -2843,7 +2880,7 @@ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v
2843
2880
  | `get_related(direction="both")` | out-neighbours, then in-neighbours; the order inside each group differs between versions | same on both lines | v0.22.0 |
2844
2881
  | `UNIQUE` index on an edge table's `in, out`: a second edge for the same ordered pair | raises ("index … already contains"), through `insert_relation()` and `RELATE`; the reverse pair is allowed | same on both lines | v0.22.0 |
2845
2882
  | Rich field types (`datetime`, `date`, `timedelta`/`Duration`, `Decimal`, `UUID`, `bytes`, `Range`, `set[X]`) | same on both lines: stored natively (sets as arrays) and read back as the declared type; a value the server would reject is refused with `ValueError` before anything is sent | same on both lines (verified on 3.3.4 and 3.1.5) | v0.23.0 |
2846
- | `TYPE set<…>` columns (a `set[X]` or `frozenset[X]` field) | an array: the ORM reads back the declared set | 3.1: writing the array is refused. 3.3: stored as a native set the surrealdb SDK 2.0.0 cannot read (reads fail with an SDK decoding error). Declare `array<…>` columns (section 24) | v0.23.0 |
2883
+ | `TYPE set<…>` columns (a `set[X]` or `frozenset[X]` field) | an array: the ORM reads back the declared set | 3.1: writing the array is refused. 3.3: stored as a native set, read back as the declared set (the SDK 2.0.0 alone cannot read it, section 24). Declare `array<…>` columns on 3.1.x | v0.23.0 |
2847
2884
  | Reading a `Decimal` | trailing zeros kept (`Decimal("12.50")` reads `12.50`) | normalised (`12.5`); the values are equal | pre-existing (documented in v0.23.0) |
2848
2885
  | Geometry fields, `nearby()`, `GeoDistance`, the `inside` / `outside` / `intersects` lookups | same on both lines: stored as native geometries, read back as the declared class, distances in metres identical | same on both lines (verified on 3.3.4 and 3.1.5); an SDK geometry SurrealDB refuses raises `ValueError` before anything is sent | v0.24.0 |
2849
2886
  | A `Decimal` coordinate written with an exponent in an SDK geometry | raw SDK value: refused, or a wrong value for a long one. ORM: sent in fixed point, stored with its value | raw SDK value: stored, a long one with a wrong value. ORM: sent in fixed point, stored with its value | v0.24.0 |
@@ -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
 
@@ -2146,10 +2148,10 @@ both lines.
2146
2148
 
2147
2149
  #### Sets
2148
2150
 
2149
- `set[X]`/`frozenset[X]` fields are stored as arrays. On SurrealDB 3.x a `TYPE set<…>` column
2150
- holds a native set that the surrealdb SDK 2.0.0 cannot read (every read of the column fails with an
2151
- SDK decoding error), and 3.1 refuses an array in it; declare such columns `array<…>`, optionally
2152
- with `VALUE $value.distinct()`:
2151
+ `set[X]`/`frozenset[X]` fields are stored as arrays. On SurrealDB 3.3 a `TYPE set<…>` column
2152
+ stores the array as a native set, which the field reads back as the declared set (see
2153
+ [Values the SDK cannot read](#values-the-sdk-cannot-read)), but 3.1 refuses an array in it; to
2154
+ support 3.1, declare such columns `array<…>`, optionally with `VALUE $value.distinct()`:
2153
2155
 
2154
2156
  ```sql
2155
2157
  DEFINE FIELD tags ON subscription TYPE array<string> VALUE $value.distinct();
@@ -2165,22 +2167,28 @@ Every value the ORM sends (a field, a filter value, a `call_function()` argument
2165
2167
  variable) goes through the same check. A value SurrealDB would reject is refused before anything
2166
2168
  is sent, with a plain `ValueError` that says why, never re-wrapped in a `SurrealDbError`:
2167
2169
 
2168
- | Value | Raised |
2169
- | ----------------------------------------------------------------------------------------------- | ---------------------------- |
2170
- | A negative duration (a `timedelta`, the SDK's `Duration`) | `ValueError` |
2171
- | A duration of `2**64` seconds or more | `ValueError` |
2172
- | A zero duration, while the installed SDK cannot read one back (SDK 2.0.0) | `ValueError` |
2173
- | A finite `Decimal` whose integer part, rounded, exceeds `2**96 - 1` | `ValueError` |
2174
- | An `int` outside the signed 64-bit range | `ValueError` (use `Decimal`) |
2175
- | A `Range` side that is neither `BoundIncluded`/`BoundExcluded` nor an open side | `ValueError` |
2176
- | `id__in=Range(…)`, `id__not_in=Range(…)`, or the same on an edge's `in`/`out` | `ValueError` |
2177
- | `atomic_increment(field, <a duration>)` | `TypeError` (use `merge()`) |
2178
- | In a live filter, a zero, negative or oversized duration, or a range bound with no literal form | `TypeError` from `live()` |
2179
- | A `Duration` or `Range` field given a value it does not accept | Pydantic's `ValidationError` |
2180
-
2181
- For a zero duration, store `None` instead (declare the field optional) and filter "longer than
2182
- zero" with `__gte=Duration(1)`. `atomic_increment()` adds numbers only: SurrealDB 2.x ignores `+=`
2183
- with a duration, so the ORM refuses it on both lines; set the new value with `merge()`:
2170
+ | Value | Raised |
2171
+ | ----------------------------------------------------------------------------------------- | ---------------------------- |
2172
+ | A negative duration (a `timedelta`, the SDK's `Duration`) | `ValueError` |
2173
+ | A duration of `2**64` seconds or more | `ValueError` |
2174
+ | A zero duration, if neither the SDK nor the ORM reads one back (never with SDK 2.0.0) | `ValueError` |
2175
+ | A finite `Decimal` whose integer part, rounded, exceeds `2**96 - 1` | `ValueError` |
2176
+ | An `int` outside the signed 64-bit range | `ValueError` (use `Decimal`) |
2177
+ | A `Range` side that is neither `BoundIncluded`/`BoundExcluded` nor an open side | `ValueError` |
2178
+ | `id__in=Range(…)`, `id__not_in=Range(…)`, or the same on an edge's `in`/`out` | `ValueError` |
2179
+ | `atomic_increment(field, <a duration>)` | `TypeError` (use `merge()`) |
2180
+ | In a live filter, a negative or oversized duration, or a range bound with no literal form | `TypeError` from `live()` |
2181
+ | A `Duration` or `Range` field given a value it does not accept | Pydantic's `ValidationError` |
2182
+
2183
+ A zero duration (`timedelta(0)`, `Duration(0)`) is written, filtered and read back like any
2184
+ other, on both lines: the surrealdb SDK 2.0.0 cannot read one, but the clients the ORM opens do
2185
+ (see [Values the SDK cannot read](#values-the-sdk-cannot-read)); in the one case where nothing
2186
+ reads it back, a live filter refuses it with `TypeError` too. Since v0.24.3 the ORM stores zero
2187
+ durations, so a record it writes can hold one that a reader outside its clients cannot read: an
2188
+ `AsyncSurreal` client the application builds itself, or another service on the SDK 2.0.0. Filter
2189
+ "longer than zero" with `__gt=Duration(0)` or `__gte=Duration(1)`. `atomic_increment()` adds
2190
+ numbers only: SurrealDB 2.x ignores `+=` with a duration, so the ORM refuses it on both lines; set
2191
+ the new value with `merge()`:
2184
2192
 
2185
2193
  ```python
2186
2194
  nonzero = await Subscription.objects().filter(trial__gte=Duration(1)).exec() # longer than zero
@@ -2190,25 +2198,50 @@ await sub.merge(trial=sub.trial + timedelta(days=7)) #
2190
2198
  #### After a write that returns the row
2191
2199
 
2192
2200
  `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)).
2201
+ apply the row the server returns to the instance. Top-level `timedelta`, `Duration` and geometry
2202
+ fields (since v0.24.0, see [section 25](#25-geospatial-fields)) are converted on the way. A field
2203
+ that holds a sub-model (a Pydantic model, a dataclass or a `TypedDict`, also inside `list[...]`,
2204
+ `dict[..., ...]` or `X | None`) or a `timedelta` below the top level (`list[timedelta]`,
2205
+ `timedelta | str`…) gets the value a read gives: the row goes through the model's validation, the
2206
+ model's own validators included, and a sub-model field holds its model instance, not the row's
2207
+ `dict`, with the ORM's durations, `timedelta`s, ranges and geometries inside. When the row as a
2208
+ whole does not validate, each such field is validated on its own, except one that the model's own
2209
+ validators could reshape (a `field_validator` on that field, a `model_validator`, a
2210
+ `model_post_init`): that one, like a value that does not validate, is applied as received, so
2211
+ these calls never fail on it. Other top-level `date`, `set` and `Range` fields hold the SDK's value
2212
+ (a midnight `datetime`, a `list`, the SDK's `Range`) until the record is loaded again (`get()`,
2213
+ `filter()`, …). Writing such an instance back is safe, sub-models included, since those values are
2214
+ stored the same way, although Pydantic warns (`PydanticSerializationUnexpectedValue`) about the
2215
+ top-level `date` and `set` fields while serialising them.
2202
2216
 
2203
2217
  #### Values the SDK cannot read
2204
2218
 
2205
- The surrealdb SDK 2.0.0 cannot decode a zero duration or a SurrealDB 3.x native set. The ORM never
2206
- sends a zero duration and sends sets as arrays, but a record another client wrote, or a
2207
- `TYPE set<…>` column on SurrealDB 3.3 (see [Sets](#sets)), may hold one: reading it fails with an
2208
- SDK decoding error. A later SDK lifts both limits
2209
- ([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)). A degenerate geometry
2210
- another client wrote (a 1-point line, a ring of fewer than 4 points) cannot be read either: see
2211
- [Geometries the SDK cannot read](#geometries-the-sdk-cannot-read).
2219
+ The surrealdb SDK 2.0.0 cannot decode a zero duration, a SurrealDB 3.x native set (a
2220
+ `TYPE set<…>` column on SurrealDB 3.3, see [Sets](#sets)) or a degenerate geometry (see
2221
+ [Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)): one such value fails the whole
2222
+ response it is in. The clients the ORM opens read them anyway, through a hook around the SDK's own
2223
+ CBOR decoder that handles only these values; everything else reads exactly as the SDK reads it:
2224
+
2225
+ - a zero duration reads as zero: `timedelta(0)` or `Duration(0)` in a typed field, the SDK's
2226
+ `Duration(0)` in an untyped one;
2227
+ - a native set reads as a Python `set`, which `set[X]` and `frozenset[X]` fields validate, or as a
2228
+ `list` when its items are unhashable (record ids, objects, nested sets) or two of them are equal
2229
+ in Python, like `1` and `true`: every item the server holds comes back.
2230
+
2231
+ Written back through the ORM (`merge(v=row.v)`, or `update()`, which rewrites the whole row, the
2232
+ untouched fields included), a zero duration stays a duration, but a native set is stored as an
2233
+ array, like every set the ORM writes, unless its column is `TYPE set<…>` (see [Sets](#sets)), and
2234
+ a degenerate geometry as a plain object (see
2235
+ [Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)). In an untyped field, `update()`
2236
+ flattens the SDK's `Duration(0)` into an object, like any SDK value there
2237
+ ([#222](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/222)).
2238
+
2239
+ The hook is installed only while the installed SDK cannot decode these values, and only on the
2240
+ ORM's own clients (`SurrealDBConnectionManager.get_client()`, `ephemeral_client()`). An
2241
+ `AsyncSurreal` client the application builds itself keeps the SDK's behaviour and fails on them.
2242
+ A later SDK reads zero durations and native sets itself
2243
+ ([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)), and the hook then
2244
+ leaves them to it.
2212
2245
 
2213
2246
  #### Authentication
2214
2247
 
@@ -2222,8 +2255,10 @@ refused value raises `ValueError` before anything is sent.
2222
2255
 
2223
2256
  Plain `datetime`, `Decimal` and `UUID` annotations work as they do there. The full ORM has no
2224
2257
  `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)).
2258
+ `Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; lite
2259
+ validates the sub-model, geometry and nested `timedelta` fields of those rows and converts
2260
+ top-level durations, while top-level `date`, `set` and `Range` fields keep the SDK's value (see
2261
+ [After a write that returns the row](#after-a-write-that-returns-the-row)).
2227
2262
 
2228
2263
  ### 25. Geospatial fields
2229
2264
 
@@ -2521,19 +2556,9 @@ for restaurant in await Restaurant.objects().all():
2521
2556
  SurrealDB keeps a GeoJSON dict as a plain object, not a geometry: the full SurrealDB-ORM stores its
2522
2557
  geometry fields that way, and so does any client that writes GeoJSON dicts. `nearby()` skips such
2523
2558
  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).
2559
+ into geometries. A geometry field reads them (a GeoJSON object validates, in a read and in the row
2560
+ a write returns), and `update()` writes the instance back with a native geometry, so loading and
2561
+ updating every record migrates a table.
2537
2562
 
2538
2563
  #### Untyped fields
2539
2564
 
@@ -2558,10 +2583,24 @@ in type-checked code, use the aliases or the classes.
2558
2583
 
2559
2584
  #### Geometries the SDK cannot read
2560
2585
 
2561
- A degenerate geometry written by another client (a 1-point line, a ring of fewer than 4 points)
2562
- cannot be read by the surrealdb SDK 2.0.0: the read fails with an SDK decoding error. The ORM never
2563
- writes one: its classes refuse such values, and so does the check of the SDK geometries it sends
2564
- (see [Decimal coordinates of SDK geometries](#decimal-coordinates-of-sdk-geometries)).
2586
+ A degenerate geometry written by another client (a line of fewer than 2 points, alone or inside
2587
+ another geometry, or a polygon ring of fewer than 4 points) cannot be decoded by the surrealdb SDK
2588
+ 2.0.0, nor by its 3.0 pre-releases. The clients the ORM opens read it as its GeoJSON dict, such as
2589
+ `{"type": "LineString", "coordinates": [[1.0, 2.0]]}`; a multi-geometry or a collection holding
2590
+ one reads as GeoJSON as a whole (see
2591
+ [Values the SDK cannot read](#values-the-sdk-cannot-read) for where this applies):
2592
+
2593
+ - an untyped field (`Any`, `dict`), `raw_query()` and live notifications give that dict;
2594
+ - a geometry field refuses it with a `ValidationError` naming the field, since the ORM's geometry
2595
+ classes refuse degenerate values: `get()` raises it, and `filter().exec()` and `raw_query()`
2596
+ return such rows as dicts, as for any row that does not validate.
2597
+
2598
+ The ORM never writes one: its classes refuse such values, and so does the check of the SDK
2599
+ geometries it sends (see [Decimal coordinates of SDK geometries](#decimal-coordinates-of-sdk-geometries)).
2600
+ Written back, the dict an untyped field holds is stored as a plain object, not a geometry, on both
2601
+ lines, like any GeoJSON dict (see [Migrating stored GeoJSON](#migrating-stored-geojson)):
2602
+ `merge(v=row.v)` does it, and so does `update()` after a change to another field, since it
2603
+ rewrites the whole row.
2565
2604
 
2566
2605
  #### Coming from the full SurrealDB-ORM
2567
2606
 
@@ -2591,8 +2630,6 @@ writes one: its classes refuse such values, and so does the check of the SDK geo
2591
2630
  `surreal_orm`, `surreal_orm.fields`, `surreal_orm.geo`); `is_geo_field` and `get_geo_info` come
2592
2631
  from `surreal_orm_lite.geo` (the full ORM: `surreal_orm.fields`). There is no
2593
2632
  `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
2633
 
2597
2634
  ---
2598
2635
 
@@ -2792,7 +2829,7 @@ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v
2792
2829
  | `get_related(direction="both")` | out-neighbours, then in-neighbours; the order inside each group differs between versions | same on both lines | v0.22.0 |
2793
2830
  | `UNIQUE` index on an edge table's `in, out`: a second edge for the same ordered pair | raises ("index … already contains"), through `insert_relation()` and `RELATE`; the reverse pair is allowed | same on both lines | v0.22.0 |
2794
2831
  | Rich field types (`datetime`, `date`, `timedelta`/`Duration`, `Decimal`, `UUID`, `bytes`, `Range`, `set[X]`) | same on both lines: stored natively (sets as arrays) and read back as the declared type; a value the server would reject is refused with `ValueError` before anything is sent | same on both lines (verified on 3.3.4 and 3.1.5) | v0.23.0 |
2795
- | `TYPE set<…>` columns (a `set[X]` or `frozenset[X]` field) | an array: the ORM reads back the declared set | 3.1: writing the array is refused. 3.3: stored as a native set the surrealdb SDK 2.0.0 cannot read (reads fail with an SDK decoding error). Declare `array<…>` columns (section 24) | v0.23.0 |
2832
+ | `TYPE set<…>` columns (a `set[X]` or `frozenset[X]` field) | an array: the ORM reads back the declared set | 3.1: writing the array is refused. 3.3: stored as a native set, read back as the declared set (the SDK 2.0.0 alone cannot read it, section 24). Declare `array<…>` columns on 3.1.x | v0.23.0 |
2796
2833
  | Reading a `Decimal` | trailing zeros kept (`Decimal("12.50")` reads `12.50`) | normalised (`12.5`); the values are equal | pre-existing (documented in v0.23.0) |
2797
2834
  | Geometry fields, `nearby()`, `GeoDistance`, the `inside` / `outside` / `intersects` lookups | same on both lines: stored as native geometries, read back as the declared class, distances in metres identical | same on both lines (verified on 3.3.4 and 3.1.5); an SDK geometry SurrealDB refuses raises `ValueError` before anything is sent | v0.24.0 |
2798
2835
  | A `Decimal` coordinate written with an exponent in an SDK geometry | raw SDK value: refused, or a wrong value for a long one. ORM: sent in fixed point, stored with its value | raw SDK value: stored, a long one with a wrong value. ORM: sent in fixed point, stored with its value | v0.24.0 |
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.24.1"
3
+ version = "0.24.3"
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.1"
1
+ __version__ = "0.24.3"
2
2
 
3
3
  from ._sdk import BoundExcluded, BoundIncluded
4
4
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum