Support for typing?

[neiljp]

I've been looking at applying typing to some code which uses PIL/pillow.

Is there any feeling regarding the addition of type annotations within Pillow, or if these belong outside the code in eg. typeshed? This influences whether I might work on a PR against Pillow itself, or generate stubs for typeshed.

On the basis of supporting python 2 and 3, I expect annotations would be in comments, and there would be an import of the typing module near the top, to define required types.

[szabolcsdombi]

Type hints would be great. I am using vscode and linting helps a lot.

I am willing to contribute.

[emmeowzing]

I am as well. I think this would be a great addition to the project.

[wiredfool]

It sounds like a good idea, at least at the top 'interface' level to help ensure a well defined interface.

Typeshed would be a simple way to get it up and running without much interference with the current repo, but in the long run I think that the appropriate place for the type annotations would be in this repo, so that they can be kept in sync and (potentially at least) help keep bugs out of the code base in the testing phase.

[emmeowzing]

What problems would the project face with Python 2/3 compatibility?

[neiljp]

I've been working with mypy in Zulip, and at least until recently they use 2 and 3, and mypy seems to work for that.

[neiljp]

@wiredfool I'll explore expanding typeshed then, if that's a go-ahead - typeshed is clear on seeking approval from project maintainers first.

That said, if direct annotation PRs would be accepted, that'd be something I'd look at working on instead.

[wiredfool]

I'm not up on the technical bits for doing type annotations. But, as I understand, there are three ways to do it:

1. In the function signatures. Requires 3.5ish+. Not an option here due to our continuing support for older pythons.
2. In function docstrings.
3. In Typeshed.

The advantage of docstrings is that they're next to the code, and once it's all in, it can be maintained and not drift out of sync with the code. The disadvantage is that they're going to require PRs into this repo.

Can you do a function or two as an example against Image.py where we've got autodoc extracting the documentation? And then possibly see if we can test against that in the test suite?

[emmeowzing]

I wouldn't opt for writing type annotations in docstrings since it's so easy to edit code and forget to update them if the types should change, even marginally. I do, however, like the methods mentioned here. Adding single (or multiple) line comments describing a function or method's type just before a docstring is checked by Mypy (and highlighted by Pycharm).

[neiljp]

Annotating in docstrings is maybe coming to mypy through a plugin, IIRC. However, yes, I was just going to take a look at this using comments.

[wiredfool]

From my POV docstrings and a comment prior to the docstring are roughly equivalent, They're both not 'in code' to the point of breaking on 2.7, but they're in the same source file.

We'd need to make the typing module a conditional import, as it doesn't need to be required.

[neiljp]

I'm working on this now.

[neiljp]

Provisional work is now in my fork here https://github.com/neiljp/Pillow/tree/test_annotate

Should I make a WIP PR? That's a lot of functions with annotations, but not all quite fully there, and mypy doesn't 'pass' the code fully (and that's just with that file). There are some code changes which I could make to help the code pass and improvements/hints from mypy, but I wasn't sure whether to just make annotations, or perhaps also add related potential changes to the code but in separate commits in the same PR?

Anyhow, interested to hear what the feeling is so far.

[wiredfool]

Go ahead and make a PR for that. It'll give us a good place to discuss it, I can ask questions and hopefully arrive at something that works/passes.