How to make packages compatible with mypy

[afrieder]

I'm getting my feet wet with PyPI with a tiny little package (https://github.com/afrieder/matcher). I want to include types so mypy can type check it. I've included both annotated .py files and a .pyi stub. However, installing this through pip (currently using pip install -e ., the newest version on PyPI doesn't have the stubs yet) results in Cannot find module named 'matcher'. First I'd like to request help and I'd also request that this be documented somewhere. mypy is an amazingly cool tool, and I'd love for more package developers to use it, but there's no documentation for making type hints more usable. Thanks.

[gvanrossum]

Thanks for asking! You're right this is a bit of a pain right now. Most "big name" packages solve this by adding stubs to typeshed, but we can't keep that up to date for every package, and when the package owner maintains the stubs it's better to have a different place to look for stubs.

One thing you could do would be to arrange to install your stubs in a separate directory rather than in site-packages, and then direct users to add that separate directory to their MYPYPATH environment variable. You'd need to add an __init__.pyi as well.

There's a proposal for where those stubs should live in PEP 484 (search for "shared/typehints/python3.5") but mypy doesn't implement it yet -- hence the suggestion to add it to MYPYPATH.

IIRC there's also some confusion about the exact name of that directory (but I can't find the issue ATM). There's definitely some discussion at #1190. Even more at python/typing#184 and python/typing#84.

@ambv Are you interested in this issue at all? I believe we could use some help cutting through all the various proposals and just implement something (especially if it matches PEP 484).

[ambv]

@gvanrossum Yes, I'll work on it this week.

[emmatyping]

I will add some simple documentation and add a link to PEP 561 in implementing #4403

[MartinThoma]

Here is a direct link to PEP 561 -- Distributing and Packaging Type Information.

It would be nice to have a tool which checks packages for compatibility (question here). check_typedpkg could be what I am looking for, but it is not on PyPI so far.