--- rest25/library/httplib.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/httplib.rst	2009-04-05 05:02:09.000000000 +0900
@@ -1,19 +1,23 @@
-
 :mod:`httplib` --- HTTP protocol client
 =======================================
 
 .. module:: httplib
    :synopsis: HTTP and HTTPS protocol client (requires sockets).
 
+.. note::
+   The :mod:`httplib` module has been renamed to :mod:`http.client` in Python
+   3.0.  The :term:`2to3` tool will automatically adapt imports when converting
+   your sources to 3.0.
+
 
 .. index::
    pair: HTTP; protocol
    single: HTTP; httplib (standard module)
 
 .. index:: module: urllib
 
 This module defines classes which implement the client side of the HTTP and
 HTTPS protocols.  It is normally not used directly --- the module :mod:`urllib`
 uses it to handle URLs that use HTTP and HTTPS.
 
 .. note::
@@ -21,53 +25,67 @@
    HTTPS support is only available if the :mod:`socket` module was compiled with
    SSL support.
 
 .. note::
 
    The public interface for this module changed substantially in Python 2.0.  The
    :class:`HTTP` class is retained only for backward compatibility with 1.5.2.  It
    should not be used in new code.  Refer to the online docstrings for usage.
 
 The module provides the following classes:
 
 
-.. class:: HTTPConnection(host[, port])
+.. class:: HTTPConnection(host[, port[, strict[, timeout]]])
 
    An :class:`HTTPConnection` instance represents one transaction with an HTTP
-   server.  It should be instantiated passing it a host and optional port number.
+   server.  It should be instantiated passing it a host and optional port
+   number.
-   If no port number is passed, the port is extracted from the host string if it
-   has the form ``host:port``, else the default HTTP port (80) is used.
+If no port number is passed, the port is extracted from the host
+   string if it has the form ``host:port``, else the default HTTP port (80) is
+   used.
+When True, the optional parameter *strict* (which defaults to a false
+   value) causes ``BadStatusLine`` to
+   be raised if the status line can't be parsed as a valid HTTP/1.0 or 1.1
+   status line.  If the optional *timeout* parameter is given, blocking
+   operations (like connection attempts) will timeout after that many seconds
+   (if it is not given, the global default timeout setting is used).
+
-For
-   example, the following calls all create instances that connect to the server at
-   the same host and port::
+   For example, the following calls all create instances that connect to the server
+   at the same host and port::
 
       >>> h1 = httplib.HTTPConnection('www.cwi.nl')
       >>> h2 = httplib.HTTPConnection('www.cwi.nl:80')
       >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)
+      >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10)
 
    .. versionadded:: 2.0
 
+   .. versionchanged:: 2.6
+      *timeout* was added.
 
-.. class:: HTTPSConnection(host[, port, key_file, cert_file])
+
+.. class:: HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout]]]]])
 
    A subclass of :class:`HTTPConnection` that uses SSL for communication with
    secure servers.  Default port is ``443``. *key_file* is the name of a PEM
    formatted file that contains your private key. *cert_file* is a PEM formatted
    certificate chain file.
 
    .. warning::
 
       This does not do any certificate verification!
 
    .. versionadded:: 2.0
 
+   .. versionchanged:: 2.6
+      *timeout* was added.
+
 
 .. class:: HTTPResponse(sock[, debuglevel=0][, strict=0])
 
    Class whose instances are returned upon successful connection.  Not instantiated
    directly by user.
 
    .. versionadded:: 2.0
 
 The following exceptions are raised as appropriate:
 
 
 .. exception:: HTTPException
@@ -78,26 +96,26 @@
    .. versionadded:: 2.0
 
 
 .. exception:: NotConnected
 
    A subclass of :exc:`HTTPException`.
 
    .. versionadded:: 2.0
 
 
 .. exception:: InvalidURL
 
-   A subclass of :exc:`HTTPException`, raised if a port is given and is either non-
-   numeric or empty.
+   A subclass of :exc:`HTTPException`, raised if a port is given and is either
+   non-numeric or empty.
 
    .. versionadded:: 2.3
 
 
 .. exception:: UnknownProtocol
 
    A subclass of :exc:`HTTPException`.
 
    .. versionadded:: 2.0
 
 
 .. exception:: UnknownTransferEncoding
@@ -370,138 +388,143 @@
 
    .. versionadded:: 2.5
 
 
 .. _httpconnection-objects:
 
 HTTPConnection Objects
 ----------------------
 
 :class:`HTTPConnection` instances have the following methods:
 
 
