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

import collections
import contextlib
import os
import pathlib
import weakref

import notmuch2._base as base
import notmuch2._capi as capi
import notmuch2._errors as errors
import notmuch2._tags as tags


__all__ = ['Message']


class Message(base.NotmuchObject):
    """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
    reference to the database object since the database object can not
    be released while the message is in use.

    Note that this represents a message in the notmuch database.  For
    full email functionality you may want to use the :mod:`email`
    package from Python's standard library.  You could e.g. create
    this as such::

       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)

    Most commonly the functionality provided by notmuch is sufficient
    to read email however.

    Messages are considered equal when they have the same message ID.
    This is how libnotmuch treats messages as well, the
    :meth:`pathnames` function returns multiple results for
    duplicates.

    :param parent: The parent object.  This is probably one off a
       :class:`Database`, :class:`Thread` or :class:`Query`.
    :type parent: NotmuchObject
    :param db: The database instance this message is associated with.
       This could be the same as the parent.
    :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()

    def __init__(self, parent, msg_p, *, db):
        self._parent = parent
        self._msg_p = msg_p
        self._db = db

    @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()

    def _destroy(self):
        if self.alive:
            capi.lib.notmuch_message_destroy(self._msg_p)
        self._msg_p = None

    @property
    def messageid(self):
        """The message ID as a string.

        The message ID is decoded with the ignore error handler.  This
        is fine as long as the message ID is well formed.  If it is
        not valid ASCII then this will be lossy.  So if you need to be
        able to write the exact same message ID back you should use
        :attr:`messageidb`.

        Note that notmuch will decode the message ID value and thus
        strip off the surrounding ``<`` and ``>`` characters.  This is
        different from Python's :mod:`email` package behaviour which
        leaves these characters in place.

        :returns: The message ID.
        :rtype: :class:`BinString`, this is a normal str but calling
           bytes() on it will return the original bytes used to create
           it.

        :raises ObjectDestroyedError: if used after destroyed.
        """
        ret = capi.lib.notmuch_message_get_message_id(self._msg_p)
        return base.BinString(capi.ffi.string(ret))

    @property
    def threadid(self):
        """The thread ID.

        The thread ID is decoded with the surrogateescape error
        handler so that it is possible to reconstruct the original
        thread ID if it is not valid UTF-8.

        :returns: The thread ID.
        :rtype: :class:`BinString`, this is a normal str but calling
           bytes() on it will return the original bytes used to create
           it.

        :raises ObjectDestroyedError: if used after destroyed.
        """
        ret = capi.lib.notmuch_message_get_thread_id(self._msg_p)
        return base.BinString(capi.ffi.string(ret))

    @property
    def path(self):
        """A pathname of the message as a pathlib.Path instance.

        If multiple files in the database contain the same message ID
        this will be just one of the files, chosen at random.

        :raises ObjectDestroyedError: if used after destroyed.
        """
        ret = capi.lib.notmuch_message_get_filename(self._msg_p)
        return pathlib.Path(os.fsdecode(capi.ffi.string(ret)))

    @property
    def pathb(self):
        """A pathname of the message as a bytes object.

        See :attr:`path` for details, this is the same but does return
        the path as a bytes object which is faster but less convenient.

        :raises ObjectDestroyedError: if used after destroyed.
        """
        ret = capi.lib.notmuch_message_get_filename(self._msg_p)
        return capi.ffi.string(ret)

    def filenames(self):
        """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 instances of
        :class:`pathlib.Path`.

        :returns: Iterator yielding :class:`pathlib.Path` instances.
        :rtype: iter

        :raises ObjectDestroyedError: if used after destroyed.
        """
        fnames_p = capi.lib.notmuch_message_get_filenames(self._msg_p)
        return PathIter(self, fnames_p)

    def filenamesb(self):
        """Return an iterator of all files for this message.

        This is like :meth:`pathnames` but the files are returned as
        byte objects instead.

        :returns: Iterator yielding :class:`bytes` instances.
        :rtype: iter

        :raises ObjectDestroyedError: if used after destroyed.
        """
        fnames_p = capi.lib.notmuch_message_get_filenames(self._msg_p)
        return FilenamesIter(self, fnames_p)

    @property
    def ghost(self):
        """Indicates whether this message is a ghost message.

        A ghost message if a message which we know exists, but it has
        no files or content associated with it.  This can happen if
        it was referenced by some other message.  Only the
        :attr:`messageid` and :attr:`threadid` attributes are valid
        for it.

        :raises ObjectDestroyedError: if used after destroyed.
        """
        ret = capi.lib.notmuch_message_get_flag(
            self._msg_p, capi.lib.NOTMUCH_MESSAGE_FLAG_GHOST)
        return bool(ret)

    @property
    def excluded(self):
        """Indicates whether this message was excluded from the query.

        When a message is created from a search, sometimes messages
        that where excluded by the search query could still be
        returned by it, e.g. because they are part of a thread
        matching the query.  the :meth:`Database.query` method allows
        these messages to be flagged, which results in this property
        being set to *True*.

        :raises ObjectDestroyedError: if used after destroyed.
        """
        ret = capi.lib.notmuch_message_get_flag(
            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.

        The time the message was sent as an integer number of seconds
        since the *epoch*, 1 Jan 1970.  This is derived from the
        message's header, you can get the original header value with
        :meth:`header`.

        :raises ObjectDestroyedError: if used after destroyed.
        """
        return capi.lib.notmuch_message_get_date(self._msg_p)

    def header(self, name):
        """Return the value of the named header.

        Returns the header from notmuch, some common headers are
        stored in the database, others are read from the file.
        Headers are returned with their newlines stripped and
        collapsed concatenated together if they occur multiple times.
        You may be better off using the standard library email
        package's ``email.message_from_file(msg.path.open())`` if that
        is not sufficient for you.

        :param header: Case-insensitive header name to retrieve.
        :type header: str or bytes

        :returns: The header value, an empty string if the header is
           not present.
        :rtype: str

        :raises LookupError: if the header is not present.
        :raises NullPointerError: For unexpected notmuch errors.
        :raises ObjectDestroyedError: if used after destroyed.
        """
        # The returned is supposedly guaranteed to be UTF-8.  Header
        # names must be ASCII as per RFC x822.
        if isinstance(name, str):
            name = name.encode('ascii')
        ret = capi.lib.notmuch_message_get_header(self._msg_p, name)
        if ret == capi.ffi.NULL:
            raise errors.NullPointerError()
        hdr = capi.ffi.string(ret)
        if not hdr:
            raise LookupError
        return hdr.decode(encoding='utf-8')

    @property
    def tags(self):
        """The tags associated with the message.

        This behaves as a set.  But removing and adding items to the
        set removes and adds them to the message in the database.

        :raises ReadOnlyDatabaseError: When manipulating tags on a
           database opened in read-only mode.
        :raises ObjectDestroyedError: if used after destroyed.
        """
        try:
            ref = self._cached_tagset
        except AttributeError:
            tagset = None
        else:
            tagset = ref()
        if tagset is None:
            tagset = tags.MutableTagSet(
                self, '_msg_p', capi.lib.notmuch_message_get_tags)
            self._cached_tagset = weakref.ref(tagset)
        return tagset

    @contextlib.contextmanager
    def frozen(self):
        """Context manager to freeze the message state.

        This allows you to perform atomic tag updates::

           with msg.frozen():
               msg.tags.clear()
               msg.tags.add('foo')

        Using This would ensure the message never ends up with no tags
        applied at all.

        It is safe to nest calls to this context manager.

        :raises ReadOnlyDatabaseError: if the database is opened in
           read-only mode.
        :raises UnbalancedFreezeThawError: if you somehow managed to
           call __exit__ of this context manager more than once.  Why
           did you do that?
        :raises ObjectDestroyedError: if used after destroyed.
        """
        ret = capi.lib.notmuch_message_freeze(self._msg_p)
        if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
            raise errors.NotmuchError(ret)
        self._frozen = True
        try:
            yield
        except Exception:
            # Only way to "rollback" these changes is to destroy
            # ourselves and re-create.  Behold.
            msgid = self.messageid
            self._destroy()
            with contextlib.suppress(Exception):
                new = self._db.find(msgid)
                self._msg_p = new._msg_p
                new._msg_p = None
                del new
            raise
        else:
            ret = capi.lib.notmuch_message_thaw(self._msg_p)
            if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
                raise errors.NotmuchError(ret)
            self._frozen = False

    @property
    def properties(self):
        """A map of arbitrary key-value pairs associated with the message.

        Be aware that properties may be used by other extensions to
        store state in.  So delete or modify with care.

        The properties map is somewhat special.  It is essentially a
        multimap-like structure where each key can have multiple
        values.  Therefore accessing a single item using
        :meth:`PropertiesMap.get` or :meth:`PropertiesMap.__getitem__`
        will only return you the *first* item if there are multiple
        and thus are only recommended if you know there to be only one
        value.

        Instead the map has an additional :meth:`PropertiesMap.all`
        method which can be used to retrieve all properties of a given
        key.  This method also allows iterating of a a subset of the
        keys starting with a given prefix.
        """
        try:
            ref = self._cached_props
        except AttributeError:
            props = None
        else:
            props = ref()
        if props is None:
            props = PropertiesMap(self, '_msg_p')
            self._cached_props = weakref.ref(props)
        return props

    def replies(self):
        """Return an iterator of all replies to this message.

        This method will only work if the message was created from a
        thread.  Otherwise it will yield no results.

        :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, msg_cls=OwnedMessage)

    def __hash__(self):
        return hash(self.messageid)

    def __eq__(self, other):
        if isinstance(other, self.__class__):
            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."""

    def __init__(self, parent, iter_p):
        super().__init__(parent, iter_p,
                         fn_destroy=capi.lib.notmuch_filenames_destroy,
                         fn_valid=capi.lib.notmuch_filenames_valid,
                         fn_get=capi.lib.notmuch_filenames_get,
                         fn_next=capi.lib.notmuch_filenames_move_to_next)

    def __next__(self):
        fname = super().__next__()
        return capi.ffi.string(fname)


