Merge Sebastian Spaeth's python bindings into bindings/python
[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 nmlib, STATUS, NotmuchError
21
22 #------------------------------------------------------------------------------
23 class Tags(object):
24     """Represents a list of notmuch tags
25
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::
33
34       for tag in tags: print tag 
35
36     as well as::
37
38        number_of_tags = len(tags)
39
40     and even a simple::
41
42        #str() iterates over all tags to construct a space separated list
43        print(str(tags))
44
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.
47     """
48
49     #notmuch_tags_get
50     _get = nmlib.notmuch_tags_get
51     _get.restype = c_char_p
52
53     def __init__(self, tags_p, parent=None):
54         """
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(?)
69         """
70         if tags_p is None:
71             NotmuchError(STATUS.NULL_POINTER)
72
73         self._tags = tags_p
74         #save reference to parent object so we keep it alive
75         self._parent = parent
76     
77     def __iter__(self):
78         """ Make Tags an iterator """
79         return self
80
81     def next(self):
82         if self._tags is None:
83             raise NotmuchError(STATUS.NOT_INITIALIZED)
84
85         if not nmlib.notmuch_tags_valid(self._tags):
86             self._tags = None
87             raise StopIteration
88
89         tag = Tags._get (self._tags)
90         nmlib.notmuch_tags_move_to_next(self._tags)
91         return tag
92
93     def __len__(self):
94         """len(:class:`Tags`) returns the number of contained tags
95
96         .. note:: As this iterates over the tags, we will not be able
97                to iterate over them again (as in retrieve them)! If
98                the tags have been exhausted already, this will raise a
99                :exc:`NotmuchError` STATUS.NOT_INITIALIZED on
100                subsequent attempts.
101         """
102         if self._tags is None:
103             raise NotmuchError(STATUS.NOT_INITIALIZED)
104
105         i=0
106         while nmlib.notmuch_tags_valid(self._msgs):
107             nmlib.notmuch_tags_move_to_next(self._msgs)
108             i += 1
109         self._tags = None
110         return i
111
112     def __str__(self):
113         """The str() representation of Tags() is a space separated list of tags
114
115         .. note:: As this iterates over the tags, we will not be able
116                to iterate over them again (as in retrieve them)! If
117                the tags have been exhausted already, this will raise a
118                :exc:`NotmuchError` STATUS.NOT_INITIALIZED on
119                subsequent attempts.
120         """
121         return " ".join(self)
122
123     def __del__(self):
124         """Close and free the notmuch tags"""
125         if self._tags is not None:
126             nmlib.notmuch_tags_destroy (self._tags)