Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit e0f0cf4

Browse files
serhiy-storchakaserhiy-storchaka
committed
Issue #18761: Improved cross-references in email documentation.
1 parent ca64d25 commit e0f0cf4

10 files changed

Lines changed: 208 additions & 156 deletions

‎Doc/library/email.charset.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -234,5 +234,5 @@ new entries to the global character set, alias, and codec registries:
234234

235235
*charset* is the canonical name of a character set. *codecname* is the name of a
236236
Python codec, as appropriate for the second argument to the :class:`str`'s
237-
:func:`decode` method
237+
:meth:`~str.encode` method
238238

‎Doc/library/email.errors.rst‎

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,8 @@ The following exception classes are defined in the :mod:`email.errors` module:
2525

2626
Raised under some error conditions when parsing the :rfc:`2822` headers of a
2727
message, this class is derived from :exc:`MessageParseError`. It can be raised
28-
from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
28+
from the :meth:`Parser.parse <email.parser.Parser.parse>` or
29+
:meth:`Parser.parsestr <email.parser.Parser.parsestr>` methods.
2930

3031
Situations where it can be raised include finding an envelope header after the
3132
first :rfc:`2822` header of the message, finding a continuation line before the
@@ -37,7 +38,8 @@ The following exception classes are defined in the :mod:`email.errors` module:
3738

3839
Raised under some error conditions when parsing the :rfc:`2822` headers of a
3940
message, this class is derived from :exc:`MessageParseError`. It can be raised
40-
from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods.
41+
from the :meth:`Parser.parse <email.parser.Parser.parse>` or
42+
:meth:`Parser.parsestr <email.parser.Parser.parsestr>` methods.
4143

4244
Situations where it can be raised include not being able to find the starting or
4345
terminating boundary in a :mimetype:`multipart/\*` message when strict parsing
@@ -46,19 +48,20 @@ The following exception classes are defined in the :mod:`email.errors` module:
4648

4749
.. exception:: MultipartConversionError()
4850

49-
Raised when a payload is added to a :class:`Message` object using
50-
:meth:`add_payload`, but the payload is already a scalar and the message's
51-
:mailheader:`Content-Type` main type is not either :mimetype:`multipart` or
52-
missing. :exc:`MultipartConversionError` multiply inherits from
53-
:exc:`MessageError` and the built-in :exc:`TypeError`.
51+
Raised when a payload is added to a :class:`~email.message.Message` object
52+
using :meth:`add_payload`, but the payload is already a scalar and the
53+
message's :mailheader:`Content-Type` main type is not either
54+
:mimetype:`multipart` or missing. :exc:`MultipartConversionError` multiply
55+
inherits from :exc:`MessageError` and the built-in :exc:`TypeError`.
5456

55-
Since :meth:`Message.add_payload` is deprecated, this exception is rarely raised
56-
in practice. However the exception may also be raised if the :meth:`attach`
57+
Since :meth:`Message.add_payload` is deprecated, this exception is rarely
58+
raised in practice. However the exception may also be raised if the
59+
:meth:`~email.message.Message.attach`
5760
method is called on an instance of a class derived from
5861
:class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g.
5962
:class:`~email.mime.image.MIMEImage`).
6063

61-
Here's the list of the defects that the :class:`~email.mime.parser.FeedParser`
64+
Here's the list of the defects that the :class:`~email.parser.FeedParser`
6265
can find while parsing messages. Note that the defects are added to the message
6366
where the problem was found, so for example, if a message nested inside a
6467
:mimetype:`multipart/alternative` had a malformed header, that nested message
@@ -97,9 +100,9 @@ this class is *not* an exception!
97100
This defect has not been used for several Python versions.
98101

99102
* :class:`MultipartInvariantViolationDefect` -- A message claimed to be a
100-
:mimetype:`multipart`, but no subparts were found. Note that when a message has
101-
this defect, its :meth:`is_multipart` method may return false even though its
102-
content type claims to be :mimetype:`multipart`.
103+
:mimetype:`multipart`, but no subparts were found. Note that when a message
104+
has this defect, its :meth:`~email.message.Message.is_multipart` method may
105+
return false even though its content type claims to be :mimetype:`multipart`.
103106

104107
* :class:`InvalidBase64PaddingDefect` -- When decoding a block of base64
105108
enocded bytes, the padding was not correct. Enough padding is added to

