Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Closed
davidfstr opened this issue Feb 28, 2023 · 2 comments
Closed

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

davidfstr opened this issue Feb 28, 2023 · 2 comments
Labels
docs Documentation in the Doc dir

Comments

@davidfstr
Copy link
Contributor

davidfstr commented Feb 28, 2023 •
edited by bedevere-bot
Loading

Documentation

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

Screen Shot 2023-02-28 at 8 56 01 AM

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
@davidfstr davidfstr added the docs Documentation in the Doc dir label Feb 28, 2023
@davidfstr davidfstr changed the title Clarify that "url" parameter to HTTPConnection.request(method, url) is usually not an URL Clarify that "url" parameter to HTTPConnection.request(method, url) is usually an absolute path Feb 28, 2023
@davidfstr davidfstr mentioned this issue Feb 28, 2023
Merged
davidfstr added a commit to davidfstr/cpython that referenced this issue Apr 4, 2023
@davidfstr
Document "url" parameter to HTTPConnection.request() (python#102327)
86275f8
@davidfstr
Copy link
Contributor Author

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 pushed a commit that referenced this issue May 9, 2023
@davidfstr @merwok
gh-102327: Extend docs for "url" and "headers" parameters to HTTPConn…
7ba6288 
…ection.request()

Added example on how to use the HTTPConnection object for making GET request.

Original issue: #102327

---------

Co-authored-by: Éric <earaujo@caravan.coop>
@miss-islington miss-islington mentioned this issue May 9, 2023
Merged
miss-islington pushed a commit to miss-islington/cpython that referenced this issue May 9, 2023
@davidfstr @merwok @miss-islington
pythongh-102327: Extend docs for "url" and "headers" parameters to HT…
395d089 
…TPConnection.request()

Added example on how to use the HTTPConnection object for making GET request.

Original issue: python#102327

---------

(cherry picked from commit 7ba6288)

Co-authored-by: David Foster <david@dafoster.net>
Co-authored-by: Éric <earaujo@caravan.coop>
Mariatta pushed a commit that referenced this issue May 9, 2023
@miss-islington @davidfstr @merwok
[3.11] gh-102327: Extend docs for "url" and "headers" parameters to H…
fffdbf4 
…TTPConnection.request()

gh-102327: Extend docs for "url" and "headers" parameters to HTTPConnection.request()

Added example on how to use the HTTPConnection object for making GET request.

Original issue: #102327

---------

(cherry picked from commit 7ba6288)

Co-authored-by: David Foster <david@dafoster.net>
Co-authored-by: Éric <earaujo@caravan.coop>
@Mariatta
Copy link
Member

Mariatta commented May 9, 2023

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

@Mariatta Mariatta closed this as completed May 9, 2023
carljm added a commit to carljm/cpython that referenced this issue May 10, 2023
@carljm
Merge branch 'main' into fixloadsuperspec
5976df9 
* main:
  pythonGH-102181: Improve specialization stats for SEND (pythonGH-102182)
  pythongh-103000: Optimise `dataclasses.asdict` for the common case (python#104364)
  pythongh-103538: Remove unused TK_AQUA code (pythonGH-103539)
  pythonGH-87695: Fix OSError from `pathlib.Path.glob()` (pythonGH-104292)
  pythongh-104263: Rely on Py_NAN and introduce Py_INFINITY (pythonGH-104202)
  pythongh-104010: Separate and improve docs for `typing.get_origin` and `typing.get_args` (python#104013)
  pythongh-101819: Adapt _io._BufferedIOBase_Type methods to Argument Clinic (python#104355)
  pythongh-103960: Dark mode: invert image brightness (python#103983)
  pythongh-104252: Immortalize Py_EMPTY_KEYS (pythongh-104253)
  pythongh-101819: Clean up _io windows console io after pythongh-104197 (python#104354)
  pythongh-101819: Harden _io init (python#104352)
  pythongh-103247: clear the module cache in a test in test_importlib/extensions/test_loader.py (pythonGH-104226)
  pythongh-103848: Adds checks to ensure that bracketed hosts found by urlsplit are of IPv6 or IPvFuture format (python#103849)
  pythongh-74895: adjust tests to work on Solaris (python#104326)
  pythongh-101819: Refactor _io in preparation for module isolation (python#104334)
  pythongh-90953: Don't use deprecated AST nodes in clinic.py (python#104322)
  pythongh-102327: Extend docs for "url" and "headers" parameters to HTTPConnection.request()
  pythongh-104328: Fix typo in ``typing.Generic`` multiple inheritance error message (python#104335)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs Documentation in the Doc dir
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@davidfstr @Mariatta