surreal-orm-lite 0.40.1__tar.gz → 0.40.2__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 (69) hide show
  1. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/CHANGELOG.md +19 -0
  2. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/PKG-INFO +15 -1
  3. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/README.md +14 -0
  4. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/docs/README.md +1 -0
  5. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/pyproject.toml +1 -1
  6. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/__init__.py +1 -1
  7. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/testing/factories.py +47 -13
  8. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/.gitignore +0 -0
  9. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/LICENSE +0 -0
  10. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/Makefile +0 -0
  11. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/_sdk.py +0 -0
  12. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/aggregations.py +0 -0
  13. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/auth.py +0 -0
  14. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/cache.py +0 -0
  15. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/changefeed.py +0 -0
  16. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/cli/__init__.py +0 -0
  17. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/cli/__main__.py +0 -0
  18. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/cli/commands.py +0 -0
  19. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/concurrency.py +0 -0
  20. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/connection_config.py +0 -0
  21. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/connection_manager.py +0 -0
  22. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/constants.py +0 -0
  23. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/decoding.py +0 -0
  24. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/define_parser.py +0 -0
  25. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/edge.py +0 -0
  26. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/embedded.py +0 -0
  27. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/encoding.py +0 -0
  28. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/enum.py +0 -0
  29. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/exceptions.py +0 -0
  30. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/functions.py +0 -0
  31. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/geo.py +0 -0
  32. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/hybrid.py +0 -0
  33. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/introspection.py +0 -0
  34. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/live.py +0 -0
  35. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/migrations/__init__.py +0 -0
  36. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/migrations/autodetect.py +0 -0
  37. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/migrations/compare.py +0 -0
  38. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/migrations/constants.py +0 -0
  39. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/migrations/executor.py +0 -0
  40. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/migrations/generator.py +0 -0
  41. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/migrations/introspector.py +0 -0
  42. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/migrations/loader.py +0 -0
  43. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/migrations/migration.py +0 -0
  44. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/migrations/operations.py +0 -0
  45. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/migrations/render.py +0 -0
  46. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/migrations/state.py +0 -0
  47. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/model_auth.py +0 -0
  48. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/model_base.py +0 -0
  49. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/model_ddl.py +0 -0
  50. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/model_generator.py +0 -0
  51. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/py.typed +0 -0
  52. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/q.py +0 -0
  53. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/query_set.py +0 -0
  54. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/routing.py +0 -0
  55. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/schema.py +0 -0
  56. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/schema_state.py +0 -0
  57. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/search.py +0 -0
  58. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/signals.py +0 -0
  59. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/subquery.py +0 -0
  60. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/surql_literal.py +0 -0
  61. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/testing/__init__.py +0 -0
  62. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/testing/database.py +0 -0
  63. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  64. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/testing/pytest_plugin.py +0 -0
  65. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/time_travel.py +0 -0
  66. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/transaction.py +0 -0
  67. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/types.py +0 -0
  68. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/utils.py +0 -0
  69. {surreal_orm_lite-0.40.1 → surreal_orm_lite-0.40.2}/src/surreal_orm_lite/vector.py +0 -0
