tinydantic 0.1.19__tar.gz → 0.2.0__tar.gz

tinydantic-0.2.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: tinydantic
+Version: 0.2.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.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.11
+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 under active development. 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. Feedback is welcome!
+
+<!-- prettier-ignore-end -->
+
+<!-- overview-end -->
+
+Full documentation is available at [tinydantic.dev](https://tinydantic.dev).
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Introduction](#introduction)
+- [Basic Example](#basic-example)
+- [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 -->
+
+## Basic Example
+
+<!-- basic-example-start -->
+
+Here's a basic example showing how to create, insert, and query for a document using `tinydantic`.
+
+### Using `tinydantic` models
+
+First, create a TinyDB database where the documents will be stored. In this example, we're using an in-memory database, but TinyDB supports other [storage types](https://tinydb.readthedocs.io/en/latest/usage.html#storage-types) which can store the database persistently as JSON, YAML, etc.
+
+```pycon
+>>> from tinydb import TinyDB
+>>> from tinydb.storages import MemoryStorage
+>>> db = TinyDB(storage=MemoryStorage)
+
+```
+
+Create a `User` document model, configuring it to store documents in the `users` table of the `db` database.
+
+> [!TIP]
+>
+> Since `User` is a subclass of [TinydanticModel][tinydantic.TinydanticModel] (which itself is a subclass of [pydantic.BaseModel][]), `User` is also a Pydantic model! You have all the power of Pydantic models when creating a `tinydantic` document model.
+
+```pycon
+>>> from pydantic import EmailStr
+>>> from tinydantic import TinydanticModel
+>>> class User(TinydanticModel, database=db, table_name='users'):
+...     name: str
+...     email: EmailStr
+
+```
+
+Create a new `User` instance for a user named "Alice".
+
+```pycon
+>>> alice = User(name='Alice', email='alice@example.com')
+
+```
+
+Insert `alice` into the database.
+
+```pycon
+>>> alice.insert()
+User(id=1, name='Alice', email='alice@example.com')
+
+```
+
+Query the database for users with the name "Alice". Notice that this returns a `User` instance that was automatically validated by Pydantic!
+
+```pycon
+>>> User.get(User.name == 'Alice')
+User(id=1, name='Alice', email='alice@example.com')
+
+```
+
+### Comparison to TinyDB
+
+Since `tinydantic` is built on top of TinyDB, you can still use `tinydb` to interact with the database directly if needed.
+
+For comparison, let's try to accomplish the same task as shown above using only TinyDB _without_ `tinydantic`. For this example, we'll continue using the same database (`db`) we created earlier.
+
+```pycon
+>>> users_table = db.table('users')
+>>> users_table.insert({'name': 'Bob', 'email': 'bob@example.com'})
+2
+>>> from tinydb import where
+>>> users_table.get(where('name') == 'Bob')
+{'name': 'Bob', 'email': 'bob@example.com'}
+
+```
+
+Notice, that TinyDB does not impose any restrictions on the document we insert _into_ the database table. Additionally, there is no automatic parsing or validation of the data _returned_ from the database.
+
+### Pydantic validation in action
+
+_What happens if an invalid document is somehow returned from the database?_
+
+Let's set up a contrived example to test the automatic Pydantic validation.
+
+First, we'll manually insert a document that is missing the `email` field from the `User` model we created earlier.
+
+```pycon
+>>> users_table.insert({'name': 'Carol'})
+3
+
+```
+
+Next, we'll query for users named "Bob" using the tinydantic model we created earlier.
+
+```pycon
+>>> User.get(User.name == 'Carol')
+Traceback (most recent call last):
+  ...
+pydantic_core._pydantic_core.ValidationError: 1 validation error for User
+email
+  Field required [type=missing, input_value={'name': 'Carol'}, input_type=Document]
+```
+
+As you can see, Pydantic produced a `ValidationError` because the document returned from the database is missing the `email` field required by the `User` model.
+
+<!-- basic-example-end -->
+
+## License
+
+See the [LICENSE](https://github.com/tinydantic/tinydantic/blob/main/LICENSE.md) file for copyright & license information.

tinydantic-0.2.0/README.md

@@ -0,0 +1,155 @@
+# 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 under active development. 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. Feedback is welcome!
+
+<!-- prettier-ignore-end -->
+
+<!-- overview-end -->
+
+Full documentation is available at [tinydantic.dev](https://tinydantic.dev).
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Introduction](#introduction)
+- [Basic Example](#basic-example)
+- [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 -->
+
+## Basic Example
+
+<!-- basic-example-start -->
+
+Here's a basic example showing how to create, insert, and query for a document using `tinydantic`.
+
+### Using `tinydantic` models
+
+First, create a TinyDB database where the documents will be stored. In this example, we're using an in-memory database, but TinyDB supports other [storage types](https://tinydb.readthedocs.io/en/latest/usage.html#storage-types) which can store the database persistently as JSON, YAML, etc.
+
+```pycon
+>>> from tinydb import TinyDB
+>>> from tinydb.storages import MemoryStorage
+>>> db = TinyDB(storage=MemoryStorage)
+
+```
+
+Create a `User` document model, configuring it to store documents in the `users` table of the `db` database.
+
+> [!TIP]
+>
+> Since `User` is a subclass of [TinydanticModel][tinydantic.TinydanticModel] (which itself is a subclass of [pydantic.BaseModel][]), `User` is also a Pydantic model! You have all the power of Pydantic models when creating a `tinydantic` document model.
+
+```pycon
+>>> from pydantic import EmailStr
+>>> from tinydantic import TinydanticModel
+>>> class User(TinydanticModel, database=db, table_name='users'):
+...     name: str
+...     email: EmailStr
+
+```
+
+Create a new `User` instance for a user named "Alice".
+
+```pycon
+>>> alice = User(name='Alice', email='alice@example.com')
+
+```
+
+Insert `alice` into the database.
+
+```pycon
+>>> alice.insert()
+User(id=1, name='Alice', email='alice@example.com')
+
+```
+
+Query the database for users with the name "Alice". Notice that this returns a `User` instance that was automatically validated by Pydantic!
+
+```pycon
+>>> User.get(User.name == 'Alice')
+User(id=1, name='Alice', email='alice@example.com')
+
+```
+
+### Comparison to TinyDB
+
+Since `tinydantic` is built on top of TinyDB, you can still use `tinydb` to interact with the database directly if needed.
+
+For comparison, let's try to accomplish the same task as shown above using only TinyDB _without_ `tinydantic`. For this example, we'll continue using the same database (`db`) we created earlier.
+
+```pycon
+>>> users_table = db.table('users')
+>>> users_table.insert({'name': 'Bob', 'email': 'bob@example.com'})
+2
+>>> from tinydb import where
+>>> users_table.get(where('name') == 'Bob')
+{'name': 'Bob', 'email': 'bob@example.com'}
+
+```
+
+Notice, that TinyDB does not impose any restrictions on the document we insert _into_ the database table. Additionally, there is no automatic parsing or validation of the data _returned_ from the database.
+
+### Pydantic validation in action
+
+_What happens if an invalid document is somehow returned from the database?_
+
+Let's set up a contrived example to test the automatic Pydantic validation.
+
+First, we'll manually insert a document that is missing the `email` field from the `User` model we created earlier.
+
+```pycon
+>>> users_table.insert({'name': 'Carol'})
+3
+
+```
+
+Next, we'll query for users named "Bob" using the tinydantic model we created earlier.
+
+```pycon
+>>> User.get(User.name == 'Carol')
+Traceback (most recent call last):
+  ...
+pydantic_core._pydantic_core.ValidationError: 1 validation error for User
+email
+  Field required [type=missing, input_value={'name': 'Carol'}, input_type=Document]
+```
+
+As you can see, Pydantic produced a `ValidationError` because the document returned from the database is missing the `email` field required by the `User` model.
+
+<!-- basic-example-end -->
+
+## License
+
+See the [LICENSE](https://github.com/tinydantic/tinydantic/blob/main/LICENSE.md) file for copyright & license information.

tinydantic-0.2.0/pyproject.toml

@@ -0,0 +1,230 @@
+# 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.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.11"
+version = "0.2.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",
+  "httpx",
+  "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",
+  "httpx",
+  "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.11"
+
+[tool.pytest.ini_options]
+addopts = "--doctest-modules --doctest-glob '*.md' --ignore=docs/superpowers"
+doctest_optionflags = "NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL"
+minversion = "6.0"
+testpaths = [
+  "CONTRIBUTING.md",
+  "README.md",
+  "docs",
+  "src",
+  "tests",
+]

tinydantic-0.2.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",
+]