Include py.typed file in distribution (PEP 561)

[tlambert03]

Description

In order for the .pyi files to be useful, scikit-image needs to include a py.typed file in top level module of the distribution.

See PEP 561 and the mypy documentation for more information.

currently, when using scikit-image in an IDE, you get:

if you drop py.typed file in the skimage folder of site-packages you get:

[lagru]

Thanks for catching this Talley! Seems obvious that we want to include this change.

Though, I can't seem to reproduce this with PyCharm on my side; behavior is identical with and without py.typed. And PyCharm finds the docstring without the file. Which IDE are you using, a vscode-based one?

[tlambert03]

Yep, vscode

[tlambert03]

If I recall correctly, pycharm actually does dynamic imports for a number of things?

[lagru]

Thanks @tlambert03. :)

[darosio]

I was used to a single:
import skimage # type: ignore
or a few:
from skimage.morphology import disk # type: ignore

Now I need a "# type: ignore" for every still untyped function I use to make the mypy check happy.
Which is fine if you are planning to add types to all/most functions in the near future. Is that the case? I could not find in the docs related planning.

[tlambert03]

You can use the mypy configuration to batch ignore, or selectively ignore specific errors (or all errors):
https://mypy.readthedocs.io/en/stable/config_file.html#suppressing-errors

example overriding specific modules here: https://mypy.readthedocs.io/en/stable/config_file.html#example-pyproject-toml

[johnthagen]

I was surprised that py.typed was added without many common functions being type annotated (img_as_float, img_as_ubyte, resize, imsave, etc.) This leads to a large number of type check errors when running mypy on a code base that uses scikit-image.

I would recommend, if possible, that you only add a py.typed file if your whole (or at least vast majority) of the public API is type annotated. Otherwise, every downstream user of your library that type checks their code will need to do suppression work.

[tlambert03]

for a little added context:
the motivation here goes back to #5101 which introduced lazy submodule imports for many modules in sci-kit image. Because modules were no longer listed as literal imports, type checkers and IDEs were no longer able to infer imports and namespaces for intellisense/autocomplete.

So, in order to tell IDEs what scikit-image has available, two options were presented (#6435 and #6429), and a variant of #6435 was merged in #6577, using pyi stubs to indicate to IDEs what modules & functions scikit-image had to offer. However, in order for static type checkers to use these static hints, you must include a py.typed file (as per PEP 561).

My understanding of the implications of py.typed from PEP 561 is not to indicate some critical mass or coverage of typed functions in a package, but simply to indicate to type checkers that they should search this package for stubs, as opposed to a third party stubs package (or typeshed) which was the historical/legacy way that many packages incrementally offered types. Users who wish to use mypy with strict setting (I'm definitely a fan) often do need to add a bit of configuration for partially typed dependencies. (and I feel like having to add import skimage # type: ignore is not dramatically different from adding an ignore_errors=True to your module overrides?)

I don't particularly have a preference here, i leave it to the maintainers of scikit-image to decide... but if you would vote for the removal of py.typed, then I think you also need to suggest how you would deal with the inability of IDEs to detect anything in scikit-image given the use of lazy imports.

[johnthagen]

The problem is that the way the suppressions work, you can't add a blanket ignore for problems in a third party library (at least I could not get this to work) because the calls to skimage happen in user code. If you have these calls scattered all over your code base, you end up having to suppress disallow_untyped_calls everywhere, which opens you up for the type checker missing real errors in other usages of your code.

For example, I tried:

[[tool.mypy.overrides]]
module = "skimage"
disallow_untyped_calls = false

But this does not suppress skimage issues:

my/package/module.py:1: error: Call to untyped function "img_as_ubyte" in typed context  [no-untyped-call]

I would be happy to be proven wrong if there is a Mypy configuration that can suppress only skimage-caused no-untyped-call errors globally.

[tlambert03]

my apologies, this feature was merged in mypy a couple days after the most release release in August: python/mypy#15845

so, it will be available soon. but until then, you're correct that's it doesn't appear possible to enforce strict typing for your own library, while using scikit-image without local ignores. I don't have too much more to add, but will just re-iterate that this is a genuinely tricky problem.

• If you remove py.typed, then at least some if not all lazy modules will not give you any IDE autocompletion or namespace hints at all. (I'm not sure this avenue has been exhausted, but a vote to remove py.typed should be accompanied with a proposal to solve this problem too)
• If you include py.typed, then dependent libraries who want to disallow untyped calls within their own libraries will have to locally ignore calls to skimage until Add option to selectively disable --disallow-untyped-calls python/mypy#15845 makes it into a release
• outside of the challenges of lazy imports, if scikit-image ever wants to offer type hints for a broader portion of the library, it will inevitably happen incrementally, so this challenge will certainly come up again in the future. (again, hopefully solved by the untyped_calls_exclude in mypy)

cheers!

[soupault]

if scikit-image ever wants to offer type hints for a broader portion of the library

I personally find type-hinting very useful, both in prototyping and proper development scenarios. So, in my mind, we should definitely go that path.

[johnthagen]

so, it will be available soon

Thanks for the reference! That certainly will limit the impact of this change and allow users to suppress this particular issue. I agree that after the next Mypy release, the negative impacts of this PR will not be nearly as severe.

[stefanv]

It sounds like the problem will be resolved by (a) a new feature now available in mypy and (b) our stated attempt to type annotate and implement protocols as part of skimage v2.

Perhaps @lagru and @jni have more to say about that plan.

[lagru]

@johnthagen, sorry for the py.typed related annoyance from our side.

We currently have a grant that also entails typing our API. It's a big effort and we are also trying to revise our API in the process but you can follow along in

• Prototype type hints for skimage.filters with mypy #7185
• Generate table of scikit-image's entire runtime API #6905
• https://github.com/scikit-image/scikit-image/wiki/API-changes-for-skimage2

From skimming the discussion above, our best bet seems to be to continue work on that and leave the py.typed be.

[johnthagen]

As of Mypy 1.6.1, you can now suppress only the untyped call errors in skimage with:

[tool.mypy]
strict = true
untyped_calls_exclude = [
    "skimage"
]