From 86275f8b4cbbaf4f141b64a8649694552cf94027 Mon Sep 17 00:00:00 2001 From: David Foster Date: Tue, 28 Feb 2023 09:19:19 -0500 Subject: [PATCH 1/8] Document "url" parameter to HTTPConnection.request() (#102327) --- Doc/library/http.client.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index ad3416135e307b..4dffa891969ead 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -264,7 +264,7 @@ 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*. 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 @@ -293,6 +293,22 @@ HTTPConnection Objects Transfer-Encoding header will automatically be set instead of Content-Length. + .. note:: + When using most HTTP methods (like ``GET`` or ``POST``) + the provided ``url`` must be an absolute path and + a ``Host`` header must be provided to conform with + :rfc:`2616#section-5.1.2`. + + For example, to perform a ``GET`` request to ``https://xkcd.com/353/``:: + + >>> import http.client + >>> host = "xkcd.com" + >>> conn = http.client.HTTPSConnection(host) + >>> conn.request("GET", "/353/", headers={"Host": host}) + >>> response = conn.getresponse() + >>> print(response.status, response.reason) + 200 OK + The *encode_chunked* argument is only relevant if Transfer-Encoding is specified in *headers*. If *encode_chunked* is ``False``, the HTTPConnection object assumes that all encoding is handled by the From 912df17e0a6623a7786f703f9f28a3dc7ae9e8db Mon Sep 17 00:00:00 2001 From: David Foster Date: Sat, 29 Apr 2023 20:42:47 -0400 Subject: [PATCH 2/8] Alter example URL to be: https://docs.python.org/3/ --- Doc/library/http.client.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index 4dffa891969ead..10b3fa6d26a02e 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -299,12 +299,12 @@ HTTPConnection Objects a ``Host`` header must be provided to conform with :rfc:`2616#section-5.1.2`. - For example, to perform a ``GET`` request to ``https://xkcd.com/353/``:: + For example, to perform a ``GET`` request to ``https://docs.python.org/3/``:: >>> import http.client - >>> host = "xkcd.com" + >>> host = "docs.python.org" >>> conn = http.client.HTTPSConnection(host) - >>> conn.request("GET", "/353/", headers={"Host": host}) + >>> conn.request("GET", "/3/", headers={"Host": host}) >>> response = conn.getresponse() >>> print(response.status, response.reason) 200 OK From 9013cd314fcb9cea4b2e0386b350830898893c5b Mon Sep 17 00:00:00 2001 From: David Foster Date: Sun, 30 Apr 2023 08:51:24 -0400 Subject: [PATCH 3/8] Alter RFC section link to appear with more-natural formatting --- Doc/library/http.client.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index 10b3fa6d26a02e..3305e25034b7e4 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -297,7 +297,7 @@ HTTPConnection Objects When using most HTTP methods (like ``GET`` or ``POST``) the provided ``url`` must be an absolute path and a ``Host`` header must be provided to conform with - :rfc:`2616#section-5.1.2`. + :rfc:`RFC 2616 §5.1.2 <2616#section-5.1.2>`. For example, to perform a ``GET`` request to ``https://docs.python.org/3/``:: From c0960c6963112a5505f2a5de7509e031b887b521 Mon Sep 17 00:00:00 2001 From: David Foster Date: Tue, 2 May 2023 09:29:00 -0400 Subject: [PATCH 4/8] Distribute new documentation to relevant parameter paragraphs --- Doc/library/http.client.rst | 34 ++++++++++++++++------------------ 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index 3305e25034b7e4..b717f264ed3f0b 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -264,7 +264,9 @@ HTTPConnection Objects encode_chunked=False) This will send a request to the server using the HTTP request - method *method* and the request URI *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>` + when using most HTTP methods (like ``GET`` or ``POST``). 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 @@ -279,7 +281,9 @@ 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>` + when using most HTTP methods (like ``GET`` or ``POST``). If *headers* contains neither Content-Length nor Transfer-Encoding, but there is a request body, one of those @@ -293,26 +297,20 @@ HTTPConnection Objects Transfer-Encoding header will automatically be set instead of Content-Length. - .. note:: - When using most HTTP methods (like ``GET`` or ``POST``) - the provided ``url`` must be an absolute path and - a ``Host`` header must be provided to conform with - :rfc:`RFC 2616 §5.1.2 <2616#section-5.1.2>`. - - 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 - The *encode_chunked* argument is only relevant if Transfer-Encoding is specified in *headers*. If *encode_chunked* is ``False``, the 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 From 231bd9e98dee8fd7f6ec9353c786469f2904556c Mon Sep 17 00:00:00 2001 From: David Foster Date: Tue, 2 May 2023 09:33:58 -0400 Subject: [PATCH 5/8] Adjust formatting --- Doc/library/http.client.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index b717f264ed3f0b..2250e96d7d5c4e 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -264,7 +264,7 @@ HTTPConnection Objects encode_chunked=False) This will send a request to the server using the HTTP request - method *method* and the request URI *url*. The provided URL must be + 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>` when using most HTTP methods (like ``GET`` or ``POST``). From 5a6293d65e8ee7df047b83f741ed6e9b529e9acb Mon Sep 17 00:00:00 2001 From: David Foster Date: Tue, 2 May 2023 09:35:46 -0400 Subject: [PATCH 6/8] Fix trailing whitespace --- Doc/library/http.client.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index 2250e96d7d5c4e..6d75d24df5a128 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -264,7 +264,7 @@ HTTPConnection Objects encode_chunked=False) This will send a request to the server using the HTTP request - method *method* and the request URI *url*. The provided *url* must be + 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>` when using most HTTP methods (like ``GET`` or ``POST``). @@ -301,7 +301,7 @@ HTTPConnection Objects specified in *headers*. If *encode_chunked* is ``False``, the 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 From e6dc07c4a2e9e1e1caee10bfdb927743eb18ae6d Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 4 May 2023 08:57:00 -0400 Subject: [PATCH 7/8] Clarify phrasing for when absolute paths are required --- Doc/library/http.client.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index 6d75d24df5a128..c4be8afac6a0dc 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -266,7 +266,8 @@ HTTPConnection Objects This will send a request to the server using the HTTP request 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>` - when using most HTTP methods (like ``GET`` or ``POST``). + (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 @@ -283,7 +284,8 @@ HTTPConnection Objects The *headers* argument should be a mapping of extra HTTP headers to send 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>` - when using most HTTP methods (like ``GET`` or ``POST``). + (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 From dcf248011d505a8155d8d49529b8f18b886c4961 Mon Sep 17 00:00:00 2001 From: David Foster Date: Thu, 4 May 2023 08:58:33 -0400 Subject: [PATCH 8/8] Fix whitespace --- Doc/library/http.client.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index c4be8afac6a0dc..4be8e02d8f5cf3 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -284,7 +284,7 @@ HTTPConnection Objects The *headers* argument should be a mapping of extra HTTP headers to send 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 + (unless connecting to an HTTP proxy server or using the ``OPTIONS`` or ``CONNECT`` methods). If *headers* contains neither Content-Length nor Transfer-Encoding,