1 from ctypes import c_char_p
2 from cnotmuch.globals import nmlib, STATUS, NotmuchError
4 #------------------------------------------------------------------------------
6 """Represents a list of notmuch tags
8 This object provides an iterator over a list of notmuch tags. Do
9 note that the underlying library only provides a one-time iterator
10 (it cannot reset the iterator to the start). Thus iterating over
11 the function will "exhaust" the list of tags, and a subsequent
12 iteration attempt will raise a :exc:`NotmuchError`
13 STATUS.NOT_INITIALIZED. Also note, that any function that uses
14 iteration (nearly all) will also exhaust the tags. So both::
16 for tag in tags: print tag
20 number_of_tags = len(tags)
24 #str() iterates over all tags to construct a space separated list
27 will "exhaust" the Tags. If you need to re-iterate over a list of
28 tags you will need to retrieve a new :class:`Tags` object.
32 _get = nmlib.notmuch_tags_get
33 _get.restype = c_char_p
35 def __init__(self, tags_p, parent=None):
37 :param tags_p: A pointer to an underlying *notmuch_tags_t*
38 structure. These are not publically exposed, so a user
39 will almost never instantiate a :class:`Tags` object
40 herself. They are usually handed back as a result,
41 e.g. in :meth:`Database.get_all_tags`. *tags_p* must be
42 valid, we will raise an :exc:`NotmuchError`
43 (STATUS.NULL_POINTER) if it is `None`.
44 :type tags_p: :class:`ctypes.c_void_p`
45 :param parent: The parent object (ie :class:`Database` or
46 :class:`Message` these tags are derived from, and saves a
47 reference to it, so we can automatically delete the db object
48 once all derived objects are dead.
49 :TODO: Make the iterator optionally work more than once by
50 cache the tags in the Python object(?)
53 NotmuchError(STATUS.NULL_POINTER)
56 #save reference to parent object so we keep it alive
60 """ Make Tags an iterator """
64 if self._tags is None:
65 raise NotmuchError(STATUS.NOT_INITIALIZED)
67 if not nmlib.notmuch_tags_valid(self._tags):
71 tag = Tags._get (self._tags)
72 nmlib.notmuch_tags_move_to_next(self._tags)
76 """len(:class:`Tags`) returns the number of contained tags
78 .. note:: As this iterates over the tags, we will not be able
79 to iterate over them again (as in retrieve them)! If
80 the tags have been exhausted already, this will raise a
81 :exc:`NotmuchError` STATUS.NOT_INITIALIZED on
84 if self._tags is None:
85 raise NotmuchError(STATUS.NOT_INITIALIZED)
88 while nmlib.notmuch_tags_valid(self._msgs):
89 nmlib.notmuch_tags_move_to_next(self._msgs)
95 """The str() representation of Tags() is a space separated list of tags
97 .. note:: As this iterates over the tags, we will not be able
98 to iterate over them again (as in retrieve them)! If
99 the tags have been exhausted already, this will raise a
100 :exc:`NotmuchError` STATUS.NOT_INITIALIZED on
103 return " ".join(self)
106 """Close and free the notmuch tags"""
107 if self._tags is not None:
108 nmlib.notmuch_tags_destroy (self._tags)