Support type annotations

[bkeryan]

Python 3 supports optional type annotations using the typing module.

Benefits of specifying type annotations:

• Clients can use external tools like mypy to perform static type-checking.
• Editors such as Visual Studio Code use type annotations to provide auto-complete suggestions.

nimi-python already documents types in docstrings, so the information is already there. It would only need to be output in a different format.

[ni-jfitzger]

I prefer to wait until we drop Python 3.8, before adding type hints, due to the major differences in how collections are annotated between 3.8 and 3.9: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html#useful-built-in-types

[bkeryan]

The collection types are really not a big deal. They don't even require the typing_extensions package.

For now, use from typing import List and write List[T]. When you drop Python 3.8, then use pyupgrade to rewrite any hand-written type hints: https://github.com/asottile/pyupgrade#pep-585-typing-rewrites

Using other new typing features in old Python versions is also possible, but it requires a little more work:

if typing.TYPE_CHECKING:
    if sys.version_info >= (3, 11):
        from typing import Self
    else:
        from typing_extensions import Self

class Session:
    def __enter__(self) -> Self: ...