surreal-orm-lite 0.24.2__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.2 → surreal_orm_lite-0.24.3}/CHANGELOG.md +56 -0
  2. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/PKG-INFO +72 -33
  3. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/README.md +71 -32
  4. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/_sdk.py +25 -1
  7. {surreal_orm_lite-0.24.2 → 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.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/encoding.py +19 -27
  10. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/geo.py +4 -0
  11. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/surql_literal.py +11 -7
  12. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/.gitignore +0 -0
  13. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/LICENSE +0 -0
  14. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/Makefile +0 -0
  15. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/aggregations.py +0 -0
  16. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/auth.py +0 -0
  17. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/changefeed.py +0 -0
  18. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/concurrency.py +0 -0
  19. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/constants.py +0 -0
  20. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/edge.py +0 -0
  21. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/enum.py +0 -0
  22. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/exceptions.py +0 -0
  23. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/functions.py +0 -0
  24. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/live.py +0 -0
  25. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/model_auth.py +0 -0
  26. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/model_base.py +0 -0
  27. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/py.typed +0 -0
  28. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/q.py +0 -0
  29. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/query_set.py +0 -0
  30. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/signals.py +0 -0
  31. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/transaction.py +0 -0
  32. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/types.py +0 -0
  33. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,62 @@ 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
+
8
64
  ## [0.24.2] - 2026-10-15
9
65
 
10
66
  Sub-models keep their rich values after a write that returns the row, and a `timedelta` below the
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.24.2
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
@@ -2199,10 +2199,10 @@ both lines.
2199
2199
 
2200
2200
  #### Sets
2201
2201
 
2202
- `set[X]`/`frozenset[X]` fields are stored as arrays. On SurrealDB 3.x a `TYPE set<…>` column
2203
- holds a native set that the surrealdb SDK 2.0.0 cannot read (every read of the column fails with an
2204
- SDK decoding error), and 3.1 refuses an array in it; declare such columns `array<…>`, optionally
2205
- 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()`:
2206
2206
 
2207
2207
  ```sql
2208
2208
  DEFINE FIELD tags ON subscription TYPE array<string> VALUE $value.distinct();
@@ -2218,22 +2218,28 @@ Every value the ORM sends (a field, a filter value, a `call_function()` argument
2218
2218
  variable) goes through the same check. A value SurrealDB would reject is refused before anything
2219
2219
  is sent, with a plain `ValueError` that says why, never re-wrapped in a `SurrealDbError`:
2220
2220
 
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, while the installed SDK cannot read one back (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 zero, 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
- For a zero duration, store `None` instead (declare the field optional) and filter "longer than
2235
- zero" with `__gte=Duration(1)`. `atomic_increment()` adds numbers only: SurrealDB 2.x ignores `+=`
2236
- 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()`:
2237
2243
 
2238
2244
  ```python
2239
2245
  nonzero = await Subscription.objects().filter(trial__gte=Duration(1)).exec() # longer than zero
@@ -2261,13 +2267,32 @@ top-level `date` and `set` fields while serialising them.
2261
2267
 
2262
2268
  #### Values the SDK cannot read
2263
2269
 
2264
- The surrealdb SDK 2.0.0 cannot decode a zero duration or a SurrealDB 3.x native set. The ORM never
2265
- sends a zero duration and sends sets as arrays, but a record another client wrote, or a
2266
- `TYPE set<…>` column on SurrealDB 3.3 (see [Sets](#sets)), may hold one: reading it fails with an
2267
- SDK decoding error. A later SDK lifts both limits
2268
- ([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)). A degenerate geometry
2269
- another client wrote (a 1-point line, a ring of fewer than 4 points) cannot be read either: see
2270
- [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.
2271
2296
 
2272
2297
  #### Authentication
2273
2298
 
@@ -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
 
@@ -2841,7 +2880,7 @@ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v
2841
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 |
2842
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 |
2843
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 |
2844
- | `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 |
2845
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) |
2846
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 |
2847
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 |
@@ -2148,10 +2148,10 @@ both lines.
2148
2148
 
2149
2149
  #### Sets
2150
2150
 
2151
- `set[X]`/`frozenset[X]` fields are stored as arrays. On SurrealDB 3.x a `TYPE set<…>` column
2152
- holds a native set that the surrealdb SDK 2.0.0 cannot read (every read of the column fails with an
2153
- SDK decoding error), and 3.1 refuses an array in it; declare such columns `array<…>`, optionally
2154
- 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()`:
2155
2155
 
2156
2156
  ```sql
2157
2157
  DEFINE FIELD tags ON subscription TYPE array<string> VALUE $value.distinct();
@@ -2167,22 +2167,28 @@ Every value the ORM sends (a field, a filter value, a `call_function()` argument
2167
2167
  variable) goes through the same check. A value SurrealDB would reject is refused before anything
2168
2168
  is sent, with a plain `ValueError` that says why, never re-wrapped in a `SurrealDbError`:
2169
2169
 
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, while the installed SDK cannot read one back (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 zero, 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
- For a zero duration, store `None` instead (declare the field optional) and filter "longer than
2184
- zero" with `__gte=Duration(1)`. `atomic_increment()` adds numbers only: SurrealDB 2.x ignores `+=`
2185
- 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()`:
2186
2192
 
2187
2193
  ```python
2188
2194
  nonzero = await Subscription.objects().filter(trial__gte=Duration(1)).exec() # longer than zero
@@ -2210,13 +2216,32 @@ top-level `date` and `set` fields while serialising them.
2210
2216
 
2211
2217
  #### Values the SDK cannot read
2212
2218
 
2213
- The surrealdb SDK 2.0.0 cannot decode a zero duration or a SurrealDB 3.x native set. The ORM never
2214
- sends a zero duration and sends sets as arrays, but a record another client wrote, or a
2215
- `TYPE set<…>` column on SurrealDB 3.3 (see [Sets](#sets)), may hold one: reading it fails with an
2216
- SDK decoding error. A later SDK lifts both limits
2217
- ([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)). A degenerate geometry
2218
- another client wrote (a 1-point line, a ring of fewer than 4 points) cannot be read either: see
2219
- [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.
2220
2245
 
2221
2246
  #### Authentication
2222
2247
 
@@ -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
 
@@ -2790,7 +2829,7 @@ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v
2790
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 |
2791
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 |
2792
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 |
2793
- | `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 |
2794
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) |
2795
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 |
2796
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.2"
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.2"
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
@@ -16,6 +16,11 @@ v0.24.0 adds the geometry symbols, aliased ``Sdk…`` so they never clash with t
16
16
  classes (``geo.py``). SDK 2.0.0 exports only ``Geometry`` and ``InvalidGeometryError`` at the top
17
17
  level and keeps the seven concrete classes in ``surrealdb.data.types.geometry``; they are looked up
18
18
  root first, then that submodule, so a release that exports them at the top level needs no change.
19
+
20
+ #235 adds what the read hook (``decoding.py``) needs: the SDK's CBOR ``tag_decoder``, read from
21
+ ``surrealdb.data.cbor`` only like ``encode``/``decode``, and the three async connection classes,
22
+ root first, then their SDK 2.0.0 submodules. Each is ``None`` when the installed SDK has no such
23
+ symbol: the hook is then not installed.
19
24
  """
20
25
 
21
26
  import importlib
@@ -39,7 +44,7 @@ from surrealdb.cbor import CBORSimpleValue, CBORTag, undefined
39
44
  # The plain CBOR null (``0xf6``): SurrealDB's open range bound (protocol tag 49). ``None`` would go
40
45
  # out as tag 6, NONE. Never mutated by the ORM; recognise a CBOR null with
41
46
  # ``isinstance(x, CBORSimpleValue) and x.value == 22``, never with ``==`` (it equals the int 22).
42
- # With SDK 3.0 (#205) this becomes the SDK's ``Null``.
47
+ # SDK 3.0 (#205): this becomes the SDK's ``Null`` sentinel.
43
48
  CBOR_NULL: Final = CBORSimpleValue(22)
44
49
 
45
50
 
@@ -63,8 +68,12 @@ def _first_of(attr: str, *modules: str, required: bool = True) -> Any:
63
68
 
64
69
 
65
70
  if TYPE_CHECKING:
71
+ from surrealdb import AsyncEmbeddedSurrealConnection as SdkAsyncEmbeddedConnection
72
+ from surrealdb import AsyncHttpSurrealConnection as SdkAsyncHttpConnection
73
+ from surrealdb import AsyncWsSurrealConnection as SdkAsyncWsConnection
66
74
  from surrealdb.data.cbor import decode as cbor_decode
67
75
  from surrealdb.data.cbor import encode as cbor_encode
76
+ from surrealdb.data.cbor import tag_decoder as cbor_tag_decoder
68
77
  from surrealdb.data.types.geometry import GeometryCollection as SdkGeometryCollection
69
78
  from surrealdb.data.types.geometry import GeometryLine as SdkGeometryLine
70
79
  from surrealdb.data.types.geometry import GeometryMultiLine as SdkGeometryMultiLine
@@ -83,6 +92,16 @@ else:
83
92
  # such codec: the local zero-duration probe then answers False.
84
93
  cbor_encode = _first_of("encode", "surrealdb.data.cbor", required=False)
85
94
  cbor_decode = _first_of("decode", "surrealdb.data.cbor", required=False)
95
+ # SDK 3.0 (#205): the read hook (``decoding.py``) wraps this ``tag_decoder`` and the decoding
96
+ # method of these three classes; re-check both against the stable SDK's layout.
97
+ cbor_tag_decoder = _first_of("tag_decoder", "surrealdb.data.cbor", required=False)
98
+ SdkAsyncWsConnection = _first_of("AsyncWsSurrealConnection", "surrealdb", "surrealdb.connections.async_ws", required=False)
99
+ SdkAsyncHttpConnection = _first_of(
100
+ "AsyncHttpSurrealConnection", "surrealdb", "surrealdb.connections.async_http", required=False
101
+ )
102
+ SdkAsyncEmbeddedConnection = _first_of(
103
+ "AsyncEmbeddedSurrealConnection", "surrealdb", "surrealdb.connections.async_embedded", required=False
104
+ )
86
105
  # ``None`` when the installed SDK has no such class: the ORM's class then derives from
87
106
  # ``ValueError`` alone (``exceptions.py``).
88
107
  SdkInvalidDurationError = _first_of("InvalidDurationError", "surrealdb", "surrealdb.errors", required=False)
@@ -121,6 +140,11 @@ __all__ = [
121
140
  "cbor_encode",
122
141
  "cbor_decode",
123
142
  "SdkInvalidDurationError",
143
+ # Read hook (#235)
144
+ "cbor_tag_decoder",
145
+ "SdkAsyncWsConnection",
146
+ "SdkAsyncHttpConnection",
147
+ "SdkAsyncEmbeddedConnection",
124
148
  # Geometry (v0.24.0)
125
149
  "SdkGeometry",
126
150
  "SdkGeometryPoint",
@@ -10,6 +10,7 @@ from uuid import UUID
10
10
 
11
11
  from pydantic import TypeAdapter, ValidationError
12
12
 
13
+ from . import decoding as _decoding
13
14
  from . import encoding as _encoding
14
15
  from ._sdk import AsyncSurreal, NotFoundError
15
16
  from .auth import AuthTokens, build_auth_payload, wrap_auth_error
@@ -202,6 +203,11 @@ class SurrealDBConnectionManager:
202
203
  ``use()`` still fail, and leaving that socket behind leaks one live connection per
203
204
  attempt against a flaky server.
204
205
 
206
+ Every client opened here reads the values SDK 2.0.0 cannot decode (zero durations, native
207
+ sets, degenerate geometries) through the read hook of ``decoding.py`` (#235), installed
208
+ as soon as the client is built, before ``connect()``. Only these clients get it: a client
209
+ the application builds itself with ``AsyncSurreal`` keeps the SDK's behaviour.
210
+
205
211
  :param signin_as_configured: sign in as the configured user. ``False`` yields an
206
212
  **anonymous** client, ready to be authenticated as somebody else.
207
213
  """
@@ -217,6 +223,9 @@ class SurrealDBConnectionManager:
217
223
  credentials = _encoding.encode({"username": user, "password": password})
218
224
  try:
219
225
  client = AsyncSurreal(url)
226
+ # SDK 3.0 (#205): the read hook is a workaround for SDK 2.0.0's decoder; ``install`` is a
227
+ # no-op once the SDK reads every value itself (capability probes), or has another layout.
228
+ _decoding.install(client)
220
229
  # WebSocket connections require explicit connect()
221
230
  if url.startswith(("ws://", "wss://")):
222
231
  await client.connect(url)
@@ -0,0 +1,338 @@
1
+ """Internal: the read side of the SDK boundary (#235), the counterpart of ``encoding.py``.
2
+
3
+ Not part of the public API — nothing here is exported by ``surreal_orm_lite``.
4
+
5
+ The surrealdb SDK 2.0.0 decodes every response in its connection modules with its CBOR
6
+ ``tag_decoder``, which raises on four kinds of values SurrealDB returns:
7
+
8
+ * a zero duration (CBOR tag 14 with an empty compact form): ``IndexError``;
9
+ * a SurrealDB 3.x native set (tag 56): ``BufferError``;
10
+ * a ``LineString`` of fewer than 2 points, alone or inside another geometry: ``TypeError``;
11
+ * a ``Polygon`` ring of fewer than 4 points: ``InvalidGeometryError``.
12
+
13
+ One such value fails the whole response it is in. ``read_tag_hook`` wraps the SDK's ``tag_decoder``:
14
+ every tag goes to it first, and only these four failures get a value instead of the error — the SDK's
15
+ ``Duration(0)``, a Python ``set`` (a ``list`` when an item is unhashable or two items are equal in
16
+ Python, like ``1`` and ``true``) and the geometry's GeoJSON ``dict`` (``{"type": …, "coordinates":
17
+ …}``, or ``"geometries"`` for a collection), which a geometry field validates or refuses clearly.
18
+ Any other failure is raised as the SDK raises it (a degenerate member beside a member of another
19
+ kind, which SurrealDB never sends, raises ``TypeError``), and every value the SDK decodes comes back
20
+ unchanged.
21
+
22
+ ``install(client)`` gives the hook to one client, the one ``ConnectionManager._open_client`` has just
23
+ built. SDK 2.0.0 has no per-client hook: each connection module binds ``decode`` at module level and
24
+ calls it in one method (``_recv_task`` over WebSocket, ``_send`` over HTTP and embedded). That method
25
+ is set on the instance as a copy of the SDK's own function — the same code object — whose module
26
+ globals are a copy of its module's with ``decode`` replaced by the SDK's ``decode`` run with
27
+ ``read_tag_hook`` as its ``tag_decoder``. Nothing is patched, forked or vendored: the code that runs is
28
+ the SDK's, its modules and classes are untouched, and a client the application builds itself with
29
+ ``AsyncSurreal`` keeps the SDK's behaviour.
30
+
31
+ The hook is installed only when the installed SDK cannot decode one of these values (``needed()``:
32
+ capability probes on hand-built CBOR, run once, no I/O, never a version comparison) and only when the
33
+ SDK's layout is the one described above (``available()``).
34
+ """
35
+
36
+ from __future__ import annotations
37
+
38
+ import functools
39
+ import types
40
+ from collections.abc import Callable
41
+ from typing import Any, Final
42
+
43
+ from . import _sdk
44
+
45
+ __all__ = [
46
+ "TAG_SET",
47
+ "active",
48
+ "available",
49
+ "install",
50
+ "needed",
51
+ "read_tag_hook",
52
+ "sdk_decodes_degenerate_geometries",
53
+ "sdk_decodes_native_sets",
54
+ "sdk_decodes_zero_duration",
55
+ ]
56
+
57
+ # SDK 3.0 (#205): the protocol tag of a SurrealDB 3.x native set, which SDK 2.0.0 does not define;
58
+ # 3.0.0b10 decodes it (``SurrealSet``). Remove with the set fallback below.
59
+ TAG_SET: Final = 56
60
+
61
+ #: The GeoJSON ``type`` of each geometry tag of the SurrealDB protocol.
62
+ _GEOMETRY_TYPES: Final[dict[int, str]] = {
63
+ 88: "Point",
64
+ 89: "LineString",
65
+ 90: "Polygon",
66
+ 91: "MultiPoint",
67
+ 92: "MultiLineString",
68
+ 93: "MultiPolygon",
69
+ 94: "GeometryCollection",
70
+ }
71
+
72
+ #: The geometries made of members, by GeoJSON ``type``: the SDK class, the attribute listing its
73
+ #: members and the members' GeoJSON ``type``. A ``GeometryCollection`` holds members of any type.
74
+ _COMPOSITES: Final[dict[str, tuple[type[Any], str, str]]] = {
75
+ "LineString": (_sdk.SdkGeometryLine, "geometry_points", "Point"),
76
+ "Polygon": (_sdk.SdkGeometryPolygon, "geometry_lines", "LineString"),
77
+ "MultiPoint": (_sdk.SdkGeometryMultiPoint, "geometry_points", "Point"),
78
+ "MultiLineString": (_sdk.SdkGeometryMultiLine, "geometry_lines", "LineString"),
79
+ "MultiPolygon": (_sdk.SdkGeometryMultiPolygon, "geometry_polygons", "Polygon"),
80
+ }
81
+
82
+ # SDK 3.0 (#205): the SDK 2.0.0 methods that decode a response, by name: ``_recv_task`` (WebSocket)
83
+ # and ``_send`` (HTTP, embedded). Re-check against the stable SDK's connection modules; the hook is
84
+ # not installed when none of a client's methods reads the SDK's ``decode`` as a module global.
85
+ _DECODING_METHODS: Final = ("_recv_task", "_send")
86
+
87
+ _UNHANDLED: Final = object()
88
+
89
+
90
+ # --- the tag hook --------------------------------------------------------------------------------
91
+
92
+
93
+ def read_tag_hook(decoder: Any, tag: Any) -> Any:
94
+ """The SDK's ``tag_decoder``, except that the four values SDK 2.0.0 refuses are read.
95
+
96
+ *tag* goes to the SDK's ``tag_decoder`` first. When that raises, a zero duration, a native set
97
+ or a degenerate geometry is read (see the module docstring); anything else re-raises the SDK's
98
+ error. A geometry the SDK built around a member read as GeoJSON (a collection or a multi-line
99
+ holding a degenerate line) is returned as GeoJSON too, since an SDK geometry cannot hold it; one
100
+ whose members are of another kind, a value SurrealDB never sends, raises ``TypeError``.
101
+ """
102
+ sdk_tag_decoder: Callable[[Any, Any], Any] = _sdk.cbor_tag_decoder
103
+ try:
104
+ value = sdk_tag_decoder(decoder, tag)
105
+ except Exception:
106
+ fallback = _fallback(tag)
107
+ if fallback is _UNHANDLED:
108
+ raise
109
+ return fallback
110
+ # SDK 3.0 (#205): keep while the SDK does not decode degenerate geometries (3.0.0b10 does not):
111
+ # SDK 2.0.0's multi-geometries and collections accept any member, a GeoJSON dict included.
112
+ if tag.tag in _GEOMETRY_TYPES and isinstance(tag.value, (list, tuple)) and any(isinstance(m, dict) for m in tag.value):
113
+ return _geojson(tag)
114
+ return value
115
+
116
+
117
+ def _fallback(tag: Any) -> Any:
118
+ """What the hook reads for a tag the SDK refused, or ``_UNHANDLED`` to re-raise the SDK's error."""
119
+ number, value = tag.tag, tag.value
120
+ if number == _sdk.TAG_DURATION_COMPACT and isinstance(value, (list, tuple)) and not value:
121
+ # SDK 3.0 (#205): remove. SDK 2.0.0 indexes the compact form without checking its length and
122
+ # raises IndexError on the server's zero duration (``[]``); 3.0.0b10 reads it.
123
+ return _sdk.SdkDuration(0)
124
+ if number == TAG_SET and isinstance(value, (list, tuple)):
125
+ # SDK 3.0 (#205): remove. SDK 2.0.0 has no decoder for tag 56 (BufferError); 3.0.0b10 reads a
126
+ # ``SurrealSet``: decide then what a read returns (a ``set`` today).
127
+ return _set_of(value)
128
+ if number in _GEOMETRY_TYPES:
129
+ # SDK 3.0 (#205): keep while the SDK does not decode degenerate geometries (3.0.0b10 does not):
130
+ # SDK 2.0.0's constructors refuse a line of fewer than 2 points (TypeError) and a ring of
131
+ # fewer than 4 (InvalidGeometryError), and a polygon fails on a ring read as GeoJSON.
132
+ try:
133
+ return _geojson(tag)
134
+ except TypeError: # a malformed value, or a point: the SDK's error stands
135
+ return _UNHANDLED
136
+ return _UNHANDLED
137
+
138
+
139
+ def _set_of(items: list[Any] | tuple[Any, ...]) -> set[Any] | list[Any]:
140
+ """A native set's items (already decoded by the SDK) as a ``set``, or a ``list`` when a ``set`` loses one.
141
+
142
+ A ``list`` when an item is unhashable, and when two items are equal in Python (``1`` and
143
+ ``True``, ``1`` and ``1.0``): the server already deduplicated the set, so a smaller ``set`` would
144
+ merge distinct SurrealDB values and drop one without an error.
145
+ """
146
+ try:
147
+ out = set(items)
148
+ except TypeError:
149
+ return list(items)
150
+ return out if len(out) == len(items) else list(items)
151
+
152
+
153
+ def _geojson(tag: Any) -> dict[str, Any]:
154
+ """The geometry *tag*, its members already decoded, as its GeoJSON ``dict``.
155
+
156
+ ``TypeError`` for a ``Point``, which is never degenerate, and when the value does not hold
157
+ members of the tag's kind, each a geometry the SDK built or one this hook read as GeoJSON.
158
+ """
159
+ kind = _GEOMETRY_TYPES[tag.tag]
160
+ members = _members(tag.value)
161
+ if kind == "GeometryCollection":
162
+ return {"type": kind, "geometries": [_member_geojson(member) for member in members]}
163
+ if kind not in _COMPOSITES:
164
+ raise TypeError(f"a {kind} is never degenerate")
165
+ _, _, member_kind = _COMPOSITES[kind]
166
+ return {"type": kind, "coordinates": [_coordinates(member, member_kind) for member in members]}
167
+
168
+
169
+ def _members(value: Any) -> list[Any] | tuple[Any, ...]:
170
+ """A geometry's members: an array, or ``TypeError``."""
171
+ if not isinstance(value, (list, tuple)):
172
+ raise TypeError(f"a geometry's members are an array, not {type(value).__name__}")
173
+ return value
174
+
175
+
176
+ def _member_geojson(member: Any) -> dict[str, Any]:
177
+ """A collection member, an SDK geometry or one this hook read as GeoJSON, as its GeoJSON ``dict``."""
178
+ if isinstance(member, dict): # the hook reads a line, a polygon, a multi-geometry or a collection
179
+ kind = member.get("type")
180
+ if kind == "GeometryCollection" and "geometries" in member:
181
+ return member
182
+ if kind not in _COMPOSITES:
183
+ raise TypeError(f"not a GeoJSON geometry this hook reads: {member!r}")
184
+ _coordinates(member, kind) # holds its coordinates, or TypeError
185
+ return member
186
+ if isinstance(member, _sdk.SdkGeometryCollection):
187
+ return {"type": "GeometryCollection", "geometries": [_member_geojson(m) for m in _members(member.geometries)]}
188
+ if isinstance(member, _sdk.SdkGeometryPoint):
189
+ return {"type": "Point", "coordinates": _coordinates(member, "Point")}
190
+ for kind, (cls, _, _) in _COMPOSITES.items():
191
+ if isinstance(member, cls):
192
+ return {"type": kind, "coordinates": _coordinates(member, kind)}
193
+ raise TypeError(f"not a geometry: {type(member).__name__}")
194
+
195
+
196
+ def _coordinates(member: Any, kind: str) -> Any:
197
+ """The GeoJSON coordinates, as plain lists, of *member*: a geometry of *kind*, or ``TypeError``.
198
+
199
+ *member* is an SDK geometry, whose points the SDK built, or a GeoJSON ``dict`` of that kind this
200
+ hook read: a position only ever comes from an SDK point, never from bare numbers.
201
+ """
202
+ if isinstance(member, dict):
203
+ if member.get("type") != kind or "coordinates" not in member:
204
+ raise TypeError(f"not a GeoJSON {kind}: {member!r}")
205
+ return member["coordinates"]
206
+ if kind == "Point":
207
+ if not isinstance(member, _sdk.SdkGeometryPoint):
208
+ raise TypeError(f"not a point: {type(member).__name__}")
209
+ return [member.longitude, member.latitude]
210
+ cls, attr, member_kind = _COMPOSITES[kind]
211
+ if not isinstance(member, cls):
212
+ raise TypeError(f"not a {kind}: {type(member).__name__}")
213
+ return [_coordinates(m, member_kind) for m in _members(getattr(member, attr))]
214
+
215
+
216
+ # --- capability probes -----------------------------------------------------------------------------
217
+
218
+
219
+ def _sdk_round_trip(value: Any) -> Any:
220
+ """*value* through the SDK's own CBOR codec, both read at call time; raises when either is missing."""
221
+ encode = _sdk.cbor_encode
222
+ decode = _sdk.cbor_decode
223
+ if encode is None or decode is None:
224
+ raise LookupError("the installed SDK has no CBOR codec in surrealdb.data.cbor")
225
+ return decode(encode(value))
226
+
227
+
228
+ @functools.cache
229
+ def sdk_decodes_zero_duration() -> bool:
230
+ """Whether the installed SDK reads a zero duration (computed once per process, no I/O).
231
+
232
+ Round-trips ``CBORTag(TAG_DURATION_COMPACT, [])`` — the server's compact form of ``0ns`` — through
233
+ the SDK's own codec and answers ``True`` only when that gives an SDK ``Duration`` equal to zero.
234
+ ``False`` on any exception, and when the shim found no codec in the installed SDK.
235
+ """
236
+ try:
237
+ value = _sdk_round_trip(_sdk.CBORTag(_sdk.TAG_DURATION_COMPACT, []))
238
+ return bool(isinstance(value, _sdk.SdkDuration) and value.elapsed == 0)
239
+ except Exception: # any failure means "cannot read it"
240
+ return False
241
+
242
+
243
+ @functools.cache
244
+ def sdk_decodes_native_sets() -> bool:
245
+ """Whether the installed SDK reads a native set (CBOR tag 56) holding ``1`` and ``2``; same rules."""
246
+ try:
247
+ return bool(sorted(_sdk_round_trip(_sdk.CBORTag(TAG_SET, [1, 2]))) == [1, 2])
248
+ except Exception:
249
+ return False
250
+
251
+
252
+ @functools.cache
253
+ def sdk_decodes_degenerate_geometries() -> bool:
254
+ """Whether the installed SDK reads a 1-point ``LineString`` and a 3-point ``Polygon`` ring; same rules."""
255
+ point = _sdk.CBORTag(88, [0.0, 0.0])
256
+ line = _sdk.CBORTag(89, [point])
257
+ ring = _sdk.CBORTag(89, [point, _sdk.CBORTag(88, [1.0, 0.0]), point])
258
+ try:
259
+ _sdk_round_trip(line)
260
+ _sdk_round_trip(_sdk.CBORTag(90, [ring]))
261
+ except Exception:
262
+ return False
263
+ return True
264
+
265
+
266
+ def needed() -> bool:
267
+ """Whether the installed SDK fails to decode at least one of the values the hook reads."""
268
+ return not (sdk_decodes_zero_duration() and sdk_decodes_native_sets() and sdk_decodes_degenerate_geometries())
269
+
270
+
271
+ # --- installation ----------------------------------------------------------------------------------
272
+
273
+
274
+ def _with_global(function: Any, name: str, expected: Any, replacement: Any) -> types.FunctionType | None:
275
+ """A copy of *function* — same code object — that reads the module global *name* as *replacement*.
276
+
277
+ ``None`` unless *function* is a plain function whose code reads a global *name* that is
278
+ *expected* in its module: the layout this module knows. The copy's globals are a snapshot of the
279
+ module's, with that one name replaced; the module itself is never changed.
280
+ """
281
+ if not isinstance(function, types.FunctionType) or expected is None:
282
+ return None
283
+ if name not in function.__code__.co_names or function.__globals__.get(name) is not expected:
284
+ return None
285
+ namespace = dict(function.__globals__)
286
+ namespace[name] = replacement
287
+ clone = types.FunctionType(function.__code__, namespace, function.__name__, function.__defaults__, function.__closure__)
288
+ clone.__kwdefaults__ = dict(function.__kwdefaults__) if function.__kwdefaults__ else None
289
+ functools.update_wrapper(clone, function)
290
+ return clone
291
+
292
+
293
+ @functools.cache
294
+ def _hooked_decode() -> Callable[[bytes], Any] | None:
295
+ """The SDK's ``decode``, run with ``read_tag_hook`` as its ``tag_decoder``; ``None`` for another layout."""
296
+ # SDK 3.0 (#205): SDK 2.0.0's ``decode(data)`` is ``loads(data, tag_hook=tag_decoder)`` with a
297
+ # module-level ``tag_decoder``. Re-check against the stable SDK's codec.
298
+ return _with_global(_sdk.cbor_decode, "tag_decoder", _sdk.cbor_tag_decoder, read_tag_hook)
299
+
300
+
301
+ @functools.cache
302
+ def _hooked_methods(cls: type[Any]) -> tuple[tuple[str, types.FunctionType], ...]:
303
+ """*cls*'s methods that decode a response, each as a copy whose ``decode`` is the hooked one."""
304
+ decode = _hooked_decode()
305
+ if decode is None:
306
+ return ()
307
+ methods: list[tuple[str, types.FunctionType]] = []
308
+ for name in _DECODING_METHODS:
309
+ clone = _with_global(getattr(cls, name, None), "decode", _sdk.cbor_decode, decode)
310
+ if clone is not None:
311
+ methods.append((name, clone))
312
+ return tuple(methods)
313
+
314
+
315
+ def available() -> bool:
316
+ """Whether the installed SDK has the layout the hook knows, for its three async connection kinds."""
317
+ kinds = (_sdk.SdkAsyncWsConnection, _sdk.SdkAsyncHttpConnection, _sdk.SdkAsyncEmbeddedConnection)
318
+ return all(cls is not None and bool(_hooked_methods(cls)) for cls in kinds)
319
+
320
+
321
+ def active() -> bool:
322
+ """Whether the clients the ORM opens get the hook: the SDK needs it and has the known layout."""
323
+ return needed() and available()
324
+
325
+
326
+ def install(client: Any) -> bool:
327
+ """Make *client* — one the ORM has just built, not yet connected — decode responses with the hook.
328
+
329
+ Sets the client's decoding method(s) on the instance (see the module docstring). ``True`` when
330
+ installed; ``False``, leaving *client* as it is, when the hook is not ``active()`` or *client*'s
331
+ class has no method this module knows.
332
+ """
333
+ if not active():
334
+ return False
335
+ methods = _hooked_methods(client.__class__)
336
+ for name, function in methods:
337
+ setattr(client, name, types.MethodType(function, client))
338
+ return bool(methods)
@@ -18,8 +18,8 @@ to a list, sorted when its items can be; an ORM or SDK ``Range`` to an SDK ``Ran
18
18
  sides are the protocol's CBOR null; and a ``Decimal`` in exponent form to its fixed-point text. It
19
19
  refuses with a plain ``ValueError``, before anything is sent: an ``int`` outside signed 64-bit, a
20
20
  ``Decimal`` whose rounded integer part exceeds ``2**96 - 1``, a negative or too long duration, a
21
- zero duration while the installed SDK cannot read one back, and a range side that is neither a
22
- bound nor an open side. Anything else comes back unchanged: the SDK decides, as in v0.22.2.
21
+ zero duration while nothing reads one back (``reads_zero_duration()``), and a range side that is
22
+ neither a bound nor an open side. Anything else comes back unchanged: the SDK decides, as in v0.22.2.
23
23
 
24
24
  Geometries (v0.24.0) take two rows. An ORM geometry (``surreal_orm_lite.geo``) becomes the equal
25
25
  SDK geometry — built without any SDK constructor — and then takes the SDK row. An SDK geometry
@@ -35,18 +35,17 @@ closed, and a member of the wrong kind.
35
35
 
36
36
  The ORM calls it through this module (``_encoding.encode(x)``), never by a name imported from it.
37
37
 
38
- ``sdk_decodes_zero_duration()`` is the one local SDK capability the rich field types depend on:
39
- SDK 2.0.0 cannot decode a zero duration (CBOR tag 14 with an empty compact form raises
40
- ``IndexError``), so the ORM refuses to send one — in a bound parameter or a live-query literal —
41
- while the probe answers ``False``. A fixed SDK lifts the refusal by itself. Call it through this
42
- module (``encoding.sdk_decodes_zero_duration()``) so a test can replace it.
38
+ ``reads_zero_duration()`` says whether a zero duration the ORM sends can be read back. SDK 2.0.0
39
+ cannot decode one (CBOR tag 14 with an empty compact form raises ``IndexError``), but since #235 the
40
+ clients the ORM opens read it through the read hook (``decoding.py``). The ORM refuses to send a zero
41
+ duration — in a bound parameter or a live-query literal — only when neither the SDK nor the hook
42
+ reads it. Call it through this module (``encoding.reads_zero_duration()``) so a test can replace it.
43
43
  """
44
44
 
45
45
  from __future__ import annotations
46
46
 
47
47
  import copy
48
48
  import decimal
49
- import functools
50
49
  import itertools
51
50
  from collections.abc import Callable
52
51
  from datetime import UTC, date, datetime, timedelta
@@ -54,10 +53,10 @@ from decimal import ROUND_DOWN, ROUND_HALF_UP, Decimal
54
53
  from typing import Any, Final, cast
55
54
  from uuid import UUID
56
55
 
57
- from . import _sdk, geo
56
+ from . import _sdk, decoding, geo
58
57
  from .types import Duration, Range, _is_open_side, _nanoseconds
59
58
 
60
- __all__ = ["encode", "sdk_decodes_zero_duration"]
59
+ __all__ = ["encode", "reads_zero_duration"]
61
60
 
62
61
  # SurrealDB integers are signed 64-bit: a larger one would be stored wrapped, or refused.
63
62
  INT64_MIN: Final = -(2**63)
@@ -195,7 +194,8 @@ def _encode_duration(value: timedelta | Duration | _sdk.SdkDuration) -> Any:
195
194
  seconds, nanoseconds = divmod(ns, _NS_PER_SECOND)
196
195
  if seconds >= DURATION_SECONDS_LIMIT:
197
196
  raise ValueError(f"Cannot send {value!r}: a SurrealDB duration holds at most 2**64 - 1 seconds.")
198
- if ns == 0 and not sdk_decodes_zero_duration():
197
+ # SDK 3.0 (#205): goes with ``reads_zero_duration()`` once the SDK reads a zero duration itself.
198
+ if ns == 0 and not reads_zero_duration():
199
199
  raise ValueError(
200
200
  f"Cannot send a zero duration ({value!r}): the installed surrealdb SDK cannot read a zero "
201
201
  "duration back. Store None instead, or filter with __gte=Duration(1)."
@@ -423,21 +423,13 @@ def _encode_sequence(value: list[Any] | tuple[Any, ...]) -> Any:
423
423
  return tuple(out) if isinstance(value, tuple) else out
424
424
 
425
425
 
426
- @functools.cache
427
- def sdk_decodes_zero_duration() -> bool:
428
- """Whether the installed SDK reads a zero duration back (computed once per process, no I/O).
426
+ def reads_zero_duration() -> bool:
427
+ """Whether a zero duration the ORM sends can be read back by the clients the ORM opens.
429
428
 
430
- Round-trips ``CBORTag(TAG_DURATION_COMPACT, [])`` — the server's compact form of ``0ns`` —
431
- through the SDK's own CBOR codec and answers ``True`` only when that gives an SDK ``Duration``
432
- equal to zero. ``False`` on any exception, and when the shim found no codec in the installed SDK
433
- (``_sdk.cbor_encode``/``_sdk.cbor_decode`` is ``None``); both are read at call time.
429
+ ``True`` when the installed SDK decodes one, or when the read hook is installed on those clients
430
+ (``decoding.active()``, SDK 2.0.0). ``False`` only for an SDK that decodes no zero duration and
431
+ whose layout the hook does not know: the ORM then refuses to send one.
434
432
  """
435
- encode = _sdk.cbor_encode
436
- decode = _sdk.cbor_decode
437
- if encode is None or decode is None:
438
- return False
439
- try:
440
- value = decode(encode(_sdk.CBORTag(_sdk.TAG_DURATION_COMPACT, [])))
441
- return bool(isinstance(value, _sdk.SdkDuration) and value.elapsed == 0)
442
- except Exception: # any failure means "cannot read it back"
443
- return False
433
+ # SDK 3.0 (#205): the SDK reads a zero duration itself (3.0.0b10 does); this is then
434
+ # ``decoding.sdk_decodes_zero_duration()`` alone, and the refusals it guards can go.
435
+ return decoding.sdk_decodes_zero_duration() or decoding.active()
@@ -183,6 +183,8 @@ def _check_ring(ring: GeometryLine, ring_type: str) -> None:
183
183
  # --- the classes ----------------------------------------------------------------------------------
184
184
 
185
185
 
186
+ # SDK 3.0 (#205): keep these classes. The SDK's geometry dataclasses have no Pydantic schema in
187
+ # 3.0.0b10 either, and ``model_dump()`` flattens them into dicts; re-check at the stable release.
186
188
  class Geometry:
187
189
  """The abstract base of the seven ORM geometry classes (v0.24.0).
188
190
 
@@ -923,6 +925,8 @@ def _coordinates_text(value: Any, kind: str) -> str:
923
925
  return f"[{', '.join(parts)}]"
924
926
 
925
927
 
928
+ # SDK 3.0 (#205): keep this rendering, never the SDK's. SDK 3.0's ``GeometryCollection.__str__`` writes
929
+ # point members as ``(x, y)``, which SurrealDB 3.x reads as a plain object (surrealdb/surrealdb.py#403).
926
930
  def _geometry_text(value: Any) -> str:
927
931
  """The SurrealQL text of an ORM or SDK geometry (and of their members): its GeoJSON **object** form.
928
932
 
@@ -22,8 +22,8 @@ neither has a decimal or non-finite coordinate. That form is also a geometry's `
22
22
 
23
23
  A ``Range`` also has a text form, ``_range_text``: what its ``str()`` and its JSON write and a
24
24
  ``Range`` field reads back. It never reaches the server, so it writes every bound value exactly and
25
- drops the refusals that only protect a live filter: a zero duration is ``0ns`` whatever the SDK
26
- decodes, a ``Decimal`` keeps all its digits, an ``int`` may exceed 64 bits and a string may hold
25
+ drops the refusals that only protect a live filter: a zero duration is ``0ns`` whatever the ORM
26
+ reads back, a ``Decimal`` keeps all its digits, an ``int`` may exceed 64 bits and a string may hold
27
27
  ``\\x00``.
28
28
 
29
29
  Two choices worth knowing:
@@ -192,8 +192,8 @@ def _decimal_text(value: Decimal) -> str:
192
192
  def _duration(value: timedelta | Duration | SdkDuration, *, text: bool = False) -> str:
193
193
  """Every unit, largest first, from the exact nanoseconds: ``1h30m1ns`` (ASCII ``us``).
194
194
 
195
- With ``text``, a zero duration is ``0ns`` whatever the installed SDK decodes: the range text form
196
- never reaches the server.
195
+ With ``text``, a zero duration is ``0ns`` whatever the ORM reads back: the range text form never
196
+ reaches the server.
197
197
  """
198
198
  try:
199
199
  nanoseconds = _nanoseconds(value)
@@ -203,7 +203,8 @@ def _duration(value: timedelta | Duration | SdkDuration, *, text: bool = False)
203
203
  raise TypeError(f"Cannot inline a negative duration ({value!r}): SurrealDB durations are never negative.")
204
204
  if nanoseconds // 10**9 >= _DURATION_SECONDS_LIMIT:
205
205
  raise TypeError(f"Cannot inline {value!r}: a SurrealDB duration holds at most 2**64 - 1 seconds.")
206
- if nanoseconds == 0 and not text and not _encoding.sdk_decodes_zero_duration():
206
+ # SDK 3.0 (#205): goes with ``encoding.reads_zero_duration()`` once the SDK reads a zero duration itself.
207
+ if nanoseconds == 0 and not text and not _encoding.reads_zero_duration():
207
208
  raise TypeError(
208
209
  f"Cannot inline a zero duration ({value!r}): the installed surrealdb SDK cannot read a zero "
209
210
  "duration back. Filter with __gte=Duration(1) instead."
@@ -267,7 +268,7 @@ def _range_text(value: Range[Any] | SdkRange) -> str:
267
268
 
268
269
  Exactly the grammar ``types._parse_range_text`` reads, so the text reads back to an equal
269
270
  ``Range``. Unlike the live-filter literal it never reaches the server, so it keeps every bound
270
- value whole: a zero duration is ``0ns`` whatever the installed SDK decodes, a ``Decimal`` is
271
+ value whole: a zero duration is ``0ns`` whatever the ORM reads back, a ``Decimal`` is
271
272
  written in full (no 28-fractional-digit or 96-bit limit), an ``int`` may exceed 64 bits and a
272
273
  string may hold ``\\x00``. Otherwise the same text as ``to_surql_literal``.
273
274
 
@@ -281,6 +282,8 @@ def _range_text(value: Range[Any] | SdkRange) -> str:
281
282
  return rendered
282
283
 
283
284
 
285
+ # SDK 3.0 (#205): keep ``geo._geometry_text`` for live-query literals, never the SDK's ``str()``
286
+ # (surrealdb/surrealdb.py#403: its ``GeometryCollection`` writes point members as ``(x, y)``).
284
287
  def _geometry(value: Any) -> str:
285
288
  """An ORM or SDK geometry's GeoJSON object literal, from ``geo._geometry_text`` (v0.24.0).
286
289
 
@@ -305,7 +308,8 @@ def to_surql_literal(value: Any) -> str:
305
308
  :raises TypeError: for a type with no verified literal form, a string containing ``\\x00``,
306
309
  an ``int`` outside signed 64-bit, a ``Decimal`` that is non-finite or beyond SurrealDB's
307
310
  28 fractional digits / 96-bit mantissa, a non-``str`` dict key, a negative duration, one
308
- of 2**64 seconds or more, a zero duration while the installed SDK cannot read one back,
311
+ of 2**64 seconds or more, a zero duration while nothing reads one back
312
+ (``encoding.reads_zero_duration()``),
309
313
  or a range whose side is not a bound or whose bound value is outside the closed set
310
314
  (``int`` but not ``bool``, finite ``float``, ``Decimal``, ``str``, ``datetime``, ``date``,
311
315
  ``timedelta``, ``Duration``), an SDK geometry SurrealDB refuses, and a geometry with a