Debian Codegraph @

Doc/library/email.errors.rst

raw
1 :mod:`!email.errors`: Exception and Defect classes
2 --------------------------------------------------
3
4 .. module:: email.errors
5 :synopsis: The exception classes used by the email package.
6
7 **Source code:** :source:`Lib/email/errors.py`
8
9 --------------
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
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`.
27
28
29 .. exception:: HeaderParseError()
30
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).
39
40
41 .. exception:: BoundaryError()
42
43 Deprecated and no longer used.
44
45
46 .. exception:: MultipartConversionError()
47
48 Raised if the :meth:`~email.message.Message.attach` method is called
49 on an instance of a class derived from
50 :class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g.
51 :class:`~email.mime.image.MIMEImage`).
52 :exc:`MultipartConversionError` multiply
53 inherits from :exc:`MessageError` and the built-in :exc:`TypeError`.
54
55
56 .. exception:: HeaderWriteError()
57
58 Raised when an error occurs when the :mod:`~email.generator` outputs
59 headers.
60
61
62 .. exception:: MessageDefect()
63
64 This is the base class for all defects found when parsing email messages.
65 It is derived from :exc:`ValueError`.
66
67 .. exception:: HeaderDefect()
68
69 This is the base class for all defects found when parsing email headers.
70 It is derived from :exc:`MessageDefect`.
71
72 Here is the list of the defects that the :class:`~email.parser.FeedParser`
73 can find while parsing messages. Note that the defects are added to the message
74 where the problem was found, so for example, if a message nested inside a
75 :mimetype:`multipart/alternative` had a malformed header, that nested message
76 object would have a defect, but the containing messages would not.
77
78 All defect classes are subclassed from :class:`email.errors.MessageDefect`.
79
80 .. exception:: NoBoundaryInMultipartDefect
81
82 A message claimed to be a multipart, but had no :mimetype:`boundary`
83 parameter.
84
85 .. exception:: StartBoundaryNotFoundDefect
86
87 The start boundary claimed in the :mailheader:`Content-Type` header was
88 never found.
89
90 .. exception:: CloseBoundaryNotFoundDefect
91
92 A start boundary was found, but no corresponding close boundary was ever
93 found.
94
95 .. versionadded:: 3.3
96
97 .. exception:: FirstHeaderLineIsContinuationDefect
98
99 The message had a continuation line as its first header line.
100
101 .. exception:: MisplacedEnvelopeHeaderDefect
102
103 A "Unix From" header was found in the middle of a header block.
104
105 .. exception:: MissingHeaderBodySeparatorDefect
106
107 A line was found while parsing headers that had no leading white space but
108 contained no ':'. Parsing continues assuming that the line represents the
109 first line of the body.
110
111 .. versionadded:: 3.3
112
113 .. exception:: MalformedHeaderDefect
114
115 A header was found that was missing a colon, or was otherwise malformed.
116
117 .. deprecated:: 3.3
118 This defect has not been used for several Python versions.
119
120 .. exception:: MultipartInvariantViolationDefect
121
122 A message claimed to be a :mimetype:`multipart`, but no subparts were found.
123 Note that when a message has this defect, its
124 :meth:`~email.message.Message.is_multipart` method may return ``False``
125 even though its content type claims to be :mimetype:`multipart`.
126
127 .. exception:: InvalidBase64PaddingDefect
128
129 When decoding a block of base64 encoded bytes, the padding was not correct.
130 Enough padding is added to perform the decode, but the resulting decoded
131 bytes may be invalid.
132
133 .. exception:: InvalidBase64CharactersDefect
134
135 When decoding a block of base64 encoded bytes, characters outside the base64
136 alphabet were encountered. The characters are ignored, but the resulting
137 decoded bytes may be invalid.
138
139 .. exception:: InvalidBase64LengthDefect
140
141 When decoding a block of base64 encoded bytes, the number of non-padding
142 base64 characters was invalid (1 more than a multiple of 4). The encoded
143 block was kept as-is.
144
145 .. exception:: InvalidDateDefect
146
147 When decoding an invalid or unparsable date field. The original value is
148 kept as-is.