Document how to import types from stubs

[ksamuel]

I'm currently trying to type an API using the signal module. At some point, we pass a callback that has the type signal._Handler (see: https://github.com/python/typeshed/blob/master/stdlib/3/signal.pyi#L73), which is not in the signal module, but in typeshed.

If I try to import it, I get an error, and I could not find the proper way to do so in the documentation.

[JukkaL]

Yes, it would be good to document this clearly, as the workaround is not obvious.

You can use the same approach used to deal with import cycles: https://mypy.readthedocs.io/en/stable/common_issues.html#import-cycles

[kshitij86]

@JukkaL I want to contribute to mypy. Could you assign this issue to me?

[JukkaL]

@kshitij86 Your contribution is welcome! This is now assigned to you.

[mfarrugi]

https://github.com/python/typeshed/blob/master/stdlib/2and3/_typeshed/__init__.pyi#L3-L13 is a good starting point for an explanation.

For any types that are only available in stubs, you must do

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    # <import your stub only type>

[gvanrossum]

@mfarrugi If you want to give it a try you’re welcome.