class PathIter(FilenamesIter):
    """Iterator for pathlib.Path objects."""

    def __next__(self):
        fname = super().__next__()
        return pathlib.Path(os.fsdecode(fname))


class PropertiesMap(base.NotmuchObject, collections.abc.MutableMapping):
    """A mutable mapping to manage properties.

    Both keys and values of properties are supposed to be UTF-8
    strings in libnotmuch.  However since the uderlying API uses
    bytestrings you can use either str or bytes to represent keys and
    all returned keys and values use :class:`BinString`.

    Also be aware that ``iter(this_map)`` will return duplicate keys,
    while the :class:`collections.abc.KeysView` returned by
    :meth:`keys` is a :class:`collections.abc.Set` subclass.  This
    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 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
    O(1).
    """
    Property = collections.namedtuple('Property', ['key', 'value'])
    _marker = object()

    def __init__(self, msg, ptr_name):
        self._msg = msg
        self._ptr = lambda: getattr(msg, ptr_name)

    @property
    def alive(self):
        if not self._msg.alive:
            return False
        try:
            self._ptr
        except errors.ObjectDestroyedError:
            return False
        else:
            return True

    def _destroy(self):
        pass

    def __iter__(self):
        """Return an iterator which iterates over the keys.

        Be aware that a single key may have multiple values associated
        with it, if so it will appear multiple times here.
        """
        iter_p = capi.lib.notmuch_message_get_properties(self._ptr(), b'', 0)
        return PropertiesKeyIter(self, iter_p)

    def __len__(self):
        iter_p = capi.lib.notmuch_message_get_properties(self._ptr(), b'', 0)
        it = base.NotmuchIter(
            self, iter_p,
            fn_destroy=capi.lib.notmuch_message_properties_destroy,
            fn_valid=capi.lib.notmuch_message_properties_valid,
            fn_get=capi.lib.notmuch_message_properties_key,
            fn_next=capi.lib.notmuch_message_properties_move_to_next,
        )
        return len(list(it))

    def __getitem__(self, key):
        """Return **the first** peroperty associated with a key."""
        if isinstance(key, str):
            key = key.encode('utf-8')
        value_pp = capi.ffi.new('char**')
        ret = capi.lib.notmuch_message_get_property(self._ptr(), key, value_pp)
        if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
            raise errors.NotmuchError(ret)
        if value_pp[0] == capi.ffi.NULL:
            raise KeyError
        return base.BinString.from_cffi(value_pp[0])

    def keys(self):
        """Return a :class:`collections.abc.KeysView` for this map.

        Even when keys occur multiple times this is a subset of set()
        so will only contain them once.
        """
        return collections.abc.KeysView({k: None for k in self})

    def items(self):
        """Return a :class:`collections.abc.ItemsView` for this map.

        The ItemsView treats a ``(key, value)`` pair as unique, so
        dupcliate ``(key, value)`` pairs will be merged together.
        However duplicate keys with different values will be returned.
        """
        items = set()
        props_p = capi.lib.notmuch_message_get_properties(self._ptr(), b'', 0)
        while capi.lib.notmuch_message_properties_valid(props_p):
            key = capi.lib.notmuch_message_properties_key(props_p)
            value = capi.lib.notmuch_message_properties_value(props_p)
            items.add((base.BinString.from_cffi(key),
                       base.BinString.from_cffi(value)))
            capi.lib.notmuch_message_properties_move_to_next(props_p)
        capi.lib.notmuch_message_properties_destroy(props_p)
        return PropertiesItemsView(items)

    def values(self):
        """Return a :class:`collecions.abc.ValuesView` for this map.

        All unique property values are included in the view.
        """
        values = set()
        props_p = capi.lib.notmuch_message_get_properties(self._ptr(), b'', 0)
        while capi.lib.notmuch_message_properties_valid(props_p):
            value = capi.lib.notmuch_message_properties_value(props_p)
            values.add(base.BinString.from_cffi(value))
            capi.lib.notmuch_message_properties_move_to_next(props_p)
        capi.lib.notmuch_message_properties_destroy(props_p)
        return PropertiesValuesView(values)

    def __setitem__(self, key, value):
        """Add a key-value pair to the properties.

        You may prefer to use :meth:`add` for clarity since this
        method usually implies implicit overwriting of an existing key
        if it exists, while for properties this is not the case.
        """
        self.add(key, value)

    def add(self, key, value):
        """Add a key-value pair to the properties."""
        if isinstance(key, str):
            key = key.encode('utf-8')
        if isinstance(value, str):
            value = value.encode('utf-8')
        ret = capi.lib.notmuch_message_add_property(self._ptr(), key, value)
        if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
            raise errors.NotmuchError(ret)

    def __delitem__(self, key):
        """Remove all properties with this key."""
        if isinstance(key, str):
            key = key.encode('utf-8')
        ret = capi.lib.notmuch_message_remove_all_properties(self._ptr(), key)
        if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
            raise errors.NotmuchError(ret)

    def remove(self, key, value):
        """Remove a key-value pair from the properties."""
        if isinstance(key, str):
            key = key.encode('utf-8')
        if isinstance(value, str):
            value = value.encode('utf-8')
        ret = capi.lib.notmuch_message_remove_property(self._ptr(), key, value)
        if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
            raise errors.NotmuchError(ret)

    def pop(self, key, default=_marker):
        try:
            value = self[key]
        except KeyError:
            if default is self._marker:
                raise
            else:
                return default
        else:
            self.remove(key, value)
            return value

    def popitem(self):
        try:
            key = next(iter(self))
        except StopIteration:
            raise KeyError
        value = self.pop(key)
        return (key, value)

    def clear(self):
        ret = capi.lib.notmuch_message_remove_all_properties(self._ptr(),
                                                             capi.ffi.NULL)
        if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
            raise errors.NotmuchError(ret)

    def getall(self, prefix='', *, exact=False):
        """Return an iterator yielding all properties for a given key prefix.

        The returned iterator yields all peroperties which start with
        a given key prefix as ``(key, value)`` namedtuples.  If called
        with ``exact=True`` then only properties which exactly match
        the prefix are returned, those a key longer than the prefix
        will not be included.

        :param prefix: The prefix of the key.
        """
        if isinstance(prefix, str):
            prefix = prefix.encode('utf-8')
        props_p = capi.lib.notmuch_message_get_properties(self._ptr(),
                                                          prefix, exact)
        return PropertiesIter(self, props_p)


