surreal-orm-lite 0.30.1__tar.gz → 0.30.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 (46) hide show
  1. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/CHANGELOG.md +81 -0
  2. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/PKG-INFO +26 -2
  3. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/README.md +25 -1
  4. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/connection_manager.py +53 -2
  7. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/query_set.py +21 -4
  8. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/transaction.py +82 -12
  9. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/.gitignore +0 -0
  10. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/LICENSE +0 -0
  11. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/Makefile +0 -0
  12. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/_sdk.py +0 -0
  13. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/aggregations.py +0 -0
  14. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/auth.py +0 -0
  15. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/cache.py +0 -0
  16. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/changefeed.py +0 -0
  17. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/concurrency.py +0 -0
  18. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/connection_config.py +0 -0
  19. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/constants.py +0 -0
  20. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/decoding.py +0 -0
  21. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/define_parser.py +0 -0
  22. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/edge.py +0 -0
  23. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/embedded.py +0 -0
  24. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/encoding.py +0 -0
  25. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/enum.py +0 -0
  26. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/exceptions.py +0 -0
  27. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/functions.py +0 -0
  28. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/geo.py +0 -0
  29. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/introspection.py +0 -0
  30. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/live.py +0 -0
  31. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/model_auth.py +0 -0
  32. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/model_base.py +0 -0
  33. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/model_generator.py +0 -0
  34. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/py.typed +0 -0
  35. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/q.py +0 -0
  36. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/routing.py +0 -0
  37. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/schema_state.py +0 -0
  38. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/signals.py +0 -0
  39. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/subquery.py +0 -0
  40. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/surql_literal.py +0 -0
  41. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/testing/__init__.py +0 -0
  42. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/testing/database.py +0 -0
  43. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  44. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/time_travel.py +0 -0
  45. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/types.py +0 -0
  46. {surreal_orm_lite-0.30.1 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,87 @@ 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.30.5] - 2026-10-19
