Type annotations

[shoyer]

Given that we seem to be on board with only supporting Python 3 (#5) in pandas 2.0, let's take full advantage of that and require type annotations for all internal pandas code. Users, of course, are free to ignore them as they please, but we can run mypy or pytype as part of our continguous integration tests to check for bugs.

Why?

1. Static typing catches loads of bugs, both for us and our users
2. Documenting types in code is far more reliable than in doc-strings
3. Such a constraint would provide strong pressure for writing functions with sane type signatures

Quite simply, this is just good software engineering.

[TomAugspurger]

+1.

My biggest annoyance has been with the repetition between types in the annotations and types in the docstrings. Presumably we could write a little decorator that pulls type-info from the function signature and puts them in the docstring (via a Jinja2 template or something).

https://www.python.org/dev/peps/pep-0526/ (new syntax for variable annotations) was recently accepted for 3.6. Have we talked at all about what version of python3 we're targeting? Separate issue?

[jankatins]

I'm currently working with pycharm and autogenerated docstrings and function signatures (matplotlibs new data arguments) are a big pain as IDEs like pycharm gets these info without starting an interpreter :-(

[brmc]

I'm definitely in favor of this. have there been any decisions made about what python versions will be supported?

@JanSchulz we might look into building a complimentary stub package for pycharm for matplotlib for the time being. auto-generated code is a huge pain.

[jreback]

@brmc we would certainly take a type stub type of file (in the current pandas repo actually). This is really a user facing file. Ideally would support both py2 & py3 (obviously py2 is quite useful for folks migrating). If you are interested please submit a PR.

[shoyer]

For pandas 2, I think the plan is Python 3 only (see #5 ).

[jreback]

type annotations would be quite useful for py2; these are also about the user api which is not likely to change much

pandas2 is still a while off

[shoyer]

@jreback to be clear, I am all for starting early on annotations! This issue is on the pandas 2 tracker, though.

[jreback]

@brmc so in reality this should be discussed on pandas-dev/pandas#14468

[brmc]

continuing conversation on pandas-dev/pandas#14468