Adding mypy annotations throughout the codebase

[pradyunsg]

We adopted the use of mypy in #4545. This issue is for discussing and tracking how we actually want to utilize mypy in pip's codebase.

[agronholm]

Is this really worth the effort, considering pip has no public API and the fact that it increases the maintenance load?

[agronholm]

If the annotations could be added directly to the code, that wouldn't be a problem, but as long as .pyi files must be used...

[pradyunsg]

Is this really worth the effort, considering pip has no public API and the fact that it increases the maintenance load?

Yes. It's a way to catch bugs and serves as useful insight into what a function expects; which helps with the what-is-going-where problem in the codebase.

but as long as .pyi files must be used...

From what I gather, # type: ... comments are enough. I don't see any fancy uses in pip's codebase that would mandate a .pyi. :)

[agronholm]

Alright, that would work then I guess.

[pradyunsg]

As an aside, @agronholm you might want to take a look at how the configuration module is annotated. :)

[pradyunsg]

I've gone ahead and generated stubs for pip via MonkeyType and put them at https://github.com/pradyunsg/pip/tree/experiment/monkeytype-annotations/stubs/pip for now.

I believe they won't be completely correct since they were generated automatically and only using on the code paths covered by the tests. They should, however, serve as a good reference for someone working to add # type: ... comments to the codebase. :)

[pradyunsg]

This issue is a good starting point for anyone who wants to help out with pip's development -- it's simple and the process of fixing this should be a good introduction to pip's development workflow. See the discussion above to understand what the desired fix is.