charset to the output charset automatically. This is not useful for
multibyte character sets, which have line length issues (multibyte
characters must be split on a character, not a byte boundary); use the
- higher-level :class:`Header` class to deal with these issues (see
- :mod:`email.header`). *convert* defaults to ``False``.
+ higher-level :class:`~email.header.Header` class to deal with these issues
+ (see :mod:`email.header`). *convert* defaults to ``False``.
The type of encoding (base64 or quoted-printable) will be based on the
*header_encoding* attribute.
:synopsis: Encoders for email message payloads.
-When creating :class:`Message` objects from scratch, you often need to encode
-the payloads for transport through compliant mail servers. This is especially
-true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages containing
-binary data.
+When creating :class:`~email.message.Message` objects from scratch, you often
+need to encode the payloads for transport through compliant mail servers. This
+is especially true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages
+containing binary data.
The :mod:`email` package provides some convenient encodings in its
:mod:`encoders` module. These encoders are actually used by the
-:class:`MIMEAudio` and :class:`MIMEImage` class constructors to provide default
-encodings. All encoder functions take exactly one argument, the message object
-to encode. They usually extract the payload, encode it, and reset the payload
-to this newly encoded value. They should also set the
-:mailheader:`Content-Transfer-Encoding` header as appropriate.
+:class:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage`
+class constructors to provide default encodings. All encoder functions take
+exactly one argument, the message object to encode. They usually extract the
+payload, encode it, and reset the payload to this newly encoded value. They
+should also set the :mailheader:`Content-Transfer-Encoding` header as appropriate.
Here are the encoding functions provided:
.. exception:: MessageParseError()
- This is the base class for exceptions thrown by the :class:`Parser` class. It
- is derived from :exc:`MessageError`.
+ This is the base class for exceptions thrown by the :class:`~email.parser.Parser`
+ class. It is derived from :exc:`MessageError`.
.. exception:: HeaderParseError()
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`
method is called on an instance of a class derived from
- :class:`MIMENonMultipart` (e.g. :class:`MIMEImage`).
+ :class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g.
+ :class:`~email.mime.image.MIMEImage`).
-Here's the list of the defects that the :class:`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
+Here's the list of the defects that the :class:`~email.mime.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
object would have a defect, but the containing messages would not.
yourself. However the bundled generator knows how to generate most email in a
standards-compliant way, should handle MIME and non-MIME email messages just
fine, and is designed so that the transformation from flat text, to a message
-structure via the :class:`Parser` class, and back to flat text, is idempotent
-(the input is identical to the output).
+structure via the :class:`~email.parser.Parser` class, and back to flat text,
+is idempotent (the input is identical to the output).
Here are the public methods of the :class:`Generator` class, imported from the
:mod:`email.generator` module:
Optional *maxheaderlen* specifies the longest length for a non-continued header.
When a header line is longer than *maxheaderlen* (in characters, with tabs
expanded to 8 spaces), the header will be split as defined in the
- :mod:`email.header.Header` class. Set to zero to disable header wrapping. The
- default is 78, as recommended (but not required) by :rfc:`2822`.
+ :class:`~email.header.Header` class. Set to zero to disable header wrapping.
+ The default is 78, as recommended (but not required) by :rfc:`2822`.
The other public :class:`Generator` methods are:
If you want to include non-ASCII characters in your email headers, say in the
:mailheader:`Subject` or :mailheader:`To` fields, you should use the
-:class:`Header` class and assign the field in the :class:`Message` object to an
-instance of :class:`Header` instead of using a string for the header value.
-Import the :class:`Header` class from the :mod:`email.header` module. For
-example::
+:class:`Header` class and assign the field in the :class:`~email.message.Message`
+object to an instance of :class:`Header` instead of using a string for the header
+value. Import the :class:`Header` class from the :mod:`email.header` module.
+For example::
>>> from email.message import Message
>>> from email.header import Header
Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII
character? We did this by creating a :class:`Header` instance and passing in
the character set that the byte string was encoded in. When the subsequent
-:class:`Message` instance was flattened, the :mailheader:`Subject` field was
-properly :rfc:`2047` encoded. MIME-aware mail readers would show this header
-using the embedded ISO-8859-1 character.
+:class:`~email.message.Message` instance was flattened, the :mailheader:`Subject`
+field was properly :rfc:`2047` encoded. MIME-aware mail readers would show this
+header using the embedded ISO-8859-1 character.
Here is the :class:`Header` class description:
Append the string *s* to the MIME header.
- Optional *charset*, if given, should be a :class:`Charset` instance (see
- :mod:`email.charset`) or the name of a character set, which will be
- converted to a :class:`Charset` instance. A value of ``None`` (the
- default) means that the *charset* given in the constructor is used.
+ Optional *charset*, if given, should be a :class:`~email.charset.Charset`
+ instance (see :mod:`email.charset`) or the name of a character set, which
+ will be converted to a :class:`~email.charset.Charset` instance. A value
+ of ``None`` (the default) means that the *charset* given in the constructor
+ is used.
*s* may be an instance of :class:`bytes` or :class:`str`. If it is an
instance of :class:`bytes`, then *charset* is the encoding of that byte
Note that this method is provided as a convenience and may not always
format the message the way you want. For example, by default it mangles
lines that begin with ``From``. For more flexibility, instantiate a
- :class:`Generator` instance and use its :meth:`flatten` method directly.
- For example::
+ :class:`~email.generator.Generator` instance and use its :meth:`flatten`
+ method directly. For example::
from io import StringIO
from email.generator import Generator
.. method:: set_charset(charset)
Set the character set of the payload to *charset*, which can either be a
- :class:`Charset` instance (see :mod:`email.charset`), a string naming a
- character set, or ``None``. If it is a string, it will be converted to a
- :class:`Charset` instance. If *charset* is ``None``, the ``charset``
- parameter will be removed from the :mailheader:`Content-Type`
- header. Anything else will generate a :exc:`TypeError`.
+ :class:`~email.charset.Charset` instance (see :mod:`email.charset`), a
+ string naming a character set, or ``None``. If it is a string, it will
+ be converted to a :class:`~email.charset.Charset` instance. If *charset*
+ is ``None``, the ``charset`` parameter will be removed from the
+ :mailheader:`Content-Type` header. Anything else will generate a
+ :exc:`TypeError`.
The message will be assumed to be of type :mimetype:`text/\*` encoded with
*charset.input_charset*. It will be converted to *charset.output_charset*
.. method:: get_charset()
- Return the :class:`Charset` instance associated with the message's
- payload.
+ Return the :class:`~email.charset.Charset` instance associated with the
+ message's payload.
The following methods implement a mapping-like interface for accessing the
message's :rfc:`2822` headers. Note that there are some semantic differences
that header has no ``charset`` parameter, *failobj* is returned.
Note that this method differs from :meth:`get_charset` which returns the
- :class:`Charset` instance for the default encoding of the message body.
+ :class:`~email.charset.Charset` instance for the default encoding of the message body.
.. method:: get_charsets([failobj])
text can become visible.
The *preamble* attribute contains this leading extra-armor text for MIME
- documents. When the :class:`Parser` discovers some text after the headers
- but before the first boundary string, it assigns this text to the
- message's *preamble* attribute. When the :class:`Generator` is writing
- out the plain text representation of a MIME message, and it finds the
+ documents. When the :class:`~email.parser.Parser` discovers some text
+ after the headers but before the first boundary string, it assigns this
+ text to the message's *preamble* attribute. When the
+ :class:`~email.generator.Generator` is writing out the plain text
+ representation of a MIME message, and it finds the
message has a *preamble* attribute, it will write this text in the area
between the headers and the first boundary. See :mod:`email.parser` and
:mod:`email.generator` for details.
Ordinarily, you get a message object structure by passing a file or some text to
a parser, which parses the text and returns the root message object. However
you can also build a complete message structure from scratch, or even individual
-:class:`Message` objects by hand. In fact, you can also take an existing
-structure and add new :class:`Message` objects, move them around, etc. This
-makes a very convenient interface for slicing-and-dicing MIME messages.
+:class:`~email.message.Message` objects by hand. In fact, you can also take an
+existing structure and add new :class:`~email.message.Message` objects, move them
+around, etc. This makes a very convenient interface for slicing-and-dicing MIME
+messages.
-You can create a new object structure by creating :class:`Message` instances,
-adding attachments and all the appropriate headers manually. For MIME messages
-though, the :mod:`email` package provides some convenient subclasses to make
-things easier.
+You can create a new object structure by creating :class:`~email.message.Message`
+instances, adding attachments and all the appropriate headers manually. For MIME
+messages though, the :mod:`email` package provides some convenient subclasses to
+make things easier.
Here are the classes:
Module: :mod:`email.mime.base`
- This is the base class for all the MIME-specific subclasses of :class:`Message`.
- Ordinarily you won't create instances specifically of :class:`MIMEBase`,
- although you could. :class:`MIMEBase` is provided primarily as a convenient
- base class for more specific MIME-aware subclasses.
+ This is the base class for all the MIME-specific subclasses of
+ :class:`~email.message.Message`. Ordinarily you won't create instances
+ specifically of :class:`MIMEBase`, although you could. :class:`MIMEBase`
+ is provided primarily as a convenient base class for more specific
+ MIME-aware subclasses.
*_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
Module: :mod:`email.mime.nonmultipart`
- A subclass of :class:`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` is called, a
- :exc:`MultipartConversionError` exception is raised.
+ 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`
+ is called, a :exc:`~email.errors.MultipartConversionError` exception is raised.
.. currentmodule:: email.mime.multipart
Module: :mod:`email.mime.multipart`
- A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
- messages that are :mimetype:`multipart`. Optional *_subtype* defaults to
- :mimetype:`mixed`, but can be used to specify the subtype of the message. A
- :mailheader:`Content-Type` header of :mimetype:`multipart/_subtype` will be
- added to the message object. A :mailheader:`MIME-Version` header will also be
- added.
+ A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
+ class for MIME messages that are :mimetype:`multipart`. Optional *_subtype*
+ defaults to :mimetype:`mixed`, but can be used to specify the subtype of the
+ message. A :mailheader:`Content-Type` header of :mimetype:`multipart/_subtype`
+ will be added to the message object. A :mailheader:`MIME-Version` header will
+ also be added.
Optional *boundary* is the multipart boundary string. When ``None`` (the
default), the boundary is calculated when needed.
Module: :mod:`email.mime.application`
- A subclass of :class:`MIMENonMultipart`, the :class:`MIMEApplication` class is
- used to represent MIME message objects of major type :mimetype:`application`.
- *_data* is a string containing the raw byte data. Optional *_subtype* specifies
- the MIME subtype and defaults to :mimetype:`octet-stream`.
+ A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+ :class:`MIMEApplication` class is used to represent MIME message objects of
+ major type :mimetype:`application`. *_data* is a string containing the raw
+ byte data. Optional *_subtype* specifies the MIME subtype and defaults to
+ :mimetype:`octet-stream`.
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
Module: :mod:`email.mime.audio`
- A subclass of :class:`MIMENonMultipart`, the :class:`MIMEAudio` class is used to
- create MIME message objects of major type :mimetype:`audio`. *_audiodata* is a
- string containing the raw audio data. If this data can be decoded by the
- standard Python module :mod:`sndhdr`, then the subtype will be automatically
- included in the :mailheader:`Content-Type` header. Otherwise you can explicitly
- specify the audio subtype via the *_subtype* parameter. If the minor type could
- not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.
+ A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+ :class:`MIMEAudio` class is used to create MIME message objects of major type
+ :mimetype:`audio`. *_audiodata* is a string containing the raw audio data. If
+ this data can be decoded by the standard Python module :mod:`sndhdr`, then the
+ subtype will be automatically included in the :mailheader:`Content-Type` header.
+ Otherwise you can explicitly specify the audio subtype via the *_subtype*
+ parameter. If the minor type could not be guessed and *_subtype* was not given,
+ then :exc:`TypeError` is raised.
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,
Module: :mod:`email.mime.image`
- A subclass of :class:`MIMENonMultipart`, the :class:`MIMEImage` class is used to
- create MIME message objects of major type :mimetype:`image`. *_imagedata* is a
- string containing the raw image data. If this data can be decoded by the
- standard Python module :mod:`imghdr`, then the subtype will be automatically
- included in the :mailheader:`Content-Type` header. Otherwise you can explicitly
- specify the image subtype via the *_subtype* parameter. If the minor type could
- not be guessed and *_subtype* was not given, then :exc:`TypeError` is raised.
+ A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+ :class:`MIMEImage` class is used to create MIME message objects of major type
+ :mimetype:`image`. *_imagedata* is a string containing the raw image data. If
+ this data can be decoded by the standard Python module :mod:`imghdr`, then the
+ subtype will be automatically included in the :mailheader:`Content-Type` header.
+ Otherwise you can explicitly specify the image subtype via the *_subtype*
+ parameter. If the minor type could not be guessed and *_subtype* was not given,
+ then :exc:`TypeError` is raised.
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,
object as necessary. The default encoding is base64. See the
:mod:`email.encoders` module for a list of the built-in encoders.
- *_params* are passed straight through to the :class:`MIMEBase` constructor.
+ *_params* are passed straight through to the :class:`~email.mime.base.MIMEBase`
+ constructor.
.. currentmodule:: email.mime.message
Module: :mod:`email.mime.message`
- A subclass of :class:`MIMENonMultipart`, the :class:`MIMEMessage` class is used
- to create MIME objects of main type :mimetype:`message`. *_msg* is used as the
- payload, and must be an instance of class :class:`Message` (or a subclass
- thereof), otherwise a :exc:`TypeError` is raised.
+ A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+ :class:`MIMEMessage` class is used to create MIME objects of main type
+ :mimetype:`message`. *_msg* is used as the payload, and must be an instance
+ of class :class:`~email.message.Message` (or a subclass thereof), otherwise
+ a :exc:`TypeError` is raised.
Optional *_subtype* sets the subtype of the message; it defaults to
:mimetype:`rfc822`.
Module: :mod:`email.mime.text`
- A subclass of :class:`MIMENonMultipart`, the :class:`MIMEText` class is used to
- create MIME objects of major type :mimetype:`text`. *_text* is the string for
- the payload. *_subtype* is the minor type and defaults to :mimetype:`plain`.
- *_charset* is the character set of the text and is passed as a parameter to the
- :class:`MIMENonMultipart` constructor; it defaults to ``us-ascii``. No guessing
- or encoding is performed on the text data.
+ A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
+ :class:`MIMEText` class is used to create MIME objects of major type
+ :mimetype:`text`. *_text* is the string for the payload. *_subtype* is the
+ minor type and defaults to :mimetype:`plain`. *_charset* is the character
+ set of the text and is passed as a parameter to the
+ :class:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults
+ to ``us-ascii``. No guessing or encoding is performed on the text data.
Message object structures can be created in one of two ways: they can be created
-from whole cloth by instantiating :class:`Message` objects and stringing them
-together via :meth:`attach` and :meth:`set_payload` calls, or they can be
-created by parsing a flat text representation of the email message.
+from whole cloth by instantiating :class:`~email.message.Message` objects and
+stringing them together via :meth:`attach` and :meth:`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
document structures, including MIME documents. You can pass the parser a string
-or a file object, and the parser will return to you the root :class:`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.
+or a file object, and the parser will return to you the root
+: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.
There are actually two parser interfaces available for use, the classic
:class:`Parser` API and the incremental :class:`FeedParser` API. The classic
Note that the parser can be extended in limited ways, and of course you can
implement your own parser completely from scratch. There is no magical
connection between the :mod:`email` package's bundled parser and the
-:class:`Message` class, so your custom parser can create message object trees
-any way it finds necessary.
+:class:`~email.message.Message` class, so your custom parser can create message
+object trees any way it finds necessary.
FeedParser API
The constructor for the :class:`Parser` class takes an optional argument
*_class*. This must be a callable factory (such as a function or a class), and
it is used whenever a sub-message object needs to be created. It defaults to
- :class:`Message` (see :mod:`email.message`). The factory will be called without
- arguments.
+ :class:`~email.message.Message` (see :mod:`email.message`). The factory will
+ be called without arguments.
The optional *strict* flag is ignored.
* 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:`Message` subparts.
+ :meth:`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
projects / python / commitdiff