Pygithub: Add type anontations for mypy (etc.)

[PeterJCLaw]

It would be great if PyGithub had type annotations for its types. This would enable users to build safer code around it as well as improving editor suggestions. As PyGithub already has a well defined type hierarchy there are already types which could be used, which is great.

(I actually originally assumed from the description that PyGithub was annotated and was surprised that it wasn't).

Is this something you've considered and/or would be open to?

[zer0tonin]

If the maintainers are ok with this idea, I wouldn't mind working on it.

[sfdye]

I am okay with this, but it's not gonna a small effort. Perhaps before this we should upgrade the project to Python 3 (since Python2 is going away soon), so we can use the Python3 style type annotations everywhere.

[trickeydan]

It is possible to use tools like https://github.com/Instagram/MonkeyType to apply type annotations inline from a stub file. So potentially, we could begin working on writing stubs, and then apply them inline after dropping support for Py2.

[zer0tonin]

Ok, I've actually started working on @trickeydan idea. I generated stubs files by running MonkeyType against the unittest and wrote them to .piy files next to the .py files. It will require checking all the stubs by hand because MonkeyType seems to have missed a few details here and there sadly (so it might take a while).

I think it will also be required to exported more or less every type we have in the module's __init__.py for people to include PyGithub's type in their typechecks.

If anyone is interested you can check the progress here : https://github.com/zer0tonin/PyGithub/tree/agg/type_stubs

Only issue I have noticed so far is that urllib3 doesn't seem to have any typing info available and sadly we use a few of their types.

[sfdye]

@zer0tonin Let's keep the ball rolling. Why not opening a PR from your branch, so we can have a review.

urllib3 is only used for the Retry function, which is recently introduced in #1002. Let's see how we can add stub to urllib3 later.

[sfdye]

Closed in #1231
CI enforcement will be added in #1442