surreal-orm-lite 0.29.2__tar.gz → 0.30.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.29.2 → surreal_orm_lite-0.30.0}/CHANGELOG.md +186 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/PKG-INFO +375 -13
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/README.md +374 -12
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/pyproject.toml +1 -1
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/__init__.py +30 -1
- surreal_orm_lite-0.30.0/src/surreal_orm_lite/define_parser.py +2466 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/functions.py +10 -2
- surreal_orm_lite-0.30.0/src/surreal_orm_lite/introspection.py +453 -0
- surreal_orm_lite-0.30.0/src/surreal_orm_lite/model_generator.py +1284 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/query_set.py +227 -86
- surreal_orm_lite-0.30.0/src/surreal_orm_lite/schema_state.py +441 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/subquery.py +2 -6
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/.gitignore +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/LICENSE +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/Makefile +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/cache.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/model_base.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/routing.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/types.py +0 -0
- {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/utils.py +0 -0
|
@@ -5,6 +5,192 @@ 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.30.0] - 2026-10-19
|
|
9
|
+
|
|
10
|
+
Schema introspection: the ORM reads the schema of a database as immutable typed objects and
|
|
11
|
+
generates `BaseSurrealModel` classes from it, with the full SurrealDB-ORM's names. It only reads
|
|
12
|
+
(`INFO FOR DB`, `INFO FOR TABLE`), and the same schema gives the same state and the same generated
|
|
13
|
+
types on SurrealDB 2.x, 3.x and the embedded engine. The first minor of Tier 3.
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
|
|
17
|
+
- **`DatabaseIntrospector(connection=None, *, tables=None).introspect()`** returns a
|
|
18
|
+
`SchemaState`: the tables (`TableState`, with their `FieldState`, `IndexState` and `EventState`)
|
|
19
|
+
and the database's accesses (`AccessState`), analyzers (`AnalyzerState`), functions
|
|
20
|
+
(`FunctionState`, keyed `"fn::name"`) and params (`ParamState`). It sends `INFO FOR DB;`, then
|
|
21
|
+
one `INFO FOR TABLE` per table, outside any transaction: no record is read, nothing is defined or
|
|
22
|
+
written. A field is keyed by its path (`"address.city"`, `"tags.*"`), with `field_type` (its kind
|
|
23
|
+
without the optional wrapper), `nullable` (whether it may be `NONE`) and its expressions
|
|
24
|
+
(`default`, `value`, `computed`, `assertion`, permission rules) as SurrealQL text; every
|
|
25
|
+
definition keeps the server's statement in `raw`, and the sections the ORM does not model are in
|
|
26
|
+
`schema.other`. `connection=` is a connection name (else the current one: `using()`, then
|
|
27
|
+
`"default"`), and `tables=` reads those tables only.
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
from surreal_orm_lite import DatabaseIntrospector
|
|
31
|
+
|
|
32
|
+
schema = await DatabaseIntrospector().introspect()
|
|
33
|
+
person = schema.tables["person"]
|
|
34
|
+
person.fields["age"].field_type # 'int': option<int> on SurrealDB 2.x, none | int on 3.x
|
|
35
|
+
person.fields["age"].nullable # True
|
|
36
|
+
person.fields["age"].default # '18': SurrealQL text
|
|
37
|
+
person.indexes["person_name"].unique # True
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
- **`ModelCodeGenerator().generate(state)`** and
|
|
41
|
+
**`generate_models_from_db(output_path=None, connection=None, *, tables=None, overwrite=True)`**
|
|
42
|
+
give deterministic source with one class per table: a `BaseSurrealModel`, or a `BaseSurrealEdge`
|
|
43
|
+
for a `TYPE RELATION` table. Fields use the lite's types (`Duration`, `Decimal`, `UUID`,
|
|
44
|
+
`RecordID`, `Range`, the geometry classes, `Literal`), sub-models for declared nested fields,
|
|
45
|
+
`computed()` for `COMPUTED` and for a `VALUE` that reads neither `$value` nor `$input`, aliases
|
|
46
|
+
for columns that cannot be attribute names, `extra="allow"` for `SCHEMALESS` tables, and
|
|
47
|
+
`connection=` for a schema read from a named connection. A constant `DEFAULT` becomes the Python
|
|
48
|
+
default (`DEFAULT 18` → `= 18`, `[]` → `Field(default_factory=list)`, `1h30m` →
|
|
49
|
+
`Duration.parse("1h30m")`, `u'…'` → `UUID("…")`); any other `DEFAULT` becomes a `server_fields`
|
|
50
|
+
entry. Names, comments and expressions read from the database reach the source only as escaped
|
|
51
|
+
string literals, single-line comments and generated identifiers.
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
from surreal_orm_lite import generate_models_from_db
|
|
55
|
+
|
|
56
|
+
source = await generate_models_from_db() # the source, as a string
|
|
57
|
+
await generate_models_from_db("app/models_generated.py") # also writes it, replacing the file
|
|
58
|
+
await generate_models_from_db("app/models_generated.py", overwrite=False) # FileExistsError
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- **`generate_models_from_db()` replaces an existing file atomically**, as the full ORM replaces
|
|
62
|
+
it: the source goes to a temporary file in the same directory, then `os.replace()` moves it over
|
|
63
|
+
the file, so a failure leaves the previous file. `overwrite=False` refuses an existing path with
|
|
64
|
+
`FileExistsError` before reading anything.
|
|
65
|
+
- **The state classes take the full SurrealDB-ORM's arguments**: `SchemaState`, `TableState`,
|
|
66
|
+
`FieldState`, `IndexState`, `EventState`, `AccessState` and `AnalyzerState` are built by
|
|
67
|
+
position or by keyword as in the full ORM, and the lite's own attributes (`raw`, `path`, `table`,
|
|
68
|
+
`comment`, …) are keyword-only. They are frozen dataclasses with read-only maps and tuples, and
|
|
69
|
+
`repr()` shows names and structure only, never a definition's text. `FunctionState`,
|
|
70
|
+
`ParamState`, `SchemaIssue` and `tables=` are lite additions. The 13 names are exported from
|
|
71
|
+
`surreal_orm_lite`.
|
|
72
|
+
- **Nothing is guessed**: a definition that cannot be parsed exactly, a section of an unexpected
|
|
73
|
+
shape or a failed `INFO FOR TABLE` becomes a `SchemaIssue` in `schema.issues` and a WARNING on
|
|
74
|
+
the `surreal_orm_lite.introspection` logger, whose message never quotes the definition.
|
|
75
|
+
`introspect()` raises `SurrealDbAuthenticationError` when the session may not run
|
|
76
|
+
`INFO FOR DB`, `SurrealDbError` when it fails otherwise, and `SurrealDbNotFoundError` for a
|
|
77
|
+
`tables=` name the database does not define.
|
|
78
|
+
- README section 31, "Schema introspection (`DatabaseIntrospector`, `generate_models_from_db()`)"
|
|
79
|
+
(reading the schema, generating models, how SurrealDB kinds become fields, what the generator
|
|
80
|
+
does not do, SurrealDB 2.x and 3.x, permissions, a note for users of the full SurrealDB-ORM), a
|
|
81
|
+
features row, rows in the 2.x/3.x and embedded-engine behaviour tables, the comparison and
|
|
82
|
+
roadmap rows, and the example notebook `examples/v0.30.0_schema_introspection.ipynb`.
|
|
83
|
+
|
|
84
|
+
### Fixed
|
|
85
|
+
|
|
86
|
+
- **A stored function's parameter list is read in linear time** (`call_function()` with keyword
|
|
87
|
+
arguments, and now introspection): a long `DEFINE FUNCTION`, or one holding `` $` `` or `$⟨`
|
|
88
|
+
without a closing quote, no longer makes the reader copy or search the rest of the definition at
|
|
89
|
+
every `$`.
|
|
90
|
+
|
|
91
|
+
### Notes
|
|
92
|
+
|
|
93
|
+
- **Kinds and field paths are normalised, expressions are kept as rendered**: `option<int>` (2.x)
|
|
94
|
+
and `none | int` (3.x) both give `field_type == "int"` and `nullable is True`, and `tags[*]`
|
|
95
|
+
(2.x) and `tags.*` (3.x) both give the field `"tags.*"`. Expressions (`default`, `value`, `raw`,
|
|
96
|
+
a generated `computed("…")`) are kept as each line renders them and may differ:
|
|
97
|
+
`VALUE IF b THEN 1 ELSE 2 END` on 2.x is `VALUE (IF b THEN 1 ELSE 2 END)` on 3.x.
|
|
98
|
+
- **Definitions only one line has** are read and typed on that line: on 3.x `COMPUTED`,
|
|
99
|
+
`REFERENCE`, `FULLTEXT` indexes, the `file` kind, `WITH REFRESH` and `BEARER` accesses, and
|
|
100
|
+
`DEFINE SEQUENCE` (kept raw in `schema.other`); on 2.x and the embedded engine `MTREE` and
|
|
101
|
+
`SEARCH ANALYZER` indexes and `geometry<feature>`.
|
|
102
|
+
- **The `users` section is never read.** On SurrealDB before 3.2.2 (every 2.x release, 3.x before
|
|
103
|
+
3.2.2, and the embedded engine of SDK 2.0.0), `INFO FOR DB` shows user password hashes to every
|
|
104
|
+
role that may run `INFO`, per SurrealDB's `INFO` documentation; introspection never reads,
|
|
105
|
+
stores, logs or writes them. Introspection needs a system user (root, a namespace or a database
|
|
106
|
+
user): a record user or an anonymous session gets `SurrealDbAuthenticationError`, except on the
|
|
107
|
+
embedded engine, whose anonymous session owns the database.
|
|
108
|
+
- **Tables not generated**, listed in the module's header and still in `schema.tables`: a table
|
|
109
|
+
named like a SurrealQL keyword, in any case (`select`, `create`, `only`, …), and a table whose
|
|
110
|
+
name is not an identifier, which the ORM's statements cannot use as a table name.
|
|
111
|
+
- **`update()` and `READONLY` datetimes**: an instance holding a `READONLY` `datetime` field cannot
|
|
112
|
+
be changed with `update()`, after `get()` as after `save()`: Python keeps microseconds, SurrealDB
|
|
113
|
+
nanoseconds, and the server refuses the changed value. This predates v0.30.0; the generated class
|
|
114
|
+
says so: change such a record with `merge()`.
|
|
115
|
+
- **Sub-fields a `DEFAULT` fills**: a sub-field filled by a `DEFAULT` the model does not hold
|
|
116
|
+
(`prefs.at DEFAULT time::now()`, or any `DEFAULT` under a `dict[str, Any]` field) stays `None` on
|
|
117
|
+
the instance after `save()`, which reads back only `server_fields` and computed fields; a
|
|
118
|
+
following `update()` sends it as `NONE`: the server refuses it when the sub-field is required and
|
|
119
|
+
erases the value when it is optional. The generated class says so: call `refresh()` after
|
|
120
|
+
`save()` before an `update()`, or change the record with `merge()`.
|
|
121
|
+
- **Defaults are copied when the models are generated**: generate them again after changing a
|
|
122
|
+
`DEFAULT`. A value set on a `server_fields` field before `save()` is not written, as since
|
|
123
|
+
v0.18.0 and in the full ORM: set it with `merge()` once the record exists.
|
|
124
|
+
- `array<T, N>` becomes `list[T]`, leaving the length to the server (SurrealDB 2.x accepts at most
|
|
125
|
+
N items, 3.x exactly N); `null | T` becomes a required `T | None`, which the ORM sends as `NONE`
|
|
126
|
+
and `null | T` refuses: declare such a field `option<T>`. `ASSERT`, `PERMISSIONS` and field
|
|
127
|
+
comments are not generated, and `READONLY` is a comment. Never call `define_computed_fields()` on
|
|
128
|
+
a generated model.
|
|
129
|
+
- **Differences from the full SurrealDB-ORM**: the state is immutable, with tuples where the full
|
|
130
|
+
ORM has lists; permission values are `'FULL'`, `'NONE'` or `'WHERE <expr>'`; `default` is
|
|
131
|
+
SurrealQL text; `nullable` is false for `null | T`; accesses are database-level
|
|
132
|
+
(`schema.accesses`); a refused or failed `INFO FOR DB` raises and an unreadable definition
|
|
133
|
+
becomes a `SchemaIssue`; `connection=` is a name, and a client object raises `TypeError`;
|
|
134
|
+
generated models use comments for the `SurrealConfigDict` keys that arrive with v0.31.0–v0.33.0
|
|
135
|
+
(`table_type`, `permissions`, `changefeed`, `view_query`, `relation_in`, `relation_out`,
|
|
136
|
+
`enforced`); class names are not singularised. `schema_diff()` and `SchemaState.diff()` come with
|
|
137
|
+
v0.37.0 (migrations), the `inspectdb` command with v0.38.0 (CLI).
|
|
138
|
+
- **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine,
|
|
139
|
+
plus 3.1.5 for backward compatibility.
|
|
140
|
+
|
|
141
|
+
## [0.29.3] - 2026-10-18
|
|
142
|
+
|
|
143
|
+
`get_or_create()` and `update_or_create()` bind the queryset's `variables()` in their lookup, as
|
|
144
|
+
`filter()` does. No new public API.
|
|
145
|
+
|
|
146
|
+
### Fixed
|
|
147
|
+
|
|
148
|
+
- **`get_or_create()` and `update_or_create()` bind `variables()` in their lookup** (#252). The
|
|
149
|
+
lookup ran without the queryset's `variables()`, so a `Var` criterion read `NONE` there:
|
|
150
|
+
`variables(n=10).get_or_create(size__gte=Var("n"), …)` compared `size` with `NONE` and could
|
|
151
|
+
match a record the caller did not mean, which `update_or_create()` then updated, and
|
|
152
|
+
`variables(t="mine").get_or_create(title=Var("t"))` did not find the existing record. The lookup
|
|
153
|
+
now binds the queryset's `variables()`, merged with those of its subquery criteria as `filter()`
|
|
154
|
+
merges them (a subquery that binds one of these names to another value raises `ValueError`), on
|
|
155
|
+
SurrealDB 2.x, 3.x and the embedded engine.
|
|
156
|
+
- **An `exact` `Var` criterion naming a variable of `variables()` is written as that variable's
|
|
157
|
+
value on create** (#252), so the next identical call finds the record:
|
|
158
|
+
`variables(t="mine").get_or_create(title=Var("t"))` behaves as `get_or_create(title="mine")`. On
|
|
159
|
+
the record id and on an edge's `in` and `out`, it is compared as the record id its value names,
|
|
160
|
+
as the same criterion given that value is (`variables(a="person:alice")` with
|
|
161
|
+
`get_or_create(in_=Var("a"), out=bob)` finds or relates `person:alice`); a value that names no
|
|
162
|
+
record id there raises `ValueError` before any request. A model instance given to `variables()`
|
|
163
|
+
is bound and written as its record id, as the instance given as the criterion is; an unsaved one
|
|
164
|
+
raises `ValueError` before any request. An `exact` `Var` that names a session parameter
|
|
165
|
+
(`Var("auth")`) or no variable of `variables()` still raises `SurrealDbError` on create.
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
from surreal_orm_lite import Var
|
|
169
|
+
|
|
170
|
+
qs = Room.objects().variables(t="mine", n=10)
|
|
171
|
+
room, created = await qs.get_or_create(title=Var("t")) # as get_or_create(title="mine")
|
|
172
|
+
room, created = await qs.update_or_create(size__gte=Var("n"), title=Var("t"), defaults={"floor": 2})
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### Changed
|
|
176
|
+
|
|
177
|
+
- **Refusals of a `"$name"` criterion in `get_or_create()` and `update_or_create()`** (#252): a
|
|
178
|
+
string criterion that is exactly `$` followed by the name of a variable of a subquery criterion's
|
|
179
|
+
`variables()` now raises `SurrealDbError` too, like one naming a variable of the queryset's
|
|
180
|
+
`variables()`. For a variable, the message names `Var('x')` as the criterion to write, under any
|
|
181
|
+
lookup but `like`/`ilike`, which take no `Var` (pass the pattern itself, or use `regex`). For a
|
|
182
|
+
session parameter, it says to pass the actual value under `exact`, and that `Var('auth')` works
|
|
183
|
+
under any other lookup but `like`/`ilike`, which take no `Var` (pass the pattern itself, or use
|
|
184
|
+
`regex`): `members__contains=Var("auth")` is looked up, never written. On the `id` column it names
|
|
185
|
+
the record id `table:⟨$name⟩` the string would be.
|
|
186
|
+
|
|
187
|
+
### Deprecated
|
|
188
|
+
|
|
189
|
+
- The `"$$"` escape of a string filter value, deprecated since v0.28.1 (#250) and listed there
|
|
190
|
+
under Changed: a string filter value starting with `$$` loses one `$` (`"$$admin"` finds
|
|
191
|
+
`"$admin"`) and emits a `DeprecationWarning`. A string filter value is always data, so write the
|
|
192
|
+
value with one `$` less. An item of an `in` list never had the escape and is unchanged.
|
|
193
|
+
|
|
8
194
|
## [0.29.2] - 2026-10-18
|
|
9
195
|
|
|
10
196
|
The text lookups `startswith`, `endswith`, `like`, `ilike`, `match` and `regex` work: each compiles
|