[BuildStream] Proposal: Consider adding type hints

[Chandan Singh <chandan chandansingh net>]

Hi all,

I wanted to start the conversation about adding type hints (as specified by PEP
484 [1]) to some parts of the BuildStream code.

I know typing in Python can be a sensitive topic at times, so bear with me for
a moment :)

Initially, I think we could consider adding type hints to just the public API
surface. As of now, this only includes Plugin API. (At a later time if we feel
that it has actually been a fruitful exercise, we could also consider expanding
it to include some private API.)

For the public API, we already attempt to add types. However, it is
not covered by
any automated type analyzer given how it is done as part of the docstring.
Switching to type hints would allow one to run static type checkers like
mypy [2], pytype [3] pyright [4] etc. Neither of them is quite perfect just yet
but they are getting better with time.

I have verified that Sphinx also plays well with this. As a bonus, it
automatically adds links to the corresponding class whenever it is used as a
type hint.

I have created a very basic example for the Source class in this patch [5].
This was hacked together in a few minutes, so it is incomplete and somewhat
flawed, but it should give you a flavor of how things might look like.

These type hints could also be beneficial for any downstream plugin authors who
want to statically analyze their plugin's source code.

That about summarizes what I wanted to say. Now, I'd be very interested to hear
about how people feel about this idea.

Thanks,
Chandan

[1]: https://www.python.org/dev/peps/pep-0484/
[2]: http://mypy-lang.org/
[3]: https://github.com/google/pytype
[4]: https://github.com/Microsoft/pyright
[5]: https://gitlab.com/BuildStream/buildstream/commit/db4ace7c3addeacec9483651189516a4a5c16c67