@@ -5,6 +5,25 @@ 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.40.2] - 2026-11-03
9
+
10
+ Follow-up of the review of the model factories (v0.40.0). No new public API.
11
+
12
+ ### Fixed
13
+
14
+ - **`Faker("choice")` returns a deep copy of the item it draws** (#399). A mutable item (a list, a dict, a nested
15
+ model) is no longer shared by every instance that draws it: `build_batch(2)` with
16
+ `meta = Faker("choice", items=[Sub(x=[1])])` gives two distinct `meta` objects.
17
+ - **A class assigned to a factory field raises `TypeError`** (#399). `role = Role` (meant as `Role.ADMIN`) used to
18
+ fall back to the model default without an error. The refusal applies at the `class` statement, only when the class
19
+ is the most-derived definition of the field: a subclass that sets a value over a base's class is accepted, and
20
+ `Meta` and classes named like no field are still ignored. The message names the factory that holds the class.
21
+
22
+ ### Notes
23
+
24
+ - An override passed to `build()`, `build_batch()`, `create()` or `create_batch()` is used as is, not copied; the
25
+ docstrings and the testing guide now say so, and list the two departures from the full ORM.
26
+
8
27
  ## [0.40.1] - 2026-11-02
9
28
 
10
29
  The remembered forward-reference rebuild of v0.39.5 keys on the names a model's annotations mention, compares
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.40.1
3
+ Version: 0.40.2
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
@@ -154,6 +154,20 @@ lists every QuerySet method and filter lookup.
154
154
 
155
155
  The [documentation index](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/README.md) lists every section of the guides.
156
156
 
157
+ ## Using with AI assistants
158
+
159
+ The [guide for AI coding assistants](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/ai/CLAUDE.md)
160
+ gives an assistant such as Claude Code the idioms, the 2.x/3.x differences and the common mistakes in one page,
161
+ each example checked by the test suite. Download it into your project, then add the line `@docs/surreal-orm-lite.md`
162
+ to your `CLAUDE.md` to import it:
163
+
164
+ ```bash
165
+ curl -fsSL -o docs/surreal-orm-lite.md https://raw.githubusercontent.com/EulogySnowfall/SurrealDB-ORM-lite/main/docs/ai/CLAUDE.md
166
+ ```
167
+
168
+ Tools that read the [llms.txt](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/llms.txt) convention
169
+ find every guide listed there.
170
+
157
171
  ## Features
158
172
 
159
173
  | Feature | Status |
@@ -103,6 +103,20 @@ lists every QuerySet method and filter lookup.
103
103
 
104
104
  The [documentation index](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/README.md) lists every section of the guides.
105
105
 
106
+ ## Using with AI assistants
107
+
108
+ The [guide for AI coding assistants](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/docs/ai/CLAUDE.md)
109
+ gives an assistant such as Claude Code the idioms, the 2.x/3.x differences and the common mistakes in one page,
110
+ each example checked by the test suite. Download it into your project, then add the line `@docs/surreal-orm-lite.md`
111
+ to your `CLAUDE.md` to import it:
112
+
113
+ ```bash
114
+ curl -fsSL -o docs/surreal-orm-lite.md https://raw.githubusercontent.com/EulogySnowfall/SurrealDB-ORM-lite/main/docs/ai/CLAUDE.md
115
+ ```
116
+
117
+ Tools that read the [llms.txt](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/blob/main/llms.txt) convention
118
+ find every guide listed there.
119
+
106
120
  ## Features
107
121
 
108
122
  | Feature | Status |
@@ -132,6 +132,7 @@ The guides keep the section numbers of the manual, so a reference such as "secti
132
132
  - [Changelog](../CHANGELOG.md): what changed in each version.
133
133
  - [Security policy](../SECURITY.md): supported versions and how to report a vulnerability.
134
134
  - [Runnable examples](../examples/): one Jupyter notebook per feature release.
135
+ - [Guide for AI coding assistants](ai/CLAUDE.md): a compact page to import into an assistant's `CLAUDE.md`.
135
136
 
136
137
  ## Roadmap
137
138
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.40.1"
3
+ version = "0.40.2"
4
4
  description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -1,4 +1,4 @@
1
- __version__ = "0.40.1"
1
+ __version__ = "0.40.2"
2
2
 
3
3
  from ._sdk import BoundExcluded, BoundIncluded
4
4
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
@@ -205,7 +205,7 @@ class Faker:
205
205
  - ``boolean`` — random bool
206
206
  - ``date`` — random date within the last year
207
207
  - ``datetime`` — random aware UTC datetime within the last year
208
- - ``choice`` — random item of ``items`` (kwargs: ``items``, required and non-empty)
208
+ - ``choice`` — deep copy of a random item of ``items`` (kwargs: ``items``, required and non-empty)
209
209
 
210
210
  Raises:
211
211
  TypeError: ``provider`` is not a string, or a keyword the provider does not take is given.
@@ -292,7 +292,8 @@ class Faker:
292
292
  return datetime.now(tz=UTC) - timedelta(seconds=seconds_back)
293
293
 
294
294
  def _gen_choice(self) -> Any:
295
- return random.choice(self.kwargs["items"])
295
+ # A deep copy, so a mutable item (list, dict, sub-model) is never shared between two instances (#399).
296
+ return copy.deepcopy(random.choice(self.kwargs["items"]))
296
297
 
297
298
  def __repr__(self) -> str:
298
299
  if self.kwargs:
@@ -315,18 +316,23 @@ def _describe_callable(value: Any) -> str:
315
316
  return kind.__qualname__ if kind.__module__ == "builtins" else f"{kind.__module__}.{kind.__qualname__}"
316
317
 
317
318
 
318
- def _collect_own(name: str, namespace: dict[str, Any]) -> dict[str, Any]:
319
- """Collect one class body's declarations, in declaration order, names as written.
319
+ def _collect_own(name: str, namespace: dict[str, Any]) -> tuple[dict[str, Any], dict[str, type]]:
320
+ """Collect one class body's declarations, in declaration order, names as written, and its classes.
320
321
 
321
- Ignored: a ``_`` name, ``Meta``, a function (lambdas included), a ``classmethod``/``staticmethod``/``property``
322
- and a class. Refused: any other callable (``datetime.now``, ``functools.partial(...)``, an instance with
323
- ``__call__``), which F1 may later give a lazy meaning. Collected: everything else.
322
+ Ignored: a ``_`` name, ``Meta``, a function (lambdas included) and a ``classmethod``/``staticmethod``/``property``.
323
+ A class is returned apart: once the model is known, the metaclass refuses it if its name is a model field and it is
324
+ that field's most-derived definition in the MRO (#399), and ignores it otherwise. Refused: any other callable (``datetime.now``, ``functools.partial(...)``, an instance
325
+ with ``__call__``), which F1 may later give a lazy meaning. Collected: everything else.
324
326
  """
325
327
  own: dict[str, Any] = {}
328
+ classes: dict[str, type] = {}
326
329
  for key, value in namespace.items():
327
330
  if key.startswith("_") or key == "Meta":
328
331
  continue
329
- if inspect.isfunction(value) or isinstance(value, (classmethod, staticmethod, property, type)):
332
+ if isinstance(value, type):
333
+ classes[key] = value
334
+ continue
335
+ if inspect.isfunction(value) or isinstance(value, (classmethod, staticmethod, property)):
330
336
  continue
331
337
  if callable(value):
332
338
  raise TypeError(
@@ -334,7 +340,7 @@ def _collect_own(name: str, namespace: dict[str, Any]) -> dict[str, Any]:
334
340
  "a Faker or a SurrealFunc — lazy values are not supported yet"
335
341
  )
336
342
  own[key] = value
337
- return own
343
+ return own, classes
338
344
 
339
345
 
340
346
  class _FactoryMeta(type):
@@ -345,12 +351,14 @@ class _FactoryMeta(type):
345
351
  """
