May 9, 2023 · Feb 28, 2023 · Apr 30, 2023 · Apr 30, 2023 · May 2, 2023 · May 2, 2023
diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst
            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
   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
   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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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``).
Copy link Member merwokMay 2, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. This line makes me wonder if`PUT` and`PATCH` are part of «most HTTP methods», so I have to follow the RFC link to see. It seems that yes, only`OPTIONS ` is given as a counter-example. I wonder if there is a way to rephrase that so that casual readers take away that url should nearly always be an absolute path, see link for exact rules. What do other people think? Copy link ContributorAuthor davidfstrMay 3, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. A more specific phrasing would be: The provided url* must be an absolute pathto conform with:rfc:`RFC 2616 §5.1.2 <2616#section-5.1.2>`,unless connecting to an HTTP proxy server orusing the ``OPTIONS`` or ``CONNECT`` methods. And further down: A:rfc:`Host header <2616#section-14.23>` must be providedto conform with:rfc:`RFC 2616 §5.1.2 <2616#section-5.1.2>`,unless connecting to an HTTP proxy server orusing the ``OPTIONS`` or ``CONNECT`` methods. A reader would still have to follow the link to determine the actual rules if they were talking to an HTTP proxy server (somewhat common?) or using`OPTIONS`/`CONNECT` (rare?). Comments? Copy link Member merwokMay 3, 2023• edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. That’s very clear! The`unless` clause could even be in parentheses. I never use proxies but I think there are two cases: explicit proxy, when you send`GET https://authority/path` on a connection opened to`http://proxy` transparent proxy, when you use an HTTP library that respects the`http_proxy` or`https_proxy` environment variables I suppose the note here applies to the first kind only? Copy link ContributorAuthor davidfstrMay 4, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Feedback applied. I think this change is ready to merge! Copy link Member merwokMay 4, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Could you reply to the question about proxy? 🙂 Copy link ContributorAuthor davidfstrMay 5, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. RFC 2616 §1.3 defines a "proxy" as: An intermediary program which acts as both a server and a client for the purpose of making requests on behalf of other clients. Requests are serviced internally or by passing them on, with possible translation, to other servers. A proxy MUST implement both the client and server requirements of this specification. A "transparent proxy" is a proxy that does not modify the request or response beyond what is required for proxy authentication and identification. A "non-transparent proxy" is a proxy that modifies the request or response in order to provide some added service to the user agent, such as group annotation services, media type transformation, protocol reduction, or anonymity filtering. Except where either transparent or non-transparent behavior is explicitly stated, the HTTP proxy requirements apply to both types of proxies. Therefore I speculate that the following requirement from§5.1.2 applies when a Python program attempts to connect toany kind of proxy: The absoluteURI form is REQUIRED when the request is being made to a proxy. I never use proxies myself so I have no empirical experience one way or the other. Copy link Member merwokMay 5, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. OK, let’s hope the people using proxies know how to handle them! davidfstr reacted with thumbs up emoji

		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
Expand All		@@ -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
Expand All		@@ -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
Expand Down