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 | |
| 7 | |
| 8 | .. index:: |
| 9 | pair: HTTP; protocol |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 10 | single: HTTP; http.client (standard module) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | |
Senthil Kumaran | aca8fd7 | 2008-06-23 04:41:59 +0000 | [diff] [blame] | 12 | .. index:: module: urllib.request |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 14 | **Source code:** :source:`Lib/http/client.py` |
| 15 | |
| 16 | -------------- |
| 17 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 18 | 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] | 19 | HTTPS protocols. It is normally not used directly --- the module |
Georg Brandl | 0f7ede4 | 2008-06-23 11:23:31 +0000 | [diff] [blame] | 20 | :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] | 21 | |
| 22 | .. note:: |
| 23 | |
Antoine Pitrou | 1ab19ca | 2010-10-13 10:39:21 +0000 | [diff] [blame] | 24 | HTTPS support is only available if Python was compiled with SSL support |
| 25 | (through the :mod:`ssl` module). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 27 | The module provides the following classes: |
| 28 | |
| 29 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 30 | .. class:: HTTPConnection(host, port=None[, strict][, timeout], \ |
| 31 | source_address=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 32 | |
| 33 | An :class:`HTTPConnection` instance represents one transaction with an HTTP |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 34 | server. It should be instantiated passing it a host and optional port |
| 35 | number. If no port number is passed, the port is extracted from the host |
| 36 | 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] | 37 | used. If the optional *timeout* parameter is given, blocking |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 38 | operations (like connection attempts) will timeout after that many seconds |
Georg Brandl | f78e02b | 2008-06-10 17:40:04 +0000 | [diff] [blame] | 39 | (if it is not given, the global default timeout setting is used). |
Raymond Hettinger | 519c308 | 2011-01-30 00:39:00 +0000 | [diff] [blame] | 40 | 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] | 41 | to use as the source address the HTTP connection is made from. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 42 | |
| 43 | For example, the following calls all create instances that connect to the server |
| 44 | at the same host and port:: |
| 45 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 46 | >>> h1 = http.client.HTTPConnection('www.cwi.nl') |
| 47 | >>> h2 = http.client.HTTPConnection('www.cwi.nl:80') |
| 48 | >>> h3 = http.client.HTTPConnection('www.cwi.nl', 80) |
| 49 | >>> h3 = http.client.HTTPConnection('www.cwi.nl', 80, timeout=10) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 50 | |
Gregory P. Smith | b406637 | 2010-01-03 03:28:29 +0000 | [diff] [blame] | 51 | .. versionchanged:: 3.2 |
| 52 | *source_address* was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 53 | |
Antoine Pitrou | 988dbd7 | 2010-12-17 17:35:56 +0000 | [diff] [blame] | 54 | .. versionchanged:: 3.2 |
| 55 | The *strict* parameter is deprecated. HTTP 0.9-style "Simple Responses" |
| 56 | are not supported anymore. |
Gregory P. Smith | b406637 | 2010-01-03 03:28:29 +0000 | [diff] [blame] | 57 | |
Antoine Pitrou | 988dbd7 | 2010-12-17 17:35:56 +0000 | [diff] [blame] | 58 | |
Ezio Melotti | e0add76 | 2012-09-14 06:32:35 +0300 | [diff] [blame] | 59 | .. class:: HTTPSConnection(host, port=None, key_file=None, \ |
| 60 | cert_file=None[, strict][, timeout], \ |
| 61 | source_address=None, *, context=None, \ |
| 62 | check_hostname=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 63 | |
| 64 | A subclass of :class:`HTTPConnection` that uses SSL for communication with |
Antoine Pitrou | 803e6d6 | 2010-10-13 10:36:15 +0000 | [diff] [blame] | 65 | secure servers. Default port is ``443``. If *context* is specified, it |
| 66 | must be a :class:`ssl.SSLContext` instance describing the various SSL |
| 67 | options. If *context* is specified and has a :attr:`~ssl.SSLContext.verify_mode` |
| 68 | of either :data:`~ssl.CERT_OPTIONAL` or :data:`~ssl.CERT_REQUIRED`, then |
| 69 | by default *host* is matched against the host name(s) allowed by the |
| 70 | server's certificate. If you want to change that behaviour, you can |
| 71 | explicitly set *check_hostname* to False. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | |
Antoine Pitrou | 803e6d6 | 2010-10-13 10:36:15 +0000 | [diff] [blame] | 73 | *key_file* and *cert_file* are deprecated, please use |
| 74 | :meth:`ssl.SSLContext.load_cert_chain` instead. |
| 75 | |
| 76 | If you access arbitrary hosts on the Internet, it is recommended to |
| 77 | require certificate checking and feed the *context* with a set of |
| 78 | trusted CA certificates:: |
| 79 | |
| 80 | context = ssl.SSLContext(ssl.PROTOCOL_TLSv1) |
| 81 | context.verify_mode = ssl.CERT_REQUIRED |
| 82 | context.load_verify_locations('/etc/pki/tls/certs/ca-bundle.crt') |
| 83 | h = client.HTTPSConnection('svn.python.org', 443, context=context) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
Gregory P. Smith | b406637 | 2010-01-03 03:28:29 +0000 | [diff] [blame] | 85 | .. versionchanged:: 3.2 |
Antoine Pitrou | 803e6d6 | 2010-10-13 10:36:15 +0000 | [diff] [blame] | 86 | *source_address*, *context* and *check_hostname* were added. |
Gregory P. Smith | b406637 | 2010-01-03 03:28:29 +0000 | [diff] [blame] | 87 | |
Antoine Pitrou | d532321 | 2010-10-22 18:19:07 +0000 | [diff] [blame] | 88 | .. versionchanged:: 3.2 |
| 89 | This class now supports HTTPS virtual hosts if possible (that is, |
| 90 | if :data:`ssl.HAS_SNI` is true). |
| 91 | |
Antoine Pitrou | 988dbd7 | 2010-12-17 17:35:56 +0000 | [diff] [blame] | 92 | .. versionchanged:: 3.2 |
| 93 | The *strict* parameter is deprecated. HTTP 0.9-style "Simple Responses" |
| 94 | are not supported anymore. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 95 | |
Antoine Pitrou | 988dbd7 | 2010-12-17 17:35:56 +0000 | [diff] [blame] | 96 | |
| 97 | .. class:: HTTPResponse(sock, debuglevel=0[, strict], method=None, url=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 98 | |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 99 | Class whose instances are returned upon successful connection. Not |
| 100 | instantiated directly by user. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 101 | |
Antoine Pitrou | 988dbd7 | 2010-12-17 17:35:56 +0000 | [diff] [blame] | 102 | .. versionchanged:: 3.2 |
| 103 | The *strict* parameter is deprecated. HTTP 0.9-style "Simple Responses" |
| 104 | are not supported anymore. |
| 105 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 106 | |
| 107 | The following exceptions are raised as appropriate: |
| 108 | |
| 109 | |
| 110 | .. exception:: HTTPException |
| 111 | |
| 112 | The base class of the other exceptions in this module. It is a subclass of |
| 113 | :exc:`Exception`. |
| 114 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | |
| 116 | .. exception:: NotConnected |
| 117 | |
| 118 | A subclass of :exc:`HTTPException`. |
| 119 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 120 | |
| 121 | .. exception:: InvalidURL |
| 122 | |
| 123 | A subclass of :exc:`HTTPException`, raised if a port is given and is either |
| 124 | non-numeric or empty. |
| 125 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | .. exception:: UnknownProtocol |
| 128 | |
| 129 | A subclass of :exc:`HTTPException`. |
| 130 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 131 | |
| 132 | .. exception:: UnknownTransferEncoding |
| 133 | |
| 134 | A subclass of :exc:`HTTPException`. |
| 135 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 136 | |
| 137 | .. exception:: UnimplementedFileMode |
| 138 | |
| 139 | A subclass of :exc:`HTTPException`. |
| 140 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 141 | |
| 142 | .. exception:: IncompleteRead |
| 143 | |
| 144 | A subclass of :exc:`HTTPException`. |
| 145 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 146 | |
| 147 | .. exception:: ImproperConnectionState |
| 148 | |
| 149 | A subclass of :exc:`HTTPException`. |
| 150 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | |
| 152 | .. exception:: CannotSendRequest |
| 153 | |
| 154 | A subclass of :exc:`ImproperConnectionState`. |
| 155 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 156 | |
| 157 | .. exception:: CannotSendHeader |
| 158 | |
| 159 | A subclass of :exc:`ImproperConnectionState`. |
| 160 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 161 | |
| 162 | .. exception:: ResponseNotReady |
| 163 | |
| 164 | A subclass of :exc:`ImproperConnectionState`. |
| 165 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 166 | |
| 167 | .. exception:: BadStatusLine |
| 168 | |
| 169 | A subclass of :exc:`HTTPException`. Raised if a server responds with a HTTP |
| 170 | status code that we don't understand. |
| 171 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 172 | The constants defined in this module are: |
| 173 | |
| 174 | |
| 175 | .. data:: HTTP_PORT |
| 176 | |
| 177 | The default port for the HTTP protocol (always ``80``). |
| 178 | |
| 179 | |
| 180 | .. data:: HTTPS_PORT |
| 181 | |
| 182 | The default port for the HTTPS protocol (always ``443``). |
| 183 | |
| 184 | and also the following constants for integer status codes: |
| 185 | |
| 186 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 187 | | Constant | Value | Definition | |
| 188 | +==========================================+=========+=======================================================================+ |
| 189 | | :const:`CONTINUE` | ``100`` | HTTP/1.1, `RFC 2616, Section | |
| 190 | | | | 10.1.1 | |
| 191 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.1>`_ | |
| 192 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 193 | | :const:`SWITCHING_PROTOCOLS` | ``101`` | HTTP/1.1, `RFC 2616, Section | |
| 194 | | | | 10.1.2 | |
| 195 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.2>`_ | |
| 196 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 197 | | :const:`PROCESSING` | ``102`` | WEBDAV, `RFC 2518, Section 10.1 | |
| 198 | | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_102>`_ | |
| 199 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 200 | | :const:`OK` | ``200`` | HTTP/1.1, `RFC 2616, Section | |
| 201 | | | | 10.2.1 | |
| 202 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1>`_ | |
| 203 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 204 | | :const:`CREATED` | ``201`` | HTTP/1.1, `RFC 2616, Section | |
| 205 | | | | 10.2.2 | |
| 206 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2>`_ | |
| 207 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 208 | | :const:`ACCEPTED` | ``202`` | HTTP/1.1, `RFC 2616, Section | |
| 209 | | | | 10.2.3 | |
| 210 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3>`_ | |
| 211 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 212 | | :const:`NON_AUTHORITATIVE_INFORMATION` | ``203`` | HTTP/1.1, `RFC 2616, Section | |
| 213 | | | | 10.2.4 | |
| 214 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.4>`_ | |
| 215 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 216 | | :const:`NO_CONTENT` | ``204`` | HTTP/1.1, `RFC 2616, Section | |
| 217 | | | | 10.2.5 | |
| 218 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5>`_ | |
| 219 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 220 | | :const:`RESET_CONTENT` | ``205`` | HTTP/1.1, `RFC 2616, Section | |
| 221 | | | | 10.2.6 | |
| 222 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.6>`_ | |
| 223 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 224 | | :const:`PARTIAL_CONTENT` | ``206`` | HTTP/1.1, `RFC 2616, Section | |
| 225 | | | | 10.2.7 | |
| 226 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.7>`_ | |
| 227 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 228 | | :const:`MULTI_STATUS` | ``207`` | WEBDAV `RFC 2518, Section 10.2 | |
| 229 | | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_207>`_ | |
| 230 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 231 | | :const:`IM_USED` | ``226`` | Delta encoding in HTTP, | |
| 232 | | | | :rfc:`3229`, Section 10.4.1 | |
| 233 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 234 | | :const:`MULTIPLE_CHOICES` | ``300`` | HTTP/1.1, `RFC 2616, Section | |
| 235 | | | | 10.3.1 | |
| 236 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.1>`_ | |
| 237 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 238 | | :const:`MOVED_PERMANENTLY` | ``301`` | HTTP/1.1, `RFC 2616, Section | |
| 239 | | | | 10.3.2 | |
| 240 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2>`_ | |
| 241 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 242 | | :const:`FOUND` | ``302`` | HTTP/1.1, `RFC 2616, Section | |
| 243 | | | | 10.3.3 | |
| 244 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3>`_ | |
| 245 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 246 | | :const:`SEE_OTHER` | ``303`` | HTTP/1.1, `RFC 2616, Section | |
| 247 | | | | 10.3.4 | |
| 248 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.4>`_ | |
| 249 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 250 | | :const:`NOT_MODIFIED` | ``304`` | HTTP/1.1, `RFC 2616, Section | |
| 251 | | | | 10.3.5 | |
| 252 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.5>`_ | |
| 253 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 254 | | :const:`USE_PROXY` | ``305`` | HTTP/1.1, `RFC 2616, Section | |
| 255 | | | | 10.3.6 | |
| 256 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.6>`_ | |
| 257 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 258 | | :const:`TEMPORARY_REDIRECT` | ``307`` | HTTP/1.1, `RFC 2616, Section | |
| 259 | | | | 10.3.8 | |
| 260 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8>`_ | |
| 261 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 262 | | :const:`BAD_REQUEST` | ``400`` | HTTP/1.1, `RFC 2616, Section | |
| 263 | | | | 10.4.1 | |
| 264 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1>`_ | |
| 265 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 266 | | :const:`UNAUTHORIZED` | ``401`` | HTTP/1.1, `RFC 2616, Section | |
| 267 | | | | 10.4.2 | |
| 268 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2>`_ | |
| 269 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 270 | | :const:`PAYMENT_REQUIRED` | ``402`` | HTTP/1.1, `RFC 2616, Section | |
| 271 | | | | 10.4.3 | |
| 272 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.3>`_ | |
| 273 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 274 | | :const:`FORBIDDEN` | ``403`` | HTTP/1.1, `RFC 2616, Section | |
| 275 | | | | 10.4.4 | |
| 276 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4>`_ | |
| 277 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 278 | | :const:`NOT_FOUND` | ``404`` | HTTP/1.1, `RFC 2616, Section | |
| 279 | | | | 10.4.5 | |
| 280 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5>`_ | |
| 281 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 282 | | :const:`METHOD_NOT_ALLOWED` | ``405`` | HTTP/1.1, `RFC 2616, Section | |
| 283 | | | | 10.4.6 | |
| 284 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6>`_ | |
| 285 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 286 | | :const:`NOT_ACCEPTABLE` | ``406`` | HTTP/1.1, `RFC 2616, Section | |
| 287 | | | | 10.4.7 | |
| 288 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7>`_ | |
| 289 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 290 | | :const:`PROXY_AUTHENTICATION_REQUIRED` | ``407`` | HTTP/1.1, `RFC 2616, Section | |
| 291 | | | | 10.4.8 | |
| 292 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.8>`_ | |
| 293 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 294 | | :const:`REQUEST_TIMEOUT` | ``408`` | HTTP/1.1, `RFC 2616, Section | |
| 295 | | | | 10.4.9 | |
| 296 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.9>`_ | |
| 297 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 298 | | :const:`CONFLICT` | ``409`` | HTTP/1.1, `RFC 2616, Section | |
| 299 | | | | 10.4.10 | |
| 300 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10>`_ | |
| 301 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 302 | | :const:`GONE` | ``410`` | HTTP/1.1, `RFC 2616, Section | |
| 303 | | | | 10.4.11 | |
| 304 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.11>`_ | |
| 305 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 306 | | :const:`LENGTH_REQUIRED` | ``411`` | HTTP/1.1, `RFC 2616, Section | |
| 307 | | | | 10.4.12 | |
| 308 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.12>`_ | |
| 309 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 310 | | :const:`PRECONDITION_FAILED` | ``412`` | HTTP/1.1, `RFC 2616, Section | |
| 311 | | | | 10.4.13 | |
| 312 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.13>`_ | |
| 313 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 314 | | :const:`REQUEST_ENTITY_TOO_LARGE` | ``413`` | HTTP/1.1, `RFC 2616, Section | |
| 315 | | | | 10.4.14 | |
| 316 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.14>`_ | |
| 317 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 318 | | :const:`REQUEST_URI_TOO_LONG` | ``414`` | HTTP/1.1, `RFC 2616, Section | |
| 319 | | | | 10.4.15 | |
| 320 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.15>`_ | |
| 321 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 322 | | :const:`UNSUPPORTED_MEDIA_TYPE` | ``415`` | HTTP/1.1, `RFC 2616, Section | |
| 323 | | | | 10.4.16 | |
| 324 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16>`_ | |
| 325 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 326 | | :const:`REQUESTED_RANGE_NOT_SATISFIABLE` | ``416`` | HTTP/1.1, `RFC 2616, Section | |
| 327 | | | | 10.4.17 | |
| 328 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.17>`_ | |
| 329 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 330 | | :const:`EXPECTATION_FAILED` | ``417`` | HTTP/1.1, `RFC 2616, Section | |
| 331 | | | | 10.4.18 | |
| 332 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.18>`_ | |
| 333 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 334 | | :const:`UNPROCESSABLE_ENTITY` | ``422`` | WEBDAV, `RFC 2518, Section 10.3 | |
| 335 | | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_422>`_ | |
| 336 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 337 | | :const:`LOCKED` | ``423`` | WEBDAV `RFC 2518, Section 10.4 | |
| 338 | | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_423>`_ | |
| 339 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 340 | | :const:`FAILED_DEPENDENCY` | ``424`` | WEBDAV, `RFC 2518, Section 10.5 | |
| 341 | | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_424>`_ | |
| 342 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 343 | | :const:`UPGRADE_REQUIRED` | ``426`` | HTTP Upgrade to TLS, | |
| 344 | | | | :rfc:`2817`, Section 6 | |
| 345 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
Hynek Schlawack | 51b2ed5 | 2012-05-16 09:51:07 +0200 | [diff] [blame] | 346 | | :const:`PRECONDITION_REQUIRED` | ``428`` | Additional HTTP Status Codes, | |
| 347 | | | | :rfc:`6585`, Section 3 | |
| 348 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 349 | | :const:`TOO_MANY_REQUESTS` | ``429`` | Additional HTTP Status Codes, | |
| 350 | | | | :rfc:`6585`, Section 4 | |
| 351 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 352 | | :const:`REQUEST_HEADER_FIELDS_TOO_LARGE` | ``431`` | Additional HTTP Status Codes, | |
| 353 | | | | :rfc:`6585`, Section 5 | |
| 354 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 355 | | :const:`INTERNAL_SERVER_ERROR` | ``500`` | HTTP/1.1, `RFC 2616, Section | |
| 356 | | | | 10.5.1 | |
| 357 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1>`_ | |
| 358 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 359 | | :const:`NOT_IMPLEMENTED` | ``501`` | HTTP/1.1, `RFC 2616, Section | |
| 360 | | | | 10.5.2 | |
| 361 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2>`_ | |
| 362 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 363 | | :const:`BAD_GATEWAY` | ``502`` | HTTP/1.1 `RFC 2616, Section | |
| 364 | | | | 10.5.3 | |
| 365 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.3>`_ | |
| 366 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 367 | | :const:`SERVICE_UNAVAILABLE` | ``503`` | HTTP/1.1, `RFC 2616, Section | |
| 368 | | | | 10.5.4 | |
| 369 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4>`_ | |
| 370 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 371 | | :const:`GATEWAY_TIMEOUT` | ``504`` | HTTP/1.1 `RFC 2616, Section | |
| 372 | | | | 10.5.5 | |
| 373 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5>`_ | |
| 374 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 375 | | :const:`HTTP_VERSION_NOT_SUPPORTED` | ``505`` | HTTP/1.1, `RFC 2616, Section | |
| 376 | | | | 10.5.6 | |
| 377 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.6>`_ | |
| 378 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 379 | | :const:`INSUFFICIENT_STORAGE` | ``507`` | WEBDAV, `RFC 2518, Section 10.6 | |
| 380 | | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_507>`_ | |
| 381 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 382 | | :const:`NOT_EXTENDED` | ``510`` | An HTTP Extension Framework, | |
| 383 | | | | :rfc:`2774`, Section 7 | |
| 384 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
Hynek Schlawack | 51b2ed5 | 2012-05-16 09:51:07 +0200 | [diff] [blame] | 385 | | :const:`NETWORK_AUTHENTICATION_REQUIRED` | ``511`` | Additional HTTP Status Codes, | |
| 386 | | | | :rfc:`6585`, Section 6 | |
| 387 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 388 | |
Georg Brandl | 945a3ad | 2012-05-21 20:28:58 +0200 | [diff] [blame] | 389 | .. versionchanged:: 3.3 |
| 390 | Added codes ``428``, ``429``, ``431`` and ``511`` from :rfc:`6585`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 391 | |
| 392 | |
| 393 | .. data:: responses |
| 394 | |
| 395 | This dictionary maps the HTTP 1.1 status codes to the W3C names. |
| 396 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 397 | Example: ``http.client.responses[http.client.NOT_FOUND]`` is ``'Not Found'``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 398 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 399 | |
| 400 | .. _httpconnection-objects: |
| 401 | |
| 402 | HTTPConnection Objects |
| 403 | ---------------------- |
| 404 | |
| 405 | :class:`HTTPConnection` instances have the following methods: |
| 406 | |
| 407 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 408 | .. method:: HTTPConnection.request(method, url, body=None, headers={}) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 409 | |
Jeremy Hylton | 236654b | 2009-03-27 20:24:34 +0000 | [diff] [blame] | 410 | This will send a request to the server using the HTTP request |
| 411 | method *method* and the selector *url*. If the *body* argument is |
| 412 | present, it should be string or bytes object of data to send after |
| 413 | the headers are finished. Strings are encoded as ISO-8859-1, the |
| 414 | default charset for HTTP. To use other encodings, pass a bytes |
| 415 | object. The Content-Length header is set to the length of the |
| 416 | string. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 417 | |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 418 | The *body* may also be an open :term:`file object`, in which case the |
Senthil Kumaran | 7bc0d87 | 2010-12-19 10:49:52 +0000 | [diff] [blame] | 419 | contents of the file is sent; this file object should support ``fileno()`` |
| 420 | and ``read()`` methods. The header Content-Length is automatically set to |
| 421 | the length of the file as reported by stat. The *body* argument may also be |
Raymond Hettinger | 519c308 | 2011-01-30 00:39:00 +0000 | [diff] [blame] | 422 | an iterable and Content-Length header should be explicitly provided when the |
Senthil Kumaran | 7bc0d87 | 2010-12-19 10:49:52 +0000 | [diff] [blame] | 423 | body is an iterable. |
Jeremy Hylton | 236654b | 2009-03-27 20:24:34 +0000 | [diff] [blame] | 424 | |
| 425 | The *headers* argument should be a mapping of extra HTTP |
| 426 | headers to send with the request. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 427 | |
Senthil Kumaran | 7bc0d87 | 2010-12-19 10:49:52 +0000 | [diff] [blame] | 428 | .. versionadded:: 3.2 |
Georg Brandl | 09a7df8 | 2010-12-19 12:33:52 +0000 | [diff] [blame] | 429 | *body* can now be an iterable. |
Senthil Kumaran | 7bc0d87 | 2010-12-19 10:49:52 +0000 | [diff] [blame] | 430 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 431 | .. method:: HTTPConnection.getresponse() |
| 432 | |
| 433 | Should be called after a request is sent to get the response from the server. |
| 434 | Returns an :class:`HTTPResponse` instance. |
| 435 | |
| 436 | .. note:: |
| 437 | |
| 438 | Note that you must have read the whole response before you can send a new |
| 439 | request to the server. |
| 440 | |
| 441 | |
| 442 | .. method:: HTTPConnection.set_debuglevel(level) |
| 443 | |
R. David Murray | d89bc3f | 2010-12-15 02:19:14 +0000 | [diff] [blame] | 444 | Set the debugging level. The default debug level is ``0``, meaning no |
| 445 | debugging output is printed. Any value greater than ``0`` will cause all |
| 446 | currently defined debug output to be printed to stdout. The ``debuglevel`` |
| 447 | is passed to any new :class:`HTTPResponse` objects that are created. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 448 | |
Mark Dickinson | 574b1d6 | 2009-10-01 20:20:09 +0000 | [diff] [blame] | 449 | .. versionadded:: 3.1 |
Benjamin Peterson | fa0d703 | 2009-06-01 22:42:33 +0000 | [diff] [blame] | 450 | |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 451 | |
Senthil Kumaran | 7e5229c | 2009-12-20 07:31:21 +0000 | [diff] [blame] | 452 | .. method:: HTTPConnection.set_tunnel(host, port=None, headers=None) |
Senthil Kumaran | 97f0c6b | 2009-07-25 04:24:38 +0000 | [diff] [blame] | 453 | |
| 454 | Set the host and the port for HTTP Connect Tunnelling. Normally used when it |
| 455 | is required to a HTTPS Connection through a proxy server. |
| 456 | |
Sandro Tosi | 44f568c | 2011-12-25 11:44:38 +0100 | [diff] [blame] | 457 | The headers argument should be a mapping of extra HTTP headers to send |
Senthil Kumaran | 7e5229c | 2009-12-20 07:31:21 +0000 | [diff] [blame] | 458 | with the CONNECT request. |
| 459 | |
Senthil Kumaran | 2e910fd | 2009-07-25 04:27:38 +0000 | [diff] [blame] | 460 | .. versionadded:: 3.2 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 461 | |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 462 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 463 | .. method:: HTTPConnection.connect() |
| 464 | |
| 465 | Connect to the server specified when the object was created. |
| 466 | |
| 467 | |
| 468 | .. method:: HTTPConnection.close() |
| 469 | |
| 470 | Close the connection to the server. |
| 471 | |
| 472 | As an alternative to using the :meth:`request` method described above, you can |
| 473 | also send your request step by step, by using the four functions below. |
| 474 | |
| 475 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 476 | .. method:: HTTPConnection.putrequest(request, selector, skip_host=False, skip_accept_encoding=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 477 | |
| 478 | This should be the first call after the connection to the server has been made. |
| 479 | It sends a line to the server consisting of the *request* string, the *selector* |
| 480 | string, and the HTTP version (``HTTP/1.1``). To disable automatic sending of |
| 481 | ``Host:`` or ``Accept-Encoding:`` headers (for example to accept additional |
| 482 | content encodings), specify *skip_host* or *skip_accept_encoding* with non-False |
| 483 | values. |
| 484 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 485 | |
| 486 | .. method:: HTTPConnection.putheader(header, argument[, ...]) |
| 487 | |
| 488 | Send an :rfc:`822`\ -style header to the server. It sends a line to the server |
| 489 | consisting of the header, a colon and a space, and the first argument. If more |
| 490 | arguments are given, continuation lines are sent, each consisting of a tab and |
| 491 | an argument. |
| 492 | |
| 493 | |
Senthil Kumaran | 5d0de3f | 2011-10-03 07:27:06 +0800 | [diff] [blame] | 494 | .. method:: HTTPConnection.endheaders(message_body=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 495 | |
Senthil Kumaran | 5d0de3f | 2011-10-03 07:27:06 +0800 | [diff] [blame] | 496 | 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] | 497 | optional *message_body* argument can be used to pass a message body |
| 498 | associated with the request. The message body will be sent in the same |
| 499 | packet as the message headers if it is string, otherwise it is sent in a |
| 500 | separate packet. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 501 | |
| 502 | .. method:: HTTPConnection.send(data) |
| 503 | |
| 504 | Send data to the server. This should be used directly only after the |
| 505 | :meth:`endheaders` method has been called and before :meth:`getresponse` is |
| 506 | called. |
| 507 | |
| 508 | |
| 509 | .. _httpresponse-objects: |
| 510 | |
| 511 | HTTPResponse Objects |
| 512 | -------------------- |
| 513 | |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 514 | An :class:`HTTPResponse` instance wraps the HTTP response from the |
| 515 | server. It provides access to the request headers and the entity |
| 516 | body. The response is an iterable object and can be used in a with |
| 517 | statement. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 518 | |
| 519 | |
| 520 | .. method:: HTTPResponse.read([amt]) |
| 521 | |
| 522 | Reads and returns the response body, or up to the next *amt* bytes. |
| 523 | |
Antoine Pitrou | 38d9643 | 2011-12-06 22:33:57 +0100 | [diff] [blame] | 524 | .. method:: HTTPResponse.readinto(b) |
| 525 | |
| 526 | Reads up to the next len(b) bytes of the response body into the buffer *b*. |
| 527 | Returns the number of bytes read. |
| 528 | |
| 529 | .. versionadded:: 3.3 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 530 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 531 | .. method:: HTTPResponse.getheader(name, default=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 532 | |
Senthil Kumaran | 790f831 | 2010-08-02 17:09:02 +0000 | [diff] [blame] | 533 | Return the value of the header *name*, or *default* if there is no header |
| 534 | matching *name*. If there is more than one header with the name *name*, |
| 535 | return all of the values joined by ', '. If 'default' is any iterable other |
| 536 | than a single string, its elements are similarly returned joined by commas. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 537 | |
| 538 | |
| 539 | .. method:: HTTPResponse.getheaders() |
| 540 | |
| 541 | Return a list of (header, value) tuples. |
| 542 | |
Senthil Kumaran | ceff566 | 2010-09-21 01:57:43 +0000 | [diff] [blame] | 543 | .. method:: HTTPResponse.fileno() |
| 544 | |
| 545 | Return the ``fileno`` of the underlying socket. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 546 | |
| 547 | .. attribute:: HTTPResponse.msg |
| 548 | |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 549 | A :class:`http.client.HTTPMessage` instance containing the response |
| 550 | headers. :class:`http.client.HTTPMessage` is a subclass of |
| 551 | :class:`email.message.Message`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 552 | |
| 553 | |
| 554 | .. attribute:: HTTPResponse.version |
| 555 | |
| 556 | HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1. |
| 557 | |
| 558 | |
| 559 | .. attribute:: HTTPResponse.status |
| 560 | |
| 561 | Status code returned by server. |
| 562 | |
| 563 | |
| 564 | .. attribute:: HTTPResponse.reason |
| 565 | |
| 566 | Reason phrase returned by server. |
| 567 | |
| 568 | |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 569 | .. attribute:: HTTPResponse.debuglevel |
| 570 | |
Georg Brandl | ef871f6 | 2010-03-12 10:06:40 +0000 | [diff] [blame] | 571 | A debugging hook. If :attr:`debuglevel` is greater than zero, messages |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 572 | will be printed to stdout as the response is read and parsed. |
| 573 | |
Senthil Kumaran | ce9b596 | 2011-06-19 16:56:49 -0700 | [diff] [blame] | 574 | .. attribute:: HTTPResponse.closed |
| 575 | |
Senthil Kumaran | fd8d7e9 | 2011-06-19 16:59:41 -0700 | [diff] [blame] | 576 | Is True if the stream is closed. |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 577 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 578 | Examples |
| 579 | -------- |
| 580 | |
| 581 | Here is an example session that uses the ``GET`` method:: |
| 582 | |
Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 583 | >>> import http.client |
| 584 | >>> conn = http.client.HTTPConnection("www.python.org") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 585 | >>> conn.request("GET", "/index.html") |
| 586 | >>> r1 = conn.getresponse() |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 587 | >>> print(r1.status, r1.reason) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 588 | 200 OK |
Senthil Kumaran | ce9b596 | 2011-06-19 16:56:49 -0700 | [diff] [blame] | 589 | >>> data1 = r1.read() # This will return entire content. |
| 590 | >>> # The following example demonstrates reading data in chunks. |
| 591 | >>> conn.request("GET", "/index.html") |
| 592 | >>> r1 = conn.getresponse() |
| 593 | >>> while not r1.closed: |
| 594 | ... print(r1.read(200)) # 200 bytes |
| 595 | b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"... |
| 596 | ... |
| 597 | >>> # Example of an invalid request |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 598 | >>> conn.request("GET", "/parrot.spam") |
| 599 | >>> r2 = conn.getresponse() |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 600 | >>> print(r2.status, r2.reason) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 601 | 404 Not Found |
| 602 | >>> data2 = r2.read() |
| 603 | >>> conn.close() |
| 604 | |
Fred Drake | 1587e3d | 2010-05-12 01:36:11 +0000 | [diff] [blame] | 605 | Here is an example session that uses the ``HEAD`` method. Note that the |
| 606 | ``HEAD`` method never returns any data. :: |
Senthil Kumaran | 71fb6c8 | 2010-04-28 17:39:48 +0000 | [diff] [blame] | 607 | |
| 608 | >>> import http.client |
| 609 | >>> conn = http.client.HTTPConnection("www.python.org") |
| 610 | >>> conn.request("HEAD","/index.html") |
| 611 | >>> res = conn.getresponse() |
| 612 | >>> print(res.status, res.reason) |
| 613 | 200 OK |
| 614 | >>> data = res.read() |
| 615 | >>> print(len(data)) |
| 616 | 0 |
| 617 | >>> data == b'' |
| 618 | True |
| 619 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 620 | Here is an example session that shows how to ``POST`` requests:: |
| 621 | |
Senthil Kumaran | aca8fd7 | 2008-06-23 04:41:59 +0000 | [diff] [blame] | 622 | >>> import http.client, urllib.parse |
Senthil Kumaran | 96c84a4 | 2011-07-20 21:56:24 +0800 | [diff] [blame] | 623 | >>> params = urllib.parse.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'}) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 624 | >>> headers = {"Content-type": "application/x-www-form-urlencoded", |
| 625 | ... "Accept": "text/plain"} |
Senthil Kumaran | 96c84a4 | 2011-07-20 21:56:24 +0800 | [diff] [blame] | 626 | >>> conn = http.client.HTTPConnection("bugs.python.org") |
| 627 | >>> conn.request("POST", "", params, headers) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 628 | >>> response = conn.getresponse() |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 629 | >>> print(response.status, response.reason) |
Senthil Kumaran | 96c84a4 | 2011-07-20 21:56:24 +0800 | [diff] [blame] | 630 | 302 Found |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 631 | >>> data = response.read() |
Senthil Kumaran | 96c84a4 | 2011-07-20 21:56:24 +0800 | [diff] [blame] | 632 | >>> data |
| 633 | 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] | 634 | >>> conn.close() |
| 635 | |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 636 | |
| 637 | .. _httpmessage-objects: |
| 638 | |
| 639 | HTTPMessage Objects |
| 640 | ------------------- |
| 641 | |
Benjamin Peterson | 605b9d9 | 2009-04-02 00:24:00 +0000 | [diff] [blame] | 642 | An :class:`http.client.HTTPMessage` instance holds the headers from an HTTP |
| 643 | response. It is implemented using the :class:`email.message.Message` class. |
Jeremy Hylton | 1052f89 | 2009-03-31 14:40:19 +0000 | [diff] [blame] | 644 | |
Benjamin Peterson | 605b9d9 | 2009-04-02 00:24:00 +0000 | [diff] [blame] | 645 | .. XXX Define the methods that clients can depend upon between versions. |