- .. 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.
+class Database(object):
+ """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.