surreal-orm-lite 0.30.7__tar.gz → 0.31.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 (47) hide show
  1. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/CHANGELOG.md +212 -0
  2. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/PKG-INFO +317 -33
  3. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/README.md +316 -32
  4. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/__init__.py +5 -1
  6. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/cache.py +21 -19
  7. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/changefeed.py +6 -6
  8. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/connection_manager.py +360 -51
  9. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/define_parser.py +154 -45
  10. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/edge.py +2 -2
  11. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/embedded.py +9 -7
  12. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/functions.py +1 -1
  13. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/introspection.py +58 -27
  14. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/live.py +1 -1
  15. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/model_base.py +149 -3
  16. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/model_generator.py +100 -63
  17. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/query_set.py +44 -43
  18. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/routing.py +18 -16
  19. surreal_orm_lite-0.31.0/src/surreal_orm_lite/schema.py +437 -0
  20. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/schema_state.py +13 -3
  21. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/subquery.py +27 -26
  22. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/testing/database.py +1 -1
  23. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/time_travel.py +19 -18
  24. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/types.py +5 -5
  25. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/utils.py +98 -8
  26. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/.gitignore +0 -0
  27. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/LICENSE +0 -0
  28. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/Makefile +0 -0
  29. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/_sdk.py +0 -0
  30. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/aggregations.py +0 -0
  31. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/auth.py +0 -0
  32. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/concurrency.py +0 -0
  33. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/connection_config.py +0 -0
  34. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/constants.py +0 -0
  35. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/decoding.py +0 -0
  36. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/encoding.py +0 -0
  37. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/enum.py +0 -0
  38. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/exceptions.py +0 -0
  39. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/geo.py +0 -0
  40. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/model_auth.py +0 -0
  41. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/py.typed +0 -0
  42. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/q.py +0 -0
  43. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/signals.py +0 -0
  44. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/surql_literal.py +0 -0
  45. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
  46. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  47. {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.31.0}/src/surreal_orm_lite/transaction.py +0 -0
