""" This file is part of notmuch. Notmuch is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. Notmuch is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with notmuch. If not, see . Copyright 2010 Sebastian Spaeth """ from ctypes import c_char_p, c_uint, POINTER, byref from .globals import ( nmlib, Enum, _str, NotmuchQueryP, NotmuchThreadsP, NotmuchDatabaseP, NotmuchMessagesP, ) from .errors import ( NotmuchError, NullPointerError, NotInitializedError, ) from .threads import Threads from .messages import Messages class Query(object): """Represents a search query on an opened :class:`Database`. A query selects and filters a subset of messages from the notmuch database we derive from. :class:`Query` provides an instance attribute :attr:`sort`, which contains the sort order (if specified via :meth:`set_sort`) or `None`. Any function in this class may throw an :exc:`NotInitializedError` in case the underlying query object was not set up correctly. .. 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""" 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 not self._query: raise NotInitializedError() """notmuch_query_create""" _create = nmlib.notmuch_query_create _create.argtypes = [NotmuchDatabaseP, c_char_p] _create.restype = NotmuchQueryP 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 :raises: :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, _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) _exclude_tag = nmlib.notmuch_query_add_tag_exclude _exclude_tag.argtypes = [NotmuchQueryP, c_char_p] _exclude_tag.resttype = None def exclude_tag(self, tagname): """Add a tag that will be excluded from the query results by default. This exclusion will be overridden if this tag appears explicitly in the query. :param tagname: Name of the tag to be excluded """ self._assert_query_is_initialized() self._exclude_tag(self._query, _str(tagname)) """notmuch_query_search_threads""" _search_threads = nmlib.notmuch_query_search_threads _search_threads.argtypes = [NotmuchQueryP, POINTER(NotmuchThreadsP)] _search_threads.restype = c_uint 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` :raises: :exc:`NullPointerError` if search_threads failed """ self._assert_query_is_initialized() threads_p = NotmuchThreadsP() # == NULL status = Query._search_threads(self._query, byref(threads_p)) if status != 0: raise NotmuchError(status) if not threads_p: raise NullPointerError return Threads(threads_p, self) """notmuch_query_search_messages_st""" _search_messages_st = nmlib.notmuch_query_search_messages_st _search_messages_st.argtypes = [NotmuchQueryP, POINTER(NotmuchMessagesP)] _search_messages_st.restype = c_uint def search_messages(self): """Filter messages according to the query and return :class:`Messages` in the defined sort order :returns: :class:`Messages` :raises: :exc:`NullPointerError` if search_messages failed """ self._assert_query_is_initialized() msgs_p = NotmuchMessagesP() # == NULL status = Query._search_messages_st(self._query, byref(msgs_p)) if status != 0: raise NotmuchError(status) if not msgs_p: raise NullPointerError return Messages(msgs_p, self) _count_messages = nmlib.notmuch_query_count_messages_st _count_messages.argtypes = [NotmuchQueryP, POINTER(c_uint)] _count_messages.restype = c_uint def count_messages(self): ''' This function performs a search and returns Xapian's best guess as to the number of matching messages. :returns: the estimated number of messages matching this query :rtype: int ''' self._assert_query_is_initialized() count = c_uint(0) status = Query._count_messages(self._query, byref(count)) if status != 0: raise NotmuchError(status) return count.value _count_threads = nmlib.notmuch_query_count_threads_st _count_threads.argtypes = [NotmuchQueryP, POINTER(c_uint)] _count_threads.restype = c_uint def count_threads(self): ''' This function performs a search and returns the number of unique thread IDs in the matching messages. This is the same as number of threads matching a search. Note that this is a significantly heavier operation than meth:`Query.count_messages`. :returns: the number of threads returned by this query :rtype: int ''' self._assert_query_is_initialized() count = c_uint(0) status = Query._count_threads(self._query, byref(count)) if status != 0: raise NotmuchError(status) return count.value _destroy = nmlib.notmuch_query_destroy _destroy.argtypes = [NotmuchQueryP] _destroy.restype = None def __del__(self): """Close and free the Query""" if self._query: self._destroy(self._query)