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, NotInitializedError,
23 OutOfMemoryError, XapianError, Enum, _str)
24 from notmuch.thread import Threads
25 from notmuch.message import Messages, Message
26 from notmuch.tag import Tags
28 class Database(object):
29 """The :class:`Database` is the highest-level object that notmuch
30 provides. It references a notmuch database, and can be opened in
31 read-only or read-write mode. A :class:`Query` can be derived from
32 or be applied to a specific database to find messages. Also adding
33 and removing messages to the database happens via this
34 object. Modifications to the database are not atmic by default (see
35 :meth:`begin_atomic`) and once a database has been modified, all
36 other database objects pointing to the same data-base will throw an
37 :exc:`XapianError` as the underlying database has been
38 modified. Close and reopen the database to continue working with it.
40 .. note:: Any function in this class can and will throw an
41 :exc:`NotInitializedError` if the database was not
42 intitialized properly.
44 .. note:: Do remember that as soon as we tear down (e.g. via `del
45 db`) this object, all underlying derived objects such as
46 queries, threads, messages, tags etc will be freed by the
47 underlying library as well. Accessing these objects will lead
48 to segfaults and other unexpected behavior. See above for
52 """Class attribute to cache user's default database"""
54 MODE = Enum(['READ_ONLY', 'READ_WRITE'])
55 """Constants: Mode in which to open the database"""
57 """notmuch_database_get_directory"""
58 _get_directory = nmlib.notmuch_database_get_directory
59 _get_directory.restype = c_void_p
61 """notmuch_database_get_path"""
62 _get_path = nmlib.notmuch_database_get_path
63 _get_path.restype = c_char_p
65 """notmuch_database_get_version"""
66 _get_version = nmlib.notmuch_database_get_version
67 _get_version.restype = c_uint
69 """notmuch_database_open"""
70 _open = nmlib.notmuch_database_open
71 _open.restype = c_void_p
73 """notmuch_database_upgrade"""
74 _upgrade = nmlib.notmuch_database_upgrade
75 _upgrade.argtypes = [c_void_p, c_void_p, c_void_p]
77 """ notmuch_database_find_message"""
78 _find_message = nmlib.notmuch_database_find_message
80 """notmuch_database_find_message_by_filename"""
81 _find_message_by_filename = nmlib.notmuch_database_find_message_by_filename
83 """notmuch_database_get_all_tags"""
84 _get_all_tags = nmlib.notmuch_database_get_all_tags
85 _get_all_tags.restype = c_void_p
87 """notmuch_database_create"""
88 _create = nmlib.notmuch_database_create
89 _create.restype = c_void_p
91 def __init__(self, path=None, create=False, mode=0):
92 """If *path* is `None`, we will try to read a users notmuch
93 configuration and use his configured database. The location of the
94 configuration file can be specified through the environment variable
95 *NOTMUCH_CONFIG*, falling back to the default `~/.notmuch-config`.
97 If *create* is `True`, the database will always be created in
98 :attr:`MODE`.READ_WRITE mode. Default mode for opening is READ_ONLY.
100 :param path: Directory to open/create the database in (see
101 above for behavior if `None`)
102 :type path: `str` or `None`
103 :param create: Pass `False` to open an existing, `True` to create a new
106 :param mode: Mode to open a database in. Is always
107 :attr:`MODE`.READ_WRITE when creating a new one.
108 :type mode: :attr:`MODE`
109 :exception: :exc:`NotmuchError` or derived exception in case of
114 # no path specified. use a user's default database
115 if Database._std_db_path is None:
116 #the following line throws a NotmuchError if it fails
117 Database._std_db_path = self._get_user_default_db()
118 path = Database._std_db_path
121 self.open(path, mode)
125 def _assert_db_is_initialized(self):
126 """Raises :exc:`NotInitializedError` if self._db is `None`"""
128 raise NotInitializedError()
130 def create(self, path):
131 """Creates a new notmuch database
133 This function is used by __init__() and usually does not need
134 to be called directly. It wraps the underlying
135 *notmuch_database_create* function and creates a new notmuch
136 database at *path*. It will always return a database in :attr:`MODE`
137 .READ_WRITE mode as creating an empty database for
138 reading only does not make a great deal of sense.
140 :param path: A directory in which we should create the database.
143 :exception: :exc:`NotmuchError` in case of any failure
144 (possibly after printing an error message on stderr).
146 if self._db is not None:
147 raise NotmuchError(message="Cannot create db, this Database() "
148 "already has an open one.")
150 res = Database._create(_str(path), Database.MODE.READ_WRITE)
154 message="Could not create the specified database")
157 def open(self, path, mode=0):
158 """Opens an existing database
160 This function is used by __init__() and usually does not need
161 to be called directly. It wraps the underlying
162 *notmuch_database_open* function.
164 :param status: Open the database in read-only or read-write mode
165 :type status: :attr:`MODE`
167 :exception: Raises :exc:`NotmuchError` in case
168 of any failure (possibly after printing an error message on stderr).
170 res = Database._open(_str(path), mode)
173 raise NotmuchError(message="Could not open the specified database")
177 """Returns the file path of an open database"""
178 self._assert_db_is_initialized()
179 return Database._get_path(self._db).decode('utf-8')
181 def get_version(self):
182 """Returns the database format version
184 :returns: The database version as positive integer
186 self._assert_db_is_initialized()
187 return Database._get_version(self._db)
189 def needs_upgrade(self):
190 """Does this database need to be upgraded before writing to it?
192 If this function returns `True` then no functions that modify the
193 database (:meth:`add_message`,
194 :meth:`Message.add_tag`, :meth:`Directory.set_mtime`,
195 etc.) will work unless :meth:`upgrade` is called successfully first.
197 :returns: `True` or `False`
199 self._assert_db_is_initialized()
200 return nmlib.notmuch_database_needs_upgrade(self._db)
203 """Upgrades the current database
205 After opening a database in read-write mode, the client should
206 check if an upgrade is needed (notmuch_database_needs_upgrade) and
207 if so, upgrade with this function before making any modifications.
209 NOT IMPLEMENTED: The optional progress_notify callback can be
210 used by the caller to provide progress indication to the
211 user. If non-NULL it will be called periodically with
212 'progress' as a floating-point value in the range of [0.0..1.0]
213 indicating the progress made so far in the upgrade process.
215 :TODO: catch exceptions, document return values and etc...
217 self._assert_db_is_initialized()
218 status = Database._upgrade(self._db, None, None)
219 #TODO: catch exceptions, document return values and etc
222 def begin_atomic(self):
223 """Begin an atomic database operation
225 Any modifications performed between a successful
226 :meth:`begin_atomic` and a :meth:`end_atomic` will be applied to
227 the database atomically. Note that, unlike a typical database
228 transaction, this only ensures atomicity, not durability;
229 neither begin nor end necessarily flush modifications to disk.
231 :returns: :attr:`STATUS`.SUCCESS or raises
233 :exception: :exc:`NotmuchError`:
234 :attr:`STATUS`.XAPIAN_EXCEPTION
235 Xapian exception occurred; atomic section not entered.
237 *Added in notmuch 0.9*"""
238 self._assert_db_is_initialized()
239 status = nmlib.notmuch_database_begin_atomic(self._db)
240 if status != STATUS.SUCCESS:
241 raise NotmuchError(status)
244 def end_atomic(self):
245 """Indicate the end of an atomic database operation
247 See :meth:`begin_atomic` for details.
249 :returns: :attr:`STATUS`.SUCCESS or raises
253 :attr:`STATUS`.XAPIAN_EXCEPTION
254 A Xapian exception occurred; atomic section not
256 :attr:`STATUS`.UNBALANCED_ATOMIC:
257 end_atomic has been called more times than begin_atomic.
259 *Added in notmuch 0.9*"""
260 self._assert_db_is_initialized()
261 status = nmlib.notmuch_database_end_atomic(self._db)
262 if status != STATUS.SUCCESS:
263 raise NotmuchError(status)
266 def get_directory(self, path):
267 """Returns a :class:`Directory` of path,
268 (creating it if it does not exist(?))
270 .. warning:: This call needs a writeable database in
271 :attr:`Database.MODE`.READ_WRITE mode. The underlying library will exit the
272 program if this method is used on a read-only database!
274 :param path: An unicode string containing the path relative to the path
275 of database (see :meth:`get_path`), or else should be an absolute path
276 with initial components that match the path of 'database'.
277 :returns: :class:`Directory` or raises an exception.
279 :exc:`NotmuchError` with :attr:`STATUS`.FILE_ERROR
280 If path is not relative database or absolute with initial
281 components same as database.
283 self._assert_db_is_initialized()
284 # sanity checking if path is valid, and make path absolute
285 if path[0] == os.sep:
286 # we got an absolute path
287 if not path.startswith(self.get_path()):
288 # but its initial components are not equal to the db path
289 raise NotmuchError(STATUS.FILE_ERROR,
290 message="Database().get_directory() called "
291 "with a wrong absolute path.")
294 #we got a relative path, make it absolute
295 abs_dirpath = os.path.abspath(os.path.join(self.get_path(), path))
297 dir_p = Database._get_directory(self._db, _str(path))
299 # return the Directory, init it with the absolute path
300 return Directory(_str(abs_dirpath), dir_p, self)
302 def add_message(self, filename, sync_maildir_flags=False):
303 """Adds a new message to the database
305 :param filename: should be a path relative to the path of the
306 open database (see :meth:`get_path`), or else should be an
307 absolute filename with initial components that match the
308 path of the database.
310 The file should be a single mail message (not a
311 multi-message mbox) that is expected to remain at its
312 current location, since the notmuch database will reference
313 the filename, and will not copy the entire contents of the
316 :param sync_maildir_flags: If the message contains Maildir
317 flags, we will -depending on the notmuch configuration- sync
318 those tags to initial notmuch tags, if set to `True`. It is
319 `False` by default to remain consistent with the libnotmuch
320 API. You might want to look into the underlying method
321 :meth:`Message.maildir_flags_to_tags`.
323 :returns: On success, we return
325 1) a :class:`Message` object that can be used for things
326 such as adding tags to the just-added message.
327 2) one of the following :attr:`STATUS` values:
329 :attr:`STATUS`.SUCCESS
330 Message successfully added to database.
331 :attr:`STATUS`.DUPLICATE_MESSAGE_ID
332 Message has the same message ID as another message already
333 in the database. The new filename was successfully added
334 to the list of the filenames for the existing message.
336 :rtype: 2-tuple(:class:`Message`, :attr:`STATUS`)
338 :exception: Raises a :exc:`NotmuchError` with the following meaning.
339 If such an exception occurs, nothing was added to the database.
341 :attr:`STATUS`.FILE_ERROR
342 An error occurred trying to open the file, (such as
343 permission denied, or file not found, etc.).
344 :attr:`STATUS`.FILE_NOT_EMAIL
345 The contents of filename don't look like an email
347 :attr:`STATUS`.READ_ONLY_DATABASE
348 Database was opened in read-only mode so no message can
351 self._assert_db_is_initialized()
353 status = nmlib.notmuch_database_add_message(self._db,
357 if not status in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
358 raise NotmuchError(status)
360 #construct Message() and return
361 msg = Message(msg_p, self)
362 #automatic sync initial tags from Maildir flags
363 if sync_maildir_flags:
364 msg.maildir_flags_to_tags()
367 def remove_message(self, filename):
368 """Removes a message (filename) from the given notmuch database
370 Note that only this particular filename association is removed from
371 the database. If the same message (as determined by the message ID)
372 is still available via other filenames, then the message will
373 persist in the database for those filenames. When the last filename
374 is removed for a particular message, the database content for that
375 message will be entirely removed.
377 :returns: A :attr:`STATUS` value with the following meaning:
379 :attr:`STATUS`.SUCCESS
380 The last filename was removed and the message was removed
382 :attr:`STATUS`.DUPLICATE_MESSAGE_ID
383 This filename was removed but the message persists in the
384 database with at least one other filename.
386 :exception: Raises a :exc:`NotmuchError` with the following meaning.
387 If such an exception occurs, nothing was removed from the
390 :attr:`STATUS`.READ_ONLY_DATABASE
391 Database was opened in read-only mode so no message can be
394 self._assert_db_is_initialized()
395 return nmlib.notmuch_database_remove_message(self._db,
398 def find_message(self, msgid):
399 """Returns a :class:`Message` as identified by its message ID
401 Wraps the underlying *notmuch_database_find_message* function.
403 :param msgid: The message ID
404 :type msgid: unicode or str
405 :returns: :class:`Message` or `None` if no message is found.
407 :exc:`OutOfMemoryError`
408 If an Out-of-memory occured while constructing the message.
410 In case of a Xapian Exception. These exceptions
411 include "Database modified" situations, e.g. when the
412 notmuch database has been modified by another program
413 in the meantime. In this case, you should close and
414 reopen the database and retry.
415 :exc:`NotInitializedError` if
416 the database was not intitialized.
418 self._assert_db_is_initialized()
420 status = Database._find_message(self._db, _str(msgid), byref(msg_p))
421 if status != STATUS.SUCCESS:
422 raise NotmuchError(status)
423 return msg_p and Message(msg_p, self) or None
425 def find_message_by_filename(self, filename):
426 """Find a message with the given filename
428 .. warning:: This call needs a writeable database in
429 :attr:`Database.MODE`.READ_WRITE mode. The underlying library will
430 exit the program if this method is used on a read-only
433 :returns: If the database contains a message with the given
434 filename, then a class:`Message:` is returned. This
435 function returns None if no message is found with the given
439 :exc:`OutOfMemoryError`
440 If an Out-of-memory occured while constructing the message.
442 In case of a Xapian Exception. These exceptions
443 include "Database modified" situations, e.g. when the
444 notmuch database has been modified by another program
445 in the meantime. In this case, you should close and
446 reopen the database and retry.
447 :exc:`NotInitializedError` if
448 the database was not intitialized.
450 *Added in notmuch 0.9*"""
451 self._assert_db_is_initialized()
453 status = Database._find_message_by_filename(self._db, _str(filename),
455 if status != STATUS.SUCCESS:
456 raise NotmuchError(status)
457 return msg_p and Message(msg_p, self) or None
459 def get_all_tags(self):
460 """Returns :class:`Tags` with a list of all tags found in the database
462 :returns: :class:`Tags`
463 :execption: :exc:`NotmuchError` with :attr:`STATUS`.NULL_POINTER on error
465 self._assert_db_is_initialized()
466 tags_p = Database._get_all_tags(self._db)
468 raise NotmuchError(STATUS.NULL_POINTER)
469 return Tags(tags_p, self)
471 def create_query(self, querystring):
472 """Returns a :class:`Query` derived from this database
474 This is a shorthand method for doing::
477 # Automatically frees the Database() when 'q' is deleted
479 q = Database(dbpath).create_query('from:"Biene Maja"')
481 # long version, which is functionally equivalent but will keep the
482 # Database in the 'db' variable around after we delete 'q':
484 db = Database(dbpath)
485 q = Query(db,'from:"Biene Maja"')
487 This function is a python extension and not in the underlying C API.
489 self._assert_db_is_initialized()
490 return Query(self, querystring)
493 return "'Notmuch DB " + self.get_path() + "'"
496 """Close and free the notmuch database if needed"""
497 if self._db is not None:
498 nmlib.notmuch_database_close(self._db)
500 def _get_user_default_db(self):
501 """ Reads a user's notmuch config and returns his db location
503 Throws a NotmuchError if it cannot find it"""
504 from ConfigParser import SafeConfigParser
505 config = SafeConfigParser()
506 conf_f = os.getenv('NOTMUCH_CONFIG',
507 os.path.expanduser('~/.notmuch-config'))
509 if not config.has_option('database', 'path'):
510 raise NotmuchError(message="No DB path specified"
511 " and no user default found")
512 return config.get('database', 'path').decode('utf-8')
516 """Property returning a pointer to `notmuch_database_t` or `None`
518 This should normally not be needed by a user (and is not yet
519 guaranteed to remain stable in future versions).
525 """Represents a search query on an opened :class:`Database`.
527 A query selects and filters a subset of messages from the notmuch
528 database we derive from.
530 :class:`Query` provides an instance attribute :attr:`sort`, which
531 contains the sort order (if specified via :meth:`set_sort`) or
534 Any function in this class may throw an :exc:`NotInitializedError`
535 in case the underlying query object was not set up correctly.
537 .. note:: Do remember that as soon as we tear down this object,
538 all underlying derived objects such as threads,
539 messages, tags etc will be freed by the underlying library
540 as well. Accessing these objects will lead to segfaults and
541 other unexpected behavior. See above for more details.
544 SORT = Enum(['OLDEST_FIRST', 'NEWEST_FIRST', 'MESSAGE_ID', 'UNSORTED'])
545 """Constants: Sort order in which to return results"""
547 """notmuch_query_create"""
548 _create = nmlib.notmuch_query_create
549 _create.restype = c_void_p
551 """notmuch_query_search_threads"""
552 _search_threads = nmlib.notmuch_query_search_threads
553 _search_threads.restype = c_void_p
555 """notmuch_query_search_messages"""
556 _search_messages = nmlib.notmuch_query_search_messages
557 _search_messages.restype = c_void_p
559 """notmuch_query_count_messages"""
560 _count_messages = nmlib.notmuch_query_count_messages
561 _count_messages.restype = c_uint
563 def __init__(self, db, querystr):
565 :param db: An open database which we derive the Query from.
566 :type db: :class:`Database`
567 :param querystr: The query string for the message.
568 :type querystr: utf-8 encoded str or unicode
573 self.create(db, querystr)
575 def create(self, db, querystr):
576 """Creates a new query derived from a Database
578 This function is utilized by __init__() and usually does not need to
581 :param db: Database to create the query from.
582 :type db: :class:`Database`
583 :param querystr: The query string
584 :type querystr: utf-8 encoded str or unicode
587 :exc:`NullPointerError` if the query creation failed
588 (e.g. too little memory).
589 :exc:`NotInitializedError` if the underlying db was not
593 raise NotmuchError(STATUS.NOT_INITIALIZED)
594 # create reference to parent db to keep it alive
596 # create query, return None if too little mem available
597 query_p = Query._create(db.db_p, _str(querystr))
599 raise NotmuchError(STATUS.NULL_POINTER)
600 self._query = query_p
602 def set_sort(self, sort):
603 """Set the sort order future results will be delivered in
605 :param sort: Sort order (see :attr:`Query.SORT`)
607 if self._query is None:
608 raise NotmuchError(STATUS.NOT_INITIALIZED)
611 nmlib.notmuch_query_set_sort(self._query, sort)
613 def search_threads(self):
614 """Execute a query for threads
616 Execute a query for threads, returning a :class:`Threads` iterator.
617 The returned threads are owned by the query and as such, will only be
618 valid until the Query is deleted.
620 The method sets :attr:`Message.FLAG`\.MATCH for those messages that
621 match the query. The method :meth:`Message.get_flag` allows us
622 to get the value of this flag.
624 :returns: :class:`Threads`
625 :exception: :exc:`NullPointerError` if search_threads failed
627 if self._query is None:
628 raise NotmuchError(STATUS.NOT_INITIALIZED)
630 threads_p = Query._search_threads(self._query)
632 if threads_p is None:
633 raise NotmuchError(STATUS.NULL_POINTER)
635 return Threads(threads_p, self)
637 def search_messages(self):
638 """Filter messages according to the query and return
639 :class:`Messages` in the defined sort order
641 :returns: :class:`Messages`
642 :exception: :exc:`NullPointerError` if search_messages failed
644 if self._query is None:
645 raise NotmuchError(STATUS.NOT_INITIALIZED)
647 msgs_p = Query._search_messages(self._query)
650 raise NotmuchError(STATUS.NULL_POINTER)
652 return Messages(msgs_p, self)
654 def count_messages(self):
655 """Estimate the number of messages matching the query
657 This function performs a search and returns Xapian's best
658 guess as to the number of matching messages. It is much faster
659 than performing :meth:`search_messages` and counting the
660 result with `len()` (although it always returned the same
661 result in my tests). Technically, it wraps the underlying
662 *notmuch_query_count_messages* function.
664 :returns: :class:`Messages`
666 if self._query is None:
667 raise NotmuchError(STATUS.NOT_INITIALIZED)
669 return Query._count_messages(self._query)
672 """Close and free the Query"""
673 if self._query is not None:
674 nmlib.notmuch_query_destroy(self._query)
677 class Directory(object):
678 """Represents a directory entry in the notmuch directory
680 Modifying attributes of this object will modify the
681 database, not the real directory attributes.
683 The Directory object is usually derived from another object
684 e.g. via :meth:`Database.get_directory`, and will automatically be
685 become invalid whenever that parent is deleted. You should
686 therefore initialized this object handing it a reference to the
687 parent, preventing the parent from automatically being garbage
691 """notmuch_directory_get_mtime"""
692 _get_mtime = nmlib.notmuch_directory_get_mtime
693 _get_mtime.restype = c_long
695 """notmuch_directory_set_mtime"""
696 _set_mtime = nmlib.notmuch_directory_set_mtime
697 _set_mtime.argtypes = [c_char_p, c_long]
699 """notmuch_directory_get_child_files"""
700 _get_child_files = nmlib.notmuch_directory_get_child_files
701 _get_child_files.restype = c_void_p
703 """notmuch_directory_get_child_directories"""
704 _get_child_directories = nmlib.notmuch_directory_get_child_directories
705 _get_child_directories.restype = c_void_p
707 def _assert_dir_is_initialized(self):
708 """Raises a NotmuchError(:attr:`STATUS`.NOT_INITIALIZED) if dir_p is None"""
709 if self._dir_p is None:
710 raise NotmuchError(STATUS.NOT_INITIALIZED)
712 def __init__(self, path, dir_p, parent):
714 :param path: The absolute path of the directory object as unicode.
715 :param dir_p: The pointer to an internal notmuch_directory_t object.
716 :param parent: The object this Directory is derived from
717 (usually a :class:`Database`). We do not directly use
718 this, but store a reference to it as long as
719 this Directory object lives. This keeps the
722 assert isinstance(path, unicode), "Path needs to be an UNICODE object"
725 self._parent = parent
727 def set_mtime(self, mtime):
728 """Sets the mtime value of this directory in the database
730 The intention is for the caller to use the mtime to allow efficient
731 identification of new messages to be added to the database. The
732 recommended usage is as follows:
734 * Read the mtime of a directory from the filesystem
736 * Call :meth:`Database.add_message` for all mail files in
739 * Call notmuch_directory_set_mtime with the mtime read from the
740 filesystem. Then, when wanting to check for updates to the
741 directory in the future, the client can call :meth:`get_mtime`
742 and know that it only needs to add files if the mtime of the
743 directory and files are newer than the stored timestamp.
745 .. note:: :meth:`get_mtime` function does not allow the caller
746 to distinguish a timestamp of 0 from a non-existent
747 timestamp. So don't store a timestamp of 0 unless you are
748 comfortable with that.
750 :param mtime: A (time_t) timestamp
751 :returns: Nothing on success, raising an exception on failure.
752 :exception: :exc:`NotmuchError`:
754 :attr:`STATUS`.XAPIAN_EXCEPTION
755 A Xapian exception occurred, mtime not stored.
756 :attr:`STATUS`.READ_ONLY_DATABASE
757 Database was opened in read-only mode so directory
758 mtime cannot be modified.
759 :attr:`STATUS`.NOT_INITIALIZED
760 The directory has not been initialized
762 self._assert_dir_is_initialized()
763 #TODO: make sure, we convert the mtime parameter to a 'c_long'
764 status = Directory._set_mtime(self._dir_p, mtime)
767 if status == STATUS.SUCCESS:
769 #fail with Exception otherwise
770 raise NotmuchError(status)
773 """Gets the mtime value of this directory in the database
775 Retrieves a previously stored mtime for this directory.
777 :param mtime: A (time_t) timestamp
778 :returns: Nothing on success, raising an exception on failure.
779 :exception: :exc:`NotmuchError`:
781 :attr:`STATUS`.NOT_INITIALIZED
782 The directory has not been initialized
784 self._assert_dir_is_initialized()
785 return Directory._get_mtime(self._dir_p)
787 # Make mtime attribute a property of Directory()
788 mtime = property(get_mtime, set_mtime, doc="""Property that allows getting
789 and setting of the Directory *mtime* (read-write)
791 See :meth:`get_mtime` and :meth:`set_mtime` for usage and
792 possible exceptions.""")
794 def get_child_files(self):
795 """Gets a Filenames iterator listing all the filenames of
796 messages in the database within the given directory.
798 The returned filenames will be the basename-entries only (not
801 self._assert_dir_is_initialized()
802 files_p = Directory._get_child_files(self._dir_p)
803 return Filenames(files_p, self)
805 def get_child_directories(self):
806 """Gets a :class:`Filenames` iterator listing all the filenames of
807 sub-directories in the database within the given directory
809 The returned filenames will be the basename-entries only (not
812 self._assert_dir_is_initialized()
813 files_p = Directory._get_child_directories(self._dir_p)
814 return Filenames(files_p, self)
818 """Returns the absolute path of this Directory (read-only)"""
822 """Object representation"""
823 return "<notmuch Directory object '%s'>" % self._path
826 """Close and free the Directory"""
827 if self._dir_p is not None:
828 nmlib.notmuch_directory_destroy(self._dir_p)
831 class Filenames(object):
832 """An iterator over File- or Directory names stored in the database"""
834 #notmuch_filenames_get
835 _get = nmlib.notmuch_filenames_get
836 _get.restype = c_char_p
838 def __init__(self, files_p, parent):
840 :param files_p: The pointer to an internal notmuch_filenames_t object.
841 :param parent: The object this Directory is derived from
842 (usually a Directory()). We do not directly use
843 this, but store a reference to it as long as
844 this Directory object lives. This keeps the
847 self._files_p = files_p
848 self._parent = parent
851 """ Make Filenames an iterator """
855 if self._files_p is None:
856 raise NotmuchError(STATUS.NOT_INITIALIZED)
858 if not nmlib.notmuch_filenames_valid(self._files_p):
862 file = Filenames._get(self._files_p)
863 nmlib.notmuch_filenames_move_to_next(self._files_p)
867 """len(:class:`Filenames`) returns the number of contained files
869 .. note:: As this iterates over the files, we will not be able to
870 iterate over them again! So this will fail::
873 files = Database().get_directory('').get_child_files()
874 if len(files) > 0: #this 'exhausts' msgs
875 # next line raises NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)!!!
876 for file in files: print file
878 if self._files_p is None:
879 raise NotmuchError(STATUS.NOT_INITIALIZED)
882 while nmlib.notmuch_filenames_valid(self._files_p):
883 nmlib.notmuch_filenames_move_to_next(self._files_p)
889 """Close and free Filenames"""
890 if self._files_p is not None:
891 nmlib.notmuch_filenames_destroy(self._files_p)