class Message(base.NotmuchObject):
- """An email message stored in the notmuch database.
+ """An email message stored in the notmuch database retrieved via a query.
This should not be directly created, instead it will be returned
by calling methods on :class:`Database`. A message keeps a
:type db: Database
:param msg_p: The C pointer to the ``notmuch_message_t``.
:type msg_p: <cdata>
-
:param dup: Whether the message was a duplicate on insertion.
-
:type dup: None or bool
"""
_msg_p = base.MemoryPointer()
"""Return an iterator of all files for this message.
If multiple files contained the same message ID they will all
- be returned here. The files are returned as intances of
+ be returned here. The files are returned as instances of
:class:`pathlib.Path`.
:returns: Iterator yielding :class:`pathlib.Path` instances.
self._msg_p, capi.lib.NOTMUCH_MESSAGE_FLAG_EXCLUDED)
return bool(ret)
+ @property
+ def matched(self):
+ """Indicates whether this message was matched by the query.
+
+ When a thread is created from a search, some of the
+ messages may not match the original query. This property
+ is set to *True* for those that do match.
+
+ :raises ObjectDestroyedError: if used after destroyed.
+ """
+ ret = capi.lib.notmuch_message_get_flag(
+ self._msg_p, capi.lib.NOTMUCH_MESSAGE_FLAG_MATCH)
+ return bool(ret)
+
@property
def date(self):
"""The message date as an integer.
This method will only work if the message was created from a
thread. Otherwise it will yield no results.
- :returns: An iterator yielding :class:`Message` instances.
+ :returns: An iterator yielding :class:`OwnedMessage` instances.
:rtype: MessageIter
"""
# The notmuch_messages_valid call accepts NULL and this will
# become an empty iterator, raising StopIteration immediately.
# Hence no return value checking here.
msgs_p = capi.lib.notmuch_message_get_replies(self._msg_p)
- return MessageIter(self, msgs_p, db=self._db)
+ return MessageIter(self, msgs_p, db=self._db, msg_cls=OwnedMessage)
def __hash__(self):
return hash(self.messageid)
return self.messageid == other.messageid
+class OwnedMessage(Message):
+ """An email message owned by parent thread object.
+
+ This subclass of Message is used for messages that are retrieved
+ from the notmuch database via a parent :class:`notmuch2.Thread`
+ object, which "owns" this message. This means that when this
+ message object is destroyed, by calling :func:`del` or
+ :meth:`_destroy` directly or indirectly, the message is not freed
+ in the notmuch API and the parent :class:`notmuch2.Thread` object
+ can return the same object again when needed.
+ """
+
+ @property
+ def alive(self):
+ return self._parent.alive
+
+ def _destroy(self):
+ pass
+
+
class FilenamesIter(base.NotmuchIter):
"""Iterator for binary filenames objects."""
means the former will yield duplicate keys while the latter won't.
It also means ``len(list(iter(this_map)))`` could be different
than ``len(this_map.keys())``. ``len(this_map)`` will correspond
- with the lenght of the default iterator.
+ with the length of the default iterator.
Be aware that libnotmuch exposes all of this as iterators, so
quite a few operations have O(n) performance instead of the usual
class MessageIter(base.NotmuchIter):
- def __init__(self, parent, msgs_p, *, db):
+ def __init__(self, parent, msgs_p, *, db, msg_cls=Message):
self._db = db
+ self._msg_cls = msg_cls
super().__init__(parent, msgs_p,
fn_destroy=capi.lib.notmuch_messages_destroy,
fn_valid=capi.lib.notmuch_messages_valid,
def __next__(self):
msg_p = super().__next__()
- return Message(self, msg_p, db=self._db)
+ return self._msg_cls(self, msg_p, db=self._db)