RFC: Use type hints in larq source code

[lgeiger]

Objective

Python 3.6 and above supports type hints and optional statically typing of Python code. Since its introduction is has seen a lot of adoption in many Python projects in particular in larger code bases. Type hints are completely optional and are stripped by the Python parser before runtime.

I am not the only one @plumerai anymore who likes type hints for Python and we only support Python 3.6+ already so I'd like to discuss if we should introduce type hints to the larq code base. I have never used typings in a big project, but below is a list of some pros and cons I can think of on top of my head.

Pros

• Makes it easy to reason about the code due to the self documenting nature of statically typed functions
• Helps with code review
• Can catch subtle bugs of in places of insufficient code coverage
• Has good integrations for editors that help with autocomplete and linting

Cons

• TensorFlow doesn't use type hints so I don't know how well type stubs are maintained
• Needs additional setup on CI and to maintain type stubs
• Might be confusing for novice Python users since it adds new syntax to the larq code base

Tooling

• MyPy (the default)
• Typeshed
• Pyre
• Pytype

[AdamHillier]

Yes.

[leonoverweel]

Yes, this would be nice.

[AdamHillier]

Since 2b262bf we do run pytype in CI but it doesn't do too much yet because there aren't many type hints around.

[koenhelwegen]

Sounds like a great idea! One small remark: as TensorFlow currently doesn't have typehints I would prefer to keep all examples provided in the documentation free of typehints, so as to not raise the threshold for users who are not familiar with them.

Btw, I know people are working on making type hints more compatible with numpy arrays, do we know if similar efforts are underway for TF tensors?

[AdamHillier]

Sounds like a great idea! One small remark: as TensorFlow currently doesn't have typehints I would prefer to keep all examples provided in the documentation free of typehints, so as to not raise the threshold for users who are not familiar with them.

The most important thing is for the external API to have type hints so that this gets picked up in editors/IDEs; any private methods or tests don't need them, and examples definitely don't.

[lgeiger]

Great, thanks for the comments. I set the status to RFC - accepted.

I would propose to gradually adopt typehints in the code base, meaning that we should encourage typehints for new code and welcome PRs adding typehints to existing code.

Btw, I know people are working on making type hints more compatible with numpy arrays, do we know if similar efforts are underway for TF tensors?

I am not aware of similar efforts in TF, but this might change with TF slowly dropping support for Python 2.

[lgeiger]

Just for reference TensorFlow Addons is also looking into introducting type checking: tensorflow/addons#743

[AdamHillier]

TFA uses this utils file to define their tensor-types: https://github.com/tensorflow/addons/blob/master/tensorflow_addons/utils/types.py