Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(6)

Side by Side Diff: Doc/library/email.policy.rst

Issue 10839: email module should not allow some header field repetitions
Patch Set: Created 7 years, 10 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | Lib/email/message.py » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`email.policy`: Policy Objects 1 :mod:`email.policy`: Policy Objects
2 ----------------------------------- 2 -----------------------------------
3 3
4 .. module:: email.policy 4 .. module:: email.policy
5 :synopsis: Controlling the parsing and generating of messages 5 :synopsis: Controlling the parsing and generating of messages
6 6
7 .. moduleauthor:: R. David Murray <rdmurray@bitdance.com> 7 .. moduleauthor:: R. David Murray <rdmurray@bitdance.com>
8 .. sectionauthor:: R. David Murray <rdmurray@bitdance.com> 8 .. sectionauthor:: R. David Murray <rdmurray@bitdance.com>
9 9
10 .. versionadded:: 3.3 10 .. versionadded:: 3.3
(...skipping 177 matching lines...) Expand 10 before | Expand all | Expand 10 after
188 188
189 Register a *defect* on *obj*. In the email package, *defect* will always 189 Register a *defect* on *obj*. In the email package, *defect* will always
190 be a subclass of :class:`~email.errors.Defect`. 190 be a subclass of :class:`~email.errors.Defect`.
191 191
192 The default implementation calls the ``append`` method of the ``defects`` 192 The default implementation calls the ``append`` method of the ``defects``
193 attribute of *obj*. When the email package calls :attr:`handle_defect`, 193 attribute of *obj*. When the email package calls :attr:`handle_defect`,
194 *obj* will normally have a ``defects`` attribute that has an ``append`` 194 *obj* will normally have a ``defects`` attribute that has an ``append``
195 method. Custom object types used with the email package (for example, 195 method. Custom object types used with the email package (for example,
196 custom ``Message`` objects) should also provide such an attribute, 196 custom ``Message`` objects) should also provide such an attribute,
197 otherwise defects in parsed messages will raise unexpected errors. 197 otherwise defects in parsed messages will raise unexpected errors.
198
199 .. method:: header_max_count(name)
200
201 Return the maximum allowed number of headers named *name*.
202
203 Called when a header is added to a :class:`~email.message.Message`
204 object. If the returned value is not ``0`` or ``None``, and there are
205 already a number of headers with the name *name* equal to the value
206 returned, a :exc:`ValueError` is raised.
207
208 Because the default behavior of ``Message.__setitem__`` is to append the
209 value to the list of headers, it is easy to create duplicate headers
210 without realizing it. This method allows certain headers to be limited
211 in the number of instances of that header that may be added to a
212 ``Message`` programmatically. (The limit is not observed by the parser,
213 which will faithfully produce as many headers as exist in the message
214 being parsed.)
215
216 The default implementation returns ``None`` for all header names.
198 217
199 .. method:: header_source_parse(sourcelines) 218 .. method:: header_source_parse(sourcelines)
200 219
201 The email package calls this method with a list of strings, each string 220 The email package calls this method with a list of strings, each string
202 ending with the line separation characters found in the source being 221 ending with the line separation characters found in the source being
203 parsed. The first line includes the field header name and separator. 222 parsed. The first line includes the field header name and separator.
204 All whitespace in the source is preserved. The method should return the 223 All whitespace in the source is preserved. The method should return the
205 ``(name, value)`` tuple that is to be stored in the ``Message`` to 224 ``(name, value)`` tuple that is to be stored in the ``Message`` to
206 represent the parsed header. 225 represent the parsed header.
207 226
(...skipping 150 matching lines...) Expand 10 before | Expand all | Expand 10 after
358 ``name`` is a header field name and ``value`` is an unfolded header field 377 ``name`` is a header field name and ``value`` is an unfolded header field
359 value, and returns a string subclass that represents that header. A 378 value, and returns a string subclass that represents that header. A
360 default ``header_factory`` (see :mod:`~email.headerregistry`) is provided 379 default ``header_factory`` (see :mod:`~email.headerregistry`) is provided
361 that understands some of the :RFC:`5322` header field types. (Currently 380 that understands some of the :RFC:`5322` header field types. (Currently
362 address fields and date fields have special treatment, while all other 381 address fields and date fields have special treatment, while all other
363 fields are treated as unstructured. This list will be completed before 382 fields are treated as unstructured. This list will be completed before
364 the extension is marked stable.) 383 the extension is marked stable.)
365 384
366 The class provides the following concrete implementations of the abstract 385 The class provides the following concrete implementations of the abstract
367 methods of :class:`Policy`: 386 methods of :class:`Policy`:
387
388 .. method:: header_max_count(name)
389
390 Returns the value of the
391 :attr:`~email.headerregistry.BaseHeader.max_count` attribute of the
392 specialized class used to represent the header with the given name.
368 393
369 .. method:: header_source_parse(sourcelines) 394 .. method:: header_source_parse(sourcelines)
370 395
371 The implementation of this method is the same as that for the 396 The implementation of this method is the same as that for the
372 :class:`Compat32` policy. 397 :class:`Compat32` policy.
373 398
374 .. method:: header_store_parse(name, value) 399 .. method:: header_store_parse(name, value)
375 400
376 The name is returned unchanged. If the input value has a ``name`` 401 The name is returned unchanged. If the input value has a ``name``
377 attribute and it matches *name* ignoring case, the value is returned 402 attribute and it matches *name* ignoring case, the value is returned
(...skipping 85 matching lines...) Expand 10 before | Expand all | Expand 10 after
463 488
464 From the application view, this means that any header obtained through the 489 From the application view, this means that any header obtained through the
465 :class:`~email.message.Message` is a custom header object with custom 490 :class:`~email.message.Message` is a custom header object with custom
466 attributes, whose string value is the fully decoded unicode value of the 491 attributes, whose string value is the fully decoded unicode value of the
467 header. Likewise, a header may be assigned a new value, or a new header 492 header. Likewise, a header may be assigned a new value, or a new header
468 created, using a unicode string, and the policy will take care of converting 493 created, using a unicode string, and the policy will take care of converting
469 the unicode string into the correct RFC encoded form. 494 the unicode string into the correct RFC encoded form.
470 495
471 The custom header objects and their attributes are described in 496 The custom header objects and their attributes are described in
472 :mod:`~email.headerregistry`. 497 :mod:`~email.headerregistry`.
OLDNEW
« no previous file with comments | « no previous file | Lib/email/message.py » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+