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