surreal-orm-lite 0.22.1__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.
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/CHANGELOG.md +182 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/PKG-INFO +443 -141
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/README.md +442 -140
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/pyproject.toml +1 -1
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/__init__.py +10 -1
- surreal_orm_lite-0.23.0/src/surreal_orm_lite/_sdk.py +98 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/changefeed.py +48 -5
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/connection_manager.py +27 -19
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/edge.py +3 -2
- surreal_orm_lite-0.23.0/src/surreal_orm_lite/encoding.py +240 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/exceptions.py +26 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/live.py +30 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/model_auth.py +2 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/model_base.py +111 -17
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/query_set.py +4 -3
- surreal_orm_lite-0.23.0/src/surreal_orm_lite/surql_literal.py +383 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/transaction.py +7 -3
- surreal_orm_lite-0.23.0/src/surreal_orm_lite/types.py +731 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/utils.py +19 -2
- surreal_orm_lite-0.22.1/src/surreal_orm_lite/_sdk.py +0 -23
- surreal_orm_lite-0.22.1/src/surreal_orm_lite/surql_literal.py +0 -196
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/.gitignore +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/LICENSE +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/Makefile +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.22.1 → surreal_orm_lite-0.23.0}/src/surreal_orm_lite/signals.py +0 -0
|
@@ -5,6 +5,188 @@ 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
|
+
|
|
153
|
+
## [0.22.2] - 2026-10-13
|
|
154
|
+
|
|
155
|
+
Change-feed fixes: history replayed by `changes(since=None)` on SurrealDB 3.x, and a timed-out
|
|
156
|
+
read that could hang on both lines. No new public API.
|
|
157
|
+
|
|
158
|
+
### Fixed
|
|
159
|
+
|
|
160
|
+
- **`changes(since=None)` no longer replays history on SurrealDB 3.x** (#212). On 3.x the stream
|
|
161
|
+
started at the server clock's millisecond (`unix_ms << 16`), but a 3.x versionstamp is
|
|
162
|
+
`unix_ms << 16 | counter` and `SINCE` is inclusive, so every entry committed earlier in that
|
|
163
|
+
same millisecond was delivered as if it were new, and `stream.cursor` did not point at the end
|
|
164
|
+
of the feed. `start()` now reads the entries stamped in that millisecond, a page of
|
|
165
|
+
`batch_size` at a time, and moves the cursor past the last one: usually one short read, at most
|
|
166
|
+
`ceil(n / batch_size) + 1` reads for the `n` entries of that millisecond, however busy the
|
|
167
|
+
table is. It goes through the same retry and `stop()` path as every other request.
|
|
168
|
+
- A write committed in that millisecond while `start()` runs is history and is skipped; a write
|
|
169
|
+
in a later millisecond, or one made after `start()` returns (even in the same millisecond),
|
|
170
|
+
is delivered.
|
|
171
|
+
- This was the cause of two intermittent change-feed test failures on SurrealDB 3.x.
|
|
172
|
+
- **A change-feed read under `asyncio.timeout()` or `wait_for()` could hang forever**, on both
|
|
173
|
+
server lines. When the read was cancelled in the very loop iteration the server's answer
|
|
174
|
+
arrived, the official SDK (surrealdb 2.0.0) raised a `KeyError` over the `CancelledError` and
|
|
175
|
+
its connection died, which is what a dropped connection looks like. The stream retried it as one
|
|
176
|
+
and lost the cancellation: the timeout never fired and the read polled on, for as long as the
|
|
177
|
+
process ran. A cancellation of the reading task is now re-raised instead of retried, so the read
|
|
178
|
+
times out as asked and loses nothing (the next read starts from the cursor). A live query's
|
|
179
|
+
automatic resubscribe gets the same guard, so cancelling it (`asyncio.run()` shutting down, for
|
|
180
|
+
instance) no longer has it reconnect on.
|
|
181
|
+
|
|
182
|
+
### Notes
|
|
183
|
+
|
|
184
|
+
- **`changes(since=None)` on SurrealDB 2.x is unchanged**: there "now" is the end of the feed,
|
|
185
|
+
found by searching the counter, which never had this problem. The README's "SurrealDB 2.6.x vs
|
|
186
|
+
3.x" table now says how the 3.x side finds "now". The timed-out read fix is the same on both
|
|
187
|
+
lines: the race is in the SDK, not in the server.
|
|
188
|
+
- Tested against SurrealDB 3.3.4 and 2.7.0 (the CI pins), plus 3.1.5 for backward compatibility.
|
|
189
|
+
|
|
8
190
|
## [0.22.0] - 2026-10-12
|
|
9
191
|
|
|
10
192
|
Native typed relations: graph edges as Pydantic models, created through the official SDK's
|