tinydantic 0.1.19__tar.gz → 0.3.0__tar.gz

tinydantic-0.3.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: tinydantic
+Version: 0.3.0
+Summary: A Pydantic-powered ODM (object-document mapper) for TinyDB
+Keywords: odm,pydantic,tinydb
+Author: Chris Wilson
+Author-email: Chris Wilson <christopher.david.wilson@gmail.com>
+License-Expression: Apache-2.0 OR MIT
+License-File: LICENSES/Apache-2.0.txt
+License-File: LICENSES/CC-BY-4.0.txt
+License-File: LICENSES/MIT.txt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+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
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic[email]>=2.11
+Requires-Dist: tinydb>=4.8
+Requires-Python: >=3.10
+Project-URL: Changelog, https://github.com/tinydantic/tinydantic/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://tinydantic.dev
+Project-URL: Issues, https://github.com/tinydantic/tinydantic/issues
+Project-URL: Source, https://github.com/tinydantic/tinydantic
+Description-Content-Type: text/markdown
+
+# tinydantic
+
+<!-- overview-start -->
+
+[![PyPI - Version](https://img.shields.io/pypi/v/tinydantic.svg)](https://pypi.org/project/tinydantic) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/tinydantic.svg)](https://pypi.org/project/tinydantic) [![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json)](https://pydantic.dev)
+
+`tinydantic` is a simple Python object-document mapper (ODM) for the [TinyDB](https://tinydb.readthedocs.io/en/latest/) document database. It uses [Pydantic](https://docs.pydantic.dev/latest/)—the most widely used data validation library—for document model definition and validation.
+
+<!-- prettier-ignore-start -->
+
+> [!NOTE]
+> `tinydantic` is an experimental project under active development and should not be considered stable for use in a production environment.
+>
+> Releases follow the [SemVer versioning spec](https://semver.org):
+>
+> > Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.
+>
+> Minor releases may include breaking changes until v1.0 — check the [changelog](https://github.com/tinydantic/tinydantic/blob/main/CHANGELOG.md) when upgrading.
+>
+> **AI Disclaimer**
+>
+> I started thinking about the idea for this project after discovering TinyDB a couple years ago. However, I never had the time (or a real use case) to finish the implementation. With the release of [Claude Fable 5](https://www.anthropic.com/claude/fable), it seemed like a good opportunity to revisit this idea and try to get an initial prototype of this working with the help of AI. I'm currently experimenting with the implementation generated by Claude to understand what works well and what needs further improvement.
+>
+> I am *not* a NoSQL database expert and it's very possible that there are better implementations and/or interfaces than what Claude has produced in this initial prototype. If you find things that are broken, awkward, missing, or don't follow best practices, please feel free to open an issue or a PR to suggest changes. Feedback is welcome!
+
+<!-- prettier-ignore-end -->
+
+<!-- overview-end -->
+
+Full documentation — including a [quickstart](https://tinydantic.dev/latest/usage/quickstart/) that walks through a complete create-read-update-delete example — is available at [tinydantic.dev](https://tinydantic.dev).
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Introduction](#introduction)
+- [License](#license)
+
+## Introduction
+
+<!-- introduction-start -->
+
+`tinydantic` is a wrapper library around [TinyDB](https://tinydb.readthedocs.io/en/latest/) that enables using [Pydantic](https://docs.pydantic.dev/) models to manage documents stored in a TinyDB database. By specifying Python type annotations for each field in a document model, data validation is handled automatically by Pydantic when instantiating a model from the database.
+
+<!-- introduction-end -->
+
+## Installation
+
+<!-- installation-start -->
+
+`tinydantic` is [available on PyPI](https://pypi.org/project/tinydantic/) and can be installed with [pip](https://github.com/pypa/pip). Easy peasy lemon squeezy 🍋
+
+```sh
+pip install tinydantic
+```
+
+<!-- installation-end -->
+
+## License
+
+See the [LICENSE](https://github.com/tinydantic/tinydantic/blob/main/LICENSE.md) file for copyright & license information.

tinydantic-0.3.0/README.md

@@ -0,0 +1,60 @@
+# tinydantic
+
+<!-- overview-start -->
+
+[![PyPI - Version](https://img.shields.io/pypi/v/tinydantic.svg)](https://pypi.org/project/tinydantic) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/tinydantic.svg)](https://pypi.org/project/tinydantic) [![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json)](https://pydantic.dev)
+
+`tinydantic` is a simple Python object-document mapper (ODM) for the [TinyDB](https://tinydb.readthedocs.io/en/latest/) document database. It uses [Pydantic](https://docs.pydantic.dev/latest/)—the most widely used data validation library—for document model definition and validation.
+
+<!-- prettier-ignore-start -->
+
+> [!NOTE]
+> `tinydantic` is an experimental project under active development and should not be considered stable for use in a production environment.
+>
+> Releases follow the [SemVer versioning spec](https://semver.org):
+>
+> > Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.
+>
+> Minor releases may include breaking changes until v1.0 — check the [changelog](https://github.com/tinydantic/tinydantic/blob/main/CHANGELOG.md) when upgrading.
+>
+> **AI Disclaimer**
+>
+> I started thinking about the idea for this project after discovering TinyDB a couple years ago. However, I never had the time (or a real use case) to finish the implementation. With the release of [Claude Fable 5](https://www.anthropic.com/claude/fable), it seemed like a good opportunity to revisit this idea and try to get an initial prototype of this working with the help of AI. I'm currently experimenting with the implementation generated by Claude to understand what works well and what needs further improvement.
+>
+> I am *not* a NoSQL database expert and it's very possible that there are better implementations and/or interfaces than what Claude has produced in this initial prototype. If you find things that are broken, awkward, missing, or don't follow best practices, please feel free to open an issue or a PR to suggest changes. Feedback is welcome!
+
+<!-- prettier-ignore-end -->
+
+<!-- overview-end -->
+
+Full documentation — including a [quickstart](https://tinydantic.dev/latest/usage/quickstart/) that walks through a complete create-read-update-delete example — is available at [tinydantic.dev](https://tinydantic.dev).
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Introduction](#introduction)
+- [License](#license)
+
+## Introduction
+
+<!-- introduction-start -->
+
+`tinydantic` is a wrapper library around [TinyDB](https://tinydb.readthedocs.io/en/latest/) that enables using [Pydantic](https://docs.pydantic.dev/) models to manage documents stored in a TinyDB database. By specifying Python type annotations for each field in a document model, data validation is handled automatically by Pydantic when instantiating a model from the database.
+
+<!-- introduction-end -->
+
+## Installation
+
+<!-- installation-start -->
+
+`tinydantic` is [available on PyPI](https://pypi.org/project/tinydantic/) and can be installed with [pip](https://github.com/pypa/pip). Easy peasy lemon squeezy 🍋
+
+```sh
+pip install tinydantic
+```
+
+<!-- installation-end -->
+
+## License
+
+See the [LICENSE](https://github.com/tinydantic/tinydantic/blob/main/LICENSE.md) file for copyright & license information.

tinydantic-0.3.0/pyproject.toml

@@ -0,0 +1,236 @@
+# SPDX-FileCopyrightText: Chris Wilson <christopher.david.wilson@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+
+#:schema https://json.schemastore.org/pyproject.json
+
+[build-system]
+build-backend = "uv_build"
+requires = [
+  "uv_build>=0.11,<0.12",
+]
+
+[project]
+authors = [
+  { name = "Chris Wilson", email = "christopher.david.wilson@gmail.com" },
+]
+# https://pypi.org/classifiers/
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Pydantic :: 2",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "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",
+]
+dependencies = [
+  "PyYAML>=6.0",
+  "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.0"
+
+[project.urls]
+Changelog = "https://github.com/tinydantic/tinydantic/blob/main/CHANGELOG.md"
+Documentation = "https://tinydantic.dev"
+Issues = "https://github.com/tinydantic/tinydantic/issues"
+Source = "https://github.com/tinydantic/tinydantic"
+
+[dependency-groups]
+dev = [
+  "check-jsonschema",
+  "commitizen",
+  "editorconfig-checker",
+  "interrogate",
+  "jsonschema[format]",
+  "poethepoet",
+  "pre-commit",
+  "pre-commit-ci-config",
+  "pyclean",
+  "reuse>=5.0.0",
+  { include-group = "docs" },
+  { include-group = "lint" },
+  { include-group = "test" },
+  { include-group = "types" },
+]
+docs = [
+  # black is used by separate_signature option in mkdocstrings-python
+  "black",
+  "fastapi",
+  "griffe",
+  "httpx2",
+  "linkchecker",
+  "markdown-callouts",
+  "markdown-gfm-admonition",
+  "mdx_truly_sane_lists",
+  "mike",
+  "mkdocs-awesome-pages-plugin",
+  "mkdocs-gen-files",
+  "mkdocs-github-admonitions-plugin",
+  "mkdocs-include-markdown-plugin",
+  "mkdocs-materialx",
+  "mkdocstrings",
+  "mkdocstrings-python",
+  "poethepoet",
+  # properdocs is the docs build engine. mike >=2.2.0 auto-detects it and
+  # runs properdocs for versioned deploys too. The mkdocs package remains
+  # installed only as a transitive dependency (mkdocs-materialx pins it for
+  # import compatibility).
+  "properdocs",
+]
+lint = [
+  "poethepoet",
+  "ruff>=0.14",
+]
+test = [
+  "fastapi",
+  "httpx2",
+  "packaging",
+  "poethepoet",
+  "pytest-cov",
+  "pytest-randomly",
+  "pytest-rerunfailures",
+  "pytest-xdist",
+  "pytest>=8",
+]
+types = [
+  "mypy>=1.14",
+  "packaging",
+  "types-PyYAML",
+]
+
+[tool.coverage.run]
+branch = true
+parallel = true
+source_pkgs = [
+  "tests",
+  "tinydantic",
+]
+
+[tool.coverage.paths]
+tests = [
+  "*/tinydantic/tests",
+  "tests",
+]
+tinydantic = [
+  "*/tinydantic/src/tinydantic",
+  "src/tinydantic",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+  "if TYPE_CHECKING:",
+  "if __name__ == .__main__.:",
+  "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.poe.tasks]
+clean = "pyclean . --debris --verbose"
+fmt = [
+  "_ruff-fix",
+  "_ruff-format",
+]
+lint = [
+  "_ruff-check",
+  "_ruff-format-check",
+]
+pre-commit = "pre-commit run --all-files --verbose"
+sbom = "reuse spdx -o reuse.spdx"
+sbom-check = "reuse lint"
+spell-check = "npx cspell --gitignore --dot ."
+test = "pytest"
+test-cov = "pytest --cov --cov-branch"
+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" }
+
+_ruff-check = "ruff check ."
+_ruff-fix = "ruff check --fix ."
+_ruff-format = "ruff format ."
+_ruff-format-check = "ruff format --check ."
+
+check = [
+  "lint",
+  "sbom-check",
+  "spell-check",
+  "types",
+]
+
+[tool.poe.tasks.docs-build]
+cmd = "properdocs build --config-file mkdocs.yaml --clean --strict"
+env = { PYTHONUNBUFFERED = "1", SOURCE_DATE_EPOCH = "1580601600" }
+
+[tool.poe.tasks.docs-build-check]
+sequence = [
+  { ref = "docs-build --no-directory-urls" },
+  { ref = "docs-check" },
+]
+
+[tool.poe.tasks.docs-check]
+cmd = "linkchecker --config .linkcheckerrc site"
+
+[tool.poe.tasks.docs-ci-publish]
+cmd = "mike deploy --config-file mkdocs.yaml --update-aliases --push"
+env = { PYTHONUNBUFFERED = "1", SOURCE_DATE_EPOCH = "1580601600" }
+
+[tool.poe.tasks.docs-serve]
+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.mypy]
+python_version = "3.10"
+
+[tool.pytest.ini_options]
+addopts = "--doctest-modules --doctest-glob '*.md' --ignore=docs/superpowers"
+doctest_optionflags = "NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL"
+filterwarnings = [
+  # The queries.md "shadowing" section deliberately defines a field named
+  # `search` to demonstrate the pitfall, so pydantic's warning is expected.
+  'ignore:Field name "search" in "Command" shadows an attribute in parent "TinydanticModel":UserWarning',
+]
+minversion = "6.0"
+testpaths = [
+  "CONTRIBUTING.md",
+  "README.md",
+  "docs",
+  "src",
+  "tests",
+]

tinydantic-0.3.0/src/tinydantic/__init__.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: Chris Wilson <christopher.david.wilson@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+
+"""`tinydantic` is a simple Python object-document mapper (ODM) for the
+[TinyDB](https://tinydb.readthedocs.io/en/latest/) document database.
+
+Attributes:
+    __version__: The `tinydantic` package version.
+"""  # noqa: D205
+
+from importlib import metadata
+
+from tinydantic._config import TinydanticConfig
+from tinydantic._errors import (
+    AmbiguousConfigError,
+    DatabaseNotBoundError,
+    DocumentIDRequiredError,
+    DocumentNotFoundError,
+    TinydanticError,
+    TinydanticUserError,
+)
+from tinydantic._model import TinydanticModel, q
+
+__version__: str = metadata.version("tinydantic")
+
+__all__ = [
+    "AmbiguousConfigError",
+    "DatabaseNotBoundError",
+    "DocumentIDRequiredError",
+    "DocumentNotFoundError",
+    "TinydanticConfig",
+    "TinydanticError",
+    "TinydanticModel",
+    "TinydanticUserError",
+    "__version__",
+    "q",
+]

tinydantic-0.3.0/src/tinydantic/_config.py

@@ -0,0 +1,137 @@
+# SPDX-FileCopyrightText: Chris Wilson <christopher.david.wilson@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+
+"""Configuration machinery for tinydantic models.
+
+Design note — why tinydantic config does NOT live in ``model_config``:
+
+Pydantic merges ``model_config`` across multiple base classes in
+"last wins" order — the *opposite* of Python's MRO (see
+https://github.com/pydantic/pydantic/issues/9992). Community fixes
+were rejected as breaking changes, and the behavior may change in
+pydantic v3. Storing tinydantic's keys there would (a) inherit those
+surprising semantics, (b) risk future key collisions with
+``ConfigDict``, and (c) couple binding resolution to behavior pydantic
+itself may flip.
+
+Instead, every model class stores only the config keys *explicitly set
+on it* in its own ``__tinydantic_config__`` class attribute, and
+lookup walks ``cls.__mro__`` for the first class that provides the
+key — standard Python attribute semantics. For the one scenario where
+pydantic's ordering and Python's ordering could disagree (two
+*unrelated* bases providing conflicting values), tinydantic refuses to
+guess and raises
+[AmbiguousConfigError][tinydantic.AmbiguousConfigError]
+at class-definition time instead.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypedDict
+
+from tinydantic._errors import AmbiguousConfigError
+
+if TYPE_CHECKING:
+    from tinydb import TinyDB
+
+# Name of the per-class attribute holding explicitly-set config.
+CONFIG_ATTR = "__tinydantic_config__"
+
+_CONFIG_KEYS = ("database", "table_name")
+
+
+class TinydanticConfig(TypedDict, total=False):
+    """Configuration options for tinydantic models.
+
+    This is a plain [TypedDict][typing.TypedDict] — deliberately NOT a
+    ``pydantic.ConfigDict`` subclass; see the module docstring for the
+    design rationale. Values are provided as class keyword arguments:
+
+    ```python
+    class User(TinydanticModel, database=db, table_name="users"):
+        name: str
+    ```
+    """
+
+    database: TinyDB
+    """TinyDB database where documents of this model are stored."""
+
+    table_name: str | None
+    """Database table name for documents of this model.
+
+    When unset (or falsy), the table name is derived from the model
+    class name converted to snake_case — for example, a model class
+    named ``AdminUser`` uses the table ``admin_user``.
+    """
+
+
+def get_config_value(
+    model_class: type,
+    key: str,
+    default: Any = None,
+) -> Any:
+    """Resolve a tinydantic config key for a model class.
+
+    Walks ``model_class.__mro__`` and returns the value from the first
+    class whose own ``__tinydantic_config__`` contains ``key`` —
+    standard Python attribute-lookup semantics, unlike pydantic's
+    ``model_config`` merge (see the module docstring).
+
+    Args:
+        model_class: The model class to resolve the key for.
+        key: The [TinydanticConfig][tinydantic.TinydanticConfig]
+            key to look up.
+        default: Value returned when no class in the MRO provides the
+            key.
+
+    Returns:
+        The resolved value, or ``default``.
+    """
+    for klass in model_class.__mro__:
+        config = klass.__dict__.get(CONFIG_ATTR)
+        if config is not None and key in config:
+            return config[key]
+    return default
+
+
+def check_config_ambiguity(model_class: type) -> None:
+    """Raise if unrelated bases supply conflicting config values.
+
+    For each config key not set on ``model_class`` itself, this checks
+    whether two classes in the MRO that are *not* part of one
+    inheritance chain (neither is a subclass of the other) provide
+    different values. Ordinary single-chain overrides — a subclass
+    overriding its parent — are never flagged.
+
+    Args:
+        model_class: The freshly created model class to validate.
+
+    Raises:
+        AmbiguousConfigError: If a genuine multi-base conflict exists.
+    """
+    own = model_class.__dict__.get(CONFIG_ATTR) or {}
+    for key in _CONFIG_KEYS:
+        if key in own:
+            continue
+        providers = [
+            klass
+            for klass in model_class.__mro__[1:]
+            if key in (klass.__dict__.get(CONFIG_ATTR) or {})
+        ]
+        if not providers[1:]:
+            continue
+        first = providers[0]
+        first_value = first.__dict__[CONFIG_ATTR][key]
+        for other in providers[1:]:
+            if issubclass(first, other):
+                # Normal override along one inheritance chain: the
+                # earlier (more derived) class legitimately wins.
+                continue
+            if first_value != other.__dict__[CONFIG_ATTR][key]:
+                raise AmbiguousConfigError(
+                    model_name=model_class.__name__,
+                    key=key,
+                    first=first.__name__,
+                    second=other.__name__,
+                )

tinydantic-0.3.0/src/tinydantic/_errors.py

@@ -0,0 +1,76 @@
+# SPDX-FileCopyrightText: Chris Wilson <christopher.david.wilson@gmail.com>
+#
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+
+"""Errors specific to tinydantic."""
+
+from __future__ import annotations
+
+
+class TinydanticError(Exception):
+    """Base class for `tinydantic` errors."""
+
+
+class TinydanticUserError(TinydanticError):
+    """Base class for errors caused by incorrect use of tinydantic."""
+
+
+class DatabaseNotBoundError(TinydanticUserError):
+    """No database is bound to the model class.
+
+    Raised when a table operation is attempted on a model that has no
+    ``database`` configured anywhere in its class hierarchy.
+    """
+
+    def __init__(self, model_name: str) -> None:
+        """Initialize with the name of the unbound model class."""
+        super().__init__(
+            f"No database is bound to {model_name!r}. Pass "
+            "database=<TinyDB instance> as a class keyword when "
+            f"defining the model, or call {model_name}.bind("
+            "database=...) before using it.",
+        )
+
+
+class AmbiguousConfigError(TinydanticUserError):
+    """Conflicting tinydantic config inherited from unrelated bases.
+
+    Raised at class-definition time when two base classes that are not
+    part of one inheritance chain supply different values for the same
+    tinydantic config key and the new class does not set that key
+    itself. tinydantic refuses to guess which base should win — see
+    the ``tinydantic._config`` module docstring for the design
+    rationale.
+    """
+
+    def __init__(
+        self,
+        *,
+        model_name: str,
+        key: str,
+        first: str,
+        second: str,
+    ) -> None:
+        """Initialize with the conflicting classes and config key."""
+        super().__init__(
+            f"{model_name!r} inherits conflicting values for tinydantic "
+            f"config key {key!r} from unrelated base classes {first!r} "
+            f"and {second!r}. Set {key}= explicitly on {model_name!r} "
+            "to resolve the ambiguity.",
+        )
+
+
+class DocumentNotFoundError(TinydanticError):
+    """Requested document is not found."""
+
+    def __init__(self) -> None:
+        """Initializes an instance of this class."""
+        super().__init__("Document not found")
+
+
+class DocumentIDRequiredError(TinydanticError):
+    """Required document ID is missing."""
+
+    def __init__(self) -> None:
+        """Initializes an instance of this class."""
+        super().__init__("Document ID is required")