python: improve Query.count_messages docstring

[notmuch] / bindings / python / notmuch / query.py

diff --git a/bindings/python/notmuch/query.py b/bindings/python/notmuch/query.py
index bab5c3ea578fa3fa3ea5e656f2bba17fad2a0437..0c08aa9eafc235b230ac8e23f7595ced9b33b7f7 100644 (file)
--- a/bindings/python/notmuch/query.py
+++ b/bindings/python/notmuch/query.py
@@ -56,26 +56,6 @@ class Query(object):
     SORT = Enum(['OLDEST_FIRST', 'NEWEST_FIRST', 'MESSAGE_ID', 'UNSORTED'])
     """Constants: Sort order in which to return results"""
 
-    """notmuch_query_create"""
-    _create = nmlib.notmuch_query_create
-    _create.argtypes = [NotmuchDatabaseP, c_char_p]
-    _create.restype = NotmuchQueryP
-
-    """notmuch_query_search_threads"""
-    _search_threads = nmlib.notmuch_query_search_threads
-    _search_threads.argtypes = [NotmuchQueryP]
-    _search_threads.restype = NotmuchThreadsP
-
-    """notmuch_query_search_messages"""
-    _search_messages = nmlib.notmuch_query_search_messages
-    _search_messages.argtypes = [NotmuchQueryP]
-    _search_messages.restype = NotmuchMessagesP
-
-    """notmuch_query_count_messages"""
-    _count_messages = nmlib.notmuch_query_count_messages
-    _count_messages.argtypes = [NotmuchQueryP]
-    _count_messages.restype = c_uint
-
     def __init__(self, db, querystr):
         """
         :param db: An open database which we derive the Query from.
@@ -93,6 +73,11 @@ class Query(object):
         if self._query is None:
             raise NotInitializedError()
 
+    """notmuch_query_create"""
+    _create = nmlib.notmuch_query_create
+    _create.argtypes = [NotmuchDatabaseP, c_char_p]
+    _create.restype = NotmuchQueryP
+
     def create(self, db, querystr):
         """Creates a new query derived from a Database
 
@@ -132,6 +117,11 @@ class Query(object):
         self.sort = sort
         self._set_sort(self._query, sort)
 
+    """notmuch_query_search_threads"""
+    _search_threads = nmlib.notmuch_query_search_threads
+    _search_threads.argtypes = [NotmuchQueryP]
+    _search_threads.restype = NotmuchThreadsP
+
     def search_threads(self):
         """Execute a query for threads
 
@@ -153,6 +143,11 @@ class Query(object):
             raise NullPointerError
         return Threads(threads_p, self)
 
+    """notmuch_query_search_messages"""
+    _search_messages = nmlib.notmuch_query_search_messages
+    _search_messages.argtypes = [NotmuchQueryP]
+    _search_messages.restype = NotmuchMessagesP
+
     def search_messages(self):
         """Filter messages according to the query and return
         :class:`Messages` in the defined sort order
@@ -167,21 +162,40 @@ class Query(object):
             raise NullPointerError
         return Messages(msgs_p, self)
 
-    def count_messages(self):
-        """Estimate the number of messages matching the query
+    _count_messages = nmlib.notmuch_query_count_messages
+    _count_messages.argtypes = [NotmuchQueryP]
+    _count_messages.restype = c_uint
 
+    def count_messages(self):
+        '''
         This function performs a search and returns Xapian's best
-        guess as to the number of matching messages. It is much faster
-        than performing :meth:`search_messages` and counting the
-        result with `len()` (although it always returned the same
-        result in my tests). Technically, it wraps the underlying
-        *notmuch_query_count_messages* function.
+        guess as to the number of matching messages.
 
-        :returns: :class:`Messages`
-        """
+        :returns: the estimated number of messages matching this query
+        :rtype:   int
+        '''
         self._assert_query_is_initialized()
         return Query._count_messages(self._query)
 
+    _count_threads = nmlib.notmuch_query_count_threads
+    _count_threads.argtypes = [NotmuchQueryP]
+    _count_threads.restype = c_uint
+
+    def count_threads(self):
+        '''
+        This function performs a search and returns the number of
+        unique thread IDs in the matching messages. This is the same
+        as number of threads matching a search.
+
+        Note that this is a significantly heavier operation than
+        meth:`Query.count_messages`.
+
+        :returns: the number of threads returned by this query
+        :rtype:   int
+        '''
+        self._assert_query_is_initialized()
+        return Query._count_threads(self._query)
+
     _destroy = nmlib.notmuch_query_destroy
     _destroy.argtypes = [NotmuchQueryP]
     _destroy.restype = None