API Documentation

tinydb.database

class tinydb.database.TinyDB(*args, **kwargs)

The main class of TinyDB.

The TinyDB class is responsible for creating the storage class instance that will store this database’s documents, managing the database tables as well as providing access to the default table.

For table management, a simple dict is used that stores the table class instances accessible using their table name.

Default table access is provided by forwarding all unknown method calls and property access operations to the default table by implementing __getattr__.

When creating a new instance, all arguments and keyword arguments (except for storage) will be passed to the storage class that is provided. If no storage class is specified, JSONStorage will be used.

Customization

For customization, the following class variables can be set:

• table_class defines the class that is used to create tables,

• default_table_name defines the name of the default table, and

• default_storage_class will define the class that will be used to create storage instances if no other storage is passed.

Added in version 4.0.

Data Storage Model

Data is stored using a storage class that provides persistence for a dict instance. This dict contains all tables and their data. The data is modelled like this:

{
    'table1': {
        0: {document...},
        1: {document...},
    },
    'table2': {
        ...
    }
}

Each entry in this dict uses the table name as its key and a dict of documents as its value. The document dict contains document IDs as keys and the documents themselves as values.

Parameters:

storage – The class of the storage to use. Will be initialized with args and kwargs.

table_class

The class that will be used to create table instances

Added in version 4.0.

alias of Table

default_table_name = '_default'

The name of the default table

Added in version 4.0.

default_storage_class

The class that will be used by default to create storage instances

Added in version 4.0.

alias of JSONStorage

table(name: str, **kwargs) → Table

Get access to a specific table.

If the table hasn’t been accessed yet, a new table instance will be created using the table_class class. Otherwise, the previously created table instance will be returned.

All further options besides the name are passed to the table class which by default is Table. Check its documentation for further parameters you can pass.

Parameters:

• name – The name of the table.

• kwargs – Keyword arguments to pass to the table class constructor

tables() → set[str]

Get the names of all tables in the database.

Returns:

a set of table names

drop_tables() → None

Drop all tables from the database. CANNOT BE REVERSED!

drop_table(name: str) → None

Drop a specific table from the database. CANNOT BE REVERSED!

Parameters:

name – The name of the table to drop.

property storage: Storage

Get the storage instance used for this TinyDB instance.

Returns:

This instance’s storage

Return type:

Storage

close() → None

Close the database.

This may be needed if the storage instance used for this database needs to perform cleanup operations like closing file handles.

To ensure this method is called, the TinyDB instance can be used as a context manager:

with TinyDB('data.json') as db:
    db.insert({'foo': 'bar'})

Upon leaving this context, the close method will be called.

tinydb.table

class tinydb.table.Table(storage: Storage, name: str, cache_size: int = 10, persist_empty: bool = False)

Represents a single TinyDB table.

It provides methods for accessing and manipulating documents.

Query Cache

As an optimization, a query cache is implemented using a LRUCache. This class mimics the interface of a normal dict, but starts to remove the least-recently used entries once a threshold is reached.

The query cache is updated on every search operation. When writing data, the whole cache is discarded as the query results may have changed.

Customization

For customization, the following class variables can be set:

• document_class defines the class that is used to represent documents,

• document_id_class defines the class that is used to represent document IDs,

• query_cache_class defines the class that is used for the query cache

• default_query_cache_capacity defines the default capacity of the query cache

Added in version 4.0.

Parameters:

• storage – The storage instance to use for this table

• name – The table name

• cache_size – Maximum capacity of query cache

• persist_empty – Store new table even with no operations on it

document_class

The class used to represent documents

Added in version 4.0.

alias of Document

document_id_class

The class used to represent a document ID

Added in version 4.0.

alias of int

query_cache_class

The class used for caching query results

Added in version 4.0.

alias of LRUCache

default_query_cache_capacity = 10

The default capacity of the query cache

Added in version 4.0.

__init__(storage: Storage, name: str, cache_size: int = 10, persist_empty: bool = False)

Create a table instance.

__repr__()

Return repr(self).

property name: str

Get the table name.

property storage: Storage

Get the table storage instance.

insert(document: Mapping) → int

Insert a new document into the table.

Parameters:

document – the document to insert

Returns:

the inserted document’s ID

insert_multiple(documents: Iterable[Mapping]) → list[int]

Insert multiple documents into the table.

Parameters:

documents – an Iterable of documents to insert

