Skip to main content

Pydantic base models for Firestore

Project description


Build Status

Database models for Firestore using Pydantic base models.


The package is available on PyPi:

pip install firedantic


In your application you will need to configure the firestore db client and optionally the collection prefix, which by default is empty.

from os import environ
from unittest.mock import Mock

import google.auth.credentials
from firedantic import configure
from import Client

# Firestore emulator must be running if using locally.
if environ.get("FIRESTORE_EMULATOR_HOST"):
    client = Client(
    client = Client()

configure(client, prefix="firedantic-test-")

Once that is done, you can start defining your Pydantic models, e.g:

from pydantic import BaseModel

from firedantic import Model

class Owner(BaseModel):
    """Dummy owner Pydantic model."""
    first_name: str
    last_name: str

class Company(Model):
    """Dummy company Firedantic model."""
    __collection__ = "companies"
    company_id: str
    owner: Owner

# Now you can use the model to save it to Firestore
owner = Owner(first_name="John", last_name="Doe")
company = Company(company_id="1234567-8", owner=owner)

# Prints out the firestore ID of the Company model

Querying is done via a MongoDB-like find():

from firedantic import Model
import firedantic.operators as op

class Product(Model):
    __collection__ = "products"
    product_id: str
    stock: int

Product.find({"product_id": "abc-123"})
Product.find({"stock": {">=": 3}})
# or
Product.find({"stock": {op.GTE: 3}})

The query operators are found at

Async usage

Firedantic can also be used in an async way, like this:

import asyncio
from os import environ
from unittest.mock import Mock

import google.auth.credentials
from import AsyncClient

from firedantic import AsyncModel, configure

# Firestore emulator must be running if using locally.
if environ.get("FIRESTORE_EMULATOR_HOST"):
    client = AsyncClient(
    client = AsyncClient()

configure(client, prefix="firedantic-test-")

class Person(AsyncModel):
    __collection__ = "persons"
    name: str

async def main():
    alice = Person(name="Alice")
    print(f"Saved Alice as {}")
    bob = Person(name="Bob")
    print(f"Saved Bob as {}")

    found_alice = await Person.find_one({"name": "Alice"})
    print(f"Found Alice: {}")
    assert ==

    found_bob = await Person.get_by_id(
    assert ==
    print(f"Found Bob: {}")

    await alice.delete()
    print("Deleted Alice")
    await bob.delete()
    print("Deleted Bob")

if __name__ == "__main__":
    # Starting from Python 3.7 ->

    # Compatible with Python 3.6 ->
    loop = asyncio.get_event_loop()
    result = loop.run_until_complete(main())


PRs are welcome!

To run tests locally, you should run:

poetry install
poetry run invoke test

About sync and async versions of library

Although this library provides both sync and async versions of models, please keep in mind that you need to explicitly maintain only async version of it. The synchronous version is generated automatically by invoke task:

poetry run invoke unasync

We decided to go this way in order to:

  • make sure both versions have the same API
  • reduce human error factor
  • avoid working on two code bases at the same time to reduce maintenance effort

Thus, please make sure you don't modify any of files under firedantic/_sync and firedantic/tests/tests_sync by hands. unasync is also running as part of pre-commit hooks, but in order to run the latest version of tests you have to run it manually.


This code is released under the BSD 3-Clause license. Details in the LICENSE file.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

firedantic-0.2.3.tar.gz (10.4 kB view hashes)

Uploaded Source

Built Distribution

firedantic-0.2.3-py3-none-any.whl (15.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page