‎Doc/library/email.headerregistry.rst‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -56,15 +56,16 @@ headers.
5656
.. attribute:: name
5757

5858
The name of the header (the portion of the field before the ':'). This
59-
is exactly the value passed in the :attr:`~EmailPolicy.header_factory`
60-
call for *name*; that is, case is preserved.
59+
is exactly the value passed in the
60+
:attr:`~email.policy.EmailPolicy.header_factory` call for *name*; that
61+
is, case is preserved.
6162

6263

6364
.. attribute:: defects
6465

6566
A tuple of :exc:`~email.errors.HeaderDefect` instances reporting any
6667
RFC compliance problems found during parsing. The email package tries to
67-
be complete about detecting compliance issues. See the :mod:`errors`
68+
be complete about detecting compliance issues. See the :mod:`~email.errors`
6869
module for a discussion of the types of defects that may be reported.
6970

7071

@@ -230,8 +231,8 @@ headers.
230231

231232
The single address encoded by the header value. If the header value
232233
actually contains more than one address (which would be a violation of
233-
the RFC under the default :mod:`policy`), accessing this attribute will
234-
result in a :exc:`ValueError`.
234+
the RFC under the default :mod:`~email.policy`), accessing this attribute
235+
will result in a :exc:`ValueError`.
235236

236237

