source: trunk/essentials/dev-lang/python/Doc/lib/emailexc.tex@ 3368

\declaremodule{standard}{email.errors}
\modulesynopsis{The exception classes used by the email package.}

The following exception classes are defined in the
\module{email.errors} module:

\begin{excclassdesc}{MessageError}{}
This is the base class for all exceptions that the \module{email}
package can raise.  It is derived from the standard
\exception{Exception} class and defines no additional methods.
\end{excclassdesc}

\begin{excclassdesc}{MessageParseError}{}
This is the base class for exceptions thrown by the \class{Parser}
class.  It is derived from \exception{MessageError}.
\end{excclassdesc}

\begin{excclassdesc}{HeaderParseError}{}
Raised under some error conditions when parsing the \rfc{2822} headers of
a message, this class is derived from \exception{MessageParseError}.
It can be raised from the \method{Parser.parse()} or
\method{Parser.parsestr()} methods.

Situations where it can be raised include finding an envelope
header after the first \rfc{2822} header of the message, finding a
continuation line before the first \rfc{2822} header is found, or finding
a line in the headers which is neither a header or a continuation
line.
\end{excclassdesc}

\begin{excclassdesc}{BoundaryError}{}
Raised under some error conditions when parsing the \rfc{2822} headers of
a message, this class is derived from \exception{MessageParseError}.
It can be raised from the \method{Parser.parse()} or
\method{Parser.parsestr()} methods.

Situations where it can be raised include not being able to find the
starting or terminating boundary in a \mimetype{multipart/*} message
when strict parsing is used.
\end{excclassdesc}

\begin{excclassdesc}{MultipartConversionError}{}
Raised when a payload is added to a \class{Message} object using
\method{add_payload()}, but the payload is already a scalar and the
message's \mailheader{Content-Type} main type is not either
\mimetype{multipart} or missing.  \exception{MultipartConversionError}
multiply inherits from \exception{MessageError} and the built-in
\exception{TypeError}.

Since \method{Message.add_payload()} is deprecated, this exception is
rarely raised in practice.  However the exception may also be raised
if the \method{attach()} method is called on an instance of a class
derived from \class{MIMENonMultipart} (e.g. \class{MIMEImage}).
\end{excclassdesc}

Here's the list of the defects that the \class{FeedParser} can find while
parsing messages.  Note that the defects are added to the message where the
problem was found, so for example, if a message nested inside a
\mimetype{multipart/alternative} had a malformed header, that nested message
object would have a defect, but the containing messages would not.

All defect classes are subclassed from \class{email.errors.MessageDefect}, but
this class is \emph{not} an exception!

\versionadded[All the defect classes were added]{2.4}

\begin{itemize}
\item \class{NoBoundaryInMultipartDefect} -- A message claimed to be a
      multipart, but had no \mimetype{boundary} parameter.

\item \class{StartBoundaryNotFoundDefect} -- The start boundary claimed in the
      \mailheader{Content-Type} header was never found.

\item \class{FirstHeaderLineIsContinuationDefect} -- The message had a
      continuation line as its first header line.

\item \class{MisplacedEnvelopeHeaderDefect} - A ``Unix From'' header was found
      in the middle of a header block.

\item \class{MalformedHeaderDefect} -- A header was found that was missing a
      colon, or was otherwise malformed.

\item \class{MultipartInvariantViolationDefect} -- A message claimed to be a
      \mimetype{multipart}, but no subparts were found.  Note that when a
      message has this defect, its \method{is_multipart()} method may return
      false even though its content type claims to be \mimetype{multipart}.
\end{itemize}