Debian Codegraph @

Doc/library/email.headerregistry.rst

raw
1 :mod:`!email.headerregistry`: Custom Header Objects
2 ---------------------------------------------------
3
4 .. module:: email.headerregistry
5 :synopsis: Automatic Parsing of headers based on the field name
6
7 .. moduleauthor:: R. David Murray <[email protected]>
8 .. sectionauthor:: R. David Murray <[email protected]>
9
10 **Source code:** :source:`Lib/email/headerregistry.py`
11
12 --------------
13
14 .. versionadded:: 3.6 [1]_
15
16 Headers are represented by customized subclasses of :class:`str`. The
17 particular class used to represent a given header is determined by the
18 :attr:`~email.policy.EmailPolicy.header_factory` of the :mod:`~email.policy` in
19 effect when the headers are created. This section documents the particular
20 ``header_factory`` implemented by the email package for handling :RFC:`5322`
21 compliant email messages, which not only provides customized header objects for
22 various header types, but also provides an extension mechanism for applications
23 to add their own custom header types.
24
25 When using any of the policy objects derived from
26 :data:`~email.policy.EmailPolicy`, all headers are produced by
27 :class:`.HeaderRegistry` and have :class:`.BaseHeader` as their last base
28 class. Each header class has an additional base class that is determined by
29 the type of the header. For example, many headers have the class
30 :class:`.UnstructuredHeader` as their other base class. The specialized second
31 class for a header is determined by the name of the header, using a lookup
32 table stored in the :class:`.HeaderRegistry`. All of this is managed
33 transparently for the typical application program, but interfaces are provided
34 for modifying the default behavior for use by more complex applications.
35
36 The sections below first document the header base classes and their attributes,
37 followed by the API for modifying the behavior of :class:`.HeaderRegistry`, and
38 finally the support classes used to represent the data parsed from structured
39 headers.
40
41
42 .. class:: BaseHeader(name, value)
43
44 *name* and *value* are passed to ``BaseHeader`` from the
45 :attr:`~email.policy.EmailPolicy.header_factory` call. The string value of
46 any header object is the *value* fully decoded to unicode.
47
48 This base class defines the following read-only properties:
49
50
51 .. attribute:: name
52
53 The name of the header (the portion of the field before the ':'). This
54 is exactly the value passed in the
55 :attr:`~email.policy.EmailPolicy.header_factory` call for *name*; that
56 is, case is preserved.
57
58
59 .. attribute:: defects
60
61 A tuple of :exc:`~email.errors.HeaderDefect` instances reporting any
62 RFC compliance problems found during parsing. The email package tries to
63 be complete about detecting compliance issues. See the :mod:`~email.errors`
64 module for a discussion of the types of defects that may be reported.
65
66
67 .. attribute:: max_count
68
69 The maximum number of headers of this type that can have the same
70 ``name``. A value of ``None`` means unlimited. The ``BaseHeader`` value
71 for this attribute is ``None``; it is expected that specialized header
72 classes will override this value as needed.
73
74 ``BaseHeader`` also provides the following method, which is called by the
75 email library code and should not in general be called by application
76 programs:
77
78 .. method:: fold(*, policy)
79
80 Return a string containing :attr:`~email.policy.Policy.linesep`
81 characters as required to correctly fold the header according to
82 *policy*. A :attr:`~email.policy.Policy.cte_type` of ``8bit`` will be
83 treated as if it were ``7bit``, since headers may not contain arbitrary
84 binary data. If :attr:`~email.policy.EmailPolicy.utf8` is ``False``,
85 non-ASCII data will be :rfc:`2047` encoded.
86
87
88 ``BaseHeader`` by itself cannot be used to create a header object. It
89 defines a protocol that each specialized header cooperates with in order to
90 produce the header object. Specifically, ``BaseHeader`` requires that
91 the specialized class provide a :func:`classmethod` named ``parse``. This
92 method is called as follows::
93
94 parse(string, kwds)
95
96 ``kwds`` is a dictionary containing one pre-initialized key, ``defects``.
97 ``defects`` is an empty list. The parse method should append any detected
98 defects to this list. On return, the ``kwds`` dictionary *must* contain
99 values for at least the keys ``decoded``, ``defects`` and ``parse_tree``.
100 ``decoded`` should be the string value for the header (that is, the header
101 value fully decoded to unicode). ``parse_tree`` is set to the parse tree obtained
102 from parsing the header. The parse method should assume that *string* may
103 contain content-transfer-encoded parts, but should correctly handle all valid
104 unicode characters as well so that it can parse un-encoded header values.
105
106 ``BaseHeader``'s ``__new__`` then creates the header instance, and calls its
107 ``init`` method. The specialized class only needs to provide an ``init``
108 method if it wishes to set additional attributes beyond those provided by
109 ``BaseHeader`` itself. Such an ``init`` method should look like this::
110
111 def init(self, /, *args, **kw):
112 self._myattr = kw.pop('myattr')
113 super().init(*args, **kw)
114
115 That is, anything extra that the specialized class puts in to the ``kwds``
116 dictionary should be removed and handled, and the remaining contents of
117 ``kw`` (and ``args``) passed to the ``BaseHeader`` ``init`` method.
118
119
120 .. class:: UnstructuredHeader
121
122 An "unstructured" header is the default type of header in :rfc:`5322`.
123 Any header that does not have a specified syntax is treated as
124 unstructured. The classic example of an unstructured header is the
125 :mailheader:`Subject` header.
126
127 In :rfc:`5322`, an unstructured header is a run of arbitrary text in the
128 ASCII character set. :rfc:`2047`, however, has an :rfc:`5322` compatible
129 mechanism for encoding non-ASCII text as ASCII characters within a header
130 value. When a *value* containing encoded words is passed to the
131 constructor, the ``UnstructuredHeader`` parser converts such encoded words
132 into unicode, following the :rfc:`2047` rules for unstructured text. The
133 parser uses heuristics to attempt to decode certain non-compliant encoded
134 words. Defects are registered in such cases, as well as defects for issues
135 such as invalid characters within the encoded words or the non-encoded text.
136
137 This header type provides no additional attributes.
138
139
140 .. class:: DateHeader
141
142 :rfc:`5322` specifies a very specific format for dates within email headers.
143 The ``DateHeader`` parser recognizes that date format, as well as
144 recognizing a number of variant forms that are sometimes found "in the
145 wild".
146
147 This header type provides the following additional attributes:
148
149 .. attribute:: datetime
150
151 If the header value can be recognized as a valid date of one form or
152 another, this attribute will contain a :class:`~datetime.datetime`
153 instance representing that date. If the timezone of the input date is
154 specified as ``-0000`` (indicating it is in UTC but contains no
155 information about the source timezone), then :attr:`.datetime` will be a
156 naive :class:`~datetime.datetime`. If a specific timezone offset is
157 found (including ``+0000``), then :attr:`.datetime` will contain an aware
158 ``datetime`` that uses :class:`datetime.timezone` to record the timezone
159 offset.
160
161 The ``decoded`` value of the header is determined by formatting the
162 ``datetime`` according to the :rfc:`5322` rules; that is, it is set to::
163
164 email.utils.format_datetime(self.datetime)
165
166 When creating a ``DateHeader``, *value* may be
167 :class:`~datetime.datetime` instance. This means, for example, that
168 the following code is valid and does what one would expect::
169
170 msg['Date'] = datetime(2011, 7, 15, 21)
171
172 Because this is a naive ``datetime`` it will be interpreted as a UTC
173 timestamp, and the resulting value will have a timezone of ``-0000``. Much
174 more useful is to use the :func:`~email.utils.localtime` function from the
175 :mod:`~email.utils` module::
176
177 msg['Date'] = utils.localtime()
178
179 This example sets the date header to the current time and date using
180 the current timezone offset.
181
182
183 .. class:: AddressHeader
184
185 Address headers are one of the most complex structured header types.
186 The ``AddressHeader`` class provides a generic interface to any address
187 header.
188
189 This header type provides the following additional attributes:
190
191
192 .. attribute:: groups
193
194 A tuple of :class:`.Group` objects encoding the
195 addresses and groups found in the header value. Addresses that are
196 not part of a group are represented in this list as single-address
197 ``Groups`` whose :attr:`~.Group.display_name` is ``None``.
198
199
200 .. attribute:: addresses
201
202 A tuple of :class:`.Address` objects encoding all
203 of the individual addresses from the header value. If the header value
204 contains any groups, the individual addresses from the group are included
205 in the list at the point where the group occurs in the value (that is,
206 the list of addresses is "flattened" into a one dimensional list).
207
208 The ``decoded`` value of the header will have all encoded words decoded to
209 unicode. :class:`~encodings.idna` encoded domain names are also decoded to
210 unicode. The ``decoded`` value is set by :ref:`joining <meth-str-join>` the
211 :class:`str` value of the elements of the ``groups`` attribute with ``',
212 '``.
213
214 A list of :class:`.Address` and :class:`.Group` objects in any combination
215 may be used to set the value of an address header. ``Group`` objects whose
216 ``display_name`` is ``None`` will be interpreted as single addresses, which
217 allows an address list to be copied with groups intact by using the list
218 obtained from the ``groups`` attribute of the source header.
219
220
221 .. class:: SingleAddressHeader
222
223 A subclass of :class:`.AddressHeader` that adds one
224 additional attribute:
225
226
227 .. attribute:: address
228
229 The single address encoded by the header value. If the header value
230 actually contains more than one address (which would be a violation of
231 the RFC under the default :mod:`~email.policy`), accessing this attribute
232 will result in a :exc:`ValueError`.
233
234
235 Many of the above classes also have a ``Unique`` variant (for example,
236 ``UniqueUnstructuredHeader``). The only difference is that in the ``Unique``
237 variant, :attr:`~.BaseHeader.max_count` is set to 1.
238
239
240 .. class:: MIMEVersionHeader
241
242 There is really only one valid value for the :mailheader:`MIME-Version`
243 header, and that is ``1.0``. For future proofing, this header class
244 supports other valid version numbers. If a version number has a valid value
245 per :rfc:`2045`, then the header object will have non-``None`` values for
246 the following attributes:
247
248 .. attribute:: version
249
250 The version number as a string, with any whitespace and/or comments
251 removed.
252
253 .. attribute:: major
254
255 The major version number as an integer
256
257 .. attribute:: minor
258
259 The minor version number as an integer
260
261
262 .. class:: ParameterizedMIMEHeader
263
264 MIME headers all start with the prefix 'Content-'. Each specific header has
265 a certain value, described under the class for that header. Some can
266 also take a list of supplemental parameters, which have a common format.
267 This class serves as a base for all the MIME headers that take parameters.
268
269 .. attribute:: params
270
271 A dictionary mapping parameter names to parameter values.
272
273
274 .. class:: ContentTypeHeader
275
276 A :class:`ParameterizedMIMEHeader` class that handles the
277 :mailheader:`Content-Type` header.
278
279 .. attribute:: content_type
280
281 The content type string, in the form ``maintype/subtype``.
282
283 .. attribute:: maintype
284
285 .. attribute:: subtype
286
287
288 .. class:: ContentDispositionHeader
289
290 A :class:`ParameterizedMIMEHeader` class that handles the
291 :mailheader:`Content-Disposition` header.
292
293 .. attribute:: content_disposition
294
295 ``inline`` and ``attachment`` are the only valid values in common use.
296
297
298 .. class:: ContentTransferEncodingHeader
299
300 Handles the :mailheader:`Content-Transfer-Encoding` header.
301
302 .. attribute:: cte
303
304 Valid values are ``7bit``, ``8bit``, ``base64``, and
305 ``quoted-printable``. See :rfc:`2045` for more information.
306
307
308
309 .. class:: HeaderRegistry(base_class=BaseHeader, \
310 default_class=UnstructuredHeader, \
311 use_default_map=True)
312
313 This is the factory used by :class:`~email.policy.EmailPolicy` by default.
314 ``HeaderRegistry`` builds the class used to create a header instance
315 dynamically, using *base_class* and a specialized class retrieved from a
316 registry that it holds. When a given header name does not appear in the
317 registry, the class specified by *default_class* is used as the specialized
318 class. When *use_default_map* is ``True`` (the default), the standard
319 mapping of header names to classes is copied in to the registry during
320 initialization. *base_class* is always the last class in the generated
321 class's :class:`~type.__bases__` list.
322
323 The default mappings are:
324
325 :subject: UniqueUnstructuredHeader
326 :date: UniqueDateHeader
327 :resent-date: DateHeader
328 :orig-date: UniqueDateHeader
329 :sender: UniqueSingleAddressHeader
330 :resent-sender: SingleAddressHeader
331 :to: UniqueAddressHeader
332 :resent-to: AddressHeader
333 :cc: UniqueAddressHeader
334 :resent-cc: AddressHeader
335 :bcc: UniqueAddressHeader
336 :resent-bcc: AddressHeader
337 :from: UniqueAddressHeader
338 :resent-from: AddressHeader
339 :reply-to: UniqueAddressHeader
340 :mime-version: MIMEVersionHeader
341 :content-type: ContentTypeHeader
342 :content-disposition: ContentDispositionHeader
343 :content-transfer-encoding: ContentTransferEncodingHeader
344 :message-id: MessageIDHeader
345
346 ``HeaderRegistry`` has the following methods:
347
348
349 .. method:: map_to_type(self, name, cls)
350
351 *name* is the name of the header to be mapped. It will be converted to
352 lower case in the registry. *cls* is the specialized class to be used,
353 along with *base_class*, to create the class used to instantiate headers
354 that match *name*.
355
356
357 .. method:: __getitem__(name)
358
359 Construct and return a class to handle creating a *name* header.
360
361
362 .. method:: __call__(name, value)
363
364 Retrieves the specialized header associated with *name* from the
365 registry (using *default_class* if *name* does not appear in the
366 registry) and composes it with *base_class* to produce a class,
367 calls the constructed class's constructor, passing it the same
368 argument list, and finally returns the class instance created thereby.
369
370
371 The following classes are the classes used to represent data parsed from
372 structured headers and can, in general, be used by an application program to
373 construct structured values to assign to specific headers.
374
375
376 .. class:: Address(display_name='', username='', domain='', addr_spec=None)
377
378 The class used to represent an email address. The general form of an
379 address is::
380
381 [display_name] <username@domain>
382
383 or::
384
385 username@domain
386
387 where each part must conform to specific syntax rules spelled out in
388 :rfc:`5322`.
389
390 As a convenience *addr_spec* can be specified instead of *username* and
391 *domain*, in which case *username* and *domain* will be parsed from the
392 *addr_spec*. An *addr_spec* must be a properly RFC quoted string; if it is
393 not ``Address`` will raise an error. Unicode characters are allowed and
394 will be property encoded when serialized. However, per the RFCs, unicode is
395 *not* allowed in the username portion of the address.
396
397 .. attribute:: display_name
398
399 The display name portion of the address, if any, with all quoting
400 removed. If the address does not have a display name, this attribute
401 will be an empty string.
402
403 .. attribute:: username
404
405 The ``username`` portion of the address, with all quoting removed.
406
407 .. attribute:: domain
408
409 The ``domain`` portion of the address.
410
411 .. attribute:: addr_spec
412
413 The ``username@domain`` portion of the address, correctly quoted
414 for use as a bare address (the second form shown above). This
415 attribute is not mutable.
416
417 .. method:: __str__()
418
419 The ``str`` value of the object is the address quoted according to
420 :rfc:`5322` rules, but with no Content Transfer Encoding of any non-ASCII
421 characters.
422
423 To support SMTP (:rfc:`5321`), ``Address`` handles one special case: if
424 ``username`` and ``domain`` are both the empty string (or ``None``), then
425 the string value of the ``Address`` is ``<>``.
426
427
428 .. class:: Group(display_name=None, addresses=None)
429
430 The class used to represent an address group. The general form of an
431 address group is::
432
433 display_name: [address-list];
434
435 As a convenience for processing lists of addresses that consist of a mixture
436 of groups and single addresses, a ``Group`` may also be used to represent
437 single addresses that are not part of a group by setting *display_name* to
438 ``None`` and providing a list of the single address as *addresses*.
439
440 .. attribute:: display_name
441
442 The ``display_name`` of the group. If it is ``None`` and there is
443 exactly one ``Address`` in ``addresses``, then the ``Group`` represents a
444 single address that is not in a group.
445
446 .. attribute:: addresses
447
448 A possibly empty tuple of :class:`.Address` objects representing the
449 addresses in the group.
450
451 .. method:: __str__()
452
453 The ``str`` value of a ``Group`` is formatted according to :rfc:`5322`,
454 but with no Content Transfer Encoding of any non-ASCII characters. If
455 ``display_name`` is none and there is a single ``Address`` in the
456 ``addresses`` list, the ``str`` value will be the same as the ``str`` of
457 that single ``Address``.
458
459
460 .. rubric:: Footnotes
461
462 .. [1] Originally added in 3.3 as a :term:`provisional module <provisional
463 package>`