From 258efb480b9e40c9d68bfe4f4822fa9a1360bc30 Mon Sep 17 00:00:00 2001 From: Yuki Kobayashi Date: Fri, 21 Feb 2025 03:43:16 +0000 Subject: [PATCH 1/2] gh-101100: Fix sphinx warnings in `library/email.errors.rst` --- Doc/library/email.errors.rst | 89 ++++++++++++++++++++++-------------- Doc/tools/.nitignore | 1 - 2 files changed, 55 insertions(+), 35 deletions(-) diff --git a/Doc/library/email.errors.rst b/Doc/library/email.errors.rst index 61142d58ca8280..4aecee59e67a28 100644 --- a/Doc/library/email.errors.rst +++ b/Doc/library/email.errors.rst @@ -77,51 +77,72 @@ object would have a defect, but the containing messages would not. All defect classes are subclassed from :class:`email.errors.MessageDefect`. -* :class:`NoBoundaryInMultipartDefect` -- A message claimed to be a multipart, - but had no :mimetype:`boundary` parameter. +.. class:: NoBoundaryInMultipartDefect -* :class:`StartBoundaryNotFoundDefect` -- The start boundary claimed in the - :mailheader:`Content-Type` header was never found. + A message claimed to be a multipart, but had no :mimetype:`boundary` + parameter. -* :class:`CloseBoundaryNotFoundDefect` -- A start boundary was found, but - no corresponding close boundary was ever found. +.. class:: StartBoundaryNotFoundDefect - .. versionadded:: 3.3 + The start boundary claimed in the :mailheader:`Content-Type` header was + never found. -* :class:`FirstHeaderLineIsContinuationDefect` -- The message had a continuation - line as its first header line. +.. class:: CloseBoundaryNotFoundDefect -* :class:`MisplacedEnvelopeHeaderDefect` - A "Unix From" header was found in the - middle of a header block. + A start boundary was found, but no corresponding close boundary was ever + found. -* :class:`MissingHeaderBodySeparatorDefect` - A line was found while parsing - headers that had no leading white space but contained no ':'. Parsing - continues assuming that the line represents the first line of the body. + .. versionadded:: 3.3 - .. versionadded:: 3.3 +.. class:: FirstHeaderLineIsContinuationDefect -* :class:`MalformedHeaderDefect` -- A header was found that was missing a colon, - or was otherwise malformed. + The message had a continuation line as its first header line. - .. deprecated:: 3.3 - This defect has not been used for several Python versions. +.. class:: MisplacedEnvelopeHeaderDefect -* :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:`~email.message.Message.is_multipart` method may - return ``False`` even though its content type claims to be :mimetype:`multipart`. + A "Unix From" header was found in the middle of a header block. -* :class:`InvalidBase64PaddingDefect` -- When decoding a block of base64 - encoded bytes, the padding was not correct. Enough padding is added to - perform the decode, but the resulting decoded bytes may be invalid. +.. class:: MissingHeaderBodySeparatorDefect -* :class:`InvalidBase64CharactersDefect` -- When decoding a block of base64 - encoded bytes, characters outside the base64 alphabet were encountered. - The characters are ignored, but the resulting decoded bytes may be invalid. + A line was found while parsing headers that had no leading white space but + contained no ':'. Parsing continues assuming that the line represents the + first line of the body. -* :class:`InvalidBase64LengthDefect` -- When decoding a block of base64 encoded - bytes, the number of non-padding base64 characters was invalid (1 more than - a multiple of 4). The encoded block was kept as-is. + .. versionadded:: 3.3 -* :class:`InvalidDateDefect` -- When decoding an invalid or unparsable date field. - The original value is kept as-is. +.. class:: MalformedHeaderDefect + + A header was found that was missing a colon, or was otherwise malformed. + + .. deprecated:: 3.3 + This defect has not been used for several Python versions. + +.. 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:`~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 encoded bytes, the padding was not correct. + Enough padding is added to perform the decode, but the resulting decoded + bytes may be invalid. + +.. class:: InvalidBase64CharactersDefect + + When decoding a block of base64 encoded bytes, characters outside the base64 + alphabet were encountered. The characters are ignored, but the resulting + decoded bytes may be invalid. + +.. class:: InvalidBase64LengthDefect + + When decoding a block of base64 encoded bytes, the number of non-padding + base64 characters was invalid (1 more than a multiple of 4). The encoded + block was kept as-is. + +.. class:: InvalidDateDefect + + When decoding an invalid or unparsable date field. The original value is + kept as-is. diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 0711a4f9c2e6cd..5a57445bd39943 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -19,7 +19,6 @@ Doc/library/collections.rst Doc/library/decimal.rst Doc/library/email.charset.rst Doc/library/email.compat32-message.rst -Doc/library/email.errors.rst Doc/library/email.parser.rst Doc/library/exceptions.rst Doc/library/functools.rst From 66850fe45a56d6d20b96841637e334707296837b Mon Sep 17 00:00:00 2001 From: Yuki Kobayashi Date: Mon, 3 Mar 2025 15:41:54 +0900 Subject: [PATCH 2/2] Update email.errors.rst --- Doc/library/email.errors.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/email.errors.rst b/Doc/library/email.errors.rst index 4aecee59e67a28..689e7397cbcf1f 100644 --- a/Doc/library/email.errors.rst +++ b/Doc/library/email.errors.rst @@ -77,32 +77,32 @@ object would have a defect, but the containing messages would not. All defect classes are subclassed from :class:`email.errors.MessageDefect`. -.. class:: NoBoundaryInMultipartDefect +.. exception:: NoBoundaryInMultipartDefect A message claimed to be a multipart, but had no :mimetype:`boundary` parameter. -.. class:: StartBoundaryNotFoundDefect +.. exception:: StartBoundaryNotFoundDefect The start boundary claimed in the :mailheader:`Content-Type` header was never found. -.. class:: CloseBoundaryNotFoundDefect +.. exception:: CloseBoundaryNotFoundDefect A start boundary was found, but no corresponding close boundary was ever found. .. versionadded:: 3.3 -.. class:: FirstHeaderLineIsContinuationDefect +.. exception:: FirstHeaderLineIsContinuationDefect The message had a continuation line as its first header line. -.. class:: MisplacedEnvelopeHeaderDefect +.. exception:: MisplacedEnvelopeHeaderDefect A "Unix From" header was found in the middle of a header block. -.. class:: MissingHeaderBodySeparatorDefect +.. exception:: MissingHeaderBodySeparatorDefect A line was found while parsing headers that had no leading white space but contained no ':'. Parsing continues assuming that the line represents the @@ -110,39 +110,39 @@ All defect classes are subclassed from :class:`email.errors.MessageDefect`. .. versionadded:: 3.3 -.. class:: MalformedHeaderDefect +.. exception:: MalformedHeaderDefect A header was found that was missing a colon, or was otherwise malformed. .. deprecated:: 3.3 This defect has not been used for several Python versions. -.. class:: MultipartInvariantViolationDefect +.. exception:: MultipartInvariantViolationDefect A message claimed to be a :mimetype:`multipart`, but no subparts were found. Note that when a message has 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 +.. exception:: InvalidBase64PaddingDefect When decoding a block of base64 encoded bytes, the padding was not correct. Enough padding is added to perform the decode, but the resulting decoded bytes may be invalid. -.. class:: InvalidBase64CharactersDefect +.. exception:: InvalidBase64CharactersDefect When decoding a block of base64 encoded bytes, characters outside the base64 alphabet were encountered. The characters are ignored, but the resulting decoded bytes may be invalid. -.. class:: InvalidBase64LengthDefect +.. exception:: InvalidBase64LengthDefect When decoding a block of base64 encoded bytes, the number of non-padding base64 characters was invalid (1 more than a multiple of 4). The encoded block was kept as-is. -.. class:: InvalidDateDefect +.. exception:: InvalidDateDefect When decoding an invalid or unparsable date field. The original value is kept as-is.