tinydb.database¶

classtinydb.database.TinyDB(*args,**kwargs)[source]¶

The main class of TinyDB.

TheTinyDB class is responsible for creating the storage class instancethat will store this database’s documents, managing the databasetables as well as providing access to the default table.

For table management, a simpledict is used that stores the table classinstances accessible using their table name.

Default table access is provided by forwarding all unknown method callsand property access operations to the default table by implementing__getattr__.

When creating a new instance, all arguments and keyword arguments (exceptforstorage) will be passed to the storage class that is provided. Ifno storage class is specified,JSONStorage will beused.

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 tocreate 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 adict instance. Thisdict contains all tables and their data.The data is modelled like this:

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

Each entry in thisdict uses the table name as its key and adict of documents as its value. The documentdict containsdocument IDs as keys and the documents themselves as values.

Parameters:	storage – The class of the storage to use. Will be initializedwithargs andkwargs.

table_class¶

alias oftinydb.table.Table

default_table_name = '_default'¶

The name of the default table

New in version 4.0.

default_storage_class¶

alias oftinydb.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 becreated using thetable_class class.Otherwise, the previously created table instance will be returned.

All further options besides the name are passed to the table class whichby default isTable. Check its documentationfor 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 databaseneeds to perform cleanup operations like closing file handles.

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

withTinyDB('data.json')asdb:db.insert({'foo':'bar'})

Upon leaving this context, theclose method will be called.

tinydb.table¶

classtinydb.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 aLRUCache. This class mimics the interface ofa normaldict, but starts to remove the least-recently used entriesonce a threshold is reached.

The query cache is updated on every search operation. When writingdata, the whole cache is discarded as the query results may havechanged.

Customization

For customization, the following class variables can be set:

• document_class defines the class that is used to representdocuments,
• document_id_class defines the class that is used to representdocument IDs,
• query_cache_class defines the class that is used for the querycache
• default_query_cache_capacity defines the default capacity ofthe 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 ofDocument

document_id_class¶

alias ofbuiltins.int

query_cache_class¶

alias oftinydb.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,doc_ids: Optional[List[T]] = None) → Union[tinydb.table.Document, List[tinydb.table.Document], None][source]¶

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

ReturnsNone 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) orNone

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

Check whether the database contains a document matching a query oran ID.

Ifdoc_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 haveor 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 updateall documents matching the query. Documentargument can be a tinydb.table.Document object if you want to specify adoc_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.

classtinydb.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 andits ID usingdoc.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¶

classtinydb.queries.Query[source]¶

TinyDB Queries.

Allows building queries for TinyDB databases. There are two main ways ofusing 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 thatwhere(...) is a shorthand forQuery(...) allowing fora more fluent syntax.

Besides the methods documented here you can combine queries using thebinary 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 getthe document to test as the first argument and returnTrue orFalse 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 tore.match

search(regex: str,flags: int = 0) → tinydb.queries.QueryInstance[source]¶

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

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

Parameters:	regex – The regular expression to use for matching flags – regex flags to pass tore.match

test(func: Callable[[Mapping[KT, VT_co]], bool], *args) → tinydb.queries.QueryInstance[source]¶

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

>>>deftest_func(val):...returnval==42...>>>Query().f1.test(test_func)

Warning

The test function provided needs to be deterministic (returning thesame value when provided with the same arguments), otherwise thismay mess up the query cache thatTableimplements.

Parameters:	func – The function to call, passing the dict as the firstargument 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 ora list of which at least one document has to be containedin 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 listwhich 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 toTrue.

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

classtinydb.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. TheQuery class acts like a query builder andgeneratesQueryInstance objects which willevaluate their query against a given document when called.

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

In order to be usable in a query cache, a query needs to have a stable hashvalue with the same query always returning the same hash. That way a queryinstance 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 thefoo field from all documents wherefoo equals 2.

tinydb.operations.delete(field)[source]¶

Delete a given field from the document.

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

Addn to a given field in the document.

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

Subtractn to a given field in the document.

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

Set a given field toval.

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 thebaseclass for storages andimplementations.

classtinydb.storages.Storage[source]¶

The abstract base class for all Storages.

A Storage (de)serializes the current state of the database and storesit 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.

classtinydb.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 modeis appropriate for writing.

Note: Using an access mode other thanr orr+ will probably lead todata loss or data corruption!

Parameters:	path – Where to store the JSON data. access_mode (str) – mode in which the file is opened (r, r+)

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.

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

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

ReturnNone 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 thebaseclass formiddlewares and implementations.

classtinydb.middlewares.Middleware[source]¶

The base class for all Middlewares.

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

Ifread() orwrite() are not overloaded, they will be forwardeddirectly 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.

classtinydb.middlewares.CachingMiddleware(storage_cls)[source]¶

Add some caching to TinyDB.

This Middleware aims to improve the performance of TinyDB by writing onlythe last DB state everyWRITE_CACHE_SIZE time and reading alwaysfrom 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¶

classtinydb.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 ofentries in the cache exceeds the cache size, the least-recently accessedentry will be discarded.

This is implemented using anOrderedDict. On every access the accessedentry is moved to the front by re-inserting it into theOrderedDict.When adding an entry and the cache size is exceeded, the last entry willbe 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]¶