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.
Files changed (46) hide show
  1. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/CHANGELOG.md +186 -0
  2. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/PKG-INFO +375 -13
  3. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/README.md +374 -12
  4. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/__init__.py +30 -1
  6. surreal_orm_lite-0.30.0/src/surreal_orm_lite/define_parser.py +2466 -0
  7. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/functions.py +10 -2
  8. surreal_orm_lite-0.30.0/src/surreal_orm_lite/introspection.py +453 -0
  9. surreal_orm_lite-0.30.0/src/surreal_orm_lite/model_generator.py +1284 -0
  10. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/query_set.py +227 -86
  11. surreal_orm_lite-0.30.0/src/surreal_orm_lite/schema_state.py +441 -0
  12. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/subquery.py +2 -6
  13. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/.gitignore +0 -0
  14. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/LICENSE +0 -0
  15. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/Makefile +0 -0
  16. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/_sdk.py +0 -0
  17. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/aggregations.py +0 -0
  18. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/auth.py +0 -0
  19. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/cache.py +0 -0
  20. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/changefeed.py +0 -0
  21. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/concurrency.py +0 -0
  22. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/connection_config.py +0 -0
  23. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/connection_manager.py +0 -0
  24. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/constants.py +0 -0
  25. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/decoding.py +0 -0
  26. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/edge.py +0 -0
  27. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/embedded.py +0 -0
  28. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/encoding.py +0 -0
  29. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/enum.py +0 -0
  30. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/exceptions.py +0 -0
  31. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/geo.py +0 -0
  32. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/live.py +0 -0
  33. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/model_auth.py +0 -0
  34. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/model_base.py +0 -0
  35. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/py.typed +0 -0
  36. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/q.py +0 -0
  37. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/routing.py +0 -0
  38. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/signals.py +0 -0
  39. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/surql_literal.py +0 -0
  40. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
  41. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/testing/database.py +0 -0
  42. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  43. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/time_travel.py +0 -0
  44. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/transaction.py +0 -0
  45. {surreal_orm_lite-0.29.2 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/types.py +0 -0
  46. {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