surreal-orm-lite 0.28.1__tar.gz → 0.29.2__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.1 → surreal_orm_lite-0.29.2}/CHANGELOG.md +198 -0
  2. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/PKG-INFO +323 -10
  3. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/README.md +322 -9
  4. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/__init__.py +3 -1
  6. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/cache.py +15 -3
  7. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/changefeed.py +61 -11
  8. surreal_orm_lite-0.29.2/src/surreal_orm_lite/connection_config.py +27 -0
  9. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/connection_manager.py +860 -47
  10. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/constants.py +15 -6
  11. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/edge.py +15 -5
  12. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/embedded.py +30 -0
  13. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/live.py +168 -52
  14. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/model_auth.py +41 -26
  15. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/model_base.py +117 -28
  16. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/query_set.py +82 -28
  17. surreal_orm_lite-0.29.2/src/surreal_orm_lite/routing.py +254 -0
  18. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/subquery.py +17 -1
  19. surreal_orm_lite-0.29.2/src/surreal_orm_lite/testing/database.py +89 -0
  20. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/transaction.py +9 -0
  21. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/utils.py +96 -8
  22. surreal_orm_lite-0.28.1/src/surreal_orm_lite/testing/database.py +0 -59
  23. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/.gitignore +0 -0
  24. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/LICENSE +0 -0
  25. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/Makefile +0 -0
  26. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/_sdk.py +0 -0
  27. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/aggregations.py +0 -0
  28. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/auth.py +0 -0
  29. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/concurrency.py +0 -0
  30. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/decoding.py +0 -0
  31. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/encoding.py +0 -0
  32. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/enum.py +0 -0
  33. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/exceptions.py +0 -0
  34. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/functions.py +0 -0
  35. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/geo.py +0 -0
  36. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/py.typed +0 -0
  37. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/q.py +0 -0
  38. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/signals.py +0 -0
  39. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/surql_literal.py +0 -0
  40. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/testing/__init__.py +0 -0
  41. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  42. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/time_travel.py +0 -0
  43. {surreal_orm_lite-0.28.1 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/types.py +0 -0
@@ -5,6 +5,204 @@ 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.2] - 2026-10-18
9
+
10
+ The text lookups `startswith`, `endswith`, `like`, `ilike`, `match` and `regex` work: each compiles
11
+ to a SurrealQL string function. No new public API.
12
+
13
+ ### Fixed
14
+
15
+ - **Text lookups compile to SurrealQL string functions** (#251). They compiled to infix operators
16
+ SurrealQL does not have (`STARTSWITH`, `LIKE`, `REGEX`…), so every such filter was a parse error
17
+ on SurrealDB 2.x, 3.x and the embedded engine, in reads and in live queries. Each now compiles to
18
+ a string function guarded by the field's type, with its value bound:
19
+ `filter(name__startswith="A")` is `((name).is_string() AND string::starts_with(name, $_f0))`.
20
+ - `startswith` and `endswith`: `string::starts_with` and `string::ends_with`.
21
+ - `match` and `regex`: `string::matches`, the regular expression (SurrealDB's syntax, the Rust
22
+ `regex` crate) as given. `match` is a regex lookup, not the full-text `@@` operator: full-text
23
+ search is planned for v0.34.0.
24
+ - `like` and `ilike`: `string::matches` on the pattern translated to an anchored regular
25
+ expression. `%` matches any run of characters (newlines included), `_` exactly one, every other
26
+ character is literal; `ilike` ignores case. The whole value must match: `like="Al"` finds
27
+ `"Al"`, not `"Alice"`.
28
+ - A record whose field is missing (`NONE`), `NULL` or not a string never matches, and the query
29
+ does not fail on it; the negation (`~Q(name__startswith="A")`) matches it. A dotted path
30
+ through an array of record links or objects (`authors.name`) holds an array: it never matches
31
+ either.
32
+
33
+ ```python
34
+ await User.objects().filter(name__startswith="A").exec()
35
+ await User.objects().filter(email__ilike="%@EXAMPLE.com").exec() # case-insensitive
36
+ await User.objects().filter(name__regex=r"^\d{3}").exec()
37
+ ```
38
+
39
+ ### Changed
40
+
41
+ - **The value of a text lookup must be a `str`** (#251), otherwise `ValueError`. A string starting
42
+ with `$` is data, as for every lookup. `startswith`, `endswith`, `match` and `regex` also take a
43
+ `Var`; `like` and `ilike` raise `ValueError` for one, since their pattern is translated before it
44
+ is sent. These calls were parse errors before, so no call that worked changes.
45
+
46
+ ### Notes
47
+
48
+ - Same behaviour on SurrealDB 2.x, 3.x and the embedded engine: the guard is written in the method
49
+ form `(field).is_string()`, which parses on both lines (`type::is::string` parses on 2.x only,
50
+ `type::is_string` on 3.x only). The path is in parentheses because SurrealDB 3.x applies
51
+ `authors.name.is_string()` to each element of the array such a path gives, and the array of
52
+ booleans let the array reach the string function, which failed the query. The README's behaviour
53
+ table has a row for the text lookups.
54
+ - `surreal_orm_lite.constants.LOOKUP_OPERATORS` (internal) no longer lists the text lookups; they
55
+ are in `TEXT_LOOKUP_FUNCTIONS`.
56
+
57
+ ## [0.29.0] - 2026-10-18
58
+
59
+ Multiple databases: one process works with several databases at once. Named connections stand
60
+ beside the default one, each model reads and writes through its own, and `using()` redirects a
61
+ block of code. The seventh and last minor of Tier 2.
62
+
63
+ ### Added
64
+
65
+ - **Named connections**:
66
+ `SurrealDBConnectionManager.add_connection(name, *, url, user=None, password=None, namespace, database)`
67
+ registers another database beside the default connection (`set_connection()`): another database
68
+ 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
69
+ one does. `remove_connection(name)`, `get_config(name)` (a frozen `ConnectionConfig`, exported
70
+ from `surreal_orm_lite`) and `list_connections()` complete the registry, with the full
71
+ SurrealDB-ORM's names.
72
+
73
+ ```python
74
+ from surreal_orm_lite import BaseSurrealModel, SurrealConfigDict, SurrealDBConnectionManager
75
+
76
+ SurrealDBConnectionManager.set_connection(url="mem://", namespace="shop", database="main") # "default"
77
+ SurrealDBConnectionManager.add_connection("analytics", url="mem://", namespace="shop", database="analytics")
78
+
79
+ class Customer(BaseSurrealModel): # no connection key: "default"
80
+ id: str | None = None
81
+ name: str
82
+
83
+ class PageView(BaseSurrealModel):
84
+ model_config = SurrealConfigDict(connection="analytics")
85
+ id: str | None = None
86
+ path: str
87
+
88
+ await Customer(id="ada", name="Ada").save() # shop/main
89
+ await PageView(id="v1", path="/pricing").save() # shop/analytics
90
+
91
+ async with SurrealDBConnectionManager.using("analytics"):
92
+ elsewhere = await Customer.objects().count() # 0: Customer runs on "analytics" here
93
+ ```
94
+
95
+ - **`add_connection()` checks its arguments** before registering anything: a non-empty name, URL,
96
+ namespace and database, and a user and password for a server URL (optional on the embedded
97
+ engine); a URL the installed SDK refuses raises `SurrealDbConnectionError`. Registering a name
98
+ again with the same settings changes nothing, and `add_connection("default", …)` configures the
99
+ default connection with these checks. `ConnectionConfig` keeps the password out of its `repr`.
100
+ `remove_connection()` of a name that is not registered is a no-op, and
101
+ `remove_connection("default")` is `unset_connection()`.
102
+ - **Model routing**: `SurrealConfigDict(connection="analytics")` sends every database call of the
103
+ model to that connection: writes, reads and every QuerySet, relations, `raw_query()`,
104
+ `call_function()`, model auth, live queries, change feeds and `as_of()`. A model without the key
105
+ uses the default connection. `Model.get_connection_name()` returns the connection its calls use
106
+ right now. The key is checked when the class is defined (`TypeError` for a value that is not a
107
+ string, `ValueError` for an empty one), and whether its name is registered at the model's first
108
+ database call (`ValueError`), so models can be declared before `add_connection()` runs. Edge
109
+ models and `AuthenticatedUserMixin` models take it too; subclasses inherit it.
110
+ - **`using(name)`**: inside `async with SurrealDBConnectionManager.using("analytics"):` every model,
111
+ whatever its key, and every manager method that talks to a database use that connection. It is
112
+ async-safe (a `ContextVar`: a task created inside the block keeps its connection), blocks nest,
113
+ and the outer connection is back after the block, on an exception too; a name that is not
114
+ registered raises `ValueError` before the block runs. `get_active_connection_name()` returns the
115
+ block's name, `None` outside any block.
116
+ - **`name=` on `get_client()`, `close_connection()` and `transaction()`**: they act on a named
117
+ connection, and without it on the current one. `inspect.signature()` does not show the
118
+ parameter, so `Depends(SurrealDBConnectionManager.get_client)` in FastAPI adds no `?name=` query
119
+ parameter and behaves as in v0.28: a request never chooses the connection.
120
+ - **Each connection keeps its own state**: its clients (one per event loop; one for the whole
121
+ process on the embedded engine), its session (`signin()` inside `using(name)` signs in that
122
+ connection only, and a stored token is replayed on its own connection only), its live streams
123
+ and change feeds (bound to the connection when they start), its transactions, its
124
+ stored-function signatures and its cached reads.
125
+ - **`embedded_database(connection=name)`** isolates a named connection in tests; inside
126
+ `using(name)` it isolates the block's connection, and naming another connection there raises
127
+ `ValueError`.
128
+ - **Errors for operations across connections**, raised before any request: `SurrealDbError` for a
129
+ model given another connection's transaction (its writes, `objects(tx=)`, `refresh(tx=)`,
130
+ `call_function(tx=)`), for a subquery whose model runs on another connection than the statement
131
+ around it, for `relate()`, `remove_relation()`, `remove_all_relations()` and `get_related()`
132
+ across connections, and for following a link (`fetch()`, a dotted path) through a field typed
133
+ with a model of another connection; `SurrealDbConnectionError` (not retryable) when a second
134
+ connection opens an on-disk embedded store (`surrealkv://`, `file://`) that another connection
135
+ of the process holds open. Inside a `using()` block every model runs on one connection, so none
136
+ of them apply there.
137
+ - README section 30, "Multiple databases (`add_connection()`, `using()`)" (routing a model,
138
+ `using()`, transactions and other operations across connections, what each connection keeps for
139
+ itself, which connection a manager method uses, a note for users of the full SurrealDB-ORM), a
140
+ features row, rows in the 2.x/3.x and embedded-engine behaviour tables, the comparison and
141
+ roadmap rows, and the example notebook `examples/v0.29.0_multi_database.ipynb`.
142
+
143
+ ### Changed
144
+
145
+ - `close_connection()` ends the live streams of its own connection only (before: every live
146
+ stream of the event loop), and `unset_connection()` closes the default connection's clients only
147
+ (`close_all_connections()` still closes every client, of every connection). With the default
148
+ connection alone, both behave as before.
149
+ - A `transaction()` records the connection it was opened on: a model of another connection is
150
+ refused (above), and a transaction whose connection is registered again with other settings, or
151
+ removed, while it is open is cancelled when its block ends, with nothing committed
152
+ (`SurrealDbConnectionError`: open it again).
153
+ - The manager's state now lives in one class per connection, the default one included: code that
154
+ read or patched the private attributes of `SurrealDBConnectionManager` must follow it. A manager
155
+ method replaced by hand, public or private, is inherited by every connection: put it back from
156
+ `vars(SurrealDBConnectionManager)[name]`, as pytest's `monkeypatch.setattr()` and
157
+ `unittest.mock.patch.object()` already do. Putting back `SurrealDBConnectionManager.<name>`, saved
158
+ before the patch, worked with one connection; it is a method bound to `SurrealDBConnectionManager`
159
+ that every connection then inherits and that acts on the current connection, so once a named
160
+ connection exists, a model with a `connection` key reads and writes the current connection's
161
+ database, with no error (README section 30, "Which connection a manager method uses").
162
+ - CI adds a "Mixed server lines" job, required by `CI Success`: the mixed-lines tests put a
163
+ SurrealDB 3.x and a 2.x connection side by side in one process; they find the servers through
164
+ `SURREALDB_PORT_3X` and `SURREALDB_PORT_2X` and skip without them.
165
+
166
+ ### Notes
167
+
168
+ - **Each connection decides on its own server line**: a SurrealDB 2.x and a 3.x server work side
169
+ by side in one process, with interactive transactions on a 3.x WebSocket connection beside
170
+ buffered ones on a 2.x connection; time travel, change feeds and live queries follow each
171
+ connection's server.
172
+ - **Registering a name again with other settings, or removing it**, retires its clients and ends
173
+ what the ORM holds on the old settings: a client still opening is closed unused (a retryable
174
+ `SurrealDbConnectionError`: retry the call), live streams end, a change feed ends at its next
175
+ read (`SurrealDbConnectionError`: start a new one), and an open `transaction()` is cancelled
176
+ (above). A client the application obtained with `get_client()` before the change is its own: on
177
+ WebSocket its next request fails; an HTTP client keeps the namespace and database it was opened
178
+ on; an embedded client follows a new namespace or database, but after a new URL or a removal it
179
+ is the previous engine, so stop using it. `set_connection()` and the `set_*()` setters keep
180
+ their earlier behaviour: clients opened on the previous settings keep serving.
181
+ - **Query cache**: an ORM write removes the cached reads of its table on every connection, more
182
+ than needed but never a stale result. Entries cached with `QueryCache.make_key()` and `set()`
183
+ are not scoped to a connection: when the same statement runs on two connections, put the
184
+ connection's name among the variables.
185
+ - **What the ORM cannot see across connections**, so keep it on one connection yourself: a link
186
+ followed through a field whose annotation names no model (`RecordID`, `str`, `dict`), graph
187
+ arrows (`select("->likes->Post")`, `traverse()`), an edge saved with endpoint ids of another
188
+ database, and raw SurrealQL (`raw_query()`, `QuerySet.query()`, `call_function()`,
189
+ `Transaction.add()`).
190
+ - **SurrealDB runs a statement, and a transaction, in one database**: two `transaction()` blocks on
191
+ two connections are two independent transactions, and a `USE` inside `raw_query()` applies to
192
+ that request only (the next request reads the connection's own database).
193
+ - **Differences from the full SurrealDB-ORM**: `close_connection()` without a name closes the
194
+ current connection only (full ORM: every connection); `list_connections()` lists `'default'`
195
+ first; registering a name again with other settings closes its clients; the getters, the
196
+ setters and `reconnect()` follow `using()`; `add_connection()` and the `connection` key are
197
+ checked; `ConnectionConfig` has no `protocol` (the official SDK speaks CBOR only) and accepts
198
+ `None` for `user` and `password`; `name` is hidden from introspection; `transaction(name)`,
199
+ `embedded_database(connection=)` and the errors for operations across connections are lite
200
+ additions.
201
+ - Not available yet: a per-queryset override (`QuerySet.using()`), a client-side connection pool,
202
+ one transaction across connections.
203
+ - **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, each alone and both in one
204
+ process, and on the embedded engine, plus 3.1.5 for backward compatibility (identical).
205
+
8
206
  ## [0.28.1] - 2026-10-17
9
207
 
10
208
  Query building checks what it is given: `select()` accepts field names and paths, `limit()` and