emacs: Add new option notmuch-search-hide-excluded

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

diff --git a/bindings/python/notmuch/tag.py b/bindings/python/notmuch/tag.py
index d0f7bb402f2c4ddaa2dda4533fd07ba2428bf5fb..fbb18ce47f004fe137a59ef13893f72481b276a9 100644 (file)
--- a/bindings/python/notmuch/tag.py
+++ b/bindings/python/notmuch/tag.py
@@ -12,12 +12,20 @@ FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 for more details.
 
 You should have received a copy of the GNU General Public License
 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/>.
+along with notmuch.  If not, see <https://www.gnu.org/licenses/>.

 
 

-Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>'
+Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>

 """
 from ctypes import c_char_p
 """
 from ctypes import c_char_p

-from notmuch.globals import nmlib, STATUS, NotmuchError, NotmuchTagsP, Python3StringMixIn
+from .globals import (
+    nmlib,
+    Python3StringMixIn,
+    NotmuchTagsP,
+)
+from .errors import (
+    NullPointerError,
+    NotInitializedError,
+)

 
 
 class Tags(Python3StringMixIn):
 
 
 class Tags(Python3StringMixIn):


@@ -29,9 +37,9 @@ class Tags(Python3StringMixIn):
     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
     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::
+    iteration attempt will raise a :exc:`NotInitializedError`.
+    Also note, that any function that uses iteration (nearly all) will
+    also exhaust the tags. So both::

 
       for tag in tags: print tag
 
 
       for tag in tags: print tag
 


@@ -56,12 +64,12 @@ class Tags(Python3StringMixIn):
     def __init__(self, tags_p, parent=None):
         """
         :param tags_p: A pointer to an underlying *notmuch_tags_t*
     def __init__(self, tags_p, parent=None):
         """
         :param tags_p: A pointer to an underlying *notmuch_tags_t*

-             structure. These are not publically exposed, so a user
+             structure. These are not publicly exposed, so a user

              will almost never instantiate a :class:`Tags` object
              herself. They are usually handed back as a result,
              e.g. in :meth:`Database.get_all_tags`.  *tags_p* must be
              will almost never instantiate a :class:`Tags` object
              herself. They are usually handed back as a result,
              e.g. in :meth:`Database.get_all_tags`.  *tags_p* must be

-             valid, we will raise an :exc:`NotmuchError`
-             (STATUS.NULL_POINTER) if it is `None`.
+             valid, we will raise an :exc:`NullPointerError` if it is
+             `None`.

         :type tags_p: :class:`ctypes.c_void_p`
         :param parent: The parent object (ie :class:`Database` or
              :class:`Message` these tags are derived from, and saves a
         :type tags_p: :class:`ctypes.c_void_p`
         :param parent: The parent object (ie :class:`Database` or
              :class:`Message` these tags are derived from, and saves a


@@ -71,7 +79,7 @@ class Tags(Python3StringMixIn):
                cache the tags in the Python object(?)
         """
         if not tags_p:
                cache the tags in the Python object(?)
         """
         if not tags_p:

-            raise NotmuchError(STATUS.NULL_POINTER)
+            raise NullPointerError()

 
         self._tags = tags_p
         #save reference to parent object so we keep it alive
 
         self._tags = tags_p
         #save reference to parent object so we keep it alive


@@ -91,7 +99,7 @@ class Tags(Python3StringMixIn):
 
     def __next__(self):
         if not self._tags:
 
     def __next__(self):
         if not self._tags:

-            raise NotmuchError(STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()

         if not self._valid(self._tags):
             self._tags = None
             raise StopIteration
         if not self._valid(self._tags):
             self._tags = None
             raise StopIteration


@@ -101,15 +109,15 @@ class Tags(Python3StringMixIn):
     next = __next__ # python2.x iterator protocol compatibility
 
     def __nonzero__(self):
     next = __next__ # python2.x iterator protocol compatibility
 
     def __nonzero__(self):

-        """Implement bool(Tags) check that can be repeatedly used
+        '''
+        Implement truth value testing. If __nonzero__ is not
+        implemented, the python runtime would fall back to `len(..) >
+        0` thus exhausting the iterator.

 
 

-        If __nonzero__ is not implemented, "if Tags()"
-        will implicitly call __len__, using up our iterator, so it is
-        important that this function is defined.
-
-        :returns: True if the Tags() iterator has at least one more Tag
-            left."""
-        return self._valid(self._tags) > 0
+        :returns: True if the wrapped iterator has at least one more object
+                  left.
+        '''
+        return self._tags and self._valid(self._tags)

 
     def __unicode__(self):
         """string representation of :class:`Tags`: a space separated list of tags
 
     def __unicode__(self):
         """string representation of :class:`Tags`: a space separated list of tags


@@ -118,8 +126,8 @@ class Tags(Python3StringMixIn):
 
             As this iterates over the tags, we will not be able to iterate over
             them again (as in retrieve them)! If the tags have been exhausted
 
             As this iterates over the tags, we will not be able to iterate over
             them again (as in retrieve them)! If the tags have been exhausted

-            already, this will raise a :exc:`NotmuchError`
-            STATUS.NOT_INITIALIZED on subsequent attempts.
+            already, this will raise a :exc:`NotInitializedError`on subsequent
+            attempts.

         """
         return " ".join(self)
 
         """
         return " ".join(self)
 


@@ -129,5 +137,5 @@ class Tags(Python3StringMixIn):
 
     def __del__(self):
         """Close and free the notmuch tags"""
 
     def __del__(self):
         """Close and free the notmuch tags"""

-        if self._tags is not None:
+        if self._tags:

             self._destroy(self._tags)
             self._destroy(self._tags)