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
-
__enter__
()¶
-
__exit__
(*args)¶ See
Table.__exit__()
-
__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
.
-
__len__
()¶ Get the total number of elements in the DB.
>>> db = TinyDB('db.json') >>> len(db) 0
-
purge_tables
()¶ Purge all tables from the database. CANNOT BE REVERSED!
-
table
(name='_default', smart_cache=False, **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.
- smart_cache – Use a smarter query caching.
See
tinydb.database.SmartCacheTable
- 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
(name, db, cache_size=10)¶ Represents a single TinyDB Table.
-
__enter__
()¶ Allow the database to be used as a context manager.
Returns: the table instance
-
__exit__
(*args)¶ Try to close the storage after being used as a context manager.
-
__init__
(name, db, cache_size=10)¶ Get access to a table.
Parameters: - name (str) – The name of the table.
- db (tinydb.database.TinyDB) – The parent database.
- 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]
-
close
(*args)¶ Try to close the storage after being used as a context manager.
-
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
-
get
(cond=None, eid=None)¶ Get exactly one element specified by a query or and ID.
Returns
None
if the element doesn’t existParameters: - 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.Parameters: - func – the function to execute on every included element. first argument: all data second argument: the current eid
- cond – elements to use
- eids – elements to use
-
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
-
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, int) -> 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
-
tinydb.queries
¶
-
class
tinydb.queries.
Query
(key)¶ Provides methods to do tests on dict fields.
Any type of comparison will be called in this class. In addition, it is aliased to
where
to provide a more intuitive syntax.When not using any comparison operation, this simply tests for existence of the given key.
-
__and__
(other)¶ Combines this query and another with logical and.
Example:
>>> (where('f1') == 5) & (where('f2') != 2) ('f1' == 5) and ('f2' != 2)
Return type: QueryAnd
-
__call__
(element)¶ Run the test on the element.
Parameters: element (dict) – The dict that we will run our tests against.
-
__eq__
(other)¶ Test a dict value for equality.
>>> where('f1') == 42 'f1' == 42
-
__ge__
(other)¶ Test a dict value for being greater than or equal to another value.
>>> where('f1') >= 42 'f1' >= 42
-
__gt__
(other)¶ Test a dict value for being greater than another value.
>>> where('f1') > 42 'f1' > 42
-
__invert__
()¶ Negates a query.
>>> ~(where('f1') >= 42) not ('f1' >= 42)
Return type: tinydb.queries.QueryNot
-
__le__
(other)¶ Test a dict value for being lower than or equal to another value.
>>> where('f1') <= 42 'f1' <= 42
-
__lt__
(other)¶ Test a dict value for being lower than another value.
>>> where('f1') < 42 'f1' < 42
-
__ne__
(other)¶ Test a dict value for inequality.
>>> where('f1') != 42 'f1' != 42
-
__or__
(other)¶ Combines this query and another with logical or.
Example:
>>> (where('f1') == 5) | (where('f2') != 2) ('f1' == 5) or ('f2' != 2)
Return type: QueryOr
-
all
(cond)¶ Checks if a condition is met by any element in a list, where a condition can also be a sequence (e.g. list).
>>> where('f1').all(where('f2') == 1) 'f1' all have 'f2' == 1
Matches:
{'f1': [{'f2': 1}, {'f2': 1}]}
>>> where('f1').all([{'f2': 1}, {'f3': 2}]) 'f1' all have [{'f2': 1}, {'f3': 2}]
Matches:
{'f1': [{'f2': 1}, {'f3': 2}]} {'f1': [{'f2': 1}, {'f3': 2}, {'f4': 3}]}
Parameters: cond – The condition to check Return type: tinydb.queries.Query
-
any
(cond)¶ Checks if a condition is met by any element in a list, where a condition can also be a sequence (e.g. list).
>>> where('f1').any(where('f2') == 1) 'f1' has any 'f2' == 1
Matches:
{'f1': [{'f2': 1}, {'f2': 0}]}
>>> where('f1').any([1, 2, 3]) 'f1' has any [1, 2, 3]
Matches:
{'f1': [1, 2]} {'f1': [3, 4, 5]}
Parameters: cond – The condition to check Return type: tinydb.queries.Query
-
contains
(regex)¶ Run a regex test against a dict value (only substring has to match).
>>> where('f1').contains(r'\d+') 'f1' ~= \d+
Parameters: regex – The regular expression to pass to re.search
Return type: QueryRegex
-
has
(key)¶ Run test on a nested dict.
>>> where('x').has('y') == 2 has 'x' => ('y' == 2)
Matches:
{'x': {'y': 2}}
Parameters: key – the key to search for in the nested dict Return type: QueryHas
-
matches
(regex)¶ Run a regex test against a dict value (whole string has to match).
>>> where('f1').matches(r'^\w+$') 'f1' ~= ^\w+$
Parameters: regex – The regular expression to pass to re.match
Return type: QueryRegex
-
test
(func, *args)¶ Run a user-defined test function against a dict value.
>>> def test_func(val): ... return val == 42 ... >>> where('f1').test(test_func) 'f1'.test(<function test_func at 0xXXXXXXXX>)
>>> def test_func_with_params(val, minimum, maximum): ... return minimum <= val <= maximum ... >>> where('f2').test(test_func_with_params, 1, 10) 'f2'.test(<function test_func_with_params at 0xXXXXXXXX>)
Parameters: - func – The function to run. Has to accept one parameter and return a boolean.
- args – Optional list of additional parameters to pass to the function.
Return type: QueryCustom
-
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.
-
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.-
flush
()¶ Flush all unwritten data to disk.
-