surreal-orm-lite 0.22.2__tar.gz → 0.24.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 (35) hide show
  1. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/CHANGELOG.md +255 -0
  2. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/PKG-INFO +846 -139
  3. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/README.md +845 -138
  4. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/__init__.py +51 -1
  6. surreal_orm_lite-0.24.0/src/surreal_orm_lite/_sdk.py +134 -0
  7. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/connection_manager.py +27 -19
  8. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/constants.py +9 -0
  9. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/edge.py +3 -2
  10. surreal_orm_lite-0.24.0/src/surreal_orm_lite/encoding.py +443 -0
  11. surreal_orm_lite-0.24.0/src/surreal_orm_lite/exceptions.py +142 -0
  12. surreal_orm_lite-0.24.0/src/surreal_orm_lite/geo.py +1291 -0
  13. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/model_auth.py +2 -0
  14. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/model_base.py +127 -17
  15. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/query_set.py +258 -26
  16. surreal_orm_lite-0.24.0/src/surreal_orm_lite/surql_literal.py +410 -0
  17. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/transaction.py +7 -3
  18. surreal_orm_lite-0.24.0/src/surreal_orm_lite/types.py +731 -0
  19. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/utils.py +57 -3
  20. surreal_orm_lite-0.22.2/src/surreal_orm_lite/_sdk.py +0 -23
  21. surreal_orm_lite-0.22.2/src/surreal_orm_lite/exceptions.py +0 -93
  22. surreal_orm_lite-0.22.2/src/surreal_orm_lite/surql_literal.py +0 -196
  23. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/.gitignore +0 -0
  24. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/LICENSE +0 -0
  25. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/Makefile +0 -0
  26. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/aggregations.py +0 -0
  27. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/auth.py +0 -0
  28. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/changefeed.py +0 -0
  29. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/concurrency.py +0 -0
  30. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/enum.py +0 -0
  31. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/functions.py +0 -0
  32. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/live.py +0 -0
  33. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/py.typed +0 -0
  34. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/q.py +0 -0
  35. {surreal_orm_lite-0.22.2 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/signals.py +0 -0
@@ -5,6 +5,261 @@ 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.24.0] - 2026-10-15
9
+
10
+ Geospatial fields: a model can declare geometry fields stored as SurrealDB's native geometries and
11
+ read back as the ORM's geometry classes, and query them with `nearby()`, a `GeoDistance`
12
+ annotation and the `inside`, `outside` and `intersects` lookups, with the same results and the
13
+ same distances on SurrealDB 2.x and 3.x. The names follow the full SurrealDB-ORM. The second minor
14
+ of Tier 2.
15
+
16
+ ### Added
17
+
18
+ - **Geometry fields.** `GeoField["kind"]` and the aliases `PointField`, `LineStringField`,
19
+ `PolygonField`, `MultiPointField`, `MultiLineStringField`, `MultiPolygonField`,
20
+ `GeometryCollectionField` and `GeometryField` declare nullable geometry fields with a `None`
21
+ default, as in the full ORM; a geometry class annotation (`entrance: GeometryPoint`) works too.
22
+ A field accepts the ORM value, the SDK's, a GeoJSON object and, for points, a
23
+ `(longitude, latitude)` pair. Every write stores a native geometry; `get()`, `filter()`, live
24
+ notifications, change feeds and the rows a write returns give back the ORM's classes.
25
+ `model_dump(mode="json")` writes GeoJSON. Edge models and field aliases are supported:
26
+
27
+ ```python
28
+ from surreal_orm_lite import (
29
+ BaseSurrealModel, GeoDistance, GeometryPoint, PointField, SurrealConfigDict,
30
+ )
31
+
32
+ class Restaurant(BaseSurrealModel):
33
+ model_config = SurrealConfigDict(table_name="restaurant")
34
+ id: str | None = None
35
+ name: str
36
+ location: PointField = None
37
+
38
+ times_square = GeometryPoint(-73.9855, 40.7580) # longitude, latitude
39
+ await Restaurant(id="pizza", name="Corner Pizza", location=(-73.9877, 40.7547)).save()
40
+
41
+ closest = await (
42
+ Restaurant.objects()
43
+ .nearby("location", times_square, max_distance=5_000) # metres
44
+ .annotate(dist=GeoDistance("location", times_square))
45
+ .order_by("dist")
46
+ .exec()
47
+ )
48
+ round(closest[0].dist) # 411: metres, as SurrealDB's geo::distance measures it
49
+ ```
50
+
51
+ - **Geometry value classes**: `Geometry` and `GeometryPoint`, `GeometryLine`, `GeometryPolygon`,
52
+ `GeometryMultiPoint`, `GeometryMultiLine`, `GeometryMultiPolygon` and `GeometryCollection`, with
53
+ the names, constructor signatures, attributes and methods of the SDK's classes
54
+ (`parse_coordinates()`, `get_coordinates()`, …). They are immutable and hashable, keep `float`
55
+ coordinates, convert to and from GeoJSON (`to_geojson()`, `Geometry.from_geojson()`,
56
+ `__geo_interface__`), and `str()` gives their SurrealQL text. They exist because Pydantic's
57
+ `model_dump()` flattens the SDK's dataclasses into plain dicts; the ORM converts them to the
58
+ SDK's classes when it sends them.
59
+ - **`InvalidGeometryError`**: raised for a geometry the classes refuse (a non-finite coordinate, a
60
+ polygon ring of fewer than 4 points or not closed, a collection nested more than 32 levels,
61
+ malformed GeoJSON). It is both a `ValueError` and a `surrealdb.InvalidGeometryError`.
62
+ - **`QuerySet.nearby(field, point, max_distance)`**: keeps the records whose field is a point within
63
+ `max_distance` metres of `point`. The point and the distance are bound as query variables, a
64
+ `.is_point()` guard leaves out records whose field holds no point, several calls are AND-ed, and
65
+ the condition applies wherever `filter()` does, `live()` and `watch()` included.
66
+ - **`GeoDistance(field, point)`** for `annotate()`: each instance gets the distance in metres as an
67
+ attribute named after the alias (`None` when its field is not a point), `order_by()` sorts by
68
+ it, and it is never written back.
69
+ - **Spatial lookups** `inside`, `outside` and `intersects` (`filter(location__inside=zone)`),
70
+ compiled to SurrealQL's `INSIDE`, `OUTSIDE` and `INTERSECTS` with one bound geometry; they work in
71
+ `filter()`, `Q` objects (`~Q` included) and live queries. `outside` keeps SurrealQL's meaning: a
72
+ record without a geometry is outside.
73
+ - **Live-query literals** for geometries (GeoJSON object form, every kind and collection member),
74
+ so `nearby()`, the spatial lookups and geometry filter values give the same notifications on
75
+ both lines.
76
+ - `is_geo_field()` and `get_geo_info()` in `surreal_orm_lite.geo`; the geometry classes, the field
77
+ aliases, `GeoField`, `GeoDistance` and `InvalidGeometryError` are exported from the package root.
78
+ - README section 25, "Geospatial fields" (annotations, values and GeoJSON, `nearby()`,
79
+ `GeoDistance`, spatial lookups, live queries, computed geometry fields, migrating stored GeoJSON,
80
+ type checkers, a note for users of the full SurrealDB-ORM); example notebook
81
+ `examples/v0.24.0_geospatial_fields.ipynb`.
82
+
83
+ ### Changed
84
+
85
+ - **Geometries go through the encoding boundary.** An ORM geometry is sent as the equal SDK
86
+ geometry; an SDK geometry is sent as it is once checked. An SDK geometry every SurrealDB line
87
+ refuses (a line of fewer than 2 points, a polygon without a ring, a ring of fewer than 4 points
88
+ once closed, a coordinate that is not a number, a member of the wrong kind) raises a plain
89
+ `ValueError` before anything is sent.
90
+ - Rows applied after a write without validation (`save()` without an id, `refresh()`, `merge()`,
91
+ `upsert()`, `patch()`, the `atomic_*` helpers) turn the SDK's geometries into the ORM's classes
92
+ in top-level geometry fields, so writing the instance back stores a geometry. Sub-models keep the
93
+ row's `dict`, as before (#228).
94
+
95
+ ### Fixed
96
+
97
+ - A `Decimal` coordinate written with an exponent in an SDK geometry is now sent in fixed-point
98
+ notation, like a top-level `Decimal`: SurrealDB 2.x refused `Decimal("1E-7")` there, and both
99
+ lines stored a long one with a wrong value. Both lines now store the value.
100
+
101
+ ### Notes
102
+
103
+ - **Same on both lines**, measured on SurrealDB 2.7.0 and 3.3.4, identical on 3.1.5: storage,
104
+ reads, `nearby()`, distances, the spatial lookups and live notifications. The README's
105
+ "SurrealDB 2.6.x vs 3.x" table gains three rows, one of them retroactive: a GeoJSON dict written
106
+ to an untyped field (`Any`, `dict`) is stored as a plain object, not a geometry.
107
+ - **Migrating from the full SurrealDB-ORM**, which stores geometry fields as GeoJSON dicts (plain
108
+ objects that `geo::*` functions refuse): a geometry field reads such a value, and `update()`
109
+ writes it back as a native geometry, so loading and updating every record migrates a table.
110
+ - **Known limits**: the surrealdb SDK 2.0.0 cannot read a degenerate geometry another client
111
+ wrote (a 1-point line, a ring of fewer than 4 points). Geometries inside sub-models are written
112
+ back as plain objects after a write that syncs the instance (#228), and ORM geometries in
113
+ untyped fields read back as the SDK's classes (#222). Filter values of other lookups and keyword
114
+ writes are not validated against the field: pass geometry objects there (#220, #221).
115
+ `GeoField["point"]` is not understood by type checkers, as in the full ORM; use the aliases or
116
+ the classes in type-checked code.
117
+
118
+ ## [0.23.0] - 2026-10-14
119
+
120
+ Rich field types: `timedelta`, `date`, sets and the ORM's own `Duration` and `Range[T]` are stored
121
+ as SurrealDB's native values and read back as the declared type, with the same behaviour on
122
+ SurrealDB 2.x and 3.x. Every value the ORM hands the official SDK now goes through one encoding
123
+ step. The first minor of Tier 2.
124
+
125
+ ### Added
126
+
127
+ - **Rich field types.** A model can declare `timedelta`, `date` (subclasses included) and
128
+ `set[X]`/`frozenset[X]` fields, and the ORM's `Duration` and `Range[T]`. Every write stores them
129
+ natively (a duration, a `datetime` at midnight UTC, an array sorted when its items can be
130
+ ordered, a range) and every read returns the declared type. Optional fields and values nested in
131
+ containers or sub-models are sent the same way at any depth. `datetime`, `Decimal`, `UUID` and
132
+ `bytes` fields keep working as before:
133
+
134
+ ```python
135
+ from datetime import date, timedelta
136
+ from surreal_orm_lite import (
137
+ BaseSurrealModel, BoundExcluded, BoundIncluded, Duration, Range, SurrealConfigDict,
138
+ )
139
+
140
+ class Subscription(BaseSurrealModel):
141
+ model_config = SurrealConfigDict(table_name="subscription")
142
+ id: str | None = None
143
+ renews_on: date
144
+ trial: timedelta
145
+ grace: Duration | None = None
146
+ active_hours: Range[int]
147
+ tags: set[str] = set()
148
+
149
+ await Subscription(
150
+ id="acme",
151
+ renews_on=date(2026, 2, 1),
152
+ trial=timedelta(days=14),
153
+ grace=Duration.parse("1h30m1ns"), # nanoseconds kept
154
+ active_hours=Range(BoundIncluded(9), BoundExcluded(17)), # 9..17
155
+ tags={"pro", "annual"},
156
+ ).save()
157
+ sub = await Subscription.objects().get("acme")
158
+ sub.trial # timedelta(days=14): a duration on the server
159
+ ```
160
+
161
+ - **`Duration`**: a SurrealDB duration with the server's nanosecond precision, where `timedelta`
162
+ stops at microseconds. It mirrors the SDK 2.0.0 `surrealdb.Duration`, the same members under the
163
+ same names and parameters (`elapsed`, `parse(value, nanoseconds=0)`, `get_seconds_and_nano()`,
164
+ `to_compact()`, `to_string()`, the unit properties), with exact results: `to_compact()` keeps
165
+ the nanoseconds and `to_string()` writes every unit. `parse()` reads the server's syntax strictly
166
+ (`"1h 30m"` and `"1.5h"` are refused). It adds `MAX_NANOSECONDS`, `from_timedelta()`,
167
+ `to_timedelta()`, hashing and ordering. As a field it accepts a `Duration`, the SDK's `Duration`,
168
+ a non-negative `timedelta` or a SurrealQL duration string (`"1h30m"`); in JSON it is that text.
169
+ - **`InvalidDurationError`**: raised for a value `Duration` refuses. It is both a `ValueError` and
170
+ a `surrealdb.InvalidDurationError`, so an `except` written against the SDK catches it.
171
+ - **`Range[T]`**: a SurrealDB range whose sides are the SDK's `BoundIncluded`/`BoundExcluded` (now
172
+ exported by the ORM) or `None` for an open side; the SDK's own spellings of an open side
173
+ (`Bound()`, `surrealdb.cbor.undefined`, a CBOR null) are accepted too. `str()` is the SurrealQL
174
+ range text (`9..17`, `1>..=5`, `65..`), which a `Range` field reads back, and which writes every
175
+ bound exactly, including values a live-query filter refuses. As a field it validates each bound
176
+ value as `T` and accepts the SDK's `Range`, a builtin `range` with step 1 and that text; in JSON
177
+ it is that text.
178
+ - **`in`/`not_in` with a `Range`** (the ORM's or the SDK's) bind it as one value (`hour IN $_f0`)
179
+ instead of refusing it as a non-iterable; a builtin `range` keeps its meaning, the list of its
180
+ integers. On the record-id column `id` and on an edge's `in`/`out` columns it raises
181
+ `ValueError`, since a record id never falls inside a value range. `contains` on a range column
182
+ tests membership (`active_hours__contains=12`).
183
+ - **Live-query literals** for durations (`1h30m1ns`, exact to the nanosecond), dates (midnight
184
+ UTC), sets (sorted when their items can be ordered) and ranges, so `live()` and `watch()` filters
185
+ on rich fields give the same results on both lines.
186
+ - `Duration`, `Range`, `BoundIncluded`, `BoundExcluded` and `InvalidDurationError` are exported
187
+ from the package root.
188
+ - README section 24, "Rich field types" (annotation table, `Duration`, `Range[T]`, filters,
189
+ precision, sets, values refused before sending, rows applied after a write, values the SDK
190
+ cannot read, authentication, a note for users of the full SurrealDB-ORM); example notebook
191
+ `examples/v0.23.0_rich_field_types.ipynb`.
192
+
193
+ ### Changed
194
+
195
+ - **Every value the ORM sends goes through one encoding step** before it reaches the official SDK:
196
+ the fields of every write API, filter values, `raw_query()` and `call_function()` variables,
197
+ transaction statements and auth variables (`signup()`, and the `variables=` of
198
+ `SurrealDBConnectionManager.signin()`/`signup()`). A value v0.22.2 already sent as it was is
199
+ handed to the SDK unchanged.
200
+ - **Values the server would reject are refused before anything is sent**, with a plain
201
+ `ValueError` that says why, never re-wrapped in a `SurrealDbError`: a negative duration, a
202
+ duration of `2**64` seconds or more, a zero duration while the installed SDK cannot read one back
203
+ (SDK 2.0.0), a finite `Decimal` whose integer part, rounded, exceeds `2**96 - 1` (the largest
204
+ SurrealDB decimal), and an `int` outside the signed 64-bit range (one between `2**63` and
205
+ `2**64 - 1` was stored as a negative number; use `Decimal`). For a zero duration, store `None`
206
+ and filter "longer than zero" with `__gte=Duration(1)`.
207
+ - A `Decimal` written with an exponent (`Decimal("1E-7")`, `Decimal("1E+3")`) is sent in
208
+ fixed-point notation (`0.0000001`, `1000`), cut after the 29th fractional digit. The server keeps
209
+ at most 28 fractional digits, rounding half away from zero as before, so the stored value is the
210
+ same. A value without an exponent is sent as before.
211
+ - `atomic_increment()` refuses a duration amount (a `timedelta`, the SDK's or the ORM's
212
+ `Duration`) with `TypeError` before anything is sent: SurrealDB 2.x ignores `+=` with a duration
213
+ where 3.x applies it, so the same call gave a different row on each line. Set the new value with
214
+ `merge()`. Numeric and `Decimal` amounts are unchanged.
215
+ - An SDK `Range` whose open side is written `undefined` (or `Bound()`) is now sent with the
216
+ protocol's null bound; the server reads it the same way, as an open side.
217
+ - Rows applied after a write without validation (`save()` without an id, `refresh()`, `merge()`,
218
+ `upsert()`, `patch()`, the `atomic_*` helpers) turn the SDK's duration into a `timedelta` or a
219
+ `Duration` in top-level fields of those types, so writing the instance back stores a duration.
220
+ Every other value is applied as received, as before.
221
+
222
+ ### Fixed
223
+
224
+ - `timedelta`, `date`, `set`/`frozenset`, SDK `Duration` and open-sided `Range` values, `Decimal`s
225
+ written with an exponent (zeros such as `0E+30` included) and `int`s outside signed 64-bit are now
226
+ converted or refused before sending, in writes, filter values, `call_function()` arguments and
227
+ auth variables.
228
+ - A row holding a duration now loads into a top-level `timedelta` field (floored to the
229
+ microsecond) through `get()`, `filter()`, `all()`, `first()`, `raw_query()`, live and
230
+ change-feed events, model `signup()` and the rows `bulk_create()` returns; the field's validation
231
+ refused the SDK's duration.
232
+ - The live-filter `Decimal` literal decides huge exponents before formatting: a zero with a long
233
+ exponent is written without building its full text, and a value beyond Python's 4,300-digit
234
+ limit raises the documented `TypeError` instead of a `ValueError`.
235
+
236
+ ### Notes
237
+
238
+ - **Same on both lines**, measured on SurrealDB 2.7.0 and 3.3.4, with 3.1.5 where it differs,
239
+ except `TYPE set<…>` columns: on 3.3 such a column holds a native set that the surrealdb SDK
240
+ 2.0.0 cannot read (reads fail with an SDK decoding error), and 3.1 refuses the array. Declare
241
+ such columns `array<…>`, optionally with `VALUE $value.distinct()`. The README's "SurrealDB 2.6.x
242
+ vs 3.x" table gains these two rows and a retroactive one: on reads, 2.x keeps a `Decimal`'s
243
+ trailing zeros (`12.50`) where 3.x normalises them (`12.5`); the values are equal.
244
+ - **SDK 2.0.0 limits**: it cannot decode a zero duration or a SurrealDB 3.x native set. The ORM
245
+ never sends either, but a record another client wrote may hold one, and reading it fails with an
246
+ SDK decoding error. A later SDK lifts both (#205).
247
+ - **Filter values on rich fields must be typed**: strings are not converted, so
248
+ `filter(trial__gte="7d")` compares the stored duration with a string; pass `timedelta(days=7)`
249
+ (#220). Keyword writes (`merge(field=...)`, `bulk_update()`) are not validated against the
250
+ field's type (#221).
251
+ - **Precision**: `datetime` to the microsecond (the SDK truncates the server's nanoseconds);
252
+ `timedelta` floored to the microsecond on read; `Duration` exact. On reads, a `timedelta` below a
253
+ top-level field (`list[timedelta]`, a sub-model's field) fails validation as before: declare
254
+ `Duration` there.
255
+ - After a write that returns the row, `date`, `set` and `Range` fields hold the SDK's value (a
256
+ midnight `datetime`, a `list`, the SDK's `Range`) until the record is loaded again; writing such
257
+ an instance back is safe.
258
+ - **Equality with the SDK's values is one-way**: `Duration(5) == surrealdb.Duration(5)` is `True`,
259
+ the reverse is `False` (the SDK's `__eq__` answers `False` for any other type); the same holds
260
+ for `Range`. Keep the ORM value on the left.
261
+ - Tested against SurrealDB 3.3.4 and 2.7.0 (the CI pins), plus 3.1.5 for backward compatibility.
262
+
8
263
  ## [0.22.2] - 2026-10-13
9
264
 
10
265
  Change-feed fixes: history replayed by `changes(since=None)` on SurrealDB 3.x, and a timed-out