Instrument code with typehints

[hjmjohnson]

Is your feature request related to a problem? Please describe.

We believe statically typing what are essentially fully dynamic languages will give MONAI code stability and improve developer productivity.

Attempt to use modern python preferred pep 484 support.
This allows advanced linters to more aggressively perform static
validation checking.

Using typehints as annotations allow for a more DRY (Do not repeat
yourself) implementation that supports various type checking linters and
documentation support.

Some pytype warnings will require more extensive corrections to fully
resolve them. These few cases are suppressed in the interest of
allowing more static checks without imposing a huge burden at the moment.

Describe the solution you'd like
Instrument code with type hint static checkers and PEP484 type hints.

This task will not be complete until

• enable mypy (Still currently the gold standard) completed in Add convenience options runtests #496,
• enable flake8-mypy (possibly with limitations as it is pretty unstable and most unmaintained).
• enable pytype (suggested replacement to flake8-mypy) (Enable Pytype CI #492 - DONE)
• mute/fix existing warnings by, for example, setting the config exclude=*.py (WIP - Enable pytype #483, 476 - 20200602 type hints part3 #480)
• set up CI pipeline so that we can verify every PR in the future (WIP - Enable pytype #483)
• setup an initial config of the relevant tools (20200602 type hints part1 #477 - DONE)
• incremental PRs to enable submodule checks, for example, change the config from exclude=.py to exclude=monai/transforms/.py (20200602 type hints part1 #477 - DONE )(20200602 type hints part2 #479 - DONE) (476- Indicate that the optional type returned must be an ndarray. #481 - Replaced)
• incremental PRs to add new type hints to the existing modules (476- 20200602 type hints part5 #482 - Rejected) (TBD)(TBD)(TBD)(TBD)
• Add temporary #type: ignore and pytype: disable=????? suppressions so that big-ticket changes can be cleanly addressed as a pirority (Add convenience options runtests #496 -DONE)
• Find all temporary # type: ignore items and resolve the temporary suppression with proper type hinting.
• review setup.cfg and remove temporary suppression of typehint warnings (Add pytype testing options #499 -Done) Mypy and flake8 options appear to be in good shape as well.

the last two steps could happen in parallel

[hjmjohnson]

The plan is to make MONAI code base pass tests with pytype static analysis, and mypy static analysis tools, along with flake8-mypy integrations.

The MONAI package should be sufficiently instrumented with type hints so that all the docstring types used to indicate expected types to developers can be statically checked and validated by the above-mentioned tools.

Eventually, the entire MONAI toolkit should be compatible with type hinting for all public-facing interfaces.

[wyli]

thanks,~ the flake8-mypy CI tests currently works fine~
for a concrete plan to enable mypy, pytype, flake8-mypy:

• setup an initial config of the relevant tools (20200602 type hints part1 #477)
• mute/fix existing warnings by, for example, setting the config exclude=*.py (e.g. WIP - Enable pytype #483, 476 - 20200602 type hints part3 #480)
• set up CI pipeline so that we can verify every PR in the future (WIP - Enable pytype #483)
• update contributing guide to inform all developers (steps to run local tests)
• incremental PRs to enable submodule checks, for example, change the config from exclude=*.py to exclude=monai/transforms/*.py (e.g. 476- Indicate that the optional type returned must be an ndarray. #481)
• incremental PRs to add new type hints to the existing modules (e.g. 476- 20200602 type hints part5 #482)

the last two steps could happen in parallel

Edit: Please ignore this comment and follow the tasks listed in the ticket

[hjmjohnson]

@wyli The flake8-mypy does NOT currently work fine. They are disabled!!! as was done explicitly to get the separate PR's working.

[wyli]

thanks for pushing this forward @hjmjohnson, we also need

• some simple instructions such as https://github.com/Project-MONAI/MONAI/blob/master/CONTRIBUTING.md#linting-and-code-style-testing to run local tests before PR (and to clean pytype cache afterwards)

[hjmjohnson]

thanks for pushing this forward @hjmjohnson, we also need

• some simple instructions such as https://github.com/Project-MONAI/MONAI/blob/master/CONTRIBUTING.md#linting-and-code-style-testing to run local tests before PR

@wyli We have some of that locally, but as we figure out how to use pytype, mypy, and other validators (i.e. we spend a lot of time with pyre, but it is really hard to install, and does not seem to produce meaningfully useful failures at this point in our type hinting journey).

@crtrentz @benjamin-gorman I know you have been working notes for how to use, configure, and resolve problems identified with pytype and mypy. Please modify the recommended CONTRIBUTING.md file with your notes as an independant PR on the master branch.

[wyli]

perhaps a new ticket is needed, but a quick question here first, could we remove 'flake8-mypy' since we have both 'flake8-mypy' and 'mypy'?

when there's a type error, running ./runtests.sh --codeformat --quick raises a flake8-mypy error but lacks error contexts. mypy provides much better messages.

[wyli]

Major APIs and docstrings are now revised to fully support typehints. closing this ticket -- please create new specific tickets to address any further typehint related issues.