sandbox/morph / Doc / library / rfc822.rst

Full commit

:mod:`rfc822` --- Parse RFC 2822 mail headers

This module defines a class, :class:`Message`, which represents an "email message" as defined by the Internet standard RFC 2822. [1] Such messages consist of a collection of message headers, and a message body. This module also defines a helper class :class:`AddressList` for parsing RFC 2822 addresses. Please refer to the RFC for information on the specific syntax of RFC 2822 messages.

The :mod:`mailbox` module provides classes to read mailboxes produced by various end-user mail programs.

A :class:`Message` instance is instantiated with an input object as parameter. Message relies only on the input object having a :meth:`readline` method; in particular, ordinary file objects qualify. Instantiation reads headers from the input object up to a delimiter line (normally a blank line) and stores them in the instance. The message body, following the headers, is not consumed.

This class can work with any input object that supports a :meth:`readline` method. If the input object has seek and tell capability, the :meth:`rewindbody` method will work; also, illegal lines will be pushed back onto the input stream. If the input object lacks seek but has an :meth:`unread` method that can push back a line of input, :class:`Message` will use that to push back illegal lines. Thus this class can be used to parse messages coming from a buffered stream.

The optional seekable argument is provided as a workaround for certain stdio libraries in which :c:func:`tell` discards buffered data before discovering that the :c:func:`lseek` system call doesn't work. For maximum portability, you should set the seekable argument to zero to prevent that initial :meth:`tell` when passing in an unseekable object such as a file object created from a socket object.

Input lines as read from the file may either be terminated by CR-LF or by a single linefeed; a terminating CR-LF is replaced by a single linefeed before the line is stored.

All header matching is done independent of upper or lower case; e.g. m['From'], m['from'] and m['FROM'] all yield the same result.

You may instantiate the :class:`AddressList` helper class using a single string parameter, a comma-separated list of RFC 2822 addresses to be parsed. (The parameter None yields an empty list.)

Message Objects

A :class:`Message` instance has the following methods:

:class:`Message` instances also support a limited mapping interface. In particular: m[name] is like m.getheader(name) but raises :exc:`KeyError` if there is no matching header; and len(m), m.get(name[, default]), name in m, m.keys(), m.values() m.items(), and 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:

AddressList Objects

An :class:`AddressList` instance has the following methods:

Finally, :class:`AddressList` instances have one public instance variable:


[1]This module originally conformed to RFC 822, hence the name. Since then, RFC 2822 has been released as an update to RFC 822. This module should be considered RFC 2822-conformant, especially in cases where the syntax or semantics have changed since RFC 822.