surreal-orm-lite 0.19.4__tar.gz → 0.20.0__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 (27) hide show
  1. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/CHANGELOG.md +72 -0
  2. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/PKG-INFO +231 -99
  3. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/README.md +230 -98
  4. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/__init__.py +6 -2
  6. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/connection_manager.py +12 -7
  7. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/live.py +344 -7
  8. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/query_set.py +84 -51
  9. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/signals.py +19 -0
  10. surreal_orm_lite-0.20.0/src/surreal_orm_lite/surql_literal.py +196 -0
  11. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/.gitignore +0 -0
  12. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/LICENSE +0 -0
  13. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/Makefile +0 -0
  14. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/_sdk.py +0 -0
  15. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/aggregations.py +0 -0
  16. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/auth.py +0 -0
  17. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/concurrency.py +0 -0
  18. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/constants.py +0 -0
  19. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/enum.py +0 -0
  20. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/exceptions.py +0 -0
  21. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/functions.py +0 -0
  22. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/model_auth.py +0 -0
  23. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/model_base.py +0 -0
  24. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/py.typed +0 -0
  25. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/q.py +0 -0
  26. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/transaction.py +0 -0
  27. {surreal_orm_lite-0.19.4 → surreal_orm_lite-0.20.0}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,78 @@ 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.20.0] - 2026-10-07
9
+
10
+ Typed live queries, with the same API as the full SurrealDB-ORM: code written against
11
+ `surreal_orm` migrates by changing the import.
12
+
13
+ ### Added
14
+
15
+ - **`QuerySet.live(*, diff=False)` → `LiveModelStream`** — an async context manager and
16
+ iterator of `ModelChangeEvent` objects carrying a **model instance**. The queryset's filters
17
+ are applied by the server, and the live query is killed when the block exits:
18
+
19
+ ```python
20
+ async with User.objects().filter(role="admin").live() as stream:
21
+ async for event in stream:
22
+ print(event.action, event.instance.name, event.record_id)
23
+ ```
24
+
25
+ - **`ModelChangeEvent`** — `action`, `instance`, `record_id` (`"user:abc"`), `changed_fields`
26
+ (diff mode, Python field names) and `raw`, field for field the full ORM's event.
27
+ - **Filtered live queries** — `filter()` (lookups, `Q`, `Var` with `variables()`) and `fetch()`
28
+ compile into `LIVE SELECT … WHERE … FETCH …`, with field aliases translated. Works identically
29
+ on SurrealDB 2.x and 3.x.
30
+ - **Diff mode** — `live(diff=True)` / `watch(diff=True)` use `LIVE SELECT DIFF`; `changed_fields`
31
+ lists the top-level fields each update touched.
32
+ - **`post_live_change` signal** — same name and arguments as the full ORM (`instance`, `action`,
33
+ `record_id`, `changed_fields`), run for every event a `live()` stream yields on one background
34
+ task per stream, in event order. A failing handler is logged and never interrupts the stream;
35
+ a normal exit waits for pending handlers (`signal_drain_timeout`, 5 s), an exception cancels
36
+ them.
37
+ - **`ModelChangeEvent.validation_error`** — a record that does not fit the model no longer ends
38
+ the stream: the event carries the error and an unvalidated instance, `post_live_change` is not
39
+ sent for it, and a warning naming the failing fields — never their values — is logged once per
40
+ stream.
41
+ - **`watch(diff=)`**, and `watch()` now honours the same filters as `live()`.
42
+ - `LiveModelStream`, `ModelChangeEvent` and `post_live_change` are exported from the package root.
43
+
44
+ ### Changed
45
+
46
+ - **`await QuerySet.live()` is deprecated.** It still starts a live query and returns its uuid
47
+ (the v0.19.0 contract), with a `DeprecationWarning` pointing at `async with ….live()` or
48
+ `watch()`. The stream `live()` now returns also implements the coroutine protocol, so
49
+ `asyncio.create_task(qs.live())` and `asyncio.run(qs.live())` keep working; it can be awaited
50
+ once, and an awaited stream refuses to `start()` (and the reverse). `inspect.iscoroutine()` is
51
+ `False` for it. To hold a subscription across tasks, start the stream
52
+ (`await qs.watch().start()`), read **it**, and stop it with `kill(stream.live_id)`.
53
+ - Every live query now starts through `LIVE SELECT` sent with `query()` rather than the SDK's
54
+ table-only `live()`. `filter()`, `fetch()` and `variables()` are no longer refused; `select()`,
55
+ `values()`, `annotate()`, `order_by()`, `limit()`, `offset()` and `objects(tx=)` still are, by
56
+ name.
57
+
58
+ ### Notes
59
+
60
+ - **SurrealDB 2.x drops bound parameters inside a live query.** `LIVE SELECT … WHERE status = $s`
61
+ is accepted, then `$s` evaluates to `NONE` at notification time and the filter matches nothing,
62
+ without an error. For live queries only, the ORM therefore writes each filter value as a
63
+ SurrealQL literal — the full ORM's approach — through a closed encoder (`None`, `bool`, `int`,
64
+ `float`, `str`, `Decimal`, `datetime` in UTC, `UUID`, `RecordID` incl. UUID keys, lists and
65
+ dicts). Any other type, a string containing NUL, an integer beyond 64 bits or a `Decimal`
66
+ beyond 28 significant fractional digits / a 96-bit mantissa raises `TypeError` at the call,
67
+ before anything is sent. A reference that is neither bound through `variables()` nor a server
68
+ parameter (`$auth`, `$session`, …) raises `SurrealDbError`: unbound, it would read as `NONE`
69
+ on every notification. Every literal is checked against the server on both lines by the test
70
+ suite.
71
+ - Filter semantics, measured identically on 2.7.0 and 3.3.0: a record entering the filter through
72
+ an update arrives as `UPDATE`; one leaving it reports nothing, nor its later `DELETE`.
73
+ - **Diff mode differs by line in its raw form**: the root patch path is `"/"` on 2.x and `""` on
74
+ 3.x, and a `DELETE` carries the whole last record on 2.x but a `replace` with `None` on 3.x.
75
+ `live(diff=True)` normalises both; `watch(diff=True)` passes them through. On both lines a
76
+ changed string arrives as `op: change` with diff-match-patch text — JSON Patch extended by
77
+ SurrealDB.
78
+ - Not yet: `auto_resubscribe=` / `on_reconnect=` (v0.21.0). Passing them raises `TypeError`.
79
+
8
80
  ## [0.19.2] - 2026-10-01
9
81
 
10
82
  Security release for the locked dependencies. No library code changes; the published package