surreal-orm-lite 0.21.0__tar.gz → 0.22.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.21.0 → surreal_orm_lite-0.22.0}/CHANGELOG.md +168 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/PKG-INFO +640 -152
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/README.md +638 -151
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/pyproject.toml +2 -1
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/__init__.py +3 -1
- surreal_orm_lite-0.22.0/src/surreal_orm_lite/edge.py +295 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/live.py +11 -2
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/model_base.py +660 -128
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/q.py +10 -3
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/query_set.py +78 -19
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/utils.py +131 -10
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/.gitignore +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/LICENSE +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/Makefile +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/transaction.py +0 -0
|
@@ -5,6 +5,174 @@ 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.22.0] - 2026-10-12
|
|
9
|
+
|
|
10
|
+
Native typed relations: graph edges as Pydantic models, created through the official SDK's
|
|
11
|
+
`insert_relation()` and returned as typed instances, with the full SurrealDB-ORM's graph API on
|
|
12
|
+
both server lines. The last minor of Tier 1.
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- **Typed edges — `BaseSurrealEdge`**. An edge table becomes a model whose data is validated by
|
|
17
|
+
Pydantic, with frozen `in_` (column `in`) and `out` record endpoints that accept a saved
|
|
18
|
+
instance, a `RecordID` or a `"table:id"` string. `relate()` takes the edge class and returns the
|
|
19
|
+
created edge:
|
|
20
|
+
|
|
21
|
+
```python
|
|
22
|
+
from pydantic import Field
|
|
23
|
+
from surrealdb import RecordID
|
|
24
|
+
from surreal_orm_lite import BaseSurrealEdge, SurrealConfigDict
|
|
25
|
+
|
|
26
|
+
class Purchased(BaseSurrealEdge):
|
|
27
|
+
model_config = SurrealConfigDict(table_name="purchased")
|
|
28
|
+
quantity: int = Field(ge=1)
|
|
29
|
+
price: float
|
|
30
|
+
|
|
31
|
+
edge = await alice.relate(Purchased, widget, quantity=2, price=9.5)
|
|
32
|
+
assert isinstance(edge, Purchased) and edge.in_ == RecordID("User", "alice")
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
`relate()` is typed with two overloads: the edge class for an edge model, `list[dict]` for a
|
|
36
|
+
table name (the v0.6.0 form, unchanged).
|
|
37
|
+
|
|
38
|
+
- **Edge `save()` and `QuerySet.bulk_create()` through `insert_relation()`** — a real relation that
|
|
39
|
+
graph traversal sees, `id` hydrated from the returned row; `bulk_create()` of N edges without an
|
|
40
|
+
id is one `insert_relation()` call. An explicit edge id that already exists raises
|
|
41
|
+
`SurrealDbError` ("already exists") and writes nothing, on every measured version.
|
|
42
|
+
- **Edges in transactions**: `save(tx=)`, `relate(Edge, …, tx=)` and `bulk_create()` under
|
|
43
|
+
`objects(tx=)`, interactive (3.x over WebSocket) and buffered (2.x, or HTTP); an auto-id edge is
|
|
44
|
+
allowed in a buffered transaction (its `id` stays `None` until the commit).
|
|
45
|
+
- **`get_or_create(in_=a, out=b)` on an edge model** is an idempotent relate; instances,
|
|
46
|
+
`RecordID`s and `"table:id"` strings converge on the same row.
|
|
47
|
+
- **`SurrealConfigDict(table_name=…)`** — the full ORM's key for a model's table name, honoured by
|
|
48
|
+
every path (writes, reads, `QuerySet`, live queries, change feeds, DDL helpers) and validated as
|
|
49
|
+
an identifier when the class is defined.
|
|
50
|
+
- **Model instances as filter values**, for every model and column: keyword filters, `Q`, every
|
|
51
|
+
scalar lookup and each item of `in`/`not_in`/`containsany`/`containsall`. The create payload of
|
|
52
|
+
`get_or_create`/`update_or_create` gets the same conversion, so
|
|
53
|
+
`Order.objects().get_or_create(customer=alice)` stores a record id.
|
|
54
|
+
- **`"table:id"` strings on edge endpoint columns** in filters (`filter(in_="User:alice")`,
|
|
55
|
+
`filter(in___in=[alice, "User:bob"])`), live queries included.
|
|
56
|
+
- **Graph helpers in the full SurrealDB-ORM's parameter order**, by position or by keyword:
|
|
57
|
+
`relate(edge, target, reverse, tx)`, `remove_relation(edge, target, reverse, tx)`,
|
|
58
|
+
`remove_all_relations(edge, direction, tx)`, `get_related(edge, direction, model_class)`; only
|
|
59
|
+
the lite's `data=` stays keyword-only. With them:
|
|
60
|
+
- `reverse=True` on `relate()` and `remove_relation()` (target → edge → self);
|
|
61
|
+
- edge fields as keyword arguments on `relate()` (`**edge_data`), merged with `data=` (a field
|
|
62
|
+
given both ways raises `TypeError` before any call);
|
|
63
|
+
- `tx=` on `relate()`, `remove_relation()` and `remove_all_relations()`;
|
|
64
|
+
- edge model classes accepted wherever an edge name is, in every helper;
|
|
65
|
+
- a list or tuple of edges for `remove_all_relations()`;
|
|
66
|
+
- `get_related(direction="both")`: out-neighbours, then in-neighbours, in one query;
|
|
67
|
+
- a bare record id as `remove_relation()` target (`"abc123"`): compared as a string with the id
|
|
68
|
+
of the edge's `out` (`in` with `reverse=True`), it matches that id in any table, as in
|
|
69
|
+
SurrealDB-ORM. Pass an instance or a `RecordID` to pin the table.
|
|
70
|
+
- `BaseSurrealEdge` is exported from the package root.
|
|
71
|
+
- README section 23, "Typed edges (`BaseSurrealEdge`)", with "Idempotent edges" (a deterministic
|
|
72
|
+
array id, a `UNIQUE` index on `in, out`) and a "Migrating from SurrealDB-ORM (graph API)" note;
|
|
73
|
+
example notebook `examples/v0.22.0_native_typed_relations.ipynb`.
|
|
74
|
+
|
|
75
|
+
### Changed
|
|
76
|
+
|
|
77
|
+
- **`QuerySet` reads the table from `get_table_name()`**, so a model with the legacy
|
|
78
|
+
`_table_name` now writes to that table too; before, writes went to the class-name table while
|
|
79
|
+
`objects()` read the other one.
|
|
80
|
+
- **`remove_relation()` and `remove_all_relations()` run a graph-path `DELETE`** with bound record
|
|
81
|
+
ids: exactly the edges a traversal sees. A plain record that merely carries `in`/`out` fields is
|
|
82
|
+
no longer matched, and an edge table that was never created is a native no-op on 3.x too, also
|
|
83
|
+
inside a transaction.
|
|
84
|
+
- `relate()` (with an edge class or a table name), `get_related()`, `remove_relation()`,
|
|
85
|
+
`remove_all_relations()` and `traverse()` accept a node whose record id is not an identifier
|
|
86
|
+
(`joe@x.com`).
|
|
87
|
+
- **Writes that would change an edge's endpoints are refused** with `ValueError` before any call
|
|
88
|
+
(`merge()`, `patch()` on the instance and the `QuerySet`, the `atomic_*` helpers,
|
|
89
|
+
`bulk_update()`, `update_or_create(defaults=)`): SurrealDB silently ignores them on both lines.
|
|
90
|
+
Delete the edge and relate again.
|
|
91
|
+
- **`upsert()` and `save(server_values=)` are refused on an edge** with `SurrealDbError`: an
|
|
92
|
+
`UPSERT` stores a plain record that no traversal sees, and `INSERT RELATION` cannot evaluate
|
|
93
|
+
`SET` expressions.
|
|
94
|
+
- An edge write refused by the table's `PERMISSIONS` raises `SurrealDbError`; the server answers it
|
|
95
|
+
with fewer rows and no error.
|
|
96
|
+
|
|
97
|
+
### Deprecated
|
|
98
|
+
|
|
99
|
+
- `_table_name` — use `model_config = SurrealConfigDict(table_name=…)`. It still works and emits a
|
|
100
|
+
`DeprecationWarning` when the class is defined (`table_name` wins when both are set); it will be
|
|
101
|
+
removed in a future minor.
|
|
102
|
+
|
|
103
|
+
### Fixed
|
|
104
|
+
|
|
105
|
+
- `SurrealConfigDict` keys are optional for type checkers (`total=False`).
|
|
106
|
+
- Filter keys on a field ending in `_` (`type___gt`, `in___in`) no longer raise
|
|
107
|
+
"Unsupported lookup".
|
|
108
|
+
- `relate(<non-str>, …)` raises `TypeError` instead of `AttributeError`.
|
|
109
|
+
- A single model instance given to a sequence lookup (`customer__in=alice`) raises `ValueError`
|
|
110
|
+
instead of being read as a list of `(name, value)` pairs.
|
|
111
|
+
- `save(tx=)`, `upsert()`, `update(tx=)` and `delete(tx=)` bind the record id instead of writing
|
|
112
|
+
it into the statement, so a record with an array id (such as `pair:[User:alice, User:bob]`) can
|
|
113
|
+
be saved, updated or deleted in a transaction and upserted in or out of one; before, the
|
|
114
|
+
statement failed to parse on both lines, and inside a transaction it failed the whole
|
|
115
|
+
transaction.
|
|
116
|
+
|
|
117
|
+
### Security
|
|
118
|
+
|
|
119
|
+
- Record ids are bound as query parameters instead of being written into the statement as
|
|
120
|
+
`table:id` text: `save(tx=)`, `upsert()`, `update(tx=)`, `delete(tx=)`, `relate()` (with an edge
|
|
121
|
+
class or a table name), `get_related()`, `remove_relation()`, `remove_all_relations()` and
|
|
122
|
+
`traverse()`. The only text written into these statements is identifiers validated before any
|
|
123
|
+
call: the table name (`table_name`, checked when the class is defined), edge names (every item
|
|
124
|
+
of a list), field names and the `traverse()` path.
|
|
125
|
+
- An edge write denied by the table's permissions can never look like a success (see Changed).
|
|
126
|
+
|
|
127
|
+
### Notes
|
|
128
|
+
|
|
129
|
+
- **A duplicate explicit edge id differs by version, and the ORM evens it out.** A raw
|
|
130
|
+
`INSERT RELATION` with an id that already exists silently keeps the old edge on 2.7.0 and on
|
|
131
|
+
3.1.5 (although the SurrealDB docs announce a record-exists error from 3.1.5), and raises
|
|
132
|
+
`AlreadyExistsError` on 3.3.3. The ORM sends a guarded statement, so it raises "already exists"
|
|
133
|
+
and writes nothing on all three; inside a buffered transaction the commit fails.
|
|
134
|
+
- On 2.x, the edge record of a `CREATE`/`UPDATE` live notification or of a change-feed update entry
|
|
135
|
+
carries `"__": true`. The typed `instance` drops it, so it is identical on both lines;
|
|
136
|
+
`ModelChangeEvent.raw` stays as the server sent it.
|
|
137
|
+
- A batch of edges partly refused by permissions stays partly written outside a transaction.
|
|
138
|
+
- Idempotent edges: `get_or_create()` has a race window between two concurrent callers; a
|
|
139
|
+
deterministic array id or a `UNIQUE` index on `in, out` closes it server-side, on both lines
|
|
140
|
+
(README section 23).
|
|
141
|
+
- Schema-level relation tables (`DEFINE TABLE … TYPE RELATION IN … OUT …`) are defined by hand for
|
|
142
|
+
now; the DDL helper, with the full ORM's `table_type`/`relation_in`/`relation_out` keys on
|
|
143
|
+
`BaseSurrealEdge`, is planned for v0.33.0.
|
|
144
|
+
- Every behaviour above was measured on SurrealDB 2.7.0 and 3.3.3, with 3.1.5 where it differs;
|
|
145
|
+
the README's "ORM behaviour: SurrealDB 2.x vs 3.x" table gains fifteen rows, one of them
|
|
146
|
+
retroactive (since v0.7.0: an undeclared field on a `SCHEMAFULL` table).
|
|
147
|
+
|
|
148
|
+
## [0.21.1] - 2026-10-12
|
|
149
|
+
|
|
150
|
+
Python 3.15 support. No library code changes; the published package behaves exactly as 0.21.0.
|
|
151
|
+
|
|
152
|
+
### Added
|
|
153
|
+
|
|
154
|
+
- **Python 3.15** (#206). The CI matrix runs the full suite on Python 3.11 to 3.15 against both
|
|
155
|
+
SurrealDB lines, the package declares the `Programming Language :: Python :: 3.15`
|
|
156
|
+
classifier, and the README's requirements table states the tested range. Lint and the
|
|
157
|
+
coverage upload stay on 3.14.
|
|
158
|
+
|
|
159
|
+
### Changed
|
|
160
|
+
|
|
161
|
+
- **`uv.lock` refreshed so the development environment installs from wheels on Python 3.15.**
|
|
162
|
+
Only the locked packages with no CPython 3.15 wheel, or only a pure-Python fallback, were
|
|
163
|
+
upgraded, plus those that follow from their new floors: aiohttp 3.14.5, cffi 2.1.1,
|
|
164
|
+
charset-normalizer 3.5.2, coverage 7.16.2, debugpy 1.8.22, markupsafe 3.0.4, propcache
|
|
165
|
+
0.5.4, pydantic 2.14.1 (pydantic-core 2.50.1), tomli 2.5.0, typing-extensions 4.16.0,
|
|
166
|
+
typing-inspection 0.4.4, websockets 17.2 and yarl 1.25.1.
|
|
167
|
+
|
|
168
|
+
### Notes
|
|
169
|
+
|
|
170
|
+
- **The dependency ranges in `pyproject.toml` are unchanged** (`pydantic>=2.13.4`,
|
|
171
|
+
`surrealdb[pydantic]>=2.0.0,<3.0.0`), so this release changes nothing in what your
|
|
172
|
+
environment resolves; the lock only pins what CI and contributors install. The full suite
|
|
173
|
+
passes on the refreshed lock, pydantic 2.14 and websockets 17 (the SDK's WebSocket transport)
|
|
174
|
+
included, on SurrealDB 2.7.0 and 3.3.3.
|
|
175
|
+
|
|
8
176
|
## [0.21.0] - 2026-10-12
|
|
9
177
|
|
|
10
178
|
Live queries that survive a dropped connection, and change feeds with a cursor that resumes
|