Returns:

a list containing the inserted documents’ IDs

all() → list[Document]

Get all documents stored in the table.

Returns:

a list with all documents.

search(cond: QueryLike) → list[Document]

Search for all documents matching a ‘where’ cond.

Parameters:

cond – the condition to check against

Returns:

list of matching documents

get() → NoReturn

get(cond: QueryLike, doc_id: None = None, doc_ids: None = None) → Document | None

get(*, cond: QueryLike, doc_id: None = None, doc_ids: None = None) → Document | None

get(cond: QueryLike | None, doc_id: int, doc_ids: list | None = None) → Document | None

get(*, cond: QueryLike | None = None, doc_id: int, doc_ids: list | None = None) → Document | None

get(cond: QueryLike | None, doc_id: None, doc_ids: list) → list[Document]

get(cond: QueryLike | None, *, doc_id: None = None, doc_ids: list) → list[Document]

get(*, cond: QueryLike | None = None, doc_id: None = None, doc_ids: list) → list[Document]

Get exactly one document specified by a query or a document ID. However, if multiple document IDs are given then returns all documents in a list.

Returns None if the document doesn’t exist.

Parameters:

• cond – the condition to check against

• doc_id – the document’s ID

• doc_ids – the document’s IDs(multiple)

Returns:

the document(s) or None

contains(cond: QueryLike | None = None, doc_id: int | None = None) → bool

Check whether the database contains a document matching a query or an ID.

If doc_id is set, it checks if the db contains the specified ID.

Parameters:

• cond – the condition use

• doc_id – the document ID to look for

update(fields: Mapping | Callable[[Mapping], None], cond: QueryLike | None = None, doc_ids: Iterable[int] | None = None) → list[int]

Update all matching documents to have a given set of fields.

When doc_ids is given, IDs that don’t refer to an existing document are silently skipped, and the returned list only contains the IDs that were actually updated.

Parameters:

• fields – the fields that the matching documents will have or a method that will update the documents

• cond – which documents to update

• doc_ids – a list of document IDs

Returns:

a list containing the updated document’s ID

update_multiple(updates: Iterable[tuple[Mapping | Callable[[Mapping], None], QueryLike]]) → list[int]

Update all matching documents to have a given set of fields.

Returns:

a list containing the updated document’s ID

upsert(document: Mapping, cond: QueryLike | None = None) → list[int]

Update documents, if they exist, insert them otherwise.

Note: This will update all documents matching the query. For example, if the query matches 3 documents, all 3 will be updated with the new data. If no documents match, a new one is inserted.

Document argument can be a tinydb.table.Document object if you want to specify a doc_id.

Parameters:

• document – the document to insert or the fields to update

• cond – which document to look for, optional if you’ve passed a

Document with a doc_id :returns: a list containing the updated documents’ IDs

remove(cond: QueryLike | None = None, doc_ids: Iterable[int] | None = None) → list[int]

Remove all matching documents.

When doc_ids is given, IDs that don’t refer to an existing document are silently skipped, and the returned list only contains the IDs that were actually removed.

Parameters:

• cond – the condition to check against

• doc_ids – a list of document IDs

Returns:

a list containing the removed documents’ ID

truncate() → None

Truncate the table by removing all documents.

count(cond: QueryLike) → int

Count the documents matching a query.

Parameters:

cond – the condition use

clear_cache() → None

Clear the query cache.

__len__()

Count the total number of documents in this table.

__iter__() → Iterator[Document]

Iterate over all documents stored in the table.

Returns:

an iterator over all documents.

class tinydb.table.Document(value: Mapping, doc_id: int)

A document stored in the database.

This class provides a way to access both a document’s content and its ID using doc.doc_id.

doc_id

The document’s id

__init__(value: Mapping, doc_id: int)

tinydb.queries

class tinydb.queries.Query

TinyDB Queries.

Allows building queries for TinyDB databases. There are two main ways of using queries:

1. ORM-like usage:

>>> User = Query()
>>> db.search(User.name == 'John Doe')
>>> db.search(User['logged-in'] == True)

2. Classical usage:

>>> db.search(where('value') == True)

Note that where(...) is a shorthand for Query(...) allowing for a more fluent syntax.

Besides the methods documented here you can combine queries using the binary AND and OR operators:

>>> # Binary AND:
>>> db.search((where('field1').exists()) & (where('field2') == 5))
>>> # Binary OR:
>>> db.search((where('field1').exists()) | (where('field2') == 5))

