X Tutup
Skip to content

Commit 3da240f

Browse files
bitdancerbitdancer
committed
python#18891: Complete new provisional email API.
This adds EmailMessage and, MIMEPart subclasses of Message with new API methods, and a ContentManager class used by the new methods. Also a new policy setting, content_manager. Patch was reviewed by Stephen J. Turnbull and Serhiy Storchaka, and reflects their feedback. I will ideally add some examples of using the new API to the documentation before the final release.
1 parent 1a16288 commit 3da240f

File tree

15 files changed

+2539
-26
lines changed

15 files changed

+2539
-26
lines changed

‎Doc/library/email.contentmanager.rst‎

Lines changed: 427 additions & 0 deletions
Large diffs are not rendered by default.

‎Doc/library/email.message.rst‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -33,10 +33,11 @@ Here are the methods of the :class:`Message` class:
3333

3434
.. class:: Message(policy=compat32)
3535

36-
The *policy* argument determiens the :mod:`~email.policy` that will be used
37-
to update the message model. The default value, :class:`compat32
38-
<email.policy.Compat32>` maintains backward compatibility with the
39-
Python 3.2 version of the email package. For more information see the
36+
If *policy* is specified (it must be an instance of a :mod:`~email.policy`
37+
class) use the rules it specifies to udpate and serialize the representation
38+
of the message. If *policy* is not set, use the :class`compat32
39+
<email.policy.Compat32>` policy, which maintains backward compatibility with
40+
the Python 3.2 version of the email package. For more information see the
4041
:mod:`~email.policy` documentation.
4142

4243
.. versionchanged:: 3.3 The *policy* keyword argument was added.
@@ -465,7 +466,8 @@ Here are the methods of the :class:`Message` class:
465466
to ``False``.
466467

467468

468-
.. method:: set_param(param, value, header='Content-Type', requote=True, charset=None, language='')
469+
.. method:: set_param(param, value, header='Content-Type', requote=True,
470+
charset=None, language='', replace=False)
469471

470472
Set a parameter in the :mailheader:`Content-Type` header. If the
471473
parameter already exists in the header, its value will be replaced with
@@ -482,6 +484,12 @@ Here are the methods of the :class:`Message` class:
482484
language, defaulting to the empty string. Both *charset* and *language*
483485
should be strings.
484486

487+
If *replace* is ``False`` (the default) the header is moved to the
488+
end of the list of headers. If *replace* is ``True``, the header
489+
will be updated in place.
490+
491+
.. versionchanged: 3.4 ``replace`` keyword was added.
492+
485493
486494
.. method:: del_param(param, header='content-type', requote=True)
487495

‎Doc/library/email.policy.rst‎

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -371,7 +371,7 @@ added matters. To illustrate::
371371
to) :rfc:`5322`, :rfc:`2047`, and the current MIME RFCs.
372372

373373
This policy adds new header parsing and folding algorithms. Instead of
374-
simple strings, headers are custom objects with custom attributes depending
374+
simple strings, headers are ``str`` subclasses with attributes that depend
375375
on the type of the field. The parsing and folding algorithm fully implement
376376
:rfc:`2047` and :rfc:`5322`.
377377

@@ -408,6 +408,20 @@ added matters. To illustrate::
408408
fields are treated as unstructured. This list will be completed before
409409
the extension is marked stable.)
410410

411+
.. attribute:: content_manager
412+
413+
An object with at least two methods: get_content and set_content. When
414+
the :meth:`~email.message.Message.get_content` or
415+
:meth:`~email.message.Message.set_content` method of a
416+
:class:`~email.message.Message` object is called, it calls the
417+
corresponding method of this object, passing it the message object as its
418+
first argument, and any arguments or keywords that were passed to it as
419+
additional arguments. By default ``content_manager`` is set to
420+
:data:`~email.contentmanager.raw_data_manager`.
421+
422+
.. versionadded 3.4
423+
424+
411425
The class provides the following concrete implementations of the abstract
412426
methods of :class:`Policy`:
413427

