Is there a best practice to make a package PEP-561 compliant?

The solution was to add one py.typed file to the root of the main package. This forces mypy to analyze the types.

As mentioned before, You need to add the py.typed in the package folder of the module. You also need to add that file to the setup.py package_data - otherwise the file would not be part of the package when You deploy it.

I personally put the type annotations in the code and dont create extra stub files - but that is only possible from python 3.4 upwards. If You want to make python2.7 compatible code, You can not use inline type annotation - in that case You can use stub files.

If You want to type annotate a third party library, You can write a *.pyi file for the functions You use for that library. That can be a bit tricky, because MYPY must only find that *.pyi file ONCE in the MYPY Path.

So I handle it that way :

for local testing, the MYPY path is set to a directory were I collect all the 3rd party stubs, for testing on travis, I have a subdirectory in the package with the stubs needed for that module to test it on travis, and set the mypy path accordingly.