Add python type hinting
schwehr opened this issue · 3 comments
This is work that might be contributed by folks other than the maintainers.
Is your feature request related to a problem? Please describe.
Checking types in python has been loose and folks sometimes get themselves in trouble when trying to modify older code bases. It's not always obvious to the reader of the code what type(s) should be in play for particular code. Having type hints in python-ndb would help a bit with that.
Describe the solution you'd like
If the project is up for it, say that you are okay with PRs that setup testing of type hinting (pytype and/or mypy) and then adding type hinting. Then maybe we can round up some contributors.
Describe alternatives you've considered
It's okay to not add type hinting. It solves only a particular set of issues. And users of the library should have test coverage exercising all of their use, but that can sometimes be a difficult bar to achieve.
Additional context
I personally have found I'm faster at modifying code with type hints and create fewer bugs in that code. YMMV.
Additionally there needs to be a couple decisions:
- Python typing work better with newer versions of python
- Are there any plans to drop support for pythons 2.7, 3.6, 3.7, 3.8?
- https://devguide.python.org/#status-of-python-branches: 3.7 and 3.8 are currently security only. 2.7 and 3.6 are past end-of-life for the python project
- Does the project allow
from __future__ import annotations
? - How much type hinting to allow?
- When to just punt and use
Any
? e.g.Dict[str, Any]
for JSON rather than something super messy - Which checker(s) to use? pytype, mypy, and/or what?
Note: we've dropped support for 2.7 and 3.6 in newer releases of NDB. 3.7 and 3.8 are still supported.
The parameter/return types used in the docs of the library seem to be pretty accurate. Are these manually written, and/or is there some tooling used (internally?) that creates .pyi files from this (or vice versa?)
This only handles the API part; it would be nice if the typing would also work for assignments to model properties etc., which I assume is more advanced typing.