From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> Date: Tue, 9 May 2023 20:00:58 +0000 (-0700) Subject: [3.11] gh-102327: Extend docs for "url" and "headers" parameters to HTTPConnection... X-Git-Tag: v3.11.4~93 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=fffdbf483140c1abfd2bba2da363af6fba0987b1;p=thirdparty%2FPython%2Fcpython.git [3.11] gh-102327: Extend docs for "url" and "headers" parameters to HTTPConnection.request() gh-102327: Extend docs for "url" and "headers" parameters to HTTPConnection.request() Added example on how to use the HTTPConnection object for making GET request. Original issue: https://github.com/python/cpython/issues/102327 --------- (cherry picked from commit 7ba6288feb961fcd60a29415c6371d2d3eb80bec) Co-authored-by: David Foster Co-authored-by: Éric --- diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index 9aeb07fade82..df99ab99826e 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -262,7 +262,10 @@ HTTPConnection Objects encode_chunked=False) This will send a request to the server using the HTTP request - method *method* and the selector *url*. + method *method* and the request URI *url*. The provided *url* must be + an absolute path to conform with :rfc:`RFC 2616 §5.1.2 <2616#section-5.1.2>` + (unless connecting to an HTTP proxy server or using the ``OPTIONS`` or + ``CONNECT`` methods). If *body* is specified, the specified data is sent after the headers are finished. It may be a :class:`str`, a :term:`bytes-like object`, an @@ -277,7 +280,10 @@ HTTPConnection Objects iterable are sent as is until the iterable is exhausted. The *headers* argument should be a mapping of extra HTTP headers to send - with the request. + with the request. A :rfc:`Host header <2616#section-14.23>` + must be provided to conform with :rfc:`RFC 2616 §5.1.2 <2616#section-5.1.2>` + (unless connecting to an HTTP proxy server or using the ``OPTIONS`` or + ``CONNECT`` methods). If *headers* contains neither Content-Length nor Transfer-Encoding, but there is a request body, one of those @@ -296,6 +302,16 @@ HTTPConnection Objects HTTPConnection object assumes that all encoding is handled by the calling code. If it is ``True``, the body will be chunk-encoded. + For example, to perform a ``GET`` request to ``https://docs.python.org/3/``:: + + >>> import http.client + >>> host = "docs.python.org" + >>> conn = http.client.HTTPSConnection(host) + >>> conn.request("GET", "/3/", headers={"Host": host}) + >>> response = conn.getresponse() + >>> print(response.status, response.reason) + 200 OK + .. note:: Chunked transfer encoding has been added to the HTTP protocol version 1.1. Unless the HTTP server is known to handle HTTP 1.1,