Type Annotations

[jpn--]

trafficstars

I have begun adding type hints to code. These are optional for Python generally and don't add or change any functionality when running the code. However, they do add functionality when writing code. IDE's like VSCode and PyCharm are able to use the type annotations to validate function usage. For example, this bit of code has all the errors highlighted in my editor; without the type hints the errors only reveal themselves when you run the code, and only one at a time -- you have to hit the first error, and fix it, and rerun before you learn about the second error.

Type annotations are used extensively in other Python libraries, including pandas and xarray.

I have also built the orca-replacing PR with the functionality that allows functions that are run "automatically" to use the type hints to determine what format data tables should be delivered (i.e. pandas DataFrames or xarray Datasets) so that in future work can migrate more easily to a situation were we can cut back on potentially costly data conversion operations, but for now we don't break anything.

I am proposing we start using type annotations regularly and extensively. Going back and doing so comprehensively throughout the entire codebase is not necessary immediately (the code obviously can run without them). It would also be a significant effort, as sometimes it is not obvious what types some arguments should be, as they go through many many layers of passing through other functions before they get used. But if we start now and type-annotate any time we touch something, even if it's only a subset of arguments to a given function we are editing, we will reduce the burden of "finishing" this job later if we ever choose to invest in that.