Debian Codegraph @

Lib/email/policy.py

raw
1 """This will be the home for the policy that hooks in the new
2 code that adds all the email6 features.
3 """
4
5 import re
6 import sys
7 from email._policybase import (
8 Compat32,
9 Policy,
10 _extend_docstrings,
11 compat32,
12 validate_header_name
13 )
14 from email.utils import _has_surrogates
15 from email.headerregistry import HeaderRegistry as HeaderRegistry
16 from email.contentmanager import raw_data_manager
17 from email.message import EmailMessage
18
19 __all__ = [
20 'Compat32',
21 'compat32',
22 'Policy',
23 'EmailPolicy',
24 'default',
25 'strict',
26 'SMTP',
27 'HTTP',
28 ]
29
30 linesep_splitter = re.compile(r'\n|\r\n?')
31
32 @_extend_docstrings
33 class EmailPolicy(Policy):
34
35 """+
36 PROVISIONAL
37
38 The API extensions enabled by this policy are currently provisional.
39 Refer to the documentation for details.
40
41 This policy adds new header parsing and folding algorithms. Instead of
42 simple strings, headers are custom objects with custom attributes
43 depending on the type of the field. The folding algorithm fully
44 implements RFCs 2047 and 5322.
45
46 In addition to the settable attributes listed above that apply to
47 all Policies, this policy adds the following additional attributes:
48
49 utf8 -- if False (the default) message headers will be
50 serialized as ASCII, using encoded words to encode
51 any non-ASCII characters in the source strings. If
52 True, the message headers will be serialized using
53 utf8 and will not contain encoded words (see RFC
54 6532 for more on this serialization format).
55
56 refold_source -- if the value for a header in the Message object
57 came from the parsing of some source, this attribute
58 indicates whether or not a generator should refold
59 that value when transforming the message back into
60 stream form. The possible values are:
61
62 none -- all source values use original folding
63 long -- source values that have any line that is
64 longer than max_line_length will be
65 refolded
66 all -- all values are refolded.
67
68 The default is 'long'.
69
70 header_factory -- a callable that takes two arguments, 'name' and
71 'value', where 'name' is a header field name and
72 'value' is an unfolded header field value, and
73 returns a string-like object that represents that
74 header. A default header_factory is provided that
75 understands some of the RFC5322 header field types.
76 (Currently address fields and date fields have
77 special treatment, while all other fields are
78 treated as unstructured. This list will be
79 completed before the extension is marked stable.)
80
81 content_manager -- an object with at least two methods: get_content
82 and set_content. When the get_content or
83 set_content method of a Message object is called,
84 it calls the corresponding method of this object,
85 passing it the message object as its first argument,
86 and any arguments or keywords that were passed to
87 it as additional arguments. The default
88 content_manager is
89 :data:`~email.contentmanager.raw_data_manager`.
90
91 """
92
93 message_factory = EmailMessage
94 utf8 = False
95 refold_source = 'long'
96 header_factory = HeaderRegistry()
97 content_manager = raw_data_manager
98
99 def __init__(self, **kw):
100 # Ensure that each new instance gets a unique header factory
101 # (as opposed to clones, which share the factory).
102 if 'header_factory' not in kw:
103 object.__setattr__(self, 'header_factory', HeaderRegistry())
104 super().__init__(**kw)
105
106 def header_max_count(self, name):
107 """+
108 The implementation for this class returns the max_count attribute from
109 the specialized header class that would be used to construct a header
110 of type 'name'.
111 """
112 return self.header_factory[name].max_count
113
114 # The logic of the next three methods is chosen such that it is possible to
115 # switch a Message object between a Compat32 policy and a policy derived
116 # from this class and have the results stay consistent. This allows a
117 # Message object constructed with this policy to be passed to a library
118 # that only handles Compat32 objects, or to receive such an object and
119 # convert it to use the newer style by just changing its policy. It is
120 # also chosen because it postpones the relatively expensive full rfc5322
121 # parse until as late as possible when parsing from source, since in many
122 # applications only a few headers will actually be inspected.
123
124 def header_source_parse(self, sourcelines):
125 """+
126 The name is parsed as everything up to the ':' and returned unmodified.
127 The value is determined by stripping leading whitespace off the
128 remainder of the first line joined with all subsequent lines, and
129 stripping any trailing carriage return or linefeed characters. (This
130 is the same as Compat32).
131
132 """
133 name, value = sourcelines[0].split(':', 1)
134 value = ''.join((value, *sourcelines[1:])).lstrip(' \t\r\n')
135 return (name, value.rstrip('\r\n'))
136
137 def header_store_parse(self, name, value):
138 """+
139 The name is returned unchanged. If the input value has a 'name'
140 attribute and it matches the name ignoring case, the value is returned
141 unchanged. Otherwise the name and value are passed to header_factory
142 method, and the resulting custom header object is returned as the
143 value. In this case a ValueError is raised if the input value contains
144 CR or LF characters.
145
146 """
147 validate_header_name(name)
148 if hasattr(value, 'name') and value.name.lower() == name.lower():
149 return (name, value)
150 if isinstance(value, str) and len(value.splitlines())>1:
151 # XXX this error message isn't quite right when we use splitlines
152 # (see issue 22233), but I'm not sure what should happen here.
153 raise ValueError("Header values may not contain linefeed "
154 "or carriage return characters")
155 return (name, self.header_factory(name, value))
156
157 def header_fetch_parse(self, name, value):
158 """+
159 If the value has a 'name' attribute, it is returned to unmodified.
160 Otherwise the name and the value with any linesep characters removed
161 are passed to the header_factory method, and the resulting custom
162 header object is returned. Any surrogateescaped bytes get turned
163 into the unicode unknown-character glyph.
164
165 """
166 if hasattr(value, 'name'):
167 return value
168 # We can't use splitlines here because it splits on more than \r and \n.
169 value = ''.join(linesep_splitter.split(value))
170 return self.header_factory(name, value)
171
172 def fold(self, name, value):
173 """+
174 Header folding is controlled by the refold_source policy setting. A
175 value is considered to be a 'source value' if and only if it does not
176 have a 'name' attribute (having a 'name' attribute means it is a header
177 object of some sort). If a source value needs to be refolded according
178 to the policy, it is converted into a custom header object by passing
179 the name and the value with any linesep characters removed to the
180 header_factory method. Folding of a custom header object is done by
181 calling its fold method with the current policy.
182
183 Source values are split into lines using splitlines. If the value is
184 not to be refolded, the lines are rejoined using the linesep from the
185 policy and returned. The exception is lines containing non-ascii
186 binary data. In that case the value is refolded regardless of the
187 refold_source setting, which causes the binary data to be CTE encoded
188 using the unknown-8bit charset.
189
190 """
191 return self._fold(name, value, refold_binary=True)
192
193 def fold_binary(self, name, value):
194 """+
195 The same as fold if cte_type is 7bit, except that the returned value is
196 bytes.
197
198 If cte_type is 8bit, non-ASCII binary data is converted back into
199 bytes. Headers with binary data are not refolded, regardless of the
200 refold_header setting, since there is no way to know whether the binary
201 data consists of single byte characters or multibyte characters.
202
203 If utf8 is true, headers are encoded to utf8, otherwise to ascii with
204 non-ASCII unicode rendered as encoded words.
205
206 """
207 folded = self._fold(name, value, refold_binary=self.cte_type=='7bit')
208 charset = 'utf8' if self.utf8 else 'ascii'
209 return folded.encode(charset, 'surrogateescape')
210
211 def _fold(self, name, value, refold_binary=False):
212 if hasattr(value, 'name'):
213 return value.fold(policy=self)
214 maxlen = self.max_line_length if self.max_line_length else sys.maxsize
215 # We can't use splitlines here because it splits on more than \r and \n.
216 lines = linesep_splitter.split(value)
217 refold = (self.refold_source == 'all' or
218 self.refold_source == 'long' and
219 (lines and len(lines[0])+len(name)+2 > maxlen or
220 any(len(x) > maxlen for x in lines[1:])))
221
222 if not refold:
223 if not self.utf8:
224 refold = not value.isascii()
225 elif refold_binary:
226 refold = _has_surrogates(value)
227 if refold:
228 return self.header_factory(name, ''.join(lines)).fold(policy=self)
229
230 return name + ': ' + self.linesep.join(lines) + self.linesep
231
232
233 default = EmailPolicy()
234 # Make the default policy use the class default header_factory
235 del default.header_factory
236 strict = default.clone(raise_on_defect=True)
237 SMTP = default.clone(linesep='\r\n')
238 HTTP = default.clone(linesep='\r\n', max_line_length=None)
239 SMTPUTF8 = SMTP.clone(utf8=True)