You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 389c6d9
Browse filesBrowse the repository at this point in the historyBrowse files
fix(model): honor document.id in upsert()'s no-match insert
upsert() with a condition serialized the model with force_dict=True,
so a set document.id was dropped on the no-match insert: the document
landed at a fresh id and document.id was then overwritten with it,
destroying even the evidence that the caller asked for a specific id
(#120). The same instance produced two different outcomes depending
on whether a condition was passed.
The no-match insert now honors document.id exactly as insert() does:
a set id says "put it here", so the document is inserted at that id,
and a taken id raises DocumentAlreadyExistsError instead of silently
duplicating the document elsewhere. Only id=None still gets a fresh
id, and the condition's own id value is still never adopted. A
matching condition still wins over a preset id (pinned by a test).
Delegating to Table.upsert() cannot express this: handed a Document
and a cond, TinyDB extracts the doc_id and passes it to
Table.update(document, cond, doc_ids=[doc_id]), which checks doc_ids
before cond — the condition is never evaluated. The non-id-condition
branch therefore inlines upstream's update-then-insert through the
public Table.update()/Table.insert(); the id-condition branch keeps
its atomic write cycle and now passes the id-bearing Document
through to the fallback insert. Both branches translate the taken-id
ValueError via the new _upsert_insert() helper. Friction recorded on
the Upstream Limitations page and tracked as #148.
Assisted-by: Claude:claude-fable-5
Copy file name to clipboardExpand all lines: CHANGELOG.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,6 +8,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
8
8
9
9
### Fixed
10
10
11
+
- `upsert()` no longer silently discards a set `document.id` when a condition is passed ([#120](https://github.com/tinydantic/tinydantic/issues/120)). The same instance used to produce two different outcomes: with no condition, `upsert(Book(id=7, ...))` honored the id; with a condition that matched nothing, the insert landed at a fresh id and `document.id` was then overwritten with it — destroying even the evidence that the caller asked for 7. The no-match insert now honors `document.id` exactly as `insert()` does: a set id says "put it here", so the document is inserted at that id, and an id that is already taken raises `DocumentAlreadyExistsError` instead of silently duplicating the document elsewhere; only a document with `id=None` still gets a fresh id. The condition's own id value is still never adopted (`upsert(book, Book.id == 7)` matching nothing does not insert at 7), matching TinyDB's own upsert semantics, and a matching condition still wins over a preset id, which is now pinned by a test. Behind the fix, the non-id-condition branch no longer delegates to `Table.upsert()`: handed a `Document` _and_ a condition, TinyDB silently prefers the `doc_id` and never evaluates the condition, so tinydantic inlines upstream's update-then-insert through the public `Table.update()`/`Table.insert()` instead — friction recorded on [Upstream Limitations](https://tinydantic.github.io/tinydantic/latest/contributing/upstream_limitations/) and tracked as [#148](https://github.com/tinydantic/tinydantic/issues/148).
12
+
11
13
- Three error messages recommended APIs that do not exist or do not work, all of them survivors of this cycle's renames. The "condition has no truth value" guard offered `Model.get(cond) is not None` as an existence check — but `get()` raises `DocumentNotFoundError` on a miss, so the advice fails on exactly the input it is offered for; the runnable spelling is `get_or_none(cond) is not None`. `DocumentIDUpdateError` said to "use `doc_ids=[...]`", a selector parameter removed this cycle in favor of `update_by_ids()`. And `DocumentIDConditionError` pointed at `doc_id=`/`doc_ids=` for the same reason; it now names `get_by_ids()`, `update_by_ids()`, and `remove_by_ids()`. Each is pinned by a test that runs the advice rather than only matching the text.
12
14
13
15
- Docs: the published reference and guides carried 76 verified inaccuracies, found by a full audit of every Markdown page, every `src/` and `scripts/` docstring, and every `tests/` docstring. The load-bearing ones: `get()` was documented as returning `None` on a miss in the README quickstart and demonstrated that way in the Concurrency page's ETag handlers (where it made the 404 branch dead code and turned a real miss into a 500); the Testing page's fixture never bound a database, so both example tests below it would have raised `DatabaseNotBoundError`; `ProfilingMiddleware`'s stacking advice was exactly inverted in both its docstring and the Storage page, so a reader instrumented the opposite layer from the one they wanted; `matches()` was described as a whole-value regex test when TinyDB anchors it at the start only, which turns the obvious allow-list pattern into one that accepts `[email protected]`; the Queries page said bitwise operators bind more loosely than comparisons (they bind more tightly, which is why it recommends parentheses) and carried a type-checker transcript that was wrong in four ways; twelve `Raises:` entries were missing across four exception types; and the enforcement, no-hook, and unique-bypass verb rosters each named two or three verbs where five apply. `docs/contributing/upstream_limitations.md` also called TinyDB's batched write `update_many()` — TinyDB has no such method, and the page is written to be read standalone by an upstream maintainer.
Copy file name to clipboardExpand all lines: docs/contributing/upstream_limitations.md
+10Lines changed: 10 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,6 +47,16 @@ Existing queries and third-party `QueryLike` objects pay nothing (the `getattr`
47
47
- Accept an optional per-pair id selector, e.g. `update_multiple(updates: Iterable[tuple[fields, cond | None, doc_ids | None]])` (or a parallel `update_multiple_by_ids()`), mirroring the `update()`/`remove()` signatures.
48
48
- Ship the `needs_doc_id`/`DocId` improvement above, which subsumes this: id conditions would then work in `update_multiple()`'s existing signature.
49
49
50
+
### `Table.upsert()` silently ignores the condition when the document carries a `doc_id`
**Limitation.**`Table.upsert(document, cond)` treats its two selectors as either/or: when `document` is a [`Document`](https://tinydb.readthedocs.io/en/latest/api.html#tinydb.table.Document) carrying a `doc_id`, the implementation extracts that id and calls `Table.update(document, cond, doc_ids=[doc_id])` — and `update()` checks `doc_ids` before `cond`, so a condition passed alongside a `Document` is **never evaluated**. Nothing raises or warns; the call simply performs a different operation (upsert by id) than the one written (upsert by condition). Consequently the public API cannot express "update the documents matching this condition; if none match, insert at this specific id": passing both selects by id and silently drops the condition, while a plain dict body cannot carry an id into the fall-through insert.
55
+
56
+
**Why it matters to an ODM.** `tinydantic` maps its `id` field to `doc_id`, and its [`upsert()`][tinydantic.TinydanticModel.upsert] honors a set `document.id` on the no-match insert exactly as [`insert()`][tinydantic.TinydanticModel.insert] does — a set id says "put it here" (tinydantic [#120](https://github.com/tinydantic/tinydantic/issues/120) fixed the earlier behavior of silently discarding it). Expressing that means serializing the model as a `Document` so its id survives to the insert — and handing that `Document` plus the user's condition to `Table.upsert()` would silently turn every condition-upsert into an id-upsert. `TinydanticModel.upsert()` (`src/tinydantic/_model.py`) therefore inlines upstream's own update-then-insert instead of delegating: `Table.update(document, cond)` first, and when nothing matched, `Table.insert(document)` with the id-bearing `Document` — public API throughout, the same two storage cycles `Table.upsert()` itself spends, with the insert's "id already taken" `ValueError` translated to [`DocumentAlreadyExistsError`][tinydantic.DocumentAlreadyExistsError]. (Id-bearing _conditions_ take the atomic private-API path recorded in the [registry below](#tinydb-private-api-usage-registry) for other reasons.)
57
+
58
+
**Suggested improvement.** When both selectors are supplied, either honor the condition — evaluate `cond`, with the `doc_id` seeding only the fall-through insert, which is strictly more expressive and is what the call reads as — or refuse the combination with a `ValueError`, as the doc_id-less-and-cond-less call already does. Either is better than the silent precedence; at minimum, the docstring ("optional if you've passed a Document with a doc_id") should state that a `Document`'s id does not merely make `cond` optional but overrides it entirely.
59
+
50
60
### `Query.matches()` is documented as whole-value and anchors only at the start
When nothing matches, the insert honors the instance's own `id` exactly as `insert()` does: a set `id` says "put it here", so the document lands at that id — and an id that is already taken is refused with [DocumentAlreadyExistsError][tinydantic.DocumentAlreadyExistsError] rather than silently duplicated at a fresh one. (The _condition's_ id value is never adopted: `upsert(book, Book.id == 7)` matching nothing inserts at `book.id` — or a fresh id if `book.id` is `None` — not at 7.)
tinydantic._errors.DocumentAlreadyExistsError: Document with id 1 already exists in table 'books' (model 'Book'). Omit id to let TinyDB assign one, or use save()/upsert() to update the existing document.
76
+
77
+
```
78
+
66
79
## Read
67
80
68
81
The table now holds four books. Read methods return validated model instances with `id` set from the stored document id.
0 commit comments