Typing spec: The @typing.type_check_only decorator

Typing
1

The @type_check_only is intended to mark helper classes in stubs that are not available at runtime. It’s documented here: typing — Support for type hints — Python 3.12.4 documentation. While it never gained much traction (and making such classes available at runtime would be preferable), I still think it’s a useful addition. Type checkers could flag such items if they are imported outside an if TYPE_CHECKING: block or used outside a typing context, and IDEs could mark such items differently.

Could this decorator be added to the typing spec?

See also Underscore for type-check only items? · Issue #11122 · python/typeshed · GitHub for a related discussion about type-check only items in typeshed.

1 Like
2

I think it makes sense to add @type_check_only to the typing spec.

However, I’m not on board with the statement “Type checkers could flag such items if they are imported outside an if TYPE_CHECKING: block”. I don’t think that type checkers should have any specialized behaviors based on TYPE_CHECKING, and I’d be opposed mandating such behavior.

If you’re interested in submitting a proposed addition to the typing spec, you’re welcome to create a draft PR for review. I think it makes sense for this to go in the directives chapter.

1 Like