surreal-orm-lite 0.30.7__tar.gz → 0.30.8__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.30.7 → surreal_orm_lite-0.30.8}/CHANGELOG.md +48 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/PKG-INFO +20 -13
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/README.md +19 -12
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/pyproject.toml +1 -1
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/cache.py +21 -19
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/changefeed.py +6 -6
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/connection_manager.py +33 -32
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/define_parser.py +35 -34
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/edge.py +2 -2
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/embedded.py +9 -7
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/functions.py +1 -1
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/introspection.py +58 -27
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/live.py +1 -1
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/model_base.py +2 -2
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/model_generator.py +100 -63
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/query_set.py +44 -43
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/routing.py +13 -13
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/schema_state.py +2 -1
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/subquery.py +27 -26
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/testing/database.py +1 -1
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/time_travel.py +19 -18
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/types.py +5 -5
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/utils.py +4 -4
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/.gitignore +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/LICENSE +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/Makefile +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/transaction.py +0 -0
|
@@ -5,6 +5,54 @@ 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.8] - 2026-10-19
|
|
9
|
+
|
|
10
|
+
Follow-ups to the v0.30.0 schema introspection (#260): a connection lost while the schema is read
|
|
11
|
+
raises instead of becoming schema issues, a relation table is an edge whatever the case of its
|
|
12
|
+
`table_type`, and generated classes carry the change feed and permissions comments the v0.30.0
|
|
13
|
+
notes described. No new public API.
|
|
14
|
+
|
|
15
|
+
### Fixed
|
|
16
|
+
|
|
17
|
+
- **A connection lost during `introspect()` raises** (#260). Every error of an `INFO FOR TABLE`
|
|
18
|
+
became a `SchemaIssue`, so a connection that dropped after `INFO FOR DB` turned every remaining
|
|
19
|
+
table into "could not be read": `introspect()` returned normally, and
|
|
20
|
+
`generate_models_from_db(path)` replaced a working module with one that listed those tables as
|
|
21
|
+
skipped. Only the server's answer to `INFO FOR TABLE` is an issue now; the transport's error, or
|
|
22
|
+
the ORM's, propagates unchanged before anything is written, so an existing file is left as it
|
|
23
|
+
was.
|
|
24
|
+
- **A relation table is an edge whatever the case of its `table_type`** (#260). The generator
|
|
25
|
+
compared `table_type` with exact case in two places and ignored case in a third: a hand-built
|
|
26
|
+
`TableState(table_type="RELATION")` gave a `BaseSurrealEdge` class that declared `in_` and `out`
|
|
27
|
+
again, and the module failed to import with a `TypeError`. States read by `DatabaseIntrospector`
|
|
28
|
+
hold `"relation"` and were not affected.
|
|
29
|
+
- **Generated classes comment their change feed and permissions** (#260), as the v0.30.0 notes
|
|
30
|
+
said: `# Changefeed: 1d INCLUDE ORIGINAL` and
|
|
31
|
+
`# Permissions: FOR select WHERE $auth.id = owner, FOR create, update FULL, FOR delete NONE`,
|
|
32
|
+
grouped the way SurrealDB renders them (`# Permissions: FULL` when `FULL` covers the four
|
|
33
|
+
operations). A table left at the default `PERMISSIONS NONE`, all four operations `NONE`, gets no
|
|
34
|
+
permissions comment. The database still applies both; the `SurrealConfigDict` keys for them
|
|
35
|
+
arrive with v0.31.0–v0.33.0. Unlike what those notes listed, `table_type` is not a comment: it
|
|
36
|
+
shows through the base class, `BaseSurrealEdge` for a relation table.
|
|
37
|
+
|
|
38
|
+
### Changed
|
|
39
|
+
|
|
40
|
+
- **An `INFO FOR TABLE` refused after `INFO FOR DB` succeeded raises
|
|
41
|
+
`SurrealDbAuthenticationError`** (#260) instead of becoming a `SchemaIssue`: the session lost its
|
|
42
|
+
rights while the schema was read (for example a client closed and reopened anonymously), and the
|
|
43
|
+
table is not at fault. A refused `INFO FOR DB` raises the same error, as in v0.30.0.
|
|
44
|
+
|
|
45
|
+
### Notes
|
|
46
|
+
|
|
47
|
+
- Docstrings and comments no longer cite internal design-note ids: they name the exception raised,
|
|
48
|
+
the case refused or the README section that documents it. README section 31 describes the new
|
|
49
|
+
class comments and which `INFO FOR TABLE` failures are schema issues.
|
|
50
|
+
- The linear-time tests of the definition parser keep the fastest of up to three timings, so a
|
|
51
|
+
pause of a shared CI runner cannot fail them.
|
|
52
|
+
- Same behaviour on SurrealDB 2.x, 3.x and the embedded engine. Server pins unchanged: tested
|
|
53
|
+
against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine, plus 3.1.5 for backward
|
|
54
|
+
compatibility.
|
|
55
|
+
|
|
8
56
|
## [0.30.7] - 2026-10-19
|
|
9
57
|
|
|
10
58
|
An instance stays in step with its stored row (#261): `save()` applies the whole row the server
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: surreal-orm-lite
|
|
3
|
-
Version: 0.30.
|
|
3
|
+
Version: 0.30.8
|
|
4
4
|
Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
|
|
5
5
|
Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
|
|
6
6
|
Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
|
|
@@ -4187,11 +4187,14 @@ schema.issues # (): everything was read and parsed
|
|
|
4187
4187
|
logging a state shows names and structure only: definition texts stay in their attributes, out of `repr()` and
|
|
4188
4188
|
`str()`.
|
|
4189
4189
|
- Nothing is guessed. A definition that cannot be parsed exactly, a section of an unexpected shape or an
|
|
4190
|
-
`INFO FOR TABLE`
|
|
4191
|
-
`statement`) and one WARNING on the `surreal_orm_lite.introspection` logger; `introspect()`
|
|
4192
|
-
An issue's message never quotes the definition, which may hold a secret.
|
|
4193
|
-
- Errors: `SurrealDbAuthenticationError` when the session may not run `INFO FOR DB`,
|
|
4194
|
-
`INFO FOR
|
|
4190
|
+
`INFO FOR TABLE` the server answers with an error becomes a `SchemaIssue` in `schema.issues` (its `kind`, `name`,
|
|
4191
|
+
`table`, `message` and `statement`) and one WARNING on the `surreal_orm_lite.introspection` logger; `introspect()`
|
|
4192
|
+
does not raise for them. An issue's message never quotes the definition, which may hold a secret.
|
|
4193
|
+
- Errors: `SurrealDbAuthenticationError` when the session may not run `INFO FOR DB`, or is refused an
|
|
4194
|
+
`INFO FOR TABLE` after `INFO FOR DB` succeeded (it lost its rights meanwhile); `SurrealDbError` when `INFO FOR DB`
|
|
4195
|
+
fails otherwise; and `SurrealDbNotFoundError` for a `tables=` name the database does not define. A connection lost
|
|
4196
|
+
during the read is not an issue: the transport's error (or the ORM's) propagates unchanged, so
|
|
4197
|
+
`generate_models_from_db()` never replaces a file with models of tables it could not read.
|
|
4195
4198
|
|
|
4196
4199
|
```python
|
|
4197
4200
|
SurrealDBConnectionManager.add_connection("archive", url="mem://", namespace="shop", database="archive")
|
|
@@ -4266,8 +4269,10 @@ class Person(BaseSurrealModel):
|
|
|
4266
4269
|
model declares `id: str | None = None` first, then one line per field, in codepoint order of the columns.
|
|
4267
4270
|
- A class is named after its table in PascalCase, without singularisation (`game_tables` → `GameTables`); a name
|
|
4268
4271
|
that is taken — a Python keyword, a name the module imports, another table's class — gets `Model` appended (`range`
|
|
4269
|
-
→ `RangeModel`). The table's comment, relation ends, view query,
|
|
4270
|
-
|
|
4272
|
+
→ `RangeModel`). The table's comment, relation ends, view query, change feed (`# Changefeed: 1d`), permissions
|
|
4273
|
+
(`# Permissions: FOR select WHERE …, FOR create, update FULL, FOR delete NONE`, left out when all four are `NONE`,
|
|
4274
|
+
a table's default), indexes and events are comments of its class, and the module's header lists every table or
|
|
4275
|
+
field left out, with the reason.
|
|
4271
4276
|
- The source is safe to import: names, comments and expressions read from the database reach it only as escaped
|
|
4272
4277
|
string literals, single-line ASCII comments and identifiers the generator builds, so a schema cannot inject code
|
|
4273
4278
|
into it. It holds no timestamp, server address, namespace or database name, and no
|
|
@@ -4344,8 +4349,9 @@ class Person(BaseSurrealModel):
|
|
|
4344
4349
|
|
|
4345
4350
|
- It reads no record: a `SCHEMALESS` table's model holds the fields the table declares (with `extra="allow"`), and an
|
|
4346
4351
|
object-literal kind (`{ a: int }`) stays a `dict[str, Any]`.
|
|
4347
|
-
- `ASSERT`, `PERMISSIONS`, `REFERENCE` (the field is a `RecordID`) and
|
|
4348
|
-
|
|
4352
|
+
- A field's `ASSERT`, `PERMISSIONS`, `REFERENCE` (the field is a `RecordID`) and comment are not generated, and a
|
|
4353
|
+
table's permissions and change feed are only comments of its class: the database still applies them. `READONLY` is
|
|
4354
|
+
a trailing `# READONLY` comment: no field option exists for it.
|
|
4349
4355
|
- `update()` may fail on an instance holding a `READONLY` datetime below the top level, in a sub-model (`address.at`),
|
|
4350
4356
|
a `tuple`, an array (`array<datetime>`, `items.*.at`) or a set, after `get()` as after `save()`: Python keeps
|
|
4351
4357
|
microseconds, SurrealDB nanoseconds, and the server refuses the changed value. `update()` keeps the top-level
|
|
@@ -4442,9 +4448,10 @@ reads, stores, logs or writes them.
|
|
|
4442
4448
|
ORM's connection name, which routing, reconnects and the generated models' `connection=` key need (full ORM: an
|
|
4443
4449
|
`HTTPConnection`).
|
|
4444
4450
|
- **Generated models use comments** where the full ORM writes
|
|
4445
|
-
`SurrealConfigDict(
|
|
4446
|
-
|
|
4447
|
-
`
|
|
4451
|
+
`SurrealConfigDict(permissions=…, changefeed=…, view_query=…, relation_in=…, relation_out=…, enforced=…)`
|
|
4452
|
+
(`# Permissions: …`, `# Changefeed: …`, `# View: AS …`, `# IN … OUT … ENFORCED`), and the base class where it writes
|
|
4453
|
+
`table_type=` (`BaseSurrealEdge` for a relation table): those keys arrive in the lite's `SurrealConfigDict` with
|
|
4454
|
+
v0.31.0–v0.33.0. `READONLY` is a comment too (full ORM: `Field(readonly=True)`).
|
|
4448
4455
|
- **`RecordID` instead of `ForeignKey`/`ReferencesField`**; no `VectorField` or `Encrypted`; `computed()` instead
|
|
4449
4456
|
of `Computed()`; `Duration`, `UUID`, `Decimal` and the geometry classes instead of `str`, `dict` and `float`;
|
|
4450
4457
|
nested fields become sub-models (full ORM: dotted attribute lines).
|
|
@@ -4136,11 +4136,14 @@ schema.issues # (): everything was read and parsed
|
|
|
4136
4136
|
logging a state shows names and structure only: definition texts stay in their attributes, out of `repr()` and
|
|
4137
4137
|
`str()`.
|
|
4138
4138
|
- Nothing is guessed. A definition that cannot be parsed exactly, a section of an unexpected shape or an
|
|
4139
|
-
`INFO FOR TABLE`
|
|
4140
|
-
`statement`) and one WARNING on the `surreal_orm_lite.introspection` logger; `introspect()`
|
|
4141
|
-
An issue's message never quotes the definition, which may hold a secret.
|
|
4142
|
-
- Errors: `SurrealDbAuthenticationError` when the session may not run `INFO FOR DB`,
|
|
4143
|
-
`INFO FOR
|
|
4139
|
+
`INFO FOR TABLE` the server answers with an error becomes a `SchemaIssue` in `schema.issues` (its `kind`, `name`,
|
|
4140
|
+
`table`, `message` and `statement`) and one WARNING on the `surreal_orm_lite.introspection` logger; `introspect()`
|
|
4141
|
+
does not raise for them. An issue's message never quotes the definition, which may hold a secret.
|
|
4142
|
+
- Errors: `SurrealDbAuthenticationError` when the session may not run `INFO FOR DB`, or is refused an
|
|
4143
|
+
`INFO FOR TABLE` after `INFO FOR DB` succeeded (it lost its rights meanwhile); `SurrealDbError` when `INFO FOR DB`
|
|
4144
|
+
fails otherwise; and `SurrealDbNotFoundError` for a `tables=` name the database does not define. A connection lost
|
|
4145
|
+
during the read is not an issue: the transport's error (or the ORM's) propagates unchanged, so
|
|
4146
|
+
`generate_models_from_db()` never replaces a file with models of tables it could not read.
|
|
4144
4147
|
|
|
4145
4148
|
```python
|
|
4146
4149
|
SurrealDBConnectionManager.add_connection("archive", url="mem://", namespace="shop", database="archive")
|
|
@@ -4215,8 +4218,10 @@ class Person(BaseSurrealModel):
|
|
|
4215
4218
|
model declares `id: str | None = None` first, then one line per field, in codepoint order of the columns.
|
|
4216
4219
|
- A class is named after its table in PascalCase, without singularisation (`game_tables` → `GameTables`); a name
|
|
4217
4220
|
that is taken — a Python keyword, a name the module imports, another table's class — gets `Model` appended (`range`
|
|
4218
|
-
→ `RangeModel`). The table's comment, relation ends, view query,
|
|
4219
|
-
|
|
4221
|
+
→ `RangeModel`). The table's comment, relation ends, view query, change feed (`# Changefeed: 1d`), permissions
|
|
4222
|
+
(`# Permissions: FOR select WHERE …, FOR create, update FULL, FOR delete NONE`, left out when all four are `NONE`,
|
|
4223
|
+
a table's default), indexes and events are comments of its class, and the module's header lists every table or
|
|
4224
|
+
field left out, with the reason.
|
|
4220
4225
|
- The source is safe to import: names, comments and expressions read from the database reach it only as escaped
|
|
4221
4226
|
string literals, single-line ASCII comments and identifiers the generator builds, so a schema cannot inject code
|
|
4222
4227
|
into it. It holds no timestamp, server address, namespace or database name, and no
|
|
@@ -4293,8 +4298,9 @@ class Person(BaseSurrealModel):
|
|
|
4293
4298
|
|
|
4294
4299
|
- It reads no record: a `SCHEMALESS` table's model holds the fields the table declares (with `extra="allow"`), and an
|
|
4295
4300
|
object-literal kind (`{ a: int }`) stays a `dict[str, Any]`.
|
|
4296
|
-
- `ASSERT`, `PERMISSIONS`, `REFERENCE` (the field is a `RecordID`) and
|
|
4297
|
-
|
|
4301
|
+
- A field's `ASSERT`, `PERMISSIONS`, `REFERENCE` (the field is a `RecordID`) and comment are not generated, and a
|
|
4302
|
+
table's permissions and change feed are only comments of its class: the database still applies them. `READONLY` is
|
|
4303
|
+
a trailing `# READONLY` comment: no field option exists for it.
|
|
4298
4304
|
- `update()` may fail on an instance holding a `READONLY` datetime below the top level, in a sub-model (`address.at`),
|
|
4299
4305
|
a `tuple`, an array (`array<datetime>`, `items.*.at`) or a set, after `get()` as after `save()`: Python keeps
|
|
4300
4306
|
microseconds, SurrealDB nanoseconds, and the server refuses the changed value. `update()` keeps the top-level
|
|
@@ -4391,9 +4397,10 @@ reads, stores, logs or writes them.
|
|
|
4391
4397
|
ORM's connection name, which routing, reconnects and the generated models' `connection=` key need (full ORM: an
|
|
4392
4398
|
`HTTPConnection`).
|
|
4393
4399
|
- **Generated models use comments** where the full ORM writes
|
|
4394
|
-
`SurrealConfigDict(
|
|
4395
|
-
|
|
4396
|
-
`
|
|
4400
|
+
`SurrealConfigDict(permissions=…, changefeed=…, view_query=…, relation_in=…, relation_out=…, enforced=…)`
|
|
4401
|
+
(`# Permissions: …`, `# Changefeed: …`, `# View: AS …`, `# IN … OUT … ENFORCED`), and the base class where it writes
|
|
4402
|
+
`table_type=` (`BaseSurrealEdge` for a relation table): those keys arrive in the lite's `SurrealConfigDict` with
|
|
4403
|
+
v0.31.0–v0.33.0. `READONLY` is a comment too (full ORM: `Field(readonly=True)`).
|
|
4397
4404
|
- **`RecordID` instead of `ForeignKey`/`ReferencesField`**; no `VectorField` or `Encrypted`; `computed()` instead
|
|
4398
4405
|
of `Computed()`; `Duration`, `UUID`, `Decimal` and the geometry classes instead of `str`, `dict` and `float`;
|
|
4399
4406
|
nested fields become sub-models (full ORM: dotted attribute lines).
|
|
@@ -23,7 +23,7 @@ What makes a cached result right:
|
|
|
23
23
|
delete invalidates (a deleted record's edges go with it).
|
|
24
24
|
|
|
25
25
|
Internal failures never fail a read: keying, copying a hit and copying a result to store fall back to the database.
|
|
26
|
-
Nothing is logged but
|
|
26
|
+
Nothing is logged but the fixed warning of an SDK without a CBOR encoder: no row, variable or key.
|
|
27
27
|
|
|
28
28
|
A leaf module: it imports ``_sdk``, ``encoding``, ``exceptions``, ``routing`` and the standard library only
|
|
29
29
|
(``BaseSurrealModel`` under ``TYPE_CHECKING``, and lazily in :meth:`QueryCache.invalidate`).
|
|
@@ -130,13 +130,13 @@ _retired: collections.deque[int] = collections.deque()
|
|
|
130
130
|
|
|
131
131
|
|
|
132
132
|
def ttl_seconds(value: object, where: str) -> float:
|
|
133
|
-
"""``value`` as seconds >= 0 (``0.0``: never cached);
|
|
133
|
+
"""``value`` as seconds >= 0 (``0.0``: never cached); the errors name ``where``.
|
|
134
134
|
|
|
135
135
|
An ``int`` or a ``float`` (``numbers.Real``, never a ``bool``) or a ``timedelta``.
|
|
136
136
|
|
|
137
137
|
Raises:
|
|
138
|
-
TypeError: anything else
|
|
139
|
-
ValueError: negative or not finite
|
|
138
|
+
TypeError: anything else.
|
|
139
|
+
ValueError: negative or not finite.
|
|
140
140
|
"""
|
|
141
141
|
if isinstance(value, bool) or not isinstance(value, (numbers.Real, timedelta)):
|
|
142
142
|
raise TypeError(f"{where} must be a number of seconds or a timedelta, not {type(value).__name__}")
|
|
@@ -187,7 +187,7 @@ def _fingerprint(encoder: Callable[[Any], bytes], frame: list[Any], variables: M
|
|
|
187
187
|
def statement_key(scope: int, kind: str, statement: str, variables: Mapping[str, Any]) -> str | None:
|
|
188
188
|
"""The key of an ORM read: ``["orm", scope, kind, statement, variables]``; ``None`` when it cannot be keyed.
|
|
189
189
|
|
|
190
|
-
``None`` (the read goes to the database) when the installed SDK exposes no CBOR encoder (
|
|
190
|
+
``None`` (the read goes to the database) when the installed SDK exposes no CBOR encoder (a warning, once per
|
|
191
191
|
process) or when anything raises, such as a value the SDK cannot send: the read raises its own error then.
|
|
192
192
|
"""
|
|
193
193
|
encoder = cbor_encode
|
|
@@ -205,7 +205,7 @@ _FAILED: Final = object()
|
|
|
205
205
|
|
|
206
206
|
|
|
207
207
|
def _require_str(method: str, name: str, value: object) -> None:
|
|
208
|
-
"""
|
|
208
|
+
"""Refuse a ``value`` that is not a ``str`` (``TypeError``)."""
|
|
209
209
|
if not isinstance(value, str):
|
|
210
210
|
raise TypeError(f"QueryCache.{method}() {name} must be a str, not {type(value).__name__}")
|
|
211
211
|
|
|
@@ -252,17 +252,17 @@ class QueryCache:
|
|
|
252
252
|
"""Set the cache's three settings, as the full SurrealDB-ORM does: an argument left out takes its default.
|
|
253
253
|
|
|
254
254
|
``default_ttl``: the TTL of a ``cache()`` read without one, in seconds or a ``timedelta`` (``0``: such reads
|
|
255
|
-
are never cached
|
|
255
|
+
are never cached). ``max_size``: the most entries kept; lowering it evicts the least recently
|
|
256
256
|
used entries at once. ``enabled=False`` hides the entries without removing them: ``get()`` returns ``None``,
|
|
257
257
|
``set()`` stores nothing, ``cache()`` reads go to the database, and nothing is counted; ``enabled=True``
|
|
258
|
-
serves again the entries still valid
|
|
258
|
+
serves again the entries still valid. Writes, expiry and closed connections keep removing entries while
|
|
259
259
|
the cache is disabled. Never clears the cache (``clear()`` does). Every argument is checked before any
|
|
260
260
|
change.
|
|
261
261
|
|
|
262
262
|
Raises:
|
|
263
|
-
TypeError: ``default_ttl`` is not a number of seconds or a ``timedelta
|
|
264
|
-
``int
|
|
265
|
-
ValueError: ``default_ttl`` is negative or not finite
|
|
263
|
+
TypeError: ``default_ttl`` is not a number of seconds or a ``timedelta``, ``max_size`` is not an
|
|
264
|
+
``int``, ``enabled`` is not a ``bool``.
|
|
265
|
+
ValueError: ``default_ttl`` is negative or not finite, ``max_size`` is below 1.
|
|
266
266
|
"""
|
|
267
267
|
seconds = ttl_seconds(default_ttl, "QueryCache.configure() default_ttl")
|
|
268
268
|
if isinstance(max_size, bool) or not isinstance(max_size, numbers.Integral):
|
|
@@ -286,8 +286,8 @@ class QueryCache:
|
|
|
286
286
|
Built from the table, the statement and the variables as the SDK would send them (its CBOR encoding), with
|
|
287
287
|
the keys of every mapping sorted (SurrealDB objects ignore key order, as the full ORM's ``sort_keys=True``
|
|
288
288
|
does): two keys are equal only when the requests are equivalent. Raises ``TypeError`` for a non-``str``
|
|
289
|
-
query/table or a non-mapping ``variables
|
|
290
|
-
|
|
289
|
+
query/table or a non-mapping ``variables``, or a value the SDK cannot send; ``SurrealDbError`` when the
|
|
290
|
+
installed SDK exposes no CBOR encoder.
|
|
291
291
|
"""
|
|
292
292
|
_require_str("make_key", "query", query)
|
|
293
293
|
if not isinstance(variables, Mapping):
|
|
@@ -303,11 +303,12 @@ class QueryCache:
|
|
|
303
303
|
|
|
304
304
|
@classmethod
|
|
305
305
|
def get(cls, key: str) -> Any | None:
|
|
306
|
-
"""A copy of the value cached under ``key``; ``None`` when missing, expired or the cache is disabled
|
|
306
|
+
"""A copy of the value cached under ``key``; ``None`` when missing, expired or the cache is disabled.
|
|
307
307
|
|
|
308
308
|
Also ``None`` (a miss) while an ORM write to the entry's table runs, from its start to its end (its
|
|
309
309
|
``pre_*``, ``around_*`` and ``post_*`` handlers included), as a ``cache()`` read of that table then goes to
|
|
310
|
-
the database: the write removes the entry when it ends, with any entry ``set()`` meanwhile.
|
|
310
|
+
the database: the write removes the entry when it ends, with any entry ``set()`` meanwhile. Raises
|
|
311
|
+
``TypeError`` for a ``key`` that is not a ``str``."""
|
|
311
312
|
_require_str("get", "key", key)
|
|
312
313
|
with cls._guard():
|
|
313
314
|
if not cls._enabled:
|
|
@@ -332,7 +333,8 @@ class QueryCache:
|
|
|
332
333
|
``table`` so that ``invalidate()`` and the ORM's writes to that table remove it. No-op when disabled; a
|
|
333
334
|
``ttl`` of ``0`` stores nothing and removes the key's previous entry (as the full ORM's already-expired
|
|
334
335
|
entry). Keys you build are yours: include whatever tells your callers apart (an entry set here is not scoped
|
|
335
|
-
to an identity). Raises
|
|
336
|
+
to an identity). Raises ``TypeError`` or ``ValueError`` on ``ttl`` (as
|
|
337
|
+
``configure()`` on ``default_ttl``), ``TypeError`` on a ``key`` or ``table`` that is not a ``str``."""
|
|
336
338
|
_require_str("set", "key", key)
|
|
337
339
|
_require_str("set", "table", table)
|
|
338
340
|
seconds = None if ttl is None else ttl_seconds(ttl, "QueryCache.set() ttl")
|
|
@@ -355,7 +357,7 @@ class QueryCache:
|
|
|
355
357
|
def invalidate(cls, model: type[BaseSurrealModel] | str) -> int:
|
|
356
358
|
"""Remove the cached entries of a model's table (or of the table named), and every cached read that
|
|
357
359
|
follows links (``fetch()``, a dotted path); return how many entries were removed. A read of that table
|
|
358
|
-
running meanwhile is not stored. Raises ``TypeError`` for anything but a model class or a ``str
|
|
360
|
+
running meanwhile is not stored. Raises ``TypeError`` for anything but a model class or a ``str``."""
|
|
359
361
|
from .model_base import BaseSurrealModel
|
|
360
362
|
|
|
361
363
|
if isinstance(model, str):
|
|
@@ -557,7 +559,7 @@ class QueryCache:
|
|
|
557
559
|
|
|
558
560
|
@classmethod
|
|
559
561
|
def _warn_no_encoder(cls) -> None:
|
|
560
|
-
"""Log
|
|
562
|
+
"""Log the missing CBOR encoder once per process (``clear()`` keeps the flag)."""
|
|
561
563
|
with cls._guard():
|
|
562
564
|
if cls._warned_no_encoder:
|
|
563
565
|
return
|
|
@@ -782,7 +784,7 @@ def _resolve(
|
|
|
782
784
|
|
|
783
785
|
|
|
784
786
|
def invalidates(of: _Of, *, deletes: bool = False) -> Callable[[F], F]:
|
|
785
|
-
"""Decorate an ORM write method so that it invalidates the cached reads it can change
|
|
787
|
+
"""Decorate an ORM write method so that it invalidates the cached reads it can change.
|
|
786
788
|
|
|
787
789
|
``of`` says which tables the call writes, from its first argument: ``"self"`` (the instance's model table),
|
|
788
790
|
``"cls"`` (the class's), ``"queryset"`` (the queryset's table; its ``objects(tx=)`` is the transaction),
|
|
@@ -350,7 +350,7 @@ class ChangeModelStream(Generic[T]):
|
|
|
350
350
|
raise StopAsyncIteration
|
|
351
351
|
if self._manager is not None:
|
|
352
352
|
# Before a pending event is handed out: once the connection serves other settings, no event of the
|
|
353
|
-
# previous database is yielded and the cursor stays where it was (
|
|
353
|
+
# previous database is yielded and the cursor stays where it was (_check_generation).
|
|
354
354
|
self._check_generation()
|
|
355
355
|
if self._pending:
|
|
356
356
|
event, after = self._pending.popleft()
|
|
@@ -375,7 +375,7 @@ class ChangeModelStream(Generic[T]):
|
|
|
375
375
|
return self._manager
|
|
376
376
|
|
|
377
377
|
def _check_generation(self) -> None:
|
|
378
|
-
"""
|
|
378
|
+
"""Raise when the bound connection was removed or registered again with other settings since the stream bound it.
|
|
379
379
|
|
|
380
380
|
Never retried: the error is not ``retryable``, and the generation never goes back, so every later read
|
|
381
381
|
raises it again.
|
|
@@ -534,8 +534,8 @@ class ChangeModelStream(Generic[T]):
|
|
|
534
534
|
|
|
535
535
|
A cancellation of the reading task (``asyncio.timeout``, ``wait_for``, ``Task.cancel()``) is
|
|
536
536
|
never retried, even when the SDK reports it as a failed request: see
|
|
537
|
-
:func:`~surreal_orm_lite.live.cancellation_lost`. Nor is
|
|
538
|
-
checked before every attempt and again once the client is in hand.
|
|
537
|
+
:func:`~surreal_orm_lite.live.cancellation_lost`. Nor is the end of the bound settings
|
|
538
|
+
(:meth:`_check_generation`), checked before every attempt and again once the client is in hand.
|
|
539
539
|
"""
|
|
540
540
|
manager = self._bound()
|
|
541
541
|
delay = float(self.reconnect_delay)
|
|
@@ -543,7 +543,7 @@ class ChangeModelStream(Generic[T]):
|
|
|
543
543
|
while True:
|
|
544
544
|
if self._stopped:
|
|
545
545
|
raise _StreamStopped
|
|
546
|
-
# Outside the try:
|
|
546
|
+
# Outside the try: a settings change is never taken for a connection failure, and nothing is sent (nor opened) once
|
|
547
547
|
# the connection serves other settings.
|
|
548
548
|
self._check_generation()
|
|
549
549
|
attempt += 1
|
|
@@ -551,7 +551,7 @@ class ChangeModelStream(Generic[T]):
|
|
|
551
551
|
try:
|
|
552
552
|
client = await manager.get_client()
|
|
553
553
|
# Again with the client in hand, no await before the operation: get_client() may have waited (the
|
|
554
|
-
# embedded guard) while the settings changed. Raised here,
|
|
554
|
+
# embedded guard) while the settings changed. Raised here, its error is re-raised below, not retried:
|
|
555
555
|
# is_connection_failure() is false for a SurrealDbConnectionError that is not retryable.
|
|
556
556
|
self._check_generation()
|
|
557
557
|
return await operation(client)
|
{surreal_orm_lite-0.30.7 → surreal_orm_lite-0.30.8}/src/surreal_orm_lite/connection_manager.py
RENAMED
|
@@ -121,13 +121,13 @@ _STATE: Final[tuple[tuple[str, Callable[[], Any]], ...]] = (
|
|
|
121
121
|
("generation", lambda: 0),
|
|
122
122
|
)
|
|
123
123
|
|
|
124
|
-
#: Which connection a routed classmethod acts on when called on the router
|
|
124
|
+
#: Which connection a routed classmethod acts on when called on the router: the current one (the
|
|
125
125
|
#: explicit name, else the ``using()`` override, else ``"default"``), always the default one, every registered one,
|
|
126
126
|
#: or the one whose live stream started the uuid.
|
|
127
127
|
_Policy = Literal["current", "default", "every", "live"]
|
|
128
128
|
|
|
129
|
-
#: What :meth:`SurrealDBConnectionManager._route` does with a connection name that is not registered: raise
|
|
130
|
-
#: answer ``None`` so the routed method returns ``None`` without running (``close_connection`` only
|
|
129
|
+
#: What :meth:`SurrealDBConnectionManager._route` does with a connection name that is not registered: raise
|
|
130
|
+
#: ``ValueError``, or answer ``None`` so the routed method returns ``None`` without running (``close_connection`` only).
|
|
131
131
|
_UnknownName = Literal["raise", "ignore"]
|
|
132
132
|
|
|
133
133
|
_P = ParamSpec("_P")
|
|
@@ -155,7 +155,7 @@ def _routed(
|
|
|
155
155
|
under ``@_cache.invalidates(...)`` too (``signup``), whose wrapper stays outermost.
|
|
156
156
|
|
|
157
157
|
A method that takes ``name`` (``get_client``, ``close_connection``, ``transaction``) keeps it in code and for
|
|
158
|
-
type checkers, but its wrapper's ``__signature__`` leaves it out
|
|
158
|
+
type checkers, but its wrapper's ``__signature__`` leaves it out: ``inspect.signature()`` shows what
|
|
159
159
|
it showed in v0.28.0, so a framework that fills parameters from a request (FastAPI's
|
|
160
160
|
``Depends(SurrealDBConnectionManager.get_client)``) never lets request data choose the connection.
|
|
161
161
|
``inspect.unwrap()`` still reaches the declared ``name``.
|
|
@@ -201,7 +201,7 @@ def _routed(
|
|
|
201
201
|
return None
|
|
202
202
|
target = target_of(cls, args, kwargs)
|
|
203
203
|
if target is None:
|
|
204
|
-
return None # unknown_name="ignore": a name that is not registered
|
|
204
|
+
return None # unknown_name="ignore": a name that is not registered
|
|
205
205
|
return await body(target, *args, **kwargs)
|
|
206
206
|
|
|
207
207
|
wrapper = routed_coroutine
|
|
@@ -215,7 +215,7 @@ def _routed(
|
|
|
215
215
|
wrapper = routed
|
|
216
216
|
wrapper.__surreal_routed__ = policy
|
|
217
217
|
if takes_name:
|
|
218
|
-
# Hidden from introspection only
|
|
218
|
+
# Hidden from introspection only: ``cls`` stays, without it ``inspect.signature()`` of the
|
|
219
219
|
# bound method raises; later parameters and the return annotation stay too.
|
|
220
220
|
wrapper.__signature__ = signature.replace(
|
|
221
221
|
parameters=[parameter for index, parameter in enumerate(signature.parameters.values()) if index != 1]
|
|
@@ -296,7 +296,7 @@ class SurrealDBConnectionManager:
|
|
|
296
296
|
__lost_identity: "weakref.WeakSet[asyncio.AbstractEventLoop]" = weakref.WeakSet()
|
|
297
297
|
|
|
298
298
|
# The SDK's in-process engine (v0.25.0): ONE client for the whole process, in this slot beside
|
|
299
|
-
# the per-loop cache. Measured with SDK 2.0.0
|
|
299
|
+
# the per-loop cache. Measured with SDK 2.0.0: an embedded client is not bound to a
|
|
300
300
|
# loop — one client serves every loop and thread — while each new client on ``mem://`` is a new,
|
|
301
301
|
# empty database, and two clients on one ``surrealkv://`` path are two engines that miss each
|
|
302
302
|
# other's writes. The per-loop rule of issue #163 would give every loop and thread a database of
|
|
@@ -305,7 +305,7 @@ class SurrealDBConnectionManager:
|
|
|
305
305
|
#
|
|
306
306
|
# A namespace/database change is a new *selection* on that one engine, and it resets the shared
|
|
307
307
|
# session — invalidate(), back to the in-process owner, then use() — instead of replaying the
|
|
308
|
-
# stored token
|
|
308
|
+
# stored token: a record session cannot write in another database and reads
|
|
309
309
|
# nothing there, and replaying a token moves the session back to the database it was issued for,
|
|
310
310
|
# silently undoing the selection. ``__embedded_selection`` is ``None`` while a client is in the
|
|
311
311
|
# slot when the selection is *stale* (a reset failed, or is under way): the next get_client()
|
|
@@ -318,7 +318,7 @@ class SurrealDBConnectionManager:
|
|
|
318
318
|
# The settings generation (v0.29.0): "these settings are still the ones this connection serves". Bumped only by
|
|
319
319
|
# _retire_server_clients() — add_connection() with other settings, remove_connection() of a named connection —
|
|
320
320
|
# never by set_connection(), unset_connection() or the setters, which keep their v0.28.0 tolerance. A client
|
|
321
|
-
# opening
|
|
321
|
+
# opening, an open transaction and a change feed compare it with the one they started under.
|
|
322
322
|
__generation: int = 0
|
|
323
323
|
|
|
324
324
|
#: The connection ``async with SurrealDBConnectionManager():`` resolved on entry, closed on exit.
|
|
@@ -345,10 +345,10 @@ class SurrealDBConnectionManager:
|
|
|
345
345
|
router, ``"default"`` is the default connection and every other policy the current one: the ``using()``
|
|
346
346
|
override, else ``"default"``. Never takes ``_REGISTRY_LOCK``: one ``dict`` lookup.
|
|
347
347
|
|
|
348
|
-
:param unknown_name: ``"ignore"`` answers ``None`` instead of raising
|
|
349
|
-
explicit or the active override removed meanwhile (``close_connection`` alone
|
|
350
|
-
:raises TypeError: *name* is not a ``str
|
|
351
|
-
:raises ValueError: *name* is empty
|
|
348
|
+
:param unknown_name: ``"ignore"`` answers ``None`` instead of raising ``ValueError`` for a name that is not
|
|
349
|
+
registered, explicit or the active override removed meanwhile (``close_connection`` alone).
|
|
350
|
+
:raises TypeError: *name* is not a ``str``.
|
|
351
|
+
:raises ValueError: *name* is empty; *name*, or the active override, is not a registered connection.
|
|
352
352
|
"""
|
|
353
353
|
if name is None:
|
|
354
354
|
if cls._connection_name is not None:
|
|
@@ -370,8 +370,8 @@ class SurrealDBConnectionManager:
|
|
|
370
370
|
def _manager_for(cls, name: str | None = None) -> "type[SurrealDBConnectionManager]":
|
|
371
371
|
"""The connection class of *name*, else of the current connection: the one resolver other modules use.
|
|
372
372
|
|
|
373
|
-
:raises TypeError: *name* is not a ``str
|
|
374
|
-
:raises ValueError: *name* is empty
|
|
373
|
+
:raises TypeError: *name* is not a ``str``.
|
|
374
|
+
:raises ValueError: *name* is empty or not a registered connection.
|
|
375
375
|
"""
|
|
376
376
|
connection = cls._route(name, policy="current")
|
|
377
377
|
assert connection is not None # unknown_name="raise" never answers None
|
|
@@ -468,7 +468,7 @@ class SurrealDBConnectionManager:
|
|
|
468
468
|
connection = _REGISTRY.get(name)
|
|
469
469
|
if connection is None:
|
|
470
470
|
connection = _REGISTRY[name] = _new_connection_class(name)
|
|
471
|
-
# After the lock
|
|
471
|
+
# After the lock: never held while a method of a connection class runs.
|
|
472
472
|
if connection._settings() == (url, user, password, namespace, database):
|
|
473
473
|
return
|
|
474
474
|
connection.set_connection(url=url, user=user, password=password, namespace=namespace, database=database)
|
|
@@ -488,8 +488,8 @@ class SurrealDBConnectionManager:
|
|
|
488
488
|
fails, an HTTP client keeps its namespace and database, and an embedded client is the previous engine (with
|
|
489
489
|
SDK 2.x still running), so stop using it, as after :meth:`close_connection`. A no-op for a name that is not
|
|
490
490
|
registered (after the name's type check). ``remove_connection("default")`` is :meth:`unset_connection`,
|
|
491
|
-
unchanged (the default is never unregistered). A model routed to a removed name raises
|
|
492
|
-
call. The name is free again as soon as this is called: an ``add_connection()`` of it, even while the old one
|
|
491
|
+
unchanged (the default is never unregistered). A model routed to a removed name raises ``ValueError`` at its next
|
|
492
|
+
database call. The name is free again as soon as this is called: an ``add_connection()`` of it, even while the old one
|
|
493
493
|
is closing, registers a new connection.
|
|
494
494
|
|
|
495
495
|
:raises TypeError: *name* is not a ``str``.
|
|
@@ -509,7 +509,7 @@ class SurrealDBConnectionManager:
|
|
|
509
509
|
return
|
|
510
510
|
# Settings cleared before the generation bump, as add_connection() writes the new ones before it: a call that
|
|
511
511
|
# reads the new generation (another thread let through the embedded guard during the removal, say) reads no
|
|
512
|
-
# settings and opens nothing; one that read the old generation is refused when it publishes its client
|
|
512
|
+
# settings and opens nothing; one that read the old generation is refused when it publishes its client,
|
|
513
513
|
# or published it before the bump, and the retirement below or unset_connection() closes it.
|
|
514
514
|
connection._clear_settings()
|
|
515
515
|
connection._retire_server_clients()
|
|
@@ -588,13 +588,13 @@ class SurrealDBConnectionManager:
|
|
|
588
588
|
@classmethod
|
|
589
589
|
@_routed("current")
|
|
590
590
|
def _settings_generation(cls) -> int:
|
|
591
|
-
"""The connection's settings generation: the one way other modules read it (change feeds
|
|
591
|
+
"""The connection's settings generation: the one way other modules read it (change feeds)."""
|
|
592
592
|
return cls.__generation
|
|
593
593
|
|
|
594
594
|
@classmethod
|
|
595
595
|
@_routed("current")
|
|
596
596
|
def _retire_server_clients(cls) -> None:
|
|
597
|
-
"""Stop serving the connection's previous settings
|
|
597
|
+
"""Stop serving the connection's previous settings: bump its generation, end its live readers on every
|
|
598
598
|
event loop and retire its server clients on every loop.
|
|
599
599
|
|
|
600
600
|
Synchronous, with or without a running event loop (``add_connection()`` may run at import time). Each loop's
|
|
@@ -1038,7 +1038,7 @@ class SurrealDBConnectionManager:
|
|
|
1038
1038
|
replayed = cls._fingerprint(cls.__url, cls.__namespace, cls.__database, cls.__user, cls.__session_token)
|
|
1039
1039
|
configured = cls._fingerprint(cls.__url, cls.__namespace, cls.__database, cls.__user, None)
|
|
1040
1040
|
# The settings generation this client is built under (v0.29.0), read with the settings themselves: a
|
|
1041
|
-
# re-registration with other settings, or a removal, while it opens makes _publish() refuse it
|
|
1041
|
+
# re-registration with other settings, or a removal, while it opens makes _publish() refuse it.
|
|
1042
1042
|
generation = cls.__generation
|
|
1043
1043
|
|
|
1044
1044
|
# Establish the connection
|
|
@@ -1114,7 +1114,7 @@ class SurrealDBConnectionManager:
|
|
|
1114
1114
|
"""Stamp and cache a freshly built client — unless the reconnect that asked for it was
|
|
1115
1115
|
abandoned meanwhile (the application closed the connection, stopped the stream), or the
|
|
1116
1116
|
connection's settings changed while it opened (v0.29.0: *generation*, the settings
|
|
1117
|
-
generation it was built under; the client is then closed unused and
|
|
1117
|
+
generation it was built under; the client is then closed unused and a retryable ``SurrealDbConnectionError`` raised)."""
|
|
1118
1118
|
if still_wanted is not None and not still_wanted():
|
|
1119
1119
|
closing = asyncio.get_running_loop().create_task(client.close())
|
|
1120
1120
|
_BACKGROUND.add(closing)
|
|
@@ -1201,7 +1201,7 @@ class SurrealDBConnectionManager:
|
|
|
1201
1201
|
|
|
1202
1202
|
The settings generation (v0.29.0) is read first, before any await: when ``add_connection()`` registers the
|
|
1203
1203
|
name again with other settings, or ``remove_connection()`` removes it, while the engine opens or its session
|
|
1204
|
-
is selected again, the call raises
|
|
1204
|
+
is selected again, the call raises a retryable ``SurrealDbConnectionError`` instead of serving the old settings
|
|
1205
1205
|
(:meth:`_refuse_retired_embedded`).
|
|
1206
1206
|
"""
|
|
1207
1207
|
if not is_embedded_url(cls.__url):
|
|
@@ -1239,7 +1239,7 @@ class SurrealDBConnectionManager:
|
|
|
1239
1239
|
@classmethod
|
|
1240
1240
|
@_routed("current")
|
|
1241
1241
|
async def _refuse_retired_embedded(cls, generation: int, cause: BaseException | None = None) -> None:
|
|
1242
|
-
"""
|
|
1242
|
+
"""Raise on the embedded engine when the settings generation is no longer *generation*, the one the caller
|
|
1243
1243
|
of :meth:`_held_embedded_client` started under. Caller holds the guard, and the slot holds the client it
|
|
1244
1244
|
opened or selected again.
|
|
1245
1245
|
|
|
@@ -1293,7 +1293,8 @@ class SurrealDBConnectionManager:
|
|
|
1293
1293
|
slot. Caller holds the guard, and the slot is empty.
|
|
1294
1294
|
|
|
1295
1295
|
An on-disk store is claimed for this connection first (v0.29.0): another connection of the process that has
|
|
1296
|
-
it open makes this raise
|
|
1296
|
+
it open makes this raise ``SurrealDbConnectionError`` before anything opens. The claim is released when no
|
|
1297
|
+
client ends up in the slot.
|
|
1297
1298
|
"""
|
|
1298
1299
|
url, namespace, database = cls.__url, cls.__namespace, cls.__database
|
|
1299
1300
|
claimed = _claim_store(url, cls)
|
|
@@ -2061,7 +2062,7 @@ class SurrealDBConnectionManager:
|
|
|
2061
2062
|
what a reconnect restores). The slot's selection is stale until ``use()`` succeeds, so
|
|
2062
2063
|
nobody takes the fast path meanwhile; on failure it stays stale — the next
|
|
2063
2064
|
:meth:`get_client` selects again — and nothing is closed: :meth:`close_connection` would
|
|
2064
|
-
discard a ``mem://`` database
|
|
2065
|
+
discard a ``mem://`` database.
|
|
2065
2066
|
"""
|
|
2066
2067
|
held = cls.__embedded_client is client
|
|
2067
2068
|
if held:
|
|
@@ -2830,8 +2831,8 @@ async def _close_quietly(client: Any) -> None:
|
|
|
2830
2831
|
|
|
2831
2832
|
|
|
2832
2833
|
def _opening_retired_text(name: str | None) -> str:
|
|
2833
|
-
"""
|
|
2834
|
-
again with other settings meanwhile), and was closed unused."""
|
|
2834
|
+
"""The message when a client finished opening on settings connection *name* no longer serves (it was removed or
|
|
2835
|
+
registered again with other settings meanwhile), and was closed unused."""
|
|
2835
2836
|
return (
|
|
2836
2837
|
f"Connection {name!r} was removed or registered again with other settings while a client was opening on the "
|
|
2837
2838
|
"old ones; that client was closed unused. Retry the call."
|
|
@@ -2839,7 +2840,7 @@ def _opening_retired_text(name: str | None) -> str:
|
|
|
2839
2840
|
|
|
2840
2841
|
|
|
2841
2842
|
def _transaction_retired_text(name: str | None) -> str:
|
|
2842
|
-
"""
|
|
2843
|
+
"""Why a transaction whose connection was removed or registered again with other settings committed
|
|
2843
2844
|
nothing — the error of a committing exit, and the note added to a body's own exception."""
|
|
2844
2845
|
return (
|
|
2845
2846
|
f"Connection {name!r} was removed or registered again with other settings while this transaction was open "
|
|
@@ -2857,7 +2858,7 @@ def _claim_store(url: str | None, connection: type[SurrealDBConnectionManager])
|
|
|
2857
2858
|
:return: the store's key when this call claimed it; ``None`` for an in-memory or server URL, or a store
|
|
2858
2859
|
*connection* already holds (a connection may open its own store again: an ``embedded_database()`` block on
|
|
2859
2860
|
its path).
|
|
2860
|
-
:raises SurrealDbConnectionError:
|
|
2861
|
+
:raises SurrealDbConnectionError: another connection of the process has that store open; never retryable.
|
|
2861
2862
|
"""
|
|
2862
2863
|
key = store_key(url)
|
|
2863
2864
|
if key is None:
|
|
@@ -2919,7 +2920,7 @@ _REGISTRY_LOCK = threading.Lock()
|
|
|
2919
2920
|
|
|
2920
2921
|
#: The on-disk embedded stores open in this process (v0.29.0): store key (:func:`~surreal_orm_lite.embedded.store_key`)
|
|
2921
2922
|
#: → the connection class whose engine has it open — the class, not its name: a name registered again is another
|
|
2922
|
-
#: connection. Two in-process engines on one store miss each other's writes, so a second connection is refused
|
|
2923
|
+
#: connection. Two in-process engines on one store miss each other's writes, so a second connection is refused
|
|
2923
2924
|
#: until the first one closes its engine.
|
|
2924
2925
|
_STORE_CLAIMS: dict[str, type[SurrealDBConnectionManager]] = {}
|
|
2925
2926
|
_STORE_LOCK = threading.Lock()
|