tinydantic 0.2.0

A Pydantic-powered ODM (object-document mapper) for TinyDB

tinydantic

tinydantic is a simple Python object-document mapper (ODM) for the TinyDB document database. It uses Pydantic—the most widely used data validation library—for document model definition and validation.

[!NOTE] tinydantic is under active development. Releases follow the SemVer versioning spec:

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 when upgrading. Feedback is welcome!

Full documentation is available at tinydantic.dev.

Table of Contents

• Installation
• Introduction
• Basic Example
• License

Introduction

tinydantic is a wrapper library around TinyDB that enables using Pydantic 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.

Installation

tinydantic is available on PyPI and can be installed with pip. Easy peasy lemon squeezy 🍋

pip install tinydantic

Basic Example

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 which can store the database persistently as JSON, YAML, etc.

>>> 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.

>>> 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".

>>> alice = User(name='Alice', email='[e-mail]')

Insert alice into the database.

>>> alice.insert()
User(id=1, name='Alice', email='[e-mail]')

Query the database for users with the name "Alice". Notice that this returns a User instance that was automatically validated by Pydantic!

>>> User.get(User.name == 'Alice')
User(id=1, name='Alice', email='[e-mail]')

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.

>>> users_table = db.table('users')
>>> users_table.insert({'name': 'Bob', 'email': '[e-mail]'})
2
>>> from tinydb import where
>>> users_table.get(where('name') == 'Bob')
{'name': 'Bob', 'email': '[e-mail]'}

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.

>>> users_table.insert({'name': 'Carol'})
3

Next, we'll query for users named "Bob" using the tinydantic model we created earlier.

>>> 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.

License

See the LICENSE file for copyright & license information.