Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 1 | :mod:`http.client` --- HTTP protocol client |
| 2 | =========================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 4 | .. module:: http.client |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 5 | :synopsis: HTTP and HTTPS protocol client (requires sockets). |
| 6 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | **Source code:** :source:`Lib/http/client.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
| 9 | .. index:: |
| 10 | pair: HTTP; protocol |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 11 | single: HTTP; http.client (standard module) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 12 | |
Senthil Kumaran | aca8fd7 | 2008-06-23 04:41:59 +0000 | [diff] [blame] | 13 | .. index:: module: urllib.request |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 14 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 15 | -------------- |
| 16 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 17 | This module defines classes which implement the client side of the HTTP and |
Senthil Kumaran | aca8fd7 | 2008-06-23 04:41:59 +0000 | [diff] [blame] | 18 | HTTPS protocols. It is normally not used directly --- the module |
Georg Brandl | 0f7ede4 | 2008-06-23 11:23:31 +0000 | [diff] [blame] | 19 | :mod:`urllib.request` uses it to handle URLs that use HTTP and HTTPS. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | |
Benjamin Peterson | 6de708f | 2015-04-20 18:18:14 -0400 | [diff] [blame] | 21 | .. seealso:: |
| 22 | |
Andrew Kuchling | 58c534d | 2016-11-08 22:33:31 -0500 | [diff] [blame] | 23 | The `Requests package <http://docs.python-requests.org/>`_ |
Martin Panter | fe289c0 | 2016-05-28 02:20:39 +0000 | [diff] [blame] | 24 | is recommended for a higher-level HTTP client interface. |
Benjamin Peterson | 6de708f | 2015-04-20 18:18:14 -0400 | [diff] [blame] | 25 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | .. note:: |
| 27 | |
Antoine Pitrou | 1ab19ca | 2010-10-13 10:39:21 +0000 | [diff] [blame] | 28 | HTTPS support is only available if Python was compiled with SSL support |
| 29 | (through the :mod:`ssl` module). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 31 | The module provides the following classes: |
| 32 | |
| 33 | |
Nir Soffer | ad455cd | 2017-11-06 23:16:37 +0200 | [diff] [blame] | 34 | .. class:: HTTPConnection(host, port=None[, timeout], source_address=None, \ |
| 35 | blocksize=8192) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 36 | |
| 37 | An :class:`HTTPConnection` instance represents one transaction with an HTTP |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 38 | server. It should be instantiated passing it a host and optional port |
| 39 | number. If no port number is passed, the port is extracted from the host |
| 40 | string if it has the form ``host:port``, else the default HTTP port (80) is |
Antoine Pitrou | 988dbd7 | 2010-12-17 17:35:56 +0000 | [diff] [blame] | 41 | used. If the optional *timeout* parameter is given, blocking |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 42 | operations (like connection attempts) will timeout after that many seconds |
Georg Brandl | f78e02b | 2008-06-10 17:40:04 +0000 | [diff] [blame] | 43 | (if it is not given, the global default timeout setting is used). |
Raymond Hettinger | 519c308 | 2011-01-30 00:39:00 +0000 | [diff] [blame] | 44 | The optional *source_address* parameter may be a tuple of a (host, port) |
Gregory P. Smith | b406637 | 2010-01-03 03:28:29 +0000 | [diff] [blame] | 45 | to use as the source address the HTTP connection is made from. |
Nir Soffer | ad455cd | 2017-11-06 23:16:37 +0200 | [diff] [blame] | 46 | The optional *blocksize* parameter sets the buffer size in bytes for |
| 47 | sending a file-like message body. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | |
| 49 | For example, the following calls all create instances that connect to the server |
| 50 | at the same host and port:: |
| 51 | |
Antoine Pitrou | c5e075f | 2014-03-22 18:19:11 +0100 | [diff] [blame] | 52 | >>> h1 = http.client.HTTPConnection('www.python.org') |
| 53 | >>> h2 = http.client.HTTPConnection('www.python.org:80') |
| 54 | >>> h3 = http.client.HTTPConnection('www.python.org', 80) |
| 55 | >>> h4 = http.client.HTTPConnection('www.python.org', 80, timeout=10) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | |
Gregory P. Smith | b406637 | 2010-01-03 03:28:29 +0000 | [diff] [blame] | 57 | .. versionchanged:: 3.2 |
| 58 | *source_address* was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 59 | |
Senthil Kumaran | aced69f | 2013-03-19 01:22:56 -0700 | [diff] [blame] | 60 | .. versionchanged:: 3.4 |
R David Murray | 0056936 | 2014-01-03 13:04:25 -0500 | [diff] [blame] | 61 | The *strict* parameter was removed. HTTP 0.9-style "Simple Responses" are |
| 62 | not longer supported. |
Gregory P. Smith | b406637 | 2010-01-03 03:28:29 +0000 | [diff] [blame] | 63 | |
Nir Soffer | ad455cd | 2017-11-06 23:16:37 +0200 | [diff] [blame] | 64 | .. versionchanged:: 3.7 |
| 65 | *blocksize* parameter was added. |
| 66 | |
Antoine Pitrou | 988dbd7 | 2010-12-17 17:35:56 +0000 | [diff] [blame] | 67 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 68 | .. class:: HTTPSConnection(host, port=None, key_file=None, \ |
Senthil Kumaran | 052ddb0 | 2013-03-18 14:11:41 -0700 | [diff] [blame] | 69 | cert_file=None[, timeout], \ |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 70 | source_address=None, *, context=None, \ |
Nir Soffer | ad455cd | 2017-11-06 23:16:37 +0200 | [diff] [blame] | 71 | check_hostname=None, blocksize=8192) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | |
| 73 | A subclass of :class:`HTTPConnection` that uses SSL for communication with |
Antoine Pitrou | 803e6d6 | 2010-10-13 10:36:15 +0000 | [diff] [blame] | 74 | secure servers. Default port is ``443``. If *context* is specified, it |
| 75 | must be a :class:`ssl.SSLContext` instance describing the various SSL |
Antoine Pitrou | c5e075f | 2014-03-22 18:19:11 +0100 | [diff] [blame] | 76 | options. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 77 | |
Antoine Pitrou | c5e075f | 2014-03-22 18:19:11 +0100 | [diff] [blame] | 78 | Please read :ref:`ssl-security` for more information on best practices. |
| 79 | |
Gregory P. Smith | b406637 | 2010-01-03 03:28:29 +0000 | [diff] [blame] | 80 | .. versionchanged:: 3.2 |
Antoine Pitrou | 803e6d6 | 2010-10-13 10:36:15 +0000 | [diff] [blame] | 81 | *source_address*, *context* and *check_hostname* were added. |
Gregory P. Smith | b406637 | 2010-01-03 03:28:29 +0000 | [diff] [blame] | 82 | |
Antoine Pitrou | d532321 | 2010-10-22 18:19:07 +0000 | [diff] [blame] | 83 | .. versionchanged:: 3.2 |
| 84 | This class now supports HTTPS virtual hosts if possible (that is, |
| 85 | if :data:`ssl.HAS_SNI` is true). |
| 86 | |
Senthil Kumaran | aced69f | 2013-03-19 01:22:56 -0700 | [diff] [blame] | 87 | .. versionchanged:: 3.4 |
R David Murray | 0056936 | 2014-01-03 13:04:25 -0500 | [diff] [blame] | 88 | The *strict* parameter was removed. HTTP 0.9-style "Simple Responses" are |
| 89 | no longer supported. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | |
Benjamin Peterson | 4ffb075 | 2014-11-03 14:29:33 -0500 | [diff] [blame] | 91 | .. versionchanged:: 3.4.3 |
| 92 | This class now performs all the necessary certificate and hostname checks |
| 93 | by default. To revert to the previous, unverified, behavior |
| 94 | :func:`ssl._create_unverified_context` can be passed to the *context* |
| 95 | parameter. |
| 96 | |
Christian Heimes | d048637 | 2016-09-10 23:23:33 +0200 | [diff] [blame] | 97 | .. deprecated:: 3.6 |
| 98 | |
| 99 | *key_file* and *cert_file* are deprecated in favor of *context*. |
| 100 | Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let |
| 101 | :func:`ssl.create_default_context` select the system's trusted CA |
| 102 | certificates for you. |
| 103 | |
| 104 | The *check_hostname* parameter is also deprecated; the |
| 105 | :attr:`ssl.SSLContext.check_hostname` attribute of *context* should |
| 106 | be used instead. |
| 107 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 108 | |
Senthil Kumaran | 052ddb0 | 2013-03-18 14:11:41 -0700 | [diff] [blame] | 109 | .. class:: HTTPResponse(sock, debuglevel=0, method=None, url=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 110 | |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 111 | Class whose instances are returned upon successful connection. Not |
| 112 | instantiated directly by user. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 113 | |
Senthil Kumaran | aced69f | 2013-03-19 01:22:56 -0700 | [diff] [blame] | 114 | .. versionchanged:: 3.4 |
R David Murray | 0056936 | 2014-01-03 13:04:25 -0500 | [diff] [blame] | 115 | The *strict* parameter was removed. HTTP 0.9 style "Simple Responses" are |
| 116 | no longer supported. |
Antoine Pitrou | 988dbd7 | 2010-12-17 17:35:56 +0000 | [diff] [blame] | 117 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 118 | |
| 119 | The following exceptions are raised as appropriate: |
| 120 | |
| 121 | |
| 122 | .. exception:: HTTPException |
| 123 | |
| 124 | The base class of the other exceptions in this module. It is a subclass of |
| 125 | :exc:`Exception`. |
| 126 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 127 | |
| 128 | .. exception:: NotConnected |
| 129 | |
| 130 | A subclass of :exc:`HTTPException`. |
| 131 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 132 | |
| 133 | .. exception:: InvalidURL |
| 134 | |
| 135 | A subclass of :exc:`HTTPException`, raised if a port is given and is either |
| 136 | non-numeric or empty. |
| 137 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 138 | |
| 139 | .. exception:: UnknownProtocol |
| 140 | |
| 141 | A subclass of :exc:`HTTPException`. |
| 142 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 143 | |
| 144 | .. exception:: UnknownTransferEncoding |
| 145 | |
| 146 | A subclass of :exc:`HTTPException`. |
| 147 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 148 | |
| 149 | .. exception:: UnimplementedFileMode |
| 150 | |
| 151 | A subclass of :exc:`HTTPException`. |
| 152 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 153 | |
| 154 | .. exception:: IncompleteRead |
| 155 | |
| 156 | A subclass of :exc:`HTTPException`. |
| 157 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 158 | |
| 159 | .. exception:: ImproperConnectionState |
| 160 | |
| 161 | A subclass of :exc:`HTTPException`. |
| 162 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 163 | |
| 164 | .. exception:: CannotSendRequest |
| 165 | |
| 166 | A subclass of :exc:`ImproperConnectionState`. |
| 167 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 168 | |
| 169 | .. exception:: CannotSendHeader |
| 170 | |
| 171 | A subclass of :exc:`ImproperConnectionState`. |
| 172 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 173 | |
| 174 | .. exception:: ResponseNotReady |
| 175 | |
| 176 | A subclass of :exc:`ImproperConnectionState`. |
| 177 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 178 | |
| 179 | .. exception:: BadStatusLine |
| 180 | |
| 181 | A subclass of :exc:`HTTPException`. Raised if a server responds with a HTTP |
| 182 | status code that we don't understand. |
| 183 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 184 | |
Berker Peksag | babc688 | 2015-02-20 09:39:38 +0200 | [diff] [blame] | 185 | .. exception:: LineTooLong |
| 186 | |
| 187 | A subclass of :exc:`HTTPException`. Raised if an excessively long line |
| 188 | is received in the HTTP protocol from the server. |
| 189 | |
| 190 | |
R David Murray | cae7bdb | 2015-04-05 19:26:29 -0400 | [diff] [blame] | 191 | .. exception:: RemoteDisconnected |
| 192 | |
| 193 | A subclass of :exc:`ConnectionResetError` and :exc:`BadStatusLine`. Raised |
| 194 | by :meth:`HTTPConnection.getresponse` when the attempt to read the response |
| 195 | results in no data read from the connection, indicating that the remote end |
| 196 | has closed the connection. |
| 197 | |
| 198 | .. versionadded:: 3.5 |
| 199 | Previously, :exc:`BadStatusLine`\ ``('')`` was raised. |
| 200 | |
| 201 | |
Georg Brandl | bf3f8eb | 2013-10-27 07:34:48 +0100 | [diff] [blame] | 202 | The constants defined in this module are: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 203 | |
| 204 | .. data:: HTTP_PORT |
| 205 | |
| 206 | The default port for the HTTP protocol (always ``80``). |
| 207 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 208 | .. data:: HTTPS_PORT |
| 209 | |
| 210 | The default port for the HTTPS protocol (always ``443``). |
| 211 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 212 | .. data:: responses |
| 213 | |
| 214 | This dictionary maps the HTTP 1.1 status codes to the W3C names. |
| 215 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 216 | Example: ``http.client.responses[http.client.NOT_FOUND]`` is ``'Not Found'``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 217 | |
Berker Peksag | cb18b95 | 2015-01-20 06:30:46 +0200 | [diff] [blame] | 218 | See :ref:`http-status-codes` for a list of HTTP status codes that are |
| 219 | available in this module as constants. |
| 220 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 221 | |
| 222 | .. _httpconnection-objects: |
| 223 | |
| 224 | HTTPConnection Objects |
| 225 | ---------------------- |
| 226 | |
| 227 | :class:`HTTPConnection` instances have the following methods: |
| 228 | |
| 229 | |
Martin Panter | 3c0d0ba | 2016-08-24 06:33:33 +0000 | [diff] [blame] | 230 | .. method:: HTTPConnection.request(method, url, body=None, headers={}, *, \ |
| 231 | encode_chunked=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 232 | |
Jeremy Hylton | 236654b | 2009-03-27 20:24:34 +0000 | [diff] [blame] | 233 | This will send a request to the server using the HTTP request |
R David Murray | beed840 | 2015-03-22 15:18:23 -0400 | [diff] [blame] | 234 | method *method* and the selector *url*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 235 | |
R David Murray | beed840 | 2015-03-22 15:18:23 -0400 | [diff] [blame] | 236 | If *body* is specified, the specified data is sent after the headers are |
Martin Panter | 3c0d0ba | 2016-08-24 06:33:33 +0000 | [diff] [blame] | 237 | finished. It may be a :class:`str`, a :term:`bytes-like object`, an |
| 238 | open :term:`file object`, or an iterable of :class:`bytes`. If *body* |
| 239 | is a string, it is encoded as ISO-8859-1, the default for HTTP. If it |
| 240 | is a bytes-like object, the bytes are sent as is. If it is a :term:`file |
| 241 | object`, the contents of the file is sent; this file object should |
| 242 | support at least the ``read()`` method. If the file object is an |
| 243 | instance of :class:`io.TextIOBase`, the data returned by the ``read()`` |
| 244 | method will be encoded as ISO-8859-1, otherwise the data returned by |
| 245 | ``read()`` is sent as is. If *body* is an iterable, the elements of the |
| 246 | iterable are sent as is until the iterable is exhausted. |
Jeremy Hylton | 236654b | 2009-03-27 20:24:34 +0000 | [diff] [blame] | 247 | |
Martin Panter | 3c0d0ba | 2016-08-24 06:33:33 +0000 | [diff] [blame] | 248 | The *headers* argument should be a mapping of extra HTTP headers to send |
| 249 | with the request. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 250 | |
Martin Panter | ef91bb2 | 2016-08-27 01:39:26 +0000 | [diff] [blame] | 251 | If *headers* contains neither Content-Length nor Transfer-Encoding, |
| 252 | but there is a request body, one of those |
| 253 | header fields will be added automatically. If |
Martin Panter | 3c0d0ba | 2016-08-24 06:33:33 +0000 | [diff] [blame] | 254 | *body* is ``None``, the Content-Length header is set to ``0`` for |
| 255 | methods that expect a body (``PUT``, ``POST``, and ``PATCH``). If |
Martin Panter | ef91bb2 | 2016-08-27 01:39:26 +0000 | [diff] [blame] | 256 | *body* is a string or a bytes-like object that is not also a |
| 257 | :term:`file <file object>`, the Content-Length header is |
| 258 | set to its length. Any other type of *body* (files |
| 259 | and iterables in general) will be chunk-encoded, and the |
| 260 | Transfer-Encoding header will automatically be set instead of |
| 261 | Content-Length. |
Martin Panter | 3c0d0ba | 2016-08-24 06:33:33 +0000 | [diff] [blame] | 262 | |
| 263 | The *encode_chunked* argument is only relevant if Transfer-Encoding is |
| 264 | specified in *headers*. If *encode_chunked* is ``False``, the |
| 265 | HTTPConnection object assumes that all encoding is handled by the |
| 266 | calling code. If it is ``True``, the body will be chunk-encoded. |
| 267 | |
| 268 | .. note:: |
| 269 | Chunked transfer encoding has been added to the HTTP protocol |
| 270 | version 1.1. Unless the HTTP server is known to handle HTTP 1.1, |
Martin Panter | ef91bb2 | 2016-08-27 01:39:26 +0000 | [diff] [blame] | 271 | the caller must either specify the Content-Length, or must pass a |
| 272 | :class:`str` or bytes-like object that is not also a file as the |
| 273 | body representation. |
R David Murray | beed840 | 2015-03-22 15:18:23 -0400 | [diff] [blame] | 274 | |
Senthil Kumaran | 7bc0d87 | 2010-12-19 10:49:52 +0000 | [diff] [blame] | 275 | .. versionadded:: 3.2 |
Georg Brandl | 09a7df8 | 2010-12-19 12:33:52 +0000 | [diff] [blame] | 276 | *body* can now be an iterable. |
Senthil Kumaran | 7bc0d87 | 2010-12-19 10:49:52 +0000 | [diff] [blame] | 277 | |
Martin Panter | 3c0d0ba | 2016-08-24 06:33:33 +0000 | [diff] [blame] | 278 | .. versionchanged:: 3.6 |
| 279 | If neither Content-Length nor Transfer-Encoding are set in |
Martin Panter | ef91bb2 | 2016-08-27 01:39:26 +0000 | [diff] [blame] | 280 | *headers*, file and iterable *body* objects are now chunk-encoded. |
| 281 | The *encode_chunked* argument was added. |
| 282 | No attempt is made to determine the Content-Length for file |
Martin Panter | 3c0d0ba | 2016-08-24 06:33:33 +0000 | [diff] [blame] | 283 | objects. |
| 284 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 285 | .. method:: HTTPConnection.getresponse() |
| 286 | |
| 287 | Should be called after a request is sent to get the response from the server. |
| 288 | Returns an :class:`HTTPResponse` instance. |
| 289 | |
| 290 | .. note:: |
| 291 | |
| 292 | Note that you must have read the whole response before you can send a new |
| 293 | request to the server. |
| 294 | |
R David Murray | cae7bdb | 2015-04-05 19:26:29 -0400 | [diff] [blame] | 295 | .. versionchanged:: 3.5 |
| 296 | If a :exc:`ConnectionError` or subclass is raised, the |
| 297 | :class:`HTTPConnection` object will be ready to reconnect when |
| 298 | a new request is sent. |
| 299 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 300 | |
| 301 | .. method:: HTTPConnection.set_debuglevel(level) |
| 302 | |
R. David Murray | d89bc3f | 2010-12-15 02:19:14 +0000 | [diff] [blame] | 303 | Set the debugging level. The default debug level is ``0``, meaning no |
| 304 | debugging output is printed. Any value greater than ``0`` will cause all |
| 305 | currently defined debug output to be printed to stdout. The ``debuglevel`` |
| 306 | is passed to any new :class:`HTTPResponse` objects that are created. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 307 | |
Mark Dickinson | 574b1d6 | 2009-10-01 20:20:09 +0000 | [diff] [blame] | 308 | .. versionadded:: 3.1 |
Benjamin Peterson | fa0d703 | 2009-06-01 22:42:33 +0000 | [diff] [blame] | 309 | |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 310 | |
Senthil Kumaran | 7e5229c | 2009-12-20 07:31:21 +0000 | [diff] [blame] | 311 | .. method:: HTTPConnection.set_tunnel(host, port=None, headers=None) |
Senthil Kumaran | 97f0c6b | 2009-07-25 04:24:38 +0000 | [diff] [blame] | 312 | |
Benjamin Peterson | a48d9ea | 2014-03-16 15:55:39 -0500 | [diff] [blame] | 313 | Set the host and the port for HTTP Connect Tunnelling. This allows running |
| 314 | the connection through a proxy server. |
Senthil Kumaran | 97f0c6b | 2009-07-25 04:24:38 +0000 | [diff] [blame] | 315 | |
Benjamin Peterson | a48d9ea | 2014-03-16 15:55:39 -0500 | [diff] [blame] | 316 | The host and port arguments specify the endpoint of the tunneled connection |
| 317 | (i.e. the address included in the CONNECT request, *not* the address of the |
| 318 | proxy server). |
| 319 | |
| 320 | The headers argument should be a mapping of extra HTTP headers to send with |
| 321 | the CONNECT request. |
| 322 | |
| 323 | For example, to tunnel through a HTTPS proxy server running locally on port |
| 324 | 8080, we would pass the address of the proxy to the :class:`HTTPSConnection` |
| 325 | constructor, and the address of the host that we eventually want to reach to |
| 326 | the :meth:`~HTTPConnection.set_tunnel` method:: |
| 327 | |
| 328 | >>> import http.client |
| 329 | >>> conn = http.client.HTTPSConnection("localhost", 8080) |
| 330 | >>> conn.set_tunnel("www.python.org") |
| 331 | >>> conn.request("HEAD","/index.html") |
Senthil Kumaran | 7e5229c | 2009-12-20 07:31:21 +0000 | [diff] [blame] | 332 | |
Senthil Kumaran | 2e910fd | 2009-07-25 04:27:38 +0000 | [diff] [blame] | 333 | .. versionadded:: 3.2 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 334 | |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 335 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 336 | .. method:: HTTPConnection.connect() |
| 337 | |
R David Murray | cae7bdb | 2015-04-05 19:26:29 -0400 | [diff] [blame] | 338 | Connect to the server specified when the object was created. By default, |
| 339 | this is called automatically when making a request if the client does not |
| 340 | already have a connection. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 341 | |
| 342 | |
| 343 | .. method:: HTTPConnection.close() |
| 344 | |
| 345 | Close the connection to the server. |
| 346 | |
Nir Soffer | ad455cd | 2017-11-06 23:16:37 +0200 | [diff] [blame] | 347 | |
| 348 | .. attribute:: HTTPConnection.blocksize |
| 349 | |
| 350 | Buffer size in bytes for sending a file-like message body. |
| 351 | |
| 352 | .. versionadded:: 3.7 |
| 353 | |
| 354 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 355 | As an alternative to using the :meth:`request` method described above, you can |
| 356 | also send your request step by step, by using the four functions below. |
| 357 | |
| 358 | |
Senthil Kumaran | 5dc504c | 2016-09-08 14:28:01 -0700 | [diff] [blame] | 359 | .. method:: HTTPConnection.putrequest(method, url, skip_host=False, \ |
| 360 | skip_accept_encoding=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 361 | |
Senthil Kumaran | 5dc504c | 2016-09-08 14:28:01 -0700 | [diff] [blame] | 362 | This should be the first call after the connection to the server has been |
| 363 | made. It sends a line to the server consisting of the *method* string, |
| 364 | the *url* string, and the HTTP version (``HTTP/1.1``). To disable automatic |
| 365 | sending of ``Host:`` or ``Accept-Encoding:`` headers (for example to accept |
| 366 | additional content encodings), specify *skip_host* or *skip_accept_encoding* |
| 367 | with non-False values. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 368 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 369 | |
| 370 | .. method:: HTTPConnection.putheader(header, argument[, ...]) |
| 371 | |
| 372 | Send an :rfc:`822`\ -style header to the server. It sends a line to the server |
| 373 | consisting of the header, a colon and a space, and the first argument. If more |
| 374 | arguments are given, continuation lines are sent, each consisting of a tab and |
| 375 | an argument. |
| 376 | |
| 377 | |
Martin Panter | 3c0d0ba | 2016-08-24 06:33:33 +0000 | [diff] [blame] | 378 | .. method:: HTTPConnection.endheaders(message_body=None, *, encode_chunked=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 379 | |
Senthil Kumaran | 5d0de3f | 2011-10-03 07:27:06 +0800 | [diff] [blame] | 380 | Send a blank line to the server, signalling the end of the headers. The |
Senthil Kumaran | ad87fa6 | 2011-10-05 23:26:49 +0800 | [diff] [blame] | 381 | optional *message_body* argument can be used to pass a message body |
Martin Panter | 3c0d0ba | 2016-08-24 06:33:33 +0000 | [diff] [blame] | 382 | associated with the request. |
| 383 | |
| 384 | If *encode_chunked* is ``True``, the result of each iteration of |
| 385 | *message_body* will be chunk-encoded as specified in :rfc:`7230`, |
| 386 | Section 3.3.1. How the data is encoded is dependent on the type of |
| 387 | *message_body*. If *message_body* implements the :ref:`buffer interface |
| 388 | <bufferobjects>` the encoding will result in a single chunk. |
Serhiy Storchaka | 2e576f5 | 2017-04-24 09:05:00 +0300 | [diff] [blame] | 389 | If *message_body* is a :class:`collections.abc.Iterable`, each iteration |
Martin Panter | 3c0d0ba | 2016-08-24 06:33:33 +0000 | [diff] [blame] | 390 | of *message_body* will result in a chunk. If *message_body* is a |
| 391 | :term:`file object`, each call to ``.read()`` will result in a chunk. |
| 392 | The method automatically signals the end of the chunk-encoded data |
| 393 | immediately after *message_body*. |
| 394 | |
| 395 | .. note:: Due to the chunked encoding specification, empty chunks |
| 396 | yielded by an iterator body will be ignored by the chunk-encoder. |
| 397 | This is to avoid premature termination of the read of the request by |
| 398 | the target server due to malformed encoding. |
| 399 | |
| 400 | .. versionadded:: 3.6 |
| 401 | Chunked encoding support. The *encode_chunked* parameter was |
| 402 | added. |
| 403 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 404 | |
| 405 | .. method:: HTTPConnection.send(data) |
| 406 | |
| 407 | Send data to the server. This should be used directly only after the |
| 408 | :meth:`endheaders` method has been called and before :meth:`getresponse` is |
| 409 | called. |
| 410 | |
| 411 | |
| 412 | .. _httpresponse-objects: |
| 413 | |
| 414 | HTTPResponse Objects |
| 415 | -------------------- |
| 416 | |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 417 | An :class:`HTTPResponse` instance wraps the HTTP response from the |
| 418 | server. It provides access to the request headers and the entity |
| 419 | body. The response is an iterable object and can be used in a with |
| 420 | statement. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 421 | |
Martin Panter | ce911c3 | 2016-03-17 06:42:48 +0000 | [diff] [blame] | 422 | .. versionchanged:: 3.5 |
| 423 | The :class:`io.BufferedIOBase` interface is now implemented and |
| 424 | all of its reader operations are supported. |
| 425 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 426 | |
| 427 | .. method:: HTTPResponse.read([amt]) |
| 428 | |
| 429 | Reads and returns the response body, or up to the next *amt* bytes. |
| 430 | |
Antoine Pitrou | 38d9643 | 2011-12-06 22:33:57 +0100 | [diff] [blame] | 431 | .. method:: HTTPResponse.readinto(b) |
| 432 | |
| 433 | Reads up to the next len(b) bytes of the response body into the buffer *b*. |
| 434 | Returns the number of bytes read. |
| 435 | |
| 436 | .. versionadded:: 3.3 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 437 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 438 | .. method:: HTTPResponse.getheader(name, default=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 439 | |
Senthil Kumaran | 790f831 | 2010-08-02 17:09:02 +0000 | [diff] [blame] | 440 | Return the value of the header *name*, or *default* if there is no header |
| 441 | matching *name*. If there is more than one header with the name *name*, |
| 442 | return all of the values joined by ', '. If 'default' is any iterable other |
| 443 | than a single string, its elements are similarly returned joined by commas. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 444 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 445 | .. method:: HTTPResponse.getheaders() |
| 446 | |
| 447 | Return a list of (header, value) tuples. |
| 448 | |
Senthil Kumaran | ceff566 | 2010-09-21 01:57:43 +0000 | [diff] [blame] | 449 | .. method:: HTTPResponse.fileno() |
| 450 | |
| 451 | Return the ``fileno`` of the underlying socket. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 452 | |
| 453 | .. attribute:: HTTPResponse.msg |
| 454 | |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 455 | A :class:`http.client.HTTPMessage` instance containing the response |
| 456 | headers. :class:`http.client.HTTPMessage` is a subclass of |
| 457 | :class:`email.message.Message`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 458 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 459 | .. attribute:: HTTPResponse.version |
| 460 | |
| 461 | HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1. |
| 462 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 463 | .. attribute:: HTTPResponse.status |
| 464 | |
| 465 | Status code returned by server. |
| 466 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 467 | .. attribute:: HTTPResponse.reason |
| 468 | |
| 469 | Reason phrase returned by server. |
| 470 | |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 471 | .. attribute:: HTTPResponse.debuglevel |
| 472 | |
Georg Brandl | ef871f6 | 2010-03-12 10:06:40 +0000 | [diff] [blame] | 473 | A debugging hook. If :attr:`debuglevel` is greater than zero, messages |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 474 | will be printed to stdout as the response is read and parsed. |
| 475 | |
Senthil Kumaran | ce9b596 | 2011-06-19 16:56:49 -0700 | [diff] [blame] | 476 | .. attribute:: HTTPResponse.closed |
| 477 | |
Serhiy Storchaka | fbc1c26 | 2013-11-29 12:17:13 +0200 | [diff] [blame] | 478 | Is ``True`` if the stream is closed. |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 479 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 480 | Examples |
| 481 | -------- |
| 482 | |
| 483 | Here is an example session that uses the ``GET`` method:: |
| 484 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 485 | >>> import http.client |
Benjamin Peterson | ac87ed7 | 2015-05-03 12:59:09 -0400 | [diff] [blame] | 486 | >>> conn = http.client.HTTPSConnection("www.python.org") |
| 487 | >>> conn.request("GET", "/") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 488 | >>> r1 = conn.getresponse() |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 489 | >>> print(r1.status, r1.reason) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 490 | 200 OK |
Senthil Kumaran | ce9b596 | 2011-06-19 16:56:49 -0700 | [diff] [blame] | 491 | >>> data1 = r1.read() # This will return entire content. |
| 492 | >>> # The following example demonstrates reading data in chunks. |
Benjamin Peterson | ac87ed7 | 2015-05-03 12:59:09 -0400 | [diff] [blame] | 493 | >>> conn.request("GET", "/") |
Senthil Kumaran | ce9b596 | 2011-06-19 16:56:49 -0700 | [diff] [blame] | 494 | >>> r1 = conn.getresponse() |
| 495 | >>> while not r1.closed: |
Serhiy Storchaka | dba9039 | 2016-05-10 12:01:23 +0300 | [diff] [blame] | 496 | ... print(r1.read(200)) # 200 bytes |
Benjamin Peterson | ac87ed7 | 2015-05-03 12:59:09 -0400 | [diff] [blame] | 497 | b'<!doctype html>\n<!--[if"... |
Senthil Kumaran | ce9b596 | 2011-06-19 16:56:49 -0700 | [diff] [blame] | 498 | ... |
| 499 | >>> # Example of an invalid request |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 500 | >>> conn.request("GET", "/parrot.spam") |
| 501 | >>> r2 = conn.getresponse() |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 502 | >>> print(r2.status, r2.reason) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 503 | 404 Not Found |
| 504 | >>> data2 = r2.read() |
| 505 | >>> conn.close() |
| 506 | |
Fred Drake | 1587e3d | 2010-05-12 01:36:11 +0000 | [diff] [blame] | 507 | Here is an example session that uses the ``HEAD`` method. Note that the |
| 508 | ``HEAD`` method never returns any data. :: |
Senthil Kumaran | 71fb6c8 | 2010-04-28 17:39:48 +0000 | [diff] [blame] | 509 | |
| 510 | >>> import http.client |
Benjamin Peterson | ac87ed7 | 2015-05-03 12:59:09 -0400 | [diff] [blame] | 511 | >>> conn = http.client.HTTPSConnection("www.python.org") |
| 512 | >>> conn.request("HEAD", "/") |
Senthil Kumaran | 71fb6c8 | 2010-04-28 17:39:48 +0000 | [diff] [blame] | 513 | >>> res = conn.getresponse() |
| 514 | >>> print(res.status, res.reason) |
| 515 | 200 OK |
| 516 | >>> data = res.read() |
| 517 | >>> print(len(data)) |
| 518 | 0 |
| 519 | >>> data == b'' |
| 520 | True |
| 521 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 522 | Here is an example session that shows how to ``POST`` requests:: |
| 523 | |
Senthil Kumaran | aca8fd7 | 2008-06-23 04:41:59 +0000 | [diff] [blame] | 524 | >>> import http.client, urllib.parse |
Senthil Kumaran | 96c84a4 | 2011-07-20 21:56:24 +0800 | [diff] [blame] | 525 | >>> params = urllib.parse.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'}) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 526 | >>> headers = {"Content-type": "application/x-www-form-urlencoded", |
| 527 | ... "Accept": "text/plain"} |
Senthil Kumaran | 96c84a4 | 2011-07-20 21:56:24 +0800 | [diff] [blame] | 528 | >>> conn = http.client.HTTPConnection("bugs.python.org") |
| 529 | >>> conn.request("POST", "", params, headers) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 530 | >>> response = conn.getresponse() |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 531 | >>> print(response.status, response.reason) |
Senthil Kumaran | 96c84a4 | 2011-07-20 21:56:24 +0800 | [diff] [blame] | 532 | 302 Found |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 533 | >>> data = response.read() |
Senthil Kumaran | 96c84a4 | 2011-07-20 21:56:24 +0800 | [diff] [blame] | 534 | >>> data |
| 535 | b'Redirecting to <a href="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 536 | >>> conn.close() |
| 537 | |
Senthil Kumaran | b5fe247 | 2013-03-13 13:38:33 -0700 | [diff] [blame] | 538 | Client side ``HTTP PUT`` requests are very similar to ``POST`` requests. The |
| 539 | difference lies only the server side where HTTP server will allow resources to |
Senthil Kumaran | e66cc81 | 2013-03-13 13:42:47 -0700 | [diff] [blame] | 540 | be created via ``PUT`` request. It should be noted that custom HTTP methods |
| 541 | +are also handled in :class:`urllib.request.Request` by sending the appropriate |
| 542 | +method attribute.Here is an example session that shows how to do ``PUT`` |
| 543 | request using http.client:: |
Senthil Kumaran | b5fe247 | 2013-03-13 13:38:33 -0700 | [diff] [blame] | 544 | |
| 545 | >>> # This creates an HTTP message |
| 546 | >>> # with the content of BODY as the enclosed representation |
Senthil Kumaran | 8b4a272 | 2014-04-16 23:33:02 -0400 | [diff] [blame] | 547 | >>> # for the resource http://localhost:8080/file |
Senthil Kumaran | b5fe247 | 2013-03-13 13:38:33 -0700 | [diff] [blame] | 548 | ... |
| 549 | >>> import http.client |
| 550 | >>> BODY = "***filecontents***" |
| 551 | >>> conn = http.client.HTTPConnection("localhost", 8080) |
| 552 | >>> conn.request("PUT", "/file", BODY) |
| 553 | >>> response = conn.getresponse() |
Georg Brandl | d277a56 | 2013-10-06 12:42:18 +0200 | [diff] [blame] | 554 | >>> print(response.status, response.reason) |
Senthil Kumaran | b5fe247 | 2013-03-13 13:38:33 -0700 | [diff] [blame] | 555 | 200, OK |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 556 | |
| 557 | .. _httpmessage-objects: |
| 558 | |
| 559 | HTTPMessage Objects |
| 560 | ------------------- |
| 561 | |
Benjamin Peterson | 605b9d9 | 2009-04-02 00:24:00 +0000 | [diff] [blame] | 562 | An :class:`http.client.HTTPMessage` instance holds the headers from an HTTP |
| 563 | response. It is implemented using the :class:`email.message.Message` class. |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 564 | |
Benjamin Peterson | 605b9d9 | 2009-04-02 00:24:00 +0000 | [diff] [blame] | 565 | .. XXX Define the methods that clients can depend upon between versions. |