surreal-orm-lite 0.24.2__tar.gz → 0.25.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 (37) hide show
  1. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/CHANGELOG.md +200 -0
  2. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/PKG-INFO +405 -51
  3. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/README.md +404 -50
  4. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/_sdk.py +39 -1
  7. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/changefeed.py +10 -1
  8. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/connection_manager.py +645 -80
  9. surreal_orm_lite-0.25.0/src/surreal_orm_lite/decoding.py +338 -0
  10. surreal_orm_lite-0.25.0/src/surreal_orm_lite/embedded.py +124 -0
  11. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/encoding.py +19 -27
  12. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/geo.py +4 -0
  13. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/live.py +7 -0
  14. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/model_auth.py +279 -26
  15. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/query_set.py +6 -3
  16. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/surql_literal.py +11 -7
  17. surreal_orm_lite-0.25.0/src/surreal_orm_lite/testing/__init__.py +28 -0
  18. surreal_orm_lite-0.25.0/src/surreal_orm_lite/testing/database.py +59 -0
  19. surreal_orm_lite-0.25.0/src/surreal_orm_lite/testing/fixtures.py +139 -0
  20. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/utils.py +3 -2
  21. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/.gitignore +0 -0
  22. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/LICENSE +0 -0
  23. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/Makefile +0 -0
  24. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/aggregations.py +0 -0
  25. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/auth.py +0 -0
  26. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/concurrency.py +0 -0
  27. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/constants.py +0 -0
  28. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/edge.py +0 -0
  29. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/enum.py +0 -0
  30. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/exceptions.py +0 -0
  31. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/functions.py +0 -0
  32. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/model_base.py +0 -0
  33. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/py.typed +0 -0
  34. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/q.py +0 -0
  35. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/signals.py +0 -0
  36. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/transaction.py +0 -0
  37. {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/types.py +0 -0
@@ -5,6 +5,206 @@ 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.25.0] - 2026-10-15
9
+
10
+ Embedded test engine: the ORM also runs on the official SDK's in-process SurrealDB engine
11
+ (`mem://`, `surrealkv://<path>`), with no server and no Docker, and the new
12
+ `surreal_orm_lite.testing` module adds `embedded_database()` and the full SurrealDB-ORM's
13
+ `SurrealFixture` / `@fixture`. The same models and queries run unchanged against a server. The
14
+ third minor of Tier 2.
15
+
16
+ ### Added
17
+
18
+ - **Embedded URLs.** With
19
+ `SurrealDBConnectionManager.set_connection(url="mem://", namespace=…, database=…)`, every ORM
20
+ call runs in-process: CRUD, QuerySet, aggregations, relations, typed edges, rich and geo fields,
21
+ upsert and patch, server values, computed fields, stored functions, buffered transactions,
22
+ change feeds and authentication. The SDK sends `mem://`, `memory://`,
23
+ `surrealkv://<path>`, `surrealkv+versioned://<path>` and `file://<path>` (a SurrealKV store) to
24
+ its engine; the ORM asks the SDK's own URL parser and keeps no list of schemes. `user` and
25
+ `password` are optional on an embedded URL and never sent: the engine's anonymous session is the
26
+ in-process owner. They are kept, so one configuration switches between a server and `mem://` by
27
+ its URL alone:
28
+
29
+ ```python
30
+ from surreal_orm_lite import BaseSurrealModel, SurrealDBConnectionManager
31
+
32
+ SurrealDBConnectionManager.set_connection(url="mem://", namespace="app", database="app")
33
+
34
+ class Note(BaseSurrealModel):
35
+ id: str | None = None
36
+ title: str
37
+
38
+ await Note(id="docs", title="Write the docs").save()
39
+ assert await Note.objects().count() == 1
40
+ assert SurrealDBConnectionManager.is_embedded()
41
+ ```
42
+
43
+ - **`SurrealDBConnectionManager.is_embedded()`**: whether the configured URL addresses the
44
+ in-process engine, for code that must run on both kinds of connection.
45
+ - **One engine per process.** The manager opens the engine on the first call and hands it to every
46
+ event loop and thread, so they all see the same database; concurrent first calls open exactly
47
+ one. A namespace or database change resets the shared session and selects the new pair on the
48
+ same engine, with no data lost; a new URL closes the old engine. Closing
49
+ (`close_connection()`, `close_all_connections()`, `unset_connection()`, `reconnect()`, the exit
50
+ of `async with SurrealDBConnectionManager():`) discards a `mem://` database, and a
51
+ `surrealkv://` one reopens with its data. `validate_connection()` never discards it. Server
52
+ clients are untouched while an embedded URL is configured: `close_connection()`, `reconnect()`
53
+ and the `async with` exit then close only the engine, so a server client keeps its live queries
54
+ and its identity, even one signed in with `store=False`, and `is_connected()` stays true on its
55
+ event loop; `close_all_connections()` and `unset_connection()` close it too. An event loop whose
56
+ server connection dropped while signed in with `store=False` still raises once the server URL is
57
+ set back with `set_url()`, or after an `embedded_database()` block: neither closing the engine
58
+ nor an identity set on it ends that state. `set_connection()` does: a new configuration is a
59
+ choice of identity.
60
+ - **Clear errors, before any request, for what the engine cannot do**: live queries (`live()`,
61
+ `watch()`, `subscribe_live()`: read the table's change feed with `changes()` instead),
62
+ `changes(since=<datetime>)` (pass a cursor or `since=None`), and `AuthenticatedUserMixin` calls
63
+ with `bind=False` and `ephemeral_client()` (the engine has a single session per database). Each
64
+ raises `SurrealDbError`.
65
+ - **Authentication on the engine.** `signin()`, `signup()`, `authenticate()` and `invalidate()`
66
+ work with the engine's record access methods and `DEFINE USER`s, and record users and table
67
+ `PERMISSIONS` apply as on a server. A sign-in changes the session of the whole process (every
68
+ event loop and thread); `invalidate()` and a namespace or database change return it to the
69
+ in-process owner and end the stored session. Model auth with `bind=True` signs that session in,
70
+ one call at a time with the connection-level calls (the last one wins), and a failed call puts
71
+ the previous session back, with one exception, as on a server: when `signup()` or `signin()`
72
+ succeeded but the record does not fit the model, the session stays signed in as that record
73
+ (the error says so). `refresh()` cannot succeed on the engine: its SurrealQL does not parse
74
+ `WITH REFRESH`.
75
+ - **`surreal_orm_lite.testing`**, a new module that does not import pytest:
76
+ - `embedded_database(url="mem://", *, namespace="test", database="test")` runs a block against
77
+ an isolated in-process database, yields the block's SDK client (valid inside the block only),
78
+ then puts the previous connection back: its settings, stored session and engine. Blocks nest;
79
+ `surrealkv://<path>` gives an on-disk database. A server URL raises `ValueError`.
80
+ - `SurrealFixture` and `@fixture`, with the full SurrealDB-ORM's names: `load()` saves a fresh
81
+ copy of each declared instance in declaration order, yields them typed as the fixture class,
82
+ and deletes them on exit. It works on any connection, a server or the engine. Unlike the full
83
+ ORM, an explicit `id` is kept, a save that fails or is cancelled mid-load deletes the copies
84
+ already saved, `@fixture` raises `TypeError` on a class that is not a `SurrealFixture`
85
+ subclass, and `load()` raises `ValueError` on an undecorated subclass of a fixture that
86
+ declares instances of its own (the full ORM loads only the parent's).
87
+
88
+ ```python
89
+ from surreal_orm_lite.testing import SurrealFixture, embedded_database, fixture
90
+
91
+ @fixture
92
+ class UserFixtures(SurrealFixture):
93
+ alice = User(name="Alice", role="admin")
94
+ bob = User(id="bob", name="Bob", role="player") # an explicit id is kept
95
+
96
+ async with embedded_database(): # a fresh, empty in-memory database
97
+ async with UserFixtures.load() as fixtures:
98
+ admins = await User.objects().filter(role="admin").exec()
99
+ assert [admin.name for admin in admins] == ["Alice"]
100
+ assert await User.objects().count() == 0 # alice and bob are deleted
101
+ ```
102
+
103
+ - README section 26, "Embedded engine and test fixtures" (in-process databases and the embedded
104
+ URL table, one engine per process, what the engine does not do, its SurrealQL line, identity,
105
+ test fixtures with a pytest recipe, a note for users of the full SurrealDB-ORM), and a new
106
+ behaviour table, "ORM behaviour: the embedded engine"; example notebook
107
+ `examples/v0.25.0_embedded_test_engine.ipynb`.
108
+
109
+ ### Changed
110
+
111
+ - `set_connection()`: `user`, `password`, `namespace` and `database` default to `None`, in the same
112
+ positional order. `is_connection_set()` needs the user and password for a server URL only.
113
+ - A URL the installed SDK refuses (`rocksdb://`, a typo) is still accepted by `set_connection()`;
114
+ the first ORM call now raises a `SurrealDbConnectionError` that quotes the SDK, before anything
115
+ is opened, instead of "Connection not been set." or "Can't connect to the database.". For
116
+ `rocksdb://` it points to #233.
117
+ - The DDL helpers (`define_computed_fields()`, `define_access()`) raise their usual
118
+ `SurrealDbError` for a statement the embedded engine cannot parse, which SDK 2.0.0 reports as a
119
+ bare `RuntimeError`.
120
+ - The `SurrealDbError` of an `AuthenticatedUserMixin` call whose record does not fit the model
121
+ (since v0.17.0) has a new text, on every path, the server lines included: it says whether the
122
+ shared session kept its previous identity or is now signed in as that record (for `refresh()`,
123
+ also that the refresh token passed in is spent and whether the new pair is kept), and it names
124
+ the fields that do not fit and Pydantic's error codes (`nickname: missing; prefs: int_parsing`),
125
+ and quotes nothing from the record: no value, and no key the model does not declare (listed as
126
+ `(undeclared field)`). The Pydantic `ValidationError` is its `__context__` instead of its
127
+ `__cause__`.
128
+
129
+ ### Notes
130
+
131
+ - **The engine is SurrealDB core 2.3.10**, bundled with the surrealdb SDK 2.0.0 base wheel (no
132
+ new dependency, every supported Python version): write 2.x SurrealQL in raw queries and computed
133
+ fields, and expect the 2.x column of the behaviour table. `client.version()` reports the SDK's
134
+ version (`surrealdb-2.0.0`). Transactions are buffered, and parse errors in raw queries are a bare
135
+ `RuntimeError`. The SDK 3.0 line bundles a 3.x engine in the `surrealdb[embedded]` extra (#205).
136
+ - **`rocksdb://` is not yet supported by the official SDK** (#233): the ORM relays the SDK's
137
+ refusal and will accept the scheme with no change once a released SDK does. A bare `memory` (no
138
+ `://`) is refused by SDK 2.0.0: write `memory://`. `surrealkv+versioned://` behaves as
139
+ `surrealkv://` until time travel (v0.26.0).
140
+ - **With the surrealdb SDK 2.x, closing does not stop an in-process engine**: a client obtained
141
+ before `close_connection()` or inside an `embedded_database()` block is still a running
142
+ database. Do not use it after the close, drop it (`del client`) before reopening the same
143
+ `surrealkv://` path, and never open one path from two processes.
144
+ - A fresh engine raises a retryable write conflict when several writes run concurrently on a table
145
+ that does not exist yet: define the table first, or use `@retry_on_conflict()`.
146
+ - The v0.24.3 read hook (#235) also applies to the embedded engine's client: zero durations and
147
+ degenerate geometries read as on a server. A `<set>[…]` is stored as an array there, as on 2.x.
148
+ - **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0 (the CI pins), plus 3.1.5
149
+ for backward compatibility; the embedded tests run in every CI job. `ModelFactory` and
150
+ `Faker` come in v0.39.0.
151
+
152
+ ## [0.24.3] - 2026-10-15
153
+
154
+ The clients the ORM opens now read the values the surrealdb SDK 2.0.0 cannot decode (zero
155
+ durations, SurrealDB 3.x native sets, degenerate geometries), and a zero duration can be stored.
156
+ No new public API.
157
+
158
+ ### Fixed
159
+
160
+ - **Some values SurrealDB returns could not be read** (#235). The surrealdb SDK 2.0.0 cannot
161
+ decode a zero duration, a SurrealDB 3.x native set (a `TYPE set<…>` column on SurrealDB 3.3) or
162
+ a degenerate geometry another client wrote (a line of fewer than 2 points, alone or inside
163
+ another geometry, or a polygon ring of fewer than 4 points): one such value failed the whole
164
+ response it was in. The clients the ORM opens (`SurrealDBConnectionManager.get_client()`,
165
+ `ephemeral_client()`) now read them, over WebSocket, HTTP and embedded connections, and later
166
+ calls on the same client keep working:
167
+ - a zero duration reads as zero: `timedelta(0)` or `Duration(0)` in a typed field, the SDK's
168
+ `Duration(0)` in an untyped one;
169
+ - a native set reads as a Python `set`, which `set[X]` and `frozenset[X]` fields validate, or as
170
+ a `list` when its items are unhashable (record ids, objects, nested sets) or two of them are
171
+ equal in Python, like `1` and `true`: every item the server holds comes back;
172
+ - a degenerate geometry reads as its GeoJSON dict, such as
173
+ `{"type": "LineString", "coordinates": [[1.0, 2.0]]}`, in an untyped field, `raw_query()` and
174
+ live notifications; a geometry field refuses it with a `ValidationError` naming the field.
175
+
176
+ Every other value reads exactly as the SDK reads it, and a malformed value still raises the
177
+ SDK's error. The values go through a hook around the SDK's own CBOR decoder, installed only on
178
+ the ORM's clients and only while the installed SDK cannot decode them: the SDK's modules are not
179
+ modified, and an `AsyncSurreal` client the application builds itself keeps the SDK's behaviour.
180
+ Written back through the ORM (`merge()`, or `update()`, which rewrites the whole row), a native
181
+ set is stored as an array, unless its column is `TYPE set<…>`, and a degenerate geometry's dict
182
+ as a plain object, on both lines.
183
+
184
+ - **A zero duration was refused** since v0.23.0 (`ValueError` for a field, a filter value or a
185
+ bound parameter, `TypeError` from `live()`), because the SDK could not read it back. The ORM's
186
+ clients now read it, so `timedelta(0)` and `Duration(0)` are written, filtered and read back like
187
+ any other duration, on both lines; filter "longer than zero" with `__gt=Duration(0)`. The refusal
188
+ remains only for an SDK that reads no zero duration and whose decoder the ORM cannot hook.
189
+ Upgrade note: a record the ORM writes can now hold a zero duration, which a reader that does not
190
+ go through the ORM's clients cannot read (an `AsyncSurreal` client the application builds itself,
191
+ another service on the SDK 2.0.0).
192
+
193
+ ### Notes
194
+
195
+ - **SurrealDB 2.x vs 3.x**: zero durations and degenerate geometries read the same on both lines.
196
+ Native sets exist only on 3.x: on 3.3 a `TYPE set<…>` column stores a `set[X]` field's array as a
197
+ native set, which now reads back as the declared set; 3.1 still refuses an array in such a
198
+ column, so declare `array<…>` columns to support 3.1. On 2.x the column holds an array, as
199
+ before.
200
+ - The README's "Values the SDK cannot read", "Geometries the SDK cannot read" and "Sets" sections,
201
+ the refusals table and the 2.x/3.x row for `TYPE set<…>` columns describe the new behaviour; the
202
+ v0.23.0 rich field types notebook stores and reads back a zero duration.
203
+ - A later SDK reads zero durations and native sets itself
204
+ ([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)); the hook then leaves
205
+ them to it.
206
+ - Tested against SurrealDB 3.3.4 and 2.7.0 (the CI pins), plus 3.1.5 for backward compatibility.
207
+
8
208
  ## [0.24.2] - 2026-10-15
9
209
 
10
210
  Sub-models keep their rich values after a write that returns the row, and a `timedelta` below the