- .. note:: Do remember that as soon as we tear down this object,
- all underlying derived objects such as threads,
- messages, tags etc will be freed by the underlying library
- as well. Accessing these objects will lead to segfaults and
- other unexpected behavior. See above for more details.
- """
- # constants
- SORT = Enum(['OLDEST_FIRST', 'NEWEST_FIRST', 'MESSAGE_ID', 'UNSORTED'])
- """Constants: Sort order in which to return results"""
-
- """notmuch_query_create"""
- _create = nmlib.notmuch_query_create
- _create.argtypes = [NotmuchDatabaseP, c_char_p]
- _create.restype = NotmuchQueryP
-
- """notmuch_query_search_threads"""
- _search_threads = nmlib.notmuch_query_search_threads
- _search_threads.argtypes = [NotmuchQueryP]
- _search_threads.restype = NotmuchThreadsP
-
- """notmuch_query_search_messages"""
- _search_messages = nmlib.notmuch_query_search_messages
- _search_messages.argtypes = [NotmuchQueryP]
- _search_messages.restype = NotmuchMessagesP
-
- """notmuch_query_count_messages"""
- _count_messages = nmlib.notmuch_query_count_messages
- _count_messages.argtypes = [NotmuchQueryP]
- _count_messages.restype = c_uint
-
- def __init__(self, db, querystr):
- """
- :param db: An open database which we derive the Query from.
- :type db: :class:`Database`
- :param querystr: The query string for the message.
- :type querystr: utf-8 encoded str or unicode
- """
- self._db = None
- self._query = None
- self.sort = None
- self.create(db, querystr)
-
- def _assert_query_is_initialized(self):
- """Raises :exc:`NotInitializedError` if self._query is `None`"""
- if self._query is None:
- raise NotInitializedError()
-
- def create(self, db, querystr):
- """Creates a new query derived from a Database
-
- This function is utilized by __init__() and usually does not need to
- be called directly.
-
- :param db: Database to create the query from.
- :type db: :class:`Database`
- :param querystr: The query string
- :type querystr: utf-8 encoded str or unicode
- :returns: Nothing
- :exception:
- :exc:`NullPointerError` if the query creation failed
- (e.g. too little memory).
- :exc:`NotInitializedError` if the underlying db was not
- intitialized.
- """
- db._assert_db_is_initialized()
- # create reference to parent db to keep it alive
- self._db = db
- # create query, return None if too little mem available
- query_p = Query._create(db.db_p, _str(querystr))
- if not query_p:
- raise NullPointerError
- self._query = query_p
-
- _set_sort = nmlib.notmuch_query_set_sort
- _set_sort.argtypes = [NotmuchQueryP, c_uint]
- _set_sort.argtypes = None
-
- def set_sort(self, sort):
- """Set the sort order future results will be delivered in
-
- :param sort: Sort order (see :attr:`Query.SORT`)
- """
- self._assert_query_is_initialized()
- self.sort = sort
- self._set_sort(self._query, sort)
-
- def search_threads(self):
- """Execute a query for threads
-
- Execute a query for threads, returning a :class:`Threads` iterator.
- The returned threads are owned by the query and as such, will only be
- valid until the Query is deleted.
-
- The method sets :attr:`Message.FLAG`\.MATCH for those messages that
- match the query. The method :meth:`Message.get_flag` allows us
- to get the value of this flag.
-
- :returns: :class:`Threads`
- :exception: :exc:`NullPointerError` if search_threads failed
- """
- self._assert_query_is_initialized()
- threads_p = Query._search_threads(self._query)
-
- if not threads_p:
- raise NullPointerError
- return Threads(threads_p, self)
-
- def search_messages(self):
- """Filter messages according to the query and return
- :class:`Messages` in the defined sort order
-
- :returns: :class:`Messages`
- :exception: :exc:`NullPointerError` if search_messages failed
- """
- self._assert_query_is_initialized()
- msgs_p = Query._search_messages(self._query)
-
- if not msgs_p:
- raise NullPointerError
- return Messages(msgs_p, self)
-
- def count_messages(self):
- """Estimate the number of messages matching the query
-
- This function performs a search and returns Xapian's best
- guess as to the number of matching messages. It is much faster
- than performing :meth:`search_messages` and counting the
- result with `len()` (although it always returned the same
- result in my tests). Technically, it wraps the underlying
- *notmuch_query_count_messages* function.
-
- :returns: :class:`Messages`
- """
- self._assert_query_is_initialized()
- return Query._count_messages(self._query)
-
- _destroy = nmlib.notmuch_query_destroy
- _destroy.argtypes = [NotmuchQueryP]
- _destroy.restype = None
-
- def __del__(self):
- """Close and free the Query"""
- if self._query is not None:
- self._destroy(self._query)
-
-
-class Directory(object):
- """Represents a directory entry in the notmuch directory
-
- Modifying attributes of this object will modify the
- database, not the real directory attributes.
-
- The Directory object is usually derived from another object
- e.g. via :meth:`Database.get_directory`, and will automatically be
- become invalid whenever that parent is deleted. You should
- therefore initialized this object handing it a reference to the
- parent, preventing the parent from automatically being garbage
- collected.
- """
-
- """notmuch_directory_get_mtime"""
- _get_mtime = nmlib.notmuch_directory_get_mtime
- _get_mtime.argtypes = [NotmuchDirectoryP]
- _get_mtime.restype = c_long
-
- """notmuch_directory_set_mtime"""
- _set_mtime = nmlib.notmuch_directory_set_mtime
- _set_mtime.argtypes = [NotmuchDirectoryP, c_long]
- _set_mtime.restype = c_uint
-
- """notmuch_directory_get_child_files"""
- _get_child_files = nmlib.notmuch_directory_get_child_files
- _get_child_files.argtypes = [NotmuchDirectoryP]
- _get_child_files.restype = NotmuchFilenamesP
-
- """notmuch_directory_get_child_directories"""
- _get_child_directories = nmlib.notmuch_directory_get_child_directories
- _get_child_directories.argtypes = [NotmuchDirectoryP]
- _get_child_directories.restype = NotmuchFilenamesP
-
- def _assert_dir_is_initialized(self):
- """Raises a NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)
- if dir_p is None"""
- if not self._dir_p:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
-
- def __init__(self, path, dir_p, parent):
- """
- :param path: The absolute path of the directory object as unicode.
- :param dir_p: The pointer to an internal notmuch_directory_t object.
- :param parent: The object this Directory is derived from
- (usually a :class:`Database`). We do not directly use
- this, but store a reference to it as long as
- this Directory object lives. This keeps the
- parent object alive.
- """
- assert isinstance(path, unicode), "Path needs to be an UNICODE object"
- self._path = path
- self._dir_p = dir_p
- self._parent = parent
-
- def set_mtime(self, mtime):
- """Sets the mtime value of this directory in the database
-
- The intention is for the caller to use the mtime to allow efficient
- identification of new messages to be added to the database. The
- recommended usage is as follows:
-
- * Read the mtime of a directory from the filesystem
-
- * Call :meth:`Database.add_message` for all mail files in
- the directory
-
- * Call notmuch_directory_set_mtime with the mtime read from the
- filesystem. Then, when wanting to check for updates to the
- directory in the future, the client can call :meth:`get_mtime`
- and know that it only needs to add files if the mtime of the
- directory and files are newer than the stored timestamp.
-
- .. note::
-
- :meth:`get_mtime` function does not allow the caller to
- distinguish a timestamp of 0 from a non-existent timestamp. So
- don't store a timestamp of 0 unless you are comfortable with
- that.
-
- :param mtime: A (time_t) timestamp
- :returns: Nothing on success, raising an exception on failure.
- :exception: :exc:`NotmuchError`:
-
- :attr:`STATUS`.XAPIAN_EXCEPTION
- A Xapian exception occurred, mtime not stored.
- :attr:`STATUS`.READ_ONLY_DATABASE
- Database was opened in read-only mode so directory
- mtime cannot be modified.
- :attr:`STATUS`.NOT_INITIALIZED
- The directory has not been initialized
- """
- self._assert_dir_is_initialized()
- #TODO: make sure, we convert the mtime parameter to a 'c_long'
- status = Directory._set_mtime(self._dir_p, mtime)
-
- #return on success
- if status == STATUS.SUCCESS:
- return
- #fail with Exception otherwise
- raise NotmuchError(status)
-
- def get_mtime(self):
- """Gets the mtime value of this directory in the database
-
- Retrieves a previously stored mtime for this directory.
-
- :param mtime: A (time_t) timestamp
- :returns: Nothing on success, raising an exception on failure.
- :exception: :exc:`NotmuchError`:
-
- :attr:`STATUS`.NOT_INITIALIZED
- The directory has not been initialized