surreal-orm-lite 0.36.3__tar.gz → 0.36.5__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 (50) hide show
  1. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/CHANGELOG.md +102 -0
  2. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/PKG-INFO +28 -9
  3. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/README.md +27 -8
  4. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/cache.py +21 -8
  7. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/connection_manager.py +19 -4
  8. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/edge.py +14 -7
  9. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/model_base.py +175 -59
  10. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/query_set.py +84 -31
  11. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/search.py +98 -11
  12. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/transaction.py +52 -8
  13. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/.gitignore +0 -0
  14. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/LICENSE +0 -0
  15. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/Makefile +0 -0
  16. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/_sdk.py +0 -0
  17. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/aggregations.py +0 -0
  18. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/auth.py +0 -0
  19. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/changefeed.py +0 -0
  20. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/concurrency.py +0 -0
  21. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/connection_config.py +0 -0
  22. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/constants.py +0 -0
  23. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/decoding.py +0 -0
  24. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/define_parser.py +0 -0
  25. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/embedded.py +0 -0
  26. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/encoding.py +0 -0
  27. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/enum.py +0 -0
  28. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/exceptions.py +0 -0
  29. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/functions.py +0 -0
  30. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/geo.py +0 -0
  31. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/introspection.py +0 -0
  32. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/live.py +0 -0
  33. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/model_auth.py +0 -0
  34. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/model_ddl.py +0 -0
  35. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/model_generator.py +0 -0
  36. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/py.typed +0 -0
  37. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/q.py +0 -0
  38. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/routing.py +0 -0
  39. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/schema.py +0 -0
  40. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/schema_state.py +0 -0
  41. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/signals.py +0 -0
  42. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/subquery.py +0 -0
  43. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/surql_literal.py +0 -0
  44. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/testing/__init__.py +0 -0
  45. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/testing/database.py +0 -0
  46. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  47. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/time_travel.py +0 -0
  48. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/types.py +0 -0
  49. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/utils.py +0 -0
  50. {surreal_orm_lite-0.36.3 → surreal_orm_lite-0.36.5}/src/surreal_orm_lite/vector.py +0 -0
