Python type-hints: Deprecate only a specific overload
04:06 23 Feb 2026

Python type-hints allow me to define several @overload for a single function, so that only a single version of the function exists at runtime, but multiple versions exist from the point of view of the type-checker.

from typing import overload

@overload
def double(x: int) -> int: ...
    
@overload
def double(x: str) -> str: ...

def double(x):
    return x*2

Now I wish to deprecate or warn about one of the overloads. I do not want to warn about the function itself, just about the use of one of its signatures. I thought about doing this with @deprecated, but all the @deprecated annotations that I have looked at (typing_extensions, warnings, third-party) don't seem to support this usecase. Anything that works at runtime does not do the trick, because the function itself is not deprecated.

I am not dead-set about this being a @deprecated-warning, any warning would be Ok.

python types python-typing