surreal-orm-lite 0.22.2__tar.gz → 0.23.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 (33) hide show
  1. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/CHANGELOG.md +145 -0
  2. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/PKG-INFO +435 -137
  3. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/README.md +434 -136
  4. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/__init__.py +10 -1
  6. surreal_orm_lite-0.23.0/src/surreal_orm_lite/_sdk.py +98 -0
  7. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/connection_manager.py +27 -19
  8. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/edge.py +3 -2
  9. surreal_orm_lite-0.23.0/src/surreal_orm_lite/encoding.py +240 -0
  10. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/exceptions.py +26 -0
  11. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/model_auth.py +2 -0
  12. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/model_base.py +111 -17
  13. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/query_set.py +4 -3
  14. surreal_orm_lite-0.23.0/src/surreal_orm_lite/surql_literal.py +383 -0
  15. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/transaction.py +7 -3
  16. surreal_orm_lite-0.23.0/src/surreal_orm_lite/types.py +731 -0
  17. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/utils.py +19 -2
  18. surreal_orm_lite-0.22.2/src/surreal_orm_lite/_sdk.py +0 -23
  19. surreal_orm_lite-0.22.2/src/surreal_orm_lite/surql_literal.py +0 -196
  20. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/.gitignore +0 -0
  21. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/LICENSE +0 -0
  22. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/Makefile +0 -0
  23. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/aggregations.py +0 -0
  24. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/auth.py +0 -0
  25. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/changefeed.py +0 -0
  26. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/concurrency.py +0 -0
  27. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/constants.py +0 -0
  28. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/enum.py +0 -0
  29. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/functions.py +0 -0
  30. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/live.py +0 -0
  31. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/py.typed +0 -0
  32. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/q.py +0 -0
  33. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/signals.py +0 -0
