surreal-orm-lite 0.23.0__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.
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/CHANGELOG.md +110 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/PKG-INFO +422 -13
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/README.md +421 -12
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/pyproject.toml +1 -1
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/__init__.py +42 -1
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/_sdk.py +36 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/constants.py +9 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/encoding.py +205 -2
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/exceptions.py +27 -4
- surreal_orm_lite-0.24.0/src/surreal_orm_lite/geo.py +1291 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/model_base.py +29 -13
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/query_set.py +254 -23
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/surql_literal.py +29 -2
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/utils.py +39 -2
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/.gitignore +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/LICENSE +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/Makefile +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.23.0 → surreal_orm_lite-0.24.0}/src/surreal_orm_lite/types.py +0 -0
|
@@ -5,6 +5,116 @@ 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
|
+
|
|
8
118
|
## [0.23.0] - 2026-10-14
|
|
9
119
|
|
|
10
120
|
Rich field types: `timedelta`, `date`, sets and the ORM's own `Duration` and `Range[T]` are stored
|