- """Represents a notmuch database (wraps notmuch_database_t)
-
- .. note:: Do remember that as soon as we tear down this object,
- all underlying derived objects such as queries, threads,
- messages, tags etc will be freed by the underlying library
- as well. Accessing these objects will lead to segfaults and
- other unexpected behavior. See above for more details.
+ """The :class:`Database` is the highest-level object that notmuch
+ provides. It references a notmuch database, and can be opened in
+ read-only or read-write mode. A :class:`Query` can be derived from
+ or be applied to a specific database to find messages. Also adding
+ and removing messages to the database happens via this
+ object. Modifications to the database are not atmic by default (see
+ :meth:`begin_atomic`) and once a database has been modified, all
+ other database objects pointing to the same data-base will throw an
+ :exc:`XapianError` as the underlying database has been
+ modified. Close and reopen the database to continue working with it.
+
+ .. note:: Any function in this class can and will throw an
+ :exc:`NotInitializedError` if the database was not
+ intitialized properly.
+
+ .. note:: Do remember that as soon as we tear down (e.g. via `del
+ db`) this object, all underlying derived objects such as
+ queries, threads, messages, tags etc will be freed by the
+ underlying library as well. Accessing these objects will lead
+ to segfaults and other unexpected behavior. See above for
+ more details.