No deep thought was given to the HTTPMessage API. Here's the extent of
the discussion that I can find. I've changed the names, but you can
find the full discussion at http://bugs.python.org/issue2848
A: mimetools.Message is compatible with email.message.Message, right?
B: I don't know how compatible it is.
C: The APIs are bit different, but it should be possible to migrate from
the old to the new.

A plausible solution is to pick some core set of functionality that we
think people need and document that API. We can modify one or both of
the current implementations to include that functionality. What do we need?

I propose that you only document the getitem header access API. I.e.
the thing that info() gives you can be used to access the message
headers via message['content-type']. That's an API common to both
rfc822.Messages (the ultimate base class of mimetools.Message) and
email.message.Message.

On Thu, Mar 26, 2009 at 4:29 PM, Barry A. Warsaw <report@bugs.python.org>wrote:
>
> Barry A. Warsaw <barry@python.org> added the comment:
>
> I propose that you only document the getitem header access API. I.e.
> the thing that info() gives you can be used to access the message
> headers via message['content-type']. That's an API common to both
> rfc822.Messages (the ultimate base class of mimetools.Message) and
> email.message.Message.
>
As I've found myself in the awkward position of having to explain the new
3.0 api to my students I've thought about this and have some
ideas/questions.
I'm also willing to help with the documentation or any enhancements.
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: 'addinfourl' object is unsubscriptable
I wish I new what an addinfourl object was.
'Fri, 27 Mar 2009 00:41:34 GMT'
'Fri, 27 Mar 2009 00:41:34 GMT'
['Date', 'Server', 'Last-Modified', 'ETag', 'Accept-Ranges',
'Content-Length', 'Connection', 'Content-Type']
Using x.headers over x.info() makes the most sense to me, but I don't know
that I can give any good rationale. Which would we want to document?
'text/html; charset=ISO-8859-1'
I guess technically this is correct since the charset is part of the
Content-Type header in HTTP but it does make life difficult for what I think
will be a pretty common use case in this new urllib: read from the url (as
bytes) and then decode them into a string using the appropriate character
set.
As you follow this road, you have the confusing option of these three calls:
'iso-8859-1'
>>> x.headers.get_charsets()
['iso-8859-1']
I think it should be a bug that get_charset() does not return anything in
this case. It is not at all clear why get_content_charset() and
get_charset() should have different behavior.
Brad
>
> ----------
> nosy: +barry
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue4773>
> _______________________________________
>

The attached file is vaguely related to the current discussion. I'd
like to document the API for the urllib response, but I'd also like to
simplify the implementation on the py3k side. We can document the
simple API on the py3k side, then support some version of that API on
the py2k side.
Apologies for the noise in this patch. I was on a plane, and I don't
understand DVCS yet.

I spent sometime on the patch which replaces the self.msg usage with
self.headers in http.client. Everything is fine.
The next step is to provide an interface in the urllib.response and the
equivalent changes to py2k.

Now that two Python 3 releases have been made, I don’t know if changing the code is still an option. The doc can certainly still be improved.
Adding Ezio to nosy; I think it’s you who opened a bug report about removing superfluous getter methods in the addinfourl class (and other ugliness).

@joel.verhagen
"Should HTTPResponse.getheaders() comma-separate the values (...)"
No, it should not. RFC 2616 states:
"Multiple message-header fields with the same field-name MAY be present in a message if and only if the entire field-value for that header field is defined as a comma-separated list [i.e., #(values)]."
As field-values for some header fields ('Set-Cookie' being an example) are not defined as a comma-separated list such fields must not be merged.
Side note:
RFC 2616 is very soon to be obsoleted by the new RFC from httpbin working group. However, in the current/newest draft (http://trac.tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-21#section-3.2) although wording is different the sense is the same.

I just caught a bug because on Python 3 `HTTPMessage` has `get_param`, while on Python 2 there is `getparam`, with a different method signature. I am trying to figure out a solution so my code can run in both python 2 and 3 without ifs on python version.

Jeremy’s patch appears to have been merged in revision 9eceb618274a. A documentation entry for the HTTPMessage class was also added in 2009, pointing back to email.message.Message. So is there anything left to do for this issue?