Title: Simplify email API via 'policy' objects
Type: enhancement Stage: resolved
Components: Versions: Python 3.3
Status: closed Resolution: accepted
Dependencies: Superseder:
Assigned To: r.david.murray Nosy List: barry, python-dev, r.david.murray
Priority: normal Keywords: patch

Created on 2011-03-31 18:48 by r.david.murray, last changed 2011-05-14 02:16 by r.david.murray. This issue is now closed.

File name Uploaded Description Edit
policy.patch r.david.murray, 2011-04-04 21:00 review
policy_for_review.patch r.david.murray, 2011-04-14 16:26 review
policy_final.patch r.david.murray, 2011-04-15 15:24 review
Repositories containing patches
Messages (6)
msg132694 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-03-31 18:48
As part of the email6 design, the email-sig came up with the idea of simplifying the current email API by introducing the concept of "policy objects".  A policy object is an object that hold various parameters and methods that can be used to control the behavior of the email package.  Thus, instead of having 'maxheaderlen', '_mangle_from', 'unixfrom', linesep, etc, etc options, you have a policy object that holds settings for these options that are applicable to a particular domain.  Thus an 'SMTP' policy would have a maxheaderlen of 76, a linesep of \r\n, and _mangle_from and unixfrom false, while mbox would have linesep \n and _mangle_from and unixfrom True.  HTTP would be like SMTP, but with maxheaderlen 0 (unlimited).

The policy is passed to the parser and/or the generator construtor to control how input is interpreted and how output is generated.  By encapsulating the details into objects related to clearly defined problem domains, we make it much simpler to use the email package both within a domain and for translating messages between domains.

Originally we saw the policy object as fundamental to the whole email6 design, but it has become clear that it is actually a relatively independent piece, and by itself much smaller than the parser and generator changes required for the full email6 implementation.

Therefore I'm starting the email6 development with the policy object piece as a standalone proposal.  I'd like to see this piece get reviewed and committed early in the process so I can use it as an underpinning for the further work.

I've set up a feature repo for email6 at features/email6.  I've pushed the framework (the policy object and its docs, with a selection of the options I intend to implement documented) and several integration updates (raise_on_defect, linesep, must_be_7bit).  I thought I'd post this issue now, with the link to the repo, so people can give me early feedback if they wish.

Ultimately I would like to deprecate the constructor arguments that are subsumed by the policy object settings.
msg132963 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-04-04 19:38
For some reason the create patch button isn't working (perhaps because I'm using a named branch?), so here is a patch representing the current state of the feature branch.
msg132968 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-04-04 21:00
Try again with a patch going in the expected direction :)
msg133745 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-04-14 16:12
Éric did a review of the previous patch (mostly doc stuff) which should
be pretty much addressed in this new version of the patch.

I'd like to propose this version (modulo any forthcoming comments) for
commit to trunk.  I've removed some parameters that I have not (yet)
implemented.  I've decided that it is better to commit the framework now
and have it there as the skeleton on which to attach the remaining items
(and some new ones I'm finding I need for the remaining email6 work)
when I'm really ready to implement those remaining items.
msg133838 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-04-15 15:24
What I hope is the final patch, after Barry's review, and Éric's second.
msg133987 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-04-18 18:00
New changeset 2f3fda9d3906 by R David Murray in branch 'default':
#11731: simplify/enhance parser/generator API by introducing policy objects.
Date User Action Args
2011-05-14 02:16:19r.david.murraysetstatus: open -> closed
resolution: accepted
stage: patch review -> resolved
2011-04-18 18:00:39python-devsetnosy: + python-dev
messages: + msg133987
2011-04-15 15:24:27r.david.murraysetfiles: + policy_final.patch

messages: + msg133838
2011-04-14 16:26:37r.david.murraysetfiles: + policy_for_review.patch
2011-04-14 16:26:19r.david.murraysetfiles: - policy_for_review.patch
2011-04-14 16:12:16r.david.murraysetfiles: + policy_for_review.patch

messages: + msg133745
2011-04-04 21:00:58r.david.murraysetfiles: + policy.patch

messages: + msg132968
2011-04-04 21:00:24r.david.murraysetfiles: - policy.patch
2011-04-04 19:38:41r.david.murraysetfiles: + policy.patch
keywords: + patch
messages: + msg132963
2011-03-31 18:48:59r.david.murraycreate