[Email-SIG] API for Header objects

[Stephen J. Turnbull]

Tony Nelson writes:

 > You are insisting on is so burdening them.  I propose lifting that burden.

I disagree.  You have made no concrete arguments that what I propose
is a burden, except in the long-since discredited sense of a few extra
keystrokes for a single use-case.  However, you *could* in principle
do so, because I've proposed (the principles for) a fairly generic API.

Specifically, to assess the burden of understanding, so far I've
implicitly accepted the existing API for Messages:

to get one instance of a header:            msg[tag]
to get the payload:                         msg.payload

which is clearly flawed (see footnote [1] and the random thoughts,
below) but not fatally so (and it's not obvious what would be better),
and proposed a *generic* API for all types in email:

to get the wire format (validated) of obj:  bytes(obj)
to get a text display (unformatted) of obj: str(obj)
to get access to all attributes of obj:     obj

Guess what?  We already have an API nearly sufficient[1] for reading
and generating Unicode text/plain messages!  It requires four (count
them, *four*) identifiers not in Python itself: the classes Message,
Header, and Payload, and the Message attribute .payload.  Is that
burdensome?  Very well then, it is burdensome.  I *joyfully* impose
that burden on you, and of course accept it myself.

(I'm cheating a little bit, because I've ignored the issue of how to
get valid data into structured Headers when generating a new message.
But you haven't addressed that issue for the case of "msg['To'] shall
return a list of (display-name, mailbox) tuples" yet, either, and I
can use whatever method you define so there's no additional burden.)

I've also suggested for many object types where structuring as a
sequence makes sense:

to get a sequence of subobjects of obj:     list(obj)

With that addition, I think we're almost ready to write a mailing list
manager.<0.5 wink>

[[ Some random thoughts apropos this outline ]]

It may make sense to apply the list API to msg['Received'], returning
the list of values of 'Received' headers.  I think it does *not* make
sense to apply it to msg['Resent-To'], as resent headers generally
come in blocks, and the API should reflect that, I think.  That being
so, I wonder if it *really* makes sense for msg[tag] to return the
list of all instances of the tag field instead of a more or less
arbitrary individual, even in the case of a header defined to be
unique by the RFCs.

Then we'd need an API for accessing blocks (maybe for parsed incoming
only, rather than something mutable for setting on outgoing
messages).  Something like

to get the list of blocks of resent headers: msg.blocks['Resent']

where you'd have to define each type of block to the parser.  Each
block would be a dictionary of the related headers, so you could get
the most recent Resent-To field with msg.blocks['Resent'][0]['To'].

[[ end random thoughts ]]

 > What parseaddr() doesn't support is groups.  I haven't seen groups used,
 > though.  It does support Comments when a name-addr is not present.
 > 
 > I still don't see any trick.  "Stephen J. Turnbull" has always been
 > accepted as a display-name, RFC 822 notwithstanding.

Not when *validating* a header generator or user input!

Note that what you're implying is that your standard of correct is not
the RFCs, it's "what has always been done."  That's problematic.  In
fact, the RFC process is carefully designed to account for "what has
always been done."  And in this case, the RFC authors have had *four*
chances to accept 'Stephen J. Turnbull' as valid syntax, and they have
refused every single time.

 > You want to make it hard for the user of the email package.

The first time I let it slide.  Now that you've repeated it, I think
you owe me an apology.


Footnotes: 
[1]  What's missing is a way to handle multiple instances of a given
field.  This is a defect in the Message class, not the Header class,
and we haven't really discussed Message at all, so I beg the reader's
indulgence.