@@ -5,6 +5,218 @@ 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.31.0] - 2026-10-19
9
+
10
+ Server-side events and DDL helpers: the ORM writes and applies `DEFINE EVENT` and
11
+ `DEFINE FUNCTION` statements from Python. Events are declared on the model, next to its fields,
12
+ and applied idempotently; stored functions are defined for `call_function()` to call. The same
13
+ code runs on SurrealDB 2.x, 3.x and the embedded engine; asynchronous events and `$input` are 3.x
14
+ only. The second minor of Tier 3.
15
+
16
+ ### Added
17
+
18
+ - **`Event(name, *, then, when=None, async_mode=False, retry=None, max_depth=None, comment=None)`**
19
+ and **`SurrealConfigDict(events=[...])`**: a model declares its server-side events, which
20
+ SurrealDB runs on every `CREATE`, `UPDATE` and `DELETE` of the table, whoever writes it (the
21
+ ORM, a raw query or another client). `Model.event_ddl()` renders their `DEFINE EVENT` statements
22
+ without a connection, `await Model.define_events()` applies them on the model's connection
23
+ (`DEFINE EVENT OVERWRITE`: run it at start-up) and returns them, and
24
+ `await Model.remove_event("name")` removes one by name, declared or not. `overwrite=False` writes
25
+ `IF NOT EXISTS`, `missing_ok=False` raises `SurrealDbNotFoundError` for a missing event, and
26
+ `Model.get_events()` lists the declared events. A subclass inherits `events` unless it sets its
27
+ own, and typed edges take events too.
28
+
29
+ ```python
30
+ class Account(BaseSurrealModel):
31
+ model_config = SurrealConfigDict(
32
+ table_name="account",
33
+ events=[
34
+ Event(
35
+ "email_audit",
36
+ when="$event = 'UPDATE' AND $before.email != $after.email",
37
+ then="CREATE audit_log SET account = $value.id, old = $before.email, new = $after.email",
38
+ ),
39
+ Event(
40
+ "no_negative_balance",
41
+ when="$event != 'DELETE' AND $after.balance < 0",
42
+ then="THROW 'balance cannot be negative'",
43
+ ),
44
+ ],
45
+ )
46
+
47
+ id: str | None = None
48
+ email: str
49
+ balance: int = 0
50
+
51
+
52
+ Account.event_ddl() # the DEFINE EVENT statements, no connection needed
53
+ await Account.define_events() # idempotent
54
+ await Account(id="ada", email="ada@example.com", balance=-5).save() # InternalError: refused
55
+ ```
56
+
57
+ - **`SurrealDBConnectionManager.define_event(event, table)`** and
58
+ **`remove_event(event, table)`** apply an `Event` to any table, with or without a model, on the
59
+ current connection (the `using()` block's, else `"default"`); `event.ddl(table)` renders the
60
+ statement. The `then` clause is always written as a block (`THEN { … }`), so several statements,
61
+ `LET` and `THROW` work on both lines.
62
+ - **Asynchronous events (SurrealDB 3.x)**: `Event(..., async_mode=True, retry=3, max_depth=2)`
63
+ writes `ASYNC RETRY 3 MAXDEPTH 2`. Such an event runs after the write's transaction commits, so
64
+ it does not hold the write up. On SurrealDB 2.x and the embedded engine, which cannot parse
65
+ `ASYNC`, every applier raises `SurrealDbError` before sending any DDL, and no event of the call
66
+ is defined; `event.ddl()` renders an asynchronous event on any line.
67
+ - **`SurrealDBConnectionManager.define_function(function, body, *, parameters=None, ...)`**,
68
+ **`remove_function(function)`** and the pure **`function_ddl()`** (exported from
69
+ `surreal_orm_lite`): stored functions defined from Python, named as `call_function()` names them
70
+ (`"greet"`, `"fn::greet"`, `"fn::billing::total"`). `parameters` maps each parameter name to its
71
+ SurrealQL kind in declaration order, the order of `call_function()`'s positional `args`;
72
+ `returns` is the result's kind, `permissions` is `"FULL"`, `"NONE"` or `"WHERE <condition>"`,
73
+ and `comment=` and `overwrite=` work as for events.
74
+
75
+ ```python
76
+ await SurrealDBConnectionManager.define_function(
77
+ "fn::greet",
78
+ "RETURN string::concat('Hello, ', $name, '!');",
79
+ parameters={"name": "string"},
80
+ returns="string",
81
+ )
82
+ await SurrealDBConnectionManager.call_function("fn::greet", ["Ada"]) # 'Hello, Ada!'
83
+ ```
84
+
85
+ - **Every applier takes `tx=`** and returns the statement it applied (`define_events()`: the
86
+ list). A refusal raises
87
+ `SurrealDbAuthenticationError` when the session may not define (a `VIEWER`, a record user, an
88
+ anonymous session), `SurrealDbNotFoundError` for a removal of a missing definition with
89
+ `missing_ok=False`, and `SurrealDbError` otherwise
90
+ (`Can't apply event definition: 'email_audit' on table 'account' -> …`). Without `tx=`, a
91
+ refusal names the event and its table, or the function, never the statement, whose `when`,
92
+ `then` or body may hold a secret, and gives the server's reason without its excerpt of the
93
+ statement. A buffered transaction (SurrealDB 2.x, HTTP, the embedded engine) only queues the
94
+ statement, so a refusal comes back when the block commits, as the transaction's own error, never
95
+ as `SurrealDbAuthenticationError` or `SurrealDbNotFoundError`, `missing_ok=False` included. When
96
+ a definition is applied in a transaction (`tx=`), an error raised when the transaction ends can
97
+ still carry the server's message, statement excerpt included (#278). `define_events()` applies
98
+ one statement per event and stops at the first refusal: pass `tx=` for all or nothing. A `tx=`
99
+ of another connection raises `SurrealDbError` before any request.
100
+ - README section 32, "Server-side events and stored functions (`Event`, `define_events()`,
101
+ `define_function()`)" (declaring events on a model, events without a model, asynchronous events,
102
+ stored functions, transactions and connections, SurrealDB 2.x and 3.x, security, a note for users
103
+ of the full SurrealDB-ORM), a features row, seven rows in the 2.x/3.x behaviour table and one in
104
+ the embedded-engine table, the comparison and roadmap rows, and the example notebook
105
+ `examples/v0.31.0_events_ddl_helpers.ipynb`. Section 17's example declares its function with
106
+ `define_function()`.
107
+
108
+ ### Changed
109
+
110
+ - **`EventState` gains `async_mode`, `retry` and `max_depth`** (keyword-only, after `comment`;
111
+ `False`, `None` and `None` by default), and **`DatabaseIntrospector` reads SurrealDB 3.x
112
+ `ASYNC` events**: 0.30.x reported such an event as a `SchemaIssue`. SurrealDB 3.x renders
113
+ `RETRY` and `MAXDEPTH` with every `ASYNC`, so an event defined without them reads back
114
+ `retry=1, max_depth=3`.
115
+ - **`call_function(params=)` follows a redefinition made with `define_function()` or
116
+ `remove_function()` at once**: both drop the function's cached signature on every connection of
117
+ this process to the same namespace and database, whatever its URL (an admin connection applying
118
+ the DDL over `http://` and the application's `ws://` connection alike), so even a reorder of the
119
+ same parameter names is picked up. A signature read that such a drop, or
120
+ `clear_function_signature_cache()`, overtakes is read again rather than cached. A function
121
+ redefined with raw DDL or from another process still needs `clear_function_signature_cache()`.
122
+
123
+ ### Notes
124
+
125
+ - **Names are validated and quoted, comments escaped**: event, table, parameter and function names
126
+ are checked as identifiers before any request, event and table names are written in backticks
127
+ (`update` or `delete` work as event names), and a comment is an escaped string literal. A
128
+ parameter name SurrealDB defines itself (`auth`, `session`, `this`, …) is refused.
129
+ - **Expressions are trusted application code, never user input.** `when`, `then`, function
130
+ bodies, kinds and permission conditions are written into the statement as given, since SurrealDB
131
+ takes no bound parameter in a definition. Their structural check (strings terminated, brackets
132
+ balanced, no NUL, no SurrealQL comment marker outside a literal, every `/` read as an operator,
133
+ no `;` outside brackets where one expression is expected) catches mistakes — unbalanced
134
+ brackets, a comment that would swallow the clauses the ORM appends, a second statement where one
135
+ expression is expected — and is not an injection defence. To use a value, read it from the
136
+ record (`$after.email`) or from a `DEFINE PARAM`. Every refusal is a `TypeError` or a
137
+ `ValueError` raised before any request. An `Event`'s `repr()` leaves out `when` and `then`, and
138
+ a refusal the server returns to a call without `tx=` names the event or the function, never its
139
+ statement (with `tx=`, see #278).
140
+ - **Kinds are written in canonical form**: `none | int` and `option<int>` are both written
141
+ `option<int>`, and a kind the ORM cannot read raises `ValueError` rather than being rewritten.
142
+ - **SurrealDB 2.x and 3.x**: `ASYNC` events are 3.x only (refused before any DDL elsewhere);
143
+ `$input` holds the fields the write sent on 3.x and is `NONE` on 2.x and the embedded engine; a
144
+ write that changes nothing fires no event, except on 3.x an `UPSERT` (the ORM's `upsert()` of an
145
+ unchanged record), which fires one `UPDATE` event; read back, each line renders event and
146
+ function definitions its own way (README section 32 and the 2.x/3.x table).
147
+ - **A write an event refuses** (a `THROW`, an error in `then`) raises the SDK's `InternalError`,
148
+ as any server refusal of a write does, and nothing is written. Every applier takes `tx=`, and
149
+ events work inside `transaction()` like any other statement.
150
+ - **Query cache, live queries and signals**: the query cache forgets the tables the ORM itself
151
+ writes, not the rows an event writes, so do not cache reads of a table events write, or call
152
+ `QueryCache.invalidate(Model)` after the write. Live queries see those rows. Applying DDL and the
153
+ rows events write fire no ORM signal.
154
+ - **Applying a definition needs a privileged system user** (root, or a namespace or database
155
+ `OWNER` or `EDITOR`): run `define_events()` and `define_function()` at start-up or deployment.
156
+ - **Differences from the full SurrealDB-ORM**: events are declared in
157
+ `SurrealConfigDict(events=[...])` rather than a `class Meta`, and the lite's `Event` adds
158
+ `max_depth=`; `then` is written `THEN { … }` where the full ORM writes `THEN (…)`, in which `LET`
159
+ and `THROW` fail; names are quoted and comments escaped with a backslash; `define_function()`
160
+ has no full-ORM equivalent (the full ORM uses `RawSQL`).
161
+ - **Deferred**: the migration operations (`DefineEvent`, `RemoveEvent`, a function operation) and
162
+ the removal of events a model no longer declares come with v0.37.0 (migrations):
163
+ `define_events()` leaves such an event defined until `remove_event()` removes it.
164
+ `generate_models_from_db()` lists a table's events in a class comment, not as `events=[...]`.
165
+ - The `SurrealConfigDict` keys that generated classes stand in for with comments (`table_type`,
166
+ `permissions`, `changefeed`, `view_query`, `relation_in`, `relation_out`, `enforced`), which the
167
+ 0.30.0 and 0.30.8 notes placed in v0.31.0–v0.33.0, are not part of this release: README section
168
+ 31 now places them in v0.32.0–v0.34.0.
169
+ - **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine,
170
+ plus 3.1.5 for backward compatibility.
171
+
172
+ ## [0.30.8] - 2026-10-19
173
+
174
+ Follow-ups to the v0.30.0 schema introspection (#260): a connection lost while the schema is read
175
+ raises instead of becoming schema issues, a relation table is an edge whatever the case of its
176
+ `table_type`, and generated classes carry the change feed and permissions comments the v0.30.0
177
+ notes described. No new public API.
178
+
179
+ ### Fixed
180
+
181
+ - **A connection lost during `introspect()` raises** (#260). Every error of an `INFO FOR TABLE`
182
+ became a `SchemaIssue`, so a connection that dropped after `INFO FOR DB` turned every remaining
183
+ table into "could not be read": `introspect()` returned normally, and
184
+ `generate_models_from_db(path)` replaced a working module with one that listed those tables as
185
+ skipped. Only the server's answer to `INFO FOR TABLE` is an issue now; the transport's error, or
186
+ the ORM's, propagates unchanged before anything is written, so an existing file is left as it
187
+ was.
188
+ - **A relation table is an edge whatever the case of its `table_type`** (#260). The generator
189
+ compared `table_type` with exact case in two places and ignored case in a third: a hand-built
190
+ `TableState(table_type="RELATION")` gave a `BaseSurrealEdge` class that declared `in_` and `out`
191
+ again, and the module failed to import with a `TypeError`. States read by `DatabaseIntrospector`
192
+ hold `"relation"` and were not affected.
193
+ - **Generated classes comment their change feed and permissions** (#260), as the v0.30.0 notes
194
+ said: `# Changefeed: 1d INCLUDE ORIGINAL` and
195
+ `# Permissions: FOR select WHERE $auth.id = owner, FOR create, update FULL, FOR delete NONE`,
196
+ grouped the way SurrealDB renders them (`# Permissions: FULL` when `FULL` covers the four
197
+ operations). A table left at the default `PERMISSIONS NONE`, all four operations `NONE`, gets no
198
+ permissions comment. The database still applies both; the `SurrealConfigDict` keys for them
199
+ arrive with v0.31.0–v0.33.0. Unlike what those notes listed, `table_type` is not a comment: it
200
+ shows through the base class, `BaseSurrealEdge` for a relation table.
201
+
202
+ ### Changed
203
+
204
+ - **An `INFO FOR TABLE` refused after `INFO FOR DB` succeeded raises
205
+ `SurrealDbAuthenticationError`** (#260) instead of becoming a `SchemaIssue`: the session lost its
206
+ rights while the schema was read (for example a client closed and reopened anonymously), and the
207
+ table is not at fault. A refused `INFO FOR DB` raises the same error, as in v0.30.0.
208
+
209
+ ### Notes
210
+
211
+ - Docstrings and comments no longer cite internal design-note ids: they name the exception raised,
212
+ the case refused or the README section that documents it. README section 31 describes the new
213
+ class comments and which `INFO FOR TABLE` failures are schema issues.
214
+ - The linear-time tests of the definition parser keep the fastest of up to three timings, so a
215
+ pause of a shared CI runner cannot fail them.
216
+ - Same behaviour on SurrealDB 2.x, 3.x and the embedded engine. Server pins unchanged: tested
217
+ against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine, plus 3.1.5 for backward
218
+ compatibility.
219
+
8
220
  ## [0.30.7] - 2026-10-19
9
221
 
10
222
  An instance stays in step with its stored row (#261): `save()` applies the whole row the server