stubtest: Support type_check_only decorator

Feature

I would like stubtest to support checking the type_check_only decorator.
This means something marked with type_check_only that DOES exist at runtime is an error.
And something that DOES NOT exist at runtime, and is marked with type_check_only should pass.

Pitch

Instead of marking stub-only classes and methods as private in typeshed, they can be marked with @type_check_only, which is designed for that exact purpose. Private may or may not be found at runtime, and users sometimes don't have a choice to use them, and basically have to guess whether they need to wrap the import in TYPE_CHECK_ONLY or not.
This would also promote marking as type_check_only special methods that don't exist at runtime, but are added to support some typechecker features, in typeshed.

Related: #9531

Could I get the topic-stubtest label here?

[stubtest] support `@type_check_only` decorator (#16422)

There is partial support for this (at least with >=1.15.0):

mypy/mypy/stubtest.py

Lines 508 to 513 in 16e99de

    
           def verify_typeinfo( 
        
               stub: nodes.TypeInfo, runtime: MaybeMissing[type[Any]], object_path: list[str] 
        
           ) -> Iterator[Error]: 
        
               if stub.is_type_check_only: 
        
                   # This type only exists in stubs, we only check that the runtime part 
        
                   # is missing. Other checks are not required.

mypy/mypy/stubtest.py

Lines 1378 to 1383 in 16e99de

    
           def verify_decorator( 
        
               stub: nodes.Decorator, runtime: MaybeMissing[Any], object_path: list[str] 
        
           ) -> Iterator[Error]: 
        
               if stub.func.is_type_check_only: 
        
                   # This function only exists in stubs, we only check that the runtime part 
        
                   # is missing. Other checks are not required.

But in case of overloaded @type_check_only functions, stubtest will still report a false positive "error: ... is not present at runtime":

mypy/mypy/stubtest.py

Lines 1163 to 1166 in 16e99de

    
           def verify_overloadedfuncdef( 
        
               stub: nodes.OverloadedFuncDef, runtime: MaybeMissing[Any], object_path: list[str] 
        
           ) -> Iterator[Error]: 
        
               # TODO: support `@type_check_only` decorator

I just ran into this limitation scipy-stubs, so it would be nice if it would also work for overload functions.

Yeah, looks like sobolevn left this as a TODO in #16422

To answer the question he left, I'd assume the semantics are that it applies to the whole function, is that what you expect as well?

I'd assume the semantics are that it applies to the whole function, is that what you expect as well?

I can't imagine where you'd want to @type_check_only a single overload 🤔. So yea, I think it would make sense to have one @type_check_only apply to the entire overloaded method. So like @override and final, and not like @deprecated.

Navigation Menu

Repository navigation

stubtest: Support `type_check_only` decorator #15146

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

	def verify_typeinfo(
	stub: nodes.TypeInfo, runtime: MaybeMissing[type[Any]], object_path: list[str]
	) -> Iterator[Error]:
	if stub.is_type_check_only:
	# This type only exists in stubs, we only check that the runtime part
	# is missing. Other checks are not required.

	def verify_decorator(
	stub: nodes.Decorator, runtime: MaybeMissing[Any], object_path: list[str]
	) -> Iterator[Error]:
	if stub.func.is_type_check_only:
	# This function only exists in stubs, we only check that the runtime part
	# is missing. Other checks are not required.

	def verify_overloadedfuncdef(
	stub: nodes.OverloadedFuncDef, runtime: MaybeMissing[Any], object_path: list[str]
	) -> Iterator[Error]:
	# TODO: support `@type_check_only` decorator

stubtest: Support type_check_only decorator #15146

Description

Activity

Avasam commented on Sep 23, 2023

jorenham commented on Jun 25, 2025

hauntsaninja commented on Jun 25, 2025

jorenham commented on Jun 25, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

stubtest: Support `type_check_only` decorator #15146