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')
def iter(self, *, encoding=None, errors='strict'):
"""Aternate iterator constructor controlling string decoding.
Tags are stored as bytes in the notmuch database, in Python
it's easier to work with unicode strings and thus is what the
normal iterator returns. However this method allows you to
specify how you would like to get the tags, defaulting to the
bytestring representation instead of unicode strings.
:param encoding: Which codec to use. The default *None* does not
decode at all and will return the unmodified bytes.
Otherwise this is passed on to :func:`str.decode`.
:param errors: If using a codec, this is the error handler.
See :func:`str.decode` to which this is passed on.
:raises NullPointerError: When things do not go as planned.
"""
# self._cffi_fn should point either to
# notmuch_database_get_all_tags, notmuch_thread_get_tags or
# notmuch_message_get_tags. nothmuch.h suggests these never
# fail, let's handle NULL anyway.
tags_p = self._cffi_fn(self._ptr())
if tags_p == capi.ffi.NULL:
raise errors.NullPointerError()
tags = TagsIter(self, tags_p, encoding=encoding, errors=errors)
return tags