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
wil 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, anddefault_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. Thisdict
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 adict
of documents as its value. The documentdict
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
andkwargs
.-
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 futher 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_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 normaldict
, 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 discareded 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 cachedefault_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_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.
-
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 – a 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.Query) → 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.Query] = 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.Query] = 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.Query] = 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.Query]]) → 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: tinydb.queries.Query) → List[int][source]¶ 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
-
remove
(cond: Optional[tinydb.queries.Query] = 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
tinydb.queries
¶
-
class
tinydb.queries.
Query
[source]¶ 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:
>>> # 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
orFalse
depending on whether the documents matches the query or not.-
__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 fuction 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.
-
class
tinydb.queries.
QueryInstance
(test: Callable[[Mapping[KT, VT_co]], bool], hashval: 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 generatesQueryInstance
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: Tuple)[source]¶ Initialize self. See help(type(self)) for accurate signature.
-
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.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, …).
-
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)
-
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()
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)[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
-
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 exeeds the cache size, the leat-recently accessed entry will be discareded.
This is implemented using an
OrderedDict
. On every access the accessed entry is moved to the front by re-inserting it into theOrderedDict
. When adding an entry and the cache size is exceeded, the last entry will be discareded.-
__weakref__
¶ list of weak references to the object (if defined)
-