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.
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/CHANGELOG.md +37 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/PKG-INFO +11 -7
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/README.md +10 -6
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/pyproject.toml +1 -1
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/changefeed.py +48 -5
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/live.py +30 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/.gitignore +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/LICENSE +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/Makefile +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/model_base.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/query_set.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/transaction.py +0 -0
- {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.
|
|
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
|

|
|
55
|
-

|
|
56
56
|

|
|
57
57
|

|
|
58
58
|
[](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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
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
|

|
|
4
|
-

|
|
5
5
|

|
|
6
6
|

|
|
7
7
|
[](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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
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 |
|
|
@@ -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)
|
|
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 =
|
|
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):
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{surreal_orm_lite-0.22.1 → surreal_orm_lite-0.22.2}/src/surreal_orm_lite/connection_manager.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|