python: clean up docstrings and API documentation

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

bindings/python/docs/source/index.rst

@@ -21,7 +21,13 @@ Notmuch can be imported as::
 
 or::
 
- from notmuch import Query,Database
+ from notmuch import Query, Database
+
+ db = Database('path',create=True)
+ msgs = Query(db,'from:myself').search_messages()
+
+ for msg in msgs:
+    print (msg)
 
 More information on specific topics can be found on the following pages:
 
@@ -36,8 +42,6 @@ More information on specific topics can be found on the following pages:
 
 .. automodule:: notmuch
 
-:todo: Document nmlib,STATUS
-
 :class:`notmuch.Database` -- The underlying notmuch database
 ---------------------------------------------------------------------
 
@@ -73,9 +77,6 @@ More information on specific topics can be found on the following pages:
 
    .. automethod:: create_query
 
-   .. note:: :meth:`create_query` was broken in release
-             0.1 and is fixed since 0.1.1.
-
    .. attribute:: Database.MODE
 
      Defines constants that are used as the mode in which to open a database.
@@ -88,6 +89,7 @@ More information on specific topics can be found on the following pages:
 
    .. autoattribute:: db_p
 
+
 :class:`notmuch.Query` -- A search query
 -------------------------------------------------
 

bindings/python/notmuch/__init__.py

@@ -17,7 +17,7 @@ likely to need.
             db = Database('path',create=True)
             msgs = Query(db,'from:myself').search_messages()
 
-    This returns a :class:`Messages` which internally contains a
+    This returns :class:`Messages` which internally contains a
     reference to its parent :class:`Query` object. Otherwise the
     Query() would be immediately freed, taking our *msgs* down with
     it.
@@ -31,7 +31,6 @@ likely to need.
     Pretty much the same is valid for all other objects in the
     hierarchy, such as :class:`Query`, :class:`Messages`,
     :class:`Message`, and :class:`Tags`.
-
 """
 
 """

bindings/python/notmuch/database.py

@@ -26,13 +26,27 @@ from notmuch.message import Messages, Message
 from notmuch.tag import Tags
 
 class Database(object):
-    """Represents a notmuch database (wraps notmuch_database_t)
+    """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:: Do remember that as soon as we tear down this object,
+    .. note:: Any function in this class can and will throw an
-           all underlying derived objects such as queries, threads,
+           :exc:`NotInitializedError` if the database was not
-           messages, tags etc will be freed by the underlying library
+           intitialized properly.
-           as well. Accessing these objects will lead to segfaults and
+
-           other unexpected behavior. See above for more details.
+    .. 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.
     """
     _std_db_path = None
     """Class attribute to cache user's default database"""
@@ -151,7 +165,7 @@ class Database(object):
         :type status:  :attr:`MODE`
         :returns: Nothing
         :exception: Raises :exc:`NotmuchError` in case
-                    of any failure (after printing an error message on stderr).
+            of any failure (possibly after printing an error message on stderr).
         """
         res = Database._open(_str(path), mode)
 
@@ -160,9 +174,7 @@ class Database(object):
         self._db = res
 
     def get_path(self):
-        """Returns the file path of an open database
+        """Returns the file path of an open database"""
-
-        .. ..:: Wraps underlying `notmuch_database_get_path`"""
         self._assert_db_is_initialized()
         return Database._get_path(self._db).decode('utf-8')
 
@@ -170,8 +182,6 @@ class Database(object):
         """Returns the database format version
 
         :returns: The database version as positive integer
-        :exception: :exc:`NotInitializedError` if
-                    the database was not intitialized.
         """
         self._assert_db_is_initialized()
         return Database._get_version(self._db)
@@ -185,8 +195,6 @@ class Database(object):
         etc.) will work unless :meth:`upgrade` is called successfully first.
 
         :returns: `True` or `False`
-        :exception: :exc:`NotInitializedError` if
-                    the database was not intitialized.
         """
         self._assert_db_is_initialized()
         return nmlib.notmuch_database_needs_upgrade(self._db)
@@ -205,9 +213,6 @@ class Database(object):
         indicating the progress made so far in the upgrade process.
 
         :TODO: catch exceptions, document return values and etc...
-
-        :exception: :exc:`NotInitializedError` if
-                    the database was not intitialized.
         """
         self._assert_db_is_initialized()
         status = Database._upgrade(self._db, None, None)
@@ -229,9 +234,6 @@ class Database(object):
             :attr:`STATUS`.XAPIAN_EXCEPTION
                 Xapian exception occurred; atomic section not entered.
 
-            :exc:`NotInitializedError` if
-                the database was not intitialized.
-
         *Added in notmuch 0.9*"""
         self._assert_db_is_initialized()
         status = nmlib.notmuch_database_begin_atomic(self._db)
@@ -254,9 +256,6 @@ class Database(object):
                 :attr:`STATUS`.UNBALANCED_ATOMIC:
                     end_atomic has been called more times than begin_atomic.
 
