Add mypy type hints

[alex-torok]

It would be great if pybuildkite shipped with type stubs included so that consuming projects could use mypy to ensure that they are using valid fields/functions on pybuildkite objects

I was inspired by PyGithub's most recent release shipping with pyi stub files included with the package. They are still in the process of updating their CI process to keep the pyi files up-to-date with the source code.

I'd be willing to help out with getting the type information in pybuildkite, but was wondering what kind of approach would you want to take? .pyi files, or in-line type hints -- any desire to keep python 2 compatibility?

[pyasi]

This is a great idea, something I've wanted for some time! I think my last release started getting the ball rolling with getting the package itself typed (and enforcing it in CI).

I have not intention on holding on to python 2 compatibility. My preference is towards in-line type hints, but I'd love to know if the .pyi implementation makes it easier for consumers of the package. Ultimately we should do whatever works better for users.

[alex-torok]

From my understanding, functional reasons for choosing pyi files is mainly to preserve python2 compatibility. pygithub only recently dropped python2 support, and I'm guessing that the typing work had already started before then. Also for larger and more active projects, I'd imagine it is easier to introduce typing in separate files.

.pyi stub files seem to be chosen for a few reasons:

• adding type info to c bindings
• Adding type info through a secondary *-typing package if maintainers don't want to take on type hints
• Some people just like the look of python without type hints inline & want to keep the type info separate

[pyasi]

With that information, and given my personal preference for type safety in the code as a means for development. I'd say we move forward implementing the inline type hints.