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
tinydb.storages.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
andkwargs
. - default_table – The name of the default table to populate.
- storage – The class of the storage to use. Will be initialized
with
-
__iter__
()¶ Iter over all documents from default table.
-
__len__
()¶ Get the total number of documents in the default table.
>>> db = TinyDB('db.json') >>> len(db) 0
-
__repr__
() <==> repr(x)¶
-
close
()¶ Close the database.
-
purge_table
(name)¶ Purge a specific table from the database. CANNOT BE REVERSED!
Parameters: name (str) – The name of the table.
-
purge_tables
()¶ Purge all tables from the database. CANNOT BE REVERSED!
-
storage_proxy_class
¶ alias of
StorageProxy
-
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 – Which table class to use.
-
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, name, cache_size=10)¶ Represents a single TinyDB Table.
-
__init__
(storage, name, cache_size=10)¶ Get access to a table.
Parameters: - storage (StorageProxy) – Access to the storage
- name – The table name
- cache_size – Maximum size of query cache.
-
__iter__
()¶ Iter over all documents stored in the table.
Returns: an iterator over all documents. Return type: listiterator[Element]
-
__len__
()¶ Get the total number of documents in the table.
-
__repr__
() <==> repr(x)¶
-
all
()¶ Get all documents stored in the table.
Returns: a list with all documents. Return type: list[Element]
-
clear_cache
()¶ Clear the query cache.
A simple helper that clears the internal query cache.
-
contains
(cond=None, doc_ids=None, eids=None)¶ Check wether the database contains a document matching a condition or an ID.
If
eids
is set, it checks if the db contains a document with one of the specified.Parameters: - cond (Query) – the condition use
- doc_ids – the document IDs to look for
-
get
(cond=None, doc_id=None, eid=None)¶ Get exactly one document specified by a query or and ID.
Returns
None
if the document doesn’t existParameters: - cond (Query) – the condition to check against
- doc_id – the document’s ID
Returns: the document or None
Return type: Element | None
-
insert
(document)¶ Insert a new document into the table.
Parameters: document – the document to insert Returns: the inserted document’s ID
-
insert_multiple
(documents)¶ Insert multiple documents into the table.
Parameters: documents – a list of documents to insert Returns: a list containing the inserted documents’ IDs
-
name
¶ Get the table name.
-
process_elements
(func, cond=None, doc_ids=None, eids=None)¶ Helper function for processing all documents specified by condition or IDs.
A repeating pattern in TinyDB is to run some code on all documents 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. Its first argument will be the data currently in the database. Its second argument is the document ID of the currently processed document.Parameters: - func – the function to execute on every included document. first argument: all data second argument: the current eid
- cond – query that matches documents to use, or
- doc_ids – list of document IDs to use
- eids – list of document IDs to use (deprecated)
Returns: the document IDs that were affected during processing
-
purge
()¶ Purge the table by removing all documents.
-
remove
(cond=None, doc_ids=None, eids=None)¶ Remove all matching documents.
Parameters: - cond (query) – the condition to check against
- doc_ids (list) – a list of document IDs
Returns: a list containing the removed document’s ID
-
search
(cond)¶ Search for all documents matching a ‘where’ cond.
Parameters: cond (Query) – the condition to check against Returns: list of matching documents Return type: list[Element]
-
update
(fields, cond=None, doc_ids=None, eids=None)¶ Update all matching documents to have a given set of fields.
Parameters: - fields (dict | dict -> None) – the fields that the matching documents will have or a method that will update the documents
- cond (query) – which documents to update
- doc_ids (list) – a list of document IDs
Returns: a list containing the updated document’s ID
-
upsert
(document, cond)¶ Update a document, if it exist - insert it otherwise.
Note: this will update all documents matching the query.
Parameters: - document – the document to insert or the fields to update
- cond – which document to look for
Returns: a list containing the updated document’s ID
-
write_back
(documents, doc_ids=None, eids=None)¶ Write back documents by doc_id
Parameters: - documents – a list of document to write back
- doc_ids – a list of documents’ ID which need to be wrote back
Returns: a list of documents’ ID that have been written
-
-
class
tinydb.database.
Document
(value, doc_id, **kwargs)¶ Represents a document stored in the database.
This is a transparent proxy for database records. It exists to provide a way to access a record’s id via
el.doc_id
.-
doc_id
¶ The document’s id
-
__init__
(value, doc_id, **kwargs)¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
-
tinydb.database.
Element
¶ alias of
tinydb.database.Document
tinydb.queries
¶
-
class
tinydb.queries.
Query
¶ TinyDB Queries.
Allows to build queries for TinyDB databases. There are two main ways of using queries:
- ORM-like usage:
>>> User = Query() >>> db.search(User.name == 'John Doe') >>> db.search(User['logged-in'] == True)
- Classical usage:
>>> db.search(where('value') == True)
Note that
where(...)
is a shorthand forQuery(...)
allowing for a more fluent syntax.Besides the methods documented here you can combine queries using the binary AND and OR operators:
>>> db.search(where('field1').exists() & where('field2') == 5) # Binary AND >>> db.search(where('field1').exists() | where('field2') == 5) # Binary OR
Queries are executed by calling the resulting object. They expect to get the document to test as the first argument and return
True
orFalse
depending on whether the documents matches the query or not.-
__eq__
(rhs)¶ Test a dict value for equality.
>>> Query().f1 == 42
Parameters: rhs – The value to compare against
-
__ge__
(rhs)¶ Test a dict value for being greater than or equal to another value.
>>> Query().f1 >= 42
Parameters: rhs – The value to compare against
-
__gt__
(rhs)¶ Test a dict value for being greater than another value.
>>> Query().f1 > 42
Parameters: rhs – The value to compare against
-
__hash__
() <==> hash(x)¶
-
__init__
()¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
__le__
(rhs)¶ Test a dict value for being lower than or equal to another value.
>>> where('f1') <= 42
Parameters: rhs – The value to compare against
-
__lt__
(rhs)¶ Test a dict value for being lower than another value.
>>> Query().f1 < 42
Parameters: rhs – The value to compare against
-
__ne__
(rhs)¶ Test a dict value for inequality.
>>> Query().f1 != 42
Parameters: rhs – The value to compare against
-
__repr__
() <==> repr(x)¶
-
all
(cond)¶ 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.
-
any
(cond)¶ 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.
-
exists
()¶ Test for a dict where a provided key exists.
>>> Query().f1.exists()
-
matches
(regex, flags=0)¶ 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
-
one_of
(items)¶ 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
-
search
(regex, flags=0)¶ 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
-
test
(func, *args)¶ Run a user-defined test function against a dict value.
>>> def test_func(val): ... return val == 42 ... >>> Query().f1.test(test_func)
Parameters: - func – The function to call, passing the dict as the first argument
- args – Additional arguments to pass to the test function
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, create_dirs=False, encoding=None, **kwargs)¶ Store the data in a JSON file.
-
__init__
(path, create_dirs=False, encoding=None, **kwargs)¶ Create a new instance.
Also creates the storage file, if it doesn’t exist.
Parameters: path (str) – Where to store the JSON data.
-
close
()¶ Optional: Close open file handles, etc.
-
read
()¶ Read the last stored state.
Any kind of deserialization should go here. Return
None
here to indicate that the storage is empty.Return type: dict
-
write
(data)¶ Write the current state of the database to the storage.
Any kind of serialization should go here.
Parameters: data (dict) – The current state of the database.
-
-
class
tinydb.storages.
MemoryStorage
¶ Store the data as JSON in memory.
-
__init__
()¶ Create a new instance.
-
read
()¶ Read the last stored state.
Any kind of deserialization should go here. Return
None
here to indicate that the storage is empty.Return type: dict
-
write
(data)¶ Write the current state of the database to the storage.
Any kind of serialization should go here.
Parameters: data (dict) – 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()
orwrite()
are not overloaded, they will be forwarded directly to the 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.-
__init__
(storage_cls=<class 'tinydb.storages.JSONStorage'>)¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
flush
()¶ Flush all unwritten data to disk.
-