gh-102327: Extend docs for "url" and "headers" parameters to HTTPConnection.request() by davidfstr · Pull Request #102328 · python/cpython

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?

A more specific phrasing would be:

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.

And further down:

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.

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?

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?

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 to any 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.