New (experimental) type stubs for skimage

HI all

I built a tool last year to generate type stubs for scientific Python packages that use numpydoc docstrings. I combine my processing of the docstrings with monkeytype traces if there are good samples. I originally did this for matplotlib, but have just completed first versions for scikit-learn, scikit-image, networkx, and vispy; working on scipy. YMMV with these stubs; I try to parse the docstrings to something sensible and use a mapping file for those I can’t make unambiguous sense of, but even the former is based in my interpretation of the docstring text which may be wrong (and probably is plenty of times). Nonetheless, it is not too difficult for me to make adjustments and regenerate these. Posting here so interested people can try them out and give feedback. You can open issues with the stubs at their repo.

I did this with the medium term aim of having good type annotations that pyright and pylance can leverage (I am the eng manager for Python runtime at Microsoft, and the pylance team falls under me). Good type annotations are not only good for finding errors but can give a much better editing experience in Visual Studio/Visual Studio Code (and any other editor that has language services that can leverage them, which is most editors these days once suitably configured). Our long term aim is to have package authors use these (if they wish) to add type stub packages or inline types that are maintained by them, rather than us (or really me, as my team is not that big and everyone else is busy with other things :-)). We did this successfully with the pandas team, thanks to a good partnership with Irv Lustig. Would love this to happen with other packages.

The stubs can be found here, which is also where issues can be files: python-type-stubs/skimage at main · microsoft/python-type-stubs · GitHub (stubs for the other packages I mentioned can be found there too). The tool I use is at GitHub - gramster/docs2stubs.

(You’ll see a mix of old style and newer style type syntax; my tool favors the newer style but the additional ones added via monkeytype use the old style (e.g. Union, Tuple,… vs | or tuple).

An even better way to help improve these in the short term is by PRs against the map files in docs2stubs/analysis at main · gramster/docs2stubs · GitHub. These are ‘#’-separated CSV files for parameter and return types that have docstrings and the types I map those docstrings to. Identifying issues there could fix large classes of bugs in these type stubs.

Hey @gramster, welcome and thanks for reaching out! It’s exciting to see this kind of work as we are planning to add type annotations to scikit-image. It’s part of the goals of the CZI5 grant that scikit-image received. When we start working on this, your typing stubs may be a good starting point or reference to keep in mind!

I’ll try to look into this some more but in the meantime I’d be interested if you encountered any unique difficulties or quirks in general or specific to scikit-image. That would be very useful to see where our documentation/API is lacking or inconsistent.