bindings/python-cffi: fix docstring

[notmuch] / bindings / python-cffi / notmuch2 / _message.py

diff --git a/bindings/python-cffi/notmuch2/_message.py b/bindings/python-cffi/notmuch2/_message.py
index 416ce7ca609a1a6d2f1f93b5c208af64cf6c9c3e..d4b34e91e2f88ff367a73cfa5b311d11cbfa6b9a 100644 (file)
--- a/bindings/python-cffi/notmuch2/_message.py
+++ b/bindings/python-cffi/notmuch2/_message.py
@@ -26,7 +26,7 @@ class Message(base.NotmuchObject):
     package from Python's standard library.  You could e.g. create
     this as such::
 
     package from Python's standard library.  You could e.g. create
     this as such::
 

-       notmuch_msg = db.get_message(msgid)  # or from a query
+       notmuch_msg = db.find(msgid)  # or from a query

        parser = email.parser.BytesParser(policy=email.policy.default)
        with notmuch_msg.path.open('rb) as fp:
            email_msg = parser.parse(fp)
        parser = email.parser.BytesParser(policy=email.policy.default)
        with notmuch_msg.path.open('rb) as fp:
            email_msg = parser.parse(fp)


@@ -47,9 +47,7 @@ class Message(base.NotmuchObject):
     :type db: Database
     :param msg_p: The C pointer to the ``notmuch_message_t``.
     :type msg_p: <cdata>
     :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.
     :param dup: Whether the message was a duplicate on insertion.

-

     :type dup: None or bool
     """
     _msg_p = base.MemoryPointer()
     :type dup: None or bool
     """
     _msg_p = base.MemoryPointer()


@@ -61,10 +59,22 @@ class Message(base.NotmuchObject):
 
     @property
     def alive(self):
 
     @property
     def alive(self):

-        return self._parent.alive
+        if not self._parent.alive:
+            return False
+        try:
+            self._msg_p
+        except errors.ObjectDestroyedError:
+            return False
+        else:
+            return True
+
+    def __del__(self):
+        self._destroy()

 
     def _destroy(self):
 
     def _destroy(self):

-        pass
+        if self.alive:
+            capi.lib.notmuch_message_destroy(self._msg_p)
+        self._msg_p = None

 
     @property
     def messageid(self):
 
     @property
     def messageid(self):


@@ -137,7 +147,7 @@ class Message(base.NotmuchObject):
         """Return an iterator of all files for this message.
 
         If multiple files contained the same message ID they will all
         """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.
         :class:`pathlib.Path`.
 
         :returns: Iterator yielding :class:`pathlib.Path` instances.


@@ -195,6 +205,20 @@ class Message(base.NotmuchObject):
             self._msg_p, capi.lib.NOTMUCH_MESSAGE_FLAG_EXCLUDED)
         return bool(ret)
 
             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.
     @property
     def date(self):
         """The message date as an integer.


@@ -347,14 +371,14 @@ class Message(base.NotmuchObject):
         This method will only work if the message was created from a
         thread.  Otherwise it will yield no results.
 
         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)
         :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)
 
     def __hash__(self):
         return hash(self.messageid)


@@ -363,30 +387,26 @@ class Message(base.NotmuchObject):
         if isinstance(other, self.__class__):
             return self.messageid == other.messageid
 
         if isinstance(other, self.__class__):
             return self.messageid == other.messageid
 

-class StandaloneMessage(Message):
-    """An email message stored in the notmuch database.

 
 

-    This subclass of Message is used for messages that are retrieved from the
-    database directly and are not owned by a query.
+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):
     @property
     def alive(self):

-        if not self._parent.alive:
-            return False
-        try:
-            self._msg_p
-        except errors.ObjectDestroyedError:
-            return False
-        else:
-            return True
-
-    def __del__(self):
-        self._destroy()
+        return self._parent.alive

 
     def _destroy(self):
 
     def _destroy(self):

-        if self.alive:
-            capi.lib.notmuch_message_destroy(self._msg_p)
-        self._msg_p = None
+        pass
+

 
 class FilenamesIter(base.NotmuchIter):
     """Iterator for binary filenames objects."""
 
 class FilenamesIter(base.NotmuchIter):
     """Iterator for binary filenames objects."""


@@ -425,7 +445,7 @@ class PropertiesMap(base.NotmuchObject, collections.abc.MutableMapping):
     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
     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
 
     Be aware that libnotmuch exposes all of this as iterators, so
     quite a few operations have O(n) performance instead of the usual


@@ -690,8 +710,9 @@ collections.abc.ValuesView.register(PropertiesValuesView)
 
 class MessageIter(base.NotmuchIter):
 
 
 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._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,
         super().__init__(parent, msgs_p,
                          fn_destroy=capi.lib.notmuch_messages_destroy,
                          fn_valid=capi.lib.notmuch_messages_valid,


@@ -700,4 +721,4 @@ class MessageIter(base.NotmuchIter):
 
     def __next__(self):
         msg_p = super().__next__()
 
     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)