# 11.6 `httplib` -- HTTP protocol client

This module defines classes which implement the client side of the HTTP and HTTPS protocols. It is normally not used directly -- the module `urllib` uses it to handle URLs that use HTTP and HTTPS.

Note: HTTPS support is only available if the `socket` module was compiled with SSL support.

Note: The public interface for this module changed substantially in Python 2.0. The `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 constants defined in this module are:

`HTTP_PORT`
  The default port for the HTTP protocol (always `80`).

`HTTPS_PORT`
  The default port for the HTTPS protocol (always `443`).

The module provides the following classes:

class `HTTPConnection`( | host[, port])

  An `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. 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)

  New in version 2.0.

class `HTTPSConnection`( | host[, port, key_file, cert_file])

  A subclass of `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!

  New in version 2.0.

class `HTTPResponse`( | sock[, debuglevel=0][, strict=0])

  Class whose instances are returned upon successful connection. Not instantiated directly by user. New in version 2.0.

The following exceptions are raised as appropriate:

exception `HTTPException`
  The base class of the other exceptions in this module. It is a subclass of `Exception`. New in version 2.0.

exception `NotConnected`
  A subclass of `HTTPException`. New in version 2.0.

exception `InvalidURL`
  A subclass of `HTTPException`, raised if a port is given and is either non-numeric or empty. New in version 2.3.

exception `UnknownProtocol`
  A subclass of `HTTPException`. New in version 2.0.

exception `UnknownTransferEncoding`
  A subclass of `HTTPException`. New in version 2.0.

exception `UnimplementedFileMode`
  A subclass of `HTTPException`. New in version 2.0.

exception `IncompleteRead`
  A subclass of `HTTPException`. New in version 2.0.

exception `ImproperConnectionState`
  A subclass of `HTTPException`. New in version 2.0.

exception `CannotSendRequest`
  A subclass of `ImproperConnectionState`. New in version 2.0.

exception `CannotSendHeader`
  A subclass of `ImproperConnectionState`. New in version 2.0.

exception `ResponseNotReady`
  A subclass of `ImproperConnectionState`. New in version 2.0.

exception `BadStatusLine`
  A subclass of `HTTPException`. Raised if a server responds with a HTTP status code that we don't understand. New in version 2.0.

Subsections

- 11.6.1 HTTPConnection Objects
- 11.6.2 HTTPResponse Objects
- 11.6.3 Examples