surreal-orm-lite 0.22.1__tar.gz → 0.22.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/CHANGELOG.md +37 -0
  2. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/PKG-INFO +11 -7
  3. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/README.md +10 -6
  4. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/changefeed.py +48 -5
  7. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/live.py +30 -0
  8. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/.gitignore +0 -0
  9. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/LICENSE +0 -0
  10. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/Makefile +0 -0
  11. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/_sdk.py +0 -0
  12. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/aggregations.py +0 -0
  13. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/auth.py +0 -0
  14. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/concurrency.py +0 -0
  15. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/connection_manager.py +0 -0
  16. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/constants.py +0 -0
  17. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/edge.py +0 -0
  18. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/enum.py +0 -0
  19. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/exceptions.py +0 -0
  20. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/functions.py +0 -0
  21. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/model_auth.py +0 -0
  22. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/model_base.py +0 -0
  23. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/py.typed +0 -0
  24. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/q.py +0 -0
  25. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/query_set.py +0 -0
  26. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/signals.py +0 -0
  27. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/surql_literal.py +0 -0
  28. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/transaction.py +0 -0
  29. {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,43 @@ 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.22.2] - 2026-10-13
9
+
10
+ Change-feed fixes: history replayed by `changes(since=None)` on SurrealDB 3.x, and a timed-out
11
+ read that could hang on both lines. No new public API.
12
+
13
+ ### Fixed
14
+
15
+ - **`changes(since=None)` no longer replays history on SurrealDB 3.x** (#212). On 3.x the stream
16
+ started at the server clock's millisecond (`unix_ms << 16`), but a 3.x versionstamp is
17
+ `unix_ms << 16 | counter` and `SINCE` is inclusive, so every entry committed earlier in that
18
+ same millisecond was delivered as if it were new, and `stream.cursor` did not point at the end
19
+ of the feed. `start()` now reads the entries stamped in that millisecond, a page of
20
+ `batch_size` at a time, and moves the cursor past the last one: usually one short read, at most
21
+ `ceil(n / batch_size) + 1` reads for the `n` entries of that millisecond, however busy the
22
+ table is. It goes through the same retry and `stop()` path as every other request.
23
+ - A write committed in that millisecond while `start()` runs is history and is skipped; a write
24
+ in a later millisecond, or one made after `start()` returns (even in the same millisecond),
25
+ is delivered.
26
+ - This was the cause of two intermittent change-feed test failures on SurrealDB 3.x.
27
+ - **A change-feed read under `asyncio.timeout()` or `wait_for()` could hang forever**, on both
28
+ server lines. When the read was cancelled in the very loop iteration the server's answer
29
+ arrived, the official SDK (surrealdb 2.0.0) raised a `KeyError` over the `CancelledError` and
30
+ its connection died, which is what a dropped connection looks like. The stream retried it as one
31
+ and lost the cancellation: the timeout never fired and the read polled on, for as long as the
32
+ process ran. A cancellation of the reading task is now re-raised instead of retried, so the read
33
+ times out as asked and loses nothing (the next read starts from the cursor). A live query's
34
+ automatic resubscribe gets the same guard, so cancelling it (`asyncio.run()` shutting down, for
35
+ instance) no longer has it reconnect on.
36
+
37
+ ### Notes
38
+
39
+ - **`changes(since=None)` on SurrealDB 2.x is unchanged**: there "now" is the end of the feed,
40
+ found by searching the counter, which never had this problem. The README's "SurrealDB 2.6.x vs
41
+ 3.x" table now says how the 3.x side finds "now". The timed-out read fix is the same on both
42
+ lines: the race is in the SDK, not in the server.
43
+ - Tested against SurrealDB 3.3.4 and 2.7.0 (the CI pins), plus 3.1.5 for backward compatibility.
44
+
8
45
  ## [0.22.0] - 2026-10-12
9
46
 
10
47
  Native typed relations: graph edges as Pydantic models, created through the official SDK's
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.22.1
3
+ Version: 0.22.2
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
@@ -52,7 +52,7 @@ Description-Content-Type: text/markdown
52
52
  # Surreal ORM Lite
53
53
 
54
54
  ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
55
- ![SurrealDB](https://img.shields.io/badge/SurrealDB-2.7.0%20%7C%203.3.3-purple)
55
+ ![SurrealDB](https://img.shields.io/badge/SurrealDB-2.7.0%20%7C%203.3.4-purple)
56
56
  ![SDK](https://img.shields.io/badge/SDK-Official%202.0-green)
57
57
  ![License](https://img.shields.io/badge/license-MIT-blue)
58
58
  [![codecov](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite/graph/badge.svg)](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite)
@@ -79,7 +79,7 @@ This ORM is designed to:
79
79
  | Official SDK | surrealdb[pydantic]>=2.0.0,<3.0.0 |
80
80
  | Pydantic | >=2.13.4 |
81
81
 
82
- > **Note**: As of v0.7.0, Surreal ORM Lite targets the SurrealDB Python SDK 2.x (`surrealdb[pydantic]>=2.0.0,<3.0.0`), which supports the SurrealDB 3.x protocol. It is tested against SurrealDB **v2.7.0** and **v3.3.3**; up to v0.19.0 the pins were v2.6.5 and v3.2.4. The 2.x line behaves identically on 2.7.0, and 3.3.0 differs from 3.2.4 in one server behaviour, listed in the behaviour table. SurrealDB 3.1.x is no longer a supported line as of v0.14.0 — the suite is still run against 3.1.5 as a backward-compatibility check, but a regression there does not block a release.
82
+ > **Note**: As of v0.7.0, Surreal ORM Lite targets the SurrealDB Python SDK 2.x (`surrealdb[pydantic]>=2.0.0,<3.0.0`), which supports the SurrealDB 3.x protocol. It is tested against SurrealDB **v2.7.0** and **v3.3.4**; up to v0.19.0 the pins were v2.6.5 and v3.2.4. The 2.x line behaves identically on 2.7.0, and 3.3.0 differs from 3.2.4 in one server behaviour, listed in the behaviour table. SurrealDB 3.1.x is no longer a supported line as of v0.14.0 — the suite is still run against 3.1.5 as a backward-compatibility check, but a regression there does not block a release.
83
83
 
84
84
  ---
85
85
 
@@ -747,7 +747,7 @@ await user.merge(plan="pro", server_values={"updated_at": SurrealFunc.call(Surre
747
747
 
748
748
  `SurrealFunc.call(fn, *args)` builds `fn(arg, …)` from a function name — a plain string or a
749
749
  member of the shipped enums, which give you autocompletion over a **curated catalog whose every
750
- member is tested against SurrealDB 2.7.0 and 3.3.3**:
750
+ member is tested against SurrealDB 2.7.0 and 3.3.4**:
751
751
 
752
752
  | Enum | Covers |
753
753
  | ----------------------- | ---------------------------------------------------------------- |
@@ -1601,6 +1601,10 @@ async for event in stream:
1601
1601
  the entries read per poll. `stop()` ends the iteration at once when it is waiting between
1602
1602
  polls or in a retry backoff, or as soon as a request already sent returns; `start()` fixes the
1603
1603
  starting position before the first read.
1604
+ - **A read under `asyncio.timeout()` or `asyncio.wait_for()`** times out as asked and loses
1605
+ nothing: the stream keeps going, and the next read starts from the cursor. Before v0.22.2 a
1606
+ read cancelled just as the server answered could be retried as a dropped connection instead,
1607
+ and never time out.
1604
1608
  - Works over **HTTP** as well as WebSocket. A dropped connection is retried with the same
1605
1609
  backoff as live streams, and nothing is lost, because the next read starts from the cursor.
1606
1610
  - **Refused:** any queryset clause — `SHOW CHANGES` has no `WHERE`, so `filter()` would silently
@@ -2036,7 +2040,7 @@ As of v0.7.0, Surreal ORM Lite uses `surrealdb[pydantic]>=2.0.0,<3.0.0` (Surreal
2036
2040
 
2037
2041
  | SurrealDB Version | SDK Version | Status |
2038
2042
  | ----------------------------- | ----------- | ------------------------------------ |
2039
- | 3.3.3 | 2.0 | ✅ Tested |
2043
+ | 3.3.4 | 2.0 | ✅ Tested |
2040
2044
  | 2.7.0 | 2.0 | ✅ Tested |
2041
2045
  | 3.2.4 | 2.0 | ✅ Compatible (tested up to v0.19.0) |
2042
2046
  | 2.6.5 | 2.0 | ✅ Compatible (tested up to v0.19.0) |
@@ -2069,7 +2073,7 @@ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v
2069
2073
  | `patch()` / `atomic_append` / `atomic_set_add` / `atomic_remove` / `atomic_increment` | same on both lines (portable `array::*` fns chosen over divergent `+=`/`-=`) | same on both lines | v0.11.0 |
2070
2074
  | `retry_on_conflict` / `SurrealDbConflictError` (retryable conflict) | same type + decorator; conflicts rarer (engine serialises more) | same type + decorator; conflicts are the normal optimistic-MVCC failure | v0.12.0 |
2071
2075
  | `SurrealFunc` / `server_values=` / `extra_vars=` on `save`/`merge` | same on both lines (compiled to portable `CREATE`/`UPDATE … SET`) | same on both lines | v0.13.0 |
2072
- | Shipped function-name enums (`SurrealTimeFunction`, `SurrealCryptoFunction`, …) | every catalogued member verified on 2.7.0 | every catalogued member verified on 3.3.3 | v0.13.0 |
2076
+ | Shipped function-name enums (`SurrealTimeFunction`, `SurrealCryptoFunction`, …) | every catalogued member verified on 2.7.0 | every catalogued member verified on 3.3.4 | v0.13.0 |
2073
2077
  | `server_values` inside a transaction — when the instance sees the computed value | only after commit (buffered; `refresh()` to read it) | immediately (interactive returns the row) | v0.13.0 |
2074
2078
  | `merge(server_values=)` on a missing record / never-created table | server returns no rows → ORM raises `SurrealDbError` | server raises `NotFound` for a missing table → ORM raises the same error | v0.13.0 |
2075
2079
  | Computed fields (`Computed[...]` → `DEFINE FIELD … VALUE`) | same on both lines (DDL, recompute triggers, precedence over client data) | same on both lines | v0.14.0 |
@@ -2122,7 +2126,7 @@ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v
2122
2126
  | Change-feed entry shape | `{versionstamp, changes}`; a create is reported as `update` | same on both lines | v0.21.0 |
2123
2127
  | Change-feed `SINCE <n>` — what `n` is | the counter, `versionstamp >> 16` (the raw stamp silently returns nothing); `ChangeModelStream.cursor` normalises it | the versionstamp, inclusive; `cursor` normalises it | v0.21.0 |
2124
2128
  | `changes(since=<datetime>)` | the server also returns some earlier changes → at-least-once | the server returns nothing → the ORM converts to a versionstamp → exact | v0.21.0 |
2125
- | `changes(since=None)` — finding "now" | the ORM searches the counter (no history replayed) | the ORM uses the server clock (no history replayed) | v0.21.0 |
2129
+ | `changes(since=None)` — finding "now" | the ORM searches the counter (no history replayed) | the ORM reads the server clock's millisecond, then skips the entries already stamped in it (no history replayed); before v0.22.2 the entries of that millisecond were replayed | v0.21.0 |
2126
2130
  | `INCLUDE ORIGINAL` delete in a change feed | the id only → an instance holding only the `id` | 3.3.x: carries `original` → the last state of the record; 3.1.5: as 2.x | v0.21.0 |
2127
2131
  | `SHOW CHANGES` on a table without a change feed | returns `[]`; `changes()` raises `SurrealDbError` instead | same on both lines | v0.21.0 |
2128
2132
  | Typed edges (`relate(Edge, …)`, edge `save()` and `bulk_create()`) through `insert_relation()` | same on both lines: a real relation that graph traversal sees, `id` hydrated from the returned row | same on both lines | v0.22.0 |
@@ -1,7 +1,7 @@
1
1
  # Surreal ORM Lite
2
2
 
3
3
  ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
4
- ![SurrealDB](https://img.shields.io/badge/SurrealDB-2.7.0%20%7C%203.3.3-purple)
4
+ ![SurrealDB](https://img.shields.io/badge/SurrealDB-2.7.0%20%7C%203.3.4-purple)
5
5
  ![SDK](https://img.shields.io/badge/SDK-Official%202.0-green)
6
6
  ![License](https://img.shields.io/badge/license-MIT-blue)
7
7
  [![codecov](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite/graph/badge.svg)](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite)
@@ -28,7 +28,7 @@ This ORM is designed to:
28
28
  | Official SDK | surrealdb[pydantic]>=2.0.0,<3.0.0 |
29
29
  | Pydantic | >=2.13.4 |
30
30
 
31
- > **Note**: As of v0.7.0, Surreal ORM Lite targets the SurrealDB Python SDK 2.x (`surrealdb[pydantic]>=2.0.0,<3.0.0`), which supports the SurrealDB 3.x protocol. It is tested against SurrealDB **v2.7.0** and **v3.3.3**; up to v0.19.0 the pins were v2.6.5 and v3.2.4. The 2.x line behaves identically on 2.7.0, and 3.3.0 differs from 3.2.4 in one server behaviour, listed in the behaviour table. SurrealDB 3.1.x is no longer a supported line as of v0.14.0 — the suite is still run against 3.1.5 as a backward-compatibility check, but a regression there does not block a release.
31
+ > **Note**: As of v0.7.0, Surreal ORM Lite targets the SurrealDB Python SDK 2.x (`surrealdb[pydantic]>=2.0.0,<3.0.0`), which supports the SurrealDB 3.x protocol. It is tested against SurrealDB **v2.7.0** and **v3.3.4**; up to v0.19.0 the pins were v2.6.5 and v3.2.4. The 2.x line behaves identically on 2.7.0, and 3.3.0 differs from 3.2.4 in one server behaviour, listed in the behaviour table. SurrealDB 3.1.x is no longer a supported line as of v0.14.0 — the suite is still run against 3.1.5 as a backward-compatibility check, but a regression there does not block a release.
32
32
 
33
33
  ---
34
34
 
@@ -696,7 +696,7 @@ await user.merge(plan="pro", server_values={"updated_at": SurrealFunc.call(Surre
696
696
 
697
697
  `SurrealFunc.call(fn, *args)` builds `fn(arg, …)` from a function name — a plain string or a
698
698
  member of the shipped enums, which give you autocompletion over a **curated catalog whose every
699
- member is tested against SurrealDB 2.7.0 and 3.3.3**:
699
+ member is tested against SurrealDB 2.7.0 and 3.3.4**:
700
700
 
701
701
  | Enum | Covers |
702
702
  | ----------------------- | ---------------------------------------------------------------- |
@@ -1550,6 +1550,10 @@ async for event in stream:
1550
1550
  the entries read per poll. `stop()` ends the iteration at once when it is waiting between
1551
1551
  polls or in a retry backoff, or as soon as a request already sent returns; `start()` fixes the
1552
1552
  starting position before the first read.
1553
+ - **A read under `asyncio.timeout()` or `asyncio.wait_for()`** times out as asked and loses
1554
+ nothing: the stream keeps going, and the next read starts from the cursor. Before v0.22.2 a
1555
+ read cancelled just as the server answered could be retried as a dropped connection instead,
1556
+ and never time out.
1553
1557
  - Works over **HTTP** as well as WebSocket. A dropped connection is retried with the same
1554
1558
  backoff as live streams, and nothing is lost, because the next read starts from the cursor.
1555
1559
  - **Refused:** any queryset clause — `SHOW CHANGES` has no `WHERE`, so `filter()` would silently
@@ -1985,7 +1989,7 @@ As of v0.7.0, Surreal ORM Lite uses `surrealdb[pydantic]>=2.0.0,<3.0.0` (Surreal
1985
1989
 
1986
1990
  | SurrealDB Version | SDK Version | Status |
1987
1991
  | ----------------------------- | ----------- | ------------------------------------ |
1988
- | 3.3.3 | 2.0 | ✅ Tested |
1992
+ | 3.3.4 | 2.0 | ✅ Tested |
1989
1993
  | 2.7.0 | 2.0 | ✅ Tested |
1990
1994
  | 3.2.4 | 2.0 | ✅ Compatible (tested up to v0.19.0) |
1991
1995
  | 2.6.5 | 2.0 | ✅ Compatible (tested up to v0.19.0) |
@@ -2018,7 +2022,7 @@ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v
2018
2022
  | `patch()` / `atomic_append` / `atomic_set_add` / `atomic_remove` / `atomic_increment` | same on both lines (portable `array::*` fns chosen over divergent `+=`/`-=`) | same on both lines | v0.11.0 |
2019
2023
  | `retry_on_conflict` / `SurrealDbConflictError` (retryable conflict) | same type + decorator; conflicts rarer (engine serialises more) | same type + decorator; conflicts are the normal optimistic-MVCC failure | v0.12.0 |
2020
2024
  | `SurrealFunc` / `server_values=` / `extra_vars=` on `save`/`merge` | same on both lines (compiled to portable `CREATE`/`UPDATE … SET`) | same on both lines | v0.13.0 |
2021
- | Shipped function-name enums (`SurrealTimeFunction`, `SurrealCryptoFunction`, …) | every catalogued member verified on 2.7.0 | every catalogued member verified on 3.3.3 | v0.13.0 |
2025
+ | Shipped function-name enums (`SurrealTimeFunction`, `SurrealCryptoFunction`, …) | every catalogued member verified on 2.7.0 | every catalogued member verified on 3.3.4 | v0.13.0 |
2022
2026
  | `server_values` inside a transaction — when the instance sees the computed value | only after commit (buffered; `refresh()` to read it) | immediately (interactive returns the row) | v0.13.0 |
2023
2027
  | `merge(server_values=)` on a missing record / never-created table | server returns no rows → ORM raises `SurrealDbError` | server raises `NotFound` for a missing table → ORM raises the same error | v0.13.0 |
2024
2028
  | Computed fields (`Computed[...]` → `DEFINE FIELD … VALUE`) | same on both lines (DDL, recompute triggers, precedence over client data) | same on both lines | v0.14.0 |
@@ -2071,7 +2075,7 @@ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v
2071
2075
  | Change-feed entry shape | `{versionstamp, changes}`; a create is reported as `update` | same on both lines | v0.21.0 |
2072
2076
  | Change-feed `SINCE <n>` — what `n` is | the counter, `versionstamp >> 16` (the raw stamp silently returns nothing); `ChangeModelStream.cursor` normalises it | the versionstamp, inclusive; `cursor` normalises it | v0.21.0 |
2073
2077
  | `changes(since=<datetime>)` | the server also returns some earlier changes → at-least-once | the server returns nothing → the ORM converts to a versionstamp → exact | v0.21.0 |
2074
- | `changes(since=None)` — finding "now" | the ORM searches the counter (no history replayed) | the ORM uses the server clock (no history replayed) | v0.21.0 |
2078
+ | `changes(since=None)` — finding "now" | the ORM searches the counter (no history replayed) | the ORM reads the server clock's millisecond, then skips the entries already stamped in it (no history replayed); before v0.22.2 the entries of that millisecond were replayed | v0.21.0 |
2075
2079
  | `INCLUDE ORIGINAL` delete in a change feed | the id only → an instance holding only the `id` | 3.3.x: carries `original` → the last state of the record; 3.1.5: as 2.x | v0.21.0 |
2076
2080
  | `SHOW CHANGES` on a table without a change feed | returns `[]`; `changes()` raises `SurrealDbError` instead | same on both lines | v0.21.0 |
2077
2081
  | Typed edges (`relate(Edge, …)`, edge `save()` and `bulk_create()`) through `insert_relation()` | same on both lines: a real relation that graph traversal sees, `id` hydrated from the returned row | same on both lines | v0.22.0 |
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.22.1"
3
+ version = "0.22.2"
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.22.1"
1
+ __version__ = "0.22.2"
2
2
 
3
3
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
4
4
  from .auth import AuthTokens
@@ -18,11 +18,14 @@ The ORM reads the server line once per stream (``version()``) and always stores
18
18
  ``SINCE`` value, so ``changes(since=stream.cursor)`` is correct on both. ``SINCE <datetime>`` is
19
19
  worse still: always empty on 3.x, and on 2.x it also returns changes from before the moment. So a
20
20
  datetime is converted to the 3.x stamp layout (``unix_ms << 16``, exact), passed through on 2.x
21
- (documented as at-least-once), and "from now" on 2.x is found by searching the counter instead.
21
+ (documented as at-least-once). "From now" is, on 2.x, the end of the feed, found by searching the
22
+ counter; on 3.x, the server clock's ``unix_ms << 16``, then past the entries already stamped in
23
+ that millisecond — a 3.x stamp is ``unix_ms << 16 | counter``, so the clock alone would replay them.
22
24
 
23
25
  Polling is plain ``query()``, so it works over HTTP as well as WebSocket. A dropped connection is
24
26
  retried with backoff like a live stream; nothing is lost, because the next poll starts from the
25
- cursor.
27
+ cursor. A cancelled read (``asyncio.timeout`` around it) is never retried, even when the SDK
28
+ reports the cancellation as a failed request on a dead connection.
26
29
  """
27
30
 
28
31
  from __future__ import annotations
@@ -40,6 +43,7 @@ from .enum import LiveAction
40
43
  from .exceptions import SurrealDbConnectionError, SurrealDbError
41
44
  from .live import (
42
45
  ModelChangeEvent,
46
+ cancellation_lost,
43
47
  cancelled_from_outside,
44
48
  hydrate,
45
49
  is_connection_failure,
@@ -277,7 +281,9 @@ class ChangeModelStream(Generic[T]):
277
281
  """Fix the starting position now rather than at the first read. Idempotent.
278
282
 
279
283
  With ``since=None`` "now" is the moment of this call, so a write made between ``start()``
280
- and the first read is delivered.
284
+ and the first read is delivered, and nothing already in the feed is. On SurrealDB 3.x "now"
285
+ is the server clock's millisecond, then past the entries already stamped in it (usually one
286
+ short read); on 2.x it is the end of the feed, found by a search of the counter.
281
287
 
282
288
  A stream stopped while starting returns without sending anything more; iterating it ends.
283
289
 
@@ -303,7 +309,7 @@ class ChangeModelStream(Generic[T]):
303
309
  else:
304
310
  self._since_clause = since_sql(since, major=major)
305
311
  elif major >= 3:
306
- self._cursor = versionstamp_at(await self._server_now())
312
+ self._cursor = await self._end_of_feed_3x()
307
313
  else:
308
314
  self._cursor = await self._end_of_feed_2x()
309
315
  self._major = major
@@ -369,6 +375,34 @@ class ChangeModelStream(Generic[T]):
369
375
  now = datetime.fromisoformat(str(now))
370
376
  return now if now.tzinfo is not None else now.replace(tzinfo=UTC)
371
377
 
378
+ async def _end_of_feed_3x(self) -> int:
379
+ """The 3.x cursor for "now": past the entries stamped in the server clock's millisecond, and no further.
380
+
381
+ The clock gives only a millisecond, ``unix_ms << 16``, while a stamp is ``unix_ms << 16 |
382
+ counter`` and ``SINCE`` is inclusive: every entry committed earlier in that millisecond is
383
+ at or after it, and would be replayed as history (issue #212). So the entries of that
384
+ millisecond, and only those, are read a page of ``batch_size`` at a time, and the cursor
385
+ moves past the last one. The scan stops at a short page or at the first entry stamped in a
386
+ later millisecond: at most ``ceil(n / batch_size) + 1`` reads for the ``n`` entries of that
387
+ millisecond (usually one short read), however busy the table is.
388
+
389
+ What counts as history: a write committed in that millisecond while :meth:`start` runs is
390
+ skipped; a write in a later millisecond is delivered, and so is one made after
391
+ :meth:`start` returns, even in the same millisecond. Not ``(unix_ms + 1) << 16``: that
392
+ would also skip a write made after :meth:`start` returns in the same millisecond.
393
+ """
394
+ cursor = versionstamp_at(await self._server_now())
395
+ end = cursor + (1 << 16) # the first stamp of the next millisecond
396
+ while True:
397
+ entries = await self._show(str(cursor), self._batch_size)
398
+ stamps = [entry.get("versionstamp") for entry in entries]
399
+ inside = [stamp for stamp in stamps if isinstance(stamp, int) and cursor <= stamp < end]
400
+ if inside:
401
+ cursor = next_cursor(max(inside), major=3)
402
+ later = any(isinstance(stamp, int) and stamp >= end for stamp in stamps)
403
+ if len(entries) < self._batch_size or later or not inside: # short, past the millisecond, or stuck
404
+ return cursor
405
+
372
406
  async def _end_of_feed_2x(self) -> int:
373
407
  """The 2.x cursor right after the newest entry, found without reading the feed.
374
408
 
@@ -444,7 +478,12 @@ class ChangeModelStream(Generic[T]):
444
478
  return section if isinstance(section, dict) else None
445
479
 
446
480
  async def _with_retry(self, operation: Callable[[Any], Awaitable[Any]]) -> Any:
447
- """Run *operation* on the manager's client, retrying connection failures with backoff."""
481
+ """Run *operation* on the manager's client, retrying connection failures with backoff.
482
+
483
+ A cancellation of the reading task (``asyncio.timeout``, ``wait_for``, ``Task.cancel()``) is
484
+ never retried, even when the SDK reports it as a failed request: see
485
+ :func:`~surreal_orm_lite.live.cancellation_lost`.
486
+ """
448
487
  from .connection_manager import SurrealDBConnectionManager
449
488
 
450
489
  delay = float(self.reconnect_delay)
@@ -462,6 +501,10 @@ class ChangeModelStream(Generic[T]):
462
501
  raise
463
502
  error: Exception = SurrealDbConnectionError("the connection dropped during the request")
464
503
  except Exception as exc:
504
+ if cancellation_lost(exc):
505
+ # The SDK raised over this task's cancellation (a timeout around the read):
506
+ # retried, the cancellation would be lost and the read would poll on forever.
507
+ raise asyncio.CancelledError from exc
465
508
  if not is_connection_failure(exc, client):
466
509
  raise
467
510
  error = exc
@@ -450,6 +450,34 @@ def cancelled_from_outside() -> bool:
450
450
  return task is not None and task.cancelling() > 0
451
451
 
452
452
 
453
+ def cancellation_lost(exc: BaseException) -> bool:
454
+ """Whether *exc* replaced a cancellation of the running task, which must then be re-raised.
455
+
456
+ The SDK can raise an ordinary error over a ``CancelledError``. When a request is cancelled in
457
+ the same loop iteration its answer arrives, the SDK's receive loop calls ``set_result()`` on the
458
+ cancelled future, dies of the ``InvalidStateError`` and clears its pending-request map, so the
459
+ request's own cleanup (``del self.qry[id]``) raises a ``KeyError`` (surrealdb 2.0.0). On a client
460
+ that is dead by now, that is what a dropped connection looks like too (see
461
+ :func:`is_connection_failure`), so a reconnect loop would retry it and lose the cancellation: a
462
+ timeout around the read would never fire. A drop is told apart by the running task itself,
463
+ which is being cancelled only in the first case. The cancellation is found in the error's
464
+ chain (``__cause__``/``__context__``), even when the error was wrapped ``from None``.
465
+ """
466
+ if not cancelled_from_outside():
467
+ return False
468
+ seen: set[int] = set()
469
+ chain: list[BaseException] = [exc]
470
+ while chain:
471
+ error = chain.pop()
472
+ if id(error) in seen:
473
+ continue
474
+ seen.add(id(error))
475
+ if isinstance(error, asyncio.CancelledError):
476
+ return True
477
+ chain.extend(link for link in (error.__cause__, error.__context__) if link is not None)
478
+ return False
479
+
480
+
453
481
  def require_websocket(url: str | None) -> None:
454
482
  """Reject a live query on a transport that cannot carry one.
455
483
 
@@ -667,6 +695,8 @@ class LiveStream:
667
695
  raise
668
696
  error: Exception = SurrealDbConnectionError("the connection dropped during the request")
669
697
  except Exception as exc:
698
+ if cancellation_lost(exc):
699
+ raise asyncio.CancelledError from exc # retried, the cancellation would be lost
670
700
  if not self._still_wanted(iterator, queue, old_id):
671
701
  return # torn down meanwhile: whatever failed, nobody is waiting for it
672
702
  if not is_connection_failure(exc, client):