surreal-orm-lite 0.24.3__tar.gz → 0.26.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.
Files changed (38) hide show
  1. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/CHANGELOG.md +252 -0
  2. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/PKG-INFO +599 -22
  3. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/README.md +598 -21
  4. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/_sdk.py +14 -0
  7. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/changefeed.py +10 -1
  8. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/connection_manager.py +640 -84
  9. surreal_orm_lite-0.26.0/src/surreal_orm_lite/embedded.py +151 -0
  10. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/live.py +7 -0
  11. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/model_auth.py +279 -26
  12. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/model_base.py +107 -13
  13. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/query_set.py +317 -40
  14. surreal_orm_lite-0.26.0/src/surreal_orm_lite/testing/__init__.py +28 -0
  15. surreal_orm_lite-0.26.0/src/surreal_orm_lite/testing/database.py +59 -0
  16. surreal_orm_lite-0.26.0/src/surreal_orm_lite/testing/fixtures.py +139 -0
  17. surreal_orm_lite-0.26.0/src/surreal_orm_lite/time_travel.py +264 -0
  18. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/utils.py +3 -2
  19. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/.gitignore +0 -0
  20. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/LICENSE +0 -0
  21. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/Makefile +0 -0
  22. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/aggregations.py +0 -0
  23. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/auth.py +0 -0
  24. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/concurrency.py +0 -0
  25. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/constants.py +0 -0
  26. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/decoding.py +0 -0
  27. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/edge.py +0 -0
  28. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/encoding.py +0 -0
  29. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/enum.py +0 -0
  30. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/exceptions.py +0 -0
  31. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/functions.py +0 -0
  32. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/geo.py +0 -0
  33. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/py.typed +0 -0
  34. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/q.py +0 -0
  35. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/signals.py +0 -0
  36. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/surql_literal.py +0 -0
  37. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/transaction.py +0 -0
  38. {surreal_orm_lite-0.24.3 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/types.py +0 -0
@@ -5,6 +5,258 @@ 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.26.0] - 2026-10-16
9
+
10
+ Time travel: a QuerySet reads a model's records as they were at a past moment, with
11
+ `as_of()` (SurrealQL's `VERSION` clause), on the official SDK's embedded
12
+ `surrealkv+versioned://` engine and on SurrealDB servers started with versioned storage. The
13
+ fourth minor of Tier 2.
14
+
15
+ ### Added
16
+
17
+ - **`QuerySet.as_of(at)`** adds a moment to every read of the queryset. Records updated since
18
+ read as they were, a record deleted since is still found, and one created later is not. The
19
+ store must keep history: the embedded `surrealkv+versioned://<path>` (no server), SurrealDB 3.x
20
+ started on `surrealkv://<path>?versioned=true` or `rocksdb://<path>?versioned=true`, or
21
+ SurrealDB 2.x started on `surrealkv+versioned://<path>`.
22
+
23
+ ```python
24
+ from surreal_orm_lite import BaseSurrealModel, SurrealDBConnectionManager
25
+
26
+ class Product(BaseSurrealModel):
27
+ id: str | None = None
28
+ name: str
29
+ price: float
30
+
31
+ SurrealDBConnectionManager.set_connection(
32
+ url=f"surrealkv+versioned://{path}/shop", namespace="shop", database="shop"
33
+ )
34
+ client = await SurrealDBConnectionManager.get_client()
35
+
36
+ lamp = Product(id="lamp", name="Lamp", price=40.0)
37
+ await lamp.save()
38
+ opening = await client.query("RETURN time::now();") # a moment, from the database's clock
39
+ await lamp.merge(price=30.0)
40
+
41
+ assert (await Product.objects().as_of(opening).get("lamp")).price == 40.0
42
+ assert (await Product.objects().get("lamp")).price == 30.0
43
+ ```
44
+
45
+ - **The moment** is an aware `datetime` (any time zone) or a naive one (UTC), an ISO-8601 string
46
+ (parsed by the ORM; a date alone is midnight UTC), a `timedelta` or the ORM's `Duration` (that
47
+ long before the database's clock), a `SurrealFunc` the database evaluates
48
+ (`SurrealFunc("time::now() - 1h")`), or `None` (the current state again); called again, the last
49
+ moment wins. The moment is always a bound parameter. A moment outside the instants SurrealDB
50
+ versions can address (1970-01-01T00:00:00Z to 2262-04-11T23:47:16.854775Z) is refused on every
51
+ line: `ValueError` at the call, or `SurrealDbError` before the read for a duration or an
52
+ expression the database resolved there.
53
+ - **Every read honours it**, with `filter()`, `Q`, `nearby()`, `order_by()`, `limit()`, `offset()`,
54
+ `select()` and `variables()`, on edge models too: `exec()`, `first()`, `get()` (with filters or by
55
+ id), `all()`, `exists()`, `count()`, `sum()`, `avg()`, `min()`, `max()`, `values(…).annotate(…)`
56
+ and `annotate(d=GeoDistance(…))`.
57
+ - **Snapshots.** The instances a time-travel read returns are read-only: `save()`, `update()`,
58
+ `merge()`, `patch()`, `upsert()`, `delete()`, the `atomic_*()` methods, `relate()`,
59
+ `remove_relation()` and `remove_all_relations()` raise `SurrealDbError` before any signal or
60
+ request, and `bulk_create()` refuses a snapshot in its list. `refresh()` turns a snapshot back
61
+ into the current record; `Product(**snapshot.model_dump()).update()` (or `.save()` for a record
62
+ deleted since, or `.upsert()`) writes a past state back. `model_copy()` and `pickle` keep the
63
+ snapshot, and a snapshot is never `==` the current instance (compare `model_dump()`s). A record
64
+ model nested in a snapshot's fields is a snapshot too, such as a link `fetch()` resolves into a
65
+ model-typed field on SurrealDB 3.x; its own `refresh()` makes it the current record.
66
+ - **Refusals before any request.** On a queryset with `as_of()`: `bulk_create()`, `bulk_update()`,
67
+ `bulk_delete()`, `patch()`, `update_or_create()`, `get_or_create()`, `delete_table()`, `query()`,
68
+ `live()`, `watch()` and `changes()` raise `SurrealDbError`; `Model.objects(tx=...).as_of(...)`
69
+ raises at the call (history cannot join a transaction); on the embedded engine, a URL that keeps
70
+ no history (`mem://`, `memory://`, `surrealkv://`, `file://`) raises, naming
71
+ `surrealkv+versioned://`. A 3.x server without versioned storage refuses the read, raised as
72
+ `SurrealDbError` with the SDK's error as its `__cause__`.
73
+ - README section 27, "Time travel (`as_of()`)" (stores that keep history, the moment, reads,
74
+ snapshots, refusals, SurrealDB 2.x without versioned storage, record links, writing history with
75
+ a raw `CREATE … VERSION`, a note for users of the full SurrealDB-ORM, which has no time travel),
76
+ new rows in both behaviour tables, and the example notebook `examples/v0.26.0_time_travel.ipynb`.
77
+
78
+ ### Changed
79
+
80
+ - `BaseSurrealModel` declares a private attribute, the snapshot marker, so every instance now has
81
+ a `__pydantic_private__` dict. Two current instances compare as before; an instance pickled by
82
+ v0.25.x unpickles as a current record, and a model's own private attributes are kept.
83
+ - `refresh()` also clears the snapshot marker of an instance read with `as_of()`.
84
+ - CI starts a second SurrealDB per job, on versioned storage, for the time-travel tests; they find
85
+ it through `SURREALDB_VERSIONED_PORT` and skip without it.
86
+
87
+ ### Notes
88
+
89
+ - **Every time-travel table read also reads each record by its id at the moment**, because a plain
90
+ `SELECT … VERSION` is wrong on both server lines: SurrealDB 3.x's table reads return the records
91
+ deleted before the moment, in their last state, and SurrealDB 2.x and the embedded engine
92
+ miscount an unfiltered `count()`. It costs about one extra point read per record scanned; a read
93
+ by id needs no check.
94
+ - **SurrealDB 2.x without versioned storage answers without an error**: in memory or on plain
95
+ SurrealKV, it returns only the records last written at or before the moment, in their current
96
+ state, and the ORM cannot tell which storage the server runs. Start 2.x with
97
+ `surrealkv+versioned://` for time travel. SurrealDB 2.x on RocksDB refuses `VERSION`
98
+ (`SurrealDbError`).
99
+ - **Record links**: `fetch()` resolves links as they were on SurrealDB 3.x, into read-only
100
+ snapshots. On SurrealDB 2.x (servers and the SDK 2.x embedded engine) they resolve to their
101
+ current state, so `exec()`, `first()` and `get()` without an id refuse `fetch()` under
102
+ `as_of()`; a dotted path through a link reads the current value there.
103
+ - **Writing history at a past moment** is left to raw queries (`CREATE … VERSION d'…'`, one
104
+ statement per `client.query()` call): stored at that moment and readable with `as_of()` on
105
+ SurrealDB 2.x and the embedded engine; accepted but not readable at that moment on SurrealDB 3.x.
106
+ - The surrealdb SDK 2.x embedded engine ignores `?versioned=true` on `surrealkv://`: use
107
+ `surrealkv+versioned://`. The SDK's own `surrealdb.Duration` is accepted at runtime only (the
108
+ annotation names the ORM's types). `_as_of` is a reserved `variables()` name on a time-travel
109
+ read: the moment is bound under it.
110
+ - A `SurrealFunc` moment is sent as written: build it in your code, never from user input, and pass
111
+ user values through `variables()`, bound.
112
+ - **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, in memory and on versioned
113
+ storage, plus 3.1.5 for backward compatibility (identical); the embedded tests run in every CI
114
+ job. Every existing call behaves as in v0.25.x.
115
+
116
+ ## [0.25.0] - 2026-10-15
117
+
118
+ Embedded test engine: the ORM also runs on the official SDK's in-process SurrealDB engine
119
+ (`mem://`, `surrealkv://<path>`), with no server and no Docker, and the new
120
+ `surreal_orm_lite.testing` module adds `embedded_database()` and the full SurrealDB-ORM's
121
+ `SurrealFixture` / `@fixture`. The same models and queries run unchanged against a server. The
122
+ third minor of Tier 2.
123
+
124
+ ### Added
125
+
126
+ - **Embedded URLs.** With
127
+ `SurrealDBConnectionManager.set_connection(url="mem://", namespace=…, database=…)`, every ORM
128
+ call runs in-process: CRUD, QuerySet, aggregations, relations, typed edges, rich and geo fields,
129
+ upsert and patch, server values, computed fields, stored functions, buffered transactions,
130
+ change feeds and authentication. The SDK sends `mem://`, `memory://`,
131
+ `surrealkv://<path>`, `surrealkv+versioned://<path>` and `file://<path>` (a SurrealKV store) to
132
+ its engine; the ORM asks the SDK's own URL parser and keeps no list of schemes. `user` and
133
+ `password` are optional on an embedded URL and never sent: the engine's anonymous session is the
134
+ in-process owner. They are kept, so one configuration switches between a server and `mem://` by
135
+ its URL alone:
136
+
137
+ ```python
138
+ from surreal_orm_lite import BaseSurrealModel, SurrealDBConnectionManager
139
+
140
+ SurrealDBConnectionManager.set_connection(url="mem://", namespace="app", database="app")
141
+
142
+ class Note(BaseSurrealModel):
143
+ id: str | None = None
144
+ title: str
145
+
146
+ await Note(id="docs", title="Write the docs").save()
147
+ assert await Note.objects().count() == 1
148
+ assert SurrealDBConnectionManager.is_embedded()
149
+ ```
150
+
151
+ - **`SurrealDBConnectionManager.is_embedded()`**: whether the configured URL addresses the
152
+ in-process engine, for code that must run on both kinds of connection.
153
+ - **One engine per process.** The manager opens the engine on the first call and hands it to every
154
+ event loop and thread, so they all see the same database; concurrent first calls open exactly
155
+ one. A namespace or database change resets the shared session and selects the new pair on the
156
+ same engine, with no data lost; a new URL closes the old engine. Closing
157
+ (`close_connection()`, `close_all_connections()`, `unset_connection()`, `reconnect()`, the exit
158
+ of `async with SurrealDBConnectionManager():`) discards a `mem://` database, and a
159
+ `surrealkv://` one reopens with its data. `validate_connection()` never discards it. Server
160
+ clients are untouched while an embedded URL is configured: `close_connection()`, `reconnect()`
161
+ and the `async with` exit then close only the engine, so a server client keeps its live queries
162
+ and its identity, even one signed in with `store=False`, and `is_connected()` stays true on its
163
+ event loop; `close_all_connections()` and `unset_connection()` close it too. An event loop whose
164
+ server connection dropped while signed in with `store=False` still raises once the server URL is
165
+ set back with `set_url()`, or after an `embedded_database()` block: neither closing the engine
166
+ nor an identity set on it ends that state. `set_connection()` does: a new configuration is a
167
+ choice of identity.
168
+ - **Clear errors, before any request, for what the engine cannot do**: live queries (`live()`,
169
+ `watch()`, `subscribe_live()`: read the table's change feed with `changes()` instead),
170
+ `changes(since=<datetime>)` (pass a cursor or `since=None`), and `AuthenticatedUserMixin` calls
171
+ with `bind=False` and `ephemeral_client()` (the engine has a single session per database). Each
172
+ raises `SurrealDbError`.
173
+ - **Authentication on the engine.** `signin()`, `signup()`, `authenticate()` and `invalidate()`
174
+ work with the engine's record access methods and `DEFINE USER`s, and record users and table
175
+ `PERMISSIONS` apply as on a server. A sign-in changes the session of the whole process (every
176
+ event loop and thread); `invalidate()` and a namespace or database change return it to the
177
+ in-process owner and end the stored session. Model auth with `bind=True` signs that session in,
178
+ one call at a time with the connection-level calls (the last one wins), and a failed call puts
179
+ the previous session back, with one exception, as on a server: when `signup()` or `signin()`
180
+ succeeded but the record does not fit the model, the session stays signed in as that record
181
+ (the error says so). `refresh()` cannot succeed on the engine: its SurrealQL does not parse
182
+ `WITH REFRESH`.
183
+ - **`surreal_orm_lite.testing`**, a new module that does not import pytest:
184
+ - `embedded_database(url="mem://", *, namespace="test", database="test")` runs a block against
185
+ an isolated in-process database, yields the block's SDK client (valid inside the block only),
186
+ then puts the previous connection back: its settings, stored session and engine. Blocks nest;
187
+ `surrealkv://<path>` gives an on-disk database. A server URL raises `ValueError`.
188
+ - `SurrealFixture` and `@fixture`, with the full SurrealDB-ORM's names: `load()` saves a fresh
189
+ copy of each declared instance in declaration order, yields them typed as the fixture class,
190
+ and deletes them on exit. It works on any connection, a server or the engine. Unlike the full
191
+ ORM, an explicit `id` is kept, a save that fails or is cancelled mid-load deletes the copies
192
+ already saved, `@fixture` raises `TypeError` on a class that is not a `SurrealFixture`
193
+ subclass, and `load()` raises `ValueError` on an undecorated subclass of a fixture that
194
+ declares instances of its own (the full ORM loads only the parent's).
195
+
196
+ ```python
197
+ from surreal_orm_lite.testing import SurrealFixture, embedded_database, fixture
198
+
199
+ @fixture
200
+ class UserFixtures(SurrealFixture):
201
+ alice = User(name="Alice", role="admin")
202
+ bob = User(id="bob", name="Bob", role="player") # an explicit id is kept
203
+
204
+ async with embedded_database(): # a fresh, empty in-memory database
205
+ async with UserFixtures.load() as fixtures:
206
+ admins = await User.objects().filter(role="admin").exec()
207
+ assert [admin.name for admin in admins] == ["Alice"]
208
+ assert await User.objects().count() == 0 # alice and bob are deleted
209
+ ```
210
+
211
+ - README section 26, "Embedded engine and test fixtures" (in-process databases and the embedded
212
+ URL table, one engine per process, what the engine does not do, its SurrealQL line, identity,
213
+ test fixtures with a pytest recipe, a note for users of the full SurrealDB-ORM), and a new
214
+ behaviour table, "ORM behaviour: the embedded engine"; example notebook
215
+ `examples/v0.25.0_embedded_test_engine.ipynb`.
216
+
217
+ ### Changed
218
+
219
+ - `set_connection()`: `user`, `password`, `namespace` and `database` default to `None`, in the same
220
+ positional order. `is_connection_set()` needs the user and password for a server URL only.
221
+ - A URL the installed SDK refuses (`rocksdb://`, a typo) is still accepted by `set_connection()`;
222
+ the first ORM call now raises a `SurrealDbConnectionError` that quotes the SDK, before anything
223
+ is opened, instead of "Connection not been set." or "Can't connect to the database.". For
224
+ `rocksdb://` it points to #233.
225
+ - The DDL helpers (`define_computed_fields()`, `define_access()`) raise their usual
226
+ `SurrealDbError` for a statement the embedded engine cannot parse, which SDK 2.0.0 reports as a
227
+ bare `RuntimeError`.
228
+ - The `SurrealDbError` of an `AuthenticatedUserMixin` call whose record does not fit the model
229
+ (since v0.17.0) has a new text, on every path, the server lines included: it says whether the
230
+ shared session kept its previous identity or is now signed in as that record (for `refresh()`,
231
+ also that the refresh token passed in is spent and whether the new pair is kept), and it names
232
+ the fields that do not fit and Pydantic's error codes (`nickname: missing; prefs: int_parsing`),
233
+ and quotes nothing from the record: no value, and no key the model does not declare (listed as
234
+ `(undeclared field)`). The Pydantic `ValidationError` is its `__context__` instead of its
235
+ `__cause__`.
236
+
237
+ ### Notes
238
+
239
+ - **The engine is SurrealDB core 2.3.10**, bundled with the surrealdb SDK 2.0.0 base wheel (no
240
+ new dependency, every supported Python version): write 2.x SurrealQL in raw queries and computed
241
+ fields, and expect the 2.x column of the behaviour table. `client.version()` reports the SDK's
242
+ version (`surrealdb-2.0.0`). Transactions are buffered, and parse errors in raw queries are a bare
243
+ `RuntimeError`. The SDK 3.0 line bundles a 3.x engine in the `surrealdb[embedded]` extra (#205).
244
+ - **`rocksdb://` is not yet supported by the official SDK** (#233): the ORM relays the SDK's
245
+ refusal and will accept the scheme with no change once a released SDK does. A bare `memory` (no
246
+ `://`) is refused by SDK 2.0.0: write `memory://`. `surrealkv+versioned://` behaves as
247
+ `surrealkv://` until time travel (v0.26.0).
248
+ - **With the surrealdb SDK 2.x, closing does not stop an in-process engine**: a client obtained
249
+ before `close_connection()` or inside an `embedded_database()` block is still a running
250
+ database. Do not use it after the close, drop it (`del client`) before reopening the same
251
+ `surrealkv://` path, and never open one path from two processes.
252
+ - A fresh engine raises a retryable write conflict when several writes run concurrently on a table
253
+ that does not exist yet: define the table first, or use `@retry_on_conflict()`.
254
+ - The v0.24.3 read hook (#235) also applies to the embedded engine's client: zero durations and
255
+ degenerate geometries read as on a server. A `<set>[…]` is stored as an array there, as on 2.x.
256
+ - **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0 (the CI pins), plus 3.1.5
257
+ for backward compatibility; the embedded tests run in every CI job. `ModelFactory` and
258
+ `Faker` come in v0.39.0.
259
+
8
260
  ## [0.24.3] - 2026-10-15
9
261
 
10
262
  The clients the ORM opens now read the values the surrealdb SDK 2.0.0 cannot decode (zero