diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/email.charset.rst | 4 | ||||
| -rw-r--r-- | Doc/library/email.encoders.rst | 18 | ||||
| -rw-r--r-- | Doc/library/email.errors.rst | 13 | ||||
| -rw-r--r-- | Doc/library/email.generator.rst | 8 | ||||
| -rw-r--r-- | Doc/library/email.header.rst | 23 | ||||
| -rw-r--r-- | Doc/library/email.message.rst | 30 | ||||
| -rw-r--r-- | Doc/library/email.mime.rst | 110 | ||||
| -rw-r--r-- | Doc/library/email.parser.rst | 29 |
8 files changed, 124 insertions, 111 deletions
diff --git a/Doc/library/email.charset.rst b/Doc/library/email.charset.rst index 01529a0..1244615 100644 --- a/Doc/library/email.charset.rst +++ b/Doc/library/email.charset.rst @@ -161,8 +161,8 @@ Import this class from the :mod:`email.charset` module. 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. diff --git a/Doc/library/email.encoders.rst b/Doc/library/email.encoders.rst index 28669c4..5421b9f 100644 --- a/Doc/library/email.encoders.rst +++ b/Doc/library/email.encoders.rst @@ -5,18 +5,18 @@ :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: diff --git a/Doc/library/email.errors.rst b/Doc/library/email.errors.rst index c68262f..2bd3ae4 100644 --- a/Doc/library/email.errors.rst +++ b/Doc/library/email.errors.rst @@ -17,8 +17,8 @@ The following exception classes are defined in the :mod:`email.errors` module: .. 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() @@ -55,11 +55,12 @@ The following exception classes are defined in the :mod:`email.errors` module: 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. diff --git a/Doc/library/email.generator.rst b/Doc/library/email.generator.rst index 4e2ea2f..0f5788a 100644 --- a/Doc/library/email.generator.rst +++ b/Doc/library/email.generator.rst @@ -16,8 +16,8 @@ functionality of the bundled generator; you could write one from scratch 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: @@ -41,8 +41,8 @@ Here are the public methods of the :class:`Generator` class, imported from the 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: diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst index 7ee4a2d..5da1d95 100644 --- a/Doc/library/email.header.rst +++ b/Doc/library/email.header.rst @@ -21,10 +21,10 @@ in its :mod:`email.header` and :mod:`email.charset` modules. 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 @@ -39,9 +39,9 @@ example:: 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: @@ -81,10 +81,11 @@ 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 diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst index edeed16..7f70898 100644 --- a/Doc/library/email.message.rst +++ b/Doc/library/email.message.rst @@ -45,8 +45,8 @@ Here are the methods of the :class:`Message` class: 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 @@ -122,11 +122,12 @@ Here are the methods of the :class:`Message` class: .. 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* @@ -137,8 +138,8 @@ Here are the methods of the :class:`Message` class: .. 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 @@ -445,7 +446,7 @@ Here are the methods of the :class:`Message` class: 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]) @@ -495,10 +496,11 @@ Here are the methods of the :class:`Message` class: 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. diff --git a/Doc/library/email.mime.rst b/Doc/library/email.mime.rst index 95407b0..0214d56 100644 --- a/Doc/library/email.mime.rst +++ b/Doc/library/email.mime.rst @@ -8,14 +8,15 @@ 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: @@ -25,10 +26,11 @@ 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 @@ -46,11 +48,11 @@ Here are the classes: 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 @@ -59,12 +61,12 @@ Here are the classes: 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. @@ -84,10 +86,11 @@ Here are the classes: 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 @@ -106,13 +109,14 @@ Here are the classes: 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, @@ -131,13 +135,14 @@ Here are the classes: 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, @@ -147,7 +152,8 @@ Here are the classes: 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 @@ -156,10 +162,11 @@ Here are the classes: 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`. @@ -171,10 +178,11 @@ Here are the classes: 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. diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst index 43f0238..ec2e71b 100644 --- a/Doc/library/email.parser.rst +++ b/Doc/library/email.parser.rst @@ -6,18 +6,18 @@ 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 @@ -31,8 +31,8 @@ incrementally, and only returns the root object when you close the parser [#]_. 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 @@ -101,8 +101,8 @@ class. 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. @@ -179,7 +179,8 @@ Here are some notes on the parsing semantics: * 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 |