> > * The patch to the docs seems to muddy the waters even further (than the
> > current slightly murky state) about whether and why .headers is to be
> > preferred over the methods, or vice-versa.  I think .headers should
> > remain undocumented, for the reason stated by the doctest that failed
> > with Hans-Peter's original patch.
> 
> IIRC, Hans-Peter's comment was on the reference to .headers
undocumented interface mentioned in the test_urllib2.

I made no reference to Hans-Peter's comment -- only to his patch, so I
don't know what you're getting at here.  Could you respond to my
comment, please?

> >  The best course of action is
> > debatable, but the patch is a regression in this respect, so should not
> > be committed as-is.
> 
> My understanding in this case was to address 1) Title()-ize the
headers and 2)
> provide a case insensitive lookup.

Can you explain why you think providing case-insensitive lookup requires
documenting .headers?


> Is this sufficient now to expose the headers method? If not, what else?
> If headers method should not be exposed, then will the 2 cases
addressed above
> still do, as this issue request was opened for that?

There is no method named "headers".  I think that the .headers attribute
should never be documented, because it does not contain the
"unredirected headers".  Changing that behaviour would break code,
further confuse matters and complicate writing code that works with
multiple versions of Python.  A case *could* be made for changing it (by
including the "unredirected headers"), because other code will have been
broken by the introduction of .unredirected_hdrs; I prefer instead to
stick with old breakage rather than swapping it for new breakage, but as
I say, the best course of action is debatable.  Another choice would be
to start the process of deprecating .headers, and introduce a new
attribute with a similar function.  As long as your chosen solution
isn't actually a step backwards or sharply sideways, I probably won't
object very strongly.  What isn't really debatable is that the patch
makes things worse here: it adds a newly-documented interface which is
subtly and surprisingly different from the other one (an unacceptable
change in itself, IMO) without even explaining the difference between
the two, why they are different, and why one would want to use or avoid
one or other interface.

There are other problems with the documentation patch, but there's no
point in discussing those until the changes are agreed on.