surreal-orm-lite 0.28.0__tar.gz → 0.29.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 (43) hide show
  1. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/CHANGELOG.md +239 -0
  2. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/PKG-INFO +383 -27
  3. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/README.md +382 -26
  4. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/__init__.py +3 -1
  6. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/cache.py +15 -3
  7. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/changefeed.py +61 -11
  8. surreal_orm_lite-0.29.0/src/surreal_orm_lite/connection_config.py +27 -0
  9. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/connection_manager.py +860 -47
  10. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/constants.py +7 -0
  11. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/edge.py +15 -5
  12. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/embedded.py +30 -0
  13. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/functions.py +16 -7
  14. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/live.py +168 -52
  15. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/model_auth.py +41 -26
  16. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/model_base.py +117 -28
  17. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/query_set.py +329 -76
  18. surreal_orm_lite-0.29.0/src/surreal_orm_lite/routing.py +254 -0
  19. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/subquery.py +34 -6
  20. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/surql_literal.py +9 -6
  21. surreal_orm_lite-0.29.0/src/surreal_orm_lite/testing/database.py +89 -0
  22. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/transaction.py +9 -0
  23. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/utils.py +180 -35
  24. surreal_orm_lite-0.28.0/src/surreal_orm_lite/testing/database.py +0 -59
  25. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/.gitignore +0 -0
  26. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/LICENSE +0 -0
  27. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/Makefile +0 -0
  28. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/_sdk.py +0 -0
  29. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/aggregations.py +0 -0
  30. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/auth.py +0 -0
  31. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/concurrency.py +0 -0
  32. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/decoding.py +0 -0
  33. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/encoding.py +0 -0
  34. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/enum.py +0 -0
  35. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/exceptions.py +0 -0
  36. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/geo.py +0 -0
  37. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/py.typed +0 -0
  38. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/q.py +0 -0
  39. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/signals.py +0 -0
  40. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
  41. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  42. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/time_travel.py +0 -0
  43. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.29.0}/src/surreal_orm_lite/types.py +0 -0