-            :exc:`NotInitializedError` if
-                    the database was not intitialized.
-
         *Added in notmuch 0.9*"""
         self._assert_db_is_initialized()
         status = nmlib.notmuch_database_end_atomic(self._db)
@@ -280,9 +279,6 @@ class Database(object):
             :exc:`NotmuchError` with :attr:`STATUS`.FILE_ERROR
                     If path is not relative database or absolute with initial
                     components same as database.
-
-            :exc:`NotInitializedError` if
-                    the database was not intitialized.
         """
         self._assert_db_is_initialized()
         # sanity checking if path is valid, and make path absolute
@@ -351,9 +347,6 @@ class Database(object):
               :attr:`STATUS`.READ_ONLY_DATABASE
                       Database was opened in read-only mode so no message can
                       be added.
-
-            :exc:`NotInitializedError` if
-                    the database was not intitialized.
         """
         self._assert_db_is_initialized()
         msg_p = c_void_p()
@@ -397,9 +390,6 @@ class Database(object):
              :attr:`STATUS`.READ_ONLY_DATABASE
                Database was opened in read-only mode so no message can be
                removed.
-
-             :exc:`NotInitializedError` if
-                    the database was not intitialized.
         """
         self._assert_db_is_initialized()
         return nmlib.notmuch_database_remove_message(self._db,
@@ -537,11 +527,12 @@ class Query(object):
     A query selects and filters a subset of messages from the notmuch
     database we derive from.
 
-    Query() provides an instance attribute :attr:`sort`, which
+    :class:`Query` provides an instance attribute :attr:`sort`, which
     contains the sort order (if specified via :meth:`set_sort`) or
     `None`.
 
-    Technically, it wraps the underlying *notmuch_query_t* struct.
+    Any function in this class may throw an :exc:`NotInitializedError`
+    in case the underlying query object was not set up correctly.
 
     .. note:: Do remember that as soon as we tear down this object,
            all underlying derived objects such as threads,
@@ -592,11 +583,11 @@ class Query(object):
         :param querystr: The query string
         :type querystr: utf-8 encoded str or unicode
         :returns: Nothing
-        :exception: :exc:`NotmuchError`
+        :exception:
-
+            :exc:`NullPointerError` if the query creation failed
-                      * :attr:`STATUS`.NOT_INITIALIZED if db is not inited
+                (e.g. too little memory).
-                      * :attr:`STATUS`.NULL_POINTER if the query creation failed
+            :exc:`NotInitializedError` if the underlying db was not
-                        (too little memory)
+                intitialized.
         """
         if db.db_p is None:
             raise NotmuchError(STATUS.NOT_INITIALIZED)
@@ -611,12 +602,7 @@ class Query(object):
     def set_sort(self, sort):
         """Set the sort order future results will be delivered in
 
-        Wraps the underlying *notmuch_query_set_sort* function.
-
         :param sort: Sort order (see :attr:`Query.SORT`)
-        :returns: Nothing
-        :exception: :exc:`NotmuchError` :attr:`STATUS`.NOT_INITIALIZED if query has not
-                    been initialized.
         """
         if self._query is None:
             raise NotmuchError(STATUS.NOT_INITIALIZED)
@@ -635,14 +621,8 @@ class Query(object):
         match the query. The method :meth:`Message.get_flag` allows us
         to get the value of this flag.
 
-        Technically, it wraps the underlying
-        *notmuch_query_search_threads* function.
-
         :returns: :class:`Threads`
-        :exception: :exc:`NotmuchError`
+        :exception: :exc:`NullPointerError` if search_threads failed
-
-                      * :attr:`STATUS`.NOT_INITIALIZED if query is not inited
-                      * :attr:`STATUS`.NULL_POINTER if search_threads failed
         """
         if self._query is None:
             raise NotmuchError(STATUS.NOT_INITIALIZED)
@@ -658,14 +638,8 @@ class Query(object):
         """Filter messages according to the query and return
         :class:`Messages` in the defined sort order
 
-        Technically, it wraps the underlying
-        *notmuch_query_search_messages* function.
-
         :returns: :class:`Messages`
-        :exception: :exc:`NotmuchError`
+        :exception: :exc:`NullPointerError` if search_messages failed
-
-                      * :attr:`STATUS`.NOT_INITIALIZED if query is not inited
-                      * :attr:`STATUS`.NULL_POINTER if search_messages failed
         """
         if self._query is None:
             raise NotmuchError(STATUS.NOT_INITIALIZED)
@@ -688,9 +662,6 @@ class Query(object):
         *notmuch_query_count_messages* function.
 
         :returns: :class:`Messages`
-        :exception: :exc:`NotmuchError`
-
-                      * :attr:`STATUS`.NOT_INITIALIZED if query is not inited
         """
         if self._query is None:
             raise NotmuchError(STATUS.NOT_INITIALIZED)