Documentation

The current documentation forHTTPConnection.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 ashttps://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 themethod andurl parameters verbatim:

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

According toRFC 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 wasgenerating 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