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 41f5122
Browse filesBrowse the repository at this point in the historyBrowse files
README.md:
- D-RM-1 "get() returns a single validated model instance (or
None)" — the finding that triggered the audit. get() returns
Self and raises DocumentNotFoundError; get_or_none() is the
lenient half, and the section now shows both.
- D-RM-2 the TIP explained mypy's overload fallback while the
example above it used get(), which has a single signature. The
two claims are now separate, and the overload one names find().
- D-RM-3 "Querying for it afterwards returns None" sat over an
example that silently switched to get_or_none().
queries.md:
- D-QRY-1 "Python's bitwise operators bind more loosely than
comparisons" — inverted. They bind more tightly, which is why
the parentheses the sentence recommends are needed.
- D-QRY-2 the "Prefer q() to suppressing the error" transcript was
wrong on four counts. Regenerated by running mypy and pyright:
get() is not overloaded (its error is arg-type and its return
type survives), find() is, and pyright keeps FindQuery[User]
where mypy falls back to Any.
- D-QRY-5 the raw-query escape hatch was motivated by methods
GuardedQuery already has. The real case is keys the model does
not declare; shadowed fields are field()'s job.
- D-QRY-6 an existence-check caption named get(), which raises.
- D-QRY-7 two tracebacks were truncated with no `...` marker,
hiding the actionable half. Both now show the full message,
pinned with -IGNORE_EXCEPTION_DETAIL.
crud.md:
- D-CRUD-1 "every other write verb checks uniqueness" — false for
every update verb.
- D-CRUD-2 "the table-level update() and update_all() below" —
those sections are above.
- D-CRUD-3 the whole-model boundary check omitted insert_many().
- D-CRUD-5 the general update() contract sat under ### update_many
while every example in it called update(). It is now its own
section, "The shared update contract", that all five verbs link
to.
find.md:
- D-FIND-1 a shown DocumentNotFoundError message the library never
produces, in two places. Only the global IGNORE_EXCEPTION_DETAIL
let it pass CI.
- D-FIND-2 "ties come out in doc-id order" — ties preserve table
order, which an explicit-id insert or a save() re-insert can put
out of id order.
- D-FIND-3 q imported and never used. D-FIND-4 a link to the top of
queries.md where #querying-by-id was meant.
models.md, concurrency.md, testing.md, fastapi.md,
schema-evolution.md:
- D-MOD-1 prose about update()/update_all() demonstrated with
update_by_ids() and labelled "update(): no hook".
- D-MOD-2 an after_read sketch redefined Session without its
table_name, silently rebinding it to a derived table.
- D-MOD-3 "Sorting-adjacent recipes" -> "Serialization-adjacent".
- D-CONC-1 the ETag example called get_by_id() and then tested for
None, so its 404 branch was dead and a real miss surfaced as a
500. Same root cause as D-RM-1.
- D-CONC-2 upsert() was said to hold no instance; it takes one. Its
contract, not its arguments, is why it does not check.
- D-TEST-1 the fixture never passed database=db, so both example
tests would have raised DatabaseNotBoundError. Fixed and run.
D-TEST-2 "Yield" over a fixture that returns.
- D-FAPI-1 asyncio.to_thread and run_in_threadpool use different
pools; the safety conclusion holds and now says why.
- D-FAPI-2 another exhaustive-sounding no-hook pair.
- D-SCHEMA-1 "the question that raises" -> "that arises".
contributing:
- D-CONTRIB-1 `heading_offset: 2` is not include-markdown syntax.
The plugin recognizes arguments by `=`, and so does its
invalid-argument warning, so it was dropped silently and strict
docs-build still passed — leaving H3s directly under the page H1.
With heading-offset=-1 the built page is H1/H2/H3 with no skip.
- D-CONTRIB-4 the hand-maintained TOC nested a sibling H2.
- D-CONTRIB-5 the docs include ends before the Development Guide,
so "The next section describes..." pointed at nothing.
The inventory-download workaround in CONTRIBUTING.md now links its
tracking issue, #146, which the two-artifact rule required and
which did not exist.
Assisted-by: Claude:claude-opus-5
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ Thanks for your interest in contributing to `tinydantic`!
9
9
-[I have a question](#i-have-a-question)
10
10
-[I found a bug](#i-found-a-bug)
11
11
-[I want to contribute](#i-want-to-contribute)
12
-
-[Development Guide](#development-guide)
12
+
-[Development Guide](#development-guide)
13
13
14
14
<!-- toc-end -->
15
15
@@ -49,7 +49,7 @@ If you are new to the project, check out <https://github.com/tinydantic/tinydant
49
49
>
50
50
> Before submitting a larger pull request (e.g. new features or breaking changes), consider creating an [issue](https://github.com/tinydantic/tinydantic/issues/new) to outline your proposed changes.
51
51
52
-
The next section describes how to set up a development environment and create a pull request to submit your changes for review.
52
+
The **Development Guide** describes how to set up a development environment and create a pull request to submit your changes for review.
53
53
54
54
<!-- development-guide-start -->
55
55
@@ -238,7 +238,7 @@ uv run poe docs-build-check
238
238
>
239
239
> The documentation build downloads Sphinx object inventories so that cross-references to external documentation (Python, Pydantic, TinyDB) resolve to links.
240
240
>
241
-
> However, [Read the Docs](https://about.readthedocs.com/) has put the site behind a Cloudflare bot challenge which blocks mkdocstrings' `mkdocstrings/0.15.0` user agent, rejecting the TinyDB inventory download (this shows up as `mkdocstrings: Couldn't load inventory ... HTTP Error 429: Too Many Requests`).
241
+
> However, [Read the Docs](https://about.readthedocs.com/) has put the site behind a Cloudflare bot challenge which blocks mkdocstrings' `mkdocstrings/0.15.0` user agent, rejecting the TinyDB inventory download (this shows up as `mkdocstrings: Couldn't load inventory ... HTTP Error 429: Too Many Requests`). This workaround is tracked in [#146](https://github.com/tinydantic/tinydantic/issues/146).
242
242
>
243
243
> If that happens (to any of the inventories), set the corresponding environment variable in your shell to point the build at a downloaded copy of the `objects.inv` inventory instead, then run the docs task as usual (from the repo root). The `file:` URL is resolved against the current working directory, so build from the repo root (the `poe docs...` tasks already require this).
Query the table by building a condition from a model field. [get()](https://tinydantic.github.io/tinydantic/latest/reference/api/tinydantic/#tinydantic.TinydanticModel.get) returns a single validated model instance (or `None`).
121
+
Query the table by building a condition from a model field. [get()](https://tinydantic.github.io/tinydantic/latest/reference/api/tinydantic/#tinydantic.TinydanticModel.get) returns a single validated model instance, and raises [DocumentNotFoundError](https://tinydantic.github.io/tinydantic/latest/reference/api/tinydantic/#tinydantic.DocumentNotFoundError) when nothing matches. Use [get_or_none()](https://tinydantic.github.io/tinydantic/latest/reference/api/tinydantic/#tinydantic.TinydanticModel.get_or_none) when a miss is an expected outcome rather than a bug.
> Reach for `q()` rather than silencing the error. `find()` is overloaded, and when no overload matches, `mypy` gives up on the whole call and types the result `Any` — so a `# type: ignore` hides the message and leaves you with an unchecked value where a `User` should be.
152
+
> Reach for `q()` rather than silencing the error. A `# type: ignore` hides the message and leaves the mistake in place, and on the overloaded [find()](https://tinydantic.github.io/tinydantic/latest/reference/api/tinydantic/#tinydantic.TinydanticModel.find) it costs more: when no overload matches, `mypy` gives up on the whole call and types the result `Any`, so everything you chain onto it goes unchecked.
151
153
152
154
See [Queries → Static type checking](https://tinydantic.github.io/tinydantic/latest/usage/queries/#static-type-checking) for what `q()` does and does not fix.
Call [delete()](https://tinydantic.github.io/tinydantic/latest/reference/api/tinydantic/#tinydantic.TinydanticModel.delete) to remove the document. Querying for it afterwards returns `None`.
171
+
Call [delete()](https://tinydantic.github.io/tinydantic/latest/reference/api/tinydantic/#tinydantic.TinydanticModel.delete) to remove the document. Querying for it afterwards with `get_or_none()`returns `None` (`get()` would raise).
Copy file name to clipboardExpand all lines: docs/usage/concurrency.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -101,7 +101,7 @@ When last-write-wins is genuinely what you want — an admin override, a migrati
101
101
-**Patch what you decided.**`book.patch(title="Dune (1965)")` — the value came from outside the document; no read went stale.
102
102
-**Save what you derived.**`stock - 1` was computed _from_ a read; route it through the load-mutate-`save()` loop above, where the check lives.
103
103
104
-
The table-level verbs — `update()`, `update_all()`, `update_many()`, `upsert()` — hold no instance and no token, so they cannot check; they rotate every document they touch, correctly invalidating tokens held elsewhere. Writing `revision_id` yourself through any update path raises [RevisionUpdateError][tinydantic.RevisionUpdateError] — a forged token could mask concurrent writes.
104
+
The update verbs — `update()`, `update_by_ids()`, `update_all()`, `update_many()`, `FindQuery.update()` — hold no instance and no token, so they cannot check. `upsert()` does take an instance, and on a revisioned model that instance carries a token, but its contract is "write this regardless of current state", so it deliberately does not check either. All six rotate every document they touch, correctly invalidating tokens held elsewhere. Writing `revision_id` yourself through any update path raises [RevisionUpdateError][tinydantic.RevisionUpdateError] — a forged token could mask concurrent writes.
105
105
106
106
### Tokens travel: the ETag pattern
107
107
@@ -117,7 +117,7 @@ The token's real power is that it survives the round trip through a client. A we
Copy file name to clipboardExpand all lines: docs/usage/crud.md
+10-4Lines changed: 10 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -261,7 +261,7 @@ pydantic_core._pydantic_core.ValidationError: 1 validation error for Book
261
261
262
262
```
263
263
264
-
Every whole-model write path (`insert()`, `save()`, `replace()`, `upsert()`) shares this boundary check. Models can opt out with the `validate_writes=False` class kwarg — the escape hatch for performance-critical bulk writes; see [Configuration](configuration.md).
264
+
Every whole-model write path (`insert()`, `insert_many()`, `save()`, `replace()`, `upsert()`) shares this boundary check. Models can opt out with the `validate_writes=False` class kwarg — the escape hatch for performance-critical bulk writes; see [Configuration](configuration.md).
265
265
266
266
### `replace`
267
267
@@ -323,6 +323,8 @@ with update_by_ids() or a query condition instead.
323
323
324
324
```
325
325
326
+
Per-value validation, merged-result validation, and the `extra_keys=` escape are shared by every update verb and covered in [The shared update contract](#the-shared-update-contract) below.
327
+
326
328
`update()` requires a condition. TinyDB's own `update()` treats a bare call as "update every document"; tinydantic raises [SelectorError][tinydantic.SelectorError] and names the two explicit spellings, so a dropped condition can never quietly rewrite the whole table:
327
329
328
330
```pycon
@@ -367,7 +369,7 @@ Updating every document is spelled [update_all()][tinydantic.TinydanticModel.upd
367
369
368
370
```
369
371
370
-
Mappings and transform callables get exactly the treatment `update()` gives them — per-value validation, merged-result validation, atomic all-or-nothing writes, and the same `extra_keys=` escape (all described below).
372
+
Mappings and transform callables get exactly the treatment `update()` gives them — per-value validation, merged-result validation, atomic all-or-nothing writes, and the same `extra_keys=` escape. See [The shared update contract](#the-shared-update-contract).
371
373
372
374
### `update_many`
373
375
@@ -396,6 +398,10 @@ Pairs may use conditions on `Book.id` (see [Queries](queries.md)) and mix them f
396
398
397
399
```
398
400
401
+
### The shared update contract
402
+
403
+
Everything below holds for all five update verbs — [update()][tinydantic.TinydanticModel.update], [update_by_ids()][tinydantic.TinydanticModel.update_by_ids], [update_all()][tinydantic.TinydanticModel.update_all], [update_many()][tinydantic.TinydanticModel.update_many], and [FindQuery.update()][tinydantic.FindQuery.update]. The examples use `update()` because it is the shortest spelling; the contract is the same for each.
404
+
399
405
Field values in the mapping get the same treatment `insert()` and `save()` give whole models: each value is validated against its field's type and serialized to a JSON-safe primitive before it reaches storage. A rich value such as a `datetime` lands in storage as the same ISO string an `insert()` would have written:
400
406
401
407
```pycon
@@ -453,7 +459,7 @@ tinydantic._errors.UnknownUpdateFieldError: update() mapping for 'Book' ...
453
459
454
460
> [!NOTE]
455
461
>
456
-
> Keys written via `extra_keys="allow"` are stored **unvalidated** (pydantic ignores keys it does not know), and stored extra keys are likewise ignored — but preserved — when updates validate merged documents. Models can opt out of merged-result validation entirely with the `validate_writes=False` class kwarg; per-field value validation (the `datetime` example above) always applies to mappings. `update()`, `update_all()`, and `update_many()` also do **not** enforce [unique fields](models.md#unique-fields) — they are the deliberate loose path; every other write verb checks uniqueness. Never pass a raw request payload through `extra_keys="allow"` — see [Security considerations](security.md#untrusted-input-in-updates).
462
+
> Keys written via `extra_keys="allow"` are stored **unvalidated** (pydantic ignores keys it does not know), and stored extra keys are likewise ignored — but preserved — when updates validate merged documents. Models can opt out of merged-result validation entirely with the `validate_writes=False` class kwarg; per-field value validation (the `datetime` example above) always applies to mappings. No update verb enforces [unique fields](models.md#unique-fields) — they are the deliberate loose path. Uniqueness is checked by the six writes that carry a model instance: `insert()`, `insert_many()`, `save()`, `replace()`, `patch()`, and `upsert()`. Never pass a raw request payload through `extra_keys="allow"` — see [Security considerations](security.md#untrusted-input-in-updates).
An empty `patch()` writes nothing but still verifies the document exists, so its error behavior does not depend on the payload — handy for HTTP PATCH endpoints fed `model_dump(exclude_unset=True)`. Being instance-level, `patch()` fires [before_write()][tinydantic.TinydanticModel.before_write], so a model that stamps `updated_at` in the hook keeps stamping it here — an empty patch writes nothing and so hooks nothing. The table-level `update()` and`update_all()` below have no instance and fire no hook; see [Lifecycle hooks](models.md#lifecycle-hooks).
500
+
An empty `patch()` writes nothing but still verifies the document exists, so its error behavior does not depend on the payload — handy for HTTP PATCH endpoints fed `model_dump(exclude_unset=True)`. Being instance-level, `patch()` fires [before_write()][tinydantic.TinydanticModel.before_write], so a model that stamps `updated_at` in the hook keeps stamping it here — an empty patch writes nothing and so hooks nothing. The five update verbs above (`update()`, `update_by_ids()`,`update_all()`, `update_many()`, and `FindQuery.update()`) hold no instance and fire no hook; see [Lifecycle hooks](models.md#lifecycle-hooks).
Copy file name to clipboardExpand all lines: docs/usage/fastapi.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -129,7 +129,7 @@ The trade to understand: a blocking call on the event loop stalls _all_ request
129
129
> Two easy ways to break Pattern A's guarantee, both of which reintroduce the threadpool:
130
130
>
131
131
> -**Plain `def` endpoints.** FastAPI runs those in a _multi-threaded_ pool — several can run at once, racing on the database. If a handler touches `tinydantic`, make it `async def`.
132
-
> -**`asyncio.to_thread` / `run_in_threadpool`.**Wrapping calls this way sends them to the same multi-threaded pool. Don't offload `tinydantic` calls piecemeal; if the loop stall genuinely hurts, adopt Pattern B wholesale.
132
+
> -**`asyncio.to_thread` / `run_in_threadpool`.**Both send the call to a multi-threaded pool — `run_in_threadpool` (from Starlette) to the same AnyIO worker pool that runs plain `def` endpoints, `asyncio.to_thread` to the event loop's default `ThreadPoolExecutor`. Either way several database calls can run at once, and mixing the two makes it worse: the two pools interleave with each other as well. Don't offload `tinydantic` calls piecemeal; if the loop stall genuinely hurts, adopt Pattern B wholesale.
133
133
134
134
### Pattern B: one dedicated database thread
135
135
@@ -178,7 +178,7 @@ As rough guidance: an operation stalling the loop for 1 ms caps you around a tho
178
178
179
179
### Concurrent _requests_ still interleave
180
180
181
-
Both patterns serialize database _operations_; neither serializes _user intent_. Two users can still load the same document into edit forms and submit conflicting saves minutes apart — no threads involved, just time. That is what `use_revision=True` optimistic concurrency is for, including the `ETag` / `If-Match` / `412` flow for exactly this API shape — see [Concurrency](concurrency.md#optimistic-concurrency-use_revision). And for partial updates, prefer [patch()][tinydantic.TinydanticModel.patch]: `user.patch(**payload.model_dump(exclude_unset=True))` writes only the named fields, so concurrent edits to unrelated fields survive. Like the other instance-level writes, `patch()` fires [before_write()][tinydantic.TinydanticModel.before_write], so audit timestamps stamped in that hook keep working on PATCH endpoints — the table-level `update()` and`update_all()` are the ones that fire no hook.
181
+
Both patterns serialize database _operations_; neither serializes _user intent_. Two users can still load the same document into edit forms and submit conflicting saves minutes apart — no threads involved, just time. That is what `use_revision=True` optimistic concurrency is for, including the `ETag` / `If-Match` / `412` flow for exactly this API shape — see [Concurrency](concurrency.md#optimistic-concurrency-use_revision). And for partial updates, prefer [patch()][tinydantic.TinydanticModel.patch]: `user.patch(**payload.model_dump(exclude_unset=True))` writes only the named fields, so concurrent edits to unrelated fields survive. Like the other instance-level writes, `patch()` fires [before_write()][tinydantic.TinydanticModel.before_write], so audit timestamps stamped in that hook keep working on PATCH endpoints — the five update verbs (`update()`, `update_by_ids()`,`update_all()`, `update_many()`, and `FindQuery.update()`) are the ones that fire no hook.
182
182
183
183
**Run a single process.** Never put a TinyDB file behind multiple workers (`uvicorn --workers 4`, Gunicorn workers) — each process rewrites the whole file from its own view and they destroy each other's writes. Add [ProcessLockMiddleware][tinydantic.tinydb.middlewares.ProcessLockMiddleware] to your storage so that misconfiguration fails at startup instead of corrupting slowly.
@@ -148,7 +148,7 @@ Sort keys are **Python field names** (what you would pass to `getattr`), with a
148
148
149
149
```
150
150
151
-
Ties preserve document order (Python's sort is stable), so equal-key documents come out in doc-id order. And because sorting runs on **validated model instances** — never on raw stored bodies — a `datetime` field compares chronologically, custom types compare by their real values, and every field is guaranteed to exist.
151
+
Ties preserve table order (Python's sort is stable), so equal-key documents come out in the order the table holds them. That is usually ascending doc-id order, but not by guarantee: an `insert()` with an explicit lower id, or a `save()` that re-inserts a [vanished document](crud.md#sharp-edge-save-vs-replacedelete-on-a-vanished-document), appends at the end. Add an explicit tiebreaker (`sort("age", "id")`) when the order of equal keys matters. And because sorting runs on **validated model instances** — never on raw stored bodies — a `datetime` field compares chronologically, custom types compare by their real values, and every field is guaranteed to exist.
152
152
153
153
An unknown name fails at the `.sort()` call itself, not three stack frames later at the terminal, and storage aliases are not sort keys — the attribute name is:
154
154
@@ -228,7 +228,7 @@ Every terminal answers about the same windowed, ordered result that [all()][tiny
tinydantic._errors.DocumentNotFoundError: No 'User' document in table 'users'
296
+
tinydantic._errors.DocumentNotFoundError: No document matching the given query in table 'users' (model 'User')
297
297
298
298
```
299
299
300
300
## When a chain is overkill
301
301
302
-
A one-shot condition read needs no chain: [search()][tinydantic.TinydanticModel.search], [get()][tinydantic.TinydanticModel.get], [count()][tinydantic.TinydanticModel.count], and [contains()][tinydantic.TinydanticModel.contains] remain the direct spellings, and `find(cond).all()` is exactly `search(cond)`. Reach for `find()` when ordering, windowing, or a reusable base query enters the picture — the conditions themselves are the same ones described on the [Queries](queries.md) page, including [querying by id](queries.md).
302
+
A one-shot condition read needs no chain: [search()][tinydantic.TinydanticModel.search], [get()][tinydantic.TinydanticModel.get], [count()][tinydantic.TinydanticModel.count], and [contains()][tinydantic.TinydanticModel.contains] remain the direct spellings, and `find(cond).all()` is exactly `search(cond)`. Reach for `find()` when ordering, windowing, or a reusable base query enters the picture — the conditions themselves are the same ones described on the [Queries](queries.md) page, including [querying by id](queries.md#querying-by-id).
0 commit comments