2 This file is part of notmuch.
4 Notmuch is free software: you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by the
6 Free Software Foundation, either version 3 of the License, or (at your
7 option) any later version.
9 Notmuch is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 You should have received a copy of the GNU General Public License
15 along with notmuch. If not, see <http://www.gnu.org/licenses/>.
17 Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>'
19 from ctypes import c_char_p
20 from notmuch.globals import nmlib, STATUS, NotmuchError
22 #------------------------------------------------------------------------------
24 """Represents a list of notmuch tags
26 This object provides an iterator over a list of notmuch tags. Do
27 note that the underlying library only provides a one-time iterator
28 (it cannot reset the iterator to the start). Thus iterating over
29 the function will "exhaust" the list of tags, and a subsequent
30 iteration attempt will raise a :exc:`NotmuchError`
31 STATUS.NOT_INITIALIZED. Also note, that any function that uses
32 iteration (nearly all) will also exhaust the tags. So both::
34 for tag in tags: print tag
38 number_of_tags = len(tags)
42 #str() iterates over all tags to construct a space separated list
45 will "exhaust" the Tags. If you need to re-iterate over a list of
46 tags you will need to retrieve a new :class:`Tags` object.
50 _get = nmlib.notmuch_tags_get
51 _get.restype = c_char_p
53 def __init__(self, tags_p, parent=None):
55 :param tags_p: A pointer to an underlying *notmuch_tags_t*
56 structure. These are not publically exposed, so a user
57 will almost never instantiate a :class:`Tags` object
58 herself. They are usually handed back as a result,
59 e.g. in :meth:`Database.get_all_tags`. *tags_p* must be
60 valid, we will raise an :exc:`NotmuchError`
61 (STATUS.NULL_POINTER) if it is `None`.
62 :type tags_p: :class:`ctypes.c_void_p`
63 :param parent: The parent object (ie :class:`Database` or
64 :class:`Message` these tags are derived from, and saves a
65 reference to it, so we can automatically delete the db object
66 once all derived objects are dead.
67 :TODO: Make the iterator optionally work more than once by
68 cache the tags in the Python object(?)
71 NotmuchError(STATUS.NULL_POINTER)
74 #save reference to parent object so we keep it alive
78 """ Make Tags an iterator """
82 if self._tags is None:
83 raise NotmuchError(STATUS.NOT_INITIALIZED)
84 # No need to call nmlib.notmuch_tags_valid(self._tags);
85 # Tags._get safely returns None, if there is no more valid tag.
86 tag = Tags._get (self._tags)
90 nmlib.notmuch_tags_move_to_next(self._tags)
93 def __nonzero__(self):
94 """Implement bool(Tags) check that can be repeatedly used
96 If __nonzero__ is not implemented, "if Tags()"
97 will implicitly call __len__, using up our iterator, so it is
98 important that this function is defined.
100 :returns: True if the Tags() iterator has at least one more Tag
102 return nmlib.notmuch_tags_valid(self._tags) > 0
105 """len(:class:`Tags`) returns the number of contained tags
107 .. note:: As this iterates over the tags, we will not be able
108 to iterate over them again (as in retrieve them)! If
109 the tags have been exhausted already, this will raise a
110 :exc:`NotmuchError` STATUS.NOT_INITIALIZED on
113 if self._tags is None:
114 raise NotmuchError(STATUS.NOT_INITIALIZED)
117 while nmlib.notmuch_tags_valid(self._msgs):
118 nmlib.notmuch_tags_move_to_next(self._msgs)
124 """The str() representation of Tags() is a space separated list of tags
126 .. note:: As this iterates over the tags, we will not be able
127 to iterate over them again (as in retrieve them)! If
128 the tags have been exhausted already, this will raise a
129 :exc:`NotmuchError` STATUS.NOT_INITIALIZED on
132 return " ".join(self)
135 """Close and free the notmuch tags"""
136 if self._tags is not None:
137 nmlib.notmuch_tags_destroy (self._tags)