class PropertiesKeyIter(base.NotmuchIter):

    def __init__(self, parent, iter_p):
        super().__init__(
            parent,
            iter_p,
            fn_destroy=capi.lib.notmuch_message_properties_destroy,
            fn_valid=capi.lib.notmuch_message_properties_valid,
            fn_get=capi.lib.notmuch_message_properties_key,
            fn_next=capi.lib.notmuch_message_properties_move_to_next)

    def __next__(self):
        item = super().__next__()
        return base.BinString.from_cffi(item)


class PropertiesIter(base.NotmuchIter):

    def __init__(self, parent, iter_p):
        super().__init__(
            parent,
            iter_p,
            fn_destroy=capi.lib.notmuch_message_properties_destroy,
            fn_valid=capi.lib.notmuch_message_properties_valid,
            fn_get=capi.lib.notmuch_message_properties_key,
            fn_next=capi.lib.notmuch_message_properties_move_to_next,
        )

    def __next__(self):
        if not self._fn_valid(self._iter_p):
            self._destroy()
            raise StopIteration
        key = capi.lib.notmuch_message_properties_key(self._iter_p)
        value = capi.lib.notmuch_message_properties_value(self._iter_p)
        capi.lib.notmuch_message_properties_move_to_next(self._iter_p)
        return PropertiesMap.Property(base.BinString.from_cffi(key),
                                      base.BinString.from_cffi(value))


class PropertiesItemsView(collections.abc.Set):

    __slots__ = ('_items',)

    def __init__(self, items):
        self._items = items

    @classmethod
    def _from_iterable(self, it):
        return set(it)

    def __len__(self):
        return len(self._items)

    def __contains__(self, item):
        return item in self._items

    def __iter__(self):
        yield from self._items


collections.abc.ItemsView.register(PropertiesItemsView)


class PropertiesValuesView(collections.abc.Set):

    __slots__ = ('_values',)

    def __init__(self, values):
        self._values = values

    def __len__(self):
        return len(self._values)

    def __contains__(self, value):
        return value in self._values

    def __iter__(self):
        yield from self._values


collections.abc.ValuesView.register(PropertiesValuesView)


class MessageIter(base.NotmuchIter):

    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,
                         fn_get=capi.lib.notmuch_messages_get,
                         fn_next=capi.lib.notmuch_messages_move_to_next)

    def __next__(self):
        msg_p = super().__next__()
        return self._msg_cls(self, msg_p, db=self._db)