346
352
 
347
353
  _own_defs: dict[str, Any]
354
+ _own_classes: dict[str, type]
348
355
  _field_defs: dict[str, Any]
349
356
 
350
357
  def __new__(mcs, name: str, bases: tuple[type, ...], namespace: dict[str, Any], **kwargs: Any) -> "_FactoryMeta":
351
- own = _collect_own(name, namespace)
358
+ own, classes = _collect_own(name, namespace)
352
359
  cls = super().__new__(mcs, name, bases, namespace, **kwargs)
353
360
  cls._own_defs = own
361
+ cls._own_classes = classes
354
362
  model = cls._find_model()
355
363
  if model is None:
356
364
  merged: dict[str, Any] = {}
@@ -377,9 +385,13 @@ class _FactoryMeta(type):
377
385
  @staticmethod
378
386
  def _normalized_defs(name: str, cls: "_FactoryMeta", model: type[BaseSurrealModel]) -> dict[str, Any]:
379
387
  """Merge the MRO's declarations keyed by the model's Python field names, then check them (D14, D15)."""
388
+ model_fields = model.model_fields
380
389
  per_class: list[list[tuple[str, str, Any]]] = []
390
+ # The most-derived definition of each model field: a value (None) or the class that holds a class there.
391
+ winners: dict[str, tuple[str, str, type] | None] = {}
381
392
  for klass in reversed(cls.__mro__):
