API Documentation

tinydb.database

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

The main class of TinyDB.

Gives access to the database, provides methods to insert/search/remove and getting tables.

DEFAULT_STORAGE

alias of JSONStorage

__getattr__(name)

Forward all unknown attribute calls to the underlying standard table.

__init__(*args, **kwargs)

Create a new instance of TinyDB.

All arguments and keyword arguments will be passed to the underlying storage class (default: JSONStorage).

Parameters:storage – The class of the storage to use. Will be initialized with args and kwargs.
__len__()

Get the total number of elements in the default table.

>>> db = TinyDB('db.json')
>>> len(db)
0
close()

Close the database.

purge_tables()

Purge all tables from the database. CANNOT BE REVERSED!

table(name='_default', **options)

Get access to a specific table.

Creates a new table, if it hasn’t been created before, otherwise it returns the cached Table object.

Parameters:
  • name (str) – The name of the table.
  • cache_size – How many query results to cache.
table_class

alias of Table

tables()

Get the names of all tables in the database.

Returns:a set of table names
Return type:set[str]
class tinydb.database.Table(storage, cache_size=10)

Represents a single TinyDB Table.

__init__(storage, cache_size=10)

Get access to a table.

Parameters:
  • storage (StorageProxyus) – Access to the storage
  • cache_size – Maximum size of query cache.
__len__()

Get the total number of elements in the table.

all()

Get all elements stored in the table.

Returns:a list with all elements.
Return type:list[Element]
clear_cache()

Clear the query cache.

A simple helper that clears the internal query cache.

contains(cond=None, eids=None)

Check wether the database contains an element matching a condition or an ID.

If eids is set, it checks if the db contains an element with one of the specified.

Parameters:
  • cond (Query) – the condition use
  • eids – the element IDs to look for
count(cond)

Count the elements matching a condition.

Parameters:cond (Query) – the condition use
get(cond=None, eid=None)

Get exactly one element specified by a query or and ID.

Returns None if the element doesn’t exist

Parameters:
  • cond (Query) – the condition to check against
  • eid – the element’s ID
Returns:

the element or None
Return type:

Element | None
insert(element)

Insert a new element into the table.

Parameters:element – the element to insert
Returns:the inserted element’s ID
insert_multiple(elements)

Insert multiple elements into the table.

Parameters:elements – a list of elements to insert
Returns:a list containing the inserted elements’ IDs
process_elements(func, cond=None, eids=None)

Helper function for processing all elements specified by condition or IDs.

A repeating pattern in TinyDB is to run some code on all elements that match a condition or are specified by their ID. This is implemented in this function. The function passed as func has to be a callable. It’s first argument will be the data currently in the database. It’s second argument is the element ID of the currently processed element.

See: update(), remove()

Parameters:
  • func – the function to execute on every included element. first argument: all data second argument: the current eid
  • cond – elements to use, or
  • eids – elements to use
Returns:

the element IDs that were affected during processed
purge()

Purge the table by removing all elements.

remove(cond=None, eids=None)

Remove all matching elements.

Parameters:
  • cond (query) – the condition to check against
  • eids (list) – a list of element IDs
Returns:

a list containing the removed element’s ID
search(cond)

Search for all elements matching a ‘where’ cond.

Parameters:cond (Query) – the condition to check against
Returns:list of matching elements
Return type:list[Element]
update(fields, cond=None, eids=None)

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

Parameters:
  • fields (dict | dict -> None) – the fields that the matching elements will have or a method that will update the elements
  • cond (query) – which elements to update
  • eids (list) – a list of element IDs
Returns:

a list containing the updated element’s ID
class tinydb.database.Element(value=None, eid=None, **kwargs)

Represents an element stored in the database.

This is a transparent proxy for database elements. It exists to provide a way to access an element’s id via el.eid.

eid

The element’s id

tinydb.queries

class tinydb.queries.Query(path=None)

A Query builder.

The:class:~tinydb.queries.Query class is actually more like a query builder. It creates and returns QueryImpl objects which represent the actual query.

__eq__(rhs)
Return type:QueryImpl

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, **kwargs)

Store the data in a JSON file.

__init__(path, **kwargs)

Create a new instance.

Also creates the storage file, if it doesn’t exist.

Parameters:path (str) – Where to store the JSON data.
class tinydb.storages.MemoryStorage

Store the data as JSON in memory.

__init__()

Create a new instance.

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=<class 'tinydb.storages.JSONStorage'>)

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.

flush()

Flush all unwritten data to disk.

« Extensions | Contribution Guidelines »