-.. method:: XXX Class.request(method, url[, body[, headers]])
+.. method:: HTTPConnection.request(method, url[, body[, headers]])
 
    This will send a request to the server using the HTTP request method *method*
    and the selector *url*.  If the *body* argument is present, it should be a
-   string of data to send after the headers are finished. The header Content-Length
-   is automatically set to the correct value. The *headers* argument should be a
-   mapping of extra HTTP headers to send with the request.
+   string of data to send after the headers are finished. Alternatively, it may
+   be an open file object, in which case the contents of the file is sent; this
+   file object should support ``fileno()`` and ``read()`` methods. The header
+   Content-Length is automatically set to the correct value. The *headers*
+   argument should be a mapping of extra HTTP headers to send with the request.
+
+   .. versionchanged:: 2.6
+      *body* can be a file object.
 
 
-.. method:: XXX Class.getresponse()
+.. method:: HTTPConnection.getresponse()
 
    Should be called after a request is sent to get the response from the server.
    Returns an :class:`HTTPResponse` instance.
 
    .. note::
 
       Note that you must have read the whole response before you can send a new
       request to the server.
 
 
-.. method:: XXX Class.set_debuglevel(level)
+.. method:: HTTPConnection.set_debuglevel(level)
 
    Set the debugging level (the amount of debugging output printed). The default
    debug level is ``0``, meaning no debugging output is printed.
 
 
-.. method:: XXX Class.connect()
+.. method:: HTTPConnection.connect()
 
    Connect to the server specified when the object was created.
 
 
-.. method:: XXX Class.close()
+.. method:: HTTPConnection.close()
 
    Close the connection to the server.
 
 As an alternative to using the :meth:`request` method described above, you can
 also send your request step by step, by using the four functions below.
 
 
-.. method:: XXX Class.putrequest(request, selector[, skip_host[, skip_accept_encoding]])
+.. method:: HTTPConnection.putrequest(request, selector[, skip_host[, skip_accept_encoding]])
 
    This should be the first call after the connection to the server has been made.
    It sends a line to the server consisting of the *request* string, the *selector*
    string, and the HTTP version (``HTTP/1.1``).  To disable automatic sending of
    ``Host:`` or ``Accept-Encoding:`` headers (for example to accept additional
    content encodings), specify *skip_host* or *skip_accept_encoding* with non-False
    values.
 
    .. versionchanged:: 2.4
       *skip_accept_encoding* argument added.
 
 
-.. method:: XXX Class.putheader(header, argument[, ...])
+.. method:: HTTPConnection.putheader(header, argument[, ...])
 
    Send an :rfc:`822`\ -style header to the server.  It sends a line to the server
    consisting of the header, a colon and a space, and the first argument.  If more
    arguments are given, continuation lines are sent, each consisting of a tab and
    an argument.
 
 
-.. method:: XXX Class.endheaders()
+.. method:: HTTPConnection.endheaders()
 
    Send a blank line to the server, signalling the end of the headers.
 
 
-.. method:: XXX Class.send(data)
+.. method:: HTTPConnection.send(data)
 
    Send data to the server.  This should be used directly only after the
    :meth:`endheaders` method has been called and before :meth:`getresponse` is
    called.
 
 
 .. _httpresponse-objects:
 
 HTTPResponse Objects
 --------------------
 
 :class:`HTTPResponse` instances have the following methods and attributes:
 
 
-.. method:: XXX Class.read([amt])
+.. method:: HTTPResponse.read([amt])
 
    Reads and returns the response body, or up to the next *amt* bytes.
 
 
-.. method:: XXX Class.getheader(name[, default])
+.. method:: HTTPResponse.getheader(name[, default])
 
    Get the contents of the header *name*, or *default* if there is no matching
    header.
 
 
-.. method:: XXX Class.getheaders()
+.. method:: HTTPResponse.getheaders()
 
    Return a list of (header, value) tuples.
 
    .. versionadded:: 2.4
 
 
-.. data:: msg
+.. attribute:: HTTPResponse.msg
 
    A :class:`mimetools.Message` instance containing the response headers.
 
 
-.. data:: version
+.. attribute:: HTTPResponse.version
 
    HTTP protocol version used by server.  10 for HTTP/1.0, 11 for HTTP/1.1.
 
 
-.. data:: status
+.. attribute:: HTTPResponse.status
 
    Status code returned by server.
 
 
-.. data:: reason
+.. attribute:: HTTPResponse.reason
 
    Reason phrase returned by server.
 
 
 .. _httplib-examples:
 
 Examples
 --------
 
 Here is an example session that uses the ``GET`` method::
 
    >>> import httplib