382
393
  own: dict[str, Any] = klass.__dict__.get("_own_defs", {})
394
+ own_classes: dict[str, type] = klass.__dict__.get("_own_classes", {})
383
395
  entries = [(raw, model.to_py_field(raw), value) for raw, value in own.items()]
384
396
  seen: dict[str, str] = {}
385
397
  for raw, py_name, _value in entries:
@@ -388,7 +400,27 @@ class _FactoryMeta(type):
388
400
  f"{name} declares {py_name!r} twice: as {py_name!r} and as its column {model.to_db_field(py_name)!r}"
389
401
  )
390
402
  seen[py_name] = raw
403
+ winners[py_name] = None
404
+ for raw, value in own_classes.items():
405
+ py_name = model.to_py_field(raw)
406
+ if py_name not in model_fields:
407
+ continue
408
+ if py_name in seen:
409
+ raise TypeError(
410
+ f"{name} declares {py_name!r} twice: as {py_name!r} and as its column {model.to_db_field(py_name)!r}"
411
+ )
412
+ seen[py_name] = raw
413
+ winners[py_name] = (klass.__name__, raw, value)
391
414
  per_class.append(entries)
415
+ for py_name, winner in winners.items():
416
+ if winner is not None:
417
+ holder, raw, value = winner
418
+ inherited = "" if holder == name else f" (inherited by {name})"
419
+ raise TypeError(
420
+ f"{holder}.{raw} is a class ({value.__qualname__}) assigned to the field {py_name!r} of "
421
+ f"{model.__name__}{inherited}; a factory attribute is a static value, a Faker or a SurrealFunc — give an "
422
+ "instance (an Enum member, for example), or pass the class as an override at the call"
423
+ )
392
424
  if model.model_config.get("extra") != "allow":
393
425
  known = set(model.model_fields)
394
426
  for entries in per_class:
@@ -432,7 +464,7 @@ class ModelFactory(Generic[M], metaclass=_FactoryMeta):
432
464
 
433
465
  Raises (at the ``class`` statement):
434
466
  TypeError: ``Meta.model`` is not a ``BaseSurrealModel`` subclass; an attribute is a callable other than a
435
- function, method or class; one class body declares a field under its Python name and its column; a
467
+ function, method or class; a class is assigned to a field of the model; one class body declares a field under its Python name and its column; a
436
468
  declared name is no field of the model (unless the model has ``extra="allow"``); a ``SurrealFunc`` is
437
469
  declared on (or inherited by) an edge factory.
438
470
  """
@@ -566,7 +598,8 @@ class ModelFactory(Generic[M], metaclass=_FactoryMeta):
566
598
  def build_batch(cls, count: int, /, **overrides: Any) -> list[M]:
567
599
  """Build *count* unsaved instances, each with fresh ``Faker`` values and fresh copies.
568
600
 
569
- Every check runs before the first instance; ``count=0`` returns ``[]``.
601
+ Every check runs before the first instance; ``count=0`` returns ``[]``. An override is used as is, not
602
+ copied: ``build_batch(3, address=Address(city="Paris"))`` gives the three instances the same object (#399).
570
603
 
571
604
  Raises:
572
605
  ValueError: the factory has no model; *count* is negative.
@@ -610,7 +643,8 @@ class ModelFactory(Generic[M], metaclass=_FactoryMeta):
610
643
 
611
644
  Every check runs before the first ``save()``; ``count=0`` returns ``[]``. A failing ``save()`` stops the
612
645
  batch and propagates; the records already created stay. ``Model.objects().bulk_create(build_batch(n))`` is the
613
- one-``INSERT`` path (no signals).
646
+ one-``INSERT`` path (no signals). An override is used as is, not copied: every record of the batch gets the
647
+ same object (#399).
614
648
 
615
649
  Raises:
616
650
  ValueError: the factory has no model; *count* is negative.