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.
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/CHANGELOG.md +56 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/PKG-INFO +72 -33
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/README.md +71 -32
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/pyproject.toml +1 -1
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/_sdk.py +25 -1
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/connection_manager.py +9 -0
- surreal_orm_lite-0.24.3/src/surreal_orm_lite/decoding.py +338 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/encoding.py +19 -27
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/geo.py +4 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/surql_literal.py +11 -7
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/.gitignore +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/LICENSE +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/Makefile +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/model_base.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/query_set.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/types.py +0 -0
- {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.
|
|
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.
|
|
2203
|
-
|
|
2204
|
-
SDK
|
|
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
|
|
2222
|
-
|
|
|
2223
|
-
| A negative duration (a `timedelta`, the SDK's `Duration`)
|
|
2224
|
-
| A duration of `2**64` seconds or more
|
|
2225
|
-
| A zero duration,
|
|
2226
|
-
| A finite `Decimal` whose integer part, rounded, exceeds `2**96 - 1`
|
|
2227
|
-
| An `int` outside the signed 64-bit range
|
|
2228
|
-
| A `Range` side that is neither `BoundIncluded`/`BoundExcluded` nor an open side
|
|
2229
|
-
| `id__in=Range(…)`, `id__not_in=Range(…)`, or the same on an edge's `in`/`out`
|
|
2230
|
-
| `atomic_increment(field, <a duration>)`
|
|
2231
|
-
| In a live filter, a
|
|
2232
|
-
| A `Duration` or `Range` field given a value it does not accept
|
|
2233
|
-
|
|
2234
|
-
|
|
2235
|
-
|
|
2236
|
-
|
|
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
|
|
2265
|
-
|
|
2266
|
-
|
|
2267
|
-
|
|
2268
|
-
|
|
2269
|
-
|
|
2270
|
-
|
|
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
|
|
2613
|
-
|
|
2614
|
-
|
|
2615
|
-
|
|
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
|
|
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.
|
|
2152
|
-
|
|
2153
|
-
SDK
|
|
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
|
|
2171
|
-
|
|
|
2172
|
-
| A negative duration (a `timedelta`, the SDK's `Duration`)
|
|
2173
|
-
| A duration of `2**64` seconds or more
|
|
2174
|
-
| A zero duration,
|
|
2175
|
-
| A finite `Decimal` whose integer part, rounded, exceeds `2**96 - 1`
|
|
2176
|
-
| An `int` outside the signed 64-bit range
|
|
2177
|
-
| A `Range` side that is neither `BoundIncluded`/`BoundExcluded` nor an open side
|
|
2178
|
-
| `id__in=Range(…)`, `id__not_in=Range(…)`, or the same on an edge's `in`/`out`
|
|
2179
|
-
| `atomic_increment(field, <a duration>)`
|
|
2180
|
-
| In a live filter, a
|
|
2181
|
-
| A `Duration` or `Range` field given a value it does not accept
|
|
2182
|
-
|
|
2183
|
-
|
|
2184
|
-
|
|
2185
|
-
|
|
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
|
|
2214
|
-
|
|
2215
|
-
|
|
2216
|
-
|
|
2217
|
-
|
|
2218
|
-
|
|
2219
|
-
|
|
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
|
|
2562
|
-
|
|
2563
|
-
|
|
2564
|
-
|
|
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
|
|
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 |
|
|
@@ -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
|
-
#
|
|
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",
|
{surreal_orm_lite-0.24.2 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/connection_manager.py
RENAMED
|
@@ -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
|
|
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
|
-
``
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
module (``encoding.
|
|
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", "
|
|
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
|
-
|
|
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
|
-
|
|
427
|
-
|
|
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
|
-
|
|
431
|
-
|
|
432
|
-
|
|
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
|
-
|
|
436
|
-
|
|
437
|
-
|
|
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
|
|
26
|
-
|
|
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
|
|
196
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|