tinydantic 0.3.1__tar.gz → 0.4.0__tar.gz

{tinydantic-0.3.1 → tinydantic-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinydantic
-Version: 0.3.1
+Version: 0.4.0
 Summary: A Pydantic-powered ODM (object-document mapper) for TinyDB
 Keywords: odm,pydantic,tinydb
 Author: Chris Wilson
@@ -13,6 +13,7 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: Pydantic :: 2
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -20,7 +21,6 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: Programming Language :: Python
 Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed

{tinydantic-0.3.1 → tinydantic-0.4.0}/pyproject.toml

@@ -4,22 +4,31 @@
 
 #:schema https://json.schemastore.org/pyproject.json
 
-[build-system]
-build-backend = "uv_build"
-requires = [
-  "uv_build>=0.11,<0.12",
-]
-
 [project]
+name = "tinydantic"
+version = "0.4.0"
+description = "A Pydantic-powered ODM (object-document mapper) for TinyDB"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0 OR MIT"
+license-files = [
+  "LICENSES/*",
+]
 authors = [
   { name = "Chris Wilson", email = "christopher.david.wilson@gmail.com" },
 ]
+keywords = [
+  "odm",
+  "pydantic",
+  "tinydb",
+]
 # https://pypi.org/classifiers/
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Framework :: Pydantic :: 2",
   "Intended Audience :: Developers",
   "Operating System :: OS Independent",
+  "Programming Language :: Python",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
@@ -27,7 +36,6 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
   "Programming Language :: Python :: Implementation :: CPython",
-  "Programming Language :: Python",
   "Topic :: Database",
   "Topic :: Software Development :: Libraries",
   "Typing :: Typed",
@@ -37,20 +45,6 @@ dependencies = [
   "pydantic[email]>=2.11",
   "tinydb>=4.8",
 ]
-description = "A Pydantic-powered ODM (object-document mapper) for TinyDB"
-keywords = [
-  "odm",
-  "pydantic",
-  "tinydb",
-]
-license = "Apache-2.0 OR MIT"
-license-files = [
-  "LICENSES/*",
-]
-name = "tinydantic"
-readme = "README.md"
-requires-python = ">=3.10"
-version = "0.3.1"
 
 [project.urls]
 Changelog = "https://github.com/tinydantic/tinydantic/blob/main/CHANGELOG.md"
@@ -109,11 +103,11 @@ test = [
   "httpx2",
   "packaging",
   "poethepoet",
+  "pytest>=8",
   "pytest-cov",
   "pytest-randomly",
   "pytest-rerunfailures",
   "pytest-xdist",
-  "pytest>=8",
 ]
 types = [
   "mypy>=1.14",
@@ -121,6 +115,20 @@ types = [
   "types-PyYAML",
 ]
 
+[build-system]
+requires = [
+  "uv_build>=0.11,<0.12",
+]
+build-backend = "uv_build"
+
+[tool.commitizen]
+annotated_tag = true
+major_version_zero = true
+name = "cz_conventional_commits"
+tag_format = "v$version"
+version_provider = "pep621"
+version_scheme = "semver2"
+
 [tool.coverage.run]
 branch = true
 parallel = true
@@ -146,13 +154,17 @@ exclude_lines = [
   "no cov",
 ]
 
-[tool.commitizen]
-annotated_tag = true
-major_version_zero = true
-name = "cz_conventional_commits"
-tag_format = "v$version"
-version_provider = "pep621"
-version_scheme = "semver2"
+[tool.interrogate]
+fail-under = 100
+ignore-overloaded-functions = true
+ignore-private = true
+ignore-semiprivate = true
+omit-covered-files = true
+style = "google"
+verbose = 2
+
+[tool.mypy]
+python_version = "3.10"
 
 [tool.poe.tasks]
 clean = "pyclean . --debris --verbose"
@@ -170,9 +182,24 @@ sbom-check = "reuse lint"
 spell-check = "npx cspell --gitignore --dot ."
 test = "pytest"
 test-cov = "pytest --cov --cov-branch"
+# Each step syncs an ephemeral environment from uv.lock for one
+# supported Python version (--isolated leaves .venv untouched) and
+# runs test-cov in it, writing a per-version COVERAGE_FILE that the
+# final coverage steps merge into one cross-version report.
+test-matrix = [
+  "_test-py310",
+  "_test-py311",
+  "_test-py312",
+  "_test-py313",
+  "_test-py314",
+  "_coverage-combine",
+  "_coverage-report",
+]
 types = "mypy --install-types --non-interactive src/tinydantic tests"
 update-project-words = { shell = "npx cspell --gitignore --dot --words-only --unique . | sort --ignore-case >> project-words.txt" }
 
+_coverage-combine = "coverage combine .coverage.py310 .coverage.py311 .coverage.py312 .coverage.py313 .coverage.py314"
+_coverage-report = "coverage report"
 _ruff-check = "ruff check ."
 _ruff-fix = "ruff check --fix ."
 _ruff-format = "ruff format ."
@@ -206,17 +233,25 @@ env = { PYTHONUNBUFFERED = "1", SOURCE_DATE_EPOCH = "1580601600" }
 cmd = "properdocs serve --config-file mkdocs.yaml --dev-addr localhost:8000"
 env = { PYTHONUNBUFFERED = "1" }
 
-[tool.interrogate]
-fail-under = 100
-ignore-overloaded-functions = true
-ignore-private = true
-ignore-semiprivate = true
-omit-covered-files = true
-style = "google"
-verbose = 2
+[tool.poe.tasks._test-py310]
+cmd = "uv run --isolated --python 3.10 --group test poe test-cov"
+env = { COVERAGE_FILE = ".coverage.py310" }
 
-[tool.mypy]
-python_version = "3.10"
+[tool.poe.tasks._test-py311]
+cmd = "uv run --isolated --python 3.11 --group test poe test-cov"
+env = { COVERAGE_FILE = ".coverage.py311" }
+
+[tool.poe.tasks._test-py312]
+cmd = "uv run --isolated --python 3.12 --group test poe test-cov"
+env = { COVERAGE_FILE = ".coverage.py312" }
+
+[tool.poe.tasks._test-py313]
+cmd = "uv run --isolated --python 3.13 --group test poe test-cov"
+env = { COVERAGE_FILE = ".coverage.py313" }
+
+[tool.poe.tasks._test-py314]
+cmd = "uv run --isolated --python 3.14 --group test poe test-cov"
+env = { COVERAGE_FILE = ".coverage.py314" }
 
 [tool.pytest.ini_options]
 addopts = "--doctest-modules --doctest-glob '*.md'"

{tinydantic-0.3.1 → tinydantic-0.4.0}/src/tinydantic/_errors.py

@@ -61,16 +61,42 @@ class AmbiguousConfigError(TinydanticUserError):
 
 
 class DocumentNotFoundError(TinydanticError):
-    """Requested document is not found."""
+    """Requested document is not found.
 
-    def __init__(self) -> None:
-        """Initialize with the "Document not found" message."""
-        super().__init__("Document not found")
+    The message names the model, the table, and — when the lookup was
+    by id — the missing document id, so the error is actionable
+    without a debugger.
+    """
+
+    def __init__(
+        self,
+        *,
+        model_name: str,
+        table_name: str,
+        doc_id: int | None = None,
+    ) -> None:
+        """Initialize with the model, table, and optional id context."""
+        if doc_id is not None:
+            selector = f"with id {doc_id}"
+        else:
+            selector = "matching the given query"
+        super().__init__(
+            f"No document {selector} in table {table_name!r} "
+            f"(model {model_name!r})",
+        )
 
 
 class DocumentIDRequiredError(TinydanticError):
-    """Required document ID is missing."""
+    """Required document ID is missing.
+
+    Raised by instance operations that address a stored document by
+    its id (``replace()``, ``delete()``) when the instance was never
+    inserted, so its ``id`` is still ``None``.
+    """
 
-    def __init__(self) -> None:
-        """Initialize with the "Document ID is required" message."""
-        super().__init__("Document ID is required")
+    def __init__(self, *, model_name: str, operation: str) -> None:
+        """Initialize with the model name and attempted operation."""
+        super().__init__(
+            f"Cannot {operation}() a {model_name!r} instance whose id "
+            "is None — insert() or save() it first",
+        )

{tinydantic-0.3.1 → tinydantic-0.4.0}/src/tinydantic/_model.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, ClassVar, cast, overload
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
 from pydantic.alias_generators import to_snake
 from tinydb.queries import Query, where
 from tinydb.table import Document, Table
@@ -44,9 +44,13 @@ if TYPE_CHECKING:
 else:
     ModelMetaclass = type(BaseModel)
 
+# Name of the per-class attribute caching per-field TypeAdapters
+# (built lazily by _field_adapter for update() serialization).
+_FIELD_ADAPTERS_ATTR = "__tinydantic_field_adapters__"
+
 
 def q(field: Any) -> Query:
-    """Tell the type checker a field expression is a TinyDB Query.
+    """Build a typed TinyDB Query from a field or a field name.
 
     At runtime, class-level field access like ``User.name`` already
     returns a [Query][tinydb.queries.Query] (courtesy of the model
@@ -59,21 +63,36 @@ def q(field: Any) -> Query:
     User.search(q(User.name) == "Alice")
     ```
 
+    A string builds a query on that document key
+    (``tinydb.queries.where``). This is the escape hatch for fields
+    whose names collide with model methods (``search``, ``get``,
+    ``count``, ...) and are therefore unreachable through the
+    ``Model.field`` shorthand:
+
+    ```python
+    Command.search(q("search") == "fuzzy")
+    ```
+
     Args:
-        field: A class-level field expression (e.g. ``User.name``).
+        field: A class-level field expression (e.g. ``User.name``)
+            or a field name string (e.g. ``"name"``).
 
     Returns:
-        The same object, typed as a Query.
+        The field expression unchanged, or a Query on the named
+        field — either way, typed as a Query.
 
     Raises:
-        TypeError: If ``field`` is not actually a TinyDB Query — for
-            example when called with an instance attribute or a plain
-            string instead of class-level field access.
+        TypeError: If ``field`` is neither a TinyDB Query nor a
+            string — for example when called with an instance
+            attribute instead of class-level field access.
     """
+    if isinstance(field, str):
+        return where(field)
     if not isinstance(field, Query):
         msg = (
             f"q() expected a TinyDB Query (class-level field access "
-            f"like Model.field), got {type(field).__name__!r}"
+            f"like Model.field) or a field name string, got "
+            f"{type(field).__name__!r}"
         )
         raise TypeError(msg)
     return field
@@ -270,24 +289,30 @@ class TinydanticModel(BaseModel, metaclass=TinydanticModelMetaclass):
         return instance
 
     @classmethod
-    def insert_multiple(cls, documents: Iterable[Self]) -> list[int]:
+    def insert_multiple(cls, documents: Iterable[Self]) -> list[Self]:
         """Insert several models at once.
 
         Serializes each model with
         [to_tinydb_document][tinydantic.TinydanticModel.to_tinydb_document]
-        and hands them to [tinydb.table.Table.insert_multiple][]. The
-        models' own ``id`` attributes are NOT updated in place; the
-        assigned document ids are returned instead.
+        and hands them to [tinydb.table.Table.insert_multiple][].
+        Exactly like [insert][tinydantic.TinydanticModel.insert], each
+        model's ``id`` is set in place to the document id TinyDB
+        assigned, and the same instances are returned in insertion
+        order.
 
         Args:
             documents: The models to insert.
 
         Returns:
-            The ids of the inserted documents, in insertion order.
+            The inserted models, with ``id`` set, in insertion order.
         """
-        return cls.get_table().insert_multiple(
-            [doc.to_tinydb_document() for doc in documents],
+        docs = list(documents)
+        doc_ids = cls.get_table().insert_multiple(
+            [doc.to_tinydb_document() for doc in docs],
         )
+        for doc, doc_id in zip(docs, doc_ids, strict=True):
+            doc.id = doc_id
+        return docs
 
     @classmethod
     def all(cls) -> list[Self]:
@@ -387,6 +412,58 @@ class TinydanticModel(BaseModel, metaclass=TinydanticModelMetaclass):
         """Get documents for the given ids (see get() for semantics)."""
         return cls.get(doc_ids=doc_ids)
 
+    @overload
+    @classmethod
+    def get_or_raise(cls, cond: QueryLike) -> Self: ...
+
+    @overload
+    @classmethod
+    def get_or_raise(cls, *, doc_id: int) -> Self: ...
+
+    @classmethod
+    def get_or_raise(
+        cls,
+        cond: QueryLike | None = None,
+        *,
+        doc_id: int | None = None,
+    ) -> Self:
+        """Get one document, raising instead of returning ``None``.
+
+        The strict counterpart to
+        [get][tinydantic.TinydanticModel.get] for call sites where a
+        missing document is an error rather than an expected outcome
+        (request handlers, lookups by known id, ...). Accepts exactly
+        one selector: a query condition or a ``doc_id``. There is no
+        ``doc_ids`` form — TinyDB silently skips missing ids in bulk
+        gets, so "raise if missing" has no single obvious meaning
+        there.
+
+        Args:
+            cond: The query condition to match.
+            doc_id: The document id to fetch.
+
+        Returns:
+            The validated model instance.
+
+        Raises:
+            DocumentNotFoundError: If no matching document exists.
+            ValueError: If no selector or both selectors are provided.
+        """
+        if cond is not None and doc_id is None:
+            result = cls.get(cond)
+        elif doc_id is not None and cond is None:
+            result = cls.get(doc_id=doc_id)
+        else:
+            msg = "Provide exactly one of cond or doc_id"
+            raise ValueError(msg)
+        if result is None:
+            raise DocumentNotFoundError(
+                model_name=cls.__name__,
+                table_name=cls.get_table().name,
+                doc_id=doc_id,
+            )
+        return result
+
     @classmethod
     def contains(
         cls,
@@ -404,6 +481,56 @@ class TinydanticModel(BaseModel, metaclass=TinydanticModelMetaclass):
             raise ValueError(msg)
         return cls.get_table().contains(cond=cond, doc_id=doc_id)
 
+    @classmethod
+    def _field_adapter(cls, field_name: str) -> TypeAdapter[Any]:
+        """Get (or build and cache) a TypeAdapter for a model field.
+
+        The adapter is built from the field's full annotation
+        (including ``Field(...)`` metadata, via
+        [rebuild_annotation][pydantic.fields.FieldInfo.rebuild_annotation])
+        and cached on this class, so repeated ``update()`` calls pay
+        the construction cost once per field.
+        """
+        adapters: dict[str, TypeAdapter[Any]] | None = cls.__dict__.get(
+            _FIELD_ADAPTERS_ATTR,
+        )
+        if adapters is None:
+            adapters = {}
+            setattr(cls, _FIELD_ADAPTERS_ATTR, adapters)
+        adapter = adapters.get(field_name)
+        if adapter is None:
+            field_info = cls.model_fields[field_name]
+            adapter = TypeAdapter(field_info.rebuild_annotation())
+            adapters[field_name] = adapter
+        return adapter
+
+    @classmethod
+    def _serialize_update_fields(cls, fields: Mapping) -> dict[str, Any]:
+        """Validate and JSON-serialize known field values in a mapping.
+
+        Each key that names a model field has its value validated
+        against that field's type and serialized in JSON mode — the
+        same treatment ``insert()``/``save()`` give whole models — so
+        rich values (datetime, UUID, nested models, ...) land in
+        storage as JSON-safe primitives. Keys that are not model
+        fields pass through unchanged.
+
+        Raises:
+            pydantic.ValidationError: If a value fails validation
+                against its field's type.
+        """
+        serialized: dict[str, Any] = {}
+        for key, value in fields.items():
+            if key in cls.model_fields:
+                adapter = cls._field_adapter(key)
+                serialized[key] = adapter.dump_python(
+                    adapter.validate_python(value),
+                    mode="json",
+                )
+            else:
+                serialized[key] = value
+        return serialized
+
     @classmethod
     def update(
         cls,
@@ -414,15 +541,23 @@ class TinydanticModel(BaseModel, metaclass=TinydanticModelMetaclass):
     ) -> list[int]:
         """Update matching documents with new fields or a transform.
 
-        Unlike ``insert``/``save``/``upsert``, the ``fields`` mapping
-        is passed to storage as-is — values are NOT serialized through
-        pydantic. Pass JSON-safe primitives (e.g.
-        ``datetime.isoformat()`` strings), or use a validated
-        instance's ``save()``/``replace()`` for full-model updates.
+        A ``fields`` mapping gets the same treatment ``insert()`` and
+        ``save()`` give whole models: each value that belongs to a
+        model field is validated against that field's type and
+        serialized to a JSON-safe primitive before it reaches storage
+        (keys that are not model fields pass through unchanged). A
+        transform callable is handed to TinyDB as-is — what it writes
+        is up to you.
 
         Returns:
             The ids of all updated documents.
+
+        Raises:
+            pydantic.ValidationError: If a mapping value fails
+                validation against its field's type.
         """
+        if not callable(fields):
+            fields = cls._serialize_update_fields(fields)
         return cls.get_table().update(
             # See replace() for why this cast is needed.
             # TODO @cdwilson: remove this cast once the annotation is
@@ -444,20 +579,31 @@ class TinydanticModel(BaseModel, metaclass=TinydanticModelMetaclass):
     ) -> list[int]:
         """Apply several (fields_or_transform, cond) updates at once.
 
-        Unlike ``insert``/``save``/``upsert``, each update's fields
-        mapping is passed to storage as-is — values are NOT serialized
-        through pydantic. Pass JSON-safe primitives (e.g.
-        ``datetime.isoformat()`` strings), or use a validated
-        instance's ``save()``/``replace()`` for full-model updates.
+        Each update's fields mapping is validated and serialized
+        exactly as in [update][tinydantic.TinydanticModel.update];
+        transform callables pass through to TinyDB as-is.
 
         Returns:
             The ids of all updated documents.
+
+        Raises:
+            pydantic.ValidationError: If a mapping value fails
+                validation against its field's type.
         """
+        prepared = [
+            (
+                fields
+                if callable(fields)
+                else cls._serialize_update_fields(fields),
+                cond,
+            )
+            for fields, cond in updates
+        ]
         return cls.get_table().update_multiple(
             # See replace() for why this cast is needed.
             cast(
                 "Iterable[tuple[Callable[[Mapping], None], QueryLike]]",
-                updates,
+                prepared,
             ),
         )
 
@@ -501,17 +647,24 @@ class TinydanticModel(BaseModel, metaclass=TinydanticModelMetaclass):
         cls.get_table().truncate()
 
     @classmethod
-    def count(cls, cond: QueryLike) -> int:
-        """Count the documents matching ``cond``.
+    def count(cls, cond: QueryLike | None = None) -> int:
+        """Count the documents matching ``cond``, or all documents.
 
-        Delegates to [tinydb.table.Table.count][].
+        With a condition, delegates to [tinydb.table.Table.count][].
+        Without one, returns the total number of documents in the
+        table (``len(table)``) — TinyDB itself spells this
+        ``len(db.table(...))``; tinydantic folds it into ``count()``
+        so "how many documents are there?" needs no query object.
 
         Args:
-            cond: The query condition to match.
+            cond: The query condition to match. When omitted, every
+                document in the table is counted.
 
         Returns:
-            The number of matching documents.
+            The number of matching (or total) documents.
         """
+        if cond is None:
+            return len(cls.get_table())
         return cls.get_table().count(cond)
 
     @classmethod
@@ -590,7 +743,10 @@ class TinydanticModel(BaseModel, metaclass=TinydanticModelMetaclass):
                 exists in the table.
         """
         if self.id is None:
-            raise DocumentIDRequiredError
+            raise DocumentIDRequiredError(
+                model_name=type(self).__name__,
+                operation="replace",
+            )
 
         try:
             updated_doc_ids = self.get_table().update(
@@ -614,10 +770,18 @@ class TinydanticModel(BaseModel, metaclass=TinydanticModelMetaclass):
                 doc_ids=[self.id],
             )
         except KeyError:
-            raise DocumentNotFoundError from None
+            raise DocumentNotFoundError(
+                model_name=type(self).__name__,
+                table_name=self.get_table().name,
+                doc_id=self.id,
+            ) from None
 
         if not updated_doc_ids:
-            raise DocumentNotFoundError
+            raise DocumentNotFoundError(
+                model_name=type(self).__name__,
+                table_name=self.get_table().name,
+                doc_id=self.id,
+            )
 
     def delete(self) -> None:
         """Remove this model's document from its table.
@@ -629,13 +793,24 @@ class TinydanticModel(BaseModel, metaclass=TinydanticModelMetaclass):
                 exists in the table.
         """
         if self.id is None:
-            raise DocumentIDRequiredError
+            raise DocumentIDRequiredError(
+                model_name=type(self).__name__,
+                operation="delete",
+            )
         try:
             removed = self.get_table().remove(doc_ids=[self.id])
         except KeyError:
-            raise DocumentNotFoundError from None
+            raise DocumentNotFoundError(
+                model_name=type(self).__name__,
+                table_name=self.get_table().name,
+                doc_id=self.id,
+            ) from None
         if not removed:
-            raise DocumentNotFoundError
+            raise DocumentNotFoundError(
+                model_name=type(self).__name__,
+                table_name=self.get_table().name,
+                doc_id=self.id,
+            )
 
     def save(self) -> Self:
         """Insert this model if it is new, otherwise update it by id.