Add type annotations

[jwodder]

Running mypy on code that uses the latest version of hdmf fails with the error message "module is installed, but missing library stubs or py.typed marker". Please add type annotations to this project and include a py.typed file in the package to indicate typing support to mypy.

[oruebel]

Thanks for the issue. Having support for type hints will be useful.

Just to provide a bit more context on this issue, because there are few factors that make this a bit more complicate beyond adding type hints to existing functions:

• HDMF as an API can automatically generate classes from data schema at runtime. I.e., the class generator would need to add type hints to the dynamically generated classes. See https://github.com/hdmf-dev/hdmf/blob/dev/src/hdmf/build/classgenerator.py
• HDMF added type checking before type hints existed in Python. HDMF defines the docval decorator that is used to decorate functions to define what the input parameters should be, e.g., types, shape, etc. docval uses this information to check types at runtime as well as to generate docstrings for the functions. I.e., we would need to modify docval to also generate type hints.

  hdmf/src/hdmf/utils.py

  Line 533 in 1d7fd83

  def docval(*validator, **options): # noqa: C901

• Since type hints are not enforced backward compatibility may be Ok, but once you would run with mypy it may get more tricky, as the type-hints generated by docval and the classgenerator would have to match in behavior. This means unit and integration testing will likely be a significant task.

Maybe there is a more incremental approach to get to what you are suggesting, i.e., maybe have type hints for some parts. I have not used mypy yet, but as far as I understand it it does not require that everything has type hints, but it will enforce type hints if they exist.