Queries are executed by calling the resulting object. They expect to get the document to test as the first argument and return True or False depending on whether the documents match the query or not.

__init__() → None

__repr__()

Return repr(self).

__hash__()

Return hash(self).

__eq__(rhs: Any)

Test a dict value for equality.

>>> Query().f1 == 42

Parameters:

rhs – The value to compare against

__ne__(rhs: Any)

Test a dict value for inequality.

>>> Query().f1 != 42

Parameters:

rhs – The value to compare against

__lt__(rhs: Any) → QueryInstance

Test a dict value for being lower than another value.

>>> Query().f1 < 42

Parameters:

rhs – The value to compare against

__le__(rhs: Any) → QueryInstance

Test a dict value for being lower than or equal to another value.

>>> where('f1') <= 42

Parameters:

rhs – The value to compare against

__gt__(rhs: Any) → QueryInstance

Test a dict value for being greater than another value.

>>> Query().f1 > 42

Parameters:

rhs – The value to compare against

__ge__(rhs: Any) → QueryInstance

Test a dict value for being greater than or equal to another value.

>>> Query().f1 >= 42

Parameters:

rhs – The value to compare against

exists() → QueryInstance

Test for a dict where a provided key exists.

>>> Query().f1.exists()

matches(regex: str, flags: int = 0) → QueryInstance

Run a regex test against a dict value (whole string has to match).

>>> Query().f1.matches(r'^\w+$')

Parameters:

• regex – The regular expression to use for matching

• flags – regex flags to pass to re.match

search(regex: str, flags: int = 0) → QueryInstance

Run a regex test against a dict value (only substring string has to match).

>>> Query().f1.search(r'^\w+$')

Parameters:

• regex – The regular expression to use for matching

• flags – regex flags to pass to re.match

test(func: Callable[[Mapping], bool], *args) → QueryInstance

Run a user-defined test function against a dict value.

>>> def test_func(val):
...     return val == 42
...
>>> Query().f1.test(test_func)

Warning

The test function provided needs to be deterministic (returning the same value when provided with the same arguments), otherwise this may mess up the query cache that Table implements.

Parameters:

• func – The function to call, passing the dict as the first argument

• args – Additional arguments to pass to the test function

any(cond: QueryInstance | list[Any]) → QueryInstance

Check if a condition is met by any document in a list, where a condition can also be a sequence (e.g. list).

>>> Query().f1.any(Query().f2 == 1)

Matches:

{'f1': [{'f2': 1}, {'f2': 0}]}

>>> Query().f1.any([1, 2, 3])

Matches:

{'f1': [1, 2]}
{'f1': [3, 4, 5]}

Parameters:

cond – Either a query that at least one document has to match or a list of which at least one document has to be contained in the tested document.

all(cond: QueryInstance | list[Any]) → QueryInstance

Check if a condition is met by all documents in a list, where a condition can also be a sequence (e.g. list).

>>> Query().f1.all(Query().f2 == 1)

Matches:

{'f1': [{'f2': 1}, {'f2': 1}]}

>>> Query().f1.all([1, 2, 3])

Matches:

{'f1': [1, 2, 3, 4, 5]}

Parameters:

cond – Either a query that all documents have to match or a list which has to be contained in the tested document.

one_of(items: list[Any]) → QueryInstance

Check if the value is contained in a list or generator.

>>> Query().f1.one_of(['value 1', 'value 2'])

Parameters:

items – The list of items to check with

noop() → QueryInstance

Always evaluate to True.

Useful for having a base value when composing queries dynamically.

map(fn: Callable[[Any], Any]) → Query

Add a function to the query path. Similar to __getattr__ but for arbitrary functions.

class tinydb.queries.QueryInstance(test: Callable[[Mapping], bool], hashval: tuple | None)

A query instance.

This is the object on which the actual query operations are performed. The Query class acts like a query builder and generates QueryInstance objects which will evaluate their query against a given document when called.

Query instances can be combined using logical OR and AND and inverted using logical NOT.

In order to be usable in a query cache, a query needs to have a stable hash value with the same query always returning the same hash. That way a query instance can be used as a key in a dictionary.

__init__(test: Callable[[Mapping], bool], hashval: tuple | None)

__call__(value: Mapping) → bool

Evaluate the query to check if it matches a specified value.

Parameters:

