for more details.
You should have received a copy of the GNU General Public License
-along with notmuch. If not, see <http://www.gnu.org/licenses/>.
+along with notmuch. If not, see <https://www.gnu.org/licenses/>.
-Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>'
+Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>
"""
-from ctypes import c_char_p, c_uint
-from notmuch.globals import (
+from ctypes import c_char_p, c_uint, POINTER, byref
+from .globals import (
nmlib,
Enum,
_str,
NotmuchThreadsP,
NotmuchDatabaseP,
NotmuchMessagesP,
+)
+from .errors import (
+ NotmuchError,
NullPointerError,
NotInitializedError,
)
-from notmuch.thread import Threads
-from notmuch.message import Messages
+from .threads import Threads
+from .messages import Messages
class Query(object):
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.
def _assert_query_is_initialized(self):
"""Raises :exc:`NotInitializedError` if self._query is `None`"""
- 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
:type db: :class:`Database`
:param querystr: The query string
:type querystr: utf-8 encoded str or unicode
- :returns: Nothing
- :exception:
+ :raises:
:exc:`NullPointerError` if the query creation failed
(e.g. too little memory).
:exc:`NotInitializedError` if the underlying db was not
# 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))
+ query_p = Query._create(db._db, _str(querystr))
if not query_p:
raise NullPointerError
self._query = query_p
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
to get the value of this flag.
:returns: :class:`Threads`
- :exception: :exc:`NullPointerError` if search_threads failed
+ :raises: :exc:`NullPointerError` if search_threads failed
"""
self._assert_query_is_initialized()
- threads_p = Query._search_threads(self._query)
+ 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 = nmlib.notmuch_query_search_messages
+ _search_messages.argtypes = [NotmuchQueryP, POINTER(NotmuchMessagesP)]
+ _search_messages.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`
- :exception: :exc:`NullPointerError` if search_messages failed
+ :raises: :exc:`NullPointerError` if search_messages failed
"""
self._assert_query_is_initialized()
- msgs_p = Query._search_messages(self._query)
+ msgs_p = NotmuchMessagesP() # == NULL
+ status = Query._search_messages(self._query, byref(msgs_p))
+ if status != 0:
+ raise NotmuchError(status)
if not msgs_p:
raise NullPointerError
return Messages(msgs_p, self)
- def count_messages(self):
- """Estimate the number of messages matching the query
+ _count_messages = nmlib.notmuch_query_count_messages
+ _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. 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.
+ guess as to the number of matching messages.
- :returns: :class:`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
+ _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()
- return Query._count_messages(self._query)
+ 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]
def __del__(self):
"""Close and free the Query"""
- if self._query is not None:
+ if self._query:
self._destroy(self._query)
projects / notmuch / blobdiff