REF: Introduce typing and type hints

[asoplata]

As per George’s recommendation, we should introduce type hints and typing to our code. This enables use of checkers like mypy https://www.mypy-lang.org/ , which can help with debugging and testing. I believe this is especially helpful with scientific computing in particular:

• For example, maybe you apply an operation and expect to get a numpy array back, but instead receive an intbecause of a bug or dependency change. Your analysis code (and tests) may process this as if it is a valid scientific output, and pass, but type checking would have prevented this at the beginning.
• Type hints also significantly improve autocompletion in all code editors.

This may make the frequent use of externals/mne.py::_validate_type() unnecessary.

If we want something similar to _validate_type() that runs EVERY time the code is used at runtime, then once we add our type-hints to our function signatures, we could try using https://github.com/RussBaz/enforce . That way, we get all the advantages of typing using the language-standard way, but also enforce our runtime checks. I personally think that using mypy at commit-time, instead of every run-time, is good enough, however.

• mypy recommends starting small, and has some great advice for the order in which to gradually add type checking to our code: https://mypy.readthedocs.io/en/stable/existing_code.html .
• For an in-progress conversation of how MNE has thought about this see here Add type hints mne-tools/mne-python#12243 (keep in mind their codebase is larger than ours)

[jasmainak]

reading the MNE conversation, I realized where my thoughts come from ;-) some legitimate concerns expressed there -- and I'd add that it might be a good idea to scour other open source repos to see if others are adopting it. I typically try to avoid being on the bleeding edge ... let others make the mistakes and learn from them. There is also the concern of an added dependency, but I suppose mypy is a well-supported repo so that concern is minor

[ntolley]

I'll chime in that I see typing used pretty consistently in the deep learning space for a few years now, still not widely accepted but I'd say it's beyond the bleeding edge currently