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