Files
Carl Meyer 9183650bed [ty] Preserve Self for unary operators on bounded type variables (#30242)
Unary `+`, `-`, and `~` could report an invalid return type when a
method returned `Self`. For example, given `x: T` with `T` bounded by
`Base`, ty inferred `Base` for `-x` even though `x.__neg__()` returned
`T`.

Use the upper bound for literal folding and the original operand as the
receiver when binding the unary method. For a union bound, each method
binds to the part of the operand that belongs to its union member. This
also keeps the diagnostic that identifies a member missing the operator.
For an intersection bound, ty checks the call on each component and
combines the return types of the matching calls.

Fixes https://github.com/astral-sh/ty/issues/4983

## Ecosystem report

At `b79065f153a6c39d5c4ea2c53f6b11f0ee553a9b`, ty removes three false
positives in Ibis, PySpark, and SymPy. In SymPy’s matrix subtraction,
preserving the operand type also exposes an existing decorated-method
inference issue (astral-sh/ty#2520). The unsupported addition and its
return warning move from reflected subtraction to forward subtraction,
replacing an incorrect return-type error there. [Full ecosystem
report](https://github.com/astral-sh/ruff/pull/30242#issuecomment-6757597391)

## Test plan

Compared a debug build to the base revision on a file with 300 `with x`
statements and a 48-class union bound. Three runs of each build used
0.42–0.43 seconds of user CPU. This checks that other implicit method
calls on union-bounded type variables still benefit from cached lookup.
2026-11-11 17:56:08 -08:00

60 KiB

Tests for the @deprecated decorator

Introduction

The decorator @deprecated("some message") can be applied to functions, methods, overloads, and classes. Uses of these items should subsequently produce a warning.

from typing_extensions import deprecated

@deprecated("use OtherClass")
def myfunc(x: int): ...

myfunc(1)  # error: [deprecated] "use OtherClass"
from typing_extensions import deprecated

@deprecated("use BetterClass")
class MyClass: ...

MyClass()  # error: [deprecated] "use BetterClass"
from typing_extensions import deprecated

class MyClass:
    @deprecated("use something else")
    def afunc(): ...
    @deprecated("don't use this!")
    def amethod(self): ...

MyClass.afunc()  # error: [deprecated] "use something else"
MyClass().amethod()  # error: [deprecated] "don't use this!"

Function replacements

An outer @deprecated decorator applies to the function returned by inner decorators.

from collections.abc import Callable
from typing import Any, TypeVar
from typing_extensions import deprecated

R = TypeVar("R")

def replacement() -> str:
    return "replacement"

def replace_with(value: R) -> Callable[[Callable[..., Any]], R]:
    def decorator(_function: Callable[..., Any]) -> R:
        return value

    return decorator

@deprecated("use replacement directly")
@replace_with(replacement)
def old() -> None:
    pass

old()  # error: [deprecated] "use replacement directly"
replacement()

@replace_with(replacement)
@deprecated("discarded by outer replacement")
def replaced_after_deprecation() -> None:
    pass

replaced_after_deprecation()

@deprecated("outer deprecation")
@replace_with(replacement)
@deprecated("inner deprecation")
def multiply_deprecated() -> None:
    pass

multiply_deprecated()  # error: [deprecated] "outer deprecation"

class StaticMethodReplacement:
    @staticmethod
    @deprecated("use replacement directly")
    @replace_with(replacement)
    def old() -> None:
        pass

StaticMethodReplacement.old()  # error: [deprecated] "use replacement directly"

Callable replacements

[environment]
python-version = "3.12"

An outer @deprecated decorator also applies when an inner decorator returns a Callable type. Both references and calls report the deprecation, and the decorated signature is preserved.

from collections.abc import Callable
from typing_extensions import deprecated

def passthrough[**P, R](function: Callable[P, R]) -> Callable[P, R]:
    return function

@deprecated("use current instead")
@passthrough
def old(value: int) -> str:
    return str(value)

old  # error: [deprecated] "use current instead"
# error: [deprecated] "use current instead"
reveal_type(old(1))  # revealed: str
# error: [invalid-argument-type]
old("wrong")  # error: [deprecated] "use current instead"

Replacing the callable with a different function discards the original deprecation. If an outer @deprecated wraps the replacement, its message is used instead.

def replace(function: Callable[[int], str]) -> Callable[[int], str]:
    return lambda value: str(value)

@replace
@deprecated("discarded deprecation")
@passthrough
def replaced(value: int) -> str:
    return str(value)

replaced(1)

@deprecated("outer deprecation")
@replace
@deprecated("inner deprecation")
@passthrough
def replaced_again(value: int) -> str:
    return str(value)

replaced_again(1)  # error: [deprecated] "outer deprecation"

Callable method replacements

[environment]
python-version = "3.12"

Changing a method's descriptor kind or specializing its class preserves the deprecation.

from collections.abc import Callable
from typing_extensions import deprecated

def passthrough[**P, R](function: Callable[P, R]) -> Callable[P, R]:
    return function

class C[T]:
    @deprecated("old initializer")
    @passthrough
    def __init__(self) -> None: ...
    @deprecated("old method")
    @passthrough
    def method(self, value: T) -> T:
        return value

    @staticmethod
    @deprecated("old static method")
    @passthrough
    def static(value: int) -> int:
        return value

    @classmethod
    @deprecated("old class method")
    @passthrough
    def class_method(cls, value: int) -> int:
        return value

c = C[int]()  # error: [deprecated] "old initializer"
c.__init__  # error: [deprecated] "old initializer"
# error: [deprecated] "old method"
reveal_type(c.method(1))  # revealed: int
# error: [invalid-argument-type]
c.method("wrong")  # error: [deprecated] "old method"
C.static(1)  # error: [deprecated] "old static method"
c.static(1)  # error: [deprecated] "old static method"
C.class_method(1)  # error: [deprecated] "old class method"
c.class_method(1)  # error: [deprecated] "old class method"

Overloaded callable replacements

[environment]
python-version = "3.12"

Deprecating a callable replacement for an overload implementation deprecates the whole function, while calls still use the declared overload signatures.

from collections.abc import Callable
from typing import overload
from typing_extensions import deprecated

def passthrough[**P, R](function: Callable[P, R]) -> Callable[P, R]:
    return function

@overload
def overloaded(value: int) -> int: ...
@overload
def overloaded(value: str) -> str: ...
@deprecated("old implementation")
@passthrough
def overloaded(value: int | str) -> int | str:
    return value

overloaded  # error: [deprecated] "old implementation"
# error: [deprecated] "old implementation"
reveal_type(overloaded(1))  # revealed: int
# error: [deprecated] "old implementation"
reveal_type(overloaded("one"))  # revealed: str

Callable-object replacements

@deprecated can also wrap callable instances at runtime, but we do not yet preserve the deprecation when an inner decorator returns an instance type.

from collections.abc import Callable
from typing import Any, TypeVar
from typing_extensions import deprecated

R = TypeVar("R")

def replace_with(value: R) -> Callable[[Callable[..., Any]], R]:
    def decorator(_function: Callable[..., Any]) -> R:
        return value

    return decorator

class Replacement:
    def __call__(self) -> str:
        return "replacement"

@deprecated("use Replacement directly")
@replace_with(Replacement())
def old() -> None:
    pass

old()  # TODO: error: [deprecated] "use Replacement directly"

Syntax

The typeshed declaration of the decorator is as follows:

class deprecated:
    message: LiteralString
    category: type[Warning] | None
    stacklevel: int
    def __init__(self, message: LiteralString, /, *, category: type[Warning] | None = ..., stacklevel: int = 1) -> None: ...
    def __call__(self, arg: _T, /) -> _T: ...

Only the mandatory message string is of interest to static analysis, the other two affect only runtime behavior.

from typing_extensions import deprecated

@deprecated  # error: [invalid-argument-type] "LiteralString"
def invalid_deco(): ...

invalid_deco()  # error: [missing-argument]
from typing_extensions import deprecated

@deprecated()  # error: [missing-argument] "message"
def invalid_deco(): ...

invalid_deco()

The argument is supposed to be a LiteralString, and we can handle simple constant propagations like this:

from typing_extensions import deprecated

x = "message"

@deprecated(x)
def invalid_deco(): ...

invalid_deco()  # error: [deprecated] "message"

However sufficiently opaque LiteralStrings we can't resolve, and so we lose the message:

from typing_extensions import deprecated, LiteralString

def opaque() -> LiteralString:
    return "message"

@deprecated(opaque())
def valid_deco(): ...

valid_deco()  # error: [deprecated]

Fully dynamic strings are technically allowed at runtime, but typeshed mandates that the input is a LiteralString, so we can/should emit a diagnostic for this:

from typing_extensions import deprecated

def opaque() -> str:
    return "message"

@deprecated(opaque())  # error: [invalid-argument-type] "LiteralString"
def dubious_deco(): ...

dubious_deco()

Although we have no use for the other arguments, we should still error if they're wrong.

from typing_extensions import deprecated

@deprecated("some message", dsfsdf="whatever")  # error: [unknown-argument] "dsfsdf"
def invalid_deco(): ...

invalid_deco()

And we should always handle correct ones fine.

from typing_extensions import deprecated

@deprecated("some message", category=DeprecationWarning, stacklevel=1)
def valid_deco(): ...

valid_deco()  # error: [deprecated] "some message"

Category

The category must be a Warning subclass or None.

from typing_extensions import deprecated

@deprecated("some message", category=42)  # error: [invalid-argument-type] "type[Warning] | None"
def invalid_category(): ...
@deprecated("some message", category=None)
def no_category(): ...

Different Versions

There are 2 different sources of @deprecated: warnings and typing_extensions. The version in warnings was added in 3.13, the version in typing_extensions is a compatibility shim.

[environment]
python-version = "3.13"

main.py:

import warnings
import typing_extensions

@warnings.deprecated("nope")
def func1(): ...
@typing_extensions.deprecated("nada")
def func2(): ...

func1()  # error: [deprecated] "nope"
func2()  # error: [deprecated] "nada"

Imports

Direct Import Deprecated

Importing a deprecated item should produce a warning. Subsequent uses of the deprecated item shouldn't produce a warning.

module.py:

from typing_extensions import deprecated

@deprecated("Use OtherType instead")
class DeprType: ...

@deprecated("Use other_func instead")
def depr_func(): ...

main.py:

# error: [deprecated] "Use OtherType instead"
# error: [deprecated] "Use other_func instead"
from module import DeprType, depr_func

# TODO: these diagnostics ideally shouldn't fire since we warn on the import
DeprType()  # error: [deprecated] "Use OtherType instead"
depr_func()  # error: [deprecated] "Use other_func instead"

def higher_order(x): ...

# TODO: these diagnostics ideally shouldn't fire since we warn on the import
higher_order(DeprType)  # error: [deprecated] "Use OtherType instead"
higher_order(depr_func)  # error: [deprecated] "Use other_func instead"

# TODO: these diagnostics ideally shouldn't fire since we warn on the import
DeprType.__str__  # error: [deprecated] "Use OtherType instead"
depr_func.__str__  # error: [deprecated] "Use other_func instead"

Conflicting local annotation

Importing a deprecated item still produces a warning when the imported value is incompatible with an existing local annotation.

module.py:

from typing_extensions import deprecated

@deprecated("Use current instead")
def old() -> None: ...

main.py:

old: str

# error: [invalid-assignment]
# error: [deprecated] "Use current instead"
from module import old

reveal_type(old)  # revealed: str

Non-Import Deprecated

If the items aren't imported and instead referenced using module.item then each use should produce a warning.

module.py:

from typing_extensions import deprecated

@deprecated("Use OtherType instead")
class DeprType: ...

@deprecated("Use other_func instead")
def depr_func(): ...

main.py:

import module

module.DeprType()  # error: [deprecated] "Use OtherType instead"
module.depr_func()  # error: [deprecated] "Use other_func instead"

def higher_order(x): ...

higher_order(module.DeprType)  # error: [deprecated] "Use OtherType instead"
higher_order(module.depr_func)  # error: [deprecated] "Use other_func instead"

module.DeprType.__str__  # error: [deprecated] "Use OtherType instead"
module.depr_func.__str__  # error: [deprecated] "Use other_func instead"

Star Import Deprecated

If the items are instead star-imported, then the actual uses should warn.

module.py:

from typing_extensions import deprecated

@deprecated("Use OtherType instead")
class DeprType: ...

@deprecated("Use other_func instead")
def depr_func(): ...

main.py:

from module import *

DeprType()  # error: [deprecated] "Use OtherType instead"
depr_func()  # error: [deprecated] "Use other_func instead"

def higher_order(x): ...

higher_order(DeprType)  # error: [deprecated] "Use OtherType instead"
higher_order(depr_func)  # error: [deprecated] "Use other_func instead"

DeprType.__str__  # error: [deprecated] "Use OtherType instead"
depr_func.__str__  # error: [deprecated] "Use other_func instead"

Aliases

Ideally a deprecated warning shouldn't transitively follow assignments, as you already had to "name" the deprecated symbol to assign it to something else. These kinds of diagnostics would therefore be redundant and annoying.

from typing_extensions import deprecated

@deprecated("Use OtherType instead")
class DeprType: ...

@deprecated("Use other_func instead")
def depr_func(): ...

alias_func = depr_func  # error: [deprecated] "Use other_func instead"
AliasClass = DeprType  # error: [deprecated] "Use OtherType instead"

# TODO: these diagnostics ideally shouldn't fire
alias_func()  # error: [deprecated] "Use other_func instead"
AliasClass()  # error: [deprecated] "Use OtherType instead"

Conditional definitions shadowing builtins

A reference to a conditionally defined deprecated function still warns when another path falls back to a builtin of the same name.

from typing_extensions import deprecated

def flag() -> bool:
    return True

if flag():
    @deprecated("old len")
    def len() -> int:
        return 0

ref = len  # error: [deprecated] "old len"

Names in annotations

Each reference to a deprecated class produces one warning, including references through aliases and generic specialization.

[environment]
python-version = "3.13"
from typing_extensions import deprecated

@deprecated("Use Replacement")
class Old[T = int]: ...

Alias = Old  # error: [deprecated] "Use Replacement"

def direct(value: Old) -> None:  # error: [deprecated] "Use Replacement"
    pass

def alias(value: Alias) -> None:  # error: [deprecated] "Use Replacement"
    pass

def specialized(value: Old[int]) -> None:  # error: [deprecated] "Use Replacement"
    pass

def specialized_alias(value: Alias[int]) -> None:  # error: [deprecated] "Use Replacement"
    pass

Dunders

Binary operators

Using + invokes __add__, so it reports that method's deprecation.

from typing_extensions import deprecated

class Number:
    @deprecated("old addition")
    def __add__(self, other: object) -> "Number":
        return self

number = Number()
number + 1  # error: [deprecated] "old addition"

Without an __iadd__ method, += falls back to __add__ and reports the same deprecation.

number += 1  # error: [deprecated] "old addition"

Reflected operators

When the left operand accepts the operation, a deprecated __radd__ on the right operand is not called and does not produce a warning.

from typing_extensions import deprecated

class Left:
    def __add__(self, other: object) -> int:
        return 0

class Right:
    @deprecated("reflected addition")
    def __radd__(self, other: object) -> int:
        return 0

Left() + Right()

Here, int.__add__ does not accept a Right instance, so + calls the deprecated Right.__radd__.

1 + Right()  # error: [deprecated] "reflected addition"

A deprecated method whose parameter does not accept the other operand does not trigger a warning when a compatible reflected method is available.

class RestrictedLeft:
    @deprecated("integer addition")
    def __add__(self, other: int) -> int:
        return 0

class ActiveRight:
    def __radd__(self, other: object) -> int:
        return 0

RestrictedLeft() + ActiveRight()

In-place operators

When __iadd__ accepts the operand, += uses it without calling a deprecated __add__.

from typing_extensions import deprecated

class Number:
    @deprecated("binary addition")
    def __add__(self, other: int) -> "Number":
        return self

    def __iadd__(self, other: int) -> "Number":
        return self

number = Number()
number += 1

A deprecated __iadd__ produces a warning at the augmented assignment.

class OldNumber:
    @deprecated("in-place addition")
    def __iadd__(self, other: int) -> "OldNumber":
        return self

old = OldNumber()
old += 1  # error: [deprecated] "in-place addition"

Callable instances

Calling an instance invokes its __call__ method and reports that method's deprecation.

from typing_extensions import deprecated

class Invocable:
    @deprecated("do not call")
    def __call__(self) -> int:
        return 0

invocable = Invocable()
invocable()  # error: [deprecated] "do not call"

An explicit reference to __call__ is also deprecated. Calling that reference still produces only one warning.

invocable.__call__  # error: [deprecated] "do not call"
invocable.__call__()  # error: [deprecated] "do not call"

Overloaded callable instances

For overloaded __call__ methods, only calls that select a deprecated overload trigger a warning.

from typing import overload
from typing_extensions import deprecated

class Overloaded:
    @overload
    @deprecated("integer call")
    def __call__(self, value: int) -> int: ...
    @overload
    def __call__(self, value: str) -> str: ...
    def __call__(self, value: int | str) -> int | str:
        return value

overloaded = Overloaded()
overloaded(1)  # error: [deprecated] "integer call"
overloaded("one")

Unary operators

If a dunder like __invert__ is deprecated, then the equivalent ~ operator should fire a diagnostic.

Custom operator

from typing_extensions import deprecated

class MyBits:
    @deprecated("MyBits `~` support is broken")
    def __invert__(self):
        return self

x = MyBits()
~x  # error: [deprecated] "MyBits `~` support is broken"

Possibly unbound operator

If the operand's type is a union and the dunder is missing on some members, it's possibly unbound. This should still report the deprecation on the members where it is found and is deprecated, alongside unsupported-operator diagnostic.

from typing_extensions import deprecated

class MyBits:
    @deprecated("MyBits `~` support is broken")
    def __invert__(self):
        return self

class NoBits: ...

def f(x: MyBits | NoBits):
    # error: [unsupported-operator]
    # error: [deprecated]
    ~x

Unions and intersections

A unary operation on a union reports a deprecation if any member's operator is deprecated.

from typing_extensions import deprecated

class Deprecated:
    @deprecated("old inversion")
    def __invert__(self) -> int:
        return 1

class Ordinary:
    def __invert__(self) -> int:
        return 3

def mixed_union(value: Deprecated | Ordinary) -> None:
    ~value  # error: [deprecated] "old inversion"

An intersection can use a non-deprecated implementation instead, so it does not warn when one is available.

def mixed_intersection(value: Deprecated) -> None:
    if isinstance(value, Ordinary):
        ~value

When every applicable implementation is deprecated, one warning includes both messages.

class AlsoDeprecated:
    @deprecated("another old inversion")
    def __invert__(self) -> int:
        return 2

def deprecated_intersection(value: Deprecated) -> None:
    if isinstance(value, AlsoDeprecated):
        # error: [deprecated] "`Deprecated.__invert__`, `AlsoDeprecated.__invert__`"
        ~value

If one component defines the operator conditionally, a deprecated branch can still be selected.

def flag() -> bool:
    return True

class Conditional:
    if flag():
        @deprecated("conditional inversion")
        def __invert__(self) -> int:
            return 1

    else:
        def __invert__(self) -> int:
            return 2

def conditional_intersection(value: Conditional) -> None:
    if isinstance(value, AlsoDeprecated):
        # error: [deprecated] "`Conditional.__invert__`, `AlsoDeprecated.__invert__`"
        ~value

A gradually typed comparison can produce an intersection of bool and Any. The unknown alternative might provide a non-deprecated operator, so inverting it should not warn.

from typing import Any

def gradual_intersection(value: Any) -> None:
    if value is None:
        return

    mask = value == 0
    ~mask

Bool literals

bool.__invert__ is one such case in typeshed. This applies both to bool literals and to arbitrary values of type bool.

~True  # error: [deprecated]

def f(x: bool):
    ~x  # error: [deprecated]

Constrained TypeVars

A unary operation on a constrained type variable can invoke the method from any of its constraints. If several methods are deprecated, their messages appear in one diagnostic.

from typing import TypeVar
from typing_extensions import deprecated

class First:
    @deprecated("first")
    def __invert__(self) -> int:
        return 42

class Second:
    @deprecated("second")
    def __invert__(self) -> int:
        return 42

T = TypeVar("T", First, Second)

def f(value: T) -> None:
    # error: [deprecated] "`First.__invert__`, `Second.__invert__`"
    ~value

Deprecation reporting for one constraint does not depend on whether another constraint supports the operator or on the order of the constraints.

class Third: ...

U = TypeVar("U", Third, First)
V = TypeVar("V", First, Third)

def g(value: U) -> None:
    # error: [unsupported-operator]
    # error: [deprecated]
    ~value

def h(value: V) -> None:
    # error: [unsupported-operator]
    # error: [deprecated]
    ~value

A constraint that is itself a union may contain a deprecated operator even when that operator is missing from another union member.

W = TypeVar("W", First | Third, Second)

def nested_union(value: W) -> None:
    # error: [unsupported-operator]
    # error: [deprecated] "`First.__invert__`, `Second.__invert__`"
    ~value

A deprecated operator should also be reported when its signature cannot accept the implicit unary call.

class Invalid:
    @deprecated("invalid inversion")
    def __invert__(self, required: int) -> int:
        return required

X = TypeVar("X", Invalid, Second)

def invalid_operator(value: X) -> None:
    # error: [unsupported-operator]
    # error: [deprecated] "`Invalid.__invert__`, `Second.__invert__`"
    ~value

Property accessors

Reading a property invokes its getter. A deprecated getter produces a warning on a read, but not on an assignment or deletion.

from typing_extensions import deprecated

class OldGetter:
    @property
    @deprecated("old getter")
    def value(self) -> int:
        return 0

    @value.setter
    def value(self, value: int) -> None: ...
    @value.deleter
    def value(self) -> None: ...

old_getter = OldGetter()
old_getter.value  # error: [deprecated] "old getter"
old_getter.value = 1
del old_getter.value

Assignments and deletions invoke the setter and deleter, respectively. Neither accessor is called when reading the property.

class OldSetter:
    @property
    def value(self) -> int:
        return 0

    @value.setter
    @deprecated("old setter")
    def value(self, value: int) -> None: ...
    @value.deleter
    @deprecated("old deleter")
    def value(self) -> None: ...

old_setter = OldSetter()
old_setter.value
old_setter.value = 1  # error: [deprecated] "old setter"
del old_setter.value  # error: [deprecated] "old deleter"

Access through the class returns the property object without invoking its deprecated getter.

OldGetter.value

Augmented property assignments

Augmented assignment reads and then writes the property. When both the getter and setter are deprecated, it reports each accessor's deprecation.

from typing_extensions import deprecated

class OldBoth:
    @property
    @deprecated("both getter")
    def value(self) -> int:
        return 0

    @value.setter
    @deprecated("both setter")
    def value(self, value: int) -> None: ...

old_both = OldBoth()
# error: [deprecated] "both getter"
# error: [deprecated] "both setter"
old_both.value += 1

Inherited properties

Reading or deleting the property on a subclass instance reports the inherited accessor's deprecation.

from typing_extensions import deprecated

class Parent:
    @property
    @deprecated("parent getter")
    def value(self) -> int:
        return 0

    @value.deleter
    @deprecated("parent deleter")
    def value(self) -> None: ...

class Child(Parent): ...

Child().value  # error: [deprecated] "parent getter"
del Child().value  # error: [deprecated] "parent deleter"

Overriding the getter with a non-deprecated method removes the deprecation on reads.

class ActiveChild(Parent):
    @property
    def value(self) -> int:
        return 0

ActiveChild().value

Properties accessed through super()

Reading a property through super() invokes the parent getter with the instance as its receiver.

from typing_extensions import deprecated

class Parent:
    @property
    @deprecated("parent getter")
    def value(self) -> int:
        return 0

    @value.deleter
    @deprecated("parent deleter")
    def value(self) -> None: ...

class Child(Parent):
    def read(self) -> int:
        return super().value  # error: [deprecated] "parent getter"

Binding super() to a class instead returns the property object without invoking its getter.

super(Child, Child).value

Deleting an attribute on a super() object does not invoke the parent's property deleter.

del super(Child, Child()).value

The same holds when the receiver may be either a super() object or an ordinary instance.

class Ordinary:
    value: int

def delete_union(flag: bool):
    target = super(Child, Child()) if flag else Ordinary()
    del target.value

Metaclass properties

A class is an instance of its metaclass, so reading or writing a metaclass property invokes its accessors.

from typing_extensions import deprecated

class Meta(type):
    @property
    @deprecated("metaclass getter")
    def value(cls) -> int:
        return 0

    @value.setter
    @deprecated("metaclass setter")
    def value(cls, value: int) -> None: ...

class C(metaclass=Meta): ...

C.value  # error: [deprecated] "metaclass getter"
C.value = 1  # error: [deprecated] "metaclass setter"

Access through the metaclass itself returns the property object without invoking its getter.

Meta.value

Properties on unions

An attribute access through a union warns if any member uses a deprecated property.

from typing_extensions import deprecated

class Old:
    @property
    @deprecated("union getter")
    def value(self) -> int:
        return 0

    @value.setter
    @deprecated("union setter")
    def value(self, value: int) -> None: ...

class Active:
    value: int

def check(value: Old | Active):
    value.value  # error: [deprecated] "union getter"
    value.value = 1  # error: [deprecated] "union setter"

An invalid assignment on one union member does not hide a deprecated setter on another member.

class Wrong:
    value: str

def check_invalid(value: Wrong | Old):
    # error: [invalid-assignment]
    # error: [deprecated] "union setter"
    value.value = 1

An invalid assignment still reports deprecations after an isinstance check narrows the union's members to intersections.

class Marker: ...

def check_invalid_intersections(value: Wrong | Old):
    if isinstance(value, Marker):
        # error: [invalid-assignment]
        # error: [deprecated] "union setter"
        value.value = 1

Properties on intersections

An intersection can use a non-deprecated member's attribute instead of a deprecated property. We do not warn when that alternative is available.

from typing_extensions import deprecated

class Old:
    @property
    @deprecated("old getter")
    def value(self) -> int:
        return 0

    @value.setter
    @deprecated("old setter")
    def value(self, value: int) -> None: ...
    @value.deleter
    @deprecated("old deleter")
    def value(self) -> None: ...

class Active:
    value: int

def check(value: Old):
    if isinstance(value, Active):
        value.value
        value.value = 1

A member without the attribute does not provide an alternative accessor, so the deprecated property still applies.

class Marker: ...

def check_marker(value: Old):
    if isinstance(value, Marker):
        value.value  # error: [deprecated] "old getter"
        value.value = 1  # error: [deprecated] "old setter"

When both members define their own deprecated property, reading, assigning, and deleting the attribute report the getter, setter, and deleter deprecations, respectively. Each warning names both declarations.

class AlsoOld:
    @property
    @deprecated("old getter")
    def value(self) -> int:
        return 0

    @value.setter
    @deprecated("old setter")
    def value(self, value: int) -> None: ...
    @value.deleter
    @deprecated("old deleter")
    def value(self) -> None: ...

def check_both(value: Old):
    if isinstance(value, AlsoOld):
        value.value  # error: [deprecated] "`Old.value`, `AlsoOld.value`: old getter"
        value.value = 1  # error: [deprecated] "`Old.value`, `AlsoOld.value`: old setter"
        del value.value  # error: [deprecated] "`Old.value`, `AlsoOld.value`: old deleter"

A non-deprecated getter suppresses the warning on reads. Assignments still warn when both setters are deprecated.

class ActiveGetter:
    @property
    def value(self) -> int:
        return 0

    @value.setter
    @deprecated("old setter")
    def value(self, value: int) -> None: ...

def check_active_getter(value: Old):
    if isinstance(value, ActiveGetter):
        value.value
        value.value = 1  # error: [deprecated] "`Old.value`, `ActiveGetter.value`: old setter"

Invalid property getter calls

The getter below accepts an int, but Python passes a C instance. Reading the property reports both the invalid call and the deprecation.

from typing_extensions import deprecated

class C:
    @property
    @deprecated("invalid getter")
    def value(self: int) -> int:
        return self

# error: [invalid-attribute-access]
# error: [deprecated] "invalid getter"
C().value

Setter deprecations and contextual inference

The ordinary attribute supplies int as the lambda's parameter type. Checking the other member's deprecated setter does not change that inferred type or warn about the non-deprecated assignment.

from collections.abc import Callable
from typing_extensions import deprecated

class Ordinary:
    callback: Callable[[int], object]

class Deprecated:
    @property
    def callback(self) -> object: ...
    @callback.setter
    @deprecated("old setter")
    def callback(self, value: Callable[[str], object]) -> None: ...

def check(value: Ordinary):
    if isinstance(value, Deprecated):
        value.callback = lambda argument: reveal_type(argument)  # revealed: int

Deprecation checks also preserve the str parameter type inferred from a protocol setter.

from typing import Protocol

class Callback(Protocol):
    @property
    def callback(self) -> Callable[[str], object]: ...
    @callback.setter
    @deprecated("callback setter")
    def callback(self, value: Callable[[str], object]) -> None: ...

def check_protocol(value: Callback):
    if isinstance(value, Ordinary):
        value.callback = lambda argument: reveal_type(argument)  # revealed: str

Overloads

Deprecated overloads

A call reports the deprecation of the overload selected by its arguments.

from typing_extensions import deprecated, overload

@overload
@deprecated("strings are no longer supported")
def f(x: str): ...
@overload
def f(x: int): ...
def f(x):
    print(x)

f(1)
f("hello")  # error: [deprecated] "strings are no longer supported"

Referring to the function without calling it does not select an overload and does not warn.

f

Function decorator applications

Applying a decorator reports the deprecation of the selected overload. An incompatible function does not select an overload.

from collections.abc import Callable
from typing import overload
from typing_extensions import deprecated

@overload
@deprecated("string functions are no longer supported")
def decorate(fn: Callable[[], str]) -> str: ...
@overload
def decorate(fn: Callable[[], int]) -> int: ...
def decorate(fn):
    return fn()

# error: [deprecated] "string functions are no longer supported"
@decorate
def string_result() -> str:
    return ""

@decorate  # ok
def integer_result() -> int:
    return 1

# error: [no-matching-overload]
@decorate
def float_result() -> float:
    return 1.0

Class decorator applications

Class decorators also report the overload selected by the decorated class.

from typing import overload
from typing_extensions import deprecated

class Old: ...
class New: ...

@overload
@deprecated("old classes are no longer supported")
def decorate(cls: type[Old]) -> type[Old]: ...
@overload
def decorate(cls: type[New]) -> type[New]: ...
def decorate(cls):
    return cls

# error: [deprecated] "old classes are no longer supported"
@decorate
class OldClass(Old): ...

@decorate  # ok
class NewClass(New): ...

Explicit __call__ of deprecated functions

Referencing a deprecated function through its __call__ method produces only one warning.

from typing_extensions import deprecated

@deprecated("old function")
def old(value: object) -> object:
    return value

# error: [deprecated] "old function"
@old.__call__
def function() -> None: ...

# error: [deprecated] "old function"
@old.__call__
class Class: ...

Conditional decorator applications

A reference to a deprecated function warns once, even when the function is one of several possible decorators. A deprecated implicit call or constructor still produces its own warning.

from typing_extensions import Self, deprecated

@deprecated("old function")
def old(value: object) -> object:
    return value

def new(value: object) -> object:
    return value

class Methods:
    @deprecated("old method")
    def old(self, value: object) -> object:
        return value

class CallableDecorator:
    @deprecated("old __call__")
    def __call__(self, value: object) -> object:
        return value

class InitDecorator:
    @deprecated("old __init__")
    def __init__(self, value: object) -> None: ...

class NewDecorator:
    @deprecated("old __new__")
    def __new__(cls, value: object) -> Self:
        return super().__new__(cls)

callable_decorator = CallableDecorator()
methods = Methods()

def example(flag: bool):
    # error: [deprecated] "old function"
    @(old if flag else new)
    def function() -> None: ...

    # error: [deprecated] "old function"
    @(old if flag else new)
    class Class: ...

    # error: [deprecated] "old method"
    @(methods.old if flag else new)
    def method_function() -> None: ...

    # error: [deprecated] "old method"
    @(methods.old if flag else new)
    class MethodClass: ...

    # error: [deprecated] "old function"
    # error: [deprecated] "old __call__"
    @(old if flag else callable_decorator)
    def callable_function() -> None: ...

    # error: [deprecated] "old function"
    # error: [deprecated] "old __call__"
    @(old if flag else callable_decorator)
    class CallableClass: ...

    # error: [deprecated] "old function"
    # error: [deprecated] "old __init__"
    @(old if flag else InitDecorator)
    def init_function() -> None: ...

    # error: [deprecated] "old function"
    # error: [deprecated] "old __init__"
    @(old if flag else InitDecorator)
    class InitClass: ...

    # error: [deprecated] "old function"
    # error: [deprecated] "old __new__"
    @(old if flag else NewDecorator)
    def new_function() -> None: ...

    # error: [deprecated] "old function"
    # error: [deprecated] "old __new__"
    @(old if flag else NewDecorator)
    class NewClass: ...

Calls through union-valued aliases

Ordinary calls through a union-valued alias also report a deprecated implementation.

from typing_extensions import deprecated

@deprecated("old function")
def old(value: object) -> object:
    return value

def new(value: object) -> object:
    return value

def ordinary_call(flag: bool):
    # error: [deprecated] "old function"
    choice = old if flag else new
    choice(1)  # error: [deprecated] "old function"

Conditional decorators with overloads

The application reports a deprecated overload only when it is selected. A deprecated implementation still takes precedence over a deprecated overload.

from collections.abc import Callable
from typing import overload
from typing_extensions import deprecated

class Old: ...
class New: ...

@overload
@deprecated("string functions are no longer supported")
def decorate(value: Callable[[], str]) -> object: ...
@overload
def decorate(value: Callable[[], int]) -> object: ...
@overload
@deprecated("old classes are no longer supported")
def decorate(value: type[Old]) -> object: ...
@overload
def decorate(value: type[New]) -> object: ...
def decorate(value: object) -> object:
    return value

def identity(value: object) -> object:
    return value

@overload
@deprecated("old overload")
def outdated(value: Callable[[], str]) -> object: ...
@overload
def outdated(value: Callable[[], int]) -> object: ...
@deprecated("old implementation")
def outdated(value: object) -> object:
    return value

def example(flag: bool):
    # error: [deprecated] "string functions are no longer supported"
    @(decorate if flag else identity)
    def string_result() -> str:
        return ""

    @(decorate if flag else identity)  # ok
    def integer_result() -> int:
        return 1

    # error: [deprecated] "old classes are no longer supported"
    @(decorate if flag else identity)
    class OldClass(Old): ...

    @(decorate if flag else identity)  # ok
    class NewClass(New): ...

    # error: [deprecated] "old implementation"
    @(outdated if flag else identity)
    def outdated_result() -> str:
        return ""

Conditional __call__ definitions

An implicit call warns when one possible definition of __call__ is deprecated.

from typing_extensions import deprecated

flag = bool(input())

class Decorator:
    if flag:
        @deprecated("old __call__")
        def __call__(self, value: object) -> object:
            return value

    else:
        def __call__(self, value: object) -> object:
            return value

decorator = Decorator()

# error: [deprecated] "old __call__"
@decorator
def function() -> None: ...

# error: [deprecated] "old __call__"
@decorator
class Class: ...

Dataclass transformer decorators

Class decorators marked with dataclass_transform also report the selected overload's deprecation, while retaining their dataclass behavior.

from typing import overload
from typing_extensions import dataclass_transform, deprecated

class Old: ...
class New: ...

@overload
@deprecated("old classes are no longer supported")
def model(cls: type[Old]) -> type[Old]: ...
@overload
def model(cls: type[New]) -> type[New]: ...
@dataclass_transform()
def model(cls: type[object]) -> type[object]:
    return cls

# error: [deprecated] "old classes are no longer supported"
@model
class OldClass(Old):
    value: int

OldClass(1)  # ok

@model  # ok
class NewClass(New):
    value: int

NewClass(1)  # ok

Callable instances as decorators

The implicit __call__ invocation reports both deprecated overloads and deprecated implementations.

from collections.abc import Callable
from typing import overload
from typing_extensions import deprecated

class Old: ...
class New: ...

class Decorator:
    @overload
    @deprecated("string functions are no longer supported")
    def __call__(self, value: Callable[[], str]) -> str: ...
    @overload
    def __call__(self, value: Callable[[], int]) -> int: ...
    @overload
    @deprecated("old classes are no longer supported")
    def __call__(self, value: type[Old]) -> type[Old]: ...
    @overload
    def __call__(self, value: type[New]) -> type[New]: ...
    def __call__(self, value):
        return value

decorate = Decorator()

# error: [deprecated] "string functions are no longer supported"
@decorate
def string_result() -> str:
    return ""

@decorate  # ok
def integer_result() -> int:
    return 1

# error: [deprecated] "old classes are no longer supported"
@decorate
class OldClass(Old): ...

@decorate  # ok
class NewClass(New): ...

class OldDecorator:
    @deprecated("do not use this decorator")
    def __call__(self, value: object) -> object:
        return value

old = OldDecorator()

# error: [deprecated] "do not use this decorator"
@old
def old_function() -> None: ...

# error: [deprecated] "do not use this decorator"
@old
class AnotherOldClass: ...

An explicit reference to __call__ already reports its deprecation, so applying it produces only one warning.

# error: [deprecated] "do not use this decorator"
@old.__call__
def explicit_call() -> None: ...

# error: [deprecated] "do not use this decorator"
@old.__call__
class ExplicitCallClass: ...

Constructor decorators

When a class is used as a decorator, the selected constructor overload can be deprecated.

from collections.abc import Callable
from typing import overload
from typing_extensions import deprecated

class Decorator:
    @overload
    @deprecated("string functions are no longer supported")
    def __init__(self, fn: Callable[[], str]) -> None: ...
    @overload
    def __init__(self, fn: Callable[[], int]) -> None: ...
    def __init__(self, fn): ...

# error: [deprecated] "string functions are no longer supported"
@Decorator
def string_result() -> str:
    return ""

@Decorator  # ok
def integer_result() -> int:
    return 1

An initializer is also called when __new__ returns an instance of the class, including when the class has a custom metaclass.

from typing_extensions import Self, deprecated

class Decorator:
    def __new__(cls, value: object) -> Self:
        return super().__new__(cls)

    @deprecated("old initializer")
    def __init__(self, value: object) -> None: ...

class Meta(type):
    def __call__(cls, value: object) -> "WithMeta":
        return super().__call__(value)

class WithMeta(Decorator, metaclass=Meta): ...

# error: [deprecated] "old initializer"
@Decorator
def function() -> None: ...

# error: [deprecated] "old initializer"
@Decorator
class Class: ...

# error: [deprecated] "old initializer"
@WithMeta
def meta_function() -> None: ...

# error: [deprecated] "old initializer"
@WithMeta
class MetaClass: ...

Deprecated decorator implementations

The implementation's deprecation takes precedence over an overload's deprecation, and each application produces only one warning.

from collections.abc import Callable
from typing import overload
from typing_extensions import deprecated

@overload
@deprecated("old function overload")
def decorate(value: Callable[[], str]) -> object: ...
@overload
def decorate(value: type[object]) -> object: ...
@deprecated("entire decorator")
def decorate(value: object) -> object:
    return value

# error: [deprecated] "entire decorator"
@decorate
def function() -> str:
    return ""

# error: [deprecated] "entire decorator"
@decorate
class Class: ...

Transparent callable decorators

A decorator that preserves a callable's signature still reports a selected deprecated overload.

from collections.abc import Callable
from typing import ParamSpec, TypeVar, overload
from typing_extensions import deprecated

P = ParamSpec("P")
R = TypeVar("R")

@overload
def preserve(value: int) -> int: ...
@overload
@deprecated("use another decorator")
def preserve(value: Callable[P, R]) -> Callable[P, R]: ...
def preserve(value):
    return value

# error: [deprecated] "use another decorator"
@preserve
def function(value: int) -> str:
    return str(value)

Stacked function decorators

The outer decorator selects an overload using the inner decorator's result.

from collections.abc import Callable
from typing import overload
from typing_extensions import deprecated

@overload
@deprecated("integer overload")
def outer(value: int) -> str: ...
@overload
def outer(value: str) -> str: ...
def outer(value):
    return str(value)

def replace_with_int(fn: Callable[[], int]) -> int:
    return fn()

def replace_with_str(fn: Callable[[], int]) -> str:
    return str(fn())

# error: [deprecated] "integer overload"
@outer
@replace_with_int
def first() -> int:
    return 1

@outer  # ok
@replace_with_str
def second() -> int:
    return 1

Stacked class decorators

An outer decorator is called with the result of the inner decorator. Only the overload selected by that final application determines whether the outer decorator is deprecated.

from typing import overload
from typing_extensions import deprecated

class Base: ...

@overload
@deprecated("class overload")
def outer(value: type[Base]) -> int: ...
@overload
def outer(value: int) -> int: ...
@overload
@deprecated("string overload")
def outer(value: str) -> str: ...
def outer(value):
    return value

def replace_with_int(cls: type[Base]) -> int:
    return 1

def replace_with_str(cls: type[Base]) -> str:
    return ""

@outer  # ok
@replace_with_int
class First(Base): ...

# error: [deprecated] "string overload"
@outer
@replace_with_str
class Second(Base): ...

Decorator applications inside no_type_check

no_type_check suppresses deprecations from decorator applications in either decorator order and inside the function body.

from collections.abc import Callable
from typing import no_type_check, overload
from typing_extensions import deprecated

@overload
@deprecated("string functions are no longer supported")
def decorate(fn: Callable[[], str]) -> str: ...
@overload
def decorate(fn: Callable[[], int]) -> int: ...
def decorate(fn):
    return fn()

@no_type_check
@decorate  # ok
def first() -> str: ...
@decorate  # ok
@no_type_check
def second() -> str: ...
@no_type_check
def outer():
    @decorate  # ok
    def nested() -> str: ...

asynccontextmanager

asynccontextmanager deprecates the overload that accepts an AsyncIterator return annotation.

[environment]
python-version = "3.13"
from collections.abc import AsyncGenerator, AsyncIterator
from contextlib import asynccontextmanager

# error: [deprecated] "Annotating the return type as `-> AsyncIterator[Foo]`"
@asynccontextmanager
async def iterator() -> AsyncIterator[int]:
    yield 1

@asynccontextmanager  # ok
async def generator() -> AsyncGenerator[int, None]:
    yield 1

Deprecated implementations

A deprecated implementation makes every call deprecated. Its message takes precedence over an individual overload's deprecation, and a call produces only one warning.

from typing_extensions import deprecated, overload

@overload
@deprecated("string overload")
def f(x: str): ...
@overload
def f(x: int): ...
@deprecated("entire function")
def f(x):
    print(x)

f(1)  # error: [deprecated] "entire function"
f("hello")  # error: [deprecated] "entire function"

Equivalent return types

An Any argument matches both overloads below. Their return types are equivalent, so overload resolution selects the first. The deprecated second overload does not produce a warning.

from typing import Any, overload
from typing_extensions import deprecated

@overload
def convert(value: int) -> str: ...
@overload
@deprecated("strings are no longer supported")
def convert(value: str) -> str: ...
def convert(value: int | str) -> str:
    return str(value)

def check(value: Any):
    convert(value)

Ambiguous overloads

All three overloads remain possible for an Any argument. Their return types differ, so no single overload wins. The call reports the deprecated overload that remains a possible target.

from typing import Any, overload
from typing_extensions import deprecated

@overload
def convert(value: list[int]) -> int: ...
@overload
@deprecated("string lists are no longer supported")
def convert(value: list[str]) -> str: ...
@overload
def convert(value: bytes) -> bytes: ...
def convert(value): ...
def check(value: Any):
    convert(value)  # error: [deprecated] "string lists are no longer supported"

The same ambiguity can occur within one member of a union. The list[Any] member can select the deprecated overload, even though the bytes member selects a non-deprecated overload.

def check_union(value: list[Any] | bytes):
    convert(value)  # error: [deprecated] "string lists are no longer supported"

Union arguments

A union argument can select different overloads for different members. The call reports a deprecation if any selected overload is deprecated.

from typing import overload
from typing_extensions import deprecated

@overload
def convert(value: int) -> str: ...
@overload
@deprecated("use an integer")
def convert(value: str) -> str: ...
def convert(value: int | str) -> str:
    return str(value)

def check(value: int | str):
    convert(value)  # error: [deprecated] "use an integer"

If no overload accepts the argument, there is no selected overload to report as deprecated.

convert(None)  # error: [no-matching-overload]

Equivalent return types within a union

Each member of a union resolves its overloads separately. The list[Any] member matches the first two overloads, whose equivalent return types select the first. The bytes member selects the third overload. Neither selected overload is deprecated.

from typing import Any, overload
from typing_extensions import deprecated

@overload
def convert(value: list[int]) -> str: ...
@overload
@deprecated("string lists are no longer supported")
def convert(value: list[str]) -> str: ...
@overload
def convert(value: bytes) -> str: ...
def convert(value) -> str:
    return ""

def check(value: list[Any] | bytes):
    convert(value)

Ambiguity in one union member

Ambiguity in one union member does not change how another member selects its overload. The list[Any] member can select the deprecated overload for lists of strings. The set[Any] member's two overloads have equivalent return types, so only its non-deprecated first overload is selected.

from typing import Any, overload
from typing_extensions import deprecated

@overload
def convert(value: list[int]) -> int: ...
@overload
@deprecated("string lists are no longer supported")
def convert(value: list[str]) -> str: ...
@overload
def convert(value: set[int]) -> int: ...
@overload
@deprecated("string sets are no longer supported")
def convert(value: set[str]) -> int: ...
def convert(value): ...
def check(value: list[Any] | set[Any]):
    # error: [deprecated] "The overload of `convert` is deprecated: string lists are no longer supported"
    convert(value)

Calls that select several deprecated overloads

An int | str argument selects a different overload for each member of the union. When both overloads are deprecated, the warning names the function once.

from typing import overload
from typing_extensions import deprecated

@overload
@deprecated("integer overload")
def convert(value: int) -> str: ...
@overload
@deprecated("string overload")
def convert(value: str) -> str: ...
def convert(value: int | str) -> str:
    return str(value)

def check(value: int | str):
    # error: [deprecated] "Possible use of deprecated function: `convert`"
    convert(value)

Shared deprecation messages across overloads

When selected overloads share a deprecation message, the warning includes that message once in both full and concise output. The full diagnostic points to each deprecated overload.

from typing import overload
from typing_extensions import deprecated

@overload
@deprecated("Use `parse` instead. Support ends in version 2.")
def convert(value: int) -> str: ...
@overload
@deprecated("Use `parse` instead. Support ends in version 2.")
def convert(value: str) -> str: ...
def convert(value: int | str) -> str:
    return str(value)

def check(value: int | str):
    # snapshot: deprecated
    convert(value)
warning[deprecated]: Possible use of deprecated function: `convert`
  --> src/mdtest_snippet.py:15:5
   |
15 |     convert(value)
   |     ^^^^^^^ Use `parse` instead. Support ends in version 2.
   |
  ::: src/mdtest_snippet.py:6:5
   |
 6 | def convert(value: int) -> str: ...
   |     -------
 7 | @overload
 8 | @deprecated("Use `parse` instead. Support ends in version 2.")
 9 | def convert(value: str) -> str: ...
   |     -------

Overloads for different receivers

The self annotations restrict which overloads each instance can call. A call on C[str] reports the deprecated string overload, even though binding the method discards the integer overload.

from typing import Generic, TypeVar, overload
from typing_extensions import deprecated

T = TypeVar("T")

class C(Generic[T]):
    @overload
    def method(self: "C[int]", value: int) -> int: ...
    @overload
    @deprecated("string method")
    def method(self: "C[str]", value: str) -> str: ...
    def method(self, value: int | str) -> int | str:
        return value

def check(integer: C[int], string: C[str]):
    integer.method(1)
    string.method("one")  # error: [deprecated] "string method"

Deprecated constructors

Calling a class can invoke __new__, __init__, or a custom metaclass's __call__. We warn about deprecated methods that the call invokes, even when the class itself is not deprecated.

__init__

Calling a class reports the deprecation of its initializer.

from typing_extensions import Self, deprecated

class OldInit:
    @deprecated("old init")
    def __init__(self) -> None: ...

OldInit()  # error: [deprecated] "old init"

An explicit call on an instance also produces only one warning.

def explicit_init(value: OldInit):
    value.__init__()  # error: [deprecated] "old init"

If a non-deprecated __new__ returns an instance of the class, Python still calls the inherited deprecated initializer.

class NewWithOldInit(OldInit):
    def __new__(cls) -> Self:
        return super().__new__(cls)

NewWithOldInit()  # error: [deprecated] "old init"

When __new__ returns an unrelated type, __init__ does not run and produces no warning.

class ReturnsInt(OldInit):
    def __new__(cls) -> int:
        return 0

ReturnsInt()

__new__

Calling a class also reports the deprecation of the method that creates the instance.

from typing_extensions import Self, deprecated

class OldNew:
    @deprecated("old new")
    def __new__(cls) -> Self:
        return super().__new__(cls)

OldNew()  # error: [deprecated] "old new"

Calling __new__ explicitly produces only one warning.

OldNew.__new__(OldNew)  # error: [deprecated] "old new"

Both constructor methods

When both methods are deprecated, the class call produces one warning that points to both declarations and includes both messages.

from typing_extensions import Self, deprecated

class Both:
    @deprecated("old new")
    def __new__(cls) -> Self:
        return super().__new__(cls)

    @deprecated("old init")
    def __init__(self) -> None: ...

# snapshot: deprecated
Both()
warning[deprecated]: Possible use of deprecated methods: `Both.__new__`, `Both.__init__`
  --> src/mdtest_snippet.py:12:1
   |
12 | Both()
   | ^^^^
info: old new
 --> src/mdtest_snippet.py:5:9
  |
5 |     def __new__(cls) -> Self:
  |         ^^^^^^^
info: old init
 --> src/mdtest_snippet.py:9:9
  |
9 |     def __init__(self) -> None: ...
  |         ^^^^^^^^

Metaclass __call__

Calling a class with a custom metaclass invokes the metaclass's __call__ method. If that method is deprecated, the class call produces a warning.

from typing_extensions import deprecated

class Meta(type):
    @deprecated("metaclass call")
    def __call__(cls) -> int:
        return 0

class WithMeta(metaclass=Meta): ...

WithMeta()  # error: [deprecated] "metaclass call"

Calls to an inherited deprecated method

When both union members inherit the same deprecated method, a call reports that method once.

from typing_extensions import deprecated

class Base:
    @deprecated("base call")
    def __call__(self) -> None: ...

class First(Base): ...
class Second(Base): ...

def check(value: First | Second):
    value()  # error: [deprecated] "base call"

Separate calls each produce a warning, even when they are on the same line.

def two_calls(value: First | Second):
    # error: 6 [deprecated] "base call"
    # error: 15 [deprecated] "base call"
    (value(), value())

Calls to an inherited deprecated overload

A deprecated overload inherited by both members of a union also produces only one warning per call.

from typing import overload
from typing_extensions import deprecated

class Overloaded:
    @overload
    @deprecated("integer call")
    def __call__(self, value: int) -> None: ...
    @overload
    def __call__(self, value: str) -> None: ...
    def __call__(self, value: int | str) -> None: ...

class FirstOverload(Overloaded): ...
class SecondOverload(Overloaded): ...

def check_overload(value: FirstOverload | SecondOverload):
    value(1)  # error: [deprecated] "integer call"
    value("one")

Suppressing call deprecations

An inline ignore suppresses the deprecation on an instance's implicit __call__ invocation.

from typing_extensions import deprecated

class Callable:
    @deprecated("do not call")
    def __call__(self) -> None: ...

Callable()()  # ty: ignore[deprecated]

An unreachable call does not produce a warning.

if False:
    Callable()()

The same applies to calls inside a no_type_check function.

from typing import no_type_check

@no_type_check
def unchecked(value: Callable):
    value()

Repeated binary operations

Several combinations of union members can invoke the same deprecated operator. Each expression reports that method once. Repeating the operation still produces a warning at the second expression.

from typing_extensions import Self, deprecated

class Number:
    @deprecated("addition")
    def __add__(self, other: int | str) -> Self:
        return self

class First(Number): ...
class Second(Number): ...

def check(number: First | Second, value: int | str):
    number + value  # error: [deprecated] "addition"
    number + value  # error: [deprecated] "addition"

The same rule applies when augmented assignment falls back to __add__.

def check_augmented(number: First | Second, value: int | str):
    number += value  # error: [deprecated] "addition"

When some members provide __iadd__ and others fall back to __add__, the warning includes the deprecations of both methods.

class InPlace(Number):
    @deprecated("in-place addition")
    def __iadd__(self, other: int | str) -> Self:
        return self

def check_mixed(number: First | InPlace, value: int | str):
    # error: [deprecated] "`Number.__add__`, `InPlace.__iadd__`"
    number += value

Calls to different deprecated methods

Deprecation messages can contain several sentences, semicolons, and line breaks.

from typing_extensions import deprecated

class First:
    @deprecated("Use `invoke` instead. Direct calls are deprecated; support ends in version 2.")
    def __call__(self) -> None: ...

class Second:
    @deprecated("Use `invoke` instead.\nSupport ends in version 3.")
    def __call__(self) -> None: ...

When either method can be called, the warning names both defining classes. The full diagnostic shows each message beside its method's definition, preserving its punctuation and line breaks.

def check(value: First | Second):
    # snapshot: deprecated
    value()
warning[deprecated]: Possible use of deprecated methods: `First.__call__`, `Second.__call__`
  --> src/mdtest_snippet.py:12:5
   |
12 |     value()
   |     ^^^^^
info: Use `invoke` instead. Direct calls are deprecated; support ends in version 2.
 --> src/mdtest_snippet.py:5:9
  |
5 |     def __call__(self) -> None: ...
  |         ^^^^^^^^
info: Use `invoke` instead.
Support ends in version 3.
 --> src/mdtest_snippet.py:9:9
  |
9 |     def __call__(self) -> None: ...
  |         ^^^^^^^^

Calls to deprecated generic methods

The warning includes the defining class's name even when both the class and method have type parameters.

[environment]
python-version = "3.12"
from typing_extensions import deprecated

class First[T]:
    @deprecated("first method")
    def __call__[U](self, value: U) -> U:
        return value

class Second:
    @deprecated("second method")
    def __call__(self, value: int) -> int:
        return value

def check(value: First[int] | Second):
    # error: [deprecated] "Possible use of deprecated methods: `First.__call__`, `Second.__call__`"
    value(1)