[urllib] Add deprecated functions

[donBarbos]

I think if they haven't been removed then they are still being used

[brianschubert]

I think these are maybe better left out. From looking at the history, these are all undocumented functions that weren't meant to be exposed in Python 3:

• https://docs.python.org/2.7/library/urllib.html#:~:text=urllib%20also%20exposes,helper%20functions
• bpo-27485: Rename and deprecate undocumented functions in urllib.parse cpython#2205

[donBarbos]

I think these are maybe better left out. From looking at the history, these are all undocumented functions that weren't meant to be exposed in Python 3:

In my view, these functions are still usable, as I don’t see any clear reason they wouldn’t be compatible with Python 3.x. Additionally, typeshed appears to be more of a reflection of the actual source code than a definitive source of documentation.

[github-actions]

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉

[brianschubert]

As I understand it, these days typeshed's policy is that its generally open to adding undocumented and/or private symbols if they are requested or known to be useful, but generally doesn't try to add all such symbols just because they're present at runtime. Adding undocumented symbols can lead to IDEs suggesting them in autocomplete suggestions and generally can mislead users of type checkers and other tools into thinking that these symbols are/were part of the public API.

Do you happen to know if these functions are actually being used out in the wild? I tried doing a quick search of open source code for them, but I'm only seeing cases them being defined in vendored copies of urllib.

If these do get added to the stubs, I might suggest removing the @deprecated decorator. @deprecated suggests a change in level of support, but these functions were never documented / supported in Python 3. Python 3.8 is just when they started also raising a warning at runtime.

[JelleZijlstra]

If these do get added to the stubs, I might suggest removing the @deprecated decorator. @deprecated suggests a change in level of support, but these functions were never documented / supported in Python 3. Python 3.8 is just when they started also raising a warning at runtime.

I don't agree with this: they raise DeprecationWarning at runtime, so adding @deprecated seems reasonable to me. They've just been deprecated for a long time.

[donBarbos]

I understand your point of view. However, I’m approaching this from the perspective that someone might still be using these functions. So I suggest we wait for the maintainer’s decision.

[JelleZijlstra]

I'm a maintainer and I agree that we should only add these if someone comes to us and tells us they're actually using these functions.

[AlexWaygood]

I am also a maintainer and I agree with Jelle. The reason stubtest has never complained about these being missing from the stub is that they've been deliberately omitted from __all__ at runtime. I'm happy to add them if somebody actually has a use for them, but let's not just add them for completeness's sake :-)

[donBarbos]

I'm a maintainer and I agree that we should only add these if someone comes to us and tells us they're actually using these functions.

I didn't notice your message when I wrote and sent mine