R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 1 | :mod:`email`: Policy Objects |
| 2 | ---------------------------- |
| 3 | |
| 4 | .. module:: email.policy |
| 5 | :synopsis: Controlling the parsing and generating of messages |
| 6 | |
Éric Araujo | 54dbfbd | 2011-08-10 21:43:13 +0200 | [diff] [blame] | 7 | .. versionadded:: 3.3 |
R David Murray | 6a45d3b | 2011-04-18 16:00:47 -0400 | [diff] [blame] | 8 | |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 9 | |
| 10 | The :mod:`email` package's prime focus is the handling of email messages as |
| 11 | described by the various email and MIME RFCs. However, the general format of |
| 12 | email messages (a block of header fields each consisting of a name followed by |
| 13 | a colon followed by a value, the whole block followed by a blank line and an |
| 14 | arbitrary 'body'), is a format that has found utility outside of the realm of |
| 15 | email. Some of these uses conform fairly closely to the main RFCs, some do |
| 16 | not. And even when working with email, there are times when it is desirable to |
| 17 | break strict compliance with the RFCs. |
| 18 | |
R David Murray | 6a45d3b | 2011-04-18 16:00:47 -0400 | [diff] [blame] | 19 | Policy objects give the email package the flexibility to handle all these |
| 20 | disparate use cases. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 21 | |
| 22 | A :class:`Policy` object encapsulates a set of attributes and methods that |
| 23 | control the behavior of various components of the email package during use. |
| 24 | :class:`Policy` instances can be passed to various classes and methods in the |
| 25 | email package to alter the default behavior. The settable values and their |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 26 | defaults are described below. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 27 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 28 | There is a default policy used by all classes in the email package. This |
| 29 | policy is named :class:`Compat32`, with a corresponding pre-defined instance |
| 30 | named :const:`compat32`. It provides for complete backward compatibility (in |
| 31 | some cases, including bug compatibility) with the pre-Python3.3 version of the |
| 32 | email package. |
| 33 | |
| 34 | The first part of this documentation covers the features of :class:`Policy`, an |
| 35 | :term:`abstract base class` that defines the features that are common to all |
| 36 | policy objects, including :const:`compat32`. This includes certain hook |
| 37 | methods that are called internally by the email package, which a custom policy |
| 38 | could override to obtain different behavior. |
| 39 | |
| 40 | When a :class:`~email.message.Message` object is created, it acquires a policy. |
| 41 | By default this will be :const:`compat32`, but a different policy can be |
| 42 | specified. If the ``Message`` is created by a :mod:`~email.parser`, a policy |
| 43 | passed to the parser will be the policy used by the ``Message`` it creates. If |
| 44 | the ``Message`` is created by the program, then the policy can be specified |
| 45 | when it is created. When a ``Message`` is passed to a :mod:`~email.generator`, |
| 46 | the generator uses the policy from the ``Message`` by default, but you can also |
| 47 | pass a specific policy to the generator that will override the one stored on |
| 48 | the ``Message`` object. |
| 49 | |
| 50 | :class:`Policy` instances are immutable, but they can be cloned, accepting the |
| 51 | same keyword arguments as the class constructor and returning a new |
| 52 | :class:`Policy` instance that is a copy of the original but with the specified |
| 53 | attributes values changed. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 54 | |
| 55 | As an example, the following code could be used to read an email message from a |
R David Murray | 6a45d3b | 2011-04-18 16:00:47 -0400 | [diff] [blame] | 56 | file on disk and pass it to the system ``sendmail`` program on a Unix system:: |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 57 | |
| 58 | >>> from email import msg_from_binary_file |
| 59 | >>> from email.generator import BytesGenerator |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 60 | >>> from subprocess import Popen, PIPE |
| 61 | >>> with open('mymsg.txt', 'b') as f: |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 62 | ... msg = msg_from_binary_file(f) |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 63 | >>> p = Popen(['sendmail', msg['To'][0].address], stdin=PIPE) |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 64 | >>> g = BytesGenerator(p.stdin, policy=msg.policy.clone(linesep='\r\n')) |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 65 | >>> g.flatten(msg) |
| 66 | >>> p.stdin.close() |
| 67 | >>> rc = p.wait() |
| 68 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 69 | Here we are telling :class:`~email.generator.BytesGenerator` to use the RFC |
| 70 | correct line separator characters when creating the binary string to feed into |
| 71 | ``sendmail's`` ``stdin``, where the default policy would use ``\n`` line |
| 72 | separators. |
Éric Araujo | fe0472e | 2011-12-03 16:00:56 +0100 | [diff] [blame] | 73 | |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 74 | Some email package methods accept a *policy* keyword argument, allowing the |
R David Murray | 6a45d3b | 2011-04-18 16:00:47 -0400 | [diff] [blame] | 75 | policy to be overridden for that method. For example, the following code uses |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 76 | the :meth:`~email.message.Message.as_string` method of the *msg* object from |
| 77 | the previous example and writes the message to a file using the native line |
| 78 | separators for the platform on which it is running:: |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 79 | |
| 80 | >>> import os |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 81 | >>> with open('converted.txt', 'wb') as f: |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 82 | ... f.write(msg.as_string(policy=msg.policy.clone(linesep=os.linesep)) |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 83 | |
| 84 | Policy objects can also be combined using the addition operator, producing a |
| 85 | policy object whose settings are a combination of the non-default values of the |
| 86 | summed objects:: |
| 87 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 88 | >>> compat_SMTP = email.policy.clone(linesep='\r\n') |
| 89 | >>> compat_strict = email.policy.clone(raise_on_defect=True) |
| 90 | >>> compat_strict_SMTP = compat_SMTP + compat_strict |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 91 | |
| 92 | This operation is not commutative; that is, the order in which the objects are |
| 93 | added matters. To illustrate:: |
| 94 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 95 | >>> policy100 = compat32.clone(max_line_length=100) |
| 96 | >>> policy80 = compat32.clone(max_line_length=80) |
| 97 | >>> apolicy = policy100 + Policy80 |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 98 | >>> apolicy.max_line_length |
| 99 | 80 |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 100 | >>> apolicy = policy80 + policy100 |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 101 | >>> apolicy.max_line_length |
| 102 | 100 |
| 103 | |
| 104 | |
| 105 | .. class:: Policy(**kw) |
| 106 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 107 | This is the :term:`abstract base class` for all policy classes. It provides |
| 108 | default implementations for a couple of trivial methods, as well as the |
| 109 | implementation of the immutability property, the :meth:`clone` method, and |
| 110 | the constructor semantics. |
| 111 | |
| 112 | The constructor of a policy class can be passed various keyword arguments. |
| 113 | The arguments that may be specified are any non-method properties on this |
| 114 | class, plus any additional non-method properties on the concrete class. A |
| 115 | value specified in the constructor will override the default value for the |
| 116 | corresponding attribute. |
| 117 | |
| 118 | This class defines the following properties, and thus values for the |
| 119 | following may be passed in the constructor of any policy class: |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 120 | |
| 121 | .. attribute:: max_line_length |
| 122 | |
| 123 | The maximum length of any line in the serialized output, not counting the |
| 124 | end of line character(s). Default is 78, per :rfc:`5322`. A value of |
| 125 | ``0`` or :const:`None` indicates that no line wrapping should be |
| 126 | done at all. |
| 127 | |
| 128 | .. attribute:: linesep |
| 129 | |
| 130 | The string to be used to terminate lines in serialized output. The |
R David Murray | 6a45d3b | 2011-04-18 16:00:47 -0400 | [diff] [blame] | 131 | default is ``\n`` because that's the internal end-of-line discipline used |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 132 | by Python, though ``\r\n`` is required by the RFCs. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 133 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 134 | .. attribute:: cte_type |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 135 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 136 | Controls the type of Content Transfer Encodings that may be or are |
| 137 | required to be used. The possible values are: |
| 138 | |
| 139 | ======== =============================================================== |
| 140 | ``7bit`` all data must be "7 bit clean" (ASCII-only). This means that |
| 141 | where necessary data will be encoded using either |
| 142 | quoted-printable or base64 encoding. |
| 143 | |
| 144 | ``8bit`` data is not constrained to be 7 bit clean. Data in headers is |
| 145 | still required to be ASCII-only and so will be encoded (see |
| 146 | 'binary_fold' below for an exception), but body parts may use |
| 147 | the ``8bit`` CTE. |
| 148 | ======== =============================================================== |
| 149 | |
| 150 | A ``cte_type`` value of ``8bit`` only works with ``BytesGenerator``, not |
| 151 | ``Generator``, because strings cannot contain binary data. If a |
| 152 | ``Generator`` is operating under a policy that specifies |
| 153 | ``cte_type=8bit``, it will act as if ``cte_type`` is ``7bit``. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 154 | |
| 155 | .. attribute:: raise_on_defect |
| 156 | |
| 157 | If :const:`True`, any defects encountered will be raised as errors. If |
| 158 | :const:`False` (the default), defects will be passed to the |
| 159 | :meth:`register_defect` method. |
| 160 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 161 | The following :class:`Policy` method is intended to be called by code using |
| 162 | the email library to create policy instances with custom settings: |
R David Murray | 6a45d3b | 2011-04-18 16:00:47 -0400 | [diff] [blame] | 163 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 164 | .. method:: clone(**kw) |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 165 | |
| 166 | Return a new :class:`Policy` instance whose attributes have the same |
| 167 | values as the current instance, except where those attributes are |
| 168 | given new values by the keyword arguments. |
| 169 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 170 | The remaining :class:`Policy` methods are called by the email package code, |
| 171 | and are not intended to be called by an application using the email package. |
| 172 | A custom policy must implement all of these methods. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 173 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 174 | .. method:: handle_defect(obj, defect) |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 175 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 176 | Handle a *defect* found on *obj*. When the email package calls this |
| 177 | method, *defect* will always be a subclass of |
| 178 | :class:`~email.errors.Defect`. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 179 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 180 | The default implementation checks the :attr:`raise_on_defect` flag. If |
| 181 | it is ``True``, *defect* is raised as an exception. If it is ``False`` |
| 182 | (the default), *obj* and *defect* are passed to :meth:`register_defect`. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 183 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 184 | .. method:: register_defect(obj, defect) |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 185 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 186 | Register a *defect* on *obj*. In the email package, *defect* will always |
| 187 | be a subclass of :class:`~email.errors.Defect`. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 188 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 189 | The default implementation calls the ``append`` method of the ``defects`` |
| 190 | attribute of *obj*. When the email package calls :attr:`handle_defect`, |
| 191 | *obj* will normally have a ``defects`` attribute that has an ``append`` |
| 192 | method. Custom object types used with the email package (for example, |
| 193 | custom ``Message`` objects) should also provide such an attribute, |
| 194 | otherwise defects in parsed messages will raise unexpected errors. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 195 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 196 | .. method:: header_source_parse(sourcelines) |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 197 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 198 | The email package calls this method with a list of strings, each string |
| 199 | ending with the line separation characters found in the source being |
| 200 | parsed. The first line includes the field header name and separator. |
| 201 | All whitespace in the source is preserved. The method should return the |
| 202 | ``(name, value)`` tuple that is to be stored in the ``Message`` to |
| 203 | represent the parsed header. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 204 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 205 | If an implementation wishes to retain compatibility with the existing |
| 206 | email package policies, *name* should be the case preserved name (all |
| 207 | characters up to the '``:``' separator), while *value* should be the |
| 208 | unfolded value (all line separator characters removed, but whitespace |
| 209 | kept intact), stripped of leading whitespace. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 210 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 211 | *sourcelines* may contain surrogateescaped binary data. |
| 212 | |
| 213 | There is no default implementation |
| 214 | |
| 215 | .. method:: header_store_parse(name, value) |
| 216 | |
| 217 | The email package calls this method with the name and value provided by |
| 218 | the application program when the application program is modifying a |
| 219 | ``Message`` programmatically (as opposed to a ``Message`` created by a |
| 220 | parser). The method should return the ``(name, value)`` tuple that is to |
| 221 | be stored in the ``Message`` to represent the header. |
| 222 | |
| 223 | If an implementation wishes to retain compatibility with the existing |
| 224 | email package policies, the *name* and *value* should be strings or |
| 225 | string subclasses that do not change the content of the passed in |
| 226 | arguments. |
| 227 | |
| 228 | There is no default implementation |
| 229 | |
| 230 | .. method:: header_fetch_parse(name, value) |
| 231 | |
| 232 | The email package calls this method with the *name* and *value* currently |
| 233 | stored in the ``Message`` when that header is requested by the |
| 234 | application program, and whatever the method returns is what is passed |
| 235 | back to the application as the value of the header being retrieved. |
| 236 | Note that there may be more than one header with the same name stored in |
| 237 | the ``Message``; the method is passed the specific name and value of the |
| 238 | header destined to be returned to the application. |
| 239 | |
| 240 | *value* may contain surrogateescaped binary data. There should be no |
| 241 | surrogateescaped binary data in the value returned by the method. |
| 242 | |
| 243 | There is no default implementation |
| 244 | |
| 245 | .. method:: fold(name, value) |
| 246 | |
| 247 | The email package calls this method with the *name* and *value* currently |
| 248 | stored in the ``Message`` for a given header. The method should return a |
| 249 | string that represents that header "folded" correctly (according to the |
| 250 | policy settings) by composing the *name* with the *value* and inserting |
| 251 | :attr:`linesep` characters at the appropriate places. See :rfc:`5322` |
| 252 | for a discussion of the rules for folding email headers. |
| 253 | |
| 254 | *value* may contain surrogateescaped binary data. There should be no |
| 255 | surrogateescaped binary data in the string returned by the method. |
| 256 | |
| 257 | .. method:: fold_binary(name, value) |
| 258 | |
| 259 | The same as :meth:`fold`, except that the returned value should be a |
| 260 | bytes object rather than a string. |
| 261 | |
| 262 | *value* may contain surrogateescaped binary data. These could be |
| 263 | converted back into binary data in the returned bytes object. |
| 264 | |
| 265 | |
| 266 | .. class:: Compat32(**kw) |
| 267 | |
| 268 | This concrete :class:`Policy` is the backward compatibility policy. It |
| 269 | replicates the behavior of the email package in Python 3.2. The |
| 270 | :mod:`policy` module also defines an instance of this class, |
| 271 | :const:`compat32`, that is used as the default policy. Thus the default |
| 272 | behavior of the email package is to maintain compatibility with Python 3.2. |
| 273 | |
| 274 | The class provides the following concrete implementations of the |
| 275 | abstract methods of :class:`Policy`: |
| 276 | |
| 277 | .. method:: header_source_parse(sourcelines) |
| 278 | |
| 279 | The name is parsed as everything up to the '``:``' and returned |
| 280 | unmodified. The value is determined by stripping leading whitespace off |
| 281 | the remainder of the first line, joining all subsequent lines together, |
| 282 | and stripping any trailing carriage return or linefeed characters. |
| 283 | |
| 284 | .. method:: header_store_parse(name, value) |
| 285 | |
| 286 | The name and value are returned unmodified. |
| 287 | |
| 288 | .. method:: header_fetch_parse(name, value) |
| 289 | |
| 290 | If the value contains binary data, it is converted into a |
| 291 | :class:`~email.header.Header` object using the ``unknown-8bit`` charset. |
| 292 | Otherwise it is returned unmodified. |
| 293 | |
| 294 | .. method:: fold(name, value) |
| 295 | |
| 296 | Headers are folded using the :class:`~email.header.Header` folding |
| 297 | algorithm, which preserves existing line breaks in the value, and wraps |
| 298 | each resulting line to the ``max_line_length``. Non-ASCII binary data are |
| 299 | CTE encoded using the ``unknown-8bit`` charset. |
| 300 | |
| 301 | .. method:: fold_binary(name, value) |
| 302 | |
| 303 | Headers are folded using the :class:`~email.header.Header` folding |
| 304 | algorithm, which preserves existing line breaks in the value, and wraps |
| 305 | each resulting line to the ``max_line_length``. If ``cte_type`` is |
| 306 | ``7bit``, non-ascii binary data is CTE encoded using the ``unknown-8bit`` |
| 307 | charset. Otherwise the original source header is used, with its existing |
| 308 | line breaks and and any (RFC invalid) binary data it may contain. |
R David Murray | 0b6f6c8 | 2012-05-25 18:42:14 -0400 | [diff] [blame^] | 309 | |
| 310 | |
| 311 | .. note:: |
| 312 | |
| 313 | The remainder of the classes documented below are included in the standard |
| 314 | library on a :term:`provisional basis <provisional package>`. Backwards |
| 315 | incompatible changes (up to and including removal of the feature) may occur |
| 316 | if deemed necessary by the core developers. |
| 317 | |
| 318 | |
| 319 | .. class:: EmailPolicy(**kw) |
| 320 | |
| 321 | This concrete :class:`Policy` provides behavior that is intended to be fully |
| 322 | compliant with the current email RFCs. These include (but are not limited |
| 323 | to) :rfc:`5322`, :rfc:`2047`, and the current MIME RFCs. |
| 324 | |
| 325 | This policy adds new header parsing and folding algorithms. Instead of |
| 326 | simple strings, headers are custom objects with custom attributes depending |
| 327 | on the type of the field. The parsing and folding algorithm fully implement |
| 328 | :rfc:`2047` and :rfc:`5322`. |
| 329 | |
| 330 | In addition to the settable attributes listed above that apply to all |
| 331 | policies, this policy adds the following additional attributes: |
| 332 | |
| 333 | .. attribute:: refold_source |
| 334 | |
| 335 | If the value for a header in the ``Message`` object originated from a |
| 336 | :mod:`~email.parser` (as opposed to being set by a program), this |
| 337 | attribute indicates whether or not a generator should refold that value |
| 338 | when transforming the message back into stream form. The possible values |
| 339 | are: |
| 340 | |
| 341 | ======== =============================================================== |
| 342 | ``none`` all source values use original folding |
| 343 | |
| 344 | ``long`` source values that have any line that is longer than |
| 345 | ``max_line_length`` will be refolded |
| 346 | |
| 347 | ``all`` all values are refolded. |
| 348 | ======== =============================================================== |
| 349 | |
| 350 | The default is ``long``. |
| 351 | |
| 352 | .. attribute:: header_factory |
| 353 | |
| 354 | A callable that takes two arguments, ``name`` and ``value``, where |
| 355 | ``name`` is a header field name and ``value`` is an unfolded header field |
| 356 | value, and returns a string-like object that represents that header. A |
| 357 | default ``header_factory`` is provided that understands some of the |
| 358 | :RFC:`5322` header field types. (Currently address fields and date |
| 359 | fields have special treatment, while all other fields are treated as |
| 360 | unstructured. This list will be completed before the extension is marked |
| 361 | stable.) |
| 362 | |
| 363 | The class provides the following concrete implementations of the abstract |
| 364 | methods of :class:`Policy`: |
| 365 | |
| 366 | .. method:: header_source_parse(sourcelines) |
| 367 | |
| 368 | The implementation of this method is the same as that for the |
| 369 | :class:`Compat32` policy. |
| 370 | |
| 371 | .. method:: header_store_parse(name, value) |
| 372 | |
| 373 | The name is returned unchanged. If the input value has a ``name`` |
| 374 | attribute and it matches *name* ignoring case, the value is returned |
| 375 | unchanged. Otherwise the *name* and *value* are passed to |
| 376 | ``header_factory``, and the resulting custom header object is returned as |
| 377 | the value. In this case a ``ValueError`` is raised if the input value |
| 378 | contains CR or LF characters. |
| 379 | |
| 380 | .. method:: header_fetch_parse(name, value) |
| 381 | |
| 382 | If the value has a ``name`` attribute, it is returned to unmodified. |
| 383 | Otherwise the *name*, and the *value* with any CR or LF characters |
| 384 | removed, are passed to the ``header_factory``, and the resulting custom |
| 385 | header object is returned. Any surrogateescaped bytes get turned into |
| 386 | the unicode unknown-character glyph. |
| 387 | |
| 388 | .. method:: fold(name, value) |
| 389 | |
| 390 | Header folding is controlled by the :attr:`refold_source` policy setting. |
| 391 | A value is considered to be a 'source value' if and only if it does not |
| 392 | have a ``name`` attribute (having a ``name`` attribute means it is a |
| 393 | header object of some sort). If a source value needs to be refolded |
| 394 | according to the policy, it is converted into a custom header object by |
| 395 | passing the *name* and the *value* with any CR and LF characters removed |
| 396 | to the ``header_factory``. Folding of a custom header object is done by |
| 397 | calling its ``fold`` method with the current policy. |
| 398 | |
| 399 | Source values are split into lines using :meth:`~str.splitlines`. If |
| 400 | the value is not to be refolded, the lines are rejoined using the |
| 401 | ``linesep`` from the policy and returned. The exception is lines |
| 402 | containing non-ascii binary data. In that case the value is refolded |
| 403 | regardless of the ``refold_source`` setting, which causes the binary data |
| 404 | to be CTE encoded using the ``unknown-8bit`` charset. |
| 405 | |
| 406 | .. method:: fold_binary(name, value) |
| 407 | |
| 408 | The same as :meth:`fold` if :attr:`cte_type` is ``7bit``, except that |
| 409 | the returned value is bytes. |
| 410 | |
| 411 | If :attr:`cte_type` is ``8bit``, non-ASCII binary data is converted back |
| 412 | into bytes. Headers with binary data are not refolded, regardless of the |
| 413 | ``refold_header`` setting, since there is no way to know whether the |
| 414 | binary data consists of single byte characters or multibyte characters. |
| 415 | |
| 416 | The following instances of :class:`EmailPolicy` provide defaults suitable for |
| 417 | specific application domains. Note that in the future the behavior of these |
| 418 | instances (in particular the ``HTTP` instance) may be adjusted to conform even |
| 419 | more closely to the RFCs relevant to their domains. |
| 420 | |
| 421 | .. data:: default |
| 422 | |
| 423 | An instance of ``EmailPolicy`` with all defaults unchanged. This policy |
| 424 | uses the standard Python ``\n`` line endings rather than the RFC-correct |
| 425 | ``\r\n``. |
| 426 | |
| 427 | .. data:: SMTP |
| 428 | |
| 429 | Suitable for serializing messages in conformance with the email RFCs. |
| 430 | Like ``default``, but with ``linesep`` set to ``\r\n``, which is RFC |
| 431 | compliant. |
| 432 | |
| 433 | .. data:: HTTP |
| 434 | |
| 435 | Suitable for serializing headers with for use in HTTP traffic. Like |
| 436 | ``SMTP`` except that ``max_line_length`` is set to ``None`` (unlimited). |
| 437 | |
| 438 | .. data:: strict |
| 439 | |
| 440 | Convenience instance. The same as ``default`` except that |
| 441 | ``raise_on_defect`` is set to ``True``. This allows any policy to be made |
| 442 | strict by writing:: |
| 443 | |
| 444 | somepolicy + policy.strict |
| 445 | |
| 446 | With all of these :class:`EmailPolicies <.EmailPolicy>`, the effective API of |
| 447 | the email package is changed from the Python 3.2 API in the following ways: |
| 448 | |
| 449 | * Setting a header on a :class:`~email.message.Message` results in that |
| 450 | header being parsed and a custom header object created. |
| 451 | |
| 452 | * Fetching a header value from a :class:`~email.message.Message` results |
| 453 | in that header being parsed and a custom header object created and |
| 454 | returned. |
| 455 | |
| 456 | * Any custom header object, or any header that is refolded due to the |
| 457 | policy settings, is folded using an algorithm that fully implements the |
| 458 | RFC folding algorithms, including knowing where encoded words are required |
| 459 | and allowed. |
| 460 | |
| 461 | From the application view, this means that any header obtained through the |
| 462 | :class:`~email.message.Message` is a custom header object with custom |
| 463 | attributes, whose string value is the fully decoded unicode value of the |
| 464 | header. Likewise, a header may be assigned a new value, or a new header |
| 465 | created, using a unicode string, and the policy will take care of converting |
| 466 | the unicode string into the correct RFC encoded form. |
| 467 | |
| 468 | The custom header objects and their attributes are described below. All custom |
| 469 | header objects are string subclasses, and their string value is the fully |
| 470 | decoded value of the header field (the part of the field after the ``:``) |
| 471 | |
| 472 | |
| 473 | .. class:: BaseHeader |
| 474 | |
| 475 | This is the base class for all custom header objects. It provides the |
| 476 | following attributes: |
| 477 | |
| 478 | .. attribute:: name |
| 479 | |
| 480 | The header field name (the portion of the field before the ':'). |
| 481 | |
| 482 | .. attribute:: defects |
| 483 | |
| 484 | A possibly empty list of :class:`~email.errors.MessageDefect` objects |
| 485 | that record any RFC violations found while parsing the header field. |
| 486 | |
| 487 | .. method:: fold(*, policy) |
| 488 | |
| 489 | Return a string containing :attr:`~email.policy.Policy.linesep` |
| 490 | characters as required to correctly fold the header according |
| 491 | to *policy*. A :attr:`~email.policy.Policy.cte_type` of |
| 492 | ``8bit`` will be treated as if it were ``7bit``, since strings |
| 493 | may not contain binary data. |
| 494 | |
| 495 | |
| 496 | .. class:: UnstructuredHeader |
| 497 | |
| 498 | The class used for any header that does not have a more specific |
| 499 | type. (The :mailheader:`Subject` header is an example of an |
| 500 | unstructured header.) It does not have any additional attributes. |
| 501 | |
| 502 | |
| 503 | .. class:: DateHeader |
| 504 | |
| 505 | The value of this type of header is a single date and time value. The |
| 506 | primary example of this type of header is the :mailheader:`Date` header. |
| 507 | |
| 508 | .. attribute:: datetime |
| 509 | |
| 510 | A :class:`~datetime.datetime` encoding the date and time from the |
| 511 | header value. |
| 512 | |
| 513 | The ``datetime`` will be a naive ``datetime`` if the value either does |
| 514 | not have a specified timezone (which would be a violation of the RFC) or |
| 515 | if the timezone is specified as ``-0000``. This timezone value indicates |
| 516 | that the date and time is to be considered to be in UTC, but with no |
| 517 | indication of the local timezone in which it was generated. (This |
| 518 | contrasts to ``+0000``, which indicates a date and time that really is in |
| 519 | the UTC ``0000`` timezone.) |
| 520 | |
| 521 | If the header value contains a valid timezone that is not ``-0000``, the |
| 522 | ``datetime`` will be an aware ``datetime`` having a |
| 523 | :class:`~datetime.tzinfo` set to the :class:`~datetime.timezone` |
| 524 | indicated by the header value. |
| 525 | |
| 526 | A ``datetime`` may also be assigned to a :mailheader:`Date` type header. |
| 527 | The resulting string value will use a timezone of ``-0000`` if the |
| 528 | ``datetime`` is naive, and the appropriate UTC offset if the ``datetime`` is |
| 529 | aware. |
| 530 | |
| 531 | |
| 532 | .. class:: AddressHeader |
| 533 | |
| 534 | This class is used for all headers that can contain addresses, whether they |
| 535 | are supposed to be singleton addresses or a list. |
| 536 | |
| 537 | .. attribute:: addresses |
| 538 | |
| 539 | A list of :class:`.Address` objects listing all of the addresses that |
| 540 | could be parsed out of the field value. |
| 541 | |
| 542 | .. attribute:: groups |
| 543 | |
| 544 | A list of :class:`.Group` objects. Every address in :attr:`.addresses` |
| 545 | appears in one of the group objects in the tuple. Addresses that are not |
| 546 | syntactically part of a group are represented by ``Group`` objects whose |
| 547 | ``name`` is ``None``. |
| 548 | |
| 549 | In addition to addresses in string form, any combination of |
| 550 | :class:`.Address` and :class:`.Group` objects, singly or in a list, may be |
| 551 | assigned to an address header. |
| 552 | |
| 553 | |
| 554 | .. class:: Address(display_name='', username='', domain='', addr_spec=None): |
| 555 | |
| 556 | The class used to represent an email address. The general form of an |
| 557 | address is:: |
| 558 | |
| 559 | [display_name] <username@domain> |
| 560 | |
| 561 | or:: |
| 562 | |
| 563 | username@domain |
| 564 | |
| 565 | where each part must conform to specific syntax rules spelled out in |
| 566 | :rfc:`5322`. |
| 567 | |
| 568 | As a convenience *addr_spec* can be specified instead of *username* and |
| 569 | *domain*, in which case *username* and *domain* will be parsed from the |
| 570 | *addr_spec*. An *addr_spec* must be a properly RFC quoted string; if it is |
| 571 | not ``Address`` will raise an error. Unicode characters are allowed and |
| 572 | will be property encoded when serialized. However, per the RFCs, unicode is |
| 573 | *not* allowed in the username portion of the address. |
| 574 | |
| 575 | .. attribute:: display_name |
| 576 | |
| 577 | The display name portion of the address, if any, with all quoting |
| 578 | removed. If the address does not have a display name, this attribute |
| 579 | will be an empty string. |
| 580 | |
| 581 | .. attribute:: username |
| 582 | |
| 583 | The ``username`` portion of the address, with all quoting removed. |
| 584 | |
| 585 | .. attribute:: domain |
| 586 | |
| 587 | The ``domain`` portion of the address. |
| 588 | |
| 589 | .. attribute:: addr_spec |
| 590 | |
| 591 | The ``username@domain`` portion of the address, correctly quoted |
| 592 | for use as a bare address (the second form shown above). This |
| 593 | attribute is not mutable. |
| 594 | |
| 595 | .. method:: __str__() |
| 596 | |
| 597 | The ``str`` value of the object is the address quoted according to |
| 598 | :rfc:`5322` rules, but with no Content Transfer Encoding of any non-ASCII |
| 599 | characters. |
| 600 | |
| 601 | |
| 602 | .. class:: Group(display_name=None, addresses=None) |
| 603 | |
| 604 | The class used to represent an address group. The general form of an |
| 605 | address group is:: |
| 606 | |
| 607 | display_name: [address-list]; |
| 608 | |
| 609 | As a convenience for processing lists of addresses that consist of a mixture |
| 610 | of groups and single addresses, a ``Group`` may also be used to represent |
| 611 | single addresses that are not part of a group by setting *display_name* to |
| 612 | ``None`` and providing a list of the single address as *addresses*. |
| 613 | |
| 614 | .. attribute:: display_name |
| 615 | |
| 616 | The ``display_name`` of the group. If it is ``None`` and there is |
| 617 | exactly one ``Address`` in ``addresses``, then the ``Group`` represents a |
| 618 | single address that is not in a group. |
| 619 | |
| 620 | .. attribute:: addresses |
| 621 | |
| 622 | A possibly empty tuple of :class:`.Address` objects representing the |
| 623 | addresses in the group. |
| 624 | |
| 625 | .. method:: __str__() |
| 626 | |
| 627 | The ``str`` value of a ``Group`` is formatted according to :rfc:`5322`, |
| 628 | but with no Content Transfer Encoding of any non-ASCII characters. If |
| 629 | ``display_name`` is none and there is a single ``Address`` in the |
| 630 | ``addresses` list, the ``str`` value will be the same as the ``str`` of |
| 631 | that single ``Address``. |