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 #------------------------------------------------------------------------------
23 class Filenames(object):
24 """Represents a list of filenames as returned by notmuch
26 This object contains the Filenames iterator. The main function is as_generator() which will return a generator so we can do a Filenamesth an iterator over a list of notmuch filenames. 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 name in filenames: print name
38 number_of_names = len(names)
42 #str() iterates over all tags to construct a space separated list
45 will "exhaust" the Filenames. However, you can use
46 :meth:`Message.get_filenames` repeatedly to get fresh Filenames
47 objects to perform various actions on filenames.
50 #notmuch_filenames_get
51 _get = nmlib.notmuch_filenames_get
52 _get.restype = c_char_p
54 def __init__(self, files_p, parent):
56 :param files_p: A pointer to an underlying *notmuch_tags_t*
57 structure. These are not publically exposed, so a user
58 will almost never instantiate a :class:`Tags` object
59 herself. They are usually handed back as a result,
60 e.g. in :meth:`Database.get_all_tags`. *tags_p* must be
61 valid, we will raise an :exc:`NotmuchError`
62 (STATUS.NULL_POINTER) if it is `None`.
63 :type files_p: :class:`ctypes.c_void_p`
64 :param parent: The parent object (ie :class:`Message` these
65 filenames are derived from, and saves a
66 reference to it, so we can automatically delete the db object
67 once all derived objects are dead.
70 NotmuchError(STATUS.NULL_POINTER)
73 #save reference to parent object so we keep it alive
76 def as_generator(self):
77 """Return generator of Filenames
79 This is the main function that will usually be used by the
81 if self._files is None:
82 raise NotmuchError(STATUS.NOT_INITIALIZED)
84 if not nmlib.notmuch_filenames_valid(self._files):
88 file = Filenames._get (self._files)
89 nmlib.notmuch_filenames_move_to_next(self._files)
93 """Represent Filenames() as newline-separated list of full paths
95 .. note:: As this iterates over the filenames, we will not be
96 able to iterate over them again (as in retrieve them)! If
97 the tags have been exhausted already, this will raise a
98 :exc:`NotmuchError` STATUS.NOT_INITIALIZED on subsequent
99 attempts. However, you can use
100 :meth:`Message.get_filenames` repeatedly to perform
101 various actions on filenames.
103 return "\n".join(self)
106 """Close and free the notmuch filenames"""
107 if self._files is not None:
108 nmlib.notmuch_filenames_destroy (self._files)