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 

    20    This is the base class for exceptions thrown by the :class:`Parser` class.  It

    21    is derived from :exc:`MessageError`.

    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

    58    :class:`MIMENonMultipart` (e.g. :class:`MIMEImage`).

    59 

    60 Here's the list of the defects that the :class:`FeedParser` can find while

    61 parsing messages.  Note that the defects are added to the message where the

    62 problem was found, so for example, if a message nested inside a

    63 :mimetype:`multipart/alternative` had a malformed header, that nested message

    64 object would have a defect, but the containing messages would not.

    65 

    66 All defect classes are subclassed from :class:`email.errors.MessageDefect`, but

    67 this class is *not* an exception!

    68 

    69 .. versionadded:: 2.4

    70    All the defect classes were added.

    71 

    72 * :class:`NoBoundaryInMultipartDefect` -- A message claimed to be a multipart,

    73   but had no :mimetype:`boundary` parameter.

    74 

    75 * :class:`StartBoundaryNotFoundDefect` -- The start boundary claimed in the

    76   :mailheader:`Content-Type` header was never found.

    77 

    78 * :class:`FirstHeaderLineIsContinuationDefect` -- The message had a continuation

    79   line as its first header line.

    80 

    81 * :class:`MisplacedEnvelopeHeaderDefect` - A "Unix From" header was found in the

    82   middle of a header block.

    83 

    84 * :class:`MalformedHeaderDefect` -- A header was found that was missing a colon,

    85   or was otherwise malformed.

    86 

    87 * :class:`MultipartInvariantViolationDefect` -- A message claimed to be a

    88   :mimetype:`multipart`, but no subparts were found.  Note that when a message has

    89   this defect, its :meth:`is_multipart` method may return false even though its

    90   content type claims to be :mimetype:`multipart`.

    91