| |
| 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: |
| |
| |
n | .. class:: HTTPConnection(host[, port]) |
n | .. class:: HTTPConnection(host[, port[, strict[, timeout]]]) |
| |
| An :class:`HTTPConnection` instance represents one transaction with an HTTP |
n | server. It should be instantiated passing it a host and optional port number. |
n | server. It should be instantiated passing it a host and optional port |
| If no port number is passed, the port is extracted from the host string if it |
| number. If no port number is passed, the port is extracted from the host |
| has the form ``host:port``, else the default HTTP port (80) is used. For |
| 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). |
| |
| example, the following calls all create instances that connect to the server at |
| For example, the following calls all create instances that connect to the server |
| the same host and port:: |
| 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) |
n | >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10) |
| |
n | .. versionadded:: 2.0 |
| |
| .. versionadded:: 2.0 |
| .. versionchanged:: 2.6 |
| *timeout* was added. |
| |
| |
n | .. class:: HTTPSConnection(host[, port, key_file, cert_file]) |
n | .. 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 |
| |
n | .. 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 |
| |
| .. _httpconnection-objects: |
| |
| HTTPConnection Objects |
| ---------------------- |
| |
| :class:`HTTPConnection` instances have the following methods: |
| |
| |
n | .. method:: XXX Class.request(method, url[, body[, headers]]) |
n | .. 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 |
n | string of data to send after the headers are finished. The header Content-Length |
n | 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 |
| is automatically set to the correct value. The *headers* argument should be a |
| Content-Length is automatically set to the correct value. The *headers* |
| mapping of extra HTTP headers to send with the request. |
| argument should be a mapping of extra HTTP headers to send with the request. |
| |
n | .. versionchanged:: 2.6 |
| *body* can be a file object. |
| |
n | .. method:: XXX Class.getresponse() |
n | |
| .. 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. |
| |
| |
n | .. method:: XXX Class.set_debuglevel(level) |
n | .. 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. |
| |
| |
n | .. method:: XXX Class.connect() |
n | .. method:: HTTPConnection.connect() |
| |
| Connect to the server specified when the object was created. |
| |
| |
n | .. method:: XXX Class.close() |
n | .. 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. |
| |
| |
n | .. method:: XXX Class.putrequest(request, selector[, skip_host[, skip_accept_encoding]]) |
n | .. 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. |
| |
| |
n | .. method:: XXX Class.putheader(header, argument[, ...]) |
n | .. 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. |
| |
| |
n | .. method:: XXX Class.endheaders() |
n | .. method:: HTTPConnection.endheaders() |
| |
| Send a blank line to the server, signalling the end of the headers. |
| |
| |
n | .. method:: XXX Class.send(data) |
n | .. 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: |
| |
| |
n | .. method:: XXX Class.read([amt]) |
n | .. method:: HTTPResponse.read([amt]) |
| |
| Reads and returns the response body, or up to the next *amt* bytes. |
| |
| |
n | .. method:: XXX Class.getheader(name[, default]) |
n | .. method:: HTTPResponse.getheader(name[, default]) |
| |
| Get the contents of the header *name*, or *default* if there is no matching |
| header. |
| |
| |
n | .. method:: XXX Class.getheaders() |
n | .. method:: HTTPResponse.getheaders() |
| |
| Return a list of (header, value) tuples. |
| |
| .. versionadded:: 2.4 |
| |
| |
n | .. data:: msg |
n | .. attribute:: HTTPResponse.msg |
| |
| A :class:`mimetools.Message` instance containing the response headers. |
| |
| |
n | .. data:: version |
n | .. attribute:: HTTPResponse.version |
| |
| HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1. |
| |
| |
n | .. data:: status |
n | .. attribute:: HTTPResponse.status |
| |
| Status code returned by server. |
| |
| |
t | .. data:: reason |
t | .. attribute:: HTTPResponse.reason |
| |
| Reason phrase returned by server. |
| |
| |
| .. _httplib-examples: |
| |
| Examples |
| -------- |