Source

cpython-pep302 / Doc / library / http.client.rst

:mod:`http.client` --- HTTP protocol client

Source code: :source:`Lib/http/client.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.request` uses it to handle URLs that use HTTP and HTTPS.

Note

HTTPS support is only available if Python was compiled with SSL support (through the :mod:`ssl` module).

The module provides the following classes:

An :class:`HTTPConnection` instance represents one transaction with an HTTP 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 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). 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 at the same host and port:

>>> h1 = http.client.HTTPConnection('www.cwi.nl')
>>> h2 = http.client.HTTPConnection('www.cwi.nl:80')
>>> h3 = http.client.HTTPConnection('www.cwi.nl', 80)
>>> h3 = http.client.HTTPConnection('www.cwi.nl', 80, timeout=10)

Class whose instances are returned upon successful connection. Not instantiated directly by user.

The following exceptions are raised as appropriate:

The constants defined in this module are:

and also the following constants for integer status codes:

Constant Value Definition
:const:`CONTINUE` 100 HTTP/1.1, RFC 2616, Section 10.1.1
:const:`SWITCHING_PROTOCOLS` 101 HTTP/1.1, RFC 2616, Section 10.1.2
:const:`PROCESSING` 102 WEBDAV, RFC 2518, Section 10.1
:const:`OK` 200 HTTP/1.1, RFC 2616, Section 10.2.1
:const:`CREATED` 201 HTTP/1.1, RFC 2616, Section 10.2.2
:const:`ACCEPTED` 202 HTTP/1.1, RFC 2616, Section 10.2.3
:const:`NON_AUTHORITATIVE_INFORMATION` 203 HTTP/1.1, RFC 2616, Section 10.2.4
:const:`NO_CONTENT` 204 HTTP/1.1, RFC 2616, Section 10.2.5
:const:`RESET_CONTENT` 205 HTTP/1.1, RFC 2616, Section 10.2.6
:const:`PARTIAL_CONTENT` 206 HTTP/1.1, RFC 2616, Section 10.2.7
:const:`MULTI_STATUS` 207 WEBDAV RFC 2518, Section 10.2
:const:`IM_USED` 226 Delta encoding in HTTP, RFC 3229, Section 10.4.1
:const:`MULTIPLE_CHOICES` 300 HTTP/1.1, RFC 2616, Section 10.3.1
:const:`MOVED_PERMANENTLY` 301 HTTP/1.1, RFC 2616, Section 10.3.2
:const:`FOUND` 302 HTTP/1.1, RFC 2616, Section 10.3.3
:const:`SEE_OTHER` 303 HTTP/1.1, RFC 2616, Section 10.3.4
:const:`NOT_MODIFIED` 304 HTTP/1.1, RFC 2616, Section 10.3.5
:const:`USE_PROXY` 305 HTTP/1.1, RFC 2616, Section 10.3.6
:const:`TEMPORARY_REDIRECT` 307 HTTP/1.1, RFC 2616, Section 10.3.8
:const:`BAD_REQUEST` 400 HTTP/1.1, RFC 2616, Section 10.4.1
:const:`UNAUTHORIZED` 401 HTTP/1.1, RFC 2616, Section 10.4.2
:const:`PAYMENT_REQUIRED` 402 HTTP/1.1, RFC 2616, Section 10.4.3
:const:`FORBIDDEN` 403 HTTP/1.1, RFC 2616, Section 10.4.4
:const:`NOT_FOUND` 404 HTTP/1.1, RFC 2616, Section 10.4.5
:const:`METHOD_NOT_ALLOWED` 405 HTTP/1.1, RFC 2616, Section 10.4.6
:const:`NOT_ACCEPTABLE` 406 HTTP/1.1, RFC 2616, Section 10.4.7
:const:`PROXY_AUTHENTICATION_REQUIRED` 407 HTTP/1.1, RFC 2616, Section 10.4.8
:const:`REQUEST_TIMEOUT` 408 HTTP/1.1, RFC 2616, Section 10.4.9
:const:`CONFLICT` 409 HTTP/1.1, RFC 2616, Section 10.4.10
:const:`GONE` 410 HTTP/1.1, RFC 2616, Section 10.4.11
:const:`LENGTH_REQUIRED` 411 HTTP/1.1, RFC 2616, Section 10.4.12
:const:`PRECONDITION_FAILED` 412 HTTP/1.1, RFC 2616, Section 10.4.13
:const:`REQUEST_ENTITY_TOO_LARGE` 413 HTTP/1.1, RFC 2616, Section 10.4.14
:const:`REQUEST_URI_TOO_LONG` 414 HTTP/1.1, RFC 2616, Section 10.4.15
:const:`UNSUPPORTED_MEDIA_TYPE` 415 HTTP/1.1, RFC 2616, Section 10.4.16
:const:`REQUESTED_RANGE_NOT_SATISFIABLE` 416 HTTP/1.1, RFC 2616, Section 10.4.17
:const:`EXPECTATION_FAILED` 417 HTTP/1.1, RFC 2616, Section 10.4.18
:const:`UNPROCESSABLE_ENTITY` 422 WEBDAV, RFC 2518, Section 10.3
:const:`LOCKED` 423 WEBDAV RFC 2518, Section 10.4
:const:`FAILED_DEPENDENCY` 424 WEBDAV, RFC 2518, Section 10.5
:const:`UPGRADE_REQUIRED` 426 HTTP Upgrade to TLS, RFC 2817, Section 6
:const:`INTERNAL_SERVER_ERROR` 500 HTTP/1.1, RFC 2616, Section 10.5.1
:const:`NOT_IMPLEMENTED` 501 HTTP/1.1, RFC 2616, Section 10.5.2
:const:`BAD_GATEWAY` 502 HTTP/1.1 RFC 2616, Section 10.5.3
:const:`SERVICE_UNAVAILABLE` 503 HTTP/1.1, RFC 2616, Section 10.5.4
:const:`GATEWAY_TIMEOUT` 504 HTTP/1.1 RFC 2616, Section 10.5.5
:const:`HTTP_VERSION_NOT_SUPPORTED` 505 HTTP/1.1, RFC 2616, Section 10.5.6
:const:`INSUFFICIENT_STORAGE` 507 WEBDAV, RFC 2518, Section 10.6
:const:`NOT_EXTENDED` 510 An HTTP Extension Framework, RFC 2774, Section 7

