Deprecate urllib3.request module

[hramezani]

Context

After adding the top-level request() method, We have a function named request in urllib3.__init__.py and a module named request(urllib3.request.py). It changes the from request import request behavior.

• Old behavior: importing request module.
• New behavior: importing request function.

Possible Solution

• We could rename the request module to urllib3.request_methods and add a deprecated module urllib3.request.
• We have to raise an AttributeError when accessing request.RequestMethods

Contribution

Would you be willing to submit a PR?
(Help can be provided if you need assistance submitting a PR)

[bluetech]

IMO it would also be good to deprecate or remove RequestMethods itself.

Reasons:

1. It is currently public API (appears in the API reference), but I somewhat doubt any external user is using it directly (please correct me if I'm wrong!). It might be done just to have the methods documented, but in this case I'd suggest using Sphinx :inherited-members: on the subclasses, so that the methods show up directly on the subclasses.

2. IMO, while mixins such as RequestMethods can save some repetition, they end up doing more harm than good. Searching the internet with keywords "inheritance", "mixin", "composition", "harmful" will turn up dozens of results, so I won't repeat it here. More concretely, the problems in urllib3 manifest in the form of type: ignores on urlopen, or making implementing such as Allow specifying pool headers which are not overridden by request-specific headers #2254 harder than they should be.

3. It makes the code a bit harder to navigate IMO (instead of tracing through functions, need to jump to the superclass and then back to the subclass).

It should be straightforward to use simple pure helper functions instead of the mixin. For example request_encode_url would become prepare_request_encode_url which returns the arguments to urlopen instead of actually calling it, and PoolManager and HTTPConnectionPool would use that helper to implement request_encode_url.

(Sorry for hijacking this issue, can move to a new one if you prefer)

[pquentin]

This is all very true, unfortunately urllib3 painted itself into a corner by documenting its internals as public APIs.

[atodorov]

Probably it's the same issue but following the instructions from the website:

>>> import urllib3
>>> resp = urllib3.request("GET", "https://httpbin.org/robots.txt")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'module' object is not callable

Not a good first-user experience. At least update the documentation.

[sethmlarson]

@atodorov Sorry that happened! Where did you find the link to those docs btw?

We just recently fixed URLs on the 1.26.x Github branch to point at 1.26.x on readthedocs instead latest because as you've found it has features documented that aren't released yet.

[atodorov]

https://urllib3.readthedocs.io/en/latest/index.html

[pquentin]

@atodorov As mentioned by @sethmlarson above, we know that latest points to the unreleased v2, while https://urllib3.readthedocs.io/en/stable/ and https://urllib3.readthedocs.io/en/1.26.x/ will show you the docs of the current released version.

Where did you get your link?

[atodorov]

Where did you get your link?

Not really sure. I see that when I google "urllib3" the link goes to the docs for the stable version. IDK how I ended up on the documentation for the devel version. The only thing I remember was that it didn't take me long. I see that the website URL in GitHub repo settings points to the devel version. Badge icons in README do too.