R David Murray | 79cf3ba | 2012-05-27 17:10:36 -0400 | [diff] [blame] | 1 | :mod:`email.errors`: Exception and Defect classes |
| 2 | ------------------------------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: email.errors |
| 5 | :synopsis: The exception classes used by the email package. |
| 6 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | **Source code:** :source:`Lib/email/errors.py` |
| 8 | |
| 9 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 27 | |
| 28 | |
| 29 | .. exception:: HeaderParseError() |
| 30 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | |
| 40 | |
| 41 | .. exception:: BoundaryError() |
| 42 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 43 | Deprecated and no longer used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 44 | |
| 45 | |
| 46 | .. exception:: MultipartConversionError() |
| 47 | |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 48 | Raised when a payload is added to a :class:`~email.message.Message` object |
| 49 | using :meth:`add_payload`, but the payload is already a scalar and the |
| 50 | message's :mailheader:`Content-Type` main type is not either |
| 51 | :mimetype:`multipart` or missing. :exc:`MultipartConversionError` multiply |
| 52 | inherits from :exc:`MessageError` and the built-in :exc:`TypeError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 53 | |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 54 | Since :meth:`Message.add_payload` is deprecated, this exception is rarely |
| 55 | raised in practice. However the exception may also be raised if the |
| 56 | :meth:`~email.message.Message.attach` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | method is called on an instance of a class derived from |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 58 | :class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g. |
| 59 | :class:`~email.mime.image.MIMEImage`). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 61 | |
| 62 | Here is the list of the defects that the :class:`~email.parser.FeedParser` |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 63 | can find while parsing messages. Note that the defects are added to the message |
| 64 | where the problem was found, so for example, if a message nested inside a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | :mimetype:`multipart/alternative` had a malformed header, that nested message |
| 66 | object would have a defect, but the containing messages would not. |
| 67 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 68 | All defect classes are subclassed from :class:`email.errors.MessageDefect`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 70 | * :class:`NoBoundaryInMultipartDefect` -- A message claimed to be a multipart, |
| 71 | but had no :mimetype:`boundary` parameter. |
| 72 | |
| 73 | * :class:`StartBoundaryNotFoundDefect` -- The start boundary claimed in the |
| 74 | :mailheader:`Content-Type` header was never found. |
| 75 | |
R David Murray | 7ef3ff3 | 2012-05-27 22:20:42 -0400 | [diff] [blame] | 76 | * :class:`CloseBoundaryNotFoundDefect` -- A start boundary was found, but |
| 77 | no corresponding close boundary was ever found. |
| 78 | |
Georg Brandl | 61063cc | 2012-06-24 22:48:30 +0200 | [diff] [blame] | 79 | .. versionadded:: 3.3 |
R David Murray | 7ef3ff3 | 2012-05-27 22:20:42 -0400 | [diff] [blame] | 80 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 81 | * :class:`FirstHeaderLineIsContinuationDefect` -- The message had a continuation |
| 82 | line as its first header line. |
| 83 | |
| 84 | * :class:`MisplacedEnvelopeHeaderDefect` - A "Unix From" header was found in the |
| 85 | middle of a header block. |
| 86 | |
R David Murray | adbdcdb | 2012-05-27 20:45:01 -0400 | [diff] [blame] | 87 | * :class:`MissingHeaderBodySeparatorDefect` - A line was found while parsing |
| 88 | headers that had no leading white space but contained no ':'. Parsing |
| 89 | continues assuming that the line represents the first line of the body. |
| 90 | |
Georg Brandl | 61063cc | 2012-06-24 22:48:30 +0200 | [diff] [blame] | 91 | .. versionadded:: 3.3 |
R David Murray | adbdcdb | 2012-05-27 20:45:01 -0400 | [diff] [blame] | 92 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 93 | * :class:`MalformedHeaderDefect` -- A header was found that was missing a colon, |
| 94 | or was otherwise malformed. |
| 95 | |
R David Murray | adbdcdb | 2012-05-27 20:45:01 -0400 | [diff] [blame] | 96 | .. deprecated:: 3.3 |
| 97 | This defect has not been used for several Python versions. |
| 98 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 99 | * :class:`MultipartInvariantViolationDefect` -- A message claimed to be a |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 100 | :mimetype:`multipart`, but no subparts were found. Note that when a message |
| 101 | has this defect, its :meth:`~email.message.Message.is_multipart` method may |
| 102 | return false even though its content type claims to be :mimetype:`multipart`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | |
R David Murray | 80e0aee | 2012-05-27 21:23:34 -0400 | [diff] [blame] | 104 | * :class:`InvalidBase64PaddingDefect` -- When decoding a block of base64 |
delirious-lettuce | 3378b20 | 2017-05-19 14:37:57 -0600 | [diff] [blame] | 105 | encoded bytes, the padding was not correct. Enough padding is added to |
R David Murray | 80e0aee | 2012-05-27 21:23:34 -0400 | [diff] [blame] | 106 | perform the decode, but the resulting decoded bytes may be invalid. |
| 107 | |
| 108 | * :class:`InvalidBase64CharactersDefect` -- When decoding a block of base64 |
delirious-lettuce | 3378b20 | 2017-05-19 14:37:57 -0600 | [diff] [blame] | 109 | encoded bytes, characters outside the base64 alphabet were encountered. |
R David Murray | 80e0aee | 2012-05-27 21:23:34 -0400 | [diff] [blame] | 110 | The characters are ignored, but the resulting decoded bytes may be invalid. |
Tal Einat | c3f55be | 2018-06-12 15:46:22 +0300 | [diff] [blame] | 111 | |
| 112 | * :class:`InvalidBase64LengthDefect` -- When decoding a block of base64 encoded |
| 113 | bytes, the number of non-padding base64 characters was invalid (1 more than |
| 114 | a multiple of 4). The encoded block was kept as-is. |