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>'
21 from ctypes import c_int, c_char_p, c_void_p, c_uint, c_long, byref
22 from notmuch.globals import nmlib, STATUS, NotmuchError, Enum, _str
23 from notmuch.thread import Threads
24 from notmuch.message import Messages, Message
25 from notmuch.tag import Tags
27 class Database(object):
28 """Represents a notmuch database (wraps notmuch_database_t)
30 .. note:: Do remember that as soon as we tear down this object,
31 all underlying derived objects such as queries, threads,
32 messages, tags etc will be freed by the underlying library
33 as well. Accessing these objects will lead to segfaults and
34 other unexpected behavior. See above for more details.
37 """Class attribute to cache user's default database"""
39 MODE = Enum(['READ_ONLY', 'READ_WRITE'])
40 """Constants: Mode in which to open the database"""
42 """notmuch_database_get_directory"""
43 _get_directory = nmlib.notmuch_database_get_directory
44 _get_directory.restype = c_void_p
46 """notmuch_database_get_path"""
47 _get_path = nmlib.notmuch_database_get_path
48 _get_path.restype = c_char_p
50 """notmuch_database_get_version"""
51 _get_version = nmlib.notmuch_database_get_version
52 _get_version.restype = c_uint
54 """notmuch_database_open"""
55 _open = nmlib.notmuch_database_open
56 _open.restype = c_void_p
58 """notmuch_database_upgrade"""
59 _upgrade = nmlib.notmuch_database_upgrade
60 _upgrade.argtypes = [c_void_p, c_void_p, c_void_p]
62 """ notmuch_database_find_message"""
63 _find_message = nmlib.notmuch_database_find_message
64 _find_message.restype = c_void_p
66 """notmuch_database_get_all_tags"""
67 _get_all_tags = nmlib.notmuch_database_get_all_tags
68 _get_all_tags.restype = c_void_p
70 """notmuch_database_create"""
71 _create = nmlib.notmuch_database_create
72 _create.restype = c_void_p
74 def __init__(self, path=None, create=False, mode=0):
75 """If *path* is `None`, we will try to read a users notmuch
76 configuration and use his configured database. The location of the
77 configuration file can be specified through the environment variable
78 *NOTMUCH_CONFIG*, falling back to the default `~/.notmuch-config`.
80 If *create* is `True`, the database will always be created in
81 :attr:`MODE`.READ_WRITE mode. Default mode for opening is READ_ONLY.
83 :param path: Directory to open/create the database in (see
84 above for behavior if `None`)
85 :type path: `str` or `None`
86 :param create: Pass `False` to open an existing, `True` to create a new
89 :param mode: Mode to open a database in. Is always
90 :attr:`MODE`.READ_WRITE when creating a new one.
91 :type mode: :attr:`MODE`
93 :exception: :exc:`NotmuchError` in case of failure.
97 # no path specified. use a user's default database
98 if Database._std_db_path is None:
99 #the following line throws a NotmuchError if it fails
100 Database._std_db_path = self._get_user_default_db()
101 path = Database._std_db_path
104 self.open(path, mode)
108 def _verify_initialized_db(self):
109 """Raises a NotmuchError in case self._db is still None"""
111 raise NotmuchError(STATUS.NOT_INITIALIZED)
113 def create(self, path):
114 """Creates a new notmuch database
116 This function is used by __init__() and usually does not need
117 to be called directly. It wraps the underlying
118 *notmuch_database_create* function and creates a new notmuch
119 database at *path*. It will always return a database in :attr:`MODE`
120 .READ_WRITE mode as creating an empty database for
121 reading only does not make a great deal of sense.
123 :param path: A directory in which we should create the database.
126 :exception: :exc:`NotmuchError` in case of any failure
127 (after printing an error message on stderr).
129 if self._db is not None:
130 raise NotmuchError(message="Cannot create db, this Database() "
131 "already has an open one.")
133 res = Database._create(_str(path), Database.MODE.READ_WRITE)
137 message="Could not create the specified database")
140 def open(self, path, mode=0):
141 """Opens an existing database
143 This function is used by __init__() and usually does not need
144 to be called directly. It wraps the underlying
145 *notmuch_database_open* function.
147 :param status: Open the database in read-only or read-write mode
148 :type status: :attr:`MODE`
150 :exception: Raises :exc:`NotmuchError` in case
151 of any failure (after printing an error message on stderr).
153 res = Database._open(_str(path), mode)
157 message="Could not open the specified database")
161 """Returns the file path of an open database
163 Wraps *notmuch_database_get_path*."""
164 # Raise a NotmuchError if not initialized
165 self._verify_initialized_db()
167 return Database._get_path(self._db).decode('utf-8')
169 def get_version(self):
170 """Returns the database format version
172 :returns: The database version as positive integer
173 :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
174 the database was not intitialized.
176 # Raise a NotmuchError if not initialized
177 self._verify_initialized_db()
179 return Database._get_version(self._db)
181 def needs_upgrade(self):
182 """Does this database need to be upgraded before writing to it?
184 If this function returns `True` then no functions that modify the
185 database (:meth:`add_message`,
186 :meth:`Message.add_tag`, :meth:`Directory.set_mtime`,
187 etc.) will work unless :meth:`upgrade` is called successfully first.
189 :returns: `True` or `False`
190 :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
191 the database was not intitialized.
193 # Raise a NotmuchError if not initialized
194 self._verify_initialized_db()
196 return nmlib.notmuch_database_needs_upgrade(self._db)
199 """Upgrades the current database
201 After opening a database in read-write mode, the client should
202 check if an upgrade is needed (notmuch_database_needs_upgrade) and
203 if so, upgrade with this function before making any modifications.
205 NOT IMPLEMENTED: The optional progress_notify callback can be
206 used by the caller to provide progress indication to the
207 user. If non-NULL it will be called periodically with
208 'progress' as a floating-point value in the range of [0.0..1.0]
209 indicating the progress made so far in the upgrade process.
211 :TODO: catch exceptions, document return values and etc...
213 # Raise a NotmuchError if not initialized
214 self._verify_initialized_db()
216 status = Database._upgrade(self._db, None, None)
217 #TODO: catch exceptions, document return values and etc
220 def get_directory(self, path):
221 """Returns a :class:`Directory` of path,
222 (creating it if it does not exist(?))
224 .. warning:: This call needs a writeable database in
225 Database.MODE.READ_WRITE mode. The underlying library will exit the
226 program if this method is used on a read-only database!
228 :param path: An unicode string containing the path relative to the path
229 of database (see :meth:`get_path`), or else should be an absolute path
230 with initial components that match the path of 'database'.
231 :returns: :class:`Directory` or raises an exception.
232 :exception: :exc:`NotmuchError`
234 STATUS.NOT_INITIALIZED
235 If the database was not intitialized.
238 If path is not relative database or absolute with initial
239 components same as database.
242 # Raise a NotmuchError if not initialized
243 self._verify_initialized_db()
245 # sanity checking if path is valid, and make path absolute
246 if path[0] == os.sep:
247 # we got an absolute path
248 if not path.startswith(self.get_path()):
249 # but its initial components are not equal to the db path
250 raise NotmuchError(STATUS.FILE_ERROR,
251 message="Database().get_directory() called "
252 "with a wrong absolute path.")
255 #we got a relative path, make it absolute
256 abs_dirpath = os.path.abspath(os.path.join(self.get_path(), path))
258 dir_p = Database._get_directory(self._db, _str(path))
260 # return the Directory, init it with the absolute path
261 return Directory(_str(abs_dirpath), dir_p, self)
263 def add_message(self, filename, sync_maildir_flags=False):
264 """Adds a new message to the database
266 :param filename: should be a path relative to the path of the open
267 database (see :meth:`get_path`), or else should be an absolute
268 filename with initial components that match the path of the
271 The file should be a single mail message (not a multi-message mbox)
272 that is expected to remain at its current location, since the
273 notmuch database will reference the filename, and will not copy the
274 entire contents of the file.
276 :param sync_maildir_flags: If the message contains Maildir
277 flags, we will -depending on the notmuch configuration- sync
278 those tags to initial notmuch tags, if set to `True`. It is
279 `False` by default to remain consistent with the libnotmuch
280 API. You might want to look into the underlying method
281 :meth:`Message.maildir_flags_to_tags`.
283 :returns: On success, we return
285 1) a :class:`Message` object that can be used for things
286 such as adding tags to the just-added message.
287 2) one of the following STATUS values:
290 Message successfully added to database.
291 STATUS.DUPLICATE_MESSAGE_ID
292 Message has the same message ID as another message already
293 in the database. The new filename was successfully added
294 to the message in the database.
296 :rtype: 2-tuple(:class:`Message`, STATUS)
298 :exception: Raises a :exc:`NotmuchError` with the following meaning.
299 If such an exception occurs, nothing was added to the database.
302 An error occurred trying to open the file, (such as
303 permission denied, or file not found, etc.).
304 STATUS.FILE_NOT_EMAIL
305 The contents of filename don't look like an email
307 STATUS.READ_ONLY_DATABASE
308 Database was opened in read-only mode so no message can
310 STATUS.NOT_INITIALIZED
311 The database has not been initialized.
313 # Raise a NotmuchError if not initialized
314 self._verify_initialized_db()
317 status = nmlib.notmuch_database_add_message(self._db,
321 if not status in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
322 raise NotmuchError(status)
324 #construct Message() and return
325 msg = Message(msg_p, self)
326 #automatic sync initial tags from Maildir flags
327 if sync_maildir_flags:
328 msg.maildir_flags_to_tags()
331 def remove_message(self, filename):
332 """Removes a message from the given notmuch database
334 Note that only this particular filename association is removed from
335 the database. If the same message (as determined by the message ID)
336 is still available via other filenames, then the message will
337 persist in the database for those filenames. When the last filename
338 is removed for a particular message, the database content for that
339 message will be entirely removed.
341 :returns: A STATUS value with the following meaning:
344 The last filename was removed and the message was removed
346 STATUS.DUPLICATE_MESSAGE_ID
347 This filename was removed but the message persists in the
348 database with at least one other filename.
350 :exception: Raises a :exc:`NotmuchError` with the following meaning.
351 If such an exception occurs, nothing was removed from the
354 STATUS.READ_ONLY_DATABASE
355 Database was opened in read-only mode so no message can be
357 STATUS.NOT_INITIALIZED
358 The database has not been initialized.
360 # Raise a NotmuchError if not initialized
361 self._verify_initialized_db()
363 return nmlib.notmuch_database_remove_message(self._db,
366 def find_message(self, msgid):
367 """Returns a :class:`Message` as identified by its message ID
369 Wraps the underlying *notmuch_database_find_message* function.
371 :param msgid: The message ID
373 :returns: :class:`Message` or `None` if no message is found or
374 if any xapian exception or out-of-memory situation
375 occurs. Do note that Xapian Exceptions include
376 "Database modified" situations, e.g. when the
377 notmuch database has been modified by
378 another program in the meantime. A return value of
379 `None` is therefore no guarantee that the message
381 :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
382 the database was not intitialized.
384 # Raise a NotmuchError if not initialized
385 self._verify_initialized_db()
387 msg_p = Database._find_message(self._db, _str(msgid))
388 return msg_p and Message(msg_p, self) or None
390 def get_all_tags(self):
391 """Returns :class:`Tags` with a list of all tags found in the database
393 :returns: :class:`Tags`
394 :execption: :exc:`NotmuchError` with STATUS.NULL_POINTER on error
396 # Raise a NotmuchError if not initialized
397 self._verify_initialized_db()
399 tags_p = Database._get_all_tags(self._db)
401 raise NotmuchError(STATUS.NULL_POINTER)
402 return Tags(tags_p, self)
404 def create_query(self, querystring):
405 """Returns a :class:`Query` derived from this database
407 This is a shorthand method for doing::
410 # Automatically frees the Database() when 'q' is deleted
412 q = Database(dbpath).create_query('from:"Biene Maja"')
414 # long version, which is functionally equivalent but will keep the
415 # Database in the 'db' variable around after we delete 'q':
417 db = Database(dbpath)
418 q = Query(db,'from:"Biene Maja"')
420 This function is a python extension and not in the underlying C API.
422 # Raise a NotmuchError if not initialized
423 self._verify_initialized_db()
425 return Query(self, querystring)
428 return "'Notmuch DB " + self.get_path() + "'"
431 """Close and free the notmuch database if needed"""
432 if self._db is not None:
433 nmlib.notmuch_database_close(self._db)
435 def _get_user_default_db(self):
436 """ Reads a user's notmuch config and returns his db location
438 Throws a NotmuchError if it cannot find it"""
439 from ConfigParser import SafeConfigParser
440 config = SafeConfigParser()
441 conf_f = os.getenv('NOTMUCH_CONFIG',
442 os.path.expanduser('~/.notmuch-config'))
444 if not config.has_option('database', 'path'):
445 raise NotmuchError(message="No DB path specified"
446 " and no user default found")
447 return config.get('database', 'path').decode('utf-8')
451 """Property returning a pointer to `notmuch_database_t` or `None`
453 This should normally not be needed by a user (and is not yet
454 guaranteed to remain stable in future versions).
460 """Represents a search query on an opened :class:`Database`.
462 A query selects and filters a subset of messages from the notmuch
463 database we derive from.
465 Query() provides an instance attribute :attr:`sort`, which
466 contains the sort order (if specified via :meth:`set_sort`) or
469 Technically, it wraps the underlying *notmuch_query_t* struct.
471 .. note:: Do remember that as soon as we tear down this object,
472 all underlying derived objects such as threads,
473 messages, tags etc will be freed by the underlying library
474 as well. Accessing these objects will lead to segfaults and
475 other unexpected behavior. See above for more details.
478 SORT = Enum(['OLDEST_FIRST', 'NEWEST_FIRST', 'MESSAGE_ID', 'UNSORTED'])
479 """Constants: Sort order in which to return results"""
481 """notmuch_query_create"""
482 _create = nmlib.notmuch_query_create
483 _create.restype = c_void_p
485 """notmuch_query_search_threads"""
486 _search_threads = nmlib.notmuch_query_search_threads
487 _search_threads.restype = c_void_p
489 """notmuch_query_search_messages"""
490 _search_messages = nmlib.notmuch_query_search_messages
491 _search_messages.restype = c_void_p
493 """notmuch_query_count_messages"""
494 _count_messages = nmlib.notmuch_query_count_messages
495 _count_messages.restype = c_uint
497 def __init__(self, db, querystr):
499 :param db: An open database which we derive the Query from.
500 :type db: :class:`Database`
501 :param querystr: The query string for the message.
502 :type querystr: utf-8 encoded str or unicode
507 self.create(db, querystr)
509 def create(self, db, querystr):
510 """Creates a new query derived from a Database
512 This function is utilized by __init__() and usually does not need to
515 :param db: Database to create the query from.
516 :type db: :class:`Database`
517 :param querystr: The query string
518 :type querystr: utf-8 encoded str or unicode
520 :exception: :exc:`NotmuchError`
522 * STATUS.NOT_INITIALIZED if db is not inited
523 * STATUS.NULL_POINTER if the query creation failed
527 raise NotmuchError(STATUS.NOT_INITIALIZED)
528 # create reference to parent db to keep it alive
530 # create query, return None if too little mem available
531 query_p = Query._create(db.db_p, _str(querystr))
533 NotmuchError(STATUS.NULL_POINTER)
534 self._query = query_p
536 def set_sort(self, sort):
537 """Set the sort order future results will be delivered in
539 Wraps the underlying *notmuch_query_set_sort* function.
541 :param sort: Sort order (see :attr:`Query.SORT`)
543 :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if query has not
546 if self._query is None:
547 raise NotmuchError(STATUS.NOT_INITIALIZED)
550 nmlib.notmuch_query_set_sort(self._query, sort)
552 def search_threads(self):
553 """Execute a query for threads
555 Execute a query for threads, returning a :class:`Threads` iterator.
556 The returned threads are owned by the query and as such, will only be
557 valid until the Query is deleted.
559 The method sets :attr:`Message.FLAG`\.MATCH for those messages that
560 match the query. The method :meth:`Message.get_flag` allows us
561 to get the value of this flag.
563 Technically, it wraps the underlying
564 *notmuch_query_search_threads* function.
566 :returns: :class:`Threads`
567 :exception: :exc:`NotmuchError`
569 * STATUS.NOT_INITIALIZED if query is not inited
570 * STATUS.NULL_POINTER if search_threads failed
572 if self._query is None:
573 raise NotmuchError(STATUS.NOT_INITIALIZED)
575 threads_p = Query._search_threads(self._query)
577 if threads_p is None:
578 raise NotmuchError(STATUS.NULL_POINTER)
580 return Threads(threads_p, self)
582 def search_messages(self):
583 """Filter messages according to the query and return
584 :class:`Messages` in the defined sort order
586 Technically, it wraps the underlying
587 *notmuch_query_search_messages* function.
589 :returns: :class:`Messages`
590 :exception: :exc:`NotmuchError`
592 * STATUS.NOT_INITIALIZED if query is not inited
593 * STATUS.NULL_POINTER if search_messages failed
595 if self._query is None:
596 raise NotmuchError(STATUS.NOT_INITIALIZED)
598 msgs_p = Query._search_messages(self._query)
601 NotmuchError(STATUS.NULL_POINTER)
603 return Messages(msgs_p, self)
605 def count_messages(self):
606 """Estimate the number of messages matching the query
608 This function performs a search and returns Xapian's best
609 guess as to the number of matching messages. It is much faster
610 than performing :meth:`search_messages` and counting the
611 result with `len()` (although it always returned the same
612 result in my tests). Technically, it wraps the underlying
613 *notmuch_query_count_messages* function.
615 :returns: :class:`Messages`
616 :exception: :exc:`NotmuchError`
618 * STATUS.NOT_INITIALIZED if query is not inited
620 if self._query is None:
621 raise NotmuchError(STATUS.NOT_INITIALIZED)
623 return Query._count_messages(self._query)
626 """Close and free the Query"""
627 if self._query is not None:
628 nmlib.notmuch_query_destroy(self._query)
631 class Directory(object):
632 """Represents a directory entry in the notmuch directory
634 Modifying attributes of this object will modify the
635 database, not the real directory attributes.
637 The Directory object is usually derived from another object
638 e.g. via :meth:`Database.get_directory`, and will automatically be
639 become invalid whenever that parent is deleted. You should
640 therefore initialized this object handing it a reference to the
641 parent, preventing the parent from automatically being garbage
645 """notmuch_directory_get_mtime"""
646 _get_mtime = nmlib.notmuch_directory_get_mtime
647 _get_mtime.restype = c_long
649 """notmuch_directory_set_mtime"""
650 _set_mtime = nmlib.notmuch_directory_set_mtime
651 _set_mtime.argtypes = [c_char_p, c_long]
653 """notmuch_directory_get_child_files"""
654 _get_child_files = nmlib.notmuch_directory_get_child_files
655 _get_child_files.restype = c_void_p
657 """notmuch_directory_get_child_directories"""
658 _get_child_directories = nmlib.notmuch_directory_get_child_directories
659 _get_child_directories.restype = c_void_p
661 def _verify_dir_initialized(self):
662 """Raises a NotmuchError(STATUS.NOT_INITIALIZED) if dir_p is None"""
663 if self._dir_p is None:
664 raise NotmuchError(STATUS.NOT_INITIALIZED)
666 def __init__(self, path, dir_p, parent):
668 :param path: The absolute path of the directory object as unicode.
669 :param dir_p: The pointer to an internal notmuch_directory_t object.
670 :param parent: The object this Directory is derived from
671 (usually a :class:`Database`). We do not directly use
672 this, but store a reference to it as long as
673 this Directory object lives. This keeps the
676 assert isinstance(path, unicode), "Path needs to be an UNICODE object"
679 self._parent = parent
681 def set_mtime(self, mtime):
682 """Sets the mtime value of this directory in the database
684 The intention is for the caller to use the mtime to allow efficient
685 identification of new messages to be added to the database. The
686 recommended usage is as follows:
688 * Read the mtime of a directory from the filesystem
690 * Call :meth:`Database.add_message` for all mail files in
693 * Call notmuch_directory_set_mtime with the mtime read from the
694 filesystem. Then, when wanting to check for updates to the
695 directory in the future, the client can call :meth:`get_mtime`
696 and know that it only needs to add files if the mtime of the
697 directory and files are newer than the stored timestamp.
699 .. note:: :meth:`get_mtime` function does not allow the caller
700 to distinguish a timestamp of 0 from a non-existent
701 timestamp. So don't store a timestamp of 0 unless you are
702 comfortable with that.
704 :param mtime: A (time_t) timestamp
705 :returns: Nothing on success, raising an exception on failure.
706 :exception: :exc:`NotmuchError`:
708 STATUS.XAPIAN_EXCEPTION
709 A Xapian exception occurred, mtime not stored.
710 STATUS.READ_ONLY_DATABASE
711 Database was opened in read-only mode so directory
712 mtime cannot be modified.
713 STATUS.NOT_INITIALIZED
714 The directory has not been initialized
716 #Raise a NotmuchError(STATUS.NOT_INITIALIZED) if the dir_p is None
717 self._verify_dir_initialized()
719 #TODO: make sure, we convert the mtime parameter to a 'c_long'
720 status = Directory._set_mtime(self._dir_p, mtime)
723 if status == STATUS.SUCCESS:
725 #fail with Exception otherwise
726 raise NotmuchError(status)
729 """Gets the mtime value of this directory in the database
731 Retrieves a previously stored mtime for this directory.
733 :param mtime: A (time_t) timestamp
734 :returns: Nothing on success, raising an exception on failure.
735 :exception: :exc:`NotmuchError`:
737 STATUS.NOT_INITIALIZED
738 The directory has not been initialized
740 #Raise a NotmuchError(STATUS.NOT_INITIALIZED) if self.dir_p is None
741 self._verify_dir_initialized()
743 return Directory._get_mtime(self._dir_p)
745 # Make mtime attribute a property of Directory()
746 mtime = property(get_mtime, set_mtime, doc="""Property that allows getting
747 and setting of the Directory *mtime* (read-write)
749 See :meth:`get_mtime` and :meth:`set_mtime` for usage and
750 possible exceptions.""")
752 def get_child_files(self):
753 """Gets a Filenames iterator listing all the filenames of
754 messages in the database within the given directory.
756 The returned filenames will be the basename-entries only (not
759 #Raise a NotmuchError(STATUS.NOT_INITIALIZED) if self._dir_p is None
760 self._verify_dir_initialized()
762 files_p = Directory._get_child_files(self._dir_p)
763 return Filenames(files_p, self)
765 def get_child_directories(self):
766 """Gets a :class:`Filenames` iterator listing all the filenames of
767 sub-directories in the database within the given directory
769 The returned filenames will be the basename-entries only (not
772 #Raise a NotmuchError(STATUS.NOT_INITIALIZED) if self._dir_p is None
773 self._verify_dir_initialized()
775 files_p = Directory._get_child_directories(self._dir_p)
776 return Filenames(files_p, self)
780 """Returns the absolute path of this Directory (read-only)"""
784 """Object representation"""
785 return "<notmuch Directory object '%s'>" % self._path
788 """Close and free the Directory"""
789 if self._dir_p is not None:
790 nmlib.notmuch_directory_destroy(self._dir_p)
793 class Filenames(object):
794 """An iterator over File- or Directory names stored in the database"""
796 #notmuch_filenames_get
797 _get = nmlib.notmuch_filenames_get
798 _get.restype = c_char_p
800 def __init__(self, files_p, parent):
802 :param files_p: The pointer to an internal notmuch_filenames_t object.
803 :param parent: The object this Directory is derived from
804 (usually a Directory()). We do not directly use
805 this, but store a reference to it as long as
806 this Directory object lives. This keeps the
809 self._files_p = files_p
810 self._parent = parent
813 """ Make Filenames an iterator """
817 if self._files_p is None:
818 raise NotmuchError(STATUS.NOT_INITIALIZED)
820 if not nmlib.notmuch_filenames_valid(self._files_p):
824 file = Filenames._get(self._files_p)
825 nmlib.notmuch_filenames_move_to_next(self._files_p)
829 """len(:class:`Filenames`) returns the number of contained files
831 .. note:: As this iterates over the files, we will not be able to
832 iterate over them again! So this will fail::
835 files = Database().get_directory('').get_child_files()
836 if len(files) > 0: #this 'exhausts' msgs
837 # next line raises NotmuchError(STATUS.NOT_INITIALIZED)!!!
838 for file in files: print file
840 if self._files_p is None:
841 raise NotmuchError(STATUS.NOT_INITIALIZED)
844 while nmlib.notmuch_filenames_valid(self._files_p):
845 nmlib.notmuch_filenames_move_to_next(self._files_p)
851 """Close and free Filenames"""
852 if self._files_p is not None:
853 nmlib.notmuch_filenames_destroy(self._files_p)