Changeset 391 for python/trunk/Doc/library/httplib.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/httplib.rst (modified) (12 diffs)

python/trunk/Doc/library/httplib.rst

@@ -7 +7 @@
 .. 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.
+   3.  The :term:`2to3` tool will automatically adapt imports when converting
+   your sources to Python 3.
 
 
@@ -17 +17 @@
 .. index:: module: urllib
 
+**Source code:** :source:`Lib/httplib.py`
+
+--------------
+
 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`
@@ -35 +39 @@
 
 
-.. class:: HTTPConnection(host[, port[, strict[, timeout]]])
+.. class:: HTTPConnection(host[, port[, strict[, timeout[, source_address]]]])
 
    An :class:`HTTPConnection` instance represents one transaction with an HTTP
@@ -47 +51 @@
    operations (like connection attempts) will timeout after that many seconds
    (if it is not given, the global default timeout setting is used).
+   The optional *source_address* parameter may be a tuple of a (host, port)
+   to use as the source address the HTTP connection is made from.
 
    For example, the following calls all create instances that connect to the server
@@ -61 +67 @@
       *timeout* was added.
 
-
-.. class:: HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout]]]]])
+   .. versionchanged:: 2.7
+      *source_address* was added.
+
+
+.. class:: HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout[, source_address]]]]]])
 
    A subclass of :class:`HTTPConnection` that uses SSL for communication with
@@ -69 +78 @@
    certificate chain file.
 
-   .. note::
-
-      This does not do any certificate verification.
+   .. warning::
+      This does not do any verification of the server's certificate.
 
    .. versionadded:: 2.0
@@ -78 +86 @@
       *timeout* was added.
 
-
-.. class:: HTTPResponse(sock[, debuglevel=0][, strict=0])
+   .. versionchanged:: 2.7
+      *source_address* was added.
+
+
+.. class:: HTTPResponse(sock, debuglevel=0, strict=0)
 
    Class whose instances are returned upon successful connection.  Not instantiated
@@ -85 +96 @@
 
    .. versionadded:: 2.0
+
+.. class:: HTTPMessage
+
+   An :class:`HTTPMessage` instance is used to hold the headers from an HTTP
+   response. It is implemented using the :class:`mimetools.Message` class and
+   provides utility functions to deal with HTTP Headers. It is not directly
+   instantiated by the users.
+
 
 The following exceptions are raised as appropriate:
@@ -429 +448 @@
 
 
+.. method:: HTTPConnection.set_tunnel(host,port=None, headers=None)
+
+   Set the host and the port for HTTP Connect Tunnelling. Normally used when
+   it is required to do HTTPS Conection through a proxy server.
+
+   The headers argument should be a mapping of extra HTTP headers to send
+   with the CONNECT request.
+
+   .. versionadded:: 2.7
+
+
 .. method:: HTTPConnection.connect()
 
@@ -463 +493 @@
 
 
-.. method:: HTTPConnection.endheaders()
-
-   Send a blank line to the server, signalling the end of the headers.
+.. method:: HTTPConnection.endheaders(message_body=None)
+
+   Send a blank line to the server, signalling the end of the headers. The
+   optional *message_body* argument can be used to pass a message body
+   associated with the request.  The message body will be sent in the same
+   packet as the message headers if it is string, otherwise it is sent in a
+   separate packet.
+
+   .. versionchanged:: 2.7
+      *message_body* was added.
 
 
@@ -500 +537 @@
    .. versionadded:: 2.4
 
+.. method:: HTTPResponse.fileno()
+
+   Returns the ``fileno`` of the underlying socket.
 
 .. attribute:: HTTPResponse.msg
@@ -542 +582 @@
    >>> conn.close()
 
+Here is an example session that uses the ``HEAD`` method.  Note that the
+``HEAD`` method never returns any data. ::
+
+   >>> import httplib
+   >>> conn = httplib.HTTPConnection("www.python.org")
+   >>> conn.request("HEAD","/index.html")
+   >>> res = conn.getresponse()
+   >>> print res.status, res.reason
+   200 OK
+   >>> data = res.read()
+   >>> print len(data)
+   0
+   >>> data == ''
+   True
+
 Here is an example session that shows how to ``POST`` requests::
 
    >>> import httplib, urllib
-   >>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
+   >>> params = urllib.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})
    >>> headers = {"Content-type": "application/x-www-form-urlencoded",
    ...            "Accept": "text/plain"}
-   >>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80")
-   >>> conn.request("POST", "/cgi-bin/query", params, headers)
+   >>> conn = httplib.HTTPConnection("bugs.python.org")
+   >>> conn.request("POST", "", params, headers)
    >>> response = conn.getresponse()
    >>> print response.status, response.reason
-   200 OK
+   302 Found
    >>> data = response.read()
+   >>> data
+   'Redirecting to <a href="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'
    >>> conn.close()
 
+Client side ``HTTP PUT`` requests are very similar to ``POST`` requests. The
+difference lies only the server side where HTTP server will allow resources to
+be created via ``PUT`` request. Here is an example session that shows how to do
+``PUT`` request using httplib::
+
+    >>> # This creates an HTTP message
+    >>> # with the content of BODY as the enclosed representation
+    >>> # for the resource http://localhost:8080/foobar
+    ...
+    >>> import httplib
+    >>> BODY = "***filecontents***"
+    >>> conn = httplib.HTTPConnection("localhost", 8080)
+    >>> conn.request("PUT", "/file", BODY)
+    >>> response = conn.getresponse()
+    >>> print response.status, response.reason
+    200, OK
+