237238
Many of the above classes also have a ``Unique`` variant (for example,
@@ -275,7 +276,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
275276

276277
.. class:: ContentTypeHeader
277278

278-
A :class:`ParameterizedMIMEHheader` class that handles the
279+
A :class:`ParameterizedMIMEHeader` class that handles the
279280
:mailheader:`Content-Type` header.
280281

281282
.. attribute:: content_type
@@ -289,7 +290,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
289290

290291
.. class:: ContentDispositionHeader
291292

292-
A :class:`ParameterizedMIMEHheader` class that handles the
293+
A :class:`ParameterizedMIMEHeader` class that handles the
293294
:mailheader:`Content-Disposition` header.
294295

295296
.. attribute:: content-disposition

‎Doc/library/email.iterators.rst‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@
66

77

88
Iterating over a message object tree is fairly easy with the
9-
:meth:`Message.walk` method. The :mod:`email.iterators` module provides some
10-
useful higher level iterations over message object trees.
9+
:meth:`Message.walk <email.message.Message.walk>` method. The
10+
:mod:`email.iterators` module provides some useful higher level iterations over
11+
message object trees.
1112

1213

1314
.. function:: body_line_iterator(msg, decode=False)
@@ -16,9 +17,11 @@ useful higher level iterations over message object trees.
1617
string payloads line-by-line. It skips over all the subpart headers, and it
1718
skips over any subpart with a payload that isn't a Python string. This is
1819
somewhat equivalent to reading the flat text representation of the message from
19-
a file using :meth:`readline`, skipping over all the intervening headers.
20+
a file using :meth:`~io.TextIOBase.readline`, skipping over all the
21+
intervening headers.
2022

21-
Optional *decode* is passed through to :meth:`Message.get_payload`.
23+
Optional *decode* is passed through to :meth:`Message.get_payload
24+
<email.message.Message.get_payload>`.
2225

2326

2427
.. function:: typed_subpart_iterator(msg, maintype='text', subtype=None)

‎Doc/library/email.message.rst‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,8 @@ Here are the methods of the :class:`Message` class:
5555
format the message the way you want. For example, by default it does
5656
not do the mangling of lines that begin with ``From`` that is
5757
required by the unix mbox format. For more flexibility, instantiate a
58-
:class:`~email.generator.Generator` instance and use its :meth:`flatten`
59-
method directly. For example::
58+
:class:`~email.generator.Generator` instance and use its
59+
:meth:`~email.generator.Generator.flatten` method directly. For example::
6060

6161
from io import StringIO
6262
from email.generator import Generator
@@ -476,8 +476,8 @@ Here are the methods of the :class:`Message` class:
476476

477477
Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
478478
*boundary*. :meth:`set_boundary` will always quote *boundary* if
479-
necessary. A :exc:`HeaderParseError` is raised if the message object has
480-
no :mailheader:`Content-Type` header.
479+
necessary. A :exc:`~email.errors.HeaderParseError` is raised if the
480+
message object has no :mailheader:`Content-Type` header.
481481

482482
Note that using this method is subtly different than deleting the old
483483
:mailheader:`Content-Type` header and adding a new one with the new
@@ -573,7 +573,8 @@ Here are the methods of the :class:`Message` class:
573573
the end of the message.
574574

575575
You do not need to set the epilogue to the empty string in order for the
576-
:class:`Generator` to print a newline at the end of the file.
576+
:class:`~email.generator.Generator` to print a newline at the end of the
577+
file.
577578

578579

579580
.. attribute:: defects

‎Doc/library/email.mime.rst‎

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,8 @@ Here are the classes:
3535
*_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
3636
or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
3737
type (e.g. :mimetype:`plain` or :mimetype:`gif`). *_params* is a parameter
38-
key/value dictionary and is passed directly to :meth:`Message.add_header`.
38+
key/value dictionary and is passed directly to :meth:`Message.add_header
39+
<email.message.Message.add_header>`.
3940

4041
The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
4142
(based on *_maintype*, *_subtype*, and *_params*), and a
@@ -50,8 +51,9 @@ Here are the classes:
5051

5152
A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
5253
class for MIME messages that are not :mimetype:`multipart`. The primary
53-
purpose of this class is to prevent the use of the :meth:`attach` method,
54-
which only makes sense for :mimetype:`multipart` messages. If :meth:`attach`
54+
purpose of this class is to prevent the use of the
55+
:meth:`~email.message.Message.attach` method, which only makes sense for
56+
:mimetype:`multipart` messages. If :meth:`~email.message.Message.attach`
5557
is called, a :exc:`~email.errors.MultipartConversionError` exception is raised.
5658

5759

@@ -74,7 +76,8 @@ Here are the classes:
7476

7577
*_subparts* is a sequence of initial subparts for the payload. It must be
7678
possible to convert this sequence to a list. You can always attach new subparts
77-
to the message by using the :meth:`Message.attach` method.
79+
to the message by using the :meth:`Message.attach
80+
<email.message.Message.attach>` method.
7881

7982
Additional parameters for the :mailheader:`Content-Type` header are taken from
8083
the keyword arguments, or passed into the *_params* argument, which is a keyword
@@ -95,8 +98,10 @@ Here are the classes:
9598

9699
Optional *_encoder* is a callable (i.e. function) which will perform the actual
97100
encoding of the data for transport. This callable takes one argument, which is
98-
the :class:`MIMEApplication` instance. It should use :meth:`get_payload` and
99-
:meth:`set_payload` to change the payload to encoded form. It should also add
101+
the :class:`MIMEApplication` instance. It should use
102+
:meth:`~email.message.Message.get_payload` and
103+
:meth:`~email.message.Message.set_payload` to change the payload to encoded
104+
form. It should also add
100105
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
101106
object as necessary. The default encoding is base64. See the
102107
:mod:`email.encoders` module for a list of the built-in encoders.
@@ -121,8 +126,10 @@ Here are the classes:
121126

122127
Optional *_encoder* is a callable (i.e. function) which will perform the actual
123128
encoding of the audio data for transport. This callable takes one argument,
124-
which is the :class:`MIMEAudio` instance. It should use :meth:`get_payload` and
125-
:meth:`set_payload` to change the payload to encoded form. It should also add
129+
which is the :class:`MIMEAudio` instance. It should use
130+
:meth:`~email.message.Message.get_payload` and
131+
:meth:`~email.message.Message.set_payload` to change the payload to encoded
132+
form. It should also add
126133
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
127134
object as necessary. The default encoding is base64. See the
128135
:mod:`email.encoders` module for a list of the built-in encoders.
@@ -147,8 +154,10 @@ Here are the classes:
147154

148155
Optional *_encoder* is a callable (i.e. function) which will perform the actual
149156
encoding of the image data for transport. This callable takes one argument,
150-
which is the :class:`MIMEImage` instance. It should use :meth:`get_payload` and
151-
:meth:`set_payload` to change the payload to encoded form. It should also add
157+
which is the :class:`MIMEImage` instance. It should use
158+
:meth:`~email.message.Message.get_payload` and
159+
:meth:`~email.message.Message.set_payload` to change the payload to encoded
160+
form. It should also add
152161
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
153162
object as necessary. The default encoding is base64. See the
154163
:mod:`email.encoders` module for a list of the built-in encoders.

0 commit comments

Comments
 (0)