HTTPConnection Objects

:class:`HTTPConnection` instances have the following methods:

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.

HTTPResponse Objects

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.

Examples

Here is an example session that uses the GET method:

>>> import http.client
>>> conn = http.client.HTTPConnection("www.python.org")
>>> conn.request("GET", "/index.html")
>>> r1 = conn.getresponse()
>>> print(r1.status, r1.reason)
200 OK
>>> data1 = r1.read()  # This will return entire content.
>>> # The following example demonstrates reading data in chunks.
>>> conn.request("GET", "/index.html")
>>> r1 = conn.getresponse()
>>> while not r1.closed:
...     print(r1.read(200)) # 200 bytes
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"...
...
>>> # Example of an invalid request
>>> conn.request("GET", "/parrot.spam")
>>> r2 = conn.getresponse()
>>> print(r2.status, r2.reason)
404 Not Found
>>> data2 = r2.read()
>>> conn.close()

Here is an example session that uses the HEAD method. Note that the HEAD method never returns any data.

>>> import http.client
>>> conn = http.client.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 == b''
True

Here is an example session that shows how to POST requests:

>>> import http.client, urllib.parse
>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> headers = {"Content-type": "application/x-www-form-urlencoded",
...            "Accept": "text/plain"}
>>> conn = http.client.HTTPConnection("musi-cal.mojam.com:80")
>>> conn.request("POST", "/cgi-bin/query", params, headers)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
200 OK
>>> data = response.read()
>>> conn.close()

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.