Clarify that "url" parameter to HTTPConnection.request(method, url) is usually an absolute path

[davidfstr]

Documentation

The current documentation for HTTPConnection.request(method, url) looks like:

---

---

No description of the "url" parameter is provided besides its name. One might easily assume (as I did originally) that an absolute URL such as https://xkcd.com was expected here.

However if you look at how the request() method is implemented, you'll notice that it creates an HTTP request line using the method and url parameters verbatim:

• For example: HTTPConnection.request("GET", "/") will create an HTTP request beginning with GET / HTTP/1.1.
• And HTTPConnection.request("GET", "https://xkcd.com") will create an HTTP request beginning with GET https://xkcd.com HTTP/1.1.

According to RFC 2616 §5.1.2, (1) the "url" in the above examples must be an absolute path (like /) and (2) the "Host" header must be provided.

I recently discovered that a website downloader program of mine was generating improper HTTP requests that were confusing WordPress sites because I was incorrectly passing an absolute URL as the "url" parameter to request() rather than passing an absolute path.

I think it would be worth extending the documentation to explain the above constraints on the "url" parameter (and the requirement of the "Host" header), so that it is easier to use the request() method correctly to generate a well-formed HTTP request.

I already have a PR proposing specific changes, which I will post shortly.

Linked PRs

• gh-102327: Extend docs for "url" and "headers" parameters to HTTPConnection.request() #102328
• [3.11] gh-102327: Extend docs for "url" and "headers" parameters to HTTPConnection.request() #104339

[davidfstr]

Hello, is there a reviewer with expertise in the http.client documentation that is available to review the PR associated with this issue?

(I am posting this ping >1 month after no activity, as recommended by the dev guide.)

[Mariatta]

Thanks for the PR. I've merged it and it will be backported to 3.11.