Merge tag '0.13.2'

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

diff --git a/bindings/python/notmuch/messages.py b/bindings/python/notmuch/messages.py
index d94f91b4886b0d91fe26b90d2e3a314aa30a837b..e83455b96aa2410bb8fed74f83d183f3e596cc7b 100644 (file)
--- a/bindings/python/notmuch/messages.py
+++ b/bindings/python/notmuch/messages.py
@@ -14,7 +14,7 @@ for more details.
 You should have received a copy of the GNU General Public License
 along with notmuch.  If not, see <http://www.gnu.org/licenses/>.
 
-Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>'
+Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>
                Jesse Rosenthal <jrosenthal@jhu.edu>
 """
 
@@ -142,7 +142,7 @@ class Messages(object):
         #reset _msgs as we iterated over it and can do so only once
         self._msgs = None
 
-        if tags_p == None:
+        if not tags_p:
             raise NullPointerError()
         return Tags(tags_p, self)
 
@@ -172,11 +172,15 @@ class Messages(object):
     next = __next__ # python2.x iterator protocol compatibility
 
     def __nonzero__(self):
-        """
-        :return: True if there is at least one more thread in the
-            Iterator, False if not."""
-        return self._msgs is not None and \
-            self._valid(self._msgs) > 0
+        '''
+        Implement truth value testing. If __nonzero__ is not
+        implemented, the python runtime would fall back to `len(..) >
+        0` thus exhausting the iterator.
+
+        :returns: True if the wrapped iterator has at least one more object
+                  left.
+        '''
+        return self._msgs and self._valid(self._msgs)
 
     _destroy = nmlib.notmuch_messages_destroy
     _destroy.argtypes = [NotmuchMessagesP]
@@ -184,7 +188,7 @@ class Messages(object):
 
     def __del__(self):
         """Close and free the notmuch Messages"""
-        if self._msgs is not None:
+        if self._msgs:
             self._destroy(self._msgs)
 
     def format_messages(self, format, indent=0, entire_thread=False):
@@ -195,6 +199,13 @@ class Messages(object):
         :param entire_thread: A bool, indicating whether we want to output
                        whole threads or only the matching messages.
         :return: a list of lines
+
+        .. deprecated:: 0.14
+                        This code adds functionality at the python
+                        level that is unlikely to be useful for
+                        anyone. Furthermore the python bindings strive
+                        to be a thin wrapper around libnotmuch, so
+                        this code will be removed in notmuch 0.15.
         """
         result = list()
 
@@ -251,6 +262,13 @@ class Messages(object):
         :param indent: A number indicating the reply depth of these messages.
         :param entire_thread: A bool, indicating whether we want to output
                        whole threads or only the matching messages.
+
+        .. deprecated:: 0.14
+                        This code adds functionality at the python
+                        level that is unlikely to be useful for
+                        anyone. Furthermore the python bindings strive
+                        to be a thin wrapper around libnotmuch, so
+                        this code will be removed in notmuch 0.15.
         """
         handle.write(''.join(self.format_messages(format, indent, entire_thread)))