@@ -427,15 +441,15 @@ added matters. To illustrate::
427441
The name is returned unchanged. If the input value has a ``name``
428442
attribute and it matches *name* ignoring case, the value is returned
429443
unchanged. Otherwise the *name* and *value* are passed to
430-
``header_factory``, and the resulting custom header object is returned as
444+
``header_factory``, and the resulting header object is returned as
431445
the value. In this case a ``ValueError`` is raised if the input value
432446
contains CR or LF characters.
433447

434448
.. method:: header_fetch_parse(name, value)
435449

436450
If the value has a ``name`` attribute, it is returned to unmodified.
437451
Otherwise the *name*, and the *value* with any CR or LF characters
438-
removed, are passed to the ``header_factory``, and the resulting custom
452+
removed, are passed to the ``header_factory``, and the resulting
439453
header object is returned. Any surrogateescaped bytes get turned into
440454
the unicode unknown-character glyph.
441455

@@ -445,9 +459,9 @@ added matters. To illustrate::
445459
A value is considered to be a 'source value' if and only if it does not
446460
have a ``name`` attribute (having a ``name`` attribute means it is a
447461
header object of some sort). If a source value needs to be refolded
448-
according to the policy, it is converted into a custom header object by
462+
according to the policy, it is converted into a header object by
449463
passing the *name* and the *value* with any CR and LF characters removed
450-
to the ``header_factory``. Folding of a custom header object is done by
464+
to the ``header_factory``. Folding of a header object is done by
451465
calling its ``fold`` method with the current policy.
452466

453467
Source values are split into lines using :meth:`~str.splitlines`. If
@@ -502,23 +516,23 @@ With all of these :class:`EmailPolicies <.EmailPolicy>`, the effective API of
502516
the email package is changed from the Python 3.2 API in the following ways:
503517

504518
* Setting a header on a :class:`~email.message.Message` results in that
505-
header being parsed and a custom header object created.
519+
header being parsed and a header object created.
506520

507521
* Fetching a header value from a :class:`~email.message.Message` results
508-
in that header being parsed and a custom header object created and
522+
in that header being parsed and a header object created and
509523
returned.
510524

511-
* Any custom header object, or any header that is refolded due to the
525+
* Any header object, or any header that is refolded due to the
512526
policy settings, is folded using an algorithm that fully implements the
513527
RFC folding algorithms, including knowing where encoded words are required
514528
and allowed.
515529

516530
From the application view, this means that any header obtained through the
517-
:class:`~email.message.Message` is a custom header object with custom
531+
:class:`~email.message.Message` is a header object with extra
518532
attributes, whose string value is the fully decoded unicode value of the
519533
header. Likewise, a header may be assigned a new value, or a new header
520534
created, using a unicode string, and the policy will take care of converting
521535
the unicode string into the correct RFC encoded form.
522536

523-
The custom header objects and their attributes are described in
537+
The header objects and their attributes are described in
524538
:mod:`~email.headerregistry`.

‎Doc/library/email.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ Contents of the :mod:`email` package documentation:
5353
email.generator.rst
5454
email.policy.rst
5555
email.headerregistry.rst
56+
email.contentmanager.rst
5657
email.mime.rst
5758
email.header.rst
5859
email.charset.rst

‎Doc/whatsnew/3.4.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,21 @@ result: a bytes object containing the fully formatted message.
280280

281281
(Contributed by R. David Murray in :issue:`18600`.)
282282

283+
A pair of new subclasses of :class:`~email.message.Message` have been added,
284+
along with a new sub-module, :mod:`~email.contentmanager`. All documentation
285+
is currently in the new module, which is being added as part of the new
286+
:term:`provisional <provosional package>` email API. These classes provide a
287+
number of new methods that make extracting content from and inserting content
288+
into email messages much easier. See the :mod:`~email.contentmanager`
289+
documentation for details.
290+
291+
These API additions complete the bulk of the work that was planned as part of
292+
the email6 project. The currently provisional API is scheduled to become final
293+
in Python 3.5 (possibly with a few minor additions in the area of error
294+
handling).
295+
296+
(Contributed by R. David Murray in :issue:`18891`.)
297+
283298

284299
functools
285300
---------

0 commit comments

Comments
 (0)
X Tutup