python: move the exception classes into error.py
[notmuch] / bindings / python / notmuch / tag.py
1 """
2 This file is part of notmuch.
3
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.
8
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
12 for more details.
13
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/>.
16
17 Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>'
18 """
19 from ctypes import c_char_p
20 from notmuch.globals import (
21     nmlib,
22     Python3StringMixIn,
23     NotmuchTagsP,
24 )
25 from .errors import (
26     NullPointerError,
27     NotInitializedError,
28 )
29
30
31 class Tags(Python3StringMixIn):
32     """Represents a list of notmuch tags
33
34     This object provides an iterator over a list of notmuch tags (which
35     are unicode instances).
36
37     Do note that the underlying library only provides a one-time
38     iterator (it cannot reset the iterator to the start). Thus iterating
39     over the function will "exhaust" the list of tags, and a subsequent
40     iteration attempt will raise a :exc:`NotInitializedError`.
41     Also note, that any function that uses iteration (nearly all) will
42     also exhaust the tags. So both::
43
44       for tag in tags: print tag
45
46     as well as::
47
48        number_of_tags = len(tags)
49
50     and even a simple::
51
52        #str() iterates over all tags to construct a space separated list
53        print(str(tags))
54
55     will "exhaust" the Tags. If you need to re-iterate over a list of
56     tags you will need to retrieve a new :class:`Tags` object.
57     """
58
59     #notmuch_tags_get
60     _get = nmlib.notmuch_tags_get
61     _get.argtypes = [NotmuchTagsP]
62     _get.restype = c_char_p
63
64     def __init__(self, tags_p, parent=None):
65         """
66         :param tags_p: A pointer to an underlying *notmuch_tags_t*
67              structure. These are not publically exposed, so a user
68              will almost never instantiate a :class:`Tags` object
69              herself. They are usually handed back as a result,
70              e.g. in :meth:`Database.get_all_tags`.  *tags_p* must be
71              valid, we will raise an :exc:`NullPointerError` if it is
72              `None`.
73         :type tags_p: :class:`ctypes.c_void_p`
74         :param parent: The parent object (ie :class:`Database` or
75              :class:`Message` these tags are derived from, and saves a
76              reference to it, so we can automatically delete the db object
77              once all derived objects are dead.
78         :TODO: Make the iterator optionally work more than once by
79                cache the tags in the Python object(?)
80         """
81         if not tags_p:
82             raise NullPointerError()
83
84         self._tags = tags_p
85         #save reference to parent object so we keep it alive
86         self._parent = parent
87
88     def __iter__(self):
89         """ Make Tags an iterator """
90         return self
91
92     _valid = nmlib.notmuch_tags_valid
93     _valid.argtypes = [NotmuchTagsP]
94     _valid.restype = bool
95
96     _move_to_next = nmlib.notmuch_tags_move_to_next
97     _move_to_next.argtypes = [NotmuchTagsP]
98     _move_to_next.restype = None
99
100     def __next__(self):
101         if not self._tags:
102             raise NotInitializedError()
103         if not self._valid(self._tags):
104             self._tags = None
105             raise StopIteration
106         tag = Tags._get(self._tags).decode('UTF-8')
107         self._move_to_next(self._tags)
108         return tag
109     next = __next__ # python2.x iterator protocol compatibility
110
111     def __nonzero__(self):
112         """Implement bool(Tags) check that can be repeatedly used
113
114         If __nonzero__ is not implemented, "if Tags()"
115         will implicitly call __len__, using up our iterator, so it is
116         important that this function is defined.
117
118         :returns: True if the Tags() iterator has at least one more Tag
119             left."""
120         return self._valid(self._tags) > 0
121
122     def __unicode__(self):
123         """string representation of :class:`Tags`: a space separated list of tags
124
125         .. note::
126
127             As this iterates over the tags, we will not be able to iterate over
128             them again (as in retrieve them)! If the tags have been exhausted
129             already, this will raise a :exc:`NotInitializedError`on subsequent
130             attempts.
131         """
132         return " ".join(self)
133
134     _destroy = nmlib.notmuch_tags_destroy
135     _destroy.argtypes = [NotmuchTagsP]
136     _destroy.restype = None
137
138     def __del__(self):
139         """Close and free the notmuch tags"""
140         if self._tags is not None:
141             self._destroy(self._tags)