@@ -5,6 +5,151 @@ 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.23.0] - 2026-10-14
9
+
10
+ Rich field types: `timedelta`, `date`, sets and the ORM's own `Duration` and `Range[T]` are stored
11
+ as SurrealDB's native values and read back as the declared type, with the same behaviour on
12
+ SurrealDB 2.x and 3.x. Every value the ORM hands the official SDK now goes through one encoding
13
+ step. The first minor of Tier 2.
14
+
15
+ ### Added
16
+
17
+ - **Rich field types.** A model can declare `timedelta`, `date` (subclasses included) and
18
+ `set[X]`/`frozenset[X]` fields, and the ORM's `Duration` and `Range[T]`. Every write stores them
19
+ natively (a duration, a `datetime` at midnight UTC, an array sorted when its items can be
20
+ ordered, a range) and every read returns the declared type. Optional fields and values nested in
21
+ containers or sub-models are sent the same way at any depth. `datetime`, `Decimal`, `UUID` and
22
+ `bytes` fields keep working as before:
23
+
24
+ ```python
25
+ from datetime import date, timedelta
26
+ from surreal_orm_lite import (
27
+ BaseSurrealModel, BoundExcluded, BoundIncluded, Duration, Range, SurrealConfigDict,
28
+ )
29
+
30
+ class Subscription(BaseSurrealModel):
31
+ model_config = SurrealConfigDict(table_name="subscription")
32
+ id: str | None = None
33
+ renews_on: date
34
+ trial: timedelta
35
+ grace: Duration | None = None
36
+ active_hours: Range[int]
37
+ tags: set[str] = set()
38
+
39
+ await Subscription(
40
+ id="acme",
41
+ renews_on=date(2026, 2, 1),
42
+ trial=timedelta(days=14),
43
+ grace=Duration.parse("1h30m1ns"), # nanoseconds kept
44
+ active_hours=Range(BoundIncluded(9), BoundExcluded(17)), # 9..17
45
+ tags={"pro", "annual"},
46
+ ).save()
47
+ sub = await Subscription.objects().get("acme")
48
+ sub.trial # timedelta(days=14): a duration on the server
49
+ ```
50
+
51
+ - **`Duration`**: a SurrealDB duration with the server's nanosecond precision, where `timedelta`
52
+ stops at microseconds. It mirrors the SDK 2.0.0 `surrealdb.Duration`, the same members under the
53
+ same names and parameters (`elapsed`, `parse(value, nanoseconds=0)`, `get_seconds_and_nano()`,
54
+ `to_compact()`, `to_string()`, the unit properties), with exact results: `to_compact()` keeps
55
+ the nanoseconds and `to_string()` writes every unit. `parse()` reads the server's syntax strictly
56
+ (`"1h 30m"` and `"1.5h"` are refused). It adds `MAX_NANOSECONDS`, `from_timedelta()`,
57
+ `to_timedelta()`, hashing and ordering. As a field it accepts a `Duration`, the SDK's `Duration`,
58
+ a non-negative `timedelta` or a SurrealQL duration string (`"1h30m"`); in JSON it is that text.
59
+ - **`InvalidDurationError`**: raised for a value `Duration` refuses. It is both a `ValueError` and
60
+ a `surrealdb.InvalidDurationError`, so an `except` written against the SDK catches it.
61
+ - **`Range[T]`**: a SurrealDB range whose sides are the SDK's `BoundIncluded`/`BoundExcluded` (now
62
+ exported by the ORM) or `None` for an open side; the SDK's own spellings of an open side
63
+ (`Bound()`, `surrealdb.cbor.undefined`, a CBOR null) are accepted too. `str()` is the SurrealQL
64
+ range text (`9..17`, `1>..=5`, `65..`), which a `Range` field reads back, and which writes every
65
+ bound exactly, including values a live-query filter refuses. As a field it validates each bound
66
+ value as `T` and accepts the SDK's `Range`, a builtin `range` with step 1 and that text; in JSON
67
+ it is that text.
68
+ - **`in`/`not_in` with a `Range`** (the ORM's or the SDK's) bind it as one value (`hour IN $_f0`)
69
+ instead of refusing it as a non-iterable; a builtin `range` keeps its meaning, the list of its
70
+ integers. On the record-id column `id` and on an edge's `in`/`out` columns it raises
71
+ `ValueError`, since a record id never falls inside a value range. `contains` on a range column
72
+ tests membership (`active_hours__contains=12`).
73
+ - **Live-query literals** for durations (`1h30m1ns`, exact to the nanosecond), dates (midnight
74
+ UTC), sets (sorted when their items can be ordered) and ranges, so `live()` and `watch()` filters
75
+ on rich fields give the same results on both lines.
76
+ - `Duration`, `Range`, `BoundIncluded`, `BoundExcluded` and `InvalidDurationError` are exported
77
+ from the package root.
78
+ - README section 24, "Rich field types" (annotation table, `Duration`, `Range[T]`, filters,
79
+ precision, sets, values refused before sending, rows applied after a write, values the SDK
80
+ cannot read, authentication, a note for users of the full SurrealDB-ORM); example notebook
81
+ `examples/v0.23.0_rich_field_types.ipynb`.
82
+
83
+ ### Changed
84
+
85
+ - **Every value the ORM sends goes through one encoding step** before it reaches the official SDK:
86
+ the fields of every write API, filter values, `raw_query()` and `call_function()` variables,
87
+ transaction statements and auth variables (`signup()`, and the `variables=` of
88
+ `SurrealDBConnectionManager.signin()`/`signup()`). A value v0.22.2 already sent as it was is
89
+ handed to the SDK unchanged.
90
+ - **Values the server would reject are refused before anything is sent**, with a plain
91
+ `ValueError` that says why, never re-wrapped in a `SurrealDbError`: a negative duration, a
92
+ duration of `2**64` seconds or more, a zero duration while the installed SDK cannot read one back
93
+ (SDK 2.0.0), a finite `Decimal` whose integer part, rounded, exceeds `2**96 - 1` (the largest
94
+ SurrealDB decimal), and an `int` outside the signed 64-bit range (one between `2**63` and
95
+ `2**64 - 1` was stored as a negative number; use `Decimal`). For a zero duration, store `None`
96
+ and filter "longer than zero" with `__gte=Duration(1)`.
97
+ - A `Decimal` written with an exponent (`Decimal("1E-7")`, `Decimal("1E+3")`) is sent in
98
+ fixed-point notation (`0.0000001`, `1000`), cut after the 29th fractional digit. The server keeps
99
+ at most 28 fractional digits, rounding half away from zero as before, so the stored value is the
100
+ same. A value without an exponent is sent as before.
101
+ - `atomic_increment()` refuses a duration amount (a `timedelta`, the SDK's or the ORM's
102
+ `Duration`) with `TypeError` before anything is sent: SurrealDB 2.x ignores `+=` with a duration
103
+ where 3.x applies it, so the same call gave a different row on each line. Set the new value with
104
+ `merge()`. Numeric and `Decimal` amounts are unchanged.
105
+ - An SDK `Range` whose open side is written `undefined` (or `Bound()`) is now sent with the
106
+ protocol's null bound; the server reads it the same way, as an open side.
107
+ - Rows applied after a write without validation (`save()` without an id, `refresh()`, `merge()`,
108
+ `upsert()`, `patch()`, the `atomic_*` helpers) turn the SDK's duration into a `timedelta` or a
109
+ `Duration` in top-level fields of those types, so writing the instance back stores a duration.
110
+ Every other value is applied as received, as before.
111
+
112
+ ### Fixed
113
+
114
+ - `timedelta`, `date`, `set`/`frozenset`, SDK `Duration` and open-sided `Range` values, `Decimal`s
115
+ written with an exponent (zeros such as `0E+30` included) and `int`s outside signed 64-bit are now
116
+ converted or refused before sending, in writes, filter values, `call_function()` arguments and
117
+ auth variables.
118
+ - A row holding a duration now loads into a top-level `timedelta` field (floored to the
119
+ microsecond) through `get()`, `filter()`, `all()`, `first()`, `raw_query()`, live and
120
+ change-feed events, model `signup()` and the rows `bulk_create()` returns; the field's validation
121
+ refused the SDK's duration.
122
+ - The live-filter `Decimal` literal decides huge exponents before formatting: a zero with a long
123
+ exponent is written without building its full text, and a value beyond Python's 4,300-digit
124
+ limit raises the documented `TypeError` instead of a `ValueError`.
125
+
126
+ ### Notes
127
+
128
+ - **Same on both lines**, measured on SurrealDB 2.7.0 and 3.3.4, with 3.1.5 where it differs,
129
+ except `TYPE set<…>` columns: on 3.3 such a column holds a native set that the surrealdb SDK
130
+ 2.0.0 cannot read (reads fail with an SDK decoding error), and 3.1 refuses the array. Declare
131
+ such columns `array<…>`, optionally with `VALUE $value.distinct()`. The README's "SurrealDB 2.6.x
132
+ vs 3.x" table gains these two rows and a retroactive one: on reads, 2.x keeps a `Decimal`'s
133
+ trailing zeros (`12.50`) where 3.x normalises them (`12.5`); the values are equal.
134
+ - **SDK 2.0.0 limits**: it cannot decode a zero duration or a SurrealDB 3.x native set. The ORM
135
+ never sends either, but a record another client wrote may hold one, and reading it fails with an
136
+ SDK decoding error. A later SDK lifts both (#205).
137
+ - **Filter values on rich fields must be typed**: strings are not converted, so
138
+ `filter(trial__gte="7d")` compares the stored duration with a string; pass `timedelta(days=7)`
139
+ (#220). Keyword writes (`merge(field=...)`, `bulk_update()`) are not validated against the
140
+ field's type (#221).
141
+ - **Precision**: `datetime` to the microsecond (the SDK truncates the server's nanoseconds);
142
+ `timedelta` floored to the microsecond on read; `Duration` exact. On reads, a `timedelta` below a
143
+ top-level field (`list[timedelta]`, a sub-model's field) fails validation as before: declare
144
+ `Duration` there.
145
+ - After a write that returns the row, `date`, `set` and `Range` fields hold the SDK's value (a
146
+ midnight `datetime`, a `list`, the SDK's `Range`) until the record is loaded again; writing such
147
+ an instance back is safe.
148
+ - **Equality with the SDK's values is one-way**: `Duration(5) == surrealdb.Duration(5)` is `True`,
149
+ the reverse is `False` (the SDK's `__eq__` answers `False` for any other type); the same holds
150
+ for `Range`. Keep the ORM value on the left.
151
+ - Tested against SurrealDB 3.3.4 and 2.7.0 (the CI pins), plus 3.1.5 for backward compatibility.
152
+
8
153
  ## [0.22.2] - 2026-10-13
9
154
 
10
155
  Change-feed fixes: history replayed by `changes(since=None)` on SurrealDB 3.x, and a timed-out