@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.2 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.