[Dev] Introduce type annotations?

[jeromekelleher]

@grahamgower brought up the idea of using type annotations in the code over in #471. I don't know much about it, so thought it would be good to have a discussion here of the pros and cons.

One abiding principle I think we should have though is that we should be conservative about Python versions. The approach taken so far (which we should document somewhere I guess) is that the minimum Python version tracks Debian stable.

[benjeffery]

Function annotation syntax has been a Python feature since version 3.0, but to use them properly you need 3.5 as that added the typing library and conventions. From what I can see tskit supports 3.6 and debian stable (buster) is on 3.7, so that shouldn't stop us. There's two main advantages:

• When on exposed methods for users they form part of the documentation, although we already have lots of types in docstrings.
• When on most methods you can statically type-check - there is a network effect as you add typing to methods, this also helps future dev work.

It would be a lot of changes, but maybe worthwhile to do the later. I need to read through the code more to get an idea of cost/benefit.

[jeromekelleher]

Thanks @benjeffery, sounds good. OK, it sounds like one to think about in ~6 months once we've settled in to using the current bout of process improvements.

[grahamgower]

Let me caveat my comment by saying I haven't used type annotations in Python before, but.... My understanding is that type annotations can be added gradually. If its decided that type annotations are desirable, then there need not be a concerted effort to annote lots of existing code right now. But this shouldn't prevent the more adhoc introduction of a few type annotations in new code. A concerted effort can be made at any point in the future.

Possibly the benefit to tskit itself would be limited, but tskit-using code would get a benefit when doing static type checking.

[benjeffery]

Linking this here for later reference: https://www.bernat.tech/the-state-of-type-hints-in-python/