Skip to content

Commit 738d055

Browse files
Fix references and typos in the email.utils documentation (#149644)
Co-authored-by: Stan Ulbrych <stan@python.org>
1 parent 0615b5c commit 738d055

1 file changed

Lines changed: 30 additions & 29 deletions

File tree

‎Doc/library/email.utils.rst‎

Lines changed: 30 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ module:
1414
.. function:: localtime(dt=None)
1515

1616
Return local time as an aware datetime object. If called without
17-
arguments, return current time. Otherwise *dt* argument should be a
17+
arguments, return the current time. Otherwise the *dt* argument should be a
1818
:class:`~datetime.datetime` instance, and it is converted to the local time
1919
zone according to the system time zone database. If *dt* is naive (that
2020
is, ``dt.tzinfo`` is ``None``), it is assumed to be in local time.
@@ -27,11 +27,11 @@ module:
2727
.. function:: make_msgid(idstring=None, domain=None)
2828

2929
Returns a string suitable for an :rfc:`2822`\ -compliant
30-
:mailheader:`Message-ID` header. Optional *idstring* if given, is a string
31-
used to strengthen the uniqueness of the message id. Optional *domain* if
32-
given provides the portion of the msgid after the '@'. The default is the
33-
local hostname. It is not normally necessary to override this default, but
34-
may be useful certain cases, such as a constructing distributed system that
30+
:mailheader:`Message-ID` header. Optional *idstring*, if given, is a string
31+
used to strengthen the uniqueness of the message id. Optional *domain*, if
32+
given, provides the portion of the msgid after the '@'. The default is the
33+
local hostname. It is normally not necessary to override this default, but
34+
may be useful in certain cases, such as constructing a distributed system that
3535
uses a consistent domain name across multiple hosts.
3636

3737
.. versionchanged:: 3.2
@@ -72,7 +72,7 @@ of the new API.
7272

7373
.. function:: formataddr(pair, charset='utf-8', *, strict=True)
7474

75-
The inverse of :meth:`parseaddr`, this takes a 2-tuple of the form ``(realname,
75+
The inverse of :func:`parseaddr`, this takes a 2-tuple of the form ``(realname,
7676
email_address)`` and returns the string value suitable for a :mailheader:`To` or
7777
:mailheader:`Cc` header. If the first element of *pair* is false, then the
7878
second element is returned unmodified.
@@ -95,9 +95,9 @@ of the new API.
9595

9696
.. function:: getaddresses(fieldvalues, *, strict=True)
9797

98-
This method returns a list of 2-tuples of the form returned by ``parseaddr()``.
98+
This function returns a list of 2-tuples of the form returned by :func:`parseaddr`.
9999
*fieldvalues* is a sequence of header field values as might be returned by
100-
:meth:`Message.get_all <email.message.Message.get_all>`.
100+
:meth:`Message.get_all() <email.message.Message.get_all>`.
101101

102102
If *strict* is true, use a strict parser which rejects malformed inputs.
103103

@@ -117,10 +117,10 @@ of the new API.
117117

118118
.. function:: parsedate(date)
119119

120-
Attempts to parse a date according to the rules in :rfc:`2822`. however, some
121-
mailers don't follow that format as specified, so :func:`parsedate` tries to
120+
Attempts to parse a date according to the rules in :rfc:`2822#section-3.3`. However,
121+
some mailers don't follow that format as specified, so :func:`parsedate` tries to
122122
guess correctly in such cases. *date* is a string containing an :rfc:`2822`
123-
date, such as ``"Mon, 20 Nov 1995 19:12:08 -0500"``. If it succeeds in parsing
123+
date, such as ``"Mon, 20 Nov 1995 19:12:08 -0500"``. If it succeeds in parsing
124124
the date, :func:`parsedate` returns a 9-tuple that can be passed directly to
125125
:func:`time.mktime`; otherwise ``None`` will be returned. Note that indexes 6,
126126
7, and 8 of the result tuple are not usable.
@@ -139,15 +139,16 @@ of the new API.
139139
.. function:: parsedate_to_datetime(date)
140140

141141
The inverse of :func:`format_datetime`. Performs the same function as
142-
:func:`parsedate`, but on success returns a :mod:`~datetime.datetime`;
143-
otherwise ``ValueError`` is raised if *date* contains an invalid value such
142+
:func:`parsedate`, but on success returns a :class:`~datetime.datetime`;
143+
otherwise :exc:`ValueError` is raised if *date* contains an invalid value such
144144
as an hour greater than 23 or a timezone offset not between -24 and 24 hours.
145145
If the input date has a timezone of ``-0000``, the ``datetime`` will be a naive
146-
``datetime``, and if the date is conforming to the RFCs it will represent a
146+
``datetime``, and if the date conforms to the RFCs it will represent a
147147
time in UTC but with no indication of the actual source timezone of the
148148
message the date comes from. If the input date has any other valid timezone
149-
offset, the ``datetime`` will be an aware ``datetime`` with the
150-
corresponding a :class:`~datetime.timezone` :class:`~datetime.tzinfo`.
149+
offset, the ``datetime`` will be an aware ``datetime`` whose corresponding
150+
:attr:`~datetime.datetime.tzinfo` attribute is a :class:`~datetime.timezone`
151+
object.
151152

152153
.. versionadded:: 3.3
153154

@@ -161,34 +162,34 @@ of the new API.
161162

162163
.. function:: formatdate(timeval=None, localtime=False, usegmt=False)
163164

164-
Returns a date string as per :rfc:`2822`, e.g.::
165+
Returns a date string as per :rfc:`2822`, for example::
165166

166167
Fri, 09 Nov 2001 01:08:47 -0000
167168

168-
Optional *timeval* if given is a floating-point time value as accepted by
169+
Optional *timeval*, if given, is a floating-point time value as accepted by
169170
:func:`time.gmtime` and :func:`time.localtime`, otherwise the current time is
170171
used.
171172

172173
Optional *localtime* is a flag that when ``True``, interprets *timeval*, and
173174
returns a date relative to the local timezone instead of UTC, properly taking
174-
daylight savings time into account. The default is ``False`` meaning UTC is
175+
daylight saving time into account. The default is ``False`` meaning UTC is
175176
used.
176177

177-
Optional *usegmt* is a flag that when ``True``, outputs a date string with the
178-
timezone as an ascii string ``GMT``, rather than a numeric ``-0000``. This is
178+
Optional *usegmt* is a flag that when ``True``, outputs a date string with the
179+
timezone as an ASCII string ``GMT``, rather than a numeric ``-0000``. This is
179180
needed for some protocols (such as HTTP). This only applies when *localtime* is
180181
``False``. The default is ``False``.
181182

182183

183184
.. function:: format_datetime(dt, usegmt=False)
184185

185-
Like ``formatdate``, but the input is a :mod:`datetime` instance. If it is
186-
a naive datetime, it is assumed to be "UTC with no information about the
186+
Like :func:`formatdate`, but the input is a :class:`~datetime.datetime` instance.
187+
If it is a naive datetime, it is assumed to be "UTC with no information about the
187188
source timezone", and the conventional ``-0000`` is used for the timezone.
188189
If it is an aware ``datetime``, then the numeric timezone offset is used.
189190
If it is an aware timezone with offset zero, then *usegmt* may be set to
190191
``True``, in which case the string ``GMT`` is used instead of the numeric
191-
timezone offset. This provides a way to generate standards conformant HTTP
192+
timezone offset. This provides a way to generate standards-conformant HTTP
192193
date headers.
193194

194195
.. versionadded:: 3.3
@@ -202,19 +203,19 @@ of the new API.
202203
.. function:: encode_rfc2231(s, charset=None, language=None)
203204

204205
Encode the string *s* according to :rfc:`2231`. Optional *charset* and
205-
*language*, if given is the character set name and language name to use. If
206+
*language*, if given, are the character set name and language name to use. If
206207
neither is given, *s* is returned as-is. If *charset* is given but *language*
207208
is not, the string is encoded using the empty string for *language*.
208209

209210

210211
.. function:: collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')
211212

212213
When a header parameter is encoded in :rfc:`2231` format,
213-
:meth:`Message.get_param <email.message.Message.get_param>` may return a
214+
:meth:`Message.get_param() <email.message.Message.get_param>` may return a
214215
3-tuple containing the character set,
215216
language, and value. :func:`collapse_rfc2231_value` turns this into a
216217
string. Optional *errors* is passed to the *errors* argument of :class:`str`'s
217-
:func:`~str.encode` method; it defaults to ``'replace'``. Optional
218+
:meth:`~str.encode` method; it defaults to ``'replace'``. Optional
218219
*fallback_charset* specifies the character set to use if the one in the
219220
:rfc:`2231` header is not known by Python; it defaults to ``'us-ascii'``.
220221

@@ -231,5 +232,5 @@ of the new API.
231232
.. rubric:: Footnotes
232233

233234
.. [#] Note that the sign of the timezone offset is the opposite of the sign of the
234-
``time.timezone`` variable for the same timezone; the latter variable follows
235+
:data:`time.timezone` variable for the same timezone; the latter variable follows
235236
the POSIX standard while this module follows :rfc:`2822`.

0 commit comments

Comments
 (0)