Add python type hinting

[schwehr]

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?

[rwhogg]

Note: we've dropped support for 2.7 and 3.6 in newer releases of NDB. 3.7 and 3.8 are still supported.

[remko]

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.

[embray]

For what it's worth we have written extensive type stubs for the old google.appengine.ext.ndb and will soon be porting them to google.cloud.ndb as well. It also includes a small mypy plugin for handling things like __init__ args. I will check with my colleagues but I believe it would be OK to make these available to the community--certainly it would be great if there is interest to have community support in maintaining them. Our typing for properties works extremely well, including things like repeated properties and required vs. non-required. There's one small bug with Property.IN I'm aware of but it can be fixed pretty easily.