python: improve Query.count_messages docstring

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

diff --git a/bindings/python/notmuch/filename.py b/bindings/python/notmuch/filename.py
index 20b90e98b86f864c39a72c549330e05d26d34417..469b6a5a97640a463d9d8625ff21078271107181 100644 (file)
--- a/bindings/python/notmuch/filename.py
+++ b/bindings/python/notmuch/filename.py
@@ -17,21 +17,23 @@ along with notmuch.  If not, see <http://www.gnu.org/licenses/>.
 Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>'
 """
 from ctypes import c_char_p
 Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>'
 """
 from ctypes import c_char_p

-from notmuch.globals import nmlib, STATUS, NotmuchError
+from notmuch.globals import (nmlib, STATUS, NotmuchError,
+    NotmuchFilenamesP, NotmuchMessageP, Python3StringMixIn)

 
 

-#------------------------------------------------------------------------------
-class Filenames(object):
+
+class Filenames(Python3StringMixIn):

     """Represents a list of filenames as returned by notmuch
 
     """Represents a list of filenames as returned by notmuch
 

-    This object contains the Filenames iterator. The main function is as_generator() which will return a generator so we can do a Filenamesth an iterator over a list of notmuch filenames. Do
-    note that the underlying library only provides a one-time iterator
-    (it cannot reset the iterator to the start). Thus iterating over
-    the function will "exhaust" the list of tags, and a subsequent
-    iteration attempt will raise a :exc:`NotmuchError`
-    STATUS.NOT_INITIALIZED. Also note, that any function that uses
-    iteration (nearly all) will also exhaust the tags. So both::
+    This object contains the Filenames iterator. The main function is
+    as_generator() which will return a generator so we can do a Filenamesth an
+    iterator over a list of notmuch filenames. Do note that the underlying
+    library only provides a one-time iterator (it cannot reset the iterator to
+    the start). Thus iterating over the function will "exhaust" the list of
+    tags, and a subsequent iteration attempt will raise a :exc:`NotmuchError`
+    STATUS.NOT_INITIALIZED. Also note, that any function that uses iteration
+    (nearly all) will also exhaust the tags. So both::

 
 

-      for name in filenames: print name 
+      for name in filenames: print name

 
     as well as::
 
 
     as well as::
 


@@ -49,6 +51,7 @@ class Filenames(object):
 
     #notmuch_filenames_get
     _get = nmlib.notmuch_filenames_get
 
     #notmuch_filenames_get
     _get = nmlib.notmuch_filenames_get

+    _get.argtypes = [NotmuchFilenamesP]

     _get.restype = c_char_p
 
     def __init__(self, files_p, parent):
     _get.restype = c_char_p
 
     def __init__(self, files_p, parent):


@@ -66,13 +69,21 @@ class Filenames(object):
              reference to it, so we can automatically delete the db object
              once all derived objects are dead.
         """
              reference to it, so we can automatically delete the db object
              once all derived objects are dead.
         """

-        if files_p is None:
-            NotmuchError(STATUS.NULL_POINTER)
+        if not files_p:
+            raise NotmuchError(STATUS.NULL_POINTER)

 
         self._files = files_p
         #save reference to parent object so we keep it alive
         self._parent = parent
 
 
         self._files = files_p
         #save reference to parent object so we keep it alive
         self._parent = parent
 

+    _valid = nmlib.notmuch_filenames_valid
+    _valid.argtypes = [NotmuchFilenamesP]
+    _valid.restype = bool
+
+    _move_to_next = nmlib.notmuch_filenames_move_to_next
+    _move_to_next.argtypes = [NotmuchFilenamesP]
+    _move_to_next.restype = None
+

     def as_generator(self):
         """Return generator of Filenames
 
     def as_generator(self):
         """Return generator of Filenames
 


@@ -81,15 +92,13 @@ class Filenames(object):
         if self._files is None:
             raise NotmuchError(STATUS.NOT_INITIALIZED)
 
         if self._files is None:
             raise NotmuchError(STATUS.NOT_INITIALIZED)
 

-        if not nmlib.notmuch_filenames_valid(self._files):
-            self._files = None
-            return
+        while self._valid(self._files):
+            yield Filenames._get(self._files).decode('utf-8', 'ignore')
+            self._move_to_next(self._files)

 
 

-        file = Filenames._get (self._files)
-        nmlib.notmuch_filenames_move_to_next(self._files)
-        yield file
-        
-    def __str__(self):
+        self._files = None
+
+    def __unicode__(self):

         """Represent Filenames() as newline-separated list of full paths
 
         .. note:: As this iterates over the filenames, we will not be
         """Represent Filenames() as newline-separated list of full paths
 
         .. note:: As this iterates over the filenames, we will not be


@@ -102,7 +111,11 @@ class Filenames(object):
         """
         return "\n".join(self)
 
         """
         return "\n".join(self)
 

+    _destroy = nmlib.notmuch_filenames_destroy
+    _destroy.argtypes = [NotmuchMessageP]
+    _destroy.restype = None
+

     def __del__(self):
         """Close and free the notmuch filenames"""
         if self._files is not None:
     def __del__(self):
         """Close and free the notmuch filenames"""
         if self._files is not None:

-            nmlib.notmuch_filenames_destroy (self._files)
+            self._destroy(self._files)