diff -r 8906713d5704 Doc/library/email.errors.rst --- a/Doc/library/email.errors.rst Fri Aug 16 19:36:18 2013 +0200 +++ b/Doc/library/email.errors.rst Fri Aug 16 22:44:40 2013 +0300 @@ -25,7 +25,7 @@ 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 ` or :meth:`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 @@ -37,7 +37,7 @@ 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 ` or :meth:`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 @@ -46,19 +46,19 @@ .. 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 + Raised when a payload is added to a :class:`~email.message.Message` object using + :meth:`~email.message.Message.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 @@ -98,7 +98,7 @@ * :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 + 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 diff -r 8906713d5704 Doc/library/email.headerregistry.rst --- a/Doc/library/email.headerregistry.rst Fri Aug 16 19:36:18 2013 +0200 +++ b/Doc/library/email.headerregistry.rst Fri Aug 16 22:44:40 2013 +0300 @@ -56,7 +56,7 @@ .. 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` + is exactly the value passed in the :attr:`~email.policy.EmailPolicy.header_factory` call for *name*; that is, case is preserved. @@ -64,7 +64,7 @@ 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. @@ -230,7 +230,7 @@ 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 + the RFC under the default :mod:`~email.policy`), accessing this attribute will result in a :exc:`ValueError`. @@ -275,7 +275,7 @@ .. class:: ContentTypeHeader - A :class:`ParameterizedMIMEHheader` class that handles the + A :class:`ParameterizedMIMEHeader` class that handles the :mailheader:`Content-Type` header. .. attribute:: content_type @@ -289,7 +289,7 @@ .. class:: ContentDispositionHeader - A :class:`ParameterizedMIMEHheader` class that handles the + A :class:`ParameterizedMIMEHeader` class that handles the :mailheader:`Content-Disposition` header. .. attribute:: content-disposition diff -r 8906713d5704 Doc/library/email.iterators.rst --- a/Doc/library/email.iterators.rst Fri Aug 16 19:36:18 2013 +0200 +++ b/Doc/library/email.iterators.rst Fri Aug 16 22:44:40 2013 +0300 @@ -6,7 +6,7 @@ Iterating over a message object tree is fairly easy with the -:meth:`Message.walk` method. The :mod:`email.iterators` module provides some +:meth:`Message.walk ` method. The :mod:`email.iterators` module provides some useful higher level iterations over message object trees. @@ -16,9 +16,9 @@ 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 `. .. function:: typed_subpart_iterator(msg, maintype='text', subtype=None) diff -r 8906713d5704 Doc/library/email.message.rst --- a/Doc/library/email.message.rst Fri Aug 16 19:36:18 2013 +0200 +++ b/Doc/library/email.message.rst Fri Aug 16 22:44:40 2013 +0300 @@ -62,7 +62,7 @@ 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` + :class:`~email.generator.Generator` instance and use its :meth:`~email.generator.Generator.flatten` method directly. For example:: from io import StringIO @@ -105,7 +105,7 @@ 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.BytesGenerator` instance and use its - :meth:`flatten` method directly. For example:: + :meth:`~email.generator.BytesGenerator.flatten` method directly. For example:: from io import BytesIO from email.generator import BytesGenerator @@ -313,7 +313,7 @@ .. method:: get(name, failobj=None) Return the value of the named header field. This is identical to - :meth:`__getitem__` except that optional *failobj* is returned if the + :meth:`~object.__getitem__` except that optional *failobj* is returned if the named header is missing (defaults to ``None``). Here are some additional useful methods: @@ -328,7 +328,7 @@ .. method:: add_header(_name, _value, **_params) - Extended header setting. This method is similar to :meth:`__setitem__` + Extended header setting. This method is similar to :meth:`~object.__setitem__` except that additional header parameters can be provided as keyword arguments. *_name* is the header field to add and *_value* is the *primary* value for the header. @@ -530,7 +530,7 @@ 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 + 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 @@ -627,7 +627,7 @@ 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 diff -r 8906713d5704 Doc/library/email.mime.rst --- a/Doc/library/email.mime.rst Fri Aug 16 19:36:18 2013 +0200 +++ b/Doc/library/email.mime.rst Fri Aug 16 22:44:40 2013 +0300 @@ -35,7 +35,7 @@ *_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 `. The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header (based on *_maintype*, *_subtype*, and *_params*), and a @@ -50,8 +50,8 @@ 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. @@ -74,7 +74,7 @@ *_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 ` 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 @@ -95,8 +95,8 @@ 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. @@ -121,8 +121,8 @@ 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. @@ -147,8 +147,8 @@ 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. diff -r 8906713d5704 Doc/library/email.parser.rst --- a/Doc/library/email.parser.rst Fri Aug 16 19:36:18 2013 +0200 +++ b/Doc/library/email.parser.rst Fri Aug 16 22:44:40 2013 +0300 @@ -7,7 +7,7 @@ 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 @@ -16,8 +16,8 @@ :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 @@ -134,7 +134,7 @@ 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 @@ -173,7 +173,7 @@ 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 + 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` @@ -210,7 +210,7 @@ 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. @@ -220,7 +220,7 @@ 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 @@ -231,7 +231,7 @@ 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. @@ -241,7 +241,7 @@ 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* and *policy* are interpreted as with the :class:`~email.parser.Parser` class constructor. .. versionadded:: 3.2 @@ -261,32 +261,32 @@ * 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 + :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` + 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 + :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 + :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 + :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. diff -r 8906713d5704 Doc/library/email.policy.rst --- a/Doc/library/email.policy.rst Fri Aug 16 19:36:18 2013 +0200 +++ b/Doc/library/email.policy.rst Fri Aug 16 22:44:40 2013 +0300 @@ -315,7 +315,7 @@ 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. @@ -459,10 +459,10 @@ .. method:: fold_binary(name, value) - The same as :meth:`fold` if :attr:`cte_type` is ``7bit``, except that + 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. diff -r 8906713d5704 Doc/library/email.rst --- a/Doc/library/email.rst Fri Aug 16 19:36:18 2013 +0200 +++ b/Doc/library/email.rst Fri Aug 16 22:44:40 2013 +0300 @@ -147,7 +147,7 @@ *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`, @@ -163,22 +163,22 @@ 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 + :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 + 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. @@ -187,52 +187,52 @@ * The :mod:`email.Header` and :mod:`email.Charset` modules have been added. -* The pickle format for :class:`Message` instances has changed. Since this was +* 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:`Message` instances, be aware that in :mod:`email` version 2, - :class:`Message` instances now have private variables *_charset* and + :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 +* 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:`Message` class for details. The changes should be + 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` + false, :meth:`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. + :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:`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 + doesn't do a :meth:`set_payload` with a :class:`~email.message.Message` instance on a container with a content type of :mimetype:`message/rfc822`. -* The :class:`Parser` constructor's *strict* argument was added, and its +* The :class:`~email.parser.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. + instead. The :class:`~email.generator.Generator` class has also grown the :meth:`clone` method. -* The :class:`DecodedGenerator` class in the :mod:`email.Generator` module was +* The :class:`~email.generator.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 +* 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:`MIMEText` constructor has been +* 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: @@ -266,65 +266,65 @@ * :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:`gettype` was renamed to :meth:`~email.message.Message.get_type`. -* The method :meth:`getmaintype` was renamed to :meth:`get_main_type`. +* The method :meth:`getmaintype` was renamed to :meth:`~email.message.Message.get_main_type`. -* The method :meth:`getsubtype` was renamed to :meth:`get_subtype`. +* The method :meth:`getsubtype` was renamed to :meth:`~email.message.Message.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 +* 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() + 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` + 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 + 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 +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:`Message` instance containing -separate :class:`Message` subparts for each header block in the 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 +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:`DecodedGenerator` which provides most of the functionality previously +: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 +* 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* @@ -338,7 +338,7 @@ 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`. @@ -348,7 +348,7 @@ :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 +closely supported in the :func:`~email.iterators.body_line_iterator` function in the :mod:`email.iterators` module. .. rubric:: Footnotes diff -r 8906713d5704 Doc/library/email.util.rst --- a/Doc/library/email.util.rst Fri Aug 16 19:36:18 2013 +0200 +++ b/Doc/library/email.util.rst Fri Aug 16 22:44:40 2013 +0300 @@ -49,7 +49,7 @@ 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 + :meth:`Message.get_all `. Here's a simple example that gets all the recipients of a message:: from email.utils import getaddresses @@ -187,10 +187,10 @@ .. 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 ` 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'``.