diff --git a/docs/_static/architecture.svg b/docs/_static/architecture.svg new file mode 100644 index 000000000..5c6f218d2 --- /dev/null +++ b/docs/_static/architecture.svg @@ -0,0 +1,97 @@ + + + + + + + + + + + TinyDB class relationships + + + Core API + + + TinyDB + + + Table + + + Document + + + Query + + + QueryInstance + + + manages + + + wraps + + + builds + + + filters + + + Persistence layer + + + Storage + + + JSONStorage + + + MemoryStorage + + + Middleware + + + CachingMiddleware + + + + + + + + Supporting components + + + LRUCache + + + operations + + + FrozenDict + + + query cache + + + read / write + + + update helpers + + + stable query hashes + \ No newline at end of file diff --git a/docs/api.rst b/docs/api.rst index fa6084bdb..e6c6f5fb1 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,6 +3,51 @@ API Documentation ================= +Architecture Overview +--------------------- + +TinyDB is organized in three layers: the **core API** you interact with in +application code, a **persistence layer** that serializes database state, and +**supporting components** used internally for caching, updates, and query +hashing. + +At the center is :class:`~tinydb.database.TinyDB`, which owns a +:class:`~tinydb.storages.Storage` instance and manages one or more +:class:`~tinydb.table.Table` objects. Each table stores documents as +:class:`~tinydb.table.Document` instances (dict-like objects that also expose +``doc_id``) and executes queries built from :class:`~tinydb.queries.Query` and +:class:`~tinydb.queries.QueryInstance`. + +Persistence is handled by subclasses of :class:`~tinydb.storages.Storage` such +as :class:`~tinydb.storages.JSONStorage` and +:class:`~tinydb.storages.MemoryStorage`. You can wrap a storage with +:class:`~tinydb.middlewares.Middleware` implementations like +:class:`~tinydb.middlewares.CachingMiddleware` to change how reads and writes +are processed. + +The diagram below summarizes how these pieces relate: + +.. image:: /_static/architecture.svg + :alt: TinyDB class diagram showing relationships between TinyDB, Table, Document, Query, Storage, and supporting components + :align: center + +**Typical data flow** + +1. You call methods on :class:`~tinydb.database.TinyDB` (for example + ``insert`` or ``search``). Unless you opened a named table explicitly, + these calls are forwarded to the default table. +2. The :class:`~tinydb.table.Table` evaluates a :class:`~tinydb.queries.QueryInstance` + against its documents. Results may be served from the table's + :class:`~tinydb.utils.LRUCache` query cache. +3. When the table changes, it reads and writes the full database state through + its :class:`~tinydb.storages.Storage` instance. +4. For partial document updates, :mod:`tinydb.operations` provides helper + callables that can be passed to :meth:`~tinydb.table.Table.update`. + +If you plan to extend TinyDB, start with :doc:`extend` for custom storages and +middlewares, then use the class reference sections below for method-level +details. + ``tinydb.database`` -------------------