- :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 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.
- """
- if db.db_p is None:
- raise NotmuchError(STATUS.NOT_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 query_p is None:
- raise NotmuchError(STATUS.NULL_POINTER)
- self._query = query_p
-
- def set_sort(self, sort):
- """Set the sort order future results will be delivered in
-
- :param sort: Sort order (see :attr:`Query.SORT`)
- """
- if self._query is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
-
- self.sort = sort
- nmlib.notmuch_query_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
- """
- if self._query is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
-
- threads_p = Query._search_threads(self._query)
-
- if threads_p is None:
- raise NotmuchError(STATUS.NULL_POINTER)
-
- 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
- """
- if self._query is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
-
- msgs_p = Query._search_messages(self._query)
-
- if msgs_p is None:
- raise NotmuchError(STATUS.NULL_POINTER)
-
- 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`
- """
- if self._query is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
-
- return Query._count_messages(self._query)
-
- def __del__(self):
- """Close and free the Query"""
- if self._query is not None:
- nmlib.notmuch_query_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.
- """