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