value – The value to check.

Returns:

Whether the value matches this query.

__hash__() → int

Return hash(self).

__repr__()

Return repr(self).

__eq__(other: object)

Return self==value.

__or__(other: QueryInstance) → QueryInstance

Return self|value.

tinydb.operations

A collection of update operations for TinyDB.

They are used for updates like this:

>>> db.update(delete('foo'), where('foo') == 2)

This would delete the foo field from all documents where foo equals 2.

tinydb.operations.delete(field: str) → Callable[[MutableMapping], None]

Delete a given field from the document.

tinydb.operations.add(field: str, n: int | float) → Callable[[MutableMapping], None]

Add n to a given field in the document.

tinydb.operations.subtract(field: str, n: int | float) → Callable[[MutableMapping], None]

Subtract n to a given field in the document.

tinydb.operations.set(field: str, val: Any) → Callable[[MutableMapping], None]

Set a given field to val.

tinydb.operations.increment(field: str) → Callable[[MutableMapping], None]

Increment a given field in the document by 1.

tinydb.operations.decrement(field: str) → Callable[[MutableMapping], None]

Decrement a given field in the document by 1.

tinydb.storage

Contains the base class for storages and implementations.

class tinydb.storages.Storage

The abstract base class for all Storages.

A Storage (de)serializes the current state of the database and stores it in some place (memory, file on disk, …).

read()

Read the last stored state.

write(data)

Write the current state of the database to the storage.

close()

Optional: Close open file handles, etc.

class tinydb.storages.JSONStorage(path: str, create_dirs=False, encoding=None, access_mode='r+', **kwargs)

Store the data in a JSON file.

__init__(path: str, create_dirs=False, encoding=None, access_mode='r+', **kwargs)

Create a new instance.

Also creates the storage file, if it doesn’t exist and the access mode is appropriate for writing.

Note: Using an access mode other than r or r+ will probably lead to data loss or data corruption!

Note: Never pass untrusted or user-controlled code as kwargs members like cls or default will be called on every write operation.

Parameters:

• path – Where to store the JSON data.

• access_mode (str) – mode in which the file is opened (r, r+)

close() → None

Optional: Close open file handles, etc.

read() → dict[str, dict[str, Any]] | None

Read the current state.

Any kind of deserialization should go here.

Return None here to indicate that the storage is empty.

write(data: dict[str, dict[str, Any]])

Write the current state of the database to the storage.

Any kind of serialization should go here.

Parameters:

data – The current state of the database.

class tinydb.storages.MemoryStorage

Store the data as JSON in memory.

__init__()

Create a new instance.

read() → dict[str, dict[str, Any]] | None

Read the current state.

Any kind of deserialization should go here.

Return None here to indicate that the storage is empty.

write(data: dict[str, dict[str, Any]])

Write the current state of the database to the storage.

Any kind of serialization should go here.

Parameters:

data – The current state of the database.

tinydb.middlewares

Contains the base class for middlewares and implementations.

class tinydb.middlewares.Middleware

The base class for all Middlewares.

Middlewares hook into the read/write process of TinyDB allowing you to extend the behaviour by adding caching, logging, …

If read() or write() are not overloaded, they will be forwarded directly to the storage instance.

storage

Type:

Storage

Access to the underlying storage instance.

read()

Read the last stored state.

write(data)

Write the current state of the database to the storage.

close()

Optional: Close open file handles, etc.

class tinydb.middlewares.CachingMiddleware(storage_cls)

Add some caching to TinyDB.

This Middleware aims to improve the performance of TinyDB by writing only the last DB state every WRITE_CACHE_SIZE time and reading always from cache.

WRITE_CACHE_SIZE = 1000

The number of write operations to cache before writing to disc

__init__(storage_cls)

flush()

Flush all unwritten data to disk.

tinydb.utils

class tinydb.utils.LRUCache(capacity=None)

A least-recently used (LRU) cache with a fixed cache size.

This class acts as a dictionary but has a limited size. If the number of entries in the cache exceeds the cache size, the least-recently accessed entry will be discarded.

This is implemented using an OrderedDict. On every access the accessed entry is moved to the front by re-inserting it into the OrderedDict. When adding an entry and the cache size is exceeded, the last entry will be discarded.

__init__(capacity=None) → None

__weakref__

list of weak references to the object

clear() → None.  Remove all items from D.

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

« Extensions | Contribution Guidelines »