@@ -5,6 +5,108 @@ 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.36.5] - 2026-10-24
9
+
10
+ Follow-up to v0.36.1 (#315): a queryset write that the ORM refuses, and an instance write
11
+ refused for one of its arguments, now leave the transaction and the query cache as they were.
12
+ No new public API.
13
+
14
+ ### Fixed
15
+
16
+ - **A refused queryset write no longer marks its table as written** (#320).
17
+ `objects(tx=tx).bulk_create()`, `bulk_update()`, `bulk_delete()` and `patch()` ran their
18
+ materialized-view and `as_of()` refusals, `bulk_create()`'s check of a snapshot in its list,
19
+ `bulk_update()`'s check of a subquery value or a computed field and `patch()`'s check of its
20
+ operations after the ORM had noted the table on the transaction. The refused call queued no
21
+ statement but left the table noted: a caller that caught the error and kept the transaction had
22
+ a later `define_indexes(tx=tx)` on that table refused by the v0.35.3 check (#304), and the
23
+ commit dropped the table's cached reads although nothing was written. Outside a transaction,
24
+ the refused call (a queryset read `as_of()` included, and `delete_table()` on a view or under
25
+ `as_of()`) put the table in flight and dropped its cached reads. These refusals now run before
26
+ anything is noted: the transaction keeps no statement and no table, `define_indexes(tx=tx)` is
27
+ accepted, and no cached read is dropped, with a transaction or without.
28
+ - **An instance write refused for one of its arguments no longer marks its table as written**
29
+ (#320). `update()` and `delete()` without an id, `patch()` refused for its operations, a
30
+ computed field or a missing id, `merge()` refused for its fields, `server_values`/`extra_vars`
31
+ or a missing id, `save()` refused for `server_values`/`extra_vars`, the `atomic_*()` helpers
32
+ refused for their amount, field, values or a missing id, and an edge's `save(server_values=…)`
33
+ or `save(extra_vars=…)` had the same effect as above, with `tx=` or without. These checks now
34
+ run right after the model's own refusals (materialized view, snapshot, excluded signup field)
35
+ and before anything is noted. Error types, messages and the refusal order are unchanged: the
36
+ connection, the model's refusals, then the arguments (`update()` and `patch()` still build their
37
+ payload before reading the id). The bookkeeping is client-side: the behaviour is the same on
38
+ SurrealDB 2.x and 3.x and on both transaction strategies.
39
+
40
+ ### Notes
41
+
42
+ - A few refusals still run after the table is noted (`upsert()` without an id, a buffered
43
+ `save(tx=…)` without an id, the argument checks of `relate()`, `remove_relation()` and
44
+ `remove_all_relations()`, among others); they are tracked in #325.
45
+ - **Docs**: the README sections "Snapshots" and "What a time-travel queryset refuses" (27),
46
+ "Writes are refused" (33) and the `define_indexes(tx=…)` note of "Transactions" (36), and the
47
+ docstrings of the affected writes, say that a refused write leaves the transaction and the query
48
+ cache as they were. No behaviour-table row: the change is client-side and identical on both
49
+ lines.
50
+ - Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0, plus 3.1.5 for backward
51
+ compatibility.
52
+
53
+ ## [0.36.4] - 2026-10-24
54
+
55
+ Follow-ups to the review of v0.36.2 (#322): an index that `remove_index(tx=…)` removed earlier
56
+ in a transaction no longer blocks `remove_analyzer(tx=…)` or `define_analyzer(tx=…)` in the same
57
+ block, `define_indexes(tx=…)` no longer defines an index with an analyzer the block removed or
58
+ redefined, and the v0.36.2 fix is tested on vector (HNSW) indexes. No new public API.
59
+
60
+ ### Fixed
61
+
62
+ - **`remove_analyzer(tx=…)` and `define_analyzer(tx=…)` no longer count an index the block
63
+ removed** (#323). Both find the indexes that use the analyzer by reading `INFO FOR TABLE`
64
+ outside the transaction, where an index that `remove_index(tx=…)` removed earlier in the block
65
+ still stands. Once a block had removed the last index using an analyzer, `remove_analyzer(tx=…)`
66
+ was refused on SurrealDB 2.x and the embedded engine ("in use by index …"), and
67
+ `define_analyzer(…, overwrite=True, tx=…)` was refused on every engine as a redefinition with
68
+ indexes to rebuild. Both now leave out the indexes the transaction noted as removed: the
69
+ analyzer can be removed, or redefined without `REBUILD INDEX`, in the same block, on SurrealDB
70
+ 2.x and 3.x, over WebSocket and HTTP and on the embedded engine. An index still standing keeps
71
+ the refusal, with the same message: another table's, another index of the same table, one
72
+ removed then defined again in the block, one removed with a raw `tx.add("REMOVE INDEX …")`
73
+ (not tracked), or any index when no `tx=` is given. SurrealDB 3.x already accepted the removal,
74
+ since the server checks it in the transaction. An index queued earlier in a buffered block is
75
+ still not seen.
76
+ - **`define_analyzer(tx=…)` after `remove_analyzer(tx=…)` of the same name defines the analyzer
77
+ again** (#323). It compared the analyzer with committed state, where the removed one still
78
+ stood, so an unchanged definition (or any definition without `overwrite=True`) applied nothing
79
+ and the commit left the database without the analyzer. The removed analyzer now counts as
80
+ missing: it is defined again after its removal, with no index read nor rebuilt.
81
+
82
+ ### Changed
83
+
84
+ - **`define_indexes(tx=…)` refuses an index whose analyzer the block removed or redefined**
85
+ (#323), whether the model declares the analyzer as an `Analyzer` or names it by `str`. Until
86
+ v0.36.3 it read the analyzers from committed state only, so it defined such an index: after
87
+ `remove_analyzer(tx=…)`, the index stood without its analyzer once the block committed, and
88
+ every write to the table was then refused; after `define_analyzer(…, overwrite=True, tx=…)`,
89
+ SurrealDB built the index over the table's records with the committed definition, not the new
90
+ one (on SurrealDB 3.x a search then missed those records, without an error). A removed analyzer
91
+ now counts as missing (an `Analyzer` is refused as one to define in a transaction, a name as one
92
+ that does not exist), and an index whose analyzer the block redefined is refused with a new
93
+ message. Both refusals raise `SurrealDbError` before any DDL and do not fail the block. To
94
+ migrate an index to a new analyzer, call `define_analyzer()` without `tx=` first.
95
+
96
+ ### Notes
97
+
98
+ - **Tests**: the v0.36.2 fix (#312) is now covered on a vector (HNSW) index: `remove_index(tx=…)`
99
+ then `define_indexes(tx=…)` in one block, over WebSocket, HTTP and the embedded engine, on an
100
+ empty table and on one holding a record. The index stands after the commit and serves
101
+ `similar_to()`; on SurrealDB 2.x, a table holding a record fails the commit with the retryable
102
+ `SurrealDbConflictError` and keeps the index, as the README's v0.36.2 row says.
103
+ - **Docs**: README section 36 (Transactions) and the docstrings of `define_indexes()`,
104
+ `remove_index()`, `define_analyzer()` and `remove_analyzer()` describe these cases. No
105
+ behaviour-table row changes: for an index removed with `remove_index(tx=…)`, the analyzer
106
+ checks now give the same result on SurrealDB 2.x and 3.x and on the embedded engine.
107
+ - Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine,
108
+ plus 3.1.5 for backward compatibility.
109
+
8
110
  ## [0.36.3] - 2026-10-24
9
111
 
10
112
  Follow-up to the review of v0.36.0 (#316): a vector field declared with `| None` keeps its
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.36.3
3
+ Version: 0.36.5
4
4
  Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
5
5
  Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
6
6
  Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
@@ -3395,8 +3395,9 @@ check. The moment is always a bound parameter.
3395
3395
  The instances a time-travel read returns are **snapshots**, read-only: `save()`, `update()`,
3396
3396
  `merge()`, `patch()`, `upsert()`, `delete()`, the `atomic_*()` methods, `relate()`,
3397
3397
  `remove_relation()` and `remove_all_relations()` raise `SurrealDbError` before any signal or
3398
- request, and `bulk_create()` refuses a snapshot in its list. To restore a past state, build a new
3399
- instance from the snapshot:
3398
+ request, and `bulk_create()` refuses a snapshot in its list. A refused write leaves a transaction
3399
+ as it was (no statement, its table not counted as written) and drops no cached read. To restore a
3400
+ past state, build a new instance from the snapshot:
3400
3401
 
3401
3402
  ```python
3402
3403
  from surreal_orm_lite import SurrealDbError
@@ -3450,9 +3451,9 @@ assert old_desk != current_desk and old_desk.model_dump() == current_desk.model_
3450
3451
  A time-travel read is read-only and cannot be streamed: `bulk_create()`, `bulk_update()`,
3451
3452
  `bulk_delete()`, `patch()`, `update_or_create()`, `get_or_create()`, `delete_table()`, `query()`,
3452
3453
  `live()`, `watch()` and `changes()` raise `SurrealDbError` on a queryset with `as_of()`, before
3453
- any request. History cannot join a transaction: `Model.objects(tx=...).as_of(...)` raises at the
3454
- call. On the embedded engine, a URL that keeps no history raises before any request, naming
3455
- `surrealkv+versioned://`.
3454
+ any request and without dropping any cached read. History cannot join a transaction:
3455
+ `Model.objects(tx=...).as_of(...)` raises at the call. On the embedded engine, a URL that keeps
3456
+ no history raises before any request, naming `surrealkv+versioned://`.
3456
3457
 
3457
3458
  #### SurrealDB 2.x without versioned storage
3458
3459
 
@@ -4955,6 +4956,10 @@ print([(str(order.id), order.amount) for order in await PaidOrder.objects().orde
4955
4956
  `bulk_delete()`, `patch()`, `update_or_create()`, `get_or_create()` (even when the record exists) and
4956
4957
  `delete_table()`. The message starts with the full ORM's `Cannot modify materialized view '<table>'` and names the
4957
4958
  call: write to the tables the view selects from instead.
4959
+ - The refusal comes before the call's own argument checks (a missing id, an invalid patch operation, a snapshot in
4960
+ `bulk_create()`'s list…). A refused call, under `tx=` or `objects(tx=…)`, leaves the transaction as it was: no
4961
+ statement, and its table is not counted as written, so a later `define_indexes(tx=…)` of the model in the block is
4962
+ not refused for it and the commit drops no cached read. Outside a transaction it drops no cached read either.
4958
4963
  - `refresh()`, `relate()`, `remove_relation()`, `remove_all_relations()`, `define_events()` and `remove_event()` stay
4959
4964
  allowed: they do not write the view's table.
4960
4965
  - Raw SurrealQL (`raw_query()`, `QuerySet.query()`, the client's `query()`) is not checked: SurrealDB 3.2 and later
@@ -6104,13 +6109,27 @@ print(await NoteV2.objects().search(text="physics").count())
6104
6109
  has already written records to the model's table with the ORM (`save()`, `objects(tx=…).bulk_create()`, …). The
6105
6110
  refusal covers every kind of index, not only full-text ones: a search would miss those records, and a `UNIQUE` index
6106
6111
  missing them would not enforce uniqueness for them. The refusal does not fail the block. `define_table(tx=…)`,
6107
- `define_relation(tx=…)` and a write to another table do not count; a raw `tx.add()` is not tracked.
6112
+ `define_relation(tx=…)` and a write to another table do not count, nor does a write the ORM refused for a
6113
+ materialized view or a snapshot read with `as_of()` (a snapshot in `bulk_create()`'s list included), an `update()`,
6114
+ `merge()`, `patch()`, `delete()` or `atomic_*()` call refused for a missing id, or a `patch()` refused for its
6115
+ operations; a raw `tx.add()` is not tracked.
6108
6116
  - Prefer `define_indexes()` outside the block: on SurrealDB 2.x, a write to a table that held records, after its index
6109
6117
  in the same block, fails the commit with a retryable `SurrealDbConflictError` that a retry meets again; so does a
6110
6118
  block that removes an index of a table that held records and defines it again, where the index stands as before.
6111
6119
  Nothing of such a block is committed. On an empty table both commit, as on 3.x.
6112
- - `remove_analyzer(tx=…)` reads committed state to find the indexes that use the analyzer: an index queued earlier in
6113
- a buffered block is not seen.
6120
+ - `remove_analyzer(tx=…)` (on SurrealDB 2.x and the embedded engine; 3.x checks in the transaction itself) and
6121
+ `define_analyzer(tx=…)` read committed state to find the indexes that use the analyzer. An index `remove_index(tx=…)`
6122
+ removed earlier in the block no longer counts, although committed state still holds it: once the block has removed the
6123
+ last index that uses an analyzer, it can remove the analyzer, or redefine it without `REBUILD INDEX`, on every engine.
6124
+ An index removed then defined again in the block, or removed with a raw `tx.add("REMOVE INDEX …")`, still counts
6125
+ there, and an index queued earlier in a buffered block is not seen.
6126
+ - Once the block has removed or redefined an analyzer, an index that uses it can no longer be defined in the block,
6127
+ whether the model declares the analyzer as an `Analyzer` or names it by `str`: `define_indexes(tx=…)` raises
6128
+ `SurrealDbError` before any DDL. A removed analyzer counts as missing, although committed state still holds it — the
6129
+ index would stand without it after the commit, and every write to the table would be refused. A redefined one would
6130
+ not be followed: SurrealDB would build the index with the committed definition. The refusal does not fail the block.
6131
+ To migrate an index to a new analyzer, call `define_analyzer()` without `tx=` first. `define_analyzer(tx=…)` after
6132
+ `remove_analyzer(tx=…)` of the same name defines the analyzer again, after its removal.
6114
6133
  - A search in an interactive transaction sees the transaction's writes; in a buffered one, a read raises, as every
6115
6134
  read does there.
6116
6135
  - In a transaction, a search on a field without a full-text index raises the same `SurrealDbError`, which the
@@ -3344,8 +3344,9 @@ check. The moment is always a bound parameter.
3344
3344
  The instances a time-travel read returns are **snapshots**, read-only: `save()`, `update()`,
3345
3345
  `merge()`, `patch()`, `upsert()`, `delete()`, the `atomic_*()` methods, `relate()`,
3346
3346
  `remove_relation()` and `remove_all_relations()` raise `SurrealDbError` before any signal or
3347
- request, and `bulk_create()` refuses a snapshot in its list. To restore a past state, build a new
3348
- instance from the snapshot:
3347
+ request, and `bulk_create()` refuses a snapshot in its list. A refused write leaves a transaction
3348
+ as it was (no statement, its table not counted as written) and drops no cached read. To restore a
3349
+ past state, build a new instance from the snapshot:
3349
3350
 
3350
3351
  ```python
3351
3352
  from surreal_orm_lite import SurrealDbError
@@ -3399,9 +3400,9 @@ assert old_desk != current_desk and old_desk.model_dump() == current_desk.model_
3399
3400
  A time-travel read is read-only and cannot be streamed: `bulk_create()`, `bulk_update()`,
3400
3401
  `bulk_delete()`, `patch()`, `update_or_create()`, `get_or_create()`, `delete_table()`, `query()`,
3401
3402
  `live()`, `watch()` and `changes()` raise `SurrealDbError` on a queryset with `as_of()`, before
3402
- any request. History cannot join a transaction: `Model.objects(tx=...).as_of(...)` raises at the
3403
- call. On the embedded engine, a URL that keeps no history raises before any request, naming
3404
- `surrealkv+versioned://`.
3403
+ any request and without dropping any cached read. History cannot join a transaction:
3404
+ `Model.objects(tx=...).as_of(...)` raises at the call. On the embedded engine, a URL that keeps
3405
+ no history raises before any request, naming `surrealkv+versioned://`.
3405
3406
 
3406
3407
  #### SurrealDB 2.x without versioned storage
3407
3408
 
@@ -4904,6 +4905,10 @@ print([(str(order.id), order.amount) for order in await PaidOrder.objects().orde
4904
4905
  `bulk_delete()`, `patch()`, `update_or_create()`, `get_or_create()` (even when the record exists) and
4905
4906
  `delete_table()`. The message starts with the full ORM's `Cannot modify materialized view '<table>'` and names the
4906
4907
  call: write to the tables the view selects from instead.
4908
+ - The refusal comes before the call's own argument checks (a missing id, an invalid patch operation, a snapshot in
4909
+ `bulk_create()`'s list…). A refused call, under `tx=` or `objects(tx=…)`, leaves the transaction as it was: no
4910
+ statement, and its table is not counted as written, so a later `define_indexes(tx=…)` of the model in the block is
4911
+ not refused for it and the commit drops no cached read. Outside a transaction it drops no cached read either.
4907
4912
  - `refresh()`, `relate()`, `remove_relation()`, `remove_all_relations()`, `define_events()` and `remove_event()` stay
4908
4913
  allowed: they do not write the view's table.
4909
4914
  - Raw SurrealQL (`raw_query()`, `QuerySet.query()`, the client's `query()`) is not checked: SurrealDB 3.2 and later
@@ -6053,13 +6058,27 @@ print(await NoteV2.objects().search(text="physics").count())
6053
6058
  has already written records to the model's table with the ORM (`save()`, `objects(tx=…).bulk_create()`, …). The
6054
6059
  refusal covers every kind of index, not only full-text ones: a search would miss those records, and a `UNIQUE` index
6055
6060
  missing them would not enforce uniqueness for them. The refusal does not fail the block. `define_table(tx=…)`,
6056
- `define_relation(tx=…)` and a write to another table do not count; a raw `tx.add()` is not tracked.
6061
+ `define_relation(tx=…)` and a write to another table do not count, nor does a write the ORM refused for a
6062
+ materialized view or a snapshot read with `as_of()` (a snapshot in `bulk_create()`'s list included), an `update()`,
6063
+ `merge()`, `patch()`, `delete()` or `atomic_*()` call refused for a missing id, or a `patch()` refused for its
6064
+ operations; a raw `tx.add()` is not tracked.
6057
6065
  - Prefer `define_indexes()` outside the block: on SurrealDB 2.x, a write to a table that held records, after its index
6058
6066
  in the same block, fails the commit with a retryable `SurrealDbConflictError` that a retry meets again; so does a
6059
6067
  block that removes an index of a table that held records and defines it again, where the index stands as before.
6060
6068
  Nothing of such a block is committed. On an empty table both commit, as on 3.x.
6061
- - `remove_analyzer(tx=…)` reads committed state to find the indexes that use the analyzer: an index queued earlier in
6062
- a buffered block is not seen.
6069
+ - `remove_analyzer(tx=…)` (on SurrealDB 2.x and the embedded engine; 3.x checks in the transaction itself) and
6070
+ `define_analyzer(tx=…)` read committed state to find the indexes that use the analyzer. An index `remove_index(tx=…)`
6071
+ removed earlier in the block no longer counts, although committed state still holds it: once the block has removed the
6072
+ last index that uses an analyzer, it can remove the analyzer, or redefine it without `REBUILD INDEX`, on every engine.
6073
+ An index removed then defined again in the block, or removed with a raw `tx.add("REMOVE INDEX …")`, still counts
6074
+ there, and an index queued earlier in a buffered block is not seen.
6075
+ - Once the block has removed or redefined an analyzer, an index that uses it can no longer be defined in the block,
6076
+ whether the model declares the analyzer as an `Analyzer` or names it by `str`: `define_indexes(tx=…)` raises
6077
+ `SurrealDbError` before any DDL. A removed analyzer counts as missing, although committed state still holds it — the
6078
+ index would stand without it after the commit, and every write to the table would be refused. A redefined one would
6079
+ not be followed: SurrealDB would build the index with the committed definition. The refusal does not fail the block.
6080
+ To migrate an index to a new analyzer, call `define_analyzer()` without `tx=` first. `define_analyzer(tx=…)` after
6081
+ `remove_analyzer(tx=…)` of the same name defines the analyzer again, after its removal.
6063
6082
  - A search in an interactive transaction sees the transaction's writes; in a buffered one, a read raises, as every
6064
6083
  read does there.
6065
6084
  - In a transaction, a search on a field without a full-text index raises the same `SurrealDbError`, which the
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.36.3"
3
+ version = "0.36.5"
4
4
  description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -1,4 +1,4 @@
1
- __version__ = "0.36.3"
1
+ __version__ = "0.36.5"
2
2
 
3
3
  from ._sdk import BoundExcluded, BoundIncluded
4
4
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
@@ -755,10 +755,10 @@ _MODEL_RESOLVERS: Final = frozenset({"self", "cls", "edge"})
755
755
  def _resolve(
756
756
  of: _Of, first: str, bound: inspect.BoundArguments, has_tx: bool, deletes: bool
757
757
  ) -> tuple[frozenset[str] | None, Any]:
758
- """The tables a call writes and the transaction it joins; every table when resolving raises."""
758
+ """The tables a call writes and the transaction it joins; every table when resolving raises. *bound* has its
759
+ defaults applied."""
759
760
  tx: Any = None
760
761
  try:
761
- bound.apply_defaults()
762
762
  if has_tx:
763
763
  tx = bound.arguments.get("tx")
764
764
  if of == "all":
@@ -791,7 +791,12 @@ def _note_records(tables: frozenset[str] | None, tx: Any) -> None:
791
791
 
792
792
 
793
793
  def invalidates(
794
- of: _Of, *, deletes: bool = False, records: bool = True, refuse: Callable[[Any], None] | None = None
794
+ of: _Of,
795
+ *,
796
+ deletes: bool = False,
797
+ records: bool = True,
798
+ refuse: Callable[[Any], None] | None = None,
799
+ refuse_args: Callable[[Mapping[str, Any]], None] | None = None,
795
800
  ) -> Callable[[F], F]:
796
801
  """Decorate an ORM write method so that it invalidates the cached reads it can change.
797
802
 
@@ -813,11 +818,16 @@ def invalidates(
813
818
  on the transaction, so a refused write invalidates nothing. The transaction is read statically, never asked. A
814
819
  queryset's transaction is checked by ``objects(tx=)``.
815
820
 
816
- ``refuse`` (issue #315) runs the method's own refusals — the model's materialized-view, snapshot and excluded
817
- signup field checks — with the call's first argument, right after that connection check and before the tables
818
- are noted on the transaction or put in flight, with a transaction or without. Whatever it raises propagates: a
819
- write it refuses leaves the transaction as it was (no statement, no table noted) and invalidates nothing. It is
820
- not called when the arguments do not bind (Python raises the function's own error).
821
+ ``refuse`` (issue #315) runs the method's own refusals with the call's first argument: the model's
822
+ materialized-view, snapshot and excluded signup field checks, or a queryset's materialized-view and ``as_of()``
823
+ checks (issue #320). Then ``refuse_args`` (issue #320) runs the checks of the call's other arguments that need no
824
+ request — a missing id, invalid patch operations, ``extra_vars`` without ``server_values``, a snapshot in
825
+ ``bulk_create()``'s list… — with the bound arguments by name, defaults applied. Both run right after that
826
+ connection check and before the tables are noted on the transaction or put in flight, with a transaction or
827
+ without, so the refusal order is the connection, the method's own refusals, then the arguments. They send nothing
828
+ and never ask the transaction. Whatever they raise propagates: a write they refuse leaves the transaction as it was
829
+ (no statement, no table noted) and invalidates nothing — no table in flight, no cached read dropped. Neither is
830
+ called when the arguments do not bind (Python raises the function's own error).
821
831
  """
822
832
  if of not in _RESOLVERS:
823
833
  raise ValueError(f"invalidates() takes one of {sorted(_RESOLVERS)}, not {of!r}")
@@ -833,6 +843,7 @@ def invalidates(
833
843
  bound = signature.bind(*args, **kwargs)
834
844
  except TypeError:
835
845
  return await func(*args, **kwargs) # Python raises the function's own error
846
+ bound.apply_defaults()
836
847
  tables, tx = _resolve(of, first, bound, has_tx, deletes)
837
848
  if tx is not None and of in _MODEL_RESOLVERS and first in bound.arguments:
838
849
  arg0 = bound.arguments[first]
@@ -840,6 +851,8 @@ def invalidates(
840
851
  _routing.check_transaction(model, tx, f"{model.__name__}.{func.__name__}()")
841
852
  if refuse is not None and first in bound.arguments:
842
853
  refuse(bound.arguments[first])
854
+ if refuse_args is not None:
855
+ refuse_args(bound.arguments)
843
856
  if records and tx is not None:
844
857
  _note_records(tables, tx)
845
858
  async with writing(tables, tx):
@@ -2746,7 +2746,15 @@ class SurrealDBConnectionManager:
2746
2746
 
2747
2747
  With *tx*, a new analyzer — or a redefinition no index uses — joins the transaction. A redefinition with indexes
2748
2748
  to rebuild is refused before any DDL: the servers rebuild an index with the analyzers committed before the
2749
- transaction began, so the rebuild must follow the committed definition.
2749
+ transaction began, so the rebuild must follow the committed definition. An index ``Model.remove_index()``
2750
+ removed earlier with the same *tx* is not to rebuild, although committed state still holds it: once the block
2751
+ has removed every index that uses the analyzer, the redefinition joins the transaction, without
2752
+ ``REBUILD INDEX``. An index removed then defined again in the block (``define_indexes(tx=…)``), or removed with
2753
+ a raw ``tx.add("REMOVE INDEX …")``, which the transaction does not track, still counts. The transaction notes
2754
+ the analyzer it defines or redefines: ``Model.define_indexes(tx=…)`` then refuses, before any DDL, to define in
2755
+ the block an index that uses it — SurrealDB would build it with the committed definition. An analyzer
2756
+ :meth:`remove_analyzer` removed earlier with the same *tx* counts as missing, although committed state still
2757
+ holds it: it is defined again after its removal.
2750
2758
 
2751
2759
  :param analyzer: the ``Analyzer`` to define.
2752
2760
  :param overwrite: ``True`` (default) redefines a changed analyzer (``OVERWRITE``) and rebuilds its indexes;
@@ -2790,9 +2798,16 @@ class SurrealDBConnectionManager:
2790
2798
  removed``. SurrealDB 3.x refuses it itself; on SurrealDB 2.x and the embedded engine, which would remove it and
2791
2799
  then refuse every write to that table, the ORM reads the line (``client.version()``), then ``INFO FOR DB`` and
2792
2800
  ``INFO FOR TABLE`` of every table, and refuses it before any DDL. Remove its indexes first
2793
- (``Model.remove_index()``). In a buffered transaction those reads see the committed state: an index queued
2794
- earlier in the block is not seen. No cached read is dropped: a removal succeeds only when no index uses the
2795
- analyzer.
2801
+ (``Model.remove_index()``). With *tx*, those reads see the committed state: an index ``Model.remove_index()``
2802
+ removed earlier with the same *tx* is left out, although committed state still holds it, so a block that
2803
+ removes the last index using the analyzer and then the analyzer commits, as on SurrealDB 3.x, which checks in
2804
+ the transaction; an index removed then defined again in the block, or removed with a raw
2805
+ ``tx.add("REMOVE INDEX …")``, which the transaction does not track, still counts, and an index queued earlier in
2806
+ a buffered block is not seen. The transaction notes the removal: ``Model.define_indexes(tx=…)`` then counts the
2807
+ analyzer as missing, although committed state still holds it, and refuses, before any DDL, to define in the
2808
+ block an index that uses it — the commit would leave that index without its analyzer, and every write to its
2809
+ table refused; :meth:`define_analyzer` with the same *tx* defines it again. No cached read is dropped: a
2810
+ removal succeeds only when no index uses the analyzer.
2796
2811
 
2797
2812
  :param analyzer: the analyzer's name (letters, digits, underscores; not starting with a digit).
2798
2813
  :param missing_ok: ``True`` (default) emits ``REMOVE ANALYZER IF EXISTS …``, so a missing analyzer is not an
@@ -63,6 +63,17 @@ _GUARDED_INSERT = (
63
63
  )
64
64
 
65
65
 
66
+ def _save_arguments(arguments: Mapping[str, Any]) -> None:
67
+ """An edge's ``save()`` argument check, for ``invalidates(refuse_args=…)`` (#320): ``server_values`` and
68
+ ``extra_vars`` are refused, after the snapshot refusal and before the edge table is noted on the transaction or
69
+ put in flight — ``INSERT RELATION`` cannot evaluate ``SET`` expressions."""
70
+ if arguments["server_values"] or arguments["extra_vars"]:
71
+ raise SurrealDbError(
72
+ "save(server_values=) is not available on an edge: INSERT RELATION cannot evaluate SET "
73
+ "expressions. Use DEFINE FIELD … DEFAULT/VALUE on the edge table."
74
+ )
75
+
76
+
66
77
  def _check_edge_id(model: BaseSurrealModel) -> None:
67
78
  """Refuse, before any call, an edge id the server would misread.
68
79
 
@@ -454,7 +465,7 @@ class BaseSurrealEdge(BaseSurrealModel):
454
465
  """``in_``/``out``: SurrealDB ignores a change to an existing edge's endpoints."""
455
466
  return _ENDPOINT_FIELDS
456
467
 
457
- @_cache.invalidates("self", refuse=_write_refusals("save()"))
468
+ @_cache.invalidates("self", refuse=_write_refusals("save()"), refuse_args=_save_arguments)
458
469
  async def save(
459
470
  self,
460
471
  tx: Transaction | None = None,
@@ -490,16 +501,12 @@ class BaseSurrealEdge(BaseSurrealModel):
490
501
 
491
502
  Raises:
492
503
  SurrealDbError: the edge was read with ``as_of()`` (a snapshot) — before its table is noted
493
- on the transaction (#315); ``server_values``/``extra_vars`` given (before any call); a
504
+ on the transaction (#315); ``server_values``/``extra_vars`` given — after the snapshot
505
+ check, before any call and before its table is noted on the transaction (#320); a
494
506
  duplicate id, a refused or rejected write.
495
507
  SurrealDbNotFoundError: an ``ENFORCED`` endpoint that does not exist.
496
508
  ValueError: an id that is a ``RecordID`` of another table, or a ``bool``.
497
509
  """
498
- if server_values or extra_vars:
499
- raise SurrealDbError(
500
- "save(server_values=) is not available on an edge: INSERT RELATION cannot evaluate SET "
501
- "expressions. Use DEFINE FIELD … DEFAULT/VALUE on the edge table."
502
- )
503
510
  return await super().save(tx=tx)
504
511
 
505
512
  async def upsert(self, tx: Transaction | None = None) -> Self: