surreal-orm-lite 0.26.0__tar.gz → 0.28.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.26.0 → surreal_orm_lite-0.28.0}/CHANGELOG.md +204 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/PKG-INFO +455 -4
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/README.md +454 -3
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/pyproject.toml +1 -1
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/__init__.py +6 -1
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/_sdk.py +6 -0
- surreal_orm_lite-0.28.0/src/surreal_orm_lite/cache.py +813 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/connection_manager.py +25 -3
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/edge.py +2 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/model_auth.py +3 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/model_base.py +19 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/q.py +14 -3
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/query_set.py +676 -118
- surreal_orm_lite-0.28.0/src/surreal_orm_lite/subquery.py +425 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/transaction.py +57 -11
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/utils.py +28 -2
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/.gitignore +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/LICENSE +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/Makefile +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/types.py +0 -0
|
@@ -5,6 +5,210 @@ 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.28.0] - 2026-10-17
|
|
9
|
+
|
|
10
|
+
Query cache: a QuerySet serves its reads from a client-side cache with `cache(ttl)`, and every ORM
|
|
11
|
+
write removes the cached reads it can change, with nothing to set up. The sixth minor of Tier 2.
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- **`QuerySet.cache(ttl=None)`** and **`QueryCache`**, exported from `surreal_orm_lite` (the full
|
|
16
|
+
SurrealDB-ORM's names). The rows a cached read returned stay in this process's memory, and the
|
|
17
|
+
same read is answered from there, without a request, until its TTL runs out or an ORM write
|
|
18
|
+
changes what it reads.
|
|
19
|
+
|
|
20
|
+
```python
|
|
21
|
+
from surreal_orm_lite import QueryCache
|
|
22
|
+
|
|
23
|
+
books = await Product.objects().filter(category="book").cache(ttl=30).exec() # the database answers
|
|
24
|
+
again = await Product.objects().filter(category="book").cache(ttl=30).exec() # the cache answers
|
|
25
|
+
await Product(id="p4", name="Atlas", category="book", price=40).save() # removes Product's cached reads
|
|
26
|
+
fresh = await Product.objects().filter(category="book").cache(ttl=30).exec() # the database answers
|
|
27
|
+
QueryCache.stats()["hits"] # 1
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- **Every read of a cached queryset**: `exec()`, `first()`, `get()` by filters or by id, `all()`,
|
|
31
|
+
`count()`, `sum()`, `avg()`, `min()`, `max()`, `exists()`, `values(…).annotate(…)` and
|
|
32
|
+
`annotate(GeoDistance)`. A read is a hit when an earlier read sent the same statement with the
|
|
33
|
+
same variables, on the same connection and with the same identity, within the TTL. Rows are
|
|
34
|
+
cached, not instances: each hit builds new instances from a copy. Empty results are cached
|
|
35
|
+
(`get(<id>)` of a missing record raises `SurrealDbNotFoundError` on the hit too); errors never
|
|
36
|
+
are. An internal failure of the cache never fails a read: the read goes to the database.
|
|
37
|
+
- **Time to live**: seconds (`int` or `float`) or a `timedelta`, the oldest result the read
|
|
38
|
+
accepts; `cache()` without a TTL uses `QueryCache`'s default (60 s unless configured); `0` means
|
|
39
|
+
never cached.
|
|
40
|
+
- **Built-in invalidation**: every ORM write removes the cached reads of the tables it writes,
|
|
41
|
+
before its `post_*` signals fire — `save()`, `update()`, `merge()`, `upsert()`, `patch()`,
|
|
42
|
+
`delete()`, the atomic operations, `relate()` and the `remove_*()` helpers, a typed edge's
|
|
43
|
+
`save()`, `bulk_create()`, `bulk_update()`, `bulk_delete()`, `QuerySet.patch()`,
|
|
44
|
+
`delete_table()`, `get_or_create()`/`update_or_create()` when they write, `signup()`,
|
|
45
|
+
`define_computed_fields()` and `define_access()`. Reads whose subqueries read those tables go
|
|
46
|
+
too; a read that follows links (`fetch()`, a dotted path, a `select()` item that is not a plain
|
|
47
|
+
field) is removed by any ORM write, and a read of an edge model by any delete. Inside
|
|
48
|
+
`transaction()` the written tables are invalidated at commit (a failed commit too, nothing on
|
|
49
|
+
rollback). While a write runs, reads of its tables go to the database and store nothing.
|
|
50
|
+
- **One cache scope per connection and identity**: a sign-in, a sign-up, `authenticate()` or
|
|
51
|
+
`invalidate()` starts a new scope and drops the previous identity's results; another event loop's
|
|
52
|
+
connection, a reconnect and an `embedded_database()` block start empty; closing a connection
|
|
53
|
+
drops its results. Cached results never cross identities.
|
|
54
|
+
- **`QueryCache`**: `configure(default_ttl=60, max_size=1000, enabled=True)` sets all three
|
|
55
|
+
settings at every call, as in the full ORM, and never clears; `enabled=False` hides the entries
|
|
56
|
+
(`cache()` reads go to the database and calling `cache()` logs a warning). Past `max_size` the
|
|
57
|
+
least recently used entry is evicted. `invalidate()` takes a model class or a table name and
|
|
58
|
+
returns how many entries it removed; `clear()` drops every entry and resets the counters;
|
|
59
|
+
`stats()` returns `entries`, `tables`, `max_size`, `default_ttl`, `enabled`, `hits` and
|
|
60
|
+
`misses`. `make_key()`, `get()` and `set()` cache your own results (of `raw_query()`, say),
|
|
61
|
+
tagged with a table so that an ORM write to it removes them; `get()` misses while such a write
|
|
62
|
+
runs.
|
|
63
|
+
- **Refusals**: `query()` raises `SurrealDbError` on a queryset with `cache()`; `live()`, `watch()`
|
|
64
|
+
and `changes()` name `cache()` among the clauses their usual error refuses; combining `cache()`
|
|
65
|
+
with `as_of()` raises `SurrealDbError`, in either order. A negative or non-finite TTL raises
|
|
66
|
+
`ValueError`, anything but a number or a `timedelta` (`True` included) `TypeError`.
|
|
67
|
+
- README section 29, "Query cache (`cache()`, `QueryCache`)" (what is cached, the time to live,
|
|
68
|
+
invalidation and what the cache cannot see, one cache per connection and identity,
|
|
69
|
+
configuration and statistics, a note for users of the full SurrealDB-ORM), a features row, a
|
|
70
|
+
row in the 2.x/3.x behaviour table, the comparison and roadmap rows, and the example notebook
|
|
71
|
+
`examples/v0.28.0_query_cache.ipynb`.
|
|
72
|
+
|
|
73
|
+
### Changed
|
|
74
|
+
|
|
75
|
+
- ORM writes now also remove the cached reads they can change, in memory, without a request.
|
|
76
|
+
Without `cache()`, every read and write sends the same requests as in v0.27.x; the texts of the
|
|
77
|
+
`live()`, `watch()` and `changes()` refusals are unchanged.
|
|
78
|
+
|
|
79
|
+
### Notes
|
|
80
|
+
|
|
81
|
+
- **Same on SurrealDB 2.x and 3.x**, and on the embedded engine. Reads inside a transaction
|
|
82
|
+
(`objects(tx=)`) are never cached: on 3.x an interactive transaction's reads see its uncommitted
|
|
83
|
+
writes, and on 2.x a buffered transaction cannot read.
|
|
84
|
+
- **What the cache cannot see** (the TTL bounds it; `QueryCache.invalidate(Model)` removes a
|
|
85
|
+
table's entries after such a change): writes by another process or client; raw SurrealQL
|
|
86
|
+
(`raw_query()`, `QuerySet.query()`, `call_function()`, `Transaction.add()`); a write whose task
|
|
87
|
+
is cancelled, or that fails client-side, after its request was sent; writes made by an access
|
|
88
|
+
method's own `SIGNIN`/`SIGNUP` clauses beyond the record they create; what the server derives on
|
|
89
|
+
its own (`DEFINE EVENT`, `REFERENCE … ON DELETE` on 3.x, views, `PERMISSIONS` that read another
|
|
90
|
+
table); values computed when the read runs (a `DEFINE PARAM` read with `Var()`,
|
|
91
|
+
`<future>`/`COMPUTED` fields, time functions in a `select()` expression); a table of relations
|
|
92
|
+
read through a model that is not a `BaseSurrealEdge`. A session changed behind the ORM's back
|
|
93
|
+
(`raw_query("USE …")`, `signin()` or `use()` on the SDK client) is not seen either: call
|
|
94
|
+
`QueryCache.clear()` after it.
|
|
95
|
+
- **Memory**: cached rows stay in this process's memory until they expire, are evicted,
|
|
96
|
+
invalidated or cleared, or their connection closes. `configure(enabled=False)` only hides them;
|
|
97
|
+
`QueryCache.clear()` drops them. Entries stored with `QueryCache.set()` are not scoped to a
|
|
98
|
+
connection or an identity: put whatever tells your callers apart in the key.
|
|
99
|
+
- **Keys** are the SHA-256 of the CBOR bytes the official SDK sends, with the keys of mappings
|
|
100
|
+
sorted: `RecordID("user", 1)` and `"user:1"` never share an entry. An SDK that exposes no CBOR
|
|
101
|
+
encoder sends every `cache()` read to the database (one warning per process).
|
|
102
|
+
- Concurrent misses of the same read each send their own request.
|
|
103
|
+
- **Differences from the full SurrealDB-ORM**: every read is cached, not only `exec()`, `first()`
|
|
104
|
+
and `get()` by filters; invalidation is built in and covers bulk operations, `QuerySet.patch()`,
|
|
105
|
+
the atomic operations, relations and transactions, where the full ORM listens to `post_save`,
|
|
106
|
+
`post_update` and `post_delete`; rows are cached instead of instances; one scope per connection
|
|
107
|
+
and identity; `live()`, `watch()`, `changes()` and `query()` refuse `cache()`; the TTL may be a
|
|
108
|
+
`float` or a `timedelta` and negative values are refused; LRU eviction instead of FIFO;
|
|
109
|
+
`invalidate()` takes a table name too; `stats()` adds `hits` and `misses`.
|
|
110
|
+
- Not available yet: invalidation from other processes or clients (through live queries),
|
|
111
|
+
caching `as_of()` reads, sharing cached results between event loops.
|
|
112
|
+
- **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, and on the embedded engine,
|
|
113
|
+
plus 3.1.5 for backward compatibility (identical).
|
|
114
|
+
|
|
115
|
+
## [0.27.0] - 2026-10-16
|
|
116
|
+
|
|
117
|
+
Subqueries: a QuerySet filters another, as `Subquery(qs)` or the queryset itself, compiled to a
|
|
118
|
+
sub-`SELECT` the server runs inside the outer statement: one request, one consistent read, every
|
|
119
|
+
inner value bound. The fifth minor of Tier 2.
|
|
120
|
+
|
|
121
|
+
### Added
|
|
122
|
+
|
|
123
|
+
- **`Subquery(qs)`**, exported from `surreal_orm_lite` (the full SurrealDB-ORM's name), and a
|
|
124
|
+
QuerySet given directly as a filter value, in `filter()` and in `Q` (`&`, `|`, `~`, any nesting).
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
from surreal_orm_lite import Q, Subquery
|
|
128
|
+
|
|
129
|
+
active = Person.objects().filter(active=True)
|
|
130
|
+
posts = await Post.objects().filter(author__in=Subquery(active)).exec()
|
|
131
|
+
same = await Post.objects().filter(author__in=active).exec() # a QuerySet is a subquery
|
|
132
|
+
|
|
133
|
+
best = Post.objects().select("score").order_by("-score").limit(1)
|
|
134
|
+
top = await Post.objects().filter(score=Subquery(best)).exec() # compared with its first value
|
|
135
|
+
|
|
136
|
+
inactive = Person.objects().filter(active=False)
|
|
137
|
+
mixed = await Post.objects().filter(Q(author__in=inactive) | Q(score__gte=9)).exec()
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
- **Lookups.** `in`, `not_in`, `containsall` and `containsany` compare the field with all the
|
|
141
|
+
subquery's values; `exact` (no suffix), `gt`, `gte`, `lt`, `lte`, `contains` and `not_contains`
|
|
142
|
+
with its first value (order the subquery to choose it). A first-value lookup on an empty
|
|
143
|
+
subquery matches no record, and `~Q(...)` of it every record; for `in`, an empty subquery is an
|
|
144
|
+
empty list.
|
|
145
|
+
- **What the inner queryset selects**: its record ids without `select()` (`SELECT VALUE id`), or
|
|
146
|
+
the values of the one field given to `select()` (an aliased field compiles its column). Its
|
|
147
|
+
`filter()`, `Q`, `nearby()`, `order_by()`, `limit()`, `offset()` and `variables()` apply; its
|
|
148
|
+
`fetch()` is ignored, as in the full ORM. Values are compared as stored, never converted: to
|
|
149
|
+
match records, select `id` or a record link.
|
|
150
|
+
- **Where it applies**: `exec()`, `first()`, `get()` with filters, `exists()`, `count()`, `sum()`,
|
|
151
|
+
`avg()`, `min()`, `max()`, `values(…).annotate(…)` and `annotate(GeoDistance)`; the writes by
|
|
152
|
+
filter `bulk_update()`, `bulk_delete()` and `QuerySet.patch()`; the lookups of `get_or_create()`
|
|
153
|
+
and `update_or_create()`. Subqueries nest. In `Model.objects(tx=tx)` the statement runs in the
|
|
154
|
+
transaction, and an interactive transaction's subquery sees its uncommitted writes. Under
|
|
155
|
+
`as_of()` every subquery reads at the same moment. `live()` and `watch()` write the sub-SELECT
|
|
156
|
+
inline, and the server evaluates it again on every change. `changes()` refuses `filter()`, so
|
|
157
|
+
subqueries too.
|
|
158
|
+
- **Refusals before any request** (`live()` and `watch()` at the call). `ValueError`: a lookup
|
|
159
|
+
that takes no subquery (`isnull`, `like`, `ilike`, `startswith`, `endswith`, `match`, `regex`,
|
|
160
|
+
`inside`, `outside`, `intersects`), a queryset that is its own subquery, an inner `values()`,
|
|
161
|
+
`annotate()` or `select()` of several fields, an inner `limit()` or `offset()` that is not an
|
|
162
|
+
`int >= 0`, an inner `order_by()` on `_sqv` it does not select, an inner `variables()` binding a
|
|
163
|
+
name of the statement to another value, a subquery inside a list, `Q(...).to_sql()` called on its
|
|
164
|
+
own with a subquery, and `bulk_update(score=Subquery(qs))`. `SurrealDbError`: an inner `as_of()`
|
|
165
|
+
(call it on the outer queryset), an inner `objects(tx=)` whose transaction is not the outer
|
|
166
|
+
one's, and a subquery as an `exact` criterion or a `defaults=` value of `get_or_create()` or
|
|
167
|
+
`update_or_create()`. `TypeError`: `Subquery(x)` for anything but a QuerySet.
|
|
168
|
+
- README section 28, "Subqueries (`Subquery`)" (what a subquery selects, the lookups, ordered and
|
|
169
|
+
limited subqueries, where subqueries apply, what they cannot do, a note for users of the full
|
|
170
|
+
SurrealDB-ORM), a bullet in the supported lookups, a `Q` example in section 5, four rows in the
|
|
171
|
+
2.x/3.x behaviour table, and the example notebook `examples/v0.27.0_subqueries.ipynb`.
|
|
172
|
+
|
|
173
|
+
### Changed
|
|
174
|
+
|
|
175
|
+
- A QuerySet given as a filter value is now a subquery. v0.26.x refused it: `in` and `not_in`
|
|
176
|
+
raised `ValueError` ("requires an iterable") and the other lookups failed when the SDK encoded
|
|
177
|
+
the request. Every call that worked in v0.26.x behaves the same.
|
|
178
|
+
- `Q.to_sql()` gains a keyword-only `subqueries` parameter (default `None`), the compiler of the
|
|
179
|
+
statement the QuerySet sends; a `Q` compiled on its own refuses a subquery lookup.
|
|
180
|
+
|
|
181
|
+
### Notes
|
|
182
|
+
|
|
183
|
+
- **One statement per request, a block of `LET`s**:
|
|
184
|
+
`{ LET $_sq0 = (SELECT VALUE id FROM Person WHERE active = $_f0); (SELECT * FROM Post WHERE author IN $_sq0) };`.
|
|
185
|
+
Each subquery is bound once, innermost first, because SurrealDB 3.2 and later can return wrong
|
|
186
|
+
rows for an inline sub-SELECT with `ORDER BY` and `LIMIT`
|
|
187
|
+
([surrealdb/surrealdb#7470](https://github.com/surrealdb/surrealdb/issues/7470)), and because the
|
|
188
|
+
official SDK's `query()` returns the first statement's result only, so the full ORM's `LET`
|
|
189
|
+
prelude (two statements) does not fit. An ordered subquery selects its column as `_sqv` with its
|
|
190
|
+
order fields: SurrealDB 2.x refuses to order a one-column sub-SELECT by another field. `$_sq0`,
|
|
191
|
+
`$_sq1`, … are reserved in such a statement and hide a `variables()` value of the same name.
|
|
192
|
+
- **A first-value lookup on an empty subquery matches no record**: SurrealDB alone would compare
|
|
193
|
+
with `array::first([])`, which is `NONE`, and `score > NONE` holds for every record, so the ORM
|
|
194
|
+
guards the comparison. The full SurrealDB-ORM matches every record there.
|
|
195
|
+
- **A subquery table that does not exist reads as empty**, like any missing table. SurrealDB 2.x
|
|
196
|
+
and the embedded engine read it so in the same request. On SurrealDB 3.x the ORM asks the server
|
|
197
|
+
whether the table exists and, once it confirms the table does not, sends the statement again
|
|
198
|
+
with that subquery empty: three requests, and only then. Any other error, even one quoting
|
|
199
|
+
"does not exist", is relayed. On 3.x a write by filter in a transaction fails with the server's
|
|
200
|
+
error, and `live()` raises `SurrealDbNotFoundError` before it starts (3.x would accept the live
|
|
201
|
+
query and never notify).
|
|
202
|
+
- **Transactions**: a buffered transaction (2.x, or HTTP) still cannot read, and applies writes by
|
|
203
|
+
filter at commit. Build the inner queryset with the same `objects(tx=)`, or with none.
|
|
204
|
+
- **Time travel**: without versioned storage, a subquery read under `as_of()` raises v0.26.0's
|
|
205
|
+
`SurrealDbError`; SurrealDB 3.1.5 raises the server's own `ThrownError` instead.
|
|
206
|
+
- Not available yet: `annotate(x=Subquery(...))`, correlated subqueries (`OuterRef`, `$parent`)
|
|
207
|
+
and `Exists`.
|
|
208
|
+
- **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, in memory and on versioned
|
|
209
|
+
storage, and on the embedded engine, plus 3.1.5 for backward compatibility (identical except the
|
|
210
|
+
time-travel error above).
|
|
211
|
+
|
|
8
212
|
## [0.26.0] - 2026-10-16
|
|
9
213
|
|
|
10
214
|
Time travel: a QuerySet reads a model's records as they were at a past moment, with
|