surreal-orm-lite 0.30.3__tar.gz → 0.30.7__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.30.3 → surreal_orm_lite-0.30.7}/CHANGELOG.md +121 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/PKG-INFO +71 -32
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/README.md +70 -31
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/pyproject.toml +1 -1
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/connection_manager.py +43 -2
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/edge.py +6 -4
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/model_base.py +170 -138
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/model_generator.py +54 -50
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/transaction.py +11 -4
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/utils.py +142 -2
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/.gitignore +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/LICENSE +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/Makefile +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/cache.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/define_parser.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/introspection.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/query_set.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/routing.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/schema_state.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/subquery.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/types.py +0 -0
|
@@ -5,6 +5,127 @@ 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.30.7] - 2026-10-19
|
|
9
|
+
|
|
10
|
+
An instance stays in step with its stored row (#261): `save()` applies the whole row the server
|
|
11
|
+
returns, every call that applies a returned row validates it as a read does, and `update()` keeps
|
|
12
|
+
the stored nanoseconds of a datetime it did not change, so a record with a top-level `READONLY`
|
|
13
|
+
datetime can be updated. No new public API, but what an instance holds after a write changes for
|
|
14
|
+
every model: read **Changed** before upgrading.
|
|
15
|
+
|
|
16
|
+
### Fixed
|
|
17
|
+
|
|
18
|
+
- **`update()` after `save()` or `get()` on a `READONLY` top-level `datetime`** is no longer
|
|
19
|
+
refused by the server (#261). SurrealDB stores nanoseconds and the SDK reads microseconds, so
|
|
20
|
+
`update()` wrote back a changed value. See item 5 under Changed.
|
|
21
|
+
- **Sub-fields a `DEFAULT` fills** (`prefs.at DEFAULT time::now()`) are on the instance right after
|
|
22
|
+
`save()` (explicit id, auto id, interactive transaction), so a following `update()` no longer
|
|
23
|
+
sends them as `NONE`, which the server refused for a required sub-field and which erased an
|
|
24
|
+
optional one (#261).
|
|
25
|
+
- **`tuple` and `set` fields** hold their declared type after `save()`, `upsert()`, `merge()` and
|
|
26
|
+
`patch()`, as after `get()` (item 2 under Changed), not the SDK's `list` (#261).
|
|
27
|
+
- **A returned column named like a Pydantic `@computed_field` or a model method** (`json`) no
|
|
28
|
+
longer replaces that attribute (#261). In 0.30.1, with a `@computed_field` (which `model_dump()`
|
|
29
|
+
writes), auto-id `save()`, `refresh()` and `merge()` raised `AttributeError` after the record was
|
|
30
|
+
stored.
|
|
31
|
+
- **`generate_models_from_db()`**: generated classes no longer carry the note about `DEFAULT`
|
|
32
|
+
sub-fields, and the `READONLY` `update()` note remains only for a datetime below the top level
|
|
33
|
+
or a top-level one past the 32nd (#261).
|
|
34
|
+
- **Buffered transactions**: a statement's parameters are renamed in one pass (#261). In 0.30.1,
|
|
35
|
+
`$a` next to a variable named `t0_a` was renamed twice and bound to `t0_a`'s value, and a
|
|
36
|
+
statement with thousands of bound values was slow to queue.
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
# DEFINE FIELD created ON event TYPE datetime DEFAULT time::now() READONLY;
|
|
40
|
+
event = await Event.objects().get("launch") # created read to the microsecond
|
|
41
|
+
event.title = "Launch day"
|
|
42
|
+
await event.update() # was refused ("readonly"); the stored created keeps its nanoseconds
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Changed
|
|
46
|
+
|
|
47
|
+
Each item was measured against 0.30.1 on SurrealDB 3.3.4, 2.7.0 and the embedded engine
|
|
48
|
+
(`mem://`) and holds on all three unless stated.
|
|
49
|
+
|
|
50
|
+
1. **Explicit-id `save()`, an edge's `save()` and interactive `save(tx=)` apply the whole stored
|
|
51
|
+
row** (#261). In 0.30.1, explicit-id `save()` and interactive `save(tx=)` read back only the
|
|
52
|
+
`server_fields` and computed fields, and an edge's `save()` (either id) only its `id` and
|
|
53
|
+
`server_fields`: the instance kept the values passed in. Now a naive `datetime` becomes the
|
|
54
|
+
aware UTC `datetime` a read gives (compare it with aware values), a sub-model field holds a new
|
|
55
|
+
instance (not the object passed in), and values a `VALUE` clause rewrote or the server coerced
|
|
56
|
+
replace the ones sent (`VALUE string::lowercase($value)` turns `"AbC"` into `"abc"` on the
|
|
57
|
+
instance). Interactive transactions exist on SurrealDB 3.x over WebSocket only; a buffered
|
|
58
|
+
transaction (HTTP, 2.x, the embedded engine) still leaves the instance as it was.
|
|
59
|
+
2. **Every call that applies the returned row validates it like a read** (#261): `save()` with
|
|
60
|
+
either id, an edge's `save()`, `refresh()`, `merge()` (default `refresh=True`), `upsert()`,
|
|
61
|
+
`patch()` and the `atomic_*` helpers. An enum field holds the enum member, not the raw
|
|
62
|
+
`str`/`int` (a `str` or `int` enum still compares equal to its value, a plain `Enum` member no
|
|
63
|
+
longer does); `tuple`, `set`, `date` and `Range` fields hold their declared type instead of the
|
|
64
|
+
SDK's `list`, midnight `datetime` and `Range`; a `float` field stored in a `decimal` column holds
|
|
65
|
+
a `float`, not a `Decimal`; a `list[Duration]` holds the ORM's `Duration`s, not the SDK's. In
|
|
66
|
+
0.30.1, `refresh()`, `merge()`, auto-id `save()`, `upsert()`, `patch()` and `atomic_*` kept the
|
|
67
|
+
SDK's values for these fields (explicit-id `save()` kept the values passed in).
|
|
68
|
+
3. **The model's validators run on the returned row for every model** (#261). Field and model
|
|
69
|
+
validators (any mode) and `model_post_init` run once per call listed in item 2, on a validated
|
|
70
|
+
copy of the row, and their result is applied to every field. In 0.30.1 they ran only when the
|
|
71
|
+
row held a sub-model field, a nested `timedelta` field or a geometry field stored as a GeoJSON
|
|
72
|
+
object, and their result reached only those fields; otherwise they did not run at all. A
|
|
73
|
+
validator that is not idempotent is applied again, as on `get()`, and a following `update()`
|
|
74
|
+
writes that value back: with `label` validated as `v + "!"`, `Model(id="a", label="x")`,
|
|
75
|
+
`save()` then `update()` stored `x!` in 0.30.1 and stores `x!!` now; `merge()` then `update()`
|
|
76
|
+
gives the same difference.
|
|
77
|
+
4. **Under `extra="allow"`, the returned row's undeclared columns go to `model_extra`** after the
|
|
78
|
+
calls listed in item 2, where a read puts them (0.30.1 dropped them), and `merge(refresh=False)`
|
|
79
|
+
with an undeclared key updates `model_extra` (#261).
|
|
80
|
+
5. **`update()` and `upsert()` keep the stored nanoseconds of a datetime written back unchanged**
|
|
81
|
+
(one that still floors to the stored value at the microsecond), for every top-level datetime up
|
|
82
|
+
to 32 per record, so a record whose `READONLY` datetimes are top-level fields can be updated
|
|
83
|
+
after `get()` or `save()` (#261). Below the top level (a sub-model, a `list`, a `tuple`, a set)
|
|
84
|
+
this depends on the data: change such a record with `merge()`.
|
|
85
|
+
|
|
86
|
+
### Notes
|
|
87
|
+
|
|
88
|
+
- SurrealDB 2.x still refuses `update()` and `upsert()` of an existing record that has a field
|
|
89
|
+
with a non-optional `TYPE` and a `VALUE` clause the model does not write, such as a generated
|
|
90
|
+
`updated: Computed[datetime]` (#267): change such a record with `merge()` there. 0.30.1 behaved
|
|
91
|
+
the same way before this release; SurrealDB 3.x recomputes the field. The v0.30.0 example
|
|
92
|
+
notebook changes its generated `NbPerson` with `merge()` for that reason.
|
|
93
|
+
- The README's "After a write that returns the row", "Precision and `Decimal`" and "What the
|
|
94
|
+
generator does not do" sections, and a new row of the 2.x vs 3.x behaviour table, describe these
|
|
95
|
+
changes.
|
|
96
|
+
- Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine, plus
|
|
97
|
+
3.1.5 for backward compatibility.
|
|
98
|
+
|
|
99
|
+
## [0.30.5] - 2026-10-19
|
|
100
|
+
|
|
101
|
+
`SurrealDBConnectionManager.kill()` no longer reports a connection lost under the request as a
|
|
102
|
+
KILL the server refused. No new public API.
|
|
103
|
+
|
|
104
|
+
### Fixed
|
|
105
|
+
|
|
106
|
+
- **A `kill()` caught by a dropped connection returns normally** (#266). A KILL sent as the
|
|
107
|
+
WebSocket went down, before the SDK had noticed the drop, failed inside the SDK (its receive loop
|
|
108
|
+
clears the pending requests, so the request's own cleanup raised a `KeyError`), and `kill()`
|
|
109
|
+
turned that into `SurrealDbError: Failed to kill live query …` although the server never
|
|
110
|
+
answered. `kill()` now asks the client: when its connection dropped under the request (the SDK's
|
|
111
|
+
receive task has ended, after a wait of at most one second when the error came from the
|
|
112
|
+
transport), it closes the dead socket and records the live query as ended, as it already did for
|
|
113
|
+
a client found dead before the call, and the stream's readers end. A refusal from a live server
|
|
114
|
+
still raises `SurrealDbError` and keeps the uuid alive, so a retry can re-attach to it.
|
|
115
|
+
- **A cancelled `kill()` raises `asyncio.CancelledError`** (#266), even when the SDK reports the
|
|
116
|
+
cancelled request as an ordinary error; it used to become `SurrealDbError`. The readers are
|
|
117
|
+
released either way.
|
|
118
|
+
- **`kill()` releases the stream's readers before it closes a dead socket** (#266), so an
|
|
119
|
+
automatic resubscribe woken by the same drop cannot reopen a subscription that is being stopped.
|
|
120
|
+
The window was open where closing the socket yields to the event loop, as on Python 3.11.
|
|
121
|
+
|
|
122
|
+
### Notes
|
|
123
|
+
|
|
124
|
+
- Docs: the README live-queries section says that a kill caught by a dropped connection is not a
|
|
125
|
+
refusal.
|
|
126
|
+
- Same behaviour on SurrealDB 2.x and 3.x (live queries are WebSocket-only). Server pins
|
|
127
|
+
unchanged: tested against SurrealDB 3.3.4 and 2.7.0, plus 3.1.5 for backward compatibility.
|
|
128
|
+
|
|
8
129
|
## [0.30.3] - 2026-10-19
|
|
9
130
|
|
|
10
131
|
A statement that fails inside `transaction()` fails the whole transaction on every strategy: a
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: surreal-orm-lite
|
|
3
|
-
Version: 0.30.
|
|
3
|
+
Version: 0.30.7
|
|
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
|
|
@@ -1763,6 +1763,8 @@ exactly what ends a stream.
|
|
|
1763
1763
|
- **A failed `kill()` releases the readers but keeps the uuid alive.** When the server refuses
|
|
1764
1764
|
the kill for any reason other than an unknown uuid, the error is raised, the readers are woken,
|
|
1765
1765
|
and the subscription is still running — so you can subscribe to it again or retry `stop()`.
|
|
1766
|
+
A kill caught by a dropped connection is not a refusal: the subscription died with the socket,
|
|
1767
|
+
so `kill()` records it as ended and returns normally.
|
|
1766
1768
|
- **The buffer is unbounded.** A stream you stop reading but never kill keeps accumulating
|
|
1767
1769
|
notifications. Use the `async with` forms, or pair every uuid you start with a `kill()`.
|
|
1768
1770
|
|
|
@@ -2245,8 +2247,12 @@ reads, a `timedelta` is converted from the SDK's duration at any depth too: a to
|
|
|
2245
2247
|
`list[timedelta]`, `dict[str, timedelta]`, `timedelta | str` or a sub-model's `timedelta` field
|
|
2246
2248
|
all read a `timedelta`, floored to the microsecond (declare `Duration` to keep the nanoseconds).
|
|
2247
2249
|
Your validators (any mode) and `model_post_init` still apply once to the value read, even when they
|
|
2248
|
-
change it in place. A naive `datetime`
|
|
2249
|
-
|
|
2250
|
+
change it in place. A naive `datetime` is written as UTC and read back as an aware UTC `datetime`.
|
|
2251
|
+
The instance keeps it naive until a call applies the row the server returns (see
|
|
2252
|
+
[After a write that returns the row](#after-a-write-that-returns-the-row)): after `save()` (since
|
|
2253
|
+
#261 with an explicit id too), `refresh()`, `merge()` (default `refresh=True`), `upsert()`,
|
|
2254
|
+
`patch()` or an `atomic_*` helper, the field holds that aware UTC `datetime`, so compare it with
|
|
2255
|
+
aware values. `update()`, and `save(tx=)` in a buffered transaction, leave it naive.
|
|
2250
2256
|
|
|
2251
2257
|
#### `Duration`
|
|
2252
2258
|
|
|
@@ -2369,7 +2375,23 @@ both lines.
|
|
|
2369
2375
|
#### Precision and `Decimal`
|
|
2370
2376
|
|
|
2371
2377
|
- `datetime`: to the microsecond. The SDK truncates the server's nanoseconds, so a stored
|
|
2372
|
-
`d'2026-01-02T03:04:05.123456789Z'` reads `…05.123456`.
|
|
2378
|
+
`d'2026-01-02T03:04:05.123456789Z'` reads `…05.123456`. `update()` and `upsert()` rewrite the
|
|
2379
|
+
whole record, but a `datetime` you did not change (it still floors to the stored value) keeps
|
|
2380
|
+
the stored nanoseconds, on both lines and the embedded engine: a record whose `READONLY`
|
|
2381
|
+
datetimes are top-level fields can be updated after `get()` or `save()`, even when they hold
|
|
2382
|
+
nanoseconds ([#261](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/261)). A
|
|
2383
|
+
datetime you changed is written as you set it, and a `READONLY` field still refuses it. So that
|
|
2384
|
+
the statement stays small whatever the data, only the top-level datetimes are sure to be kept,
|
|
2385
|
+
up to 32 per record. Below the top level (in a sub-model, a `list` or a `tuple`, down to three
|
|
2386
|
+
levels) a datetime is kept only while the values rebuilt to reach it fit in what the fields
|
|
2387
|
+
before it left of those 32, so it depends on the data: an `update()` that passes in a test can
|
|
2388
|
+
fail once a list of timestamped items before the sub-model grows. A datetime not kept, and one
|
|
2389
|
+
in a set (its items have no position to match a stored value by), is written as sent: a
|
|
2390
|
+
`READONLY` field holding one may refuse `update()`, so change such a record with `merge()`.
|
|
2391
|
+
SurrealDB 2.x also refuses, for now, `update()` and `upsert()` of an existing record that has
|
|
2392
|
+
a field with a non-optional `TYPE` and a `VALUE` clause the model does not write (a `Computed`
|
|
2393
|
+
field, such as a generated `updated: Computed[datetime]`): change it with `merge()` there
|
|
2394
|
+
([#267](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/267)).
|
|
2373
2395
|
- `timedelta`: floored to the microsecond on read (`1h30m1ns` reads `timedelta(seconds=5400)`).
|
|
2374
2396
|
- `Duration`: exact, to the nanosecond.
|
|
2375
2397
|
- `Decimal`: a value whose `str()` writes no exponent is sent as before. A value written with an
|
|
@@ -2432,22 +2454,40 @@ await sub.merge(trial=sub.trial + timedelta(days=7)) #
|
|
|
2432
2454
|
|
|
2433
2455
|
#### After a write that returns the row
|
|
2434
2456
|
|
|
2435
|
-
`save()` without an id, `refresh()`, `merge()`, `upsert()`, `patch()` and
|
|
2436
|
-
apply the row the server returns to the instance.
|
|
2437
|
-
|
|
2438
|
-
|
|
2439
|
-
|
|
2440
|
-
|
|
2441
|
-
|
|
2442
|
-
|
|
2443
|
-
|
|
2444
|
-
|
|
2445
|
-
|
|
2446
|
-
|
|
2447
|
-
|
|
2448
|
-
`
|
|
2449
|
-
|
|
2450
|
-
|
|
2457
|
+
`save()` (with or without an id, an edge's too), `refresh()`, `merge()`, `upsert()`, `patch()` and
|
|
2458
|
+
the `atomic_*` helpers apply the row the server returns to the instance. After `save()` the
|
|
2459
|
+
instance therefore holds what the record holds: the `server_fields` and computed fields, the
|
|
2460
|
+
sub-fields a `DEFAULT` filled (`prefs.at DEFAULT time::now()`), and the values the server coerced
|
|
2461
|
+
or rewrote (`VALUE string::lowercase($value)`), so a following `update()` writes them back
|
|
2462
|
+
unchanged ([#261](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/261)). An id you
|
|
2463
|
+
gave stays as you gave it; an auto id is the server's `RecordID`. A buffered transaction (HTTP,
|
|
2464
|
+
SurrealDB 2.x, the embedded engine) returns no row before commit: there `save(tx=)` leaves the
|
|
2465
|
+
instance as it was, and `refresh()` after the commit reads the row.
|
|
2466
|
+
|
|
2467
|
+
The top-level `timedelta`, `Duration` and geometry fields (since v0.24.0, see
|
|
2468
|
+
[section 25](#25-geospatial-fields)) are converted on the way, and every other field gets the
|
|
2469
|
+
value a read gives (#261; before, only a field holding a sub-model, a geometry or a nested
|
|
2470
|
+
`timedelta` did): the row goes through the model's validation, the model's own validators
|
|
2471
|
+
included. A sub-model field holds its model instance, not the row's `dict`, with the ORM's
|
|
2472
|
+
durations, `timedelta`s, ranges and geometries inside; an enum field holds the enum, not its `str`
|
|
2473
|
+
or `int`; a `tuple`, set, `date` or `Range` field holds its declared type, not the SDK's `list`,
|
|
2474
|
+
midnight `datetime` or `Range`; a `float` field stored in a `decimal` column holds a `float`, not a
|
|
2475
|
+
`Decimal`; a `list[Duration]` holds the ORM's durations. When the row as a whole does not validate,
|
|
2476
|
+
each field is validated on its own, except one that the model's own validators could reshape (a
|
|
2477
|
+
`field_validator` on that field, a `model_validator`, a `model_post_init`): that one, like a value
|
|
2478
|
+
that does not validate, is applied as received, so these calls never fail on it. The `id` keeps
|
|
2479
|
+
the server's `RecordID`. A column the model does not declare goes where a read puts it: as the SDK
|
|
2480
|
+
reads it into `model_extra` under `extra="allow"`, nowhere otherwise. So a column holding a Pydantic
|
|
2481
|
+
`@computed_field` (`model_dump()` writes it) or named like a method (`json`) never replaces that
|
|
2482
|
+
attribute.
|
|
2483
|
+
|
|
2484
|
+
Writing such an instance back is safe, sub-models included: a following `update()` replaces the
|
|
2485
|
+
record with these values, as after `get()`. So a `float` field stored in a `decimal` column writes
|
|
2486
|
+
the float's rounding (`0.12345678901234567890` becomes `0.1234567890123457`: declare `Decimal` to
|
|
2487
|
+
keep every digit), and under `extra="allow"` the columns in `model_extra` are written back, not
|
|
2488
|
+
removed. An enum declared `(str, Enum)` or `(int, Enum)` holds the member, as after `get()`: it
|
|
2489
|
+
compares equal to its value, but `str()` and f-strings give `Color.RED`, not `red` (a `StrEnum` or
|
|
2490
|
+
an `IntEnum` gives the value), so use `.value` to build a key, a URL or a log line from it.
|
|
2451
2491
|
|
|
2452
2492
|
#### Values the SDK cannot read
|
|
2453
2493
|
|
|
@@ -2493,9 +2533,8 @@ refused value raises `ValueError` before anything is sent.
|
|
|
2493
2533
|
|
|
2494
2534
|
Plain `datetime`, `Decimal` and `UUID` annotations work as they do there. The full ORM has no
|
|
2495
2535
|
`timedelta` or `Range` fields and its `Duration` is a string: `timedelta`, `Duration` and
|
|
2496
|
-
`Range[T]` fields are lite additions. The full ORM also validates the rows its writes return;
|
|
2497
|
-
|
|
2498
|
-
top-level durations, while top-level `date`, `set` and `Range` fields keep the SDK's value (see
|
|
2536
|
+
`Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; so
|
|
2537
|
+
does lite, every field but the `id` since #261, with top-level durations converted (see
|
|
2499
2538
|
[After a write that returns the row](#after-a-write-that-returns-the-row)).
|
|
2500
2539
|
|
|
2501
2540
|
### 25. Geospatial fields
|
|
@@ -4307,14 +4346,13 @@ class Person(BaseSurrealModel):
|
|
|
4307
4346
|
object-literal kind (`{ a: int }`) stays a `dict[str, Any]`.
|
|
4308
4347
|
- `ASSERT`, `PERMISSIONS`, `REFERENCE` (the field is a `RecordID`) and field comments are not generated: the database
|
|
4309
4348
|
still applies them. `READONLY` is a trailing `# READONLY` comment: no field option exists for it.
|
|
4310
|
-
- `update()`
|
|
4311
|
-
|
|
4312
|
-
|
|
4313
|
-
|
|
4314
|
-
|
|
4315
|
-
|
|
4316
|
-
|
|
4317
|
-
change the record with `merge()`.
|
|
4349
|
+
- `update()` may fail on an instance holding a `READONLY` datetime below the top level, in a sub-model (`address.at`),
|
|
4350
|
+
a `tuple`, an array (`array<datetime>`, `items.*.at`) or a set, after `get()` as after `save()`: Python keeps
|
|
4351
|
+
microseconds, SurrealDB nanoseconds, and the server refuses the changed value. `update()` keeps the top-level
|
|
4352
|
+
`READONLY` datetimes to the nanosecond, up to 32 per record; below the top level it keeps one only while the fields
|
|
4353
|
+
before it leave room, which depends on the data (see [Precision and `Decimal`](#precision-and-decimal)). The
|
|
4354
|
+
generated class says so, as does a class with more than 32 top-level fields that may hold a datetime: change such a
|
|
4355
|
+
record with `merge()`.
|
|
4318
4356
|
- `array<T, N>` becomes `list[T]`: the length is left to the server, which checks it differently on each line
|
|
4319
4357
|
(SurrealDB 2.x accepts at most N items, 3.x exactly N).
|
|
4320
4358
|
- `null | T` becomes a required `T | None`, but the ORM sends `None` as `NONE`, which `null | T` refuses: give such a
|
|
@@ -4537,7 +4575,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
4537
4575
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
4538
4576
|
on 2.7.0. The 3.x column was measured on 3.2.4 and holds on 3.3.0, except where a row says
|
|
4539
4577
|
otherwise. The full suite and every divergence below were re-verified on both new versions.
|
|
4540
|
-
Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
|
|
4578
|
+
Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four.
|
|
4541
4579
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
4542
4580
|
|
|
4543
4581
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -4656,6 +4694,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
4656
4694
|
| Schema introspection of a database removed while the connection is open | empty schema | `SurrealDbError` (the database does not exist) until the database is defined again | v0.30.0 |
|
|
4657
4695
|
| DDL not yet committed in a transaction, seen by schema introspection | invisible | invisible | v0.30.0 |
|
|
4658
4696
|
| A regex with a backslash pair before a `/` (schema introspection) | `/a\\/b/` accepted (a backslash, then an escaped slash), `/\\/` refused: such a definition is a `SchemaIssue`, not read | `/\\/` accepted (an escaped backslash, then the closing slash), `/a\\/b/` refused: such a definition is a `SchemaIssue`, not read | v0.30.0 |
|
|
4697
|
+
| `save()` applies the returned row (explicit id, edges); `update()`/`upsert()` keep an unchanged stored `datetime` (nanoseconds) | stored row and read types (enums, sets…) after `save()`; a top-level `READONLY` datetime updates, a nested one may not; refused if a typed `VALUE` field is left out (#267) | as on 2.x (verified on 3.3.4 and 3.1.5), but a typed `VALUE` field left out is recomputed; `save(tx=)` in an interactive transaction applies the row too, a buffered one does not | v0.30.7 |
|
|
4659
4698
|
| Full suite and every divergence in this table, re-run on SurrealDB 2.7.0 and 3.3.0 | 2.7.0 identical to 2.6.5 (same passes, same 3.x-only skips) | 3.3.0 identical to 3.2.4, except the system-user signin row | v0.19.1 |
|
|
4660
4699
|
|
|
4661
4700
|
> **Note on record IDs**: A record loaded from the database has its `id` field set to a native `surrealdb.RecordID` object, not a plain string. Use `model.get_raw_id()` to obtain the bare identifier string (e.g. `"alice"`), or compare directly with `model.id == RecordID("User", "alice")`. In-memory instances you construct yourself retain whatever value you assign.
|
|
@@ -1712,6 +1712,8 @@ exactly what ends a stream.
|
|
|
1712
1712
|
- **A failed `kill()` releases the readers but keeps the uuid alive.** When the server refuses
|
|
1713
1713
|
the kill for any reason other than an unknown uuid, the error is raised, the readers are woken,
|
|
1714
1714
|
and the subscription is still running — so you can subscribe to it again or retry `stop()`.
|
|
1715
|
+
A kill caught by a dropped connection is not a refusal: the subscription died with the socket,
|
|
1716
|
+
so `kill()` records it as ended and returns normally.
|
|
1715
1717
|
- **The buffer is unbounded.** A stream you stop reading but never kill keeps accumulating
|
|
1716
1718
|
notifications. Use the `async with` forms, or pair every uuid you start with a `kill()`.
|
|
1717
1719
|
|
|
@@ -2194,8 +2196,12 @@ reads, a `timedelta` is converted from the SDK's duration at any depth too: a to
|
|
|
2194
2196
|
`list[timedelta]`, `dict[str, timedelta]`, `timedelta | str` or a sub-model's `timedelta` field
|
|
2195
2197
|
all read a `timedelta`, floored to the microsecond (declare `Duration` to keep the nanoseconds).
|
|
2196
2198
|
Your validators (any mode) and `model_post_init` still apply once to the value read, even when they
|
|
2197
|
-
change it in place. A naive `datetime`
|
|
2198
|
-
|
|
2199
|
+
change it in place. A naive `datetime` is written as UTC and read back as an aware UTC `datetime`.
|
|
2200
|
+
The instance keeps it naive until a call applies the row the server returns (see
|
|
2201
|
+
[After a write that returns the row](#after-a-write-that-returns-the-row)): after `save()` (since
|
|
2202
|
+
#261 with an explicit id too), `refresh()`, `merge()` (default `refresh=True`), `upsert()`,
|
|
2203
|
+
`patch()` or an `atomic_*` helper, the field holds that aware UTC `datetime`, so compare it with
|
|
2204
|
+
aware values. `update()`, and `save(tx=)` in a buffered transaction, leave it naive.
|
|
2199
2205
|
|
|
2200
2206
|
#### `Duration`
|
|
2201
2207
|
|
|
@@ -2318,7 +2324,23 @@ both lines.
|
|
|
2318
2324
|
#### Precision and `Decimal`
|
|
2319
2325
|
|
|
2320
2326
|
- `datetime`: to the microsecond. The SDK truncates the server's nanoseconds, so a stored
|
|
2321
|
-
`d'2026-01-02T03:04:05.123456789Z'` reads `…05.123456`.
|
|
2327
|
+
`d'2026-01-02T03:04:05.123456789Z'` reads `…05.123456`. `update()` and `upsert()` rewrite the
|
|
2328
|
+
whole record, but a `datetime` you did not change (it still floors to the stored value) keeps
|
|
2329
|
+
the stored nanoseconds, on both lines and the embedded engine: a record whose `READONLY`
|
|
2330
|
+
datetimes are top-level fields can be updated after `get()` or `save()`, even when they hold
|
|
2331
|
+
nanoseconds ([#261](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/261)). A
|
|
2332
|
+
datetime you changed is written as you set it, and a `READONLY` field still refuses it. So that
|
|
2333
|
+
the statement stays small whatever the data, only the top-level datetimes are sure to be kept,
|
|
2334
|
+
up to 32 per record. Below the top level (in a sub-model, a `list` or a `tuple`, down to three
|
|
2335
|
+
levels) a datetime is kept only while the values rebuilt to reach it fit in what the fields
|
|
2336
|
+
before it left of those 32, so it depends on the data: an `update()` that passes in a test can
|
|
2337
|
+
fail once a list of timestamped items before the sub-model grows. A datetime not kept, and one
|
|
2338
|
+
in a set (its items have no position to match a stored value by), is written as sent: a
|
|
2339
|
+
`READONLY` field holding one may refuse `update()`, so change such a record with `merge()`.
|
|
2340
|
+
SurrealDB 2.x also refuses, for now, `update()` and `upsert()` of an existing record that has
|
|
2341
|
+
a field with a non-optional `TYPE` and a `VALUE` clause the model does not write (a `Computed`
|
|
2342
|
+
field, such as a generated `updated: Computed[datetime]`): change it with `merge()` there
|
|
2343
|
+
([#267](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/267)).
|
|
2322
2344
|
- `timedelta`: floored to the microsecond on read (`1h30m1ns` reads `timedelta(seconds=5400)`).
|
|
2323
2345
|
- `Duration`: exact, to the nanosecond.
|
|
2324
2346
|
- `Decimal`: a value whose `str()` writes no exponent is sent as before. A value written with an
|
|
@@ -2381,22 +2403,40 @@ await sub.merge(trial=sub.trial + timedelta(days=7)) #
|
|
|
2381
2403
|
|
|
2382
2404
|
#### After a write that returns the row
|
|
2383
2405
|
|
|
2384
|
-
`save()` without an id, `refresh()`, `merge()`, `upsert()`, `patch()` and
|
|
2385
|
-
apply the row the server returns to the instance.
|
|
2386
|
-
|
|
2387
|
-
|
|
2388
|
-
|
|
2389
|
-
|
|
2390
|
-
|
|
2391
|
-
|
|
2392
|
-
|
|
2393
|
-
|
|
2394
|
-
|
|
2395
|
-
|
|
2396
|
-
|
|
2397
|
-
`
|
|
2398
|
-
|
|
2399
|
-
|
|
2406
|
+
`save()` (with or without an id, an edge's too), `refresh()`, `merge()`, `upsert()`, `patch()` and
|
|
2407
|
+
the `atomic_*` helpers apply the row the server returns to the instance. After `save()` the
|
|
2408
|
+
instance therefore holds what the record holds: the `server_fields` and computed fields, the
|
|
2409
|
+
sub-fields a `DEFAULT` filled (`prefs.at DEFAULT time::now()`), and the values the server coerced
|
|
2410
|
+
or rewrote (`VALUE string::lowercase($value)`), so a following `update()` writes them back
|
|
2411
|
+
unchanged ([#261](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/261)). An id you
|
|
2412
|
+
gave stays as you gave it; an auto id is the server's `RecordID`. A buffered transaction (HTTP,
|
|
2413
|
+
SurrealDB 2.x, the embedded engine) returns no row before commit: there `save(tx=)` leaves the
|
|
2414
|
+
instance as it was, and `refresh()` after the commit reads the row.
|
|
2415
|
+
|
|
2416
|
+
The top-level `timedelta`, `Duration` and geometry fields (since v0.24.0, see
|
|
2417
|
+
[section 25](#25-geospatial-fields)) are converted on the way, and every other field gets the
|
|
2418
|
+
value a read gives (#261; before, only a field holding a sub-model, a geometry or a nested
|
|
2419
|
+
`timedelta` did): the row goes through the model's validation, the model's own validators
|
|
2420
|
+
included. A sub-model field holds its model instance, not the row's `dict`, with the ORM's
|
|
2421
|
+
durations, `timedelta`s, ranges and geometries inside; an enum field holds the enum, not its `str`
|
|
2422
|
+
or `int`; a `tuple`, set, `date` or `Range` field holds its declared type, not the SDK's `list`,
|
|
2423
|
+
midnight `datetime` or `Range`; a `float` field stored in a `decimal` column holds a `float`, not a
|
|
2424
|
+
`Decimal`; a `list[Duration]` holds the ORM's durations. When the row as a whole does not validate,
|
|
2425
|
+
each field is validated on its own, except one that the model's own validators could reshape (a
|
|
2426
|
+
`field_validator` on that field, a `model_validator`, a `model_post_init`): that one, like a value
|
|
2427
|
+
that does not validate, is applied as received, so these calls never fail on it. The `id` keeps
|
|
2428
|
+
the server's `RecordID`. A column the model does not declare goes where a read puts it: as the SDK
|
|
2429
|
+
reads it into `model_extra` under `extra="allow"`, nowhere otherwise. So a column holding a Pydantic
|
|
2430
|
+
`@computed_field` (`model_dump()` writes it) or named like a method (`json`) never replaces that
|
|
2431
|
+
attribute.
|
|
2432
|
+
|
|
2433
|
+
Writing such an instance back is safe, sub-models included: a following `update()` replaces the
|
|
2434
|
+
record with these values, as after `get()`. So a `float` field stored in a `decimal` column writes
|
|
2435
|
+
the float's rounding (`0.12345678901234567890` becomes `0.1234567890123457`: declare `Decimal` to
|
|
2436
|
+
keep every digit), and under `extra="allow"` the columns in `model_extra` are written back, not
|
|
2437
|
+
removed. An enum declared `(str, Enum)` or `(int, Enum)` holds the member, as after `get()`: it
|
|
2438
|
+
compares equal to its value, but `str()` and f-strings give `Color.RED`, not `red` (a `StrEnum` or
|
|
2439
|
+
an `IntEnum` gives the value), so use `.value` to build a key, a URL or a log line from it.
|
|
2400
2440
|
|
|
2401
2441
|
#### Values the SDK cannot read
|
|
2402
2442
|
|
|
@@ -2442,9 +2482,8 @@ refused value raises `ValueError` before anything is sent.
|
|
|
2442
2482
|
|
|
2443
2483
|
Plain `datetime`, `Decimal` and `UUID` annotations work as they do there. The full ORM has no
|
|
2444
2484
|
`timedelta` or `Range` fields and its `Duration` is a string: `timedelta`, `Duration` and
|
|
2445
|
-
`Range[T]` fields are lite additions. The full ORM also validates the rows its writes return;
|
|
2446
|
-
|
|
2447
|
-
top-level durations, while top-level `date`, `set` and `Range` fields keep the SDK's value (see
|
|
2485
|
+
`Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; so
|
|
2486
|
+
does lite, every field but the `id` since #261, with top-level durations converted (see
|
|
2448
2487
|
[After a write that returns the row](#after-a-write-that-returns-the-row)).
|
|
2449
2488
|
|
|
2450
2489
|
### 25. Geospatial fields
|
|
@@ -4256,14 +4295,13 @@ class Person(BaseSurrealModel):
|
|
|
4256
4295
|
object-literal kind (`{ a: int }`) stays a `dict[str, Any]`.
|
|
4257
4296
|
- `ASSERT`, `PERMISSIONS`, `REFERENCE` (the field is a `RecordID`) and field comments are not generated: the database
|
|
4258
4297
|
still applies them. `READONLY` is a trailing `# READONLY` comment: no field option exists for it.
|
|
4259
|
-
- `update()`
|
|
4260
|
-
|
|
4261
|
-
|
|
4262
|
-
|
|
4263
|
-
|
|
4264
|
-
|
|
4265
|
-
|
|
4266
|
-
change the record with `merge()`.
|
|
4298
|
+
- `update()` may fail on an instance holding a `READONLY` datetime below the top level, in a sub-model (`address.at`),
|
|
4299
|
+
a `tuple`, an array (`array<datetime>`, `items.*.at`) or a set, after `get()` as after `save()`: Python keeps
|
|
4300
|
+
microseconds, SurrealDB nanoseconds, and the server refuses the changed value. `update()` keeps the top-level
|
|
4301
|
+
`READONLY` datetimes to the nanosecond, up to 32 per record; below the top level it keeps one only while the fields
|
|
4302
|
+
before it leave room, which depends on the data (see [Precision and `Decimal`](#precision-and-decimal)). The
|
|
4303
|
+
generated class says so, as does a class with more than 32 top-level fields that may hold a datetime: change such a
|
|
4304
|
+
record with `merge()`.
|
|
4267
4305
|
- `array<T, N>` becomes `list[T]`: the length is left to the server, which checks it differently on each line
|
|
4268
4306
|
(SurrealDB 2.x accepts at most N items, 3.x exactly N).
|
|
4269
4307
|
- `null | T` becomes a required `T | None`, but the ORM sends `None` as `NONE`, which `null | T` refuses: give such a
|
|
@@ -4486,7 +4524,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
4486
4524
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
4487
4525
|
on 2.7.0. The 3.x column was measured on 3.2.4 and holds on 3.3.0, except where a row says
|
|
4488
4526
|
otherwise. The full suite and every divergence below were re-verified on both new versions.
|
|
4489
|
-
Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
|
|
4527
|
+
Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four.
|
|
4490
4528
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
4491
4529
|
|
|
4492
4530
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -4605,6 +4643,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
4605
4643
|
| Schema introspection of a database removed while the connection is open | empty schema | `SurrealDbError` (the database does not exist) until the database is defined again | v0.30.0 |
|
|
4606
4644
|
| DDL not yet committed in a transaction, seen by schema introspection | invisible | invisible | v0.30.0 |
|
|
4607
4645
|
| A regex with a backslash pair before a `/` (schema introspection) | `/a\\/b/` accepted (a backslash, then an escaped slash), `/\\/` refused: such a definition is a `SchemaIssue`, not read | `/\\/` accepted (an escaped backslash, then the closing slash), `/a\\/b/` refused: such a definition is a `SchemaIssue`, not read | v0.30.0 |
|
|
4646
|
+
| `save()` applies the returned row (explicit id, edges); `update()`/`upsert()` keep an unchanged stored `datetime` (nanoseconds) | stored row and read types (enums, sets…) after `save()`; a top-level `READONLY` datetime updates, a nested one may not; refused if a typed `VALUE` field is left out (#267) | as on 2.x (verified on 3.3.4 and 3.1.5), but a typed `VALUE` field left out is recomputed; `save(tx=)` in an interactive transaction applies the row too, a buffered one does not | v0.30.7 |
|
|
4608
4647
|
| Full suite and every divergence in this table, re-run on SurrealDB 2.7.0 and 3.3.0 | 2.7.0 identical to 2.6.5 (same passes, same 3.x-only skips) | 3.3.0 identical to 3.2.4, except the system-user signin row | v0.19.1 |
|
|
4609
4648
|
|
|
4610
4649
|
> **Note on record IDs**: A record loaded from the database has its `id` field set to a native `surrealdb.RecordID` object, not a plain string. Use `model.get_raw_id()` to obtain the bare identifier string (e.g. `"alice"`), or compare directly with `model.id == RecordID("User", "alice")`. In-memory instances you construct yourself retain whatever value you assign.
|
{surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.7}/src/surreal_orm_lite/connection_manager.py
RENAMED
|
@@ -33,12 +33,14 @@ from .exceptions import (
|
|
|
33
33
|
from .functions import build_call_statement, normalize_function_name, parse_function_parameters
|
|
34
34
|
from .live import (
|
|
35
35
|
LiveIterator,
|
|
36
|
+
cancellation_lost,
|
|
36
37
|
close_all_subscribers,
|
|
37
38
|
is_connection_failure,
|
|
38
39
|
is_dead,
|
|
39
40
|
mark_killed,
|
|
40
41
|
open_stream,
|
|
41
42
|
owner_of,
|
|
43
|
+
recv_task_of,
|
|
42
44
|
release_subscribers,
|
|
43
45
|
require_websocket,
|
|
44
46
|
)
|
|
@@ -50,6 +52,10 @@ logger = logging.getLogger(__name__)
|
|
|
50
52
|
# Strong references to fire-and-forget closes, which the event loop alone would let be collected.
|
|
51
53
|
_BACKGROUND: set[asyncio.Task[Any]] = set()
|
|
52
54
|
|
|
55
|
+
# How long a KILL that failed on a transport error waits for the SDK's receive loop to end, before
|
|
56
|
+
# deciding the connection is still up (and the failure a real one).
|
|
57
|
+
_DROP_SETTLE_TIMEOUT = 1.0
|
|
58
|
+
|
|
53
59
|
|
|
54
60
|
@lru_cache(maxsize=256)
|
|
55
61
|
def _cached_type_adapter(return_type: Any) -> TypeAdapter[Any]:
|
|
@@ -2473,10 +2479,16 @@ class SurrealDBConnectionManager:
|
|
|
2473
2479
|
client still cached on this loop — a stream started on a server, stopped after switching
|
|
2474
2480
|
to the engine — receives the KILL; otherwise the call is the no-op above.
|
|
2475
2481
|
|
|
2482
|
+
A KILL caught by a drop — sent as the connection goes down, before the SDK has noticed —
|
|
2483
|
+
is not a refusal either: the live query died with the socket, so the call ends as it does
|
|
2484
|
+
on a dead client, and raises nothing.
|
|
2485
|
+
|
|
2476
2486
|
:param query_uuid: the uuid of a running live query, e.g. ``stream.live_id``.
|
|
2477
2487
|
:raises SurrealDbError: if the server refuses the kill for a reason other than an
|
|
2478
2488
|
unknown uuid. The readers are released anyway, but the uuid is **not** recorded as
|
|
2479
2489
|
dead — the subscription is still running, so a retry can re-attach to it.
|
|
2490
|
+
:raises asyncio.CancelledError: if the calling task is cancelled, even when the SDK
|
|
2491
|
+
reports the cancelled request as an ordinary error. The readers are released.
|
|
2480
2492
|
"""
|
|
2481
2493
|
client = cls._cached_client()
|
|
2482
2494
|
try:
|
|
@@ -2485,6 +2497,8 @@ class SurrealDBConnectionManager:
|
|
|
2485
2497
|
# receive loop that died on a bad frame leaves the socket open, though, and the server
|
|
2486
2498
|
# still running them: closing the transport is what ends them then.
|
|
2487
2499
|
if client is None or is_dead(client):
|
|
2500
|
+
# Before any await: a resubscribe woken by the same drop must find the reader gone.
|
|
2501
|
+
release_subscribers(query_uuid)
|
|
2488
2502
|
if client is not None:
|
|
2489
2503
|
await cls._close_dead_socket(client)
|
|
2490
2504
|
mark_killed(query_uuid)
|
|
@@ -2494,14 +2508,41 @@ class SurrealDBConnectionManager:
|
|
|
2494
2508
|
try:
|
|
2495
2509
|
await client.kill(query_uuid)
|
|
2496
2510
|
except Exception as exc:
|
|
2497
|
-
|
|
2511
|
+
# Before any await: a resubscribe woken by the same drop must find the reader gone,
|
|
2512
|
+
# or it opens a connection for a subscription being torn down. Closing the socket
|
|
2513
|
+
# below yields the loop on Python 3.11, where `wait_for` always wraps a Task.
|
|
2514
|
+
release_subscribers(query_uuid)
|
|
2515
|
+
if cancellation_lost(exc):
|
|
2516
|
+
raise asyncio.CancelledError from exc # the SDK raised over the caller's cancellation
|
|
2517
|
+
if await cls._dropped_under_request(client, exc):
|
|
2518
|
+
# The server never answered: the connection went down with the request in flight.
|
|
2519
|
+
await cls._close_dead_socket(client)
|
|
2520
|
+
elif not cls._is_unknown_live_query(exc):
|
|
2498
2521
|
raise SurrealDbError(f"Failed to kill live query {query_uuid}: {exc}") from exc
|
|
2499
2522
|
mark_killed(query_uuid)
|
|
2500
2523
|
finally:
|
|
2501
2524
|
# In a `finally` so that every exit — success, failure, cancellation — wakes the
|
|
2502
|
-
# readers; nothing else ever would.
|
|
2525
|
+
# readers; nothing else ever would. Idempotent after an early release above, and it
|
|
2526
|
+
# also wakes a reader that subscribed to the uuid while this call was awaiting.
|
|
2503
2527
|
release_subscribers(query_uuid)
|
|
2504
2528
|
|
|
2529
|
+
@staticmethod
|
|
2530
|
+
async def _dropped_under_request(client: Any, exc: Exception) -> bool:
|
|
2531
|
+
"""Whether a request on *client* failed with *exc* because its WebSocket dropped.
|
|
2532
|
+
|
|
2533
|
+
Decided on the client, never on the error alone. The SDK reports a request caught by a
|
|
2534
|
+
drop as a bare ``KeyError``: its receive loop ends, cancels the pending request and clears
|
|
2535
|
+
the pending-request map, so the request's own cleanup finds its id gone (surrealdb 2.0.0)
|
|
2536
|
+
— by then the receive task is done. A transport error can surface a moment before that
|
|
2537
|
+
loop has ended, so it gets a bounded wait to catch up; anything else is decided at once.
|
|
2538
|
+
"""
|
|
2539
|
+
task = recv_task_of(client)
|
|
2540
|
+
if task is None:
|
|
2541
|
+
return False
|
|
2542
|
+
if not task.done() and is_connection_failure(exc, None):
|
|
2543
|
+
await asyncio.wait({task}, timeout=_DROP_SETTLE_TIMEOUT)
|
|
2544
|
+
return task.done()
|
|
2545
|
+
|
|
2505
2546
|
@staticmethod
|
|
2506
2547
|
def _is_unknown_live_query(exc: Exception) -> bool:
|
|
2507
2548
|
"""Whether *exc* is the server refusing to kill a live query it does not know.
|