API Documentation

tinydb.database

class tinydb.database.TinyDB(*args, **kwargs)[source]

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.

New 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

alias of tinydb.table.Table

default_table_name = '_default'

The name of the default table

New in version 4.0.

default_storage_class

alias of tinydb.storages.JSONStorage

table(name: str, **kwargs) → tinydb.table.Table[source]

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 wil 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][source]

Get the names of all tables in the database.

Returns:a set of table names
drop_tables() → None[source]

Drop all tables from the database. CANNOT BE REVERSED!

drop_table(name: str) → None[source]

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

Parameters:name – The name of the table to drop.
storage

Get the storage instance used for this TinyDB instance.

Returns:This instance’s storage
Return type:Storage
close() → None[source]

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: tinydb.storages.Storage, name: str, cache_size: int = 10)[source]

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

New 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
document_class

The class used to represent documents

New in version 4.0.

alias of Document

document_id_class

alias of builtins.int

query_cache_class

alias of tinydb.utils.LRUCache

default_query_cache_capacity = 10

The default capacity of the query cache

New in version 4.0.

__init__(storage: tinydb.storages.Storage, name: str, cache_size: int = 10)[source]

Create a table instance.

__repr__()[source]

Return repr(self).

name

Get the table name.

storage

Get the table storage instance.

insert(document: Mapping[KT, VT_co]) → int[source]

Insert a new document into the table.

Parameters:document – the document to insert
Returns:the inserted document’s ID
insert_multiple(documents: Iterable[Mapping[KT, VT_co]]) → List[int][source]

Insert multiple documents into the table.

Parameters:documents – an Iterable of documents to insert
Returns:a list containing the inserted documents’ IDs
all() → List[tinydb.table.Document][source]

Get all documents stored in the table.

Returns:a list with all documents.
search(cond: tinydb.queries.QueryLike) → List[tinydb.table.Document][source]

Search for all documents matching a ‘where’ cond.

Parameters:cond – the condition to check against
Returns:list of matching documents
get(cond: Optional[tinydb.queries.QueryLike] = None, doc_id: Optional[int] = None) → Optional[tinydb.table.Document][source]

Get exactly one document specified by a query or a document ID.

Returns None if the document doesn’t exist.

Parameters:
  • cond – the condition to check against
  • doc_id – the document’s ID
Returns:

the document or None

contains(cond: Optional[tinydb.queries.QueryLike] = None, doc_id: Optional[int] = None) → bool[source]

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: Union[Mapping[KT, VT_co], Callable[[Mapping[KT, VT_co]], None]], cond: Optional[tinydb.queries.QueryLike] = None, doc_ids: Optional[Iterable[int]] = None) → List[int][source]

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

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[Union[Mapping[KT, VT_co], Callable[[Mapping[KT, VT_co]], None]], tinydb.queries.QueryLike]]) → List[int][source]

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

Returns:a list containing the updated document’s ID
upsert(document: Mapping[KT, VT_co], cond: Optional[tinydb.queries.QueryLike] = None) → List[int][source]

Update documents, if they exist, insert them otherwise.

Note: This will update all documents matching the query. 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: Optional[tinydb.queries.QueryLike] = None, doc_ids: Optional[Iterable[int]] = None) → List[int][source]

Remove all matching documents.

Parameters:
  • cond – the condition to check against
  • doc_ids – a list of document IDs
Returns:

a list containing the removed documents’ ID

truncate() → None[source]

Truncate the table by removing all documents.

count(cond: tinydb.queries.QueryLike) → int[source]

Count the documents matching a query.

Parameters:cond – the condition use
clear_cache() → None[source]

Clear the query cache.

__len__()[source]

Count the total number of documents in this table.

__iter__() → Iterator[tinydb.table.Document][source]

Iterate over all documents stored in the table.

Returns:an iterator over all documents.
class tinydb.table.Document(value: Mapping[KT, VT_co], doc_id: int)[source]

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[KT, VT_co], doc_id: int)[source]

Initialize self. See help(type(self)) for accurate signature.

tinydb.queries

