| .. _message-objects: |
| |
| Message Objects |
| --------------- |
| |
| A :class:`Message` instance has the following methods: |
| |
| |
n | .. method:: XXX Class.rewindbody() |
n | .. method:: Message.rewindbody() |
| |
| Seek to the start of the message body. This only works if the file object is |
| seekable. |
| |
| |
n | .. method:: XXX Class.isheader(line) |
n | .. method:: Message.isheader(line) |
| |
| Returns a line's canonicalized fieldname (the dictionary key that will be used |
| to index it) if the line is a legal :rfc:`2822` header; otherwise returns |
| ``None`` (implying that parsing should stop here and the line be pushed back on |
| the input stream). It is sometimes useful to override this method in a |
| subclass. |
| |
| |
n | .. method:: XXX Class.islast(line) |
n | .. method:: Message.islast(line) |
| |
| Return true if the given line is a delimiter on which Message should stop. The |
| delimiter line is consumed, and the file object's read location positioned |
| immediately after it. By default this method just checks that the line is |
| blank, but you can override it in a subclass. |
| |
| |
n | .. method:: XXX Class.iscomment(line) |
n | .. method:: Message.iscomment(line) |
| |
| Return ``True`` if the given line should be ignored entirely, just skipped. By |
| default this is a stub that always returns ``False``, but you can override it in |
| a subclass. |
| |
| |
n | .. method:: XXX Class.getallmatchingheaders(name) |
n | .. method:: Message.getallmatchingheaders(name) |
| |
| Return a list of lines consisting of all headers matching *name*, if any. Each |
| physical line, whether it is a continuation line or not, is a separate list |
| item. Return the empty list if no header matches *name*. |
| |
| |
n | .. method:: XXX Class.getfirstmatchingheader(name) |
n | .. method:: Message.getfirstmatchingheader(name) |
| |
| Return a list of lines comprising the first header matching *name*, and its |
| continuation line(s), if any. Return ``None`` if there is no header matching |
| *name*. |
| |
| |
n | .. method:: XXX Class.getrawheader(name) |
n | .. method:: Message.getrawheader(name) |
| |
| Return a single string consisting of the text after the colon in the first |
| header matching *name*. This includes leading whitespace, the trailing |
| linefeed, and internal linefeeds and whitespace if there any continuation |
| line(s) were present. Return ``None`` if there is no header matching *name*. |
| |
| |
n | .. method:: XXX Class.getheader(name[, default]) |
n | .. method:: Message.getheader(name[, default]) |
| |
n | Return a single string consisting of the last header matching *name*, |
| Like ``getrawheader(name)``, but strip leading and trailing whitespace. |
| but strip leading and trailing whitespace. |
| Internal whitespace is not stripped. The optional *default* argument can be |
| used to specify a different default to be returned when there is no header |
n | matching *name*. |
n | matching *name*; it defaults to ``None``. |
| This is the preferred way to get parsed headers. |
| |
| |
n | .. method:: XXX Class.get(name[, default]) |
n | .. method:: Message.get(name[, default]) |
| |
| An alias for :meth:`getheader`, to make the interface more compatible with |
| regular dictionaries. |
| |
| |
n | .. method:: XXX Class.getaddr(name) |
n | .. method:: Message.getaddr(name) |
| |
| Return a pair ``(full name, email address)`` parsed from the string returned by |
| ``getheader(name)``. If no header matching *name* exists, return ``(None, |
| None)``; otherwise both the full name and the address are (possibly empty) |
| strings. |
| |
| Example: If *m*'s first :mailheader:`From` header contains the string |
| ``'jack@cwi.nl (Jack Jansen)'``, then ``m.getaddr('From')`` will yield the pair |
| ``('Jack Jansen', 'jack@cwi.nl')``. If the header contained ``'Jack Jansen |
| <jack@cwi.nl>'`` instead, it would yield the exact same result. |
| |
| |
n | .. method:: XXX Class.getaddrlist(name) |
n | .. method:: Message.getaddrlist(name) |
| |
| This is similar to ``getaddr(list)``, but parses a header containing a list of |
| email addresses (e.g. a :mailheader:`To` header) and returns a list of ``(full |
| name, email address)`` pairs (even if there was only one address in the header). |
| If there is no header matching *name*, return an empty list. |
| |
| If multiple headers exist that match the named header (e.g. if there are several |
| :mailheader:`Cc` headers), all are parsed for addresses. Any continuation lines |
| the named headers contain are also parsed. |
| |
| |
n | .. method:: XXX Class.getdate(name) |
n | .. method:: Message.getdate(name) |
| |
| Retrieve a header using :meth:`getheader` and parse it into a 9-tuple compatible |
| with :func:`time.mktime`; note that fields 6, 7, and 8 are not usable. If |
| there is no header matching *name*, or it is unparsable, return ``None``. |
| |
| Date parsing appears to be a black art, and not all mailers adhere to the |
| standard. While it has been tested and found correct on a large collection of |
| email from many sources, it is still possible that this function may |
| occasionally yield an incorrect result. |
| |
| |
n | .. method:: XXX Class.getdate_tz(name) |
n | .. method:: Message.getdate_tz(name) |
| |
| Retrieve a header using :meth:`getheader` and parse it into a 10-tuple; the |
| first 9 elements will make a tuple compatible with :func:`time.mktime`, and the |
| 10th is a number giving the offset of the date's timezone from UTC. Note that |
| fields 6, 7, and 8 are not usable. Similarly to :meth:`getdate`, if there is |
| no header matching *name*, or it is unparsable, return ``None``. |
| |
| :class:`Message` instances also support a limited mapping interface. In |
| particular: ``m[name]`` is like ``m.getheader(name)`` but raises :exc:`KeyError` |
n | if there is no matching header; and ``len(m)``, ``m.get(name[, *default*])``, |
n | if there is no matching header; and ``len(m)``, ``m.get(name[, default])``, |
| ``m.has_key(name)``, ``m.keys()``, ``m.values()`` ``m.items()``, and |
| ``name in m``, ``m.keys()``, ``m.values()`` ``m.items()``, and |
| ``m.setdefault(name[, *default*])`` act as expected, with the one difference |
| ``m.setdefault(name[, default])`` act as expected, with the one difference |
| that :meth:`setdefault` uses an empty string as the default value. |
| :class:`Message` instances also support the mapping writable interface ``m[name] |
| = value`` and ``del m[name]``. :class:`Message` objects do not support the |
| :meth:`clear`, :meth:`copy`, :meth:`popitem`, or :meth:`update` methods of the |
| mapping interface. (Support for :meth:`get` and :meth:`setdefault` was only |
| added in Python 2.2.) |
| |
| Finally, :class:`Message` instances have some public instance variables: |
| |
| |
n | .. attribute:: XXX Class.headers |
n | .. attribute:: Message.headers |
| |
| A list containing the entire set of header lines, in the order in which they |
| were read (except that setitem calls may disturb this order). Each line contains |
| a trailing newline. The blank line terminating the headers is not contained in |
| the list. |
| |
| |
n | .. attribute:: XXX Class.fp |
n | .. attribute:: Message.fp |
| |
| The file or file-like object passed at instantiation time. This can be used to |
| read the message content. |
| |
| |
n | .. attribute:: XXX Class.unixfrom |
n | .. attribute:: Message.unixfrom |
| |
| The Unix ``From`` line, if the message had one, or an empty string. This is |
| needed to regenerate the message in some contexts, such as an ``mbox``\ -style |
| mailbox file. |
| |
| |
| .. _addresslist-objects: |
| |
| AddressList Objects |
| ------------------- |
| |
| An :class:`AddressList` instance has the following methods: |
| |
| |
n | .. method:: XXX Class.__len__() |
n | .. method:: AddressList.__len__() |
| |
| Return the number of addresses in the address list. |
| |
| |
n | .. method:: XXX Class.__str__() |
n | .. method:: AddressList.__str__() |
| |
| Return a canonicalized string representation of the address list. Addresses are |
| rendered in "name" <host@domain> form, comma-separated. |
| |
| |
n | .. method:: XXX Class.__add__(alist) |
n | .. method:: AddressList.__add__(alist) |
| |
| Return a new :class:`AddressList` instance that contains all addresses in both |
| :class:`AddressList` operands, with duplicates removed (set union). |
| |
| |
n | .. method:: XXX Class.__iadd__(alist) |
n | .. method:: AddressList.__iadd__(alist) |
| |
| In-place version of :meth:`__add__`; turns this :class:`AddressList` instance |
| into the union of itself and the right-hand instance, *alist*. |
| |
| |
n | .. method:: XXX Class.__sub__(alist) |
n | .. method:: AddressList.__sub__(alist) |
| |
| Return a new :class:`AddressList` instance that contains every address in the |
| left-hand :class:`AddressList` operand that is not present in the right-hand |
| address operand (set difference). |
| |
| |
n | .. method:: XXX Class.__isub__(alist) |
n | .. method:: AddressList.__isub__(alist) |
| |
| In-place version of :meth:`__sub__`, removing addresses in this list which are |
| also in *alist*. |
| |
| Finally, :class:`AddressList` instances have one public instance variable: |
| |
| |
t | .. attribute:: XXX Class.addresslist |
t | .. attribute:: AddressList.addresslist |
| |
| A list of tuple string pairs, one per address. In each member, the first is the |
| canonicalized name part, the second is the actual route-address (``'@'``\ |
| -separated username-host.domain pair). |
| |
| .. rubric:: Footnotes |
| |
| .. [#] This module originally conformed to :rfc:`822`, hence the name. Since then, |