Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/lib/python3.8/email/policy.py @ 69:33d812a61356

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