Update HTTPResponse documentation and add placeholder for HTTPMessage.
diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst
index 5fcc0f0..4d9a4dd 100644
--- a/Doc/library/http.client.rst
+++ b/Doc/library/http.client.rst
@@ -59,8 +59,8 @@
.. class:: HTTPResponse(sock[, debuglevel=0][, strict=0])
- Class whose instances are returned upon successful connection. Not instantiated
- directly by user.
+ Class whose instances are returned upon successful connection. Not
+ instantiated directly by user.
The following exceptions are raised as appropriate:
@@ -433,7 +433,10 @@
HTTPResponse Objects
--------------------
-:class:`HTTPResponse` instances have the following methods and attributes:
+An :class:`HTTPResponse` instance wraps the HTTP response from the
+server. It provides access to the request headers and the entity
+body. The response is an iterable object and can be used in a with
+statement.
.. method:: HTTPResponse.read([amt])
@@ -454,7 +457,9 @@
.. attribute:: HTTPResponse.msg
- An :class:`email.message.Message` instance containing the response headers.
+ A :class:`http.client.HTTPMessage` instance containing the response
+ headers. :class:`http.client.HTTPMessage` is a subclass of
+ :class:`email.message.Message`.
.. attribute:: HTTPResponse.version
@@ -472,6 +477,12 @@
Reason phrase returned by server.
+.. attribute:: HTTPResponse.debuglevel
+
+ A debugging hook. If `debuglevel` is greater than zero, messages
+ will be printed to stdout as the response is read and parsed.
+
+
Examples
--------
@@ -505,3 +516,14 @@
>>> data = response.read()
>>> conn.close()
+
+.. _httpmessage-objects:
+
+HTTPMessage Objects
+-------------------
+
+An :class:`http.client.HTTPMessage` instance holds the headers from an
+HTTP response. It is implemented using the
+:class:`email.message.Message' class.
+
+XXX Define the methods that clients can depend upon between versions.
\ No newline at end of file