[Email-SIG] API for Header objects [was: Dropping bytes "support" in json]

[Stephen J. Turnbull]

Tony Nelson writes:

 > OK, Header instances could have a .useful field that returned the useful
 > data in all instances.  But in any case, the email package should guide
 > users in the correct usage, rather than leaving every choice seeming equal,
 > when only one choice is correct.

What do you mean by "only one choice is correct?"  For example, a
Destination field might be used for presentation (in which case the
display name are needed), or to compose a list of recipients (when
thjey should be discarded).  Some applications might prefer to receive
the combination as the original string (although that often is not
valid RFC-any), others might prefer it parsed into a pair of display
name and mailbox.

Quoth Barry Warsaw:

 > >A good API for getting the parsed and decoded header values needs to
 > >take into account that it won't always be a string.  For unstructured
 > >headers like Subject, str(header) would work just fine.  For an
 > >Originator or Destination address, what does str(header) return?

A string (not folded) of comma-separated addresses in "Display Name"
<po at box.example.com> form.

 > >And what would be the API for getting the set of
 > >realname/addresses out of the header?

Does there need to be one?  An AddressHeader object could support
indexing: message['To'][0] returns the first displayname,mailbox pair.
If you really want a list, what's wrong with list(header)?  (Yes, I
recall that you (Barry) said you don't think subclassing worked very
well, but I wonder if maybe we can't get it righter this time around.)

 > msg[<headername>] would be the preferred way.

This goes against the principle that this returns a Header object.
For one thing, I really think that there need to be some common
methods all Header objects support, like str() and to_wire_format().
Also, if this returns a list for 'To', then str(msg['To']) won't work
right: it will return the list enclosed in square brackets and the
mailbox portions will be quoted, which isn't useful.

 > msg.get_header(<headername>).useful would return the useful data form of
 > any header.

Er, shouldn't we just throw away the data that is never useful?<wink>

 > msg.get_header(<headername>).addresses would return the address list from
 > any address Header, and raise AttributeError with other Headers.

Yes, but a list of what?  Strings?  Bytes?  Displayname/mailbox pairs?