[Email-SIG] API thoughts

[R. David Murray]

On Tue, 01 Mar 2011 16:55:58 -0800, Glenn Linderman <v+python at g.nevcal.com> wrote:
> On 3/1/2011 2:59 PM, R. David Murray wrote:
> > On Tue, 01 Mar 2011 13:58:50 -0800, Glenn Linderman<v+python at g.nevcal.com>  wrote:
> Another reason is if the existing code handles many cases that are not 
> needed, and cannot be optimized for the case that is needed.  A "fast 
> path" reimplementation can eliminate the cases that are not needed, and 
> speed the result.  That, of course, depends on the internals of the 
> parsing of headers in the email package, and how much overhead RFC 2047 
> adds to that, which I haven't investigated and don't know.  Happily, 
> when uploading big files, headers are a  tiny fraction of time spent.  
> Sadly, when using large fill-in-the-blanks forms, header parsing can be 
> a significant fraction of the time spent.

I think the overhead if there are no encoded words in the header should
be minimal (probably a re scan, but possibly not even that, we'll see).
This could also be controlled by the policy (ie: the HTTP policy could
cause the header parser to skip the check-for-rfc2047-encoded-words
step).

> Presently, the cgi.py stream API only provides a open-file-like handle 
> to the data... so it can be read, written, and sought, but not assigned 
> to a specific filesystem, renamed, or moved using os facilities.  So a 
> broader API seems to be necessary for cgi.py; if that were available in 
> email, that would be helpful for cgi.py.

Yeah, additions to the cgi API are probably required to support this
properly.

> Hmm.  And while it might be more complex to handle structured headers, 
> in fact they come in a character sequences, so a mapping to string is 
> not impossible.  The real issue is if those headers had another API in 
> email5 (I could look that up, I guess), but perhaps that API could also 
> be supported along with a subclass of string.

They don't.  The issue is that what we would like is for the email6 API
for the address header to be that it looks like a list of Address objects.
So msg['To'][0] would yield an address object.  But if we also want the
header to look like a string, that won't work, because as a string that
should yield the first character of the body of the header.

Now, a sensible application would process the list of addresses in a To
header by passing it to util.getaddresses, but you can bet that there
are applications that don't do that.

A compromise would be to have an 'addresses' method that returned the
list of addresses.  Perhaps this would even be sensible in the context of
email6 by itself:  it would mean that all headers had a uniform base API
(they act like strings) and all structured information is accessed via
special methods.

> OK, what I was asking boils down to if the Message object can support 
> both APIs, the application doesn't need to care.  New applications would 
> probably want to use the new APIs, of course.  But they could be passed 
> between old and new applications (or fragments thereof) if they support 
> both.  It certainly wouldn't hurt to introduce the concept of a version 
> for the object, although in itself, that would only be accessible via a 
> new API, so old applications wouldn't think to use it...

Yeah, that would be an ideal world.  Let's see how close we can get :)

--David