class tinydb.queries.Query[source]

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)
  1. 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[source]

Initialize self. See help(type(self)) for accurate signature.

__repr__()[source]

Return repr(self).

__hash__()[source]

Return hash(self).

__eq__(rhs: Any)[source]

Test a dict value for equality.

>>> Query().f1 == 42
Parameters:rhs – The value to compare against
__ne__(rhs: Any)[source]

Test a dict value for inequality.

>>> Query().f1 != 42
Parameters:rhs – The value to compare against
__lt__(rhs: Any) → tinydb.queries.QueryInstance[source]

Test a dict value for being lower than another value.

>>> Query().f1 < 42
Parameters:rhs – The value to compare against
__le__(rhs: Any) → tinydb.queries.QueryInstance[source]

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) → tinydb.queries.QueryInstance[source]

Test a dict value for being greater than another value.

>>> Query().f1 > 42
Parameters:rhs – The value to compare against
__ge__(rhs: Any) → tinydb.queries.QueryInstance[source]

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

>>> Query().f1 >= 42
Parameters:rhs – The value to compare against
exists() → tinydb.queries.QueryInstance[source]

Test for a dict where a provided key exists.

>>> Query().f1.exists()
matches(regex: str, flags: int = 0) → tinydb.queries.QueryInstance[source]

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) → tinydb.queries.QueryInstance[source]

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[KT, VT_co]], bool], *args) → tinydb.queries.QueryInstance[source]

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: Union[tinydb.queries.QueryInstance, List[Any]]) → tinydb.queries.QueryInstance[source]

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: Union[QueryInstance, List[Any]]) → tinydb.queries.QueryInstance[source]

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]) → tinydb.queries.QueryInstance[source]

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() → tinydb.queries.QueryInstance[source]

Always evaluate to True.

Useful for having a base value when composing queries dynamically.

map(fn: Callable[[Any], Any]) → tinydb.queries.Query[source]

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

class tinydb.queries.QueryInstance(test: Callable[[Mapping[KT, VT_co]], bool], hashval: Optional[Tuple])[source]

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[KT, VT_co]], bool], hashval: Optional[Tuple])[source]

Initialize self. See help(type(self)) for accurate signature.

__call__(value: Mapping[KT, VT_co]) → bool[source]

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[source]

Return hash(self).

__repr__()[source]

Return repr(self).

__eq__(other: object)[source]

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)[source]

Delete a given field from the document.

tinydb.operations.add(field, n)[source]

Add n to a given field in the document.

tinydb.operations.subtract(field, n)[source]

Subtract n to a given field in the document.

tinydb.operations.set(field, val)[source]

Set a given field to val.

tinydb.operations.increment(field)[source]

Increment a given field in the document by 1.

tinydb.operations.decrement(field)[source]

Decrement a given field in the document by 1.

tinydb.storage

Contains the base class for storages and implementations.

class tinydb.storages.Storage[source]

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()[source]

Read the last stored state.

write(data)[source]

Write the current state of the database to the storage.

close()[source]

Optional: Close open file handles, etc.

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

Store the data in a JSON file.

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

Create a new instance.

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

Parameters:
  • path – Where to store the JSON data.
  • access_mode (str) – mode in which the file is opened (r, r+, w, a, x, b, t, +, U)
close() → None[source]

Optional: Close open file handles, etc.

read() → Optional[Dict[str, Dict[str, Any]]][source]

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]])[source]

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[source]

Store the data as JSON in memory.

__init__()[source]

Create a new instance.

read() → Optional[Dict[str, Dict[str, Any]]][source]

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]])[source]

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[source]

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)[source]

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)[source]

Initialize self. See help(type(self)) for accurate signature.

flush()[source]

Flush all unwritten data to disk.

tinydb.utils

class tinydb.utils.LRUCache(capacity=None)[source]

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[source]

Initialize self. See help(type(self)) for accurate signature.

__weakref__

list of weak references to the object (if defined)

clear() → None. Remove all items from D.[source]
get(k[, d]) → D[k] if k in D, else d. d defaults to None.[source]

« Extensions | Contribution Guidelines »