[Email-SIG] API thoughts

[Barry Warsaw]

On Mar 01, 2011, at 03:40 PM, R. David Murray wrote:

>So, and here is the point of this email, how does the policy framework
>integrate into this design?
[...]
>This list breaks down into items that affect the Parser, ones that affect
>the Generator, and ones that affect both the Parser and the Message.
>(Well, the "how much transformation" affects all three in the sense that
>the data has to be preserved by both the Parser and the Message in order
>for the Generator to be able to implement it, but I think we can take
>it as a given that we are going to preserve that data.)
>
>The pieces that are shared between the Parser and the Message are really
>about the Message:  how are the sub-objects represented?  How are the
>structured headers represented?  So we could consider that the Parser
>is a *consumer* of those pieces of policy, but that they are defined on
>the Message, not on the Parser.
>
>What this means is that the policy controlling each of the major
>components (parser, message, generator) are in principle independent.
[...]
>Re-thinking it now, though, I think there are actually two distinct
>components here: the I/O policy(s), and the Message construction policy.
[...]
>So, I think the "policy framework" is actually two things:  the
>header/mime-types registry, and the Parser/Generator policies.  Let's have
>'policy' refer to only the I/O policy, and call the other the email
>class registry.

+1

This makes a lot of sense, and I'm glad you've been thinking about this more
deeply than I have since we last bandied it about.  At the time, I thought a
single policy hierarchy would probably be fine, but you've laid out a good
argument for keeping them separate, and in fact not even calling the latter a
'policy'.  Here's another distinction:

Policy objects should be composable.  This would allow for a standard library
of policies that could be mixed and matched for specific applications, and
might even include some higher level policies like 'CGI' or 'NNTP'.  E.g. my
applications might combine a standard 'don't-check-rfc-2047' policy with a
'use-only-CRNL' and 'die-on-defect'.

I wonder too, how sophisticated policy objects really need to be.  Are they
just bags of attributes with some defaults, properties for access, maybe some
validation, and composability?

As for the registry, I don't think you need anything near that.  You just need
to say "when you see this mime-type, create an object using this callable".
Multiple registrations might be useful, but I don't think composability is.

>The real meat of email6, then, is the header/mime-types registry, and
>the changes in the API of the resulting Message objects.  The parser
>currently accepts a _factory argument that specifies the object to be used
>in creating the Message.   I propose that we deprecate this argument,
>but that any code using it gets the old behavior of the parser (using
>_factory to create the class for any new sub-objects).  Then we introduce
>a new argument, 'factory'.  This new argument would expect a callable
>that takes a mime-type as its argument, and returns an appropriate class.
>The parser would be re-written so that it could use this factory, and
>the backward compatibility case would be trivial to implement.

+1.  The underscore name in _factory is a historical wart that's not needed
any more.  I'm not even sure it makes much sense any more in Message
subclasses.  It *does* still make sense in e.g. add_header() where there's a
potential name collision between the arguments and the **params.  We should
evaluate these more carefully given today's API and clean this up if possible
(modulo all b/c considerations).

>In theory the classes returned by the registry/factory are arbitrary,
>but in practice we will need to define the minimal API that they
>should provide.  By specifying the API separately from the concrete
>implementation in email6, we will allow third parties to write classes
>that can play well with programs expecting to operate on email6 Messages.
>This will allow, for example, an MUA to provide custom classes to enhance
>presentation, while still allowing the message to be submitted to smtplib
>for transmission.

+1

>I guess I'm proposing, then, that there be an API version definition,
>with two values as of Python3.3: email5 API, and email6 API.  We'll
>figure out how we name and interrogate these formally later.
>
>The Header registry in this vision is accessed through the Message class.
>I have various thoughts about how this will work, but I'm going to leave
>those for later, since this email is already long enough.  I also have
>some additional thoughts about backward compatibility, but it is going
>to require some experimentation to see if they are realistic.

Cool.  Really great stuff David.

-Barry
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/email-sig/attachments/20110302/cdce70ca/attachment.pgp>