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_find_message_by_filename"""
67 _find_message_by_filename = nmlib.notmuch_database_find_message_by_filename
68 _find_message_by_filename.restype = c_void_p
70 """notmuch_database_get_all_tags"""
71 _get_all_tags = nmlib.notmuch_database_get_all_tags
72 _get_all_tags.restype = c_void_p
74 """notmuch_database_create"""
75 _create = nmlib.notmuch_database_create
76 _create.restype = c_void_p
78 def __init__(self, path=None, create=False, mode=0):
79 """If *path* is `None`, we will try to read a users notmuch
80 configuration and use his configured database. The location of the
81 configuration file can be specified through the environment variable
82 *NOTMUCH_CONFIG*, falling back to the default `~/.notmuch-config`.
84 If *create* is `True`, the database will always be created in
85 :attr:`MODE`.READ_WRITE mode. Default mode for opening is READ_ONLY.
87 :param path: Directory to open/create the database in (see
88 above for behavior if `None`)
89 :type path: `str` or `None`
90 :param create: Pass `False` to open an existing, `True` to create a new
93 :param mode: Mode to open a database in. Is always
94 :attr:`MODE`.READ_WRITE when creating a new one.
95 :type mode: :attr:`MODE`
97 :exception: :exc:`NotmuchError` in case of failure.
101 # no path specified. use a user's default database
102 if Database._std_db_path is None:
103 #the following line throws a NotmuchError if it fails
104 Database._std_db_path = self._get_user_default_db()
105 path = Database._std_db_path
108 self.open(path, mode)
112 def _assert_db_is_initialized(self):
113 """Raises a NotmuchError in case self._db is still None"""
115 raise NotmuchError(STATUS.NOT_INITIALIZED)
117 def create(self, path):
118 """Creates a new notmuch database
120 This function is used by __init__() and usually does not need
121 to be called directly. It wraps the underlying
122 *notmuch_database_create* function and creates a new notmuch
123 database at *path*. It will always return a database in :attr:`MODE`
124 .READ_WRITE mode as creating an empty database for
125 reading only does not make a great deal of sense.
127 :param path: A directory in which we should create the database.
130 :exception: :exc:`NotmuchError` in case of any failure
131 (after printing an error message on stderr).
133 if self._db is not None:
134 raise NotmuchError(message="Cannot create db, this Database() "
135 "already has an open one.")
137 res = Database._create(_str(path), Database.MODE.READ_WRITE)
141 message="Could not create the specified database")
144 def open(self, path, mode=0):
145 """Opens an existing database
147 This function is used by __init__() and usually does not need
148 to be called directly. It wraps the underlying
149 *notmuch_database_open* function.
151 :param status: Open the database in read-only or read-write mode
152 :type status: :attr:`MODE`
154 :exception: Raises :exc:`NotmuchError` in case
155 of any failure (after printing an error message on stderr).
157 res = Database._open(_str(path), mode)
161 message="Could not open the specified database")
165 """Returns the file path of an open database
167 Wraps *notmuch_database_get_path*."""
168 self._assert_db_is_initialized()
169 return Database._get_path(self._db).decode('utf-8')
171 def get_version(self):
172 """Returns the database format version
174 :returns: The database version as positive integer
175 :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
176 the database was not intitialized.
178 self._assert_db_is_initialized()
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 self._assert_db_is_initialized()
194 return nmlib.notmuch_database_needs_upgrade(self._db)
197 """Upgrades the current database
199 After opening a database in read-write mode, the client should
200 check if an upgrade is needed (notmuch_database_needs_upgrade) and
201 if so, upgrade with this function before making any modifications.
203 NOT IMPLEMENTED: The optional progress_notify callback can be
204 used by the caller to provide progress indication to the
205 user. If non-NULL it will be called periodically with
206 'progress' as a floating-point value in the range of [0.0..1.0]
207 indicating the progress made so far in the upgrade process.
209 :TODO: catch exceptions, document return values and etc...
211 self._assert_db_is_initialized()
212 status = Database._upgrade(self._db, None, None)
213 #TODO: catch exceptions, document return values and etc
216 def begin_atomic(self):
217 """Begin an atomic database operation
219 Any modifications performed between a successful
220 :meth:`begin_atomic` and a :meth:`end_atomic` will be applied to
221 the database atomically. Note that, unlike a typical database
222 transaction, this only ensures atomicity, not durability;
223 neither begin nor end necessarily flush modifications to disk.
225 :returns: STATUS.SUCCESS or raises
227 :exception: :exc:`NotmuchError` STATUS.XAPIAN_EXCEPTION::
229 A Xapian exception occurred; atomic section not
231 self._assert_db_is_initialized()
232 status = nmlib.notmuch_database_begin_atomic(self._db)
233 if status != STATUS.SUCCESS:
234 raise NotmuchError(status)
237 def end_atomic(self):
238 """Indicate the end of an atomic database operation
240 See :meth:`begin_atomic` for details.
242 :returns: STATUS.SUCCESS or raises
246 STATUS.XAPIAN_EXCEPTION
247 A Xapian exception occurred; atomic section not
249 STATUS.UNBALANCED_ATOMIC:
250 end_atomic has been called more times than begin_atomic."""
251 self._assert_db_is_initialized()
252 status = nmlib.notmuch_database_end_atomic(self._db)
253 if status != STATUS.SUCCESS:
254 raise NotmuchError(status)
257 def get_directory(self, path):
258 """Returns a :class:`Directory` of path,
259 (creating it if it does not exist(?))
261 .. warning:: This call needs a writeable database in
262 Database.MODE.READ_WRITE mode. The underlying library will exit the
263 program if this method is used on a read-only database!
265 :param path: An unicode string containing the path relative to the path
266 of database (see :meth:`get_path`), or else should be an absolute path
267 with initial components that match the path of 'database'.
268 :returns: :class:`Directory` or raises an exception.
269 :exception: :exc:`NotmuchError`
271 STATUS.NOT_INITIALIZED
272 If the database was not intitialized.
275 If path is not relative database or absolute with initial
276 components same as database.
279 self._assert_db_is_initialized()
280 # sanity checking if path is valid, and make path absolute
281 if path[0] == os.sep:
282 # we got an absolute path
283 if not path.startswith(self.get_path()):
284 # but its initial components are not equal to the db path
285 raise NotmuchError(STATUS.FILE_ERROR,
286 message="Database().get_directory() called "
287 "with a wrong absolute path.")
290 #we got a relative path, make it absolute
291 abs_dirpath = os.path.abspath(os.path.join(self.get_path(), path))
293 dir_p = Database._get_directory(self._db, _str(path))
295 # return the Directory, init it with the absolute path
296 return Directory(_str(abs_dirpath), dir_p, self)
298 def add_message(self, filename, sync_maildir_flags=False):
299 """Adds a new message to the database
301 :param filename: should be a path relative to the path of the open
302 database (see :meth:`get_path`), or else should be an absolute
303 filename with initial components that match the path of the
306 The file should be a single mail message (not a multi-message mbox)
307 that is expected to remain at its current location, since the
308 notmuch database will reference the filename, and will not copy the
309 entire contents of the file.
311 :param sync_maildir_flags: If the message contains Maildir
312 flags, we will -depending on the notmuch configuration- sync
313 those tags to initial notmuch tags, if set to `True`. It is
314 `False` by default to remain consistent with the libnotmuch
315 API. You might want to look into the underlying method
316 :meth:`Message.maildir_flags_to_tags`.
318 :returns: On success, we return
320 1) a :class:`Message` object that can be used for things
321 such as adding tags to the just-added message.
322 2) one of the following STATUS values:
325 Message successfully added to database.
326 STATUS.DUPLICATE_MESSAGE_ID
327 Message has the same message ID as another message already
328 in the database. The new filename was successfully added
329 to the list of the filenames for the existing message.
331 :rtype: 2-tuple(:class:`Message`, STATUS)
333 :exception: Raises a :exc:`NotmuchError` with the following meaning.
334 If such an exception occurs, nothing was added to the database.
337 An error occurred trying to open the file, (such as
338 permission denied, or file not found, etc.).
339 STATUS.FILE_NOT_EMAIL
340 The contents of filename don't look like an email
342 STATUS.READ_ONLY_DATABASE
343 Database was opened in read-only mode so no message can
345 STATUS.NOT_INITIALIZED
346 The database has not been initialized.
348 self._assert_db_is_initialized()
350 status = nmlib.notmuch_database_add_message(self._db,
354 if not status in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
355 raise NotmuchError(status)
357 #construct Message() and return
358 msg = Message(msg_p, self)
359 #automatic sync initial tags from Maildir flags
360 if sync_maildir_flags:
361 msg.maildir_flags_to_tags()
364 def remove_message(self, filename):
365 """Removes a message (filename) from the given notmuch database
367 Note that only this particular filename association is removed from
368 the database. If the same message (as determined by the message ID)
369 is still available via other filenames, then the message will
370 persist in the database for those filenames. When the last filename
371 is removed for a particular message, the database content for that
372 message will be entirely removed.
374 :returns: A STATUS value with the following meaning:
377 The last filename was removed and the message was removed
379 STATUS.DUPLICATE_MESSAGE_ID
380 This filename was removed but the message persists in the
381 database with at least one other filename.
383 :exception: Raises a :exc:`NotmuchError` with the following meaning.
384 If such an exception occurs, nothing was removed from the
387 STATUS.READ_ONLY_DATABASE
388 Database was opened in read-only mode so no message can be
390 STATUS.NOT_INITIALIZED
391 The database has not been initialized.
393 self._assert_db_is_initialized()
394 return nmlib.notmuch_database_remove_message(self._db,
397 def find_message(self, msgid):
398 """Returns a :class:`Message` as identified by its message ID
400 Wraps the underlying *notmuch_database_find_message* function.
402 :param msgid: The message ID
404 :returns: :class:`Message` or `None` if no message is found or
405 if any xapian exception or out-of-memory situation
406 occurs. Do note that Xapian Exceptions include
407 "Database modified" situations, e.g. when the
408 notmuch database has been modified by
409 another program in the meantime. A return value of
410 `None` is therefore no guarantee that the message
412 :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
413 the database was not intitialized.
415 self._assert_db_is_initialized()
416 msg_p = Database._find_message(self._db, _str(msgid))
417 return msg_p and Message(msg_p, self) or None
419 def find_message_by_filename(self, filename):
420 """Find a message with the given filename
422 :returns: If the database contains a message with the given
423 filename, then a class:`Message:` is returned. This
424 function returns None in the following situations:
426 * No message is found with the given filename
427 * An out-of-memory situation occurs
428 * A Xapian exception occurs"""
429 self._assert_db_is_initialized()
430 msg_p = Database._find_message_by_filename(self._db, _str(filename))
431 return msg_p and Message(msg_p, self) or None
433 def get_all_tags(self):
434 """Returns :class:`Tags` with a list of all tags found in the database
436 :returns: :class:`Tags`
437 :execption: :exc:`NotmuchError` with STATUS.NULL_POINTER on error
439 self._assert_db_is_initialized()
440 tags_p = Database._get_all_tags(self._db)
442 raise NotmuchError(STATUS.NULL_POINTER)
443 return Tags(tags_p, self)
445 def create_query(self, querystring):
446 """Returns a :class:`Query` derived from this database
448 This is a shorthand method for doing::
451 # Automatically frees the Database() when 'q' is deleted
453 q = Database(dbpath).create_query('from:"Biene Maja"')
455 # long version, which is functionally equivalent but will keep the
456 # Database in the 'db' variable around after we delete 'q':
458 db = Database(dbpath)
459 q = Query(db,'from:"Biene Maja"')
461 This function is a python extension and not in the underlying C API.
463 self._assert_db_is_initialized()
464 return Query(self, querystring)
467 return "'Notmuch DB " + self.get_path() + "'"
470 """Close and free the notmuch database if needed"""
471 if self._db is not None:
472 nmlib.notmuch_database_close(self._db)
474 def _get_user_default_db(self):
475 """ Reads a user's notmuch config and returns his db location
477 Throws a NotmuchError if it cannot find it"""
478 from ConfigParser import SafeConfigParser
479 config = SafeConfigParser()
480 conf_f = os.getenv('NOTMUCH_CONFIG',
481 os.path.expanduser('~/.notmuch-config'))
483 if not config.has_option('database', 'path'):
484 raise NotmuchError(message="No DB path specified"
485 " and no user default found")
486 return config.get('database', 'path').decode('utf-8')
490 """Property returning a pointer to `notmuch_database_t` or `None`
492 This should normally not be needed by a user (and is not yet
493 guaranteed to remain stable in future versions).
499 """Represents a search query on an opened :class:`Database`.
501 A query selects and filters a subset of messages from the notmuch
502 database we derive from.
504 Query() provides an instance attribute :attr:`sort`, which
505 contains the sort order (if specified via :meth:`set_sort`) or
508 Technically, it wraps the underlying *notmuch_query_t* struct.
510 .. note:: Do remember that as soon as we tear down this object,
511 all underlying derived objects such as threads,
512 messages, tags etc will be freed by the underlying library
513 as well. Accessing these objects will lead to segfaults and
514 other unexpected behavior. See above for more details.
517 SORT = Enum(['OLDEST_FIRST', 'NEWEST_FIRST', 'MESSAGE_ID', 'UNSORTED'])
518 """Constants: Sort order in which to return results"""
520 """notmuch_query_create"""
521 _create = nmlib.notmuch_query_create
522 _create.restype = c_void_p
524 """notmuch_query_search_threads"""
525 _search_threads = nmlib.notmuch_query_search_threads
526 _search_threads.restype = c_void_p
528 """notmuch_query_search_messages"""
529 _search_messages = nmlib.notmuch_query_search_messages
530 _search_messages.restype = c_void_p
532 """notmuch_query_count_messages"""
533 _count_messages = nmlib.notmuch_query_count_messages
534 _count_messages.restype = c_uint
536 def __init__(self, db, querystr):
538 :param db: An open database which we derive the Query from.
539 :type db: :class:`Database`
540 :param querystr: The query string for the message.
541 :type querystr: utf-8 encoded str or unicode
546 self.create(db, querystr)
548 def create(self, db, querystr):
549 """Creates a new query derived from a Database
551 This function is utilized by __init__() and usually does not need to
554 :param db: Database to create the query from.
555 :type db: :class:`Database`
556 :param querystr: The query string
557 :type querystr: utf-8 encoded str or unicode
559 :exception: :exc:`NotmuchError`
561 * STATUS.NOT_INITIALIZED if db is not inited
562 * STATUS.NULL_POINTER if the query creation failed
566 raise NotmuchError(STATUS.NOT_INITIALIZED)
567 # create reference to parent db to keep it alive
569 # create query, return None if too little mem available
570 query_p = Query._create(db.db_p, _str(querystr))
572 NotmuchError(STATUS.NULL_POINTER)
573 self._query = query_p
575 def set_sort(self, sort):
576 """Set the sort order future results will be delivered in
578 Wraps the underlying *notmuch_query_set_sort* function.
580 :param sort: Sort order (see :attr:`Query.SORT`)
582 :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if query has not
585 if self._query is None:
586 raise NotmuchError(STATUS.NOT_INITIALIZED)
589 nmlib.notmuch_query_set_sort(self._query, sort)
591 def search_threads(self):
592 """Execute a query for threads
594 Execute a query for threads, returning a :class:`Threads` iterator.
595 The returned threads are owned by the query and as such, will only be
596 valid until the Query is deleted.
598 The method sets :attr:`Message.FLAG`\.MATCH for those messages that
599 match the query. The method :meth:`Message.get_flag` allows us
600 to get the value of this flag.
602 Technically, it wraps the underlying
603 *notmuch_query_search_threads* function.
605 :returns: :class:`Threads`
606 :exception: :exc:`NotmuchError`
608 * STATUS.NOT_INITIALIZED if query is not inited
609 * STATUS.NULL_POINTER if search_threads failed
611 if self._query is None:
612 raise NotmuchError(STATUS.NOT_INITIALIZED)
614 threads_p = Query._search_threads(self._query)
616 if threads_p is None:
617 raise NotmuchError(STATUS.NULL_POINTER)
619 return Threads(threads_p, self)
621 def search_messages(self):
622 """Filter messages according to the query and return
623 :class:`Messages` in the defined sort order
625 Technically, it wraps the underlying
626 *notmuch_query_search_messages* function.
628 :returns: :class:`Messages`
629 :exception: :exc:`NotmuchError`
631 * STATUS.NOT_INITIALIZED if query is not inited
632 * STATUS.NULL_POINTER if search_messages failed
634 if self._query is None:
635 raise NotmuchError(STATUS.NOT_INITIALIZED)
637 msgs_p = Query._search_messages(self._query)
640 NotmuchError(STATUS.NULL_POINTER)
642 return Messages(msgs_p, self)
644 def count_messages(self):
645 """Estimate the number of messages matching the query
647 This function performs a search and returns Xapian's best
648 guess as to the number of matching messages. It is much faster
649 than performing :meth:`search_messages` and counting the
650 result with `len()` (although it always returned the same
651 result in my tests). Technically, it wraps the underlying
652 *notmuch_query_count_messages* function.
654 :returns: :class:`Messages`
655 :exception: :exc:`NotmuchError`
657 * STATUS.NOT_INITIALIZED if query is not inited
659 if self._query is None:
660 raise NotmuchError(STATUS.NOT_INITIALIZED)
662 return Query._count_messages(self._query)
665 """Close and free the Query"""
666 if self._query is not None:
667 nmlib.notmuch_query_destroy(self._query)
670 class Directory(object):
671 """Represents a directory entry in the notmuch directory
673 Modifying attributes of this object will modify the
674 database, not the real directory attributes.
676 The Directory object is usually derived from another object
677 e.g. via :meth:`Database.get_directory`, and will automatically be
678 become invalid whenever that parent is deleted. You should
679 therefore initialized this object handing it a reference to the
680 parent, preventing the parent from automatically being garbage
684 """notmuch_directory_get_mtime"""
685 _get_mtime = nmlib.notmuch_directory_get_mtime
686 _get_mtime.restype = c_long
688 """notmuch_directory_set_mtime"""
689 _set_mtime = nmlib.notmuch_directory_set_mtime
690 _set_mtime.argtypes = [c_char_p, c_long]
692 """notmuch_directory_get_child_files"""
693 _get_child_files = nmlib.notmuch_directory_get_child_files
694 _get_child_files.restype = c_void_p
696 """notmuch_directory_get_child_directories"""
697 _get_child_directories = nmlib.notmuch_directory_get_child_directories
698 _get_child_directories.restype = c_void_p
700 def _verify_dir_initialized(self):
701 """Raises a NotmuchError(STATUS.NOT_INITIALIZED) if dir_p is None"""
702 if self._dir_p is None:
703 raise NotmuchError(STATUS.NOT_INITIALIZED)
705 def __init__(self, path, dir_p, parent):
707 :param path: The absolute path of the directory object as unicode.
708 :param dir_p: The pointer to an internal notmuch_directory_t object.
709 :param parent: The object this Directory is derived from
710 (usually a :class:`Database`). We do not directly use
711 this, but store a reference to it as long as
712 this Directory object lives. This keeps the
715 assert isinstance(path, unicode), "Path needs to be an UNICODE object"
718 self._parent = parent
720 def set_mtime(self, mtime):
721 """Sets the mtime value of this directory in the database
723 The intention is for the caller to use the mtime to allow efficient
724 identification of new messages to be added to the database. The
725 recommended usage is as follows:
727 * Read the mtime of a directory from the filesystem
729 * Call :meth:`Database.add_message` for all mail files in
732 * Call notmuch_directory_set_mtime with the mtime read from the
733 filesystem. Then, when wanting to check for updates to the
734 directory in the future, the client can call :meth:`get_mtime`
735 and know that it only needs to add files if the mtime of the
736 directory and files are newer than the stored timestamp.
738 .. note:: :meth:`get_mtime` function does not allow the caller
739 to distinguish a timestamp of 0 from a non-existent
740 timestamp. So don't store a timestamp of 0 unless you are
741 comfortable with that.
743 :param mtime: A (time_t) timestamp
744 :returns: Nothing on success, raising an exception on failure.
745 :exception: :exc:`NotmuchError`:
747 STATUS.XAPIAN_EXCEPTION
748 A Xapian exception occurred, mtime not stored.
749 STATUS.READ_ONLY_DATABASE
750 Database was opened in read-only mode so directory
751 mtime cannot be modified.
752 STATUS.NOT_INITIALIZED
753 The directory has not been initialized
755 #Raise a NotmuchError(STATUS.NOT_INITIALIZED) if the dir_p is None
756 self._verify_dir_initialized()
758 #TODO: make sure, we convert the mtime parameter to a 'c_long'
759 status = Directory._set_mtime(self._dir_p, mtime)
762 if status == STATUS.SUCCESS:
764 #fail with Exception otherwise
765 raise NotmuchError(status)
768 """Gets the mtime value of this directory in the database
770 Retrieves a previously stored mtime for this directory.
772 :param mtime: A (time_t) timestamp
773 :returns: Nothing on success, raising an exception on failure.
774 :exception: :exc:`NotmuchError`:
776 STATUS.NOT_INITIALIZED
777 The directory has not been initialized
779 #Raise a NotmuchError(STATUS.NOT_INITIALIZED) if self.dir_p is None
780 self._verify_dir_initialized()
782 return Directory._get_mtime(self._dir_p)
784 # Make mtime attribute a property of Directory()
785 mtime = property(get_mtime, set_mtime, doc="""Property that allows getting
786 and setting of the Directory *mtime* (read-write)
788 See :meth:`get_mtime` and :meth:`set_mtime` for usage and
789 possible exceptions.""")
791 def get_child_files(self):
792 """Gets a Filenames iterator listing all the filenames of
793 messages in the database within the given directory.
795 The returned filenames will be the basename-entries only (not
798 #Raise a NotmuchError(STATUS.NOT_INITIALIZED) if self._dir_p is None
799 self._verify_dir_initialized()
801 files_p = Directory._get_child_files(self._dir_p)
802 return Filenames(files_p, self)
804 def get_child_directories(self):
805 """Gets a :class:`Filenames` iterator listing all the filenames of
806 sub-directories in the database within the given directory
808 The returned filenames will be the basename-entries only (not
811 #Raise a NotmuchError(STATUS.NOT_INITIALIZED) if self._dir_p is None
812 self._verify_dir_initialized()
814 files_p = Directory._get_child_directories(self._dir_p)
815 return Filenames(files_p, self)
819 """Returns the absolute path of this Directory (read-only)"""
823 """Object representation"""
824 return "<notmuch Directory object '%s'>" % self._path
827 """Close and free the Directory"""
828 if self._dir_p is not None:
829 nmlib.notmuch_directory_destroy(self._dir_p)
832 class Filenames(object):
833 """An iterator over File- or Directory names stored in the database"""
835 #notmuch_filenames_get
836 _get = nmlib.notmuch_filenames_get
837 _get.restype = c_char_p
839 def __init__(self, files_p, parent):
841 :param files_p: The pointer to an internal notmuch_filenames_t object.
842 :param parent: The object this Directory is derived from
843 (usually a Directory()). We do not directly use
844 this, but store a reference to it as long as
845 this Directory object lives. This keeps the
848 self._files_p = files_p
849 self._parent = parent
852 """ Make Filenames an iterator """
856 if self._files_p is None:
857 raise NotmuchError(STATUS.NOT_INITIALIZED)
859 if not nmlib.notmuch_filenames_valid(self._files_p):
863 file = Filenames._get(self._files_p)
864 nmlib.notmuch_filenames_move_to_next(self._files_p)
868 """len(:class:`Filenames`) returns the number of contained files
870 .. note:: As this iterates over the files, we will not be able to
871 iterate over them again! So this will fail::
874 files = Database().get_directory('').get_child_files()
875 if len(files) > 0: #this 'exhausts' msgs
876 # next line raises NotmuchError(STATUS.NOT_INITIALIZED)!!!
877 for file in files: print file
879 if self._files_p is None:
880 raise NotmuchError(STATUS.NOT_INITIALIZED)
883 while nmlib.notmuch_filenames_valid(self._files_p):
884 nmlib.notmuch_filenames_move_to_next(self._files_p)
890 """Close and free Filenames"""
891 if self._files_p is not None:
892 nmlib.notmuch_filenames_destroy(self._files_p)