| 1 |
:mod:`!email.errors`: Exception and Defect classes |
| 2 |
-------------------------------------------------- |
| 3 |
|
| 4 |
.. module:: email.errors |
| 5 |
:synopsis: The exception classes used by the email package. |
| 6 |
|
| 7 |
**Source code:** :source:`Lib/email/errors.py` |
| 8 |
|
| 9 |
-------------- |
| 10 |
|
| 11 |
The following exception classes are defined in the :mod:`!email.errors` module: |
| 12 |
|
| 13 |
|
| 14 |
.. exception:: MessageError() |
| 15 |
|
| 16 |
This is the base class for all exceptions that the :mod:`email` package can |
| 17 |
raise. It is derived from the standard :exc:`Exception` class and defines no |
| 18 |
additional methods. |
| 19 |
|
| 20 |
|
| 21 |
.. exception:: MessageParseError() |
| 22 |
|
| 23 |
This is the base class for exceptions raised by the |
| 24 |
:class:`~email.parser.Parser` class. It is derived from |
| 25 |
:exc:`MessageError`. This class is also used internally by the parser used |
| 26 |
by :mod:`~email.headerregistry`. |
| 27 |
|
| 28 |
|
| 29 |
.. exception:: HeaderParseError() |
| 30 |
|
| 31 |
Raised under some error conditions when parsing the :rfc:`5322` headers of a |
| 32 |
message, this class is derived from :exc:`MessageParseError`. The |
| 33 |
:meth:`~email.message.EmailMessage.set_boundary` method will raise this |
| 34 |
error if the content type is unknown when the method is called. |
| 35 |
:class:`~email.header.Header` may raise this error for certain base64 |
| 36 |
decoding errors, and when an attempt is made to create a header that appears |
| 37 |
to contain an embedded header (that is, there is what is supposed to be a |
| 38 |
continuation line that has no leading whitespace and looks like a header). |
| 39 |
|
| 40 |
|
| 41 |
.. exception:: BoundaryError() |
| 42 |
|
| 43 |
Deprecated and no longer used. |
| 44 |
|
| 45 |
|
| 46 |
.. exception:: MultipartConversionError() |
| 47 |
|
| 48 |
Raised if the :meth:`~email.message.Message.attach` method is called |
| 49 |
on an instance of a class derived from |
| 50 |
:class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g. |
| 51 |
:class:`~email.mime.image.MIMEImage`). |
| 52 |
:exc:`MultipartConversionError` multiply |
| 53 |
inherits from :exc:`MessageError` and the built-in :exc:`TypeError`. |
| 54 |
|
| 55 |
|
| 56 |
.. exception:: HeaderWriteError() |
| 57 |
|
| 58 |
Raised when an error occurs when the :mod:`~email.generator` outputs |
| 59 |
headers. |
| 60 |
|
| 61 |
|
| 62 |
.. exception:: MessageDefect() |
| 63 |
|
| 64 |
This is the base class for all defects found when parsing email messages. |
| 65 |
It is derived from :exc:`ValueError`. |
| 66 |
|
| 67 |
.. exception:: HeaderDefect() |
| 68 |
|
| 69 |
This is the base class for all defects found when parsing email headers. |
| 70 |
It is derived from :exc:`MessageDefect`. |
| 71 |
|
| 72 |
Here is the list of the defects that the :class:`~email.parser.FeedParser` |
| 73 |
can find while parsing messages. Note that the defects are added to the message |
| 74 |
where the problem was found, so for example, if a message nested inside a |
| 75 |
:mimetype:`multipart/alternative` had a malformed header, that nested message |
| 76 |
object would have a defect, but the containing messages would not. |
| 77 |
|
| 78 |
All defect classes are subclassed from :class:`email.errors.MessageDefect`. |
| 79 |
|
| 80 |
.. exception:: NoBoundaryInMultipartDefect |
| 81 |
|
| 82 |
A message claimed to be a multipart, but had no :mimetype:`boundary` |
| 83 |
parameter. |
| 84 |
|
| 85 |
.. exception:: StartBoundaryNotFoundDefect |
| 86 |
|
| 87 |
The start boundary claimed in the :mailheader:`Content-Type` header was |
| 88 |
never found. |
| 89 |
|
| 90 |
.. exception:: CloseBoundaryNotFoundDefect |
| 91 |
|
| 92 |
A start boundary was found, but no corresponding close boundary was ever |
| 93 |
found. |
| 94 |
|
| 95 |
.. versionadded:: 3.3 |
| 96 |
|
| 97 |
.. exception:: FirstHeaderLineIsContinuationDefect |
| 98 |
|
| 99 |
The message had a continuation line as its first header line. |
| 100 |
|
| 101 |
.. exception:: MisplacedEnvelopeHeaderDefect |
| 102 |
|
| 103 |
A "Unix From" header was found in the middle of a header block. |
| 104 |
|
| 105 |
.. exception:: MissingHeaderBodySeparatorDefect |
| 106 |
|
| 107 |
A line was found while parsing headers that had no leading white space but |
| 108 |
contained no ':'. Parsing continues assuming that the line represents the |
| 109 |
first line of the body. |
| 110 |
|
| 111 |
.. versionadded:: 3.3 |
| 112 |
|
| 113 |
.. exception:: MalformedHeaderDefect |
| 114 |
|
| 115 |
A header was found that was missing a colon, or was otherwise malformed. |
| 116 |
|
| 117 |
.. deprecated:: 3.3 |
| 118 |
This defect has not been used for several Python versions. |
| 119 |
|
| 120 |
.. exception:: MultipartInvariantViolationDefect |
| 121 |
|
| 122 |
A message claimed to be a :mimetype:`multipart`, but no subparts were found. |
| 123 |
Note that when a message has this defect, its |
| 124 |
:meth:`~email.message.Message.is_multipart` method may return ``False`` |
| 125 |
even though its content type claims to be :mimetype:`multipart`. |
| 126 |
|
| 127 |
.. exception:: InvalidBase64PaddingDefect |
| 128 |
|
| 129 |
When decoding a block of base64 encoded bytes, the padding was not correct. |
| 130 |
Enough padding is added to perform the decode, but the resulting decoded |
| 131 |
bytes may be invalid. |
| 132 |
|
| 133 |
.. exception:: InvalidBase64CharactersDefect |
| 134 |
|
| 135 |
When decoding a block of base64 encoded bytes, characters outside the base64 |
| 136 |
alphabet were encountered. The characters are ignored, but the resulting |
| 137 |
decoded bytes may be invalid. |
| 138 |
|
| 139 |
.. exception:: InvalidBase64LengthDefect |
| 140 |
|
| 141 |
When decoding a block of base64 encoded bytes, the number of non-padding |
| 142 |
base64 characters was invalid (1 more than a multiple of 4). The encoded |
| 143 |
block was kept as-is. |
| 144 |
|
| 145 |
.. exception:: InvalidDateDefect |
| 146 |
|
| 147 |
When decoding an invalid or unparsable date field. The original value is |
| 148 |
kept as-is. |