surreal-orm-lite 0.25.0__tar.gz → 0.27.0__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.25.0 → surreal_orm_lite-0.27.0}/CHANGELOG.md +205 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/PKG-INFO +501 -6
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/README.md +500 -5
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/pyproject.toml +1 -1
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/__init__.py +3 -1
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/_sdk.py +6 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/embedded.py +29 -2
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/model_base.py +107 -13
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/q.py +14 -3
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/query_set.py +738 -119
- surreal_orm_lite-0.27.0/src/surreal_orm_lite/subquery.py +423 -0
- surreal_orm_lite-0.27.0/src/surreal_orm_lite/time_travel.py +264 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/utils.py +28 -2
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/.gitignore +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/LICENSE +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/Makefile +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/types.py +0 -0
|
@@ -5,6 +5,211 @@ 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.27.0] - 2026-10-16
|
|
9
|
+
|
|
10
|
+
Subqueries: a QuerySet filters another, as `Subquery(qs)` or the queryset itself, compiled to a
|
|
11
|
+
sub-`SELECT` the server runs inside the outer statement: one request, one consistent read, every
|
|
12
|
+
inner value bound. The fifth minor of Tier 2.
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- **`Subquery(qs)`**, exported from `surreal_orm_lite` (the full SurrealDB-ORM's name), and a
|
|
17
|
+
QuerySet given directly as a filter value, in `filter()` and in `Q` (`&`, `|`, `~`, any nesting).
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
from surreal_orm_lite import Q, Subquery
|
|
21
|
+
|
|
22
|
+
active = Person.objects().filter(active=True)
|
|
23
|
+
posts = await Post.objects().filter(author__in=Subquery(active)).exec()
|
|
24
|
+
same = await Post.objects().filter(author__in=active).exec() # a QuerySet is a subquery
|
|
25
|
+
|
|
26
|
+
best = Post.objects().select("score").order_by("-score").limit(1)
|
|
27
|
+
top = await Post.objects().filter(score=Subquery(best)).exec() # compared with its first value
|
|
28
|
+
|
|
29
|
+
inactive = Person.objects().filter(active=False)
|
|
30
|
+
mixed = await Post.objects().filter(Q(author__in=inactive) | Q(score__gte=9)).exec()
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- **Lookups.** `in`, `not_in`, `containsall` and `containsany` compare the field with all the
|
|
34
|
+
subquery's values; `exact` (no suffix), `gt`, `gte`, `lt`, `lte`, `contains` and `not_contains`
|
|
35
|
+
with its first value (order the subquery to choose it). A first-value lookup on an empty
|
|
36
|
+
subquery matches no record, and `~Q(...)` of it every record; for `in`, an empty subquery is an
|
|
37
|
+
empty list.
|
|
38
|
+
- **What the inner queryset selects**: its record ids without `select()` (`SELECT VALUE id`), or
|
|
39
|
+
the values of the one field given to `select()` (an aliased field compiles its column). Its
|
|
40
|
+
`filter()`, `Q`, `nearby()`, `order_by()`, `limit()`, `offset()` and `variables()` apply; its
|
|
41
|
+
`fetch()` is ignored, as in the full ORM. Values are compared as stored, never converted: to
|
|
42
|
+
match records, select `id` or a record link.
|
|
43
|
+
- **Where it applies**: `exec()`, `first()`, `get()` with filters, `exists()`, `count()`, `sum()`,
|
|
44
|
+
`avg()`, `min()`, `max()`, `values(…).annotate(…)` and `annotate(GeoDistance)`; the writes by
|
|
45
|
+
filter `bulk_update()`, `bulk_delete()` and `QuerySet.patch()`; the lookups of `get_or_create()`
|
|
46
|
+
and `update_or_create()`. Subqueries nest. In `Model.objects(tx=tx)` the statement runs in the
|
|
47
|
+
transaction, and an interactive transaction's subquery sees its uncommitted writes. Under
|
|
48
|
+
`as_of()` every subquery reads at the same moment. `live()` and `watch()` write the sub-SELECT
|
|
49
|
+
inline, and the server evaluates it again on every change. `changes()` refuses `filter()`, so
|
|
50
|
+
subqueries too.
|
|
51
|
+
- **Refusals before any request** (`live()` and `watch()` at the call). `ValueError`: a lookup
|
|
52
|
+
that takes no subquery (`isnull`, `like`, `ilike`, `startswith`, `endswith`, `match`, `regex`,
|
|
53
|
+
`inside`, `outside`, `intersects`), a queryset that is its own subquery, an inner `values()`,
|
|
54
|
+
`annotate()` or `select()` of several fields, an inner `limit()` or `offset()` that is not an
|
|
55
|
+
`int >= 0`, an inner `order_by()` on `_sqv` it does not select, an inner `variables()` binding a
|
|
56
|
+
name of the statement to another value, a subquery inside a list, `Q(...).to_sql()` called on its
|
|
57
|
+
own with a subquery, and `bulk_update(score=Subquery(qs))`. `SurrealDbError`: an inner `as_of()`
|
|
58
|
+
(call it on the outer queryset), an inner `objects(tx=)` whose transaction is not the outer
|
|
59
|
+
one's, and a subquery as an `exact` criterion or a `defaults=` value of `get_or_create()` or
|
|
60
|
+
`update_or_create()`. `TypeError`: `Subquery(x)` for anything but a QuerySet.
|
|
61
|
+
- README section 28, "Subqueries (`Subquery`)" (what a subquery selects, the lookups, ordered and
|
|
62
|
+
limited subqueries, where subqueries apply, what they cannot do, a note for users of the full
|
|
63
|
+
SurrealDB-ORM), a bullet in the supported lookups, a `Q` example in section 5, four rows in the
|
|
64
|
+
2.x/3.x behaviour table, and the example notebook `examples/v0.27.0_subqueries.ipynb`.
|
|
65
|
+
|
|
66
|
+
### Changed
|
|
67
|
+
|
|
68
|
+
- A QuerySet given as a filter value is now a subquery. v0.26.x refused it: `in` and `not_in`
|
|
69
|
+
raised `ValueError` ("requires an iterable") and the other lookups failed when the SDK encoded
|
|
70
|
+
the request. Every call that worked in v0.26.x behaves the same.
|
|
71
|
+
- `Q.to_sql()` gains a keyword-only `subqueries` parameter (default `None`), the compiler of the
|
|
72
|
+
statement the QuerySet sends; a `Q` compiled on its own refuses a subquery lookup.
|
|
73
|
+
|
|
74
|
+
### Notes
|
|
75
|
+
|
|
76
|
+
- **One statement per request, a block of `LET`s**:
|
|
77
|
+
`{ LET $_sq0 = (SELECT VALUE id FROM Person WHERE active = $_f0); (SELECT * FROM Post WHERE author IN $_sq0) };`.
|
|
78
|
+
Each subquery is bound once, innermost first, because SurrealDB 3.2 and later can return wrong
|
|
79
|
+
rows for an inline sub-SELECT with `ORDER BY` and `LIMIT`
|
|
80
|
+
([surrealdb/surrealdb#7470](https://github.com/surrealdb/surrealdb/issues/7470)), and because the
|
|
81
|
+
official SDK's `query()` returns the first statement's result only, so the full ORM's `LET`
|
|
82
|
+
prelude (two statements) does not fit. An ordered subquery selects its column as `_sqv` with its
|
|
83
|
+
order fields: SurrealDB 2.x refuses to order a one-column sub-SELECT by another field. `$_sq0`,
|
|
84
|
+
`$_sq1`, … are reserved in such a statement and hide a `variables()` value of the same name.
|
|
85
|
+
- **A first-value lookup on an empty subquery matches no record**: SurrealDB alone would compare
|
|
86
|
+
with `array::first([])`, which is `NONE`, and `score > NONE` holds for every record, so the ORM
|
|
87
|
+
guards the comparison. The full SurrealDB-ORM matches every record there.
|
|
88
|
+
- **A subquery table that does not exist reads as empty**, like any missing table. SurrealDB 2.x
|
|
89
|
+
and the embedded engine read it so in the same request. On SurrealDB 3.x the ORM asks the server
|
|
90
|
+
whether the table exists and, once it confirms the table does not, sends the statement again
|
|
91
|
+
with that subquery empty: three requests, and only then. Any other error, even one quoting
|
|
92
|
+
"does not exist", is relayed. On 3.x a write by filter in a transaction fails with the server's
|
|
93
|
+
error, and `live()` raises `SurrealDbNotFoundError` before it starts (3.x would accept the live
|
|
94
|
+
query and never notify).
|
|
95
|
+
- **Transactions**: a buffered transaction (2.x, or HTTP) still cannot read, and applies writes by
|
|
96
|
+
filter at commit. Build the inner queryset with the same `objects(tx=)`, or with none.
|
|
97
|
+
- **Time travel**: without versioned storage, a subquery read under `as_of()` raises v0.26.0's
|
|
98
|
+
`SurrealDbError`; SurrealDB 3.1.5 raises the server's own `ThrownError` instead.
|
|
99
|
+
- Not available yet: `annotate(x=Subquery(...))`, correlated subqueries (`OuterRef`, `$parent`)
|
|
100
|
+
and `Exists`.
|
|
101
|
+
- **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, in memory and on versioned
|
|
102
|
+
storage, and on the embedded engine, plus 3.1.5 for backward compatibility (identical except the
|
|
103
|
+
time-travel error above).
|
|
104
|
+
|
|
105
|
+
## [0.26.0] - 2026-10-16
|
|
106
|
+
|
|
107
|
+
Time travel: a QuerySet reads a model's records as they were at a past moment, with
|
|
108
|
+
`as_of()` (SurrealQL's `VERSION` clause), on the official SDK's embedded
|
|
109
|
+
`surrealkv+versioned://` engine and on SurrealDB servers started with versioned storage. The
|
|
110
|
+
fourth minor of Tier 2.
|
|
111
|
+
|
|
112
|
+
### Added
|
|
113
|
+
|
|
114
|
+
- **`QuerySet.as_of(at)`** adds a moment to every read of the queryset. Records updated since
|
|
115
|
+
read as they were, a record deleted since is still found, and one created later is not. The
|
|
116
|
+
store must keep history: the embedded `surrealkv+versioned://<path>` (no server), SurrealDB 3.x
|
|
117
|
+
started on `surrealkv://<path>?versioned=true` or `rocksdb://<path>?versioned=true`, or
|
|
118
|
+
SurrealDB 2.x started on `surrealkv+versioned://<path>`.
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
from surreal_orm_lite import BaseSurrealModel, SurrealDBConnectionManager
|
|
122
|
+
|
|
123
|
+
class Product(BaseSurrealModel):
|
|
124
|
+
id: str | None = None
|
|
125
|
+
name: str
|
|
126
|
+
price: float
|
|
127
|
+
|
|
128
|
+
SurrealDBConnectionManager.set_connection(
|
|
129
|
+
url=f"surrealkv+versioned://{path}/shop", namespace="shop", database="shop"
|
|
130
|
+
)
|
|
131
|
+
client = await SurrealDBConnectionManager.get_client()
|
|
132
|
+
|
|
133
|
+
lamp = Product(id="lamp", name="Lamp", price=40.0)
|
|
134
|
+
await lamp.save()
|
|
135
|
+
opening = await client.query("RETURN time::now();") # a moment, from the database's clock
|
|
136
|
+
await lamp.merge(price=30.0)
|
|
137
|
+
|
|
138
|
+
assert (await Product.objects().as_of(opening).get("lamp")).price == 40.0
|
|
139
|
+
assert (await Product.objects().get("lamp")).price == 30.0
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
- **The moment** is an aware `datetime` (any time zone) or a naive one (UTC), an ISO-8601 string
|
|
143
|
+
(parsed by the ORM; a date alone is midnight UTC), a `timedelta` or the ORM's `Duration` (that
|
|
144
|
+
long before the database's clock), a `SurrealFunc` the database evaluates
|
|
145
|
+
(`SurrealFunc("time::now() - 1h")`), or `None` (the current state again); called again, the last
|
|
146
|
+
moment wins. The moment is always a bound parameter. A moment outside the instants SurrealDB
|
|
147
|
+
versions can address (1970-01-01T00:00:00Z to 2262-04-11T23:47:16.854775Z) is refused on every
|
|
148
|
+
line: `ValueError` at the call, or `SurrealDbError` before the read for a duration or an
|
|
149
|
+
expression the database resolved there.
|
|
150
|
+
- **Every read honours it**, with `filter()`, `Q`, `nearby()`, `order_by()`, `limit()`, `offset()`,
|
|
151
|
+
`select()` and `variables()`, on edge models too: `exec()`, `first()`, `get()` (with filters or by
|
|
152
|
+
id), `all()`, `exists()`, `count()`, `sum()`, `avg()`, `min()`, `max()`, `values(…).annotate(…)`
|
|
153
|
+
and `annotate(d=GeoDistance(…))`.
|
|
154
|
+
- **Snapshots.** The instances a time-travel read returns are read-only: `save()`, `update()`,
|
|
155
|
+
`merge()`, `patch()`, `upsert()`, `delete()`, the `atomic_*()` methods, `relate()`,
|
|
156
|
+
`remove_relation()` and `remove_all_relations()` raise `SurrealDbError` before any signal or
|
|
157
|
+
request, and `bulk_create()` refuses a snapshot in its list. `refresh()` turns a snapshot back
|
|
158
|
+
into the current record; `Product(**snapshot.model_dump()).update()` (or `.save()` for a record
|
|
159
|
+
deleted since, or `.upsert()`) writes a past state back. `model_copy()` and `pickle` keep the
|
|
160
|
+
snapshot, and a snapshot is never `==` the current instance (compare `model_dump()`s). A record
|
|
161
|
+
model nested in a snapshot's fields is a snapshot too, such as a link `fetch()` resolves into a
|
|
162
|
+
model-typed field on SurrealDB 3.x; its own `refresh()` makes it the current record.
|
|
163
|
+
- **Refusals before any request.** On a queryset with `as_of()`: `bulk_create()`, `bulk_update()`,
|
|
164
|
+
`bulk_delete()`, `patch()`, `update_or_create()`, `get_or_create()`, `delete_table()`, `query()`,
|
|
165
|
+
`live()`, `watch()` and `changes()` raise `SurrealDbError`; `Model.objects(tx=...).as_of(...)`
|
|
166
|
+
raises at the call (history cannot join a transaction); on the embedded engine, a URL that keeps
|
|
167
|
+
no history (`mem://`, `memory://`, `surrealkv://`, `file://`) raises, naming
|
|
168
|
+
`surrealkv+versioned://`. A 3.x server without versioned storage refuses the read, raised as
|
|
169
|
+
`SurrealDbError` with the SDK's error as its `__cause__`.
|
|
170
|
+
- README section 27, "Time travel (`as_of()`)" (stores that keep history, the moment, reads,
|
|
171
|
+
snapshots, refusals, SurrealDB 2.x without versioned storage, record links, writing history with
|
|
172
|
+
a raw `CREATE … VERSION`, a note for users of the full SurrealDB-ORM, which has no time travel),
|
|
173
|
+
new rows in both behaviour tables, and the example notebook `examples/v0.26.0_time_travel.ipynb`.
|
|
174
|
+
|
|
175
|
+
### Changed
|
|
176
|
+
|
|
177
|
+
- `BaseSurrealModel` declares a private attribute, the snapshot marker, so every instance now has
|
|
178
|
+
a `__pydantic_private__` dict. Two current instances compare as before; an instance pickled by
|
|
179
|
+
v0.25.x unpickles as a current record, and a model's own private attributes are kept.
|
|
180
|
+
- `refresh()` also clears the snapshot marker of an instance read with `as_of()`.
|
|
181
|
+
- CI starts a second SurrealDB per job, on versioned storage, for the time-travel tests; they find
|
|
182
|
+
it through `SURREALDB_VERSIONED_PORT` and skip without it.
|
|
183
|
+
|
|
184
|
+
### Notes
|
|
185
|
+
|
|
186
|
+
- **Every time-travel table read also reads each record by its id at the moment**, because a plain
|
|
187
|
+
`SELECT … VERSION` is wrong on both server lines: SurrealDB 3.x's table reads return the records
|
|
188
|
+
deleted before the moment, in their last state, and SurrealDB 2.x and the embedded engine
|
|
189
|
+
miscount an unfiltered `count()`. It costs about one extra point read per record scanned; a read
|
|
190
|
+
by id needs no check.
|
|
191
|
+
- **SurrealDB 2.x without versioned storage answers without an error**: in memory or on plain
|
|
192
|
+
SurrealKV, it returns only the records last written at or before the moment, in their current
|
|
193
|
+
state, and the ORM cannot tell which storage the server runs. Start 2.x with
|
|
194
|
+
`surrealkv+versioned://` for time travel. SurrealDB 2.x on RocksDB refuses `VERSION`
|
|
195
|
+
(`SurrealDbError`).
|
|
196
|
+
- **Record links**: `fetch()` resolves links as they were on SurrealDB 3.x, into read-only
|
|
197
|
+
snapshots. On SurrealDB 2.x (servers and the SDK 2.x embedded engine) they resolve to their
|
|
198
|
+
current state, so `exec()`, `first()` and `get()` without an id refuse `fetch()` under
|
|
199
|
+
`as_of()`; a dotted path through a link reads the current value there.
|
|
200
|
+
- **Writing history at a past moment** is left to raw queries (`CREATE … VERSION d'…'`, one
|
|
201
|
+
statement per `client.query()` call): stored at that moment and readable with `as_of()` on
|
|
202
|
+
SurrealDB 2.x and the embedded engine; accepted but not readable at that moment on SurrealDB 3.x.
|
|
203
|
+
- The surrealdb SDK 2.x embedded engine ignores `?versioned=true` on `surrealkv://`: use
|
|
204
|
+
`surrealkv+versioned://`. The SDK's own `surrealdb.Duration` is accepted at runtime only (the
|
|
205
|
+
annotation names the ORM's types). `_as_of` is a reserved `variables()` name on a time-travel
|
|
206
|
+
read: the moment is bound under it.
|
|
207
|
+
- A `SurrealFunc` moment is sent as written: build it in your code, never from user input, and pass
|
|
208
|
+
user values through `variables()`, bound.
|
|
209
|
+
- **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, in memory and on versioned
|
|
210
|
+
storage, plus 3.1.5 for backward compatibility (identical); the embedded tests run in every CI
|
|
211
|
+
job. Every existing call behaves as in v0.25.x.
|
|
212
|
+
|
|
8
213
|
## [0.25.0] - 2026-10-15
|
|
9
214
|
|
|
10
215
|
Embedded test engine: the ORM also runs on the official SDK's in-process SurrealDB engine
|