Re: [BuildStream] Proposal: Consider adding type hints

[Tristan Daniël Maat <tristan maat codethink co uk>]

Hi Chandan,

> 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 :)

Awesome! Jim tried this sometime last year as well ([1]), but I suspect we
were dealing with other fires, so it never gained much traction.

This should really not be a very sensitive topic - we already have fixed 
types
for our public API, as you say, this is simply encoding that with a real
language feature so we don't accidentally break our own policy; a
no-brainer really.

Given that we have also stopped supporting python <3.4 (which anyway
accepted type hints syntactically) I don't see a reason not to make this
change.

> 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 do think this change should definitely come with the addition to CI of
a choice of one of these - it would be hard to spot its usefulness without
them.
> 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.
This brings up an interesting point; currently our public API does not
specify what container types like dict or list should contain. Python
actually supports hints like Dict[str, str].

While, to my knowledge, we technically only accept specific types in those
containers, changing that breaks that contract (since someone could have
written plugins with types that quack like ducks, but don't inherit from
ducks). Yet I feel that adding more specific hints would make this more
useful.

Do we want to become more strict about types in our API surface as part
of this change, given that we technically already are that strict?

> That about summarizes what I wanted to say. Now, I'd be very interested to hear
> about how people feel about this idea.
I'm obviously in favor of this (: Let's see what others have to say.
> Thanks,
> Chandan

Thanks,
Tristan

[1]: https://gitlab.com/BuildStream/buildstream/issues/482