| 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 | |
| 14 | 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] | 15 | HTTPS protocols. It is normally not used directly --- the module |
| Georg Brandl | 0f7ede4 | 2008-06-23 11:23:31 +0000 | [diff] [blame] | 16 | :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] | 17 | |
| 18 | .. note:: |
| 19 | |
| 20 | HTTPS support is only available if the :mod:`socket` module was compiled with |
| 21 | SSL support. |
| 22 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 23 | The module provides the following classes: |
| 24 | |
| 25 | |
| 26 | .. class:: HTTPConnection(host[, port[, strict[, timeout]]]) |
| 27 | |
| 28 | An :class:`HTTPConnection` instance represents one transaction with an HTTP |
| Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 29 | server. It should be instantiated passing it a host and optional port |
| 30 | number. If no port number is passed, the port is extracted from the host |
| 31 | string if it has the form ``host:port``, else the default HTTP port (80) is |
| Benjamin Peterson | f608c61 | 2008-11-16 18:33:53 +0000 | [diff] [blame^] | 32 | used. When True, the optional parameter *strict* (which defaults to a false |
| 33 | value) causes ``BadStatusLine`` to |
| Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 34 | be raised if the status line can't be parsed as a valid HTTP/1.0 or 1.1 |
| 35 | status line. If the optional *timeout* parameter is given, blocking |
| 36 | operations (like connection attempts) will timeout after that many seconds |
| Georg Brandl | f78e02b | 2008-06-10 17:40:04 +0000 | [diff] [blame] | 37 | (if it is not given, the global default timeout setting is used). |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 38 | |
| 39 | For example, the following calls all create instances that connect to the server |
| 40 | at the same host and port:: |
| 41 | |
| Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 42 | >>> h1 = http.client.HTTPConnection('www.cwi.nl') |
| 43 | >>> h2 = http.client.HTTPConnection('www.cwi.nl:80') |
| 44 | >>> h3 = http.client.HTTPConnection('www.cwi.nl', 80) |
| 45 | >>> h3 = http.client.HTTPConnection('www.cwi.nl', 80, timeout=10) |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 47 | |
| 48 | .. class:: HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout]]]]]) |
| 49 | |
| 50 | A subclass of :class:`HTTPConnection` that uses SSL for communication with |
| 51 | secure servers. Default port is ``443``. *key_file* is the name of a PEM |
| 52 | formatted file that contains your private key. *cert_file* is a PEM formatted |
| 53 | certificate chain file. |
| 54 | |
| 55 | .. warning:: |
| 56 | |
| 57 | This does not do any certificate verification! |
| 58 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 59 | |
| 60 | .. class:: HTTPResponse(sock[, debuglevel=0][, strict=0]) |
| 61 | |
| 62 | Class whose instances are returned upon successful connection. Not instantiated |
| 63 | directly by user. |
| 64 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | |
| 66 | The following exceptions are raised as appropriate: |
| 67 | |
| 68 | |
| 69 | .. exception:: HTTPException |
| 70 | |
| 71 | The base class of the other exceptions in this module. It is a subclass of |
| 72 | :exc:`Exception`. |
| 73 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | |
| 75 | .. exception:: NotConnected |
| 76 | |
| 77 | A subclass of :exc:`HTTPException`. |
| 78 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | |
| 80 | .. exception:: InvalidURL |
| 81 | |
| 82 | A subclass of :exc:`HTTPException`, raised if a port is given and is either |
| 83 | non-numeric or empty. |
| 84 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | |
| 86 | .. exception:: UnknownProtocol |
| 87 | |
| 88 | A subclass of :exc:`HTTPException`. |
| 89 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | |
| 91 | .. exception:: UnknownTransferEncoding |
| 92 | |
| 93 | A subclass of :exc:`HTTPException`. |
| 94 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 95 | |
| 96 | .. exception:: UnimplementedFileMode |
| 97 | |
| 98 | A subclass of :exc:`HTTPException`. |
| 99 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 100 | |
| 101 | .. exception:: IncompleteRead |
| 102 | |
| 103 | A subclass of :exc:`HTTPException`. |
| 104 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | |
| 106 | .. exception:: ImproperConnectionState |
| 107 | |
| 108 | A subclass of :exc:`HTTPException`. |
| 109 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 110 | |
| 111 | .. exception:: CannotSendRequest |
| 112 | |
| 113 | A subclass of :exc:`ImproperConnectionState`. |
| 114 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | |
| 116 | .. exception:: CannotSendHeader |
| 117 | |
| 118 | A subclass of :exc:`ImproperConnectionState`. |
| 119 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 120 | |
| 121 | .. exception:: ResponseNotReady |
| 122 | |
| 123 | A subclass of :exc:`ImproperConnectionState`. |
| 124 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 125 | |
| 126 | .. exception:: BadStatusLine |
| 127 | |
| 128 | A subclass of :exc:`HTTPException`. Raised if a server responds with a HTTP |
| 129 | status code that we don't understand. |
| 130 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 131 | The constants defined in this module are: |
| 132 | |
| 133 | |
| 134 | .. data:: HTTP_PORT |
| 135 | |
| 136 | The default port for the HTTP protocol (always ``80``). |
| 137 | |
| 138 | |
| 139 | .. data:: HTTPS_PORT |
| 140 | |
| 141 | The default port for the HTTPS protocol (always ``443``). |
| 142 | |
| 143 | and also the following constants for integer status codes: |
| 144 | |
| 145 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 146 | | Constant | Value | Definition | |
| 147 | +==========================================+=========+=======================================================================+ |
| 148 | | :const:`CONTINUE` | ``100`` | HTTP/1.1, `RFC 2616, Section | |
| 149 | | | | 10.1.1 | |
| 150 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.1>`_ | |
| 151 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 152 | | :const:`SWITCHING_PROTOCOLS` | ``101`` | HTTP/1.1, `RFC 2616, Section | |
| 153 | | | | 10.1.2 | |
| 154 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.2>`_ | |
| 155 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 156 | | :const:`PROCESSING` | ``102`` | WEBDAV, `RFC 2518, Section 10.1 | |
| 157 | | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_102>`_ | |
| 158 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 159 | | :const:`OK` | ``200`` | HTTP/1.1, `RFC 2616, Section | |
| 160 | | | | 10.2.1 | |
| 161 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1>`_ | |
| 162 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 163 | | :const:`CREATED` | ``201`` | HTTP/1.1, `RFC 2616, Section | |
| 164 | | | | 10.2.2 | |
| 165 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2>`_ | |
| 166 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 167 | | :const:`ACCEPTED` | ``202`` | HTTP/1.1, `RFC 2616, Section | |
| 168 | | | | 10.2.3 | |
| 169 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3>`_ | |
| 170 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 171 | | :const:`NON_AUTHORITATIVE_INFORMATION` | ``203`` | HTTP/1.1, `RFC 2616, Section | |
| 172 | | | | 10.2.4 | |
| 173 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.4>`_ | |
| 174 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 175 | | :const:`NO_CONTENT` | ``204`` | HTTP/1.1, `RFC 2616, Section | |
| 176 | | | | 10.2.5 | |
| 177 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5>`_ | |
| 178 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 179 | | :const:`RESET_CONTENT` | ``205`` | HTTP/1.1, `RFC 2616, Section | |
| 180 | | | | 10.2.6 | |
| 181 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.6>`_ | |
| 182 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 183 | | :const:`PARTIAL_CONTENT` | ``206`` | HTTP/1.1, `RFC 2616, Section | |
| 184 | | | | 10.2.7 | |
| 185 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.7>`_ | |
| 186 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 187 | | :const:`MULTI_STATUS` | ``207`` | WEBDAV `RFC 2518, Section 10.2 | |
| 188 | | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_207>`_ | |
| 189 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 190 | | :const:`IM_USED` | ``226`` | Delta encoding in HTTP, | |
| 191 | | | | :rfc:`3229`, Section 10.4.1 | |
| 192 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 193 | | :const:`MULTIPLE_CHOICES` | ``300`` | HTTP/1.1, `RFC 2616, Section | |
| 194 | | | | 10.3.1 | |
| 195 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.1>`_ | |
| 196 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 197 | | :const:`MOVED_PERMANENTLY` | ``301`` | HTTP/1.1, `RFC 2616, Section | |
| 198 | | | | 10.3.2 | |
| 199 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2>`_ | |
| 200 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 201 | | :const:`FOUND` | ``302`` | HTTP/1.1, `RFC 2616, Section | |
| 202 | | | | 10.3.3 | |
| 203 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3>`_ | |
| 204 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 205 | | :const:`SEE_OTHER` | ``303`` | HTTP/1.1, `RFC 2616, Section | |
| 206 | | | | 10.3.4 | |
| 207 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.4>`_ | |
| 208 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 209 | | :const:`NOT_MODIFIED` | ``304`` | HTTP/1.1, `RFC 2616, Section | |
| 210 | | | | 10.3.5 | |
| 211 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.5>`_ | |
| 212 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 213 | | :const:`USE_PROXY` | ``305`` | HTTP/1.1, `RFC 2616, Section | |
| 214 | | | | 10.3.6 | |
| 215 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.6>`_ | |
| 216 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 217 | | :const:`TEMPORARY_REDIRECT` | ``307`` | HTTP/1.1, `RFC 2616, Section | |
| 218 | | | | 10.3.8 | |
| 219 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8>`_ | |
| 220 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 221 | | :const:`BAD_REQUEST` | ``400`` | HTTP/1.1, `RFC 2616, Section | |
| 222 | | | | 10.4.1 | |
| 223 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1>`_ | |
| 224 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 225 | | :const:`UNAUTHORIZED` | ``401`` | HTTP/1.1, `RFC 2616, Section | |
| 226 | | | | 10.4.2 | |
| 227 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2>`_ | |
| 228 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 229 | | :const:`PAYMENT_REQUIRED` | ``402`` | HTTP/1.1, `RFC 2616, Section | |
| 230 | | | | 10.4.3 | |
| 231 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.3>`_ | |
| 232 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 233 | | :const:`FORBIDDEN` | ``403`` | HTTP/1.1, `RFC 2616, Section | |
| 234 | | | | 10.4.4 | |
| 235 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4>`_ | |
| 236 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 237 | | :const:`NOT_FOUND` | ``404`` | HTTP/1.1, `RFC 2616, Section | |
| 238 | | | | 10.4.5 | |
| 239 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5>`_ | |
| 240 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 241 | | :const:`METHOD_NOT_ALLOWED` | ``405`` | HTTP/1.1, `RFC 2616, Section | |
| 242 | | | | 10.4.6 | |
| 243 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6>`_ | |
| 244 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 245 | | :const:`NOT_ACCEPTABLE` | ``406`` | HTTP/1.1, `RFC 2616, Section | |
| 246 | | | | 10.4.7 | |
| 247 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7>`_ | |
| 248 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 249 | | :const:`PROXY_AUTHENTICATION_REQUIRED` | ``407`` | HTTP/1.1, `RFC 2616, Section | |
| 250 | | | | 10.4.8 | |
| 251 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.8>`_ | |
| 252 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 253 | | :const:`REQUEST_TIMEOUT` | ``408`` | HTTP/1.1, `RFC 2616, Section | |
| 254 | | | | 10.4.9 | |
| 255 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.9>`_ | |
| 256 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 257 | | :const:`CONFLICT` | ``409`` | HTTP/1.1, `RFC 2616, Section | |
| 258 | | | | 10.4.10 | |
| 259 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10>`_ | |
| 260 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 261 | | :const:`GONE` | ``410`` | HTTP/1.1, `RFC 2616, Section | |
| 262 | | | | 10.4.11 | |
| 263 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.11>`_ | |
| 264 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 265 | | :const:`LENGTH_REQUIRED` | ``411`` | HTTP/1.1, `RFC 2616, Section | |
| 266 | | | | 10.4.12 | |
| 267 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.12>`_ | |
| 268 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 269 | | :const:`PRECONDITION_FAILED` | ``412`` | HTTP/1.1, `RFC 2616, Section | |
| 270 | | | | 10.4.13 | |
| 271 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.13>`_ | |
| 272 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 273 | | :const:`REQUEST_ENTITY_TOO_LARGE` | ``413`` | HTTP/1.1, `RFC 2616, Section | |
| 274 | | | | 10.4.14 | |
| 275 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.14>`_ | |
| 276 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 277 | | :const:`REQUEST_URI_TOO_LONG` | ``414`` | HTTP/1.1, `RFC 2616, Section | |
| 278 | | | | 10.4.15 | |
| 279 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.15>`_ | |
| 280 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 281 | | :const:`UNSUPPORTED_MEDIA_TYPE` | ``415`` | HTTP/1.1, `RFC 2616, Section | |
| 282 | | | | 10.4.16 | |
| 283 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16>`_ | |
| 284 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 285 | | :const:`REQUESTED_RANGE_NOT_SATISFIABLE` | ``416`` | HTTP/1.1, `RFC 2616, Section | |
| 286 | | | | 10.4.17 | |
| 287 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.17>`_ | |
| 288 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 289 | | :const:`EXPECTATION_FAILED` | ``417`` | HTTP/1.1, `RFC 2616, Section | |
| 290 | | | | 10.4.18 | |
| 291 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.18>`_ | |
| 292 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 293 | | :const:`UNPROCESSABLE_ENTITY` | ``422`` | WEBDAV, `RFC 2518, Section 10.3 | |
| 294 | | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_422>`_ | |
| 295 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 296 | | :const:`LOCKED` | ``423`` | WEBDAV `RFC 2518, Section 10.4 | |
| 297 | | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_423>`_ | |
| 298 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 299 | | :const:`FAILED_DEPENDENCY` | ``424`` | WEBDAV, `RFC 2518, Section 10.5 | |
| 300 | | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_424>`_ | |
| 301 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 302 | | :const:`UPGRADE_REQUIRED` | ``426`` | HTTP Upgrade to TLS, | |
| 303 | | | | :rfc:`2817`, Section 6 | |
| 304 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 305 | | :const:`INTERNAL_SERVER_ERROR` | ``500`` | HTTP/1.1, `RFC 2616, Section | |
| 306 | | | | 10.5.1 | |
| 307 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1>`_ | |
| 308 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 309 | | :const:`NOT_IMPLEMENTED` | ``501`` | HTTP/1.1, `RFC 2616, Section | |
| 310 | | | | 10.5.2 | |
| 311 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2>`_ | |
| 312 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 313 | | :const:`BAD_GATEWAY` | ``502`` | HTTP/1.1 `RFC 2616, Section | |
| 314 | | | | 10.5.3 | |
| 315 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.3>`_ | |
| 316 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 317 | | :const:`SERVICE_UNAVAILABLE` | ``503`` | HTTP/1.1, `RFC 2616, Section | |
| 318 | | | | 10.5.4 | |
| 319 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4>`_ | |
| 320 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 321 | | :const:`GATEWAY_TIMEOUT` | ``504`` | HTTP/1.1 `RFC 2616, Section | |
| 322 | | | | 10.5.5 | |
| 323 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5>`_ | |
| 324 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 325 | | :const:`HTTP_VERSION_NOT_SUPPORTED` | ``505`` | HTTP/1.1, `RFC 2616, Section | |
| 326 | | | | 10.5.6 | |
| 327 | | | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.6>`_ | |
| 328 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 329 | | :const:`INSUFFICIENT_STORAGE` | ``507`` | WEBDAV, `RFC 2518, Section 10.6 | |
| 330 | | | | <http://www.webdav.org/specs/rfc2518.html#STATUS_507>`_ | |
| 331 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 332 | | :const:`NOT_EXTENDED` | ``510`` | An HTTP Extension Framework, | |
| 333 | | | | :rfc:`2774`, Section 7 | |
| 334 | +------------------------------------------+---------+-----------------------------------------------------------------------+ |
| 335 | |
| 336 | |
| 337 | .. data:: responses |
| 338 | |
| 339 | This dictionary maps the HTTP 1.1 status codes to the W3C names. |
| 340 | |
| Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 341 | Example: ``http.client.responses[http.client.NOT_FOUND]`` is ``'Not Found'``. |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 342 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 343 | |
| 344 | .. _httpconnection-objects: |
| 345 | |
| 346 | HTTPConnection Objects |
| 347 | ---------------------- |
| 348 | |
| 349 | :class:`HTTPConnection` instances have the following methods: |
| 350 | |
| 351 | |
| 352 | .. method:: HTTPConnection.request(method, url[, body[, headers]]) |
| 353 | |
| 354 | This will send a request to the server using the HTTP request method *method* |
| 355 | and the selector *url*. If the *body* argument is present, it should be a |
| 356 | string of data to send after the headers are finished. Alternatively, it may |
| 357 | be an open file object, in which case the contents of the file is sent; this |
| 358 | file object should support ``fileno()`` and ``read()`` methods. The header |
| 359 | Content-Length is automatically set to the correct value. The *headers* |
| 360 | argument should be a mapping of extra HTTP headers to send with the request. |
| 361 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 362 | |
| 363 | .. method:: HTTPConnection.getresponse() |
| 364 | |
| 365 | Should be called after a request is sent to get the response from the server. |
| 366 | Returns an :class:`HTTPResponse` instance. |
| 367 | |
| 368 | .. note:: |
| 369 | |
| 370 | Note that you must have read the whole response before you can send a new |
| 371 | request to the server. |
| 372 | |
| 373 | |
| 374 | .. method:: HTTPConnection.set_debuglevel(level) |
| 375 | |
| 376 | Set the debugging level (the amount of debugging output printed). The default |
| 377 | debug level is ``0``, meaning no debugging output is printed. |
| 378 | |
| 379 | |
| 380 | .. method:: HTTPConnection.connect() |
| 381 | |
| 382 | Connect to the server specified when the object was created. |
| 383 | |
| 384 | |
| 385 | .. method:: HTTPConnection.close() |
| 386 | |
| 387 | Close the connection to the server. |
| 388 | |
| 389 | As an alternative to using the :meth:`request` method described above, you can |
| 390 | also send your request step by step, by using the four functions below. |
| 391 | |
| 392 | |
| 393 | .. method:: HTTPConnection.putrequest(request, selector[, skip_host[, skip_accept_encoding]]) |
| 394 | |
| 395 | This should be the first call after the connection to the server has been made. |
| 396 | It sends a line to the server consisting of the *request* string, the *selector* |
| 397 | string, and the HTTP version (``HTTP/1.1``). To disable automatic sending of |
| 398 | ``Host:`` or ``Accept-Encoding:`` headers (for example to accept additional |
| 399 | content encodings), specify *skip_host* or *skip_accept_encoding* with non-False |
| 400 | values. |
| 401 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 402 | |
| 403 | .. method:: HTTPConnection.putheader(header, argument[, ...]) |
| 404 | |
| 405 | Send an :rfc:`822`\ -style header to the server. It sends a line to the server |
| 406 | consisting of the header, a colon and a space, and the first argument. If more |
| 407 | arguments are given, continuation lines are sent, each consisting of a tab and |
| 408 | an argument. |
| 409 | |
| 410 | |
| 411 | .. method:: HTTPConnection.endheaders() |
| 412 | |
| 413 | Send a blank line to the server, signalling the end of the headers. |
| 414 | |
| 415 | |
| 416 | .. method:: HTTPConnection.send(data) |
| 417 | |
| 418 | Send data to the server. This should be used directly only after the |
| 419 | :meth:`endheaders` method has been called and before :meth:`getresponse` is |
| 420 | called. |
| 421 | |
| 422 | |
| 423 | .. _httpresponse-objects: |
| 424 | |
| 425 | HTTPResponse Objects |
| 426 | -------------------- |
| 427 | |
| 428 | :class:`HTTPResponse` instances have the following methods and attributes: |
| 429 | |
| 430 | |
| 431 | .. method:: HTTPResponse.read([amt]) |
| 432 | |
| 433 | Reads and returns the response body, or up to the next *amt* bytes. |
| 434 | |
| 435 | |
| 436 | .. method:: HTTPResponse.getheader(name[, default]) |
| 437 | |
| 438 | Get the contents of the header *name*, or *default* if there is no matching |
| 439 | header. |
| 440 | |
| 441 | |
| 442 | .. method:: HTTPResponse.getheaders() |
| 443 | |
| 444 | Return a list of (header, value) tuples. |
| 445 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 446 | |
| 447 | .. attribute:: HTTPResponse.msg |
| 448 | |
| Georg Brandl | 83e9f4c | 2008-06-12 18:52:31 +0000 | [diff] [blame] | 449 | An :class:`email.message.Message` instance containing the response headers. |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 450 | |
| 451 | |
| 452 | .. attribute:: HTTPResponse.version |
| 453 | |
| 454 | HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1. |
| 455 | |
| 456 | |
| 457 | .. attribute:: HTTPResponse.status |
| 458 | |
| 459 | Status code returned by server. |
| 460 | |
| 461 | |
| 462 | .. attribute:: HTTPResponse.reason |
| 463 | |
| 464 | Reason phrase returned by server. |
| 465 | |
| 466 | |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 467 | Examples |
| 468 | -------- |
| 469 | |
| 470 | Here is an example session that uses the ``GET`` method:: |
| 471 | |
| Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 472 | >>> import http.client |
| 473 | >>> conn = http.client.HTTPConnection("www.python.org") |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 474 | >>> conn.request("GET", "/index.html") |
| 475 | >>> r1 = conn.getresponse() |
| Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 476 | >>> print(r1.status, r1.reason) |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 477 | 200 OK |
| 478 | >>> data1 = r1.read() |
| 479 | >>> conn.request("GET", "/parrot.spam") |
| 480 | >>> r2 = conn.getresponse() |
| Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 481 | >>> print(r2.status, r2.reason) |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 482 | 404 Not Found |
| 483 | >>> data2 = r2.read() |
| 484 | >>> conn.close() |
| 485 | |
| 486 | Here is an example session that shows how to ``POST`` requests:: |
| 487 | |
| Senthil Kumaran | aca8fd7 | 2008-06-23 04:41:59 +0000 | [diff] [blame] | 488 | >>> import http.client, urllib.parse |
| 489 | >>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0}) |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 490 | >>> headers = {"Content-type": "application/x-www-form-urlencoded", |
| 491 | ... "Accept": "text/plain"} |
| Georg Brandl | 2442015 | 2008-05-26 16:32:26 +0000 | [diff] [blame] | 492 | >>> conn = http.client.HTTPConnection("musi-cal.mojam.com:80") |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 493 | >>> conn.request("POST", "/cgi-bin/query", params, headers) |
| 494 | >>> response = conn.getresponse() |
| Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 495 | >>> print(response.status, response.reason) |
| Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 496 | 200 OK |
| 497 | >>> data = response.read() |
| 498 | >>> conn.close() |
| 499 | |