Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`email`: Exception and Defect classes |
| 2 | ------------------------------------------ |
| 3 | |
| 4 | .. module:: email.errors |
| 5 | :synopsis: The exception classes used by the email package. |
| 6 | |
| 7 | |
| 8 | The following exception classes are defined in the :mod:`email.errors` module: |
| 9 | |
| 10 | |
| 11 | .. exception:: MessageError() |
| 12 | |
| 13 | This is the base class for all exceptions that the :mod:`email` package can |
| 14 | raise. It is derived from the standard :exc:`Exception` class and defines no |
| 15 | additional methods. |
| 16 | |
| 17 | |
| 18 | .. exception:: MessageParseError() |
| 19 | |
Georg Brandl | 7cb1319 | 2010-08-03 12:06:29 +0000 | [diff] [blame] | 20 | This is the base class for exceptions raised by the :class:`~email.parser.Parser` |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 21 | class. It is derived from :exc:`MessageError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 22 | |
| 23 | |
| 24 | .. exception:: HeaderParseError() |
| 25 | |
| 26 | Raised under some error conditions when parsing the :rfc:`2822` headers of a |
| 27 | message, this class is derived from :exc:`MessageParseError`. It can be raised |
| 28 | from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods. |
| 29 | |
| 30 | Situations where it can be raised include finding an envelope header after the |
| 31 | first :rfc:`2822` header of the message, finding a continuation line before the |
| 32 | first :rfc:`2822` header is found, or finding a line in the headers which is |
| 33 | neither a header or a continuation line. |
| 34 | |
| 35 | |
| 36 | .. exception:: BoundaryError() |
| 37 | |
| 38 | Raised under some error conditions when parsing the :rfc:`2822` headers of a |
| 39 | message, this class is derived from :exc:`MessageParseError`. It can be raised |
| 40 | from the :meth:`Parser.parse` or :meth:`Parser.parsestr` methods. |
| 41 | |
| 42 | Situations where it can be raised include not being able to find the starting or |
| 43 | terminating boundary in a :mimetype:`multipart/\*` message when strict parsing |
| 44 | is used. |
| 45 | |
| 46 | |
| 47 | .. exception:: MultipartConversionError() |
| 48 | |
| 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`. |
| 54 | |
| 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 | 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 | |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 61 | Here's the list of the defects that the :class:`~email.mime.parser.FeedParser` |
| 62 | can find while parsing messages. Note that the defects are added to the message |
| 63 | 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] | 64 | :mimetype:`multipart/alternative` had a malformed header, that nested message |
| 65 | object would have a defect, but the containing messages would not. |
| 66 | |
| 67 | All defect classes are subclassed from :class:`email.errors.MessageDefect`, but |
| 68 | this class is *not* an exception! |
| 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 | |
| 76 | * :class:`FirstHeaderLineIsContinuationDefect` -- The message had a continuation |
| 77 | line as its first header line. |
| 78 | |
| 79 | * :class:`MisplacedEnvelopeHeaderDefect` - A "Unix From" header was found in the |
| 80 | middle of a header block. |
| 81 | |
| 82 | * :class:`MalformedHeaderDefect` -- A header was found that was missing a colon, |
| 83 | or was otherwise malformed. |
| 84 | |
| 85 | * :class:`MultipartInvariantViolationDefect` -- A message claimed to be a |
| 86 | :mimetype:`multipart`, but no subparts were found. Note that when a message has |
| 87 | this defect, its :meth:`is_multipart` method may return false even though its |
| 88 | content type claims to be :mimetype:`multipart`. |
| 89 | |