9
+
10
+ `SurrealDBConnectionManager.kill()` no longer reports a connection lost under the request as a
11
+ KILL the server refused. No new public API.
12
+
13
+ ### Fixed
14
+
15
+ - **A `kill()` caught by a dropped connection returns normally** (#266). A KILL sent as the
16
+ WebSocket went down, before the SDK had noticed the drop, failed inside the SDK (its receive loop
17
+ clears the pending requests, so the request's own cleanup raised a `KeyError`), and `kill()`
18
+ turned that into `SurrealDbError: Failed to kill live query …` although the server never
19
+ answered. `kill()` now asks the client: when its connection dropped under the request (the SDK's
20
+ receive task has ended, after a wait of at most one second when the error came from the
21
+ transport), it closes the dead socket and records the live query as ended, as it already did for
22
+ a client found dead before the call, and the stream's readers end. A refusal from a live server
23
+ still raises `SurrealDbError` and keeps the uuid alive, so a retry can re-attach to it.
24
+ - **A cancelled `kill()` raises `asyncio.CancelledError`** (#266), even when the SDK reports the
25
+ cancelled request as an ordinary error; it used to become `SurrealDbError`. The readers are
26
+ released either way.
27
+ - **`kill()` releases the stream's readers before it closes a dead socket** (#266), so an
28
+ automatic resubscribe woken by the same drop cannot reopen a subscription that is being stopped.
29
+ The window was open where closing the socket yields to the event loop, as on Python 3.11.
30
+
31
+ ### Notes
32
+
33
+ - Docs: the README live-queries section says that a kill caught by a dropped connection is not a
34
+ refusal.
35
+ - Same behaviour on SurrealDB 2.x and 3.x (live queries are WebSocket-only). Server pins
36
+ unchanged: tested against SurrealDB 3.3.4 and 2.7.0, plus 3.1.5 for backward compatibility.
37
+
38
+ ## [0.30.3] - 2026-10-19
39
+
40
+ A statement that fails inside `transaction()` fails the whole transaction on every strategy: a
41
+ transaction block now behaves the same on SurrealDB 2.x and 3.x, over WebSocket, over HTTP and on
42
+ the embedded engine. No new public API.
43
+
44
+ ### Changed
45
+
46
+ - **A failed statement fails the whole `transaction()` block, on every strategy** (#268). After a
47
+ statement fails inside the block, even when the block catches its error and carries on, the
48
+ transaction is cancelled when the block ends, nothing of the block is committed, and leaving the
49
+ block raises `SurrealDbError`, or `SurrealDbConflictError` when the failure was a retryable
50
+ conflict, so `retry_on_conflict` retries the block. Interactive transactions (SurrealDB 3.x over
51
+ WebSocket) now behave like the buffered ones (SurrealDB 2.x, HTTP, the embedded engine), which
52
+ already failed as a whole at commit: the failed statement raises its error at once, then leaving
53
+ the block raises "The transaction was cancelled: a statement in it failed; nothing was committed
54
+ (…)", chained to that error.
55
+ - An explicit `tx.commit()` after a failed statement raises the same error and cancels the
56
+ transaction.
57
+ - When the block's own exception propagates, that exception is the one raised, as before.
58
+ - Reads the ORM answers itself do not fail the transaction: a table that does not exist reads as
59
+ no rows, and `get()` raises `SurrealDbNotFoundError`.
60
+ - A statement interrupted inside the block (a timeout or a task cancellation) fails the
61
+ transaction too.
62
+
63
+ Upgrade note: a block that catches a statement's error and carries on now raises when it ends,
64
+ on every strategy, as it already did on the buffered ones. To carry on after such an error, run
65
+ that statement in a transaction of its own or outside the transaction.
66
+
67
+ ```python
68
+ async with SurrealDBConnectionManager.transaction() as tx:
69
+ await User(id="alice", name="Alice").save(tx=tx)
70
+ try:
71
+ await Order(id="o2", user="User:alice", total=-1).save(tx=tx) # refused by a field ASSERT
72
+ except SurrealDbError:
73
+ pass # caught, but the transaction can no longer commit
74
+ # leaving the block raised SurrealDbError: alice was not saved either
75
+ ```
76
+
77
+ ### Fixed
78
+
79
+ - **The error of a failed statement, "Transaction failed and rolled back: …", now describes what
80
+ happens on every strategy** (#268): on an interactive transaction as on a buffered one, nothing
81
+ of the block is committed.
82
+
83
+ ### Notes
84
+
85
+ - Docs: the README transactions section (11) states the rule with an example, and the "ORM
86
+ behaviour: SurrealDB 2.x vs 3.x" table gains a row for a statement that fails inside
87
+ `transaction()` with its error caught in the block.
88
+
8
89
  ## [0.30.0] - 2026-10-19
9
90
 
10
91
  Schema introspection: the ORM reads the schema of a database as immutable typed objects and
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.30.1
3
+ Version: 0.30.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
@@ -725,6 +725,27 @@ async with SurrealDBConnectionManager.transaction() as tx:
725
725
  tx raise; `save(tx=)` requires an explicit `id`. `bulk_update`/`bulk_delete` return `0`
726
726
  (the row count is not knowable before commit).
727
727
 
728
+ **A failed statement fails the whole transaction, on every strategy.** After a statement fails
729
+ inside the block — even when the block catches its error and carries on — the transaction is
730
+ cancelled when the block ends, nothing of the block is committed, and leaving the block raises
731
+ `SurrealDbError` (`SurrealDbConflictError` for a retryable conflict, so `retry_on_conflict` still
732
+ retries the block). A buffered transaction fails as a whole at commit; an interactive one raises
733
+ the failed statement's error at once, then, when the block ends, "The transaction was cancelled: a
734
+ statement in it failed; nothing was committed (…)", chained to that error. An explicit
735
+ `tx.commit()` after a failure raises the same error. When the block's own exception propagates,
736
+ that exception wins, as before. Reads the ORM answers itself are not failed statements: a table
737
+ that does not exist reads as no rows, and `get()` raises `SurrealDbNotFoundError`.
738
+
739
+ ```python
740
+ async with SurrealDBConnectionManager.transaction() as tx:
741
+ await User(id="alice", name="Alice").save(tx=tx)
742
+ try:
743
+ await Order(id="o2", user="User:alice", total=-1).save(tx=tx) # refused by a field ASSERT
744
+ except SurrealDbError:
745
+ pass # caught, but the transaction can no longer commit
746
+ # leaving the block raised SurrealDbError: alice was not saved either
747
+ ```
748
+
728
749
  ### 12. Upsert & get_or_create / update_or_create
729
750
 
730
751
  ```python
@@ -1742,6 +1763,8 @@ exactly what ends a stream.
1742
1763
  - **A failed `kill()` releases the readers but keeps the uuid alive.** When the server refuses
1743
1764
  the kill for any reason other than an unknown uuid, the error is raised, the readers are woken,
1744
1765
  and the subscription is still running — so you can subscribe to it again or retry `stop()`.
1766
+ A kill caught by a dropped connection is not a refusal: the subscription died with the socket,
1767
+ so `kill()` records it as ended and returns normally.
1745
1768
  - **The buffer is unbounded.** A stream you stop reading but never kill keeps accumulating
1746
1769
  notifications. Use the `async with` forms, or pair every uuid you start with a `kill()`.
1747
1770
 
@@ -4516,7 +4539,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
4516
4539
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
4517
4540
  on 2.7.0. The 3.x column was measured on 3.2.4 and holds on 3.3.0, except where a row says
4518
4541
  otherwise. The full suite and every divergence below were re-verified on both new versions.
4519
- Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs.
4542
+ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
4520
4543
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
4521
4544
 
4522
4545
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -4549,6 +4572,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
4549
4572
  | `call_function(tx=)` — return value | `None` (buffered: queued until commit) | the function's value (interactive returns it immediately) | v0.15.0 |
4550
4573
  | `call_function(tx=, return_type=)` | raises `ValueError` (no value to coerce yet) | coerces the returned value | v0.15.0 |
4551
4574
  | Missing function called inside a transaction | surfaces at COMMIT as `SurrealDbError` (buffered: the call is only queued) | raises `SurrealDbNotFoundError` at call time | v0.15.0 |
4575
+ | A statement that fails inside `transaction()`, its error caught in the block | leaving the block raises `SurrealDbError`, nothing of the block committed (the buffered batch fails as a whole) | same on both lines; over WebSocket the statement raises at once, then the block's end cancels the transaction and raises `SurrealDbError` | v0.30.3 |
4552
4576
  | Declared parameter name that collides with a reserved word, as echoed by `INFO FOR DB` | quoted: `` $`by` `` — parser accepts it | bare: `$by` | v0.15.0 |
4553
4577
  | Auth methods (`signin`, `signup`, `authenticate`, `invalidate`, `info`) | same on both lines (native SDK primitives, verified on 2.6.5) | same on both lines (verified on 3.2.4) | v0.16.0 |
4554
4578
  | Auth failure — raw SDK exception for a wrong password | `InternalError` | `NotFoundError` | v0.16.0 |
@@ -674,6 +674,27 @@ async with SurrealDBConnectionManager.transaction() as tx:
674
674
  tx raise; `save(tx=)` requires an explicit `id`. `bulk_update`/`bulk_delete` return `0`
675
675
  (the row count is not knowable before commit).
676
676
 
677
+ **A failed statement fails the whole transaction, on every strategy.** After a statement fails
678
+ inside the block — even when the block catches its error and carries on — the transaction is
679
+ cancelled when the block ends, nothing of the block is committed, and leaving the block raises
680
+ `SurrealDbError` (`SurrealDbConflictError` for a retryable conflict, so `retry_on_conflict` still
681
+ retries the block). A buffered transaction fails as a whole at commit; an interactive one raises
682
+ the failed statement's error at once, then, when the block ends, "The transaction was cancelled: a
683
+ statement in it failed; nothing was committed (…)", chained to that error. An explicit
684
+ `tx.commit()` after a failure raises the same error. When the block's own exception propagates,
685
+ that exception wins, as before. Reads the ORM answers itself are not failed statements: a table
686
+ that does not exist reads as no rows, and `get()` raises `SurrealDbNotFoundError`.
687
+
688
+ ```python
689
+ async with SurrealDBConnectionManager.transaction() as tx:
690
+ await User(id="alice", name="Alice").save(tx=tx)
691
+ try:
692
+ await Order(id="o2", user="User:alice", total=-1).save(tx=tx) # refused by a field ASSERT
693
+ except SurrealDbError:
694
+ pass # caught, but the transaction can no longer commit
695
+ # leaving the block raised SurrealDbError: alice was not saved either
696
+ ```
697
+
677
698
  ### 12. Upsert & get_or_create / update_or_create
678
699
 
679
700
  ```python
@@ -1691,6 +1712,8 @@ exactly what ends a stream.
1691
1712
  - **A failed `kill()` releases the readers but keeps the uuid alive.** When the server refuses
1692
1713
  the kill for any reason other than an unknown uuid, the error is raised, the readers are woken,
1693
1714
  and the subscription is still running — so you can subscribe to it again or retry `stop()`.
1715
+ A kill caught by a dropped connection is not a refusal: the subscription died with the socket,
1716
+ so `kill()` records it as ended and returns normally.
1694
1717
  - **The buffer is unbounded.** A stream you stop reading but never kill keeps accumulating
1695
1718
  notifications. Use the `async with` forms, or pair every uuid you start with a `kill()`.
1696
1719
 
@@ -4465,7 +4488,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
4465
4488
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
4466
4489
  on 2.7.0. The 3.x column was measured on 3.2.4 and holds on 3.3.0, except where a row says
4467
4490
  otherwise. The full suite and every divergence below were re-verified on both new versions.
4468
- Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs.
4491
+ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
4469
4492
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
4470
4493
 
4471
4494
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -4498,6 +4521,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
4498
4521
  | `call_function(tx=)` — return value | `None` (buffered: queued until commit) | the function's value (interactive returns it immediately) | v0.15.0 |
4499
4522
  | `call_function(tx=, return_type=)` | raises `ValueError` (no value to coerce yet) | coerces the returned value | v0.15.0 |
4500
4523
  | Missing function called inside a transaction | surfaces at COMMIT as `SurrealDbError` (buffered: the call is only queued) | raises `SurrealDbNotFoundError` at call time | v0.15.0 |
4524
+ | A statement that fails inside `transaction()`, its error caught in the block | leaving the block raises `SurrealDbError`, nothing of the block committed (the buffered batch fails as a whole) | same on both lines; over WebSocket the statement raises at once, then the block's end cancels the transaction and raises `SurrealDbError` | v0.30.3 |
4501
4525
  | Declared parameter name that collides with a reserved word, as echoed by `INFO FOR DB` | quoted: `` $`by` `` — parser accepts it | bare: `$by` | v0.15.0 |
4502
4526
  | Auth methods (`signin`, `signup`, `authenticate`, `invalidate`, `info`) | same on both lines (native SDK primitives, verified on 2.6.5) | same on both lines (verified on 3.2.4) | v0.16.0 |
4503
4527
  | Auth failure — raw SDK exception for a wrong password | `InternalError` | `NotFoundError` | v0.16.0 |
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.30.1"
3
+ version = "0.30.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.30.1"
1
+ __version__ = "0.30.5"
2
2
 
3
3
  from ._sdk import BoundExcluded, BoundIncluded
4
4
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
@@ -33,12 +33,14 @@ from .exceptions import (
33
33
  from .functions import build_call_statement, normalize_function_name, parse_function_parameters
34
34
  from .live import (
35
35
  LiveIterator,
36
+ cancellation_lost,
36
37
  close_all_subscribers,
37
38
  is_connection_failure,
38
39
  is_dead,
39
40
  mark_killed,
40
41
  open_stream,
41
42
  owner_of,
43
+ recv_task_of,
42
44
  release_subscribers,
43
45
  require_websocket,
44
46
  )
@@ -50,6 +52,10 @@ logger = logging.getLogger(__name__)
50
52
  # Strong references to fire-and-forget closes, which the event loop alone would let be collected.
51
53
  _BACKGROUND: set[asyncio.Task[Any]] = set()
52
54
 
55
+ # How long a KILL that failed on a transport error waits for the SDK's receive loop to end, before
56
+ # deciding the connection is still up (and the failure a real one).
57
+ _DROP_SETTLE_TIMEOUT = 1.0
58
+
53
59
 
54
60
  @lru_cache(maxsize=256)
55
61
  def _cached_type_adapter(return_type: Any) -> TypeAdapter[Any]:
@@ -1627,6 +1633,16 @@ class SurrealDBConnectionManager:
1627
1633
  ``commit()`` BEFORE deferred ``post_*`` signals fire. An exception from a deferred
1628
1634
  handler surfaces AFTER a durable commit (not a rollback).
1629
1635
 
1636
+ A failed statement fails the transaction on every strategy (issue #268): after a statement
1637
+ fails inside the block — even when the block catches its error and carries on — the
1638
+ transaction is cancelled when the block ends, nothing is committed, and leaving the block
1639
+ raises ``SurrealDbError`` (``SurrealDbConflictError`` for a retryable conflict, so
1640
+ ``retry_on_conflict`` still retries). A buffered batch fails as a whole at commit; an
1641
+ interactive transaction raises "The transaction was cancelled: a statement in it failed;
1642
+ nothing was committed (…)", chained to the failed statement's error. When the body's own
1643
+ exception propagates, that exception wins. A read the ORM answers itself (a missing table
1644
+ read as no rows, ``get()`` raising ``SurrealDbNotFoundError``) is not a failed statement.
1645
+
1630
1646
  SurrealDB has no savepoints/nested transactions; nested ``transaction()`` calls
1631
1647
  open INDEPENDENT transactions, not savepoints.
1632
1648
 
@@ -2463,10 +2479,16 @@ class SurrealDBConnectionManager:
2463
2479
  client still cached on this loop — a stream started on a server, stopped after switching
2464
2480
  to the engine — receives the KILL; otherwise the call is the no-op above.
2465
2481
 
2482
+ A KILL caught by a drop — sent as the connection goes down, before the SDK has noticed —
2483
+ is not a refusal either: the live query died with the socket, so the call ends as it does
2484
+ on a dead client, and raises nothing.
2485
+
2466
2486
  :param query_uuid: the uuid of a running live query, e.g. ``stream.live_id``.
2467
2487
  :raises SurrealDbError: if the server refuses the kill for a reason other than an
2468
2488
  unknown uuid. The readers are released anyway, but the uuid is **not** recorded as
2469
2489
  dead — the subscription is still running, so a retry can re-attach to it.
2490
+ :raises asyncio.CancelledError: if the calling task is cancelled, even when the SDK
2491
+ reports the cancelled request as an ordinary error. The readers are released.
2470
2492
  """
2471
2493
  client = cls._cached_client()
2472
2494
  try:
@@ -2475,6 +2497,8 @@ class SurrealDBConnectionManager:
2475
2497
  # receive loop that died on a bad frame leaves the socket open, though, and the server
2476
2498
  # still running them: closing the transport is what ends them then.
2477
2499
  if client is None or is_dead(client):
2500
+ # Before any await: a resubscribe woken by the same drop must find the reader gone.
2501
+ release_subscribers(query_uuid)
2478
2502
  if client is not None:
2479
2503
  await cls._close_dead_socket(client)
2480
2504
  mark_killed(query_uuid)
@@ -2484,14 +2508,41 @@ class SurrealDBConnectionManager:
2484
2508
  try:
2485
2509
  await client.kill(query_uuid)
2486
2510
  except Exception as exc:
2487
- if not cls._is_unknown_live_query(exc):
2511
+ # Before any await: a resubscribe woken by the same drop must find the reader gone,
2512
+ # or it opens a connection for a subscription being torn down. Closing the socket
2513
+ # below yields the loop on Python 3.11, where `wait_for` always wraps a Task.
2514
+ release_subscribers(query_uuid)
2515
+ if cancellation_lost(exc):
2516
+ raise asyncio.CancelledError from exc # the SDK raised over the caller's cancellation
2517
+ if await cls._dropped_under_request(client, exc):
2518
+ # The server never answered: the connection went down with the request in flight.
2519
+ await cls._close_dead_socket(client)
2520
+ elif not cls._is_unknown_live_query(exc):
2488
2521
  raise SurrealDbError(f"Failed to kill live query {query_uuid}: {exc}") from exc
2489
2522
  mark_killed(query_uuid)
2490
2523
  finally:
2491
2524
  # In a `finally` so that every exit — success, failure, cancellation — wakes the
2492
- # readers; nothing else ever would.
2525
+ # readers; nothing else ever would. Idempotent after an early release above, and it
2526
+ # also wakes a reader that subscribed to the uuid while this call was awaiting.
2493
2527
  release_subscribers(query_uuid)
2494
2528
 
2529
+ @staticmethod
2530
+ async def _dropped_under_request(client: Any, exc: Exception) -> bool:
2531
+ """Whether a request on *client* failed with *exc* because its WebSocket dropped.
2532
+
2533
+ Decided on the client, never on the error alone. The SDK reports a request caught by a
2534
+ drop as a bare ``KeyError``: its receive loop ends, cancels the pending request and clears
2535
+ the pending-request map, so the request's own cleanup finds its id gone (surrealdb 2.0.0)
2536
+ — by then the receive task is done. A transport error can surface a moment before that
2537
+ loop has ended, so it gets a bounded wait to catch up; anything else is decided at once.
2538
+ """
2539
+ task = recv_task_of(client)
2540
+ if task is None:
2541
+ return False
2542
+ if not task.done() and is_connection_failure(exc, None):
2543
+ await asyncio.wait({task}, timeout=_DROP_SETTLE_TIMEOUT)
2544
+ return task.done()
2545
+
2495
2546
  @staticmethod
2496
2547
  def _is_unknown_live_query(exc: Exception) -> bool:
2497
2548
  """Whether *exc* is the server refusing to kill a live query it does not know.
@@ -1114,7 +1114,15 @@ class QuerySet:
1114
1114
  try:
1115
1115
  return await self._tx.run_read(query, vars_) # type: ignore[no-any-return]
1116
1116
  except ServerError as exc:
1117
- if await self._reads_as_empty(exc, subquery_tables):
1117
+ # A read the ORM answers itself (no rows, or sent again without the missing subquery table) does not
1118
+ # fail the transaction (issue #268); an error relayed does.
1119
+ try:
1120
+ empty = await self._reads_as_empty(exc, subquery_tables)
1121
+ except _subquery._MissingSubqueryTable:
1122
+ self._tx._absorb_failure(exc)
1123
+ raise
1124
+ if empty:
1125
+ self._tx._absorb_failure(exc)
1118
1126
  return []
1119
1127
  raise
1120
1128
  client = await self._manager().get_client()
@@ -1174,8 +1182,13 @@ class QuerySet:
1174
1182
  client = await self._manager().get_client()
1175
1183
  await client.query(_subquery.TABLE_PROBE, _encoding.encode(variables))
1176
1184
  except NotFoundError as exc:
1185
+ # The check's answer, never a failed statement of the transaction (issue #268).
1186
+ if self._tx is not None:
1187
+ self._tx._absorb_failure(exc)
1177
1188
  return _subquery.missing_table(exc) == table
1178
- except ServerError:
1189
+ except ServerError as exc:
1190
+ if self._tx is not None:
1191
+ self._tx._absorb_failure(exc)
1179
1192
  return False
1180
1193
  return False
1181
1194
 
@@ -1431,7 +1444,9 @@ class QuerySet:
1431
1444
  if self._tx is not None:
1432
1445
  try:
1433
1446
  rows = await self._tx.run_read("SELECT * FROM $rid;", {"rid": record_id})
1434
- except NotFoundError:
1447
+ except NotFoundError as exc:
1448
+ # "No record" is an answer, not a failed statement of the transaction (issue #268).
1449
+ self._tx._absorb_failure(exc)
1435
1450
  raise SurrealDbNotFoundError("No result found.") from None
1436
1451
  data = rows[0] if isinstance(rows, list) and rows else rows
1437
1452
  if not data:
@@ -1481,7 +1496,9 @@ class QuerySet:
1481
1496
  if self._tx is not None:
1482
1497
  try:
1483
1498
  rows = await self._tx.run_read(f"SELECT * FROM {self._model_table};", {})
1484
- except NotFoundError:
1499
+ except NotFoundError as exc:
1500
+ # A missing table reads as no rows: not a failed statement of the transaction (issue #268).
1501
+ self._tx._absorb_failure(exc)
1485
1502
  return self.model.from_db([])
1486
1503
  return self.model.from_db(rows if isinstance(rows, list) else [])
1487
1504
 
@@ -14,6 +14,12 @@ Two strategies share one public interface:
14
14
 
15
15
  ``connection_manager.transaction()`` probes ``client.begin()`` to pick the strategy.
16
16
 
17
+ A failed statement fails the transaction on both strategies (issue #268). A buffered batch fails as a whole at
18
+ commit. The interactive strategy records every statement that fails (a write or a read whose error the ORM does not
19
+ answer itself, e.g. a missing table read as no rows); ``commit()`` then cancels instead of committing and raises,
20
+ so leaving a ``transaction()`` block after a failed statement raises and nothing of the block is committed, even
21
+ when the block caught the statement's error.
22
+
17
23
  Query cache (v0.28.0): an ORM write that joins a transaction notes the tables it writes on it
18
24
  (``_note_cache_write``); the commit puts them in flight and invalidates their cached reads when
19
25
  it returns or raises (a failed commit's state is unknown). ``cancel()`` forgets them: nothing
@@ -32,6 +38,10 @@ from .exceptions import SurrealDbConflictError, SurrealDbError
32
38
 
33
39
  _NOT_EXECUTED_FILLER = "The query was not executed due to a failed transaction"
34
40
 
41
+ #: The error ``InteractiveTransaction.commit()`` raises after a failed statement (issue #268), followed by that
42
+ #: statement's error.
43
+ _CANCELLED_AFTER_FAILURE = "The transaction was cancelled: a statement in it failed; nothing was committed"
44
+
35
45
 
36
46
  def _is_pure_filler(result: Any) -> bool:
37
47
  """True if a statement's message is ONLY the generic 'not executed' filler.
@@ -75,6 +85,25 @@ class Transaction(ABC):
75
85
  # Query cache: the tables written in this transaction, invalidated at commit.
76
86
  self._cache_tables: set[str] = set()
77
87
  self._cache_all = False
88
+ # Issue #268: the errors of the statements that failed in this transaction (interactive strategy).
89
+ self._failures: list[BaseException] = []
90
+
91
+ def _note_failure(self, error: BaseException) -> None:
92
+ """Record that a statement run in this transaction failed with *error*: the transaction can no longer commit."""
93
+ self._failures.append(error)
94
+
95
+ def _absorb_failure(self, error: BaseException) -> None:
96
+ """Forget the failure *error*, which the ORM answered itself (issue #268).
97
+
98
+ A read the ORM reads as an answer — a missing table read as no rows, ``get()`` raising "not found", the
99
+ missing-table check of a subquery — does not fail the transaction. Matched by identity; an error that was
100
+ not recorded is ignored.
101
+ """
102
+ self._failures = [failure for failure in self._failures if failure is not error]
103
+
104
+ def _first_failure(self) -> BaseException | None:
105
+ """The error of the first statement that failed in this transaction and was not absorbed, else ``None``."""
106
+ return self._failures[0] if self._failures else None
78
107
 
79
108
  def _note_cache_write(self, tables: Iterable[str] | None) -> None:
80
109
  """Note the tables an ORM write in this transaction changes (``None``: every table).
@@ -139,8 +168,10 @@ class Transaction(ABC):
139
168
 
140
169
  ``query()`` silently returns ``None`` on a failed transaction, so the
141
170
  commit/write paths use ``query_raw()`` and call this. Any statement with
142
- ``status == "ERR"`` means the transaction rolled back. Prefers the root cause
143
- (the first ERR whose ``details.kind`` is not ``"NotExecuted"``).
171
+ ``status == "ERR"`` means the transaction is rolled back: a buffered batch at once, an
172
+ interactive transaction when it ends (its ``commit()`` cancels after a failed statement,
173
+ issue #268). Prefers the root cause (the first ERR whose ``details.kind`` is not
174
+ ``"NotExecuted"``).
144
175
  """
145
176
  if not isinstance(raw, dict) or not isinstance(raw.get("result"), list):
146
177
  raise SurrealDbError(f"Transaction failed: unrecognized query_raw() response shape: {raw!r}")
@@ -255,37 +286,72 @@ class InteractiveTransaction(Transaction):
255
286
  (done by the connection manager). Every operation passes ``txn_id=`` so it joins the
256
287
  server-side transaction; reads see uncommitted writes and are isolated from other
257
288
  operations on the same connection.
289
+
290
+ A statement that fails — its request raises, or the server reports an error — is recorded
291
+ (issue #268); its error still raises at once. ``commit()`` then cancels the transaction
292
+ instead of committing it and raises :data:`_CANCELLED_AFTER_FAILURE`, so the transaction fails
293
+ as a whole, as a buffered one does, even when the caller caught the statement's error.
258
294
  """
259
295
 
260
296
  def __init__(self, client: Any, txn_id: Any) -> None:
261
297
  super().__init__()
262
298
  self._client = client
263
299
  self._txn_id = txn_id
300
+ self._cancelled = False
264
301
 
265
302
  @property
266
303
  def is_interactive(self) -> bool:
267
304
  return True
268
305
 
269
306
  async def add(self, statement: str, variables: dict[str, Any] | None = None) -> Any:
270
- """Run a write inside the transaction; inspect status; return its rows."""
307
+ """Run a write inside the transaction; inspect status; return its rows.
308
+
309
+ A failure is recorded before it raises: the transaction will not commit (issue #268).
310
+ """
271
311
  payload = _encoding.encode(variables or {})
272
312
  try:
273
- raw = await self._client.query_raw(statement, payload, txn_id=self._txn_id)
274
- except Exception as exc:
275
- raise _as_conflict(exc) from exc
276
- self.raise_for_status(raw)
313
+ try:
314
+ raw = await self._client.query_raw(statement, payload, txn_id=self._txn_id)
315
+ except Exception as exc:
316
+ raise _as_conflict(exc) from exc
317
+ self.raise_for_status(raw)
318
+ except BaseException as failure:
319
+ self._note_failure(failure)
320
+ raise
277
321
  statements = raw["result"]
278
322
  return statements[-1]["result"] if statements else []
279
323
 
280
324
  async def run_read(self, statement: str, variables: dict[str, Any] | None = None) -> Any:
281
- """Run a read inside the transaction and return rows directly."""
325
+ """Run a read inside the transaction and return rows directly.
326
+
327
+ A failure is recorded before it raises (issue #268); the ORM forgets it when it reads the
328
+ error as an answer (:meth:`_absorb_failure`).
329
+ """
282
330
  payload = _encoding.encode(variables or {})
283
331
  try:
284
- return await self._client.query(statement, payload, txn_id=self._txn_id)
285
- except Exception as exc:
286
- raise _as_conflict(exc) from exc
332
+ try:
333
+ return await self._client.query(statement, payload, txn_id=self._txn_id)
334
+ except Exception as exc:
335
+ raise _as_conflict(exc) from exc
336
+ except BaseException as failure:
337
+ self._note_failure(failure)
338
+ raise
287
339
 
288
340
  async def commit(self) -> None:
341
+ """Commit the transaction; after a failed statement, cancel it and raise instead (issue #268).
342
+
343
+ Raises:
344
+ SurrealDbError: a statement failed in this transaction (:data:`_CANCELLED_AFTER_FAILURE`, followed by that
345
+ statement's error, which is chained as the cause): the transaction was cancelled, nothing was
346
+ committed. ``SurrealDbConflictError`` when that statement's error was a retryable conflict.
347
+ """
348
+ failure = self._first_failure()
349
+ if failure is not None:
350
+ from .concurrency import is_conflict_error
351
+
352
+ await self.cancel()
353
+ error_type = SurrealDbConflictError if is_conflict_error(failure) else SurrealDbError
354
+ raise error_type(f"{_CANCELLED_AFTER_FAILURE} ({str(failure) or type(failure).__name__})") from failure
289
355
  # The tables noted are in flight during the commit and invalidated when it returns
290
356
  # or raises (a failed commit's state is unknown).
291
357
  try:
@@ -298,7 +364,11 @@ class InteractiveTransaction(Transaction):
298
364
  self._forget_cache_writes()
299
365
 
300
366
  async def cancel(self) -> None:
301
- # Nothing became visible: the tables noted are forgotten, not invalidated.
367
+ # Nothing became visible: the tables noted are forgotten, not invalidated. Sent once: a
368
+ # commit() that cancelled after a failed statement is cancelled again by transaction().
302
369
  self._forget_cache_writes()
370
+ if self._cancelled:
371
+ return
372
+ self._cancelled = True
303
373
  with contextlib.suppress(Exception):
304
374
  await self._client.cancel(self._txn_id)