*charset* is the canonical name of a character set. *codecname* is the name of a
Python codec, as appropriate for the second argument to the :class:`str`'s
- :func:`decode` method
+ :meth:`~str.encode` method
Raised under some error conditions when parsing the :rfc:`2822` headers of a
message, this class is derived from :exc:`MessageParseError`. It can be raised
- from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
+ from the :meth:`Parser.parse <email.parser.Parser.parse>` or
+ :meth:`Parser.parsestr <email.parser.Parser.parsestr>` methods.
Situations where it can be raised include finding an envelope header after the
first :rfc:`2822` header of the message, finding a continuation line before the
Raised under some error conditions when parsing the :rfc:`2822` headers of a
message, this class is derived from :exc:`MessageParseError`. It can be raised
- from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
+ from the :meth:`Parser.parse <email.parser.Parser.parse>` or
+ :meth:`Parser.parsestr <email.parser.Parser.parsestr>` methods.
Situations where it can be raised include not being able to find the starting or
terminating boundary in a :mimetype:`multipart/\*` message when strict parsing
.. exception:: MultipartConversionError()
- Raised when a payload is added to a :class:`Message` object using
- :meth:`add_payload`, but the payload is already a scalar and the message's
- :mailheader:`Content-Type` main type is not either :mimetype:`multipart` or
- missing. :exc:`MultipartConversionError` multiply inherits from
- :exc:`MessageError` and the built-in :exc:`TypeError`.
+ Raised when a payload is added to a :class:`~email.message.Message` object
+ using :meth:`add_payload`, but the payload is already a scalar and the
+ message's :mailheader:`Content-Type` main type is not either
+ :mimetype:`multipart` or missing. :exc:`MultipartConversionError` multiply
+ inherits from :exc:`MessageError` and the built-in :exc:`TypeError`.
- Since :meth:`Message.add_payload` is deprecated, this exception is rarely raised
- in practice. However the exception may also be raised if the :meth:`attach`
+ Since :meth:`Message.add_payload` is deprecated, this exception is rarely
+ raised in practice. However the exception may also be raised if the
+ :meth:`~email.message.Message.attach`
method is called on an instance of a class derived from
:class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g.
:class:`~email.mime.image.MIMEImage`).
-Here's the list of the defects that the :class:`~email.mime.parser.FeedParser`
+Here's the list of the defects that the :class:`~email.parser.FeedParser`
can find while parsing messages. Note that the defects are added to the message
where the problem was found, so for example, if a message nested inside a
:mimetype:`multipart/alternative` had a malformed header, that nested message
This defect has not been used for several Python versions.
* :class:`MultipartInvariantViolationDefect` -- A message claimed to be a
- :mimetype:`multipart`, but no subparts were found. Note that when a message has
- this defect, its :meth:`is_multipart` method may return false even though its
- content type claims to be :mimetype:`multipart`.
+ :mimetype:`multipart`, but no subparts were found. Note that when a message
+ has this defect, its :meth:`~email.message.Message.is_multipart` method may
+ return false even though its content type claims to be :mimetype:`multipart`.
* :class:`InvalidBase64PaddingDefect` -- When decoding a block of base64
enocded bytes, the padding was not correct. Enough padding is added to
.. attribute:: name
The name of the header (the portion of the field before the ':'). This
- is exactly the value passed in the :attr:`~EmailPolicy.header_factory`
- call for *name*; that is, case is preserved.
+ is exactly the value passed in the
+ :attr:`~email.policy.EmailPolicy.header_factory` call for *name*; that
+ is, case is preserved.
.. attribute:: defects
A tuple of :exc:`~email.errors.HeaderDefect` instances reporting any
RFC compliance problems found during parsing. The email package tries to
- be complete about detecting compliance issues. See the :mod:`errors`
+ be complete about detecting compliance issues. See the :mod:`~email.errors`
module for a discussion of the types of defects that may be reported.
The single address encoded by the header value. If the header value
actually contains more than one address (which would be a violation of
- the RFC under the default :mod:`policy`), accessing this attribute will
- result in a :exc:`ValueError`.
+ the RFC under the default :mod:`~email.policy`), accessing this attribute
+ will result in a :exc:`ValueError`.
Many of the above classes also have a ``Unique`` variant (for example,
.. class:: ContentTypeHeader
- A :class:`ParameterizedMIMEHheader` class that handles the
+ A :class:`ParameterizedMIMEHeader` class that handles the
:mailheader:`Content-Type` header.
.. attribute:: content_type
.. class:: ContentDispositionHeader
- A :class:`ParameterizedMIMEHheader` class that handles the
+ A :class:`ParameterizedMIMEHeader` class that handles the
:mailheader:`Content-Disposition` header.
.. attribute:: content-disposition
Iterating over a message object tree is fairly easy with the
-:meth:`Message.walk` method. The :mod:`email.iterators` module provides some
-useful higher level iterations over message object trees.
+:meth:`Message.walk <email.message.Message.walk>` method. The
+:mod:`email.iterators` module provides some useful higher level iterations over
+message object trees.
.. function:: body_line_iterator(msg, decode=False)
string payloads line-by-line. It skips over all the subpart headers, and it
skips over any subpart with a payload that isn't a Python string. This is
somewhat equivalent to reading the flat text representation of the message from
- a file using :meth:`readline`, skipping over all the intervening headers.
+ a file using :meth:`~io.TextIOBase.readline`, skipping over all the
+ intervening headers.
- Optional *decode* is passed through to :meth:`Message.get_payload`.
+ Optional *decode* is passed through to :meth:`Message.get_payload
+ <email.message.Message.get_payload>`.
.. function:: typed_subpart_iterator(msg, maintype='text', subtype=None)
format the message the way you want. For example, by default it does
not do the mangling of lines that begin with ``From`` that is
required by the unix mbox format. For more flexibility, instantiate a
- :class:`~email.generator.Generator` instance and use its :meth:`flatten`
- method directly. For example::
+ :class:`~email.generator.Generator` instance and use its
+ :meth:`~email.generator.Generator.flatten` method directly. For example::
from io import StringIO
from email.generator import Generator
Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
*boundary*. :meth:`set_boundary` will always quote *boundary* if
- necessary. A :exc:`HeaderParseError` is raised if the message object has
- no :mailheader:`Content-Type` header.
+ necessary. A :exc:`~email.errors.HeaderParseError` is raised if the
+ message object has no :mailheader:`Content-Type` header.
Note that using this method is subtly different than deleting the old
:mailheader:`Content-Type` header and adding a new one with the new
the end of the message.
You do not need to set the epilogue to the empty string in order for the
- :class:`Generator` to print a newline at the end of the file.
+ :class:`~email.generator.Generator` to print a newline at the end of the
+ file.
.. attribute:: defects
*_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
type (e.g. :mimetype:`plain` or :mimetype:`gif`). *_params* is a parameter
- key/value dictionary and is passed directly to :meth:`Message.add_header`.
+ key/value dictionary and is passed directly to :meth:`Message.add_header
+ <email.message.Message.add_header>`.
The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
(based on *_maintype*, *_subtype*, and *_params*), and a
A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
class for MIME messages that are not :mimetype:`multipart`. The primary
- purpose of this class is to prevent the use of the :meth:`attach` method,
- which only makes sense for :mimetype:`multipart` messages. If :meth:`attach`
+ purpose of this class is to prevent the use of the
+ :meth:`~email.message.Message.attach` method, which only makes sense for
+ :mimetype:`multipart` messages. If :meth:`~email.message.Message.attach`
is called, a :exc:`~email.errors.MultipartConversionError` exception is raised.
*_subparts* is a sequence of initial subparts for the payload. It must be
possible to convert this sequence to a list. You can always attach new subparts
- to the message by using the :meth:`Message.attach` method.
+ to the message by using the :meth:`Message.attach
+ <email.message.Message.attach>` method.
Additional parameters for the :mailheader:`Content-Type` header are taken from
the keyword arguments, or passed into the *_params* argument, which is a keyword
Optional *_encoder* is a callable (i.e. function) which will perform the actual
encoding of the data for transport. This callable takes one argument, which is
- the :class:`MIMEApplication` instance. It should use :meth:`get_payload` and
- :meth:`set_payload` to change the payload to encoded form. It should also add
+ the :class:`MIMEApplication` instance. It should use
+ :meth:`~email.message.Message.get_payload` and
+ :meth:`~email.message.Message.set_payload` to change the payload to encoded
+ form. It should also add
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
object as necessary. The default encoding is base64. See the
:mod:`email.encoders` module for a list of the built-in encoders.
Optional *_encoder* is a callable (i.e. function) which will perform the actual
encoding of the audio data for transport. This callable takes one argument,
- which is the :class:`MIMEAudio` instance. It should use :meth:`get_payload` and
- :meth:`set_payload` to change the payload to encoded form. It should also add
+ which is the :class:`MIMEAudio` instance. It should use
+ :meth:`~email.message.Message.get_payload` and
+ :meth:`~email.message.Message.set_payload` to change the payload to encoded
+ form. It should also add
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
object as necessary. The default encoding is base64. See the
:mod:`email.encoders` module for a list of the built-in encoders.
Optional *_encoder* is a callable (i.e. function) which will perform the actual
encoding of the image data for transport. This callable takes one argument,
- which is the :class:`MIMEImage` instance. It should use :meth:`get_payload` and
- :meth:`set_payload` to change the payload to encoded form. It should also add
+ which is the :class:`MIMEImage` instance. It should use
+ :meth:`~email.message.Message.get_payload` and
+ :meth:`~email.message.Message.set_payload` to change the payload to encoded
+ form. It should also add
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
object as necessary. The default encoding is base64. See the
:mod:`email.encoders` module for a list of the built-in encoders.
Message object structures can be created in one of two ways: they can be created
from whole cloth by instantiating :class:`~email.message.Message` objects and
-stringing them together via :meth:`attach` and :meth:`set_payload` calls, or they
+stringing them together via :meth:`~email.message.Message.attach` and
+:meth:`~email.message.Message.set_payload` calls, or they
can be created by parsing a flat text representation of the email message.
The :mod:`email` package provides a standard parser that understands most email
:class:`~email.message.Message` instance of the object structure. For simple,
non-MIME messages the payload of this root object will likely be a string
containing the text of the message. For MIME messages, the root object will
-return ``True`` from its :meth:`is_multipart` method, and the subparts can be
-accessed via the :meth:`get_payload` and :meth:`walk` methods.
+return ``True`` from its :meth:`~email.message.Message.is_multipart` method, and
+the subparts can be accessed via the :meth:`~email.message.Message.get_payload`
+and :meth:`~email.message.Message.walk` methods.
There are actually two parser interfaces available for use, the classic
:class:`Parser` API and the incremental :class:`FeedParser` API. The classic
Read all the data from the file-like object *fp*, parse the resulting
text, and return the root message object. *fp* must support both the
- :meth:`readline` and the :meth:`read` methods on file-like objects.
+ :meth:`~io.TextIOBase.readline` and the :meth:`~io.TextIOBase.read`
+ methods on file-like objects.
The text contained in *fp* must be formatted as a block of :rfc:`2822`
style headers and header continuation lines, optionally preceded by a
Read all the data from the binary file-like object *fp*, parse the
resulting bytes, and return the message object. *fp* must support
- both the :meth:`readline` and the :meth:`read` methods on file-like
- objects.
+ both the :meth:`~io.IOBase.readline` and the :meth:`~io.IOBase.read`
+ methods on file-like objects.
The bytes contained in *fp* must be formatted as a block of :rfc:`2822`
style headers and header continuation lines, optionally preceded by a
Return a message object structure from a string. This is exactly equivalent to
``Parser().parsestr(s)``. *_class* and *policy* are interpreted as
- with the :class:`Parser` class constructor.
+ with the :class:`~email.parser.Parser` class constructor.
.. versionchanged:: 3.3
Removed the *strict* argument. Added the *policy* keyword.
Return a message object structure from a byte string. This is exactly
equivalent to ``BytesParser().parsebytes(s)``. Optional *_class* and
- *strict* are interpreted as with the :class:`Parser` class constructor.
+ *strict* are interpreted as with the :class:`~email.parser.Parser` class
+ constructor.
.. versionadded:: 3.2
.. versionchanged:: 3.3
Return a message object structure tree from an open :term:`file object`.
This is exactly equivalent to ``Parser().parse(fp)``. *_class*
- and *policy* are interpreted as with the :class:`Parser` class constructor.
+ and *policy* are interpreted as with the :class:`~email.parser.Parser` class
+ constructor.
.. versionchanged::
Removed the *strict* argument. Added the *policy* keyword.
Return a message object structure tree from an open binary :term:`file
object`. This is exactly equivalent to ``BytesParser().parse(fp)``.
- *_class* and *policy* are interpreted as with the :class:`Parser`
- class constructor.
+ *_class* and *policy* are interpreted as with the
+ :class:`~email.parser.Parser` class constructor.
.. versionadded:: 3.2
.. versionchanged:: 3.3
* Most non-\ :mimetype:`multipart` type messages are parsed as a single message
object with a string payload. These objects will return ``False`` for
- :meth:`is_multipart`. Their :meth:`get_payload` method will return a string
- object.
+ :meth:`~email.message.Message.is_multipart`. Their
+ :meth:`~email.message.Message.get_payload` method will return a string object.
* All :mimetype:`multipart` type messages will be parsed as a container message
object with a list of sub-message objects for their payload. The outer
- container message will return ``True`` for :meth:`is_multipart` and their
- :meth:`get_payload` method will return the list of :class:`~email.message.Message`
- subparts.
+ container message will return ``True`` for
+ :meth:`~email.message.Message.is_multipart` and their
+ :meth:`~email.message.Message.get_payload` method will return the list of
+ :class:`~email.message.Message` subparts.
* Most messages with a content type of :mimetype:`message/\*` (e.g.
:mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be
parsed as container object containing a list payload of length 1. Their
- :meth:`is_multipart` method will return ``True``. The single element in the
- list payload will be a sub-message object.
+ :meth:`~email.message.Message.is_multipart` method will return ``True``.
+ The single element in the list payload will be a sub-message object.
* Some non-standards compliant messages may not be internally consistent about
their :mimetype:`multipart`\ -edness. Such messages may have a
:mailheader:`Content-Type` header of type :mimetype:`multipart`, but their
- :meth:`is_multipart` method may return ``False``. If such messages were parsed
- with the :class:`FeedParser`, they will have an instance of the
- :class:`MultipartInvariantViolationDefect` class in their *defects* attribute
- list. See :mod:`email.errors` for details.
+ :meth:`~email.message.Message.is_multipart` method may return ``False``.
+ If such messages were parsed with the :class:`~email.parser.FeedParser`,
+ they will have an instance of the
+ :class:`~email.errors.MultipartInvariantViolationDefect` class in their
+ *defects* attribute list. See :mod:`email.errors` for details.
.. rubric:: Footnotes
.. [#] As of email package version 3.0, introduced in Python 2.4, the classic
- :class:`Parser` was re-implemented in terms of the :class:`FeedParser`, so the
- semantics and results are identical between the two parsers.
+ :class:`~email.parser.Parser` was re-implemented in terms of the
+ :class:`~email.parser.FeedParser`, so the semantics and results are
+ identical between the two parsers.
This concrete :class:`Policy` is the backward compatibility policy. It
replicates the behavior of the email package in Python 3.2. The
- :mod:`policy` module also defines an instance of this class,
+ :mod:`~email.policy` module also defines an instance of this class,
:const:`compat32`, that is used as the default policy. Thus the default
behavior of the email package is to maintain compatibility with Python 3.2.
.. method:: fold_binary(name, value)
- The same as :meth:`fold` if :attr:`cte_type` is ``7bit``, except that
- the returned value is bytes.
+ The same as :meth:`fold` if :attr:`~Policy.cte_type` is ``7bit``, except
+ that the returned value is bytes.
- If :attr:`cte_type` is ``8bit``, non-ASCII binary data is converted back
+ If :attr:`~Policy.cte_type` is ``8bit``, non-ASCII binary data is
+ converted back
into bytes. Headers with binary data are not refolded, regardless of the
``refold_header`` setting, since there is no way to know whether the
binary data consists of single byte characters or multibyte characters.
*Note that the version 3 names will continue to work until Python 2.6*.
* The :mod:`email.mime.application` module was added, which contains the
- :class:`MIMEApplication` class.
+ :class:`~email.mime.application.MIMEApplication` class.
* Methods that were deprecated in version 3 have been removed. These include
:meth:`Generator.__call__`, :meth:`Message.get_type`,
:meth:`Message.get_main_type`, :meth:`Message.get_subtype`.
* Fixes have been added for :rfc:`2231` support which can change some of the
- return types for :func:`Message.get_param` and friends. Under some
+ return types for :func:`Message.get_param <email.message.Message.get_param>`
+ and friends. Under some
circumstances, values which used to return a 3-tuple now return simple strings
(specifically, if all extended parameter segments were unencoded, there is no
language and charset designation expected, so the return type is now a simple
Here are the major differences between :mod:`email` version 3 and version 2:
-* The :class:`FeedParser` class was introduced, and the :class:`Parser` class
- was implemented in terms of the :class:`FeedParser`. All parsing therefore is
+* The :class:`~email.parser.FeedParser` class was introduced, and the
+ :class:`~email.parser.Parser` class was implemented in terms of the
+ :class:`~email.parser.FeedParser`. All parsing therefore is
non-strict, and parsing will make a best effort never to raise an exception.
Problems found while parsing messages are stored in the message's *defect*
attribute.
* All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2
have been removed. These include the *_encoder* argument to the
- :class:`MIMEText` constructor, the :meth:`Message.add_payload` method, the
- :func:`Utils.dump_address_pair` function, and the functions :func:`Utils.decode`
- and :func:`Utils.encode`.
+ :class:`~email.mime.text.MIMEText` constructor, the
+ :meth:`Message.add_payload` method, the :func:`Utils.dump_address_pair`
+ function, and the functions :func:`Utils.decode` and :func:`Utils.encode`.
* New :exc:`DeprecationWarning`\ s have been added to:
:meth:`Generator.__call__`, :meth:`Message.get_type`,
:meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict*
- argument to the :class:`Parser` class. These are expected to be removed in
- future versions.
+ argument to the :class:`~email.parser.Parser` class. These are expected to
+ be removed in future versions.
* Support for Pythons earlier than 2.3 has been removed.
* The :mod:`email.Header` and :mod:`email.Charset` modules have been added.
-* The pickle format for :class:`Message` instances has changed. Since this was
- never (and still isn't) formally defined, this isn't considered a backward
- incompatibility. However if your application pickles and unpickles
- :class:`Message` instances, be aware that in :mod:`email` version 2,
- :class:`Message` instances now have private variables *_charset* and
- *_default_type*.
+* The pickle format for :class:`~email.message.Message` instances has changed.
+ Since this was never (and still isn't) formally defined, this isn't
+ considered a backward incompatibility. However if your application pickles
+ and unpickles :class:`~email.message.Message` instances, be aware that in
+ :mod:`email` version 2, :class:`~email.message.Message` instances now have
+ private variables *_charset* and *_default_type*.
-* Several methods in the :class:`Message` class have been deprecated, or their
- signatures changed. Also, many new methods have been added. See the
- documentation for the :class:`Message` class for details. The changes should be
- completely backward compatible.
+* Several methods in the :class:`~email.message.Message` class have been
+ deprecated, or their signatures changed. Also, many new methods have been
+ added. See the documentation for the :class:`~email.message.Message` class
+ for details. The changes should be completely backward compatible.
* The object structure has changed in the face of :mimetype:`message/rfc822`
- content types. In :mod:`email` version 1, such a type would be represented by a
- scalar payload, i.e. the container message's :meth:`is_multipart` returned
- false, :meth:`get_payload` was not a list object, but a single :class:`Message`
- instance.
+ content types. In :mod:`email` version 1, such a type would be represented
+ by a scalar payload, i.e. the container message's
+ :meth:`~email.message.Message.is_multipart` returned false,
+ :meth:`~email.message.Message.get_payload` was not a list object, but a
+ single :class:`~email.message.Message` instance.
This structure was inconsistent with the rest of the package, so the object
representation for :mimetype:`message/rfc822` content types was changed. In
:mod:`email` version 2, the container *does* return ``True`` from
- :meth:`is_multipart`, and :meth:`get_payload` returns a list containing a single
- :class:`Message` item.
-
- Note that this is one place that backward compatibility could not be completely
- maintained. However, if you're already testing the return type of
- :meth:`get_payload`, you should be fine. You just need to make sure your code
- doesn't do a :meth:`set_payload` with a :class:`Message` instance on a container
- with a content type of :mimetype:`message/rfc822`.
-
-* The :class:`Parser` constructor's *strict* argument was added, and its
- :meth:`parse` and :meth:`parsestr` methods grew a *headersonly* argument. The
- *strict* flag was also added to functions :func:`email.message_from_file` and
- :func:`email.message_from_string`.
-
-* :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten`
- instead. The :class:`Generator` class has also grown the :meth:`clone` method.
-
-* The :class:`DecodedGenerator` class in the :mod:`email.Generator` module was
- added.
-
-* The intermediate base classes :class:`MIMENonMultipart` and
- :class:`MIMEMultipart` have been added, and interposed in the class hierarchy
- for most of the other MIME-related derived classes.
-
-* The *_encoder* argument to the :class:`MIMEText` constructor has been
- deprecated. Encoding now happens implicitly based on the *_charset* argument.
+ :meth:`~email.message.Message.is_multipart`, and
+ :meth:`~email.message.Message.get_payload` returns a list containing a single
+ :class:`~email.message.Message` item.
+
+ Note that this is one place that backward compatibility could not be
+ completely maintained. However, if you're already testing the return type of
+ :meth:`~email.message.Message.get_payload`, you should be fine. You just need
+ to make sure your code doesn't do a :meth:`~email.message.Message.set_payload`
+ with a :class:`~email.message.Message` instance on a container with a content
+ type of :mimetype:`message/rfc822`.
+
+* The :class:`~email.parser.Parser` constructor's *strict* argument was added,
+ and its :meth:`~email.parser.Parser.parse` and
+ :meth:`~email.parser.Parser.parsestr` methods grew a *headersonly* argument.
+ The *strict* flag was also added to functions :func:`email.message_from_file`
+ and :func:`email.message_from_string`.
+
+* :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten
+ <email.generator.Generator.flatten>` instead. The
+ :class:`~email.generator.Generator` class has also grown the
+ :meth:`~email.generator.Generator.clone` method.
+
+* The :class:`~email.generator.DecodedGenerator` class in the
+ :mod:`email.generator` module was added.
+
+* The intermediate base classes
+ :class:`~email.mime.nonmultipart.MIMENonMultipart` and
+ :class:`~email.mime.multipart.MIMEMultipart` have been added, and interposed
+ in the class hierarchy for most of the other MIME-related derived classes.
+
+* The *_encoder* argument to the :class:`~email.mime.text.MIMEText` constructor
+ has been deprecated. Encoding now happens implicitly based on the
+ *_charset* argument.
* The following functions in the :mod:`email.Utils` module have been deprecated:
:func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following
* :func:`messageFromFile` has been renamed to :func:`message_from_file`.
-The :class:`Message` class has the following differences:
+The :class:`~email.message.Message` class has the following differences:
-* The method :meth:`asString` was renamed to :meth:`as_string`.
+* The method :meth:`asString` was renamed to
+ :meth:`~email.message.Message.as_string`.
-* The method :meth:`ismultipart` was renamed to :meth:`is_multipart`.
+* The method :meth:`ismultipart` was renamed to
+ :meth:`~email.message.Message.is_multipart`.
-* The :meth:`get_payload` method has grown a *decode* optional argument.
+* The :meth:`~email.message.Message.get_payload` method has grown a *decode*
+ optional argument.
-* The method :meth:`getall` was renamed to :meth:`get_all`.
+* The method :meth:`getall` was renamed to
+ :meth:`~email.message.Message.get_all`.
-* The method :meth:`addheader` was renamed to :meth:`add_header`.
+* The method :meth:`addheader` was renamed to
+ :meth:`~email.message.Message.add_header`.
* The method :meth:`gettype` was renamed to :meth:`get_type`.
* The method :meth:`getsubtype` was renamed to :meth:`get_subtype`.
-* The method :meth:`getparams` was renamed to :meth:`get_params`. Also, whereas
- :meth:`getparams` returned a list of strings, :meth:`get_params` returns a list
- of 2-tuples, effectively the key/value pairs of the parameters, split on the
- ``'='`` sign.
+* The method :meth:`getparams` was renamed to
+ :meth:`~email.message.Message.get_params`. Also, whereas :meth:`getparams`
+ returned a list of strings, :meth:`~email.message.Message.get_params` returns
+ a list of 2-tuples, effectively the key/value pairs of the parameters, split
+ on the ``'='`` sign.
-* The method :meth:`getparam` was renamed to :meth:`get_param`.
+* The method :meth:`getparam` was renamed to
+ :meth:`~email.message.Message.get_param`.
-* The method :meth:`getcharsets` was renamed to :meth:`get_charsets`.
+* The method :meth:`getcharsets` was renamed to
+ :meth:`~email.message.Message.get_charsets`.
-* The method :meth:`getfilename` was renamed to :meth:`get_filename`.
+* The method :meth:`getfilename` was renamed to
+ :meth:`~email.message.Message.get_filename`.
-* The method :meth:`getboundary` was renamed to :meth:`get_boundary`.
+* The method :meth:`getboundary` was renamed to
+ :meth:`~email.message.Message.get_boundary`.
-* The method :meth:`setboundary` was renamed to :meth:`set_boundary`.
+* The method :meth:`setboundary` was renamed to
+ :meth:`~email.message.Message.set_boundary`.
* The method :meth:`getdecodedpayload` was removed. To get similar
- functionality, pass the value 1 to the *decode* flag of the get_payload()
- method.
+ functionality, pass the value 1 to the *decode* flag of the
+ :meth:`~email.message.Message.get_payload` method.
* The method :meth:`getpayloadastext` was removed. Similar functionality is
- supported by the :class:`DecodedGenerator` class in the :mod:`email.generator`
- module.
+ supported by the :class:`~email.generator.DecodedGenerator` class in the
+ :mod:`email.generator` module.
* The method :meth:`getbodyastext` was removed. You can get similar
- functionality by creating an iterator with :func:`typed_subpart_iterator` in the
- :mod:`email.iterators` module.
+ functionality by creating an iterator with
+ :func:`~email.iterators.typed_subpart_iterator` in the :mod:`email.iterators`
+ module.
-The :class:`Parser` class has no differences in its public interface. It does
-have some additional smarts to recognize :mimetype:`message/delivery-status`
-type messages, which it represents as a :class:`Message` instance containing
-separate :class:`Message` subparts for each header block in the delivery status
-notification [#]_.
+The :class:`~email.parser.Parser` class has no differences in its public
+interface. It does have some additional smarts to recognize
+:mimetype:`message/delivery-status` type messages, which it represents as a
+:class:`~email.message.Message` instance containing separate
+:class:`~email.message.Message` subparts for each header block in the delivery
+status notification [#]_.
-The :class:`Generator` class has no differences in its public interface. There
-is a new class in the :mod:`email.generator` module though, called
-:class:`DecodedGenerator` which provides most of the functionality previously
-available in the :meth:`Message.getpayloadastext` method.
+The :class:`~email.generator.Generator` class has no differences in its public
+interface. There is a new class in the :mod:`email.generator` module though,
+called :class:`~email.generator.DecodedGenerator` which provides most of the
+functionality previously available in the :meth:`Message.getpayloadastext`
+method.
The following modules and classes have been changed:
-* The :class:`MIMEBase` class constructor arguments *_major* and *_minor* have
- changed to *_maintype* and *_subtype* respectively.
+* The :class:`~email.mime.base.MIMEBase` class constructor arguments *_major*
+ and *_minor* have changed to *_maintype* and *_subtype* respectively.
* The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor*
argument has been renamed to *_subtype*.
but that clashed with the Python standard library module :mod:`rfc822` on some
case-insensitive file systems.
- Also, the :class:`MIMEMessage` class now represents any kind of MIME message
+ Also, the :class:`~email.mime.message.MIMEMessage` class now represents any
+ kind of MIME message
with main type :mimetype:`message`. It takes an optional argument *_subtype*
which is used to set the MIME subtype. *_subtype* defaults to
:mimetype:`rfc822`.
:mod:`email.utils` module.
The ``MsgReader`` class/module has been removed. Its functionality is most
-closely supported in the :func:`body_line_iterator` function in the
-:mod:`email.iterators` module.
+closely supported in the :func:`~email.iterators.body_line_iterator` function
+in the :mod:`email.iterators` module.
.. rubric:: Footnotes
This method returns a list of 2-tuples of the form returned by ``parseaddr()``.
*fieldvalues* is a sequence of header field values as might be returned by
- :meth:`Message.get_all`. Here's a simple example that gets all the recipients
- of a message::
+ :meth:`Message.get_all <email.message.Message.get_all>`. Here's a simple
+ example that gets all the recipients of a message::
from email.utils import getaddresses
.. function:: collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')
When a header parameter is encoded in :rfc:`2231` format,
- :meth:`Message.get_param` may return a 3-tuple containing the character set,
+ :meth:`Message.get_param <email.message.Message.get_param>` may return a
+ 3-tuple containing the character set,
language, and value. :func:`collapse_rfc2231_value` turns this into a unicode
string. Optional *errors* is passed to the *errors* argument of :class:`str`'s
- :func:`encode` method; it defaults to ``'replace'``. Optional
+ :func:`~str.encode` method; it defaults to ``'replace'``. Optional
*fallback_charset* specifies the character set to use if the one in the
:rfc:`2231` header is not known by Python; it defaults to ``'us-ascii'``.
projects / thirdparty / Python / cpython.git / commitdiff
