Use of type hints in Python3 code

[portante]

Let's discuss how we want to consider rolling out the use of Python3 type hints. They were added in Python 3.5, and currently our lowest supported version of Python3 is 3.6. So we should be safe to add them in all the code.

I'd propose that existing PRs created prior to this discussion would not have to be changed to add them.

But for all future PRs, what should the policy be? We also require the use of type hints?

[dbutenhof]

I started applying type hints in my tracking database PR, so we already have code on main using them. At Webb's reminder, I'd also already added hints to my endpoints configure API.

We should definitely start using them for new code. TBD how we work around / adapt existing code, but we should move in that direction as it makes reading code much easier.

[webbnh]

I hate Python type hints: I think they are ugly, confusing, and they make the function signatures bloated and hard to read.

That said, I cannot deny (and do prize!) their power, and I think that using them is better than not using them. And...I'm sure that, after awhile, I will get used to them....

As for how to get there, I would propose the following:

• all new code (code which adds new function definitions) should use them in the function definition, for parameters and return type. (We can give current open PR's a "bye".)
• any change which modifies an existing function signature should add them to all the parameters and the return type.
• any change which significantly modifies an existing function body, should be encouraged to add them to the signature.
• for small changes we should generally discourage adding type hints, unless they are done in a separate commit which does basically nothing but add type hints -- we want to avoid code churn and anything which makes code review harder.

The bigger question for me is, do we want to encourage using type hints for things other than function parameters and return values? In most cases, I think that the type is obvious from context (which is typically not the case for function invocations, which is where the hint-checks are needed most). For most local variable definitions, the hints are just clutter and wasted effort, especially if the variable holds an aggregate type which is harder to describe than it is to simply assign to an instance.

[portante]

That proposal seems reasonable.

And it also seems reasonable to start with function parameters and return values first before we try to extend its use.