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.
Files changed (29) hide show
  1. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/CHANGELOG.md +168 -0
  2. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/PKG-INFO +640 -152
  3. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/README.md +638 -151
  4. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/pyproject.toml +2 -1
  5. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/__init__.py +3 -1
  6. surreal_orm_lite-0.22.0/src/surreal_orm_lite/edge.py +295 -0
  7. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/live.py +11 -2
  8. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/model_base.py +660 -128
  9. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/q.py +10 -3
  10. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/query_set.py +78 -19
  11. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/utils.py +131 -10
  12. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/.gitignore +0 -0
  13. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/LICENSE +0 -0
  14. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/Makefile +0 -0
  15. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/_sdk.py +0 -0
  16. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/aggregations.py +0 -0
  17. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/auth.py +0 -0
  18. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/changefeed.py +0 -0
  19. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/concurrency.py +0 -0
  20. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/connection_manager.py +0 -0
  21. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/constants.py +0 -0
  22. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/enum.py +0 -0
  23. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/exceptions.py +0 -0
  24. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/functions.py +0 -0
  25. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/model_auth.py +0 -0
  26. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/py.typed +0 -0
  27. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/signals.py +0 -0
  28. {surreal_orm_lite-0.21.0 → surreal_orm_lite-0.22.0}/src/surreal_orm_lite/surql_literal.py +0 -0
  29. {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