@@ -5,6 +5,245 @@ 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.29.0] - 2026-10-18
9
+
10
+ Multiple databases: one process works with several databases at once. Named connections stand
11
+ beside the default one, each model reads and writes through its own, and `using()` redirects a
12
+ block of code. The seventh and last minor of Tier 2.
13
+
14
+ ### Added
15
+
16
+ - **Named connections**:
17
+ `SurrealDBConnectionManager.add_connection(name, *, url, user=None, password=None, namespace, database)`
18
+ registers another database beside the default connection (`set_connection()`): another database
19
+ on the same server, another server, or the embedded engine. It opens nothing: each connection opens its own clients on first use, as the default
20
+ one does. `remove_connection(name)`, `get_config(name)` (a frozen `ConnectionConfig`, exported
21
+ from `surreal_orm_lite`) and `list_connections()` complete the registry, with the full
22
+ SurrealDB-ORM's names.
23
+
24
+ ```python
25
+ from surreal_orm_lite import BaseSurrealModel, SurrealConfigDict, SurrealDBConnectionManager
26
+
27
+ SurrealDBConnectionManager.set_connection(url="mem://", namespace="shop", database="main") # "default"
28
+ SurrealDBConnectionManager.add_connection("analytics", url="mem://", namespace="shop", database="analytics")
29
+
30
+ class Customer(BaseSurrealModel): # no connection key: "default"
31
+ id: str | None = None
32
+ name: str
33
+
34
+ class PageView(BaseSurrealModel):
35
+ model_config = SurrealConfigDict(connection="analytics")
36
+ id: str | None = None
37
+ path: str
38
+
39
+ await Customer(id="ada", name="Ada").save() # shop/main
40
+ await PageView(id="v1", path="/pricing").save() # shop/analytics
41
+
42
+ async with SurrealDBConnectionManager.using("analytics"):
43
+ elsewhere = await Customer.objects().count() # 0: Customer runs on "analytics" here
44
+ ```
45
+
46
+ - **`add_connection()` checks its arguments** before registering anything: a non-empty name, URL,
47
+ namespace and database, and a user and password for a server URL (optional on the embedded
48
+ engine); a URL the installed SDK refuses raises `SurrealDbConnectionError`. Registering a name
49
+ again with the same settings changes nothing, and `add_connection("default", …)` configures the
50
+ default connection with these checks. `ConnectionConfig` keeps the password out of its `repr`.
51
+ `remove_connection()` of a name that is not registered is a no-op, and
52
+ `remove_connection("default")` is `unset_connection()`.
53
+ - **Model routing**: `SurrealConfigDict(connection="analytics")` sends every database call of the
54
+ model to that connection: writes, reads and every QuerySet, relations, `raw_query()`,
55
+ `call_function()`, model auth, live queries, change feeds and `as_of()`. A model without the key
56
+ uses the default connection. `Model.get_connection_name()` returns the connection its calls use
57
+ right now. The key is checked when the class is defined (`TypeError` for a value that is not a
58
+ string, `ValueError` for an empty one), and whether its name is registered at the model's first
59
+ database call (`ValueError`), so models can be declared before `add_connection()` runs. Edge
60
+ models and `AuthenticatedUserMixin` models take it too; subclasses inherit it.
61
+ - **`using(name)`**: inside `async with SurrealDBConnectionManager.using("analytics"):` every model,
62
+ whatever its key, and every manager method that talks to a database use that connection. It is
63
+ async-safe (a `ContextVar`: a task created inside the block keeps its connection), blocks nest,
64
+ and the outer connection is back after the block, on an exception too; a name that is not
65
+ registered raises `ValueError` before the block runs. `get_active_connection_name()` returns the
66
+ block's name, `None` outside any block.
67
+ - **`name=` on `get_client()`, `close_connection()` and `transaction()`**: they act on a named
68
+ connection, and without it on the current one. `inspect.signature()` does not show the
69
+ parameter, so `Depends(SurrealDBConnectionManager.get_client)` in FastAPI adds no `?name=` query
70
+ parameter and behaves as in v0.28: a request never chooses the connection.
71
+ - **Each connection keeps its own state**: its clients (one per event loop; one for the whole
72
+ process on the embedded engine), its session (`signin()` inside `using(name)` signs in that
73
+ connection only, and a stored token is replayed on its own connection only), its live streams
74
+ and change feeds (bound to the connection when they start), its transactions, its
75
+ stored-function signatures and its cached reads.
76
+ - **`embedded_database(connection=name)`** isolates a named connection in tests; inside
77
+ `using(name)` it isolates the block's connection, and naming another connection there raises
78
+ `ValueError`.
79
+ - **Errors for operations across connections**, raised before any request: `SurrealDbError` for a
80
+ model given another connection's transaction (its writes, `objects(tx=)`, `refresh(tx=)`,
81
+ `call_function(tx=)`), for a subquery whose model runs on another connection than the statement
82
+ around it, for `relate()`, `remove_relation()`, `remove_all_relations()` and `get_related()`
83
+ across connections, and for following a link (`fetch()`, a dotted path) through a field typed
84
+ with a model of another connection; `SurrealDbConnectionError` (not retryable) when a second
85
+ connection opens an on-disk embedded store (`surrealkv://`, `file://`) that another connection
86
+ of the process holds open. Inside a `using()` block every model runs on one connection, so none
87
+ of them apply there.
88
+ - README section 30, "Multiple databases (`add_connection()`, `using()`)" (routing a model,
89
+ `using()`, transactions and other operations across connections, what each connection keeps for
90
+ itself, which connection a manager method uses, a note for users of the full SurrealDB-ORM), a
91
+ features row, rows in the 2.x/3.x and embedded-engine behaviour tables, the comparison and
92
+ roadmap rows, and the example notebook `examples/v0.29.0_multi_database.ipynb`.
93
+
94
+ ### Changed
95
+
96
+ - `close_connection()` ends the live streams of its own connection only (before: every live
97
+ stream of the event loop), and `unset_connection()` closes the default connection's clients only
98
+ (`close_all_connections()` still closes every client, of every connection). With the default
99
+ connection alone, both behave as before.
100
+ - A `transaction()` records the connection it was opened on: a model of another connection is
101
+ refused (above), and a transaction whose connection is registered again with other settings, or
102
+ removed, while it is open is cancelled when its block ends, with nothing committed
103
+ (`SurrealDbConnectionError`: open it again).
104
+ - The manager's state now lives in one class per connection, the default one included: code that
105
+ read or patched the private attributes of `SurrealDBConnectionManager` must follow it. A manager
106
+ method replaced by hand, public or private, is inherited by every connection: put it back from
107
+ `vars(SurrealDBConnectionManager)[name]`, as pytest's `monkeypatch.setattr()` and
108
+ `unittest.mock.patch.object()` already do. Putting back `SurrealDBConnectionManager.<name>`, saved
109
+ before the patch, worked with one connection; it is a method bound to `SurrealDBConnectionManager`
110
+ that every connection then inherits and that acts on the current connection, so once a named
111
+ connection exists, a model with a `connection` key reads and writes the current connection's
112
+ database, with no error (README section 30, "Which connection a manager method uses").
113
+ - CI adds a "Mixed server lines" job, required by `CI Success`: the mixed-lines tests put a
114
+ SurrealDB 3.x and a 2.x connection side by side in one process; they find the servers through
115
+ `SURREALDB_PORT_3X` and `SURREALDB_PORT_2X` and skip without them.
116
+
117
+ ### Notes
118
+
119
+ - **Each connection decides on its own server line**: a SurrealDB 2.x and a 3.x server work side
120
+ by side in one process, with interactive transactions on a 3.x WebSocket connection beside
121
+ buffered ones on a 2.x connection; time travel, change feeds and live queries follow each
122
+ connection's server.
123
+ - **Registering a name again with other settings, or removing it**, retires its clients and ends
124
+ what the ORM holds on the old settings: a client still opening is closed unused (a retryable
125
+ `SurrealDbConnectionError`: retry the call), live streams end, a change feed ends at its next
126
+ read (`SurrealDbConnectionError`: start a new one), and an open `transaction()` is cancelled
127
+ (above). A client the application obtained with `get_client()` before the change is its own: on
128
+ WebSocket its next request fails; an HTTP client keeps the namespace and database it was opened
129
+ on; an embedded client follows a new namespace or database, but after a new URL or a removal it
130
+ is the previous engine, so stop using it. `set_connection()` and the `set_*()` setters keep
131
+ their earlier behaviour: clients opened on the previous settings keep serving.
132
+ - **Query cache**: an ORM write removes the cached reads of its table on every connection, more
133
+ than needed but never a stale result. Entries cached with `QueryCache.make_key()` and `set()`
134
+ are not scoped to a connection: when the same statement runs on two connections, put the
135
+ connection's name among the variables.
136
+ - **What the ORM cannot see across connections**, so keep it on one connection yourself: a link
137
+ followed through a field whose annotation names no model (`RecordID`, `str`, `dict`), graph
138
+ arrows (`select("->likes->Post")`, `traverse()`), an edge saved with endpoint ids of another
139
+ database, and raw SurrealQL (`raw_query()`, `QuerySet.query()`, `call_function()`,
140
+ `Transaction.add()`).
141
+ - **SurrealDB runs a statement, and a transaction, in one database**: two `transaction()` blocks on
142
+ two connections are two independent transactions, and a `USE` inside `raw_query()` applies to
143
+ that request only (the next request reads the connection's own database).
144
+ - **Differences from the full SurrealDB-ORM**: `close_connection()` without a name closes the
145
+ current connection only (full ORM: every connection); `list_connections()` lists `'default'`
146
+ first; registering a name again with other settings closes its clients; the getters, the
147
+ setters and `reconnect()` follow `using()`; `add_connection()` and the `connection` key are
148
+ checked; `ConnectionConfig` has no `protocol` (the official SDK speaks CBOR only) and accepts
149
+ `None` for `user` and `password`; `name` is hidden from introspection; `transaction(name)`,
150
+ `embedded_database(connection=)` and the errors for operations across connections are lite
151
+ additions.
152
+ - Not available yet: a per-queryset override (`QuerySet.using()`), a client-side connection pool,
153
+ one transaction across connections.
154
+ - **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, each alone and both in one
155
+ process, and on the embedded engine, plus 3.1.5 for backward compatibility (identical).
156
+
157
+ ## [0.28.1] - 2026-10-17
158
+
159
+ Query building checks what it is given: `select()` accepts field names and paths, `limit()` and
160
+ `offset()` take a non-negative integer, and a string filter value is always data, with `Var()` as
161
+ the only variable reference. No new public API.
162
+
163
+ ### Changed
164
+
165
+ - **A string filter value is data, whatever its first character** (#250), on every filter path:
166
+ `filter()`, `Q`, `get()`, `first()`, `count()`, `exists()`, `get_or_create()`,
167
+ `update_or_create()`, `bulk_update()` by filter, `cache()`, subqueries and live queries.
168
+ `filter(name="$admin")` compares `name` with the string `"$admin"`, bound like any other value.
169
+ `Var("name")` is the only reference to a query variable, whose value `variables()` gives.
170
+ Migration: where a filter uses the `"$name"` form (deprecated since v0.14.3), write
171
+ `Var("name")`. When a string filter value is exactly `$` followed by the name of a variable of
172
+ `variables()` or of a session parameter (`$access`, `$auth`, `$session`, `$token`), a
173
+ `UserWarning` names the `Var(...)` to write, once per read, pointing at the caller's line; the
174
+ value stays data. Any other string, such as `"$x"` with no variable `x`, is data and nothing
175
+ warns.
176
+
177
+ ```python
178
+ from surreal_orm_lite import Var
179
+
180
+ await User.objects().filter(name="$admin").exec() # the string "$admin"
181
+ await User.objects().filter(age__gte=Var("min_age")).variables(min_age=21).exec() # $min_age
182
+ await Doc.objects().filter(owner=Var("auth")).exec() # SurrealDB's $auth
183
+ ```
184
+
185
+ - **The `"$$"` escape keeps its meaning and is deprecated** (#250): a string filter value starting
186
+ with `$$` loses one `$` (`"$$admin"` finds `"$admin"`) and emits a `DeprecationWarning`; write
187
+ the value with one `$` less. An item of an `in` list never had the escape and is unchanged.
188
+ - **`variables()` refuses `access`, `auth`, `session` and `token`** with a `ValueError` (#250):
189
+ SurrealDB sets these parameters for each session and refuses a query variable of that name. To
190
+ pass your own value, give it another name or put the value itself in the filter:
191
+ `filter(token=Var("device_token")).variables(device_token=t)` or `filter(token=t)`.
192
+ `Var("token")` without `variables()` reads SurrealDB's `$token`, and likewise for the three
193
+ others, in reads and in live queries.
194
+ - **`get_or_create()` and `update_or_create()`** raise `SurrealDbError` before any request when a
195
+ scalar string criterion is exactly `$` followed by the name of a variable of `variables()` or of
196
+ a session parameter, whatever its lookup (#250): pass the actual value as the criterion (the
197
+ record id, or the value itself). Any other `"$name"` string is looked up and written as it is.
198
+ `Var("auth")` finds the signed-in user's record but cannot be written: with no record to return,
199
+ it raises `SurrealDbError`.
200
+ - **`select()` checks its items** like `order_by()` and `values()` (#247): each item is `"*"`, a
201
+ field name (an aliased field by its Python name), a dotted path into a nested object or through a
202
+ record link, or such a path followed by `.*` (`"author.*"`). Anything else raises `ValueError`
203
+ naming the item when `select()` is called, before any request, and the selection in place is
204
+ kept; an item that is not a `str` raises `TypeError`. Write a computed projection with `query()`
205
+ and bound parameters.
206
+ - **`limit()` and `offset()` take a non-negative integer** (#249) of any type with `__index__`
207
+ (an `IntEnum` member, NumPy's `int64`; the parameter is annotated `SupportsIndex`), up to
208
+ `2**63 - 1`. A `bool`, `str`, `float` or `None` raises `TypeError`, a negative value or one above
209
+ `2**63 - 1` `ValueError`, naming the method and the value, when the method is called (for a
210
+ subquery's `limit()` and `offset()` too), before any request; the value in place is kept.
211
+ SurrealDB 2.x and the embedded engine refuse a value above `2**32 - 1` when the read runs;
212
+ SurrealDB 3.x reads it.
213
+ - **Live queries**: `Var("scope")` takes its value from `variables(scope=...)` like any other name
214
+ and raises `SurrealDbError` without it (#250). `$access`, `$auth`, `$session`, `$token`, `$this`
215
+ and `$parent` stay references the server reads on every notification.
216
+
217
+ ### Fixed
218
+
219
+ - On an edge's `in` and `out`, which hold record ids, a string that is `$` followed by the name of
220
+ a variable of `variables()` or of a session parameter raises a `ValueError` whose message names
221
+ the `Var(...)` to write (#250).
222
+ - Each warning of a filter value is emitted once per read: the second compilation of a `cache()`
223
+ miss and the re-send of a subquery over a missing table stay quiet, for the `"$$"`
224
+ `DeprecationWarning` too (#250).
225
+
226
+ ### Removed
227
+
228
+ - `utils.remove_quotes_for_variables()` and `utils.VALID_VARIABLE_REF_PATTERN`, internal helpers
229
+ that were never in `__all__`.
230
+
231
+ ### Notes
232
+
233
+ - **SurrealDB 2.x vs 3.x**: string filter values and `Var()` behave the same on both lines and on
234
+ the embedded engine. `select("meta.*")` on a nested object that is not a record link gives the
235
+ object on 3.x and its values as a list on 2.x and the embedded engine (through a link, the linked
236
+ record on both). A `limit()` or `offset()` above `2**32 - 1` is refused by SurrealDB 2.x and the
237
+ embedded engine when the read runs, and read by 3.x.
238
+ - **Docs**: the README section "String filter values and `Var()`" replaces "Filter values that
239
+ start with `$`"; new parts "What `select()` accepts" and "`limit()` and `offset()`"; the
240
+ live-query, subquery and query-cache invalidation notes match; three rows in the 2.x/3.x behaviour
241
+ table (string filter values, a nested object's `.*`, `LIMIT`/`START` above `2**32 - 1`). The
242
+ `getting_started` notebook reads `SURREALDB_HOST` and `SURREALDB_PORT`; the v0.14.3 notebook says
243
+ the `"$$"` escape is deprecated since v0.28.1.
244
+ - **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, and on the embedded engine,
245
+ plus 3.1.5 for backward compatibility (identical).
246
+
8
247
  ## [0.28.0] - 2026-10-17
9
248
 
10
249
  Query cache: a QuerySet serves its reads from a client-side cache with `cache(ttl)`, and every ORM