Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>'
"""
-from ctypes import c_char_p, c_void_p, c_long, c_int
-from notmuch.globals import (nmlib, STATUS,
- NotmuchError, NotmuchThreadP, NotmuchThreadsP, NotmuchMessagesP,
- NotmuchTagsP,)
+from ctypes import c_char_p, c_long, c_int
+from notmuch.globals import (
+ nmlib,
+ Python3StringMixIn,
+ NullPointerError,
+ NotInitializedError,
+ NotmuchThreadP,
+ NotmuchThreadsP,
+ NotmuchMessagesP,
+ NotmuchTagsP,
+)
from notmuch.message import Messages
from notmuch.tag import Tags
from datetime import date
-class Threads(object):
+class Threads(Python3StringMixIn):
"""Represents a list of notmuch threads
This object provides an iterator over a list of notmuch threads
library only provides a one-time iterator (it cannot reset the
iterator to the start). Thus iterating over the function will
"exhaust" the list of threads, and a subsequent iteration attempt
- will raise a :exc:`NotmuchError` STATUS.NOT_INITIALIZED. Also
+ will raise a :exc:`NotInitializedError`. Also
note, that any function that uses iteration will also
exhaust the messages. So both::
will almost never instantiate a :class:`Threads` object
herself. They are usually handed back as a result,
e.g. in :meth:`Query.search_threads`. *threads_p* must be
- valid, we will raise an :exc:`NotmuchError`
- (STATUS.NULL_POINTER) if it is `None`.
+ valid, we will raise an :exc:`NullPointerError` if it is
+ `None`.
:type threads_p: :class:`ctypes.c_void_p`
:param parent: The parent object
(ie :class:`Query`) these tags are derived from. It saves
:TODO: Make the iterator work more than once and cache the tags in
the Python object.(?)
"""
- if threads_p is None:
- raise NotmuchError(STATUS.NULL_POINTER)
+ if not threads_p:
+ raise NullPointerError()
self._threads = threads_p
#store parent, so we keep them alive as long as self is alive
_move_to_next.argtypes = [NotmuchThreadsP]
_move_to_next.restype = None
- def next(self):
- if self._threads is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
+ def __next__(self):
+ if not self._threads:
+ raise NotInitializedError()
if not self._valid(self._threads):
self._threads = None
thread = Thread(Threads._get(self._threads), self)
self._move_to_next(self._threads)
return thread
+ next = __next__ # python2.x iterator protocol compatibility
def __len__(self):
"""len(:class:`Threads`) returns the number of contained Threads
#THIS FAILS
threads = Database().create_query('').search_threads()
if len(threads) > 0: #this 'exhausts' threads
- # next line raises NotmuchError(STATUS.NOT_INITIALIZED)!!!
+ # next line raises :exc:`NotInitializedError`!!!
for thread in threads: print thread
"""
- if self._threads is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
+ if not self._threads:
+ raise NotInitializedError()
i = 0
# returns 'bool'. On out-of-memory it returns None
will almost never instantiate a :class:`Thread` object
herself. They are usually handed back as a result,
e.g. when iterating through :class:`Threads`. *thread_p*
- must be valid, we will raise an :exc:`NotmuchError`
- (STATUS.NULL_POINTER) if it is `None`.
+ must be valid, we will raise an :exc:`NullPointerError`
+ if it is `None`.
:param parent: A 'parent' object is passed which this message is
derived from. We save a reference to it, so we can
automatically delete the parent object once all derived
objects are dead.
"""
- if thread_p is None:
- raise NotmuchError(STATUS.NULL_POINTER)
+ if not thread_p:
+ raise NullPointerError()
self._thread = thread_p
#keep reference to parent, so we keep it alive
self._parent = parent
for as long as the thread is valid.
:returns: String with a message ID
- :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the thread
+ :exception: :exc:`NotInitializedError` if the thread
is not initialized.
"""
- if self._thread is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
- return Thread._get_thread_id(self._thread)
-
+ if not self._thread:
+ raise NotInitializedError()
+ return Thread._get_thread_id(self._thread).decode('utf-8', 'ignore')
_get_total_messages = nmlib.notmuch_thread_get_total_messages
_get_total_messages.argtypes = [NotmuchThreadP]
:returns: The number of all messages in the database
belonging to this thread. Contrast with
:meth:`get_matched_messages`.
- :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the thread
+ :exception: :exc:`NotInitializedError` if the thread
is not initialized.
"""
- if self._thread is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
+ if not self._thread:
+ raise NotInitializedError()
return self._get_total_messages(self._thread)
def get_toplevel_messages(self):
messages, etc.).
:returns: :class:`Messages`
- :exception: :exc:`NotmuchError`
-
- * STATUS.NOT_INITIALIZED if query is not inited
- * STATUS.NULL_POINTER if search_messages failed
+ :raises: :exc:`NotInitializedError` if query is not initialized
+ :raises: :exc:`NullPointerError` if search_messages failed
"""
- if self._thread is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
+ if not self._thread:
+ raise NotInitializedError()
msgs_p = Thread._get_toplevel_messages(self._thread)
- if msgs_p is None:
- raise NotmuchError(STATUS.NULL_POINTER)
+ if not msgs_p:
+ raise NullPointerError()
return Messages(msgs_p, self)
:returns: The number of all messages belonging to this thread that
matched the :class:`Query`from which this thread was created.
Contrast with :meth:`get_total_messages`.
- :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the thread
+ :exception: :exc:`NotInitializedError` if the thread
is not initialized.
"""
- if self._thread is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
+ if not self._thread:
+ raise NotInitializedError()
return self._get_matched_messages(self._thread)
def get_authors(self):
The returned string belongs to 'thread' and will only be valid for
as long as this Thread() is not deleted.
"""
- if self._thread is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
+ if not self._thread:
+ raise NotInitializedError()
authors = Thread._get_authors(self._thread)
- if authors is None:
+ if not authors:
return None
- return authors.decode('UTF-8')
+ return authors.decode('UTF-8', 'ignore')
def get_subject(self):
"""Returns the Subject of 'thread'
The returned string belongs to 'thread' and will only be valid for
as long as this Thread() is not deleted.
"""
- if self._thread is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
+ if not self._thread:
+ raise NotInitializedError()
subject = Thread._get_subject(self._thread)
- if subject is None:
+ if not subject:
return None
- return subject.decode('UTF-8')
+ return subject.decode('UTF-8', 'ignore')
def get_newest_date(self):
"""Returns time_t of the newest message date
:returns: A time_t timestamp.
:rtype: c_unit64
- :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+ :exception: :exc:`NotInitializedError` if the message
is not initialized.
"""
- if self._thread is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
+ if not self._thread:
+ raise NotInitializedError()
return Thread._get_newest_date(self._thread)
def get_oldest_date(self):
:returns: A time_t timestamp.
:rtype: c_unit64
- :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+ :exception: :exc:`NotInitializedError` if the message
is not initialized.
"""
- if self._thread is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
+ if not self._thread:
+ raise NotInitializedError()
return Thread._get_oldest_date(self._thread)
def get_tags(self):
query from which it derived is explicitely deleted).
:returns: A :class:`Tags` iterator.
- :exception: :exc:`NotmuchError`
-
- * STATUS.NOT_INITIALIZED if the thread
- is not initialized.
- * STATUS.NULL_POINTER, on error
+ :raises: :exc:`NotInitializedError` if query is not initialized
+ :raises: :exc:`NullPointerError` if search_messages failed
"""
- if self._thread is None:
- raise NotmuchError(STATUS.NOT_INITIALIZED)
+ if not self._thread:
+ raise NotInitializedError()
tags_p = Thread._get_tags(self._thread)
if tags_p == None:
- raise NotmuchError(STATUS.NULL_POINTER)
+ raise NullPointerError()
return Tags(tags_p, self)
- def __str__(self):
- """A str(Thread()) is represented by a 1-line summary"""
- thread = {}
- thread['id'] = self.get_thread_id()
-
- ###TODO: How do we find out the current sort order of Threads?
- ###Add a "sort" attribute to the Threads() object?
- #if (sort == NOTMUCH_SORT_OLDEST_FIRST)
- # date = notmuch_thread_get_oldest_date (thread);
- #else
- # date = notmuch_thread_get_newest_date (thread);
- thread['date'] = date.fromtimestamp(self.get_newest_date())
- thread['matched'] = self.get_matched_messages()
- thread['total'] = self.get_total_messages()
- thread['authors'] = self.get_authors()
- thread['subject'] = self.get_subject()
- thread['tags'] = self.get_tags()
-
- return "thread:%s %12s [%d/%d] %s; %s (%s)" % (thread['id'],
- thread['date'],
- thread['matched'],
- thread['total'],
- thread['authors'],
- thread['subject'],
- thread['tags'])
+ def __unicode__(self):
+ frm = "thread:%s %12s [%d/%d] %s; %s (%s)"
+
+ return frm % (self.get_thread_id(),
+ date.fromtimestamp(self.get_newest_date()),
+ self.get_matched_messages(),
+ self.get_total_messages(),
+ self.get_authors(),
+ self.get_subject(),
+ self.get_tags(),
+ )
_destroy = nmlib.notmuch_thread_destroy
_destroy.argtypes = [NotmuchThreadP]