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.
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/CHANGELOG.md +200 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/PKG-INFO +405 -51
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/README.md +404 -50
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/pyproject.toml +1 -1
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/_sdk.py +39 -1
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/changefeed.py +10 -1
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/connection_manager.py +645 -80
- surreal_orm_lite-0.25.0/src/surreal_orm_lite/decoding.py +338 -0
- surreal_orm_lite-0.25.0/src/surreal_orm_lite/embedded.py +124 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/encoding.py +19 -27
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/geo.py +4 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/live.py +7 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/model_auth.py +279 -26
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/query_set.py +6 -3
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/surql_literal.py +11 -7
- surreal_orm_lite-0.25.0/src/surreal_orm_lite/testing/__init__.py +28 -0
- surreal_orm_lite-0.25.0/src/surreal_orm_lite/testing/database.py +59 -0
- surreal_orm_lite-0.25.0/src/surreal_orm_lite/testing/fixtures.py +139 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/utils.py +3 -2
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/.gitignore +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/LICENSE +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/Makefile +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/model_base.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.24.2 → surreal_orm_lite-0.25.0}/src/surreal_orm_lite/transaction.py +0 -0
- {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
|