surreal-orm-lite 0.30.3__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.3 → surreal_orm_lite-0.30.5}/CHANGELOG.md +30 -0
  2. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/PKG-INFO +3 -1
  3. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/README.md +2 -0
  4. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/connection_manager.py +43 -2
  7. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/.gitignore +0 -0
  8. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/LICENSE +0 -0
  9. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/Makefile +0 -0
  10. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/_sdk.py +0 -0
  11. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/aggregations.py +0 -0
  12. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/auth.py +0 -0
  13. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/cache.py +0 -0
  14. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/changefeed.py +0 -0
  15. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/concurrency.py +0 -0
  16. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/connection_config.py +0 -0
  17. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/constants.py +0 -0
  18. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/decoding.py +0 -0
  19. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/define_parser.py +0 -0
  20. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/edge.py +0 -0
  21. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/embedded.py +0 -0
  22. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/encoding.py +0 -0
  23. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/enum.py +0 -0
  24. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/exceptions.py +0 -0
  25. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/functions.py +0 -0
  26. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/geo.py +0 -0
  27. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/introspection.py +0 -0
  28. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/live.py +0 -0
  29. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/model_auth.py +0 -0
  30. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/model_base.py +0 -0
  31. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/model_generator.py +0 -0
  32. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/py.typed +0 -0
  33. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/q.py +0 -0
  34. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/query_set.py +0 -0
  35. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/routing.py +0 -0
  36. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/schema_state.py +0 -0
  37. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/signals.py +0 -0
  38. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/subquery.py +0 -0
  39. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/surql_literal.py +0 -0
  40. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/testing/__init__.py +0 -0
  41. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/testing/database.py +0 -0
  42. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  43. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/time_travel.py +0 -0
  44. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/transaction.py +0 -0
  45. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/types.py +0 -0
  46. {surreal_orm_lite-0.30.3 → surreal_orm_lite-0.30.5}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,36 @@ 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
+
8
38
  ## [0.30.3] - 2026-10-19
9
39
 
10
40
  A statement that fails inside `transaction()` fails the whole transaction on every strategy: a
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.30.3
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
@@ -1763,6 +1763,8 @@ exactly what ends a stream.
1763
1763
  - **A failed `kill()` releases the readers but keeps the uuid alive.** When the server refuses
1764
1764
  the kill for any reason other than an unknown uuid, the error is raised, the readers are woken,
1765
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.
1766
1768
  - **The buffer is unbounded.** A stream you stop reading but never kill keeps accumulating
1767
1769
  notifications. Use the `async with` forms, or pair every uuid you start with a `kill()`.
1768
1770
 
@@ -1712,6 +1712,8 @@ exactly what ends a stream.
1712
1712
  - **A failed `kill()` releases the readers but keeps the uuid alive.** When the server refuses
1713
1713
  the kill for any reason other than an unknown uuid, the error is raised, the readers are woken,
1714
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.
1715
1717
  - **The buffer is unbounded.** A stream you stop reading but never kill keeps accumulating
1716
1718
  notifications. Use the `async with` forms, or pair every uuid you start with a `kill()`.
1717
1719
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.30.3"
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.3"
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]:
@@ -2473,10 +2479,16 @@ class SurrealDBConnectionManager:
2473
2479
  client still cached on this loop — a stream started on a server, stopped after switching
2474
2480
  to the engine — receives the KILL; otherwise the call is the no-op above.
2475
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
+
2476
2486
  :param query_uuid: the uuid of a running live query, e.g. ``stream.live_id``.
2477
2487
  :raises SurrealDbError: if the server refuses the kill for a reason other than an
2478
2488
  unknown uuid. The readers are released anyway, but the uuid is **not** recorded as
2479
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.
2480
2492
  """
2481
2493
  client = cls._cached_client()
2482
2494
  try:
@@ -2485,6 +2497,8 @@ class SurrealDBConnectionManager:
2485
2497
  # receive loop that died on a bad frame leaves the socket open, though, and the server
2486
2498
  # still running them: closing the transport is what ends them then.
2487
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)
2488
2502
  if client is not None:
2489
2503
  await cls._close_dead_socket(client)
2490
2504
  mark_killed(query_uuid)
@@ -2494,14 +2508,41 @@ class SurrealDBConnectionManager:
2494
2508
  try:
2495
2509
  await client.kill(query_uuid)
2496
2510
  except Exception as exc:
2497
- 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):
2498
2521
  raise SurrealDbError(f"Failed to kill live query {query_uuid}: {exc}") from exc
2499
2522
  mark_killed(query_uuid)
2500
2523
  finally:
2501
2524
  # In a `finally` so that every exit — success, failure, cancellation — wakes the
2502
- # 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.
2503
2527
  release_subscribers(query_uuid)
2504
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
+
2505
2546
  @staticmethod
2506
2547
  def _is_unknown_live_query(exc: Exception) -> bool:
2507
2548
  """Whether *exc* is the server refusing to kill a live query it does not know.