Doc/lib/emailexc.tex

   1 \declaremodule{standard}{email.Errors}
   2 \modulesynopsis{The exception classes used by the email package.}
   3
   4 The following exception classes are defined in the
   5 \module{email.Errors} module:
   6
   7 \begin{excclassdesc}{MessageError}{}
   8 This is the base class for all exceptions that the \module{email}
   9 package can raise.  It is derived from the standard
  10 \exception{Exception} class and defines no additional methods.
  11 \end{excclassdesc}
  12
  13 \begin{excclassdesc}{MessageParseError}{}
  14 This is the base class for exceptions thrown by the \class{Parser}
  15 class.  It is derived from \exception{MessageError}.
  16 \end{excclassdesc}
  17
  18 \begin{excclassdesc}{HeaderParseError}{}
  19 Raised under some error conditions when parsing the \rfc{2822} headers of
  20 a message, this class is derived from \exception{MessageParseError}.
  21 It can be raised from the \method{Parser.parse()} or
  22 \method{Parser.parsestr()} methods.
  23
  24 Situations where it can be raised include finding an envelope
  25 header after the first \rfc{2822} header of the message, finding a
  26 continuation line before the first \rfc{2822} header is found, or finding
  27 a line in the headers which is neither a header or a continuation
  28 line.
  29 \end{excclassdesc}
  30
  31 \begin{excclassdesc}{BoundaryError}{}
  32 Raised under some error conditions when parsing the \rfc{2822} headers of
  33 a message, this class is derived from \exception{MessageParseError}.
  34 It can be raised from the \method{Parser.parse()} or
  35 \method{Parser.parsestr()} methods.
  36
  37 Situations where it can be raised include not being able to find the
  38 starting or terminating boundary in a \mimetype{multipart/*} message
  39 when strict parsing is used.
  40 \end{excclassdesc}
  41
  42 \begin{excclassdesc}{MultipartConversionError}{}
  43 Raised when a payload is added to a \class{Message} object using
  44 \method{add_payload()}, but the payload is already a scalar and the
  45 message's \mailheader{Content-Type} main type is not either
  46 \mimetype{multipart} or missing.  \exception{MultipartConversionError}
  47 multiply inherits from \exception{MessageError} and the built-in
  48 \exception{TypeError}.
  49
  50 Since \method{Message.add_payload()} is deprecated, this exception is
  51 rarely raised in practice.  However the exception may also be raised
  52 if the \method{attach()} method is called on an instance of a class
  53 derived from \class{MIMENonMultipart} (e.g. \class{MIMEImage}).
  54 \end{excclassdesc}
  55
  56 Here's the list of the defects that the \class{FeedParser} can find while
  57 parsing messages.  Note that the defects are added to the message where the
  58 problem was found, so for example, if a message nested inside a
  59 \mimetype{multipart/alternative} had a malformed header, that nested message
  60 object would have a defect, but the containing messages would not.
  61
  62 All defect classes are subclassed from \class{email.Errors.MessageDefect}, but
  63 this class is \emph{not} an exception!
  64
  65 \versionadded[All the defect classes were added]{2.4}
  66
  67 \begin{itemize}
  68 \item \class{NoBoundaryInMultipartDefect} -- A message claimed to be a
  69       multipart, but had no \mimetype{boundary} parameter.
  70
  71 \item \class{StartBoundaryNotFoundDefect} -- The start boundary claimed in the
  72       \mailheader{Content-Type} header was never found.
  73
  74 \item \class{FirstHeaderLineIsContinuationDefect} -- The message had a
  75       continuation line as its first header line.
  76
  77 \item \class{MisplacedEnvelopeHeaderDefect} - A ``Unix From'' header was found
  78       in the middle of a header block.
  79
  80 \item \class{MalformedHeaderDefect} -- A header was found that was missing a
  81       colon, or was otherwise malformed.
  82
  83 \item \class{MultipartInvariantViolationDefect} -- A message claimed to be a
  84       \mimetype{multipart}, but no subparts were found.  Note that when a
  85       message has this defect, its \method{is_multipart()} method may return
  86       false even though its content type claims to be \mimetype{multipart}.
  87 \end{itemize}