Add type annotations to urllib3

[tharvik]

Would that be okay if type annotations of urllib3 were added to the typeshed repo?

It would be nice to have your explicit consent, as stated in PEP 484.

[haikuginger]

I personally have no objection, although it'd probably be best for us to double-check the annotation when complete.

[tharvik]

I'll write some and let you know when I open the PR, thanks!

[Lukasa]

I also have no objection, though part of me wonders: if the type checker is now good enough, should we just have stub files here and make them part of our CI?

[tharvik]

Function annotation are only available in python 3, you may want to keep compatibility with python 2 then.

[Lukasa]

@tharvik That's why I'm suggesting stub files: stub files can be distributed with the library without breaking Python 2.

[tharvik]

Ho, misread, yup, that would be better this way, I'll do you a pull request soon then (and by design of typeshed, also copy it there).

[Lukasa]

My understanding of typeshed is that actually they'd rather we distributed it than they did. They shouldn't really need a copy if we ship one.

[tharvik]

Correct, I'm reading PEP 484 again.

From it, we can either have stubs in shared/typehints/python* or alongside the existing python files. What do you prefer?

[tharvik]

From what I just saw, it would be easier to split it by python version, because of much conditional imports and behaviour.

[Lukasa]

I'm happy to split by Python version, at least in the first instance.

[sigmavirus24]

mypy-lang supports using the magical comment annotations, why not use that instead?

[sigmavirus24]

if the type checker is now good enough

@Lukasa mypy-lang is good, yes. But the typing module is still as it was when it was introduced in PEP 484 (primitive).

[shazow]

(No objections here)

[tharvik]

mypy-lang supports using the magical comment annotations, why not use that instead?

@sigmavirus24 we can also do that, but for now, mypy is still quite bad at handling conditional imports, so if we want it to be useful now, it would be better to have splitted stubs.

[and-semakin]

At the current moment mypy is mature and should be considered stable. There are alternative type checkers available such as pyright and pyre. I believe overall Python typing ecosystem is developed enough. Of course there are still some questions to be answered.

urllib3 is the most popular package according to PyPI stats and it is lacking of type hints. I'm pretty sure that adding typing here will evolve all the Python ecosystem. It is definitely worth the effort.

As far as I can see there was an attempt (#880) to add type hints. I think that we should take one more attempt to include it here. I can try to do it for my own or help someone who wants to coordinate the process. What do you think? @tharvik?

[sethmlarson]

I'm 100% on adding type-hints, just needs someone to execute the work. :)

[haikuginger]

I'm also 100% in favor of adding type annotations now. I'd suggest that we do so progressively on our external interfaces (PoolManager methods?) first and then move inwards for additional validation of our more private surfaces.

[shazow]

(Still no objections here)

[pquentin]

Should this be closed in favor of #1897?

[sethmlarson]

Yeah, closing this one :)