22

✏️ Editing: httplib.rst.txt

: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.  The :term:`2to3` tool will automatically adapt imports when converting
   your sources to Python 3.

.. index::
   pair: HTTP; protocol
   single: HTTP; httplib (standard module)

.. 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`
uses it to handle URLs that use HTTP and HTTPS.

.. seealso::

The `Requests package <http://requests.readthedocs.org/>`_
    is recommended for a higher-level HTTP client interface.

.. note::

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[, strict[, timeout[, source_address]]]])

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.  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).
   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 = 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.

.. versionchanged:: 2.7
      *source_address* was added.

.. class:: HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout[, source_address[, context]]]]]]])

A subclass of :class:`HTTPConnection` that uses SSL for communication with
   secure servers.  Default port is ``443``.  If *context* is specified, it must
   be a :class:`ssl.SSLContext` instance describing the various SSL options.

*key_file* and *cert_file* are deprecated, please use
   :meth:`ssl.SSLContext.load_cert_chain` instead, or let
   :func:`ssl.create_default_context` select the system's trusted CA
   certificates for you.

Please read :ref:`ssl-security` for more information on best practices.

.. versionadded:: 2.0

.. versionchanged:: 2.6
      *timeout* was added.

.. versionchanged:: 2.7
      *source_address* was added.

.. versionchanged:: 2.7.9
      *context* was added.

This class now performs all the necessary certificate and hostname checks
      by default. To revert to the previous, unverified, behavior
      :func:`ssl._create_unverified_context` can be passed to the *context*
      parameter.

.. class:: HTTPResponse(sock, debuglevel=0, strict=0)

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

.. 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:

.. exception:: HTTPException

The base class of the other exceptions in this module.  It is a subclass of
   :exc:`Exception`.

.. versionadded:: 2.0

.. exception:: NotConnected