Add basic support for PEP 702 (@deprecated).

docs/source/command_line.rst

@@ -533,6 +533,12 @@ potentially problematic or redundant in some way.
 
         This limitation will be removed in future releases of mypy.
 
+.. option:: --report-deprecated-as-error
+
+    By default, mypy emits notes if your code imports or uses deprecated
+    features.    This flag converts such notes to errors, causing mypy to
+    eventually finish with a non-zero exit code.  Features are considered
+    deprecated when decorated with ``warnings.deprecated``.
 
 .. _miscellaneous-strictness-flags:
 

docs/source/error_code_list2.rst

@@ -231,6 +231,44 @@ incorrect control flow or conditional checks that are accidentally always true o
         # Error: Statement is unreachable  [unreachable]
         print('unreachable')
 
+.. _code-deprecated:
+
+Check that imported or used feature is deprecated [deprecated]
+--------------------------------------------------------------
+
+By default, mypy generates a note if your code imports a deprecated feature explicitly with a
+``from mod import depr`` statement or uses a deprecated feature imported otherwise or defined
+locally.  Features are considered deprecated when decorated with ``warnings.deprecated``, as
+specified in `PEP 702 <https://peps.python.org/pep-0702>`_.  You can silence single notes via
+``# type: ignore[deprecated]`` or turn off this check completely via ``--disable-error-code=deprecated``.
+Use the :option:`--report-deprecated-as-error <mypy --report-deprecated-as-error>` option for
+more strictness, which turns all such notes into errors.
+
+.. note::
+
+    The ``warnings`` module provides the ``@deprecated`` decorator since Python 3.13.
+    To use it with older Python versions, import it from ``typing_extensions`` instead.
+
+Examples:
+
+.. code-block:: python
+
+    # mypy: report-deprecated-as-error
+
+    # Error: abc.abstractproperty is deprecated: Deprecated, use 'property' with 'abstractmethod' instead
+    from abc import abstractproperty
+
+    from typing_extensions import deprecated
+
+    @deprecated("use new_function")
+    def old_function() -> None:
+        print("I am old")
+
+    # Error: __main__.old_function is deprecated: use new_function
+    old_function()
+    old_function()  # type: ignore[deprecated]
+
+
 .. _code-redundant-expr:
 
 Check that expression is redundant [redundant-expr]

mypy/checker.py

@@ -184,6 +184,7 @@
 )
 from mypy.types import (
     ANY_STRATEGY,
+    DEPRECATED_TYPE_NAMES,
     MYPYC_NATIVE_INT_NAMES,
     OVERLOAD_NAMES,
     AnyType,
@@ -636,6 +637,10 @@ def _visit_overloaded_func_def(self, defn: OverloadedFuncDef) -> None:
         if len(defn.items) == 1:
             self.fail(message_registry.MULTIPLE_OVERLOADS_REQUIRED, defn)
 
+        for item in defn.items:
+            if isinstance(item, Decorator) and isinstance(ct := item.func.type, CallableType):
+                self.create_deprecation_warning(ct, item.decorators)
+
         if defn.is_property:
             # HACK: Infer the type of the property.
             assert isinstance(defn.items[0], Decorator)
@@ -654,6 +659,17 @@ def _visit_overloaded_func_def(self, defn: OverloadedFuncDef) -> None:
             self.fail(message_registry.INCONSISTENT_ABSTRACT_OVERLOAD, defn)
         if defn.impl:
             defn.impl.accept(self)
+            if (
+                isinstance(defn.impl, Decorator)
+                and isinstance(defn.impl.func.type, CallableType)
+                and ((deprecated := defn.impl.func.type.deprecated) is not None)
+            ):
+                if isinstance(defn.type, (CallableType, Overloaded)):
+                    defn.type.deprecated = deprecated
+                for subdef in defn.items:
+                    type_ = get_proper_type(subdef.type)
+                    if isinstance(type_, (CallableType, Overloaded)):
+                        type_.deprecated = deprecated
         if not defn.is_property:
             self.check_overlapping_overloads(defn)
             if defn.type is None:
@@ -2406,6 +2422,7 @@ def check__exit__return_type(self, defn: FuncItem) -> None:
     def visit_class_def(self, defn: ClassDef) -> None:
         """Type check a class definition."""
         typ = defn.info
+        self.create_deprecation_warning(typ, defn.decorators)
         for base in typ.mro[1:]:
             if base.is_final:
                 self.fail(message_registry.CANNOT_INHERIT_FROM_FINAL.format(base.name), defn)
@@ -2835,6 +2852,12 @@ def check_metaclass_compatibility(self, typ: TypeInfo) -> None:
         )
 
     def visit_import_from(self, node: ImportFrom) -> None:
+        for name, _ in node.names:
+            if (sym := self.globals.get(name)) is not None:
+                if isinstance(sym.node, TypeInfo):
+                    self.warn_deprecated(sym.node, node)
+                elif isinstance(typ := get_proper_type(sym.type), (CallableType, Overloaded)):
+                    self.warn_deprecated(typ, node)
         self.check_import(node)
 
     def visit_import_all(self, node: ImportAll) -> None:
@@ -2923,6 +2946,16 @@ def visit_assignment_stmt(self, s: AssignmentStmt) -> None:
 
         Handle all kinds of assignment statements (simple, indexed, multiple).
         """
+
+        if isinstance(s.rvalue, TempNode) and s.rvalue.no_rhs:
+            for lvalue in s.lvalues:
+                if (
+                    isinstance(lvalue, NameExpr)
+                    and isinstance(var := lvalue.node, Var)
+                    and isinstance(instance := get_proper_type(var.type), Instance)
+                ):
+                    self.check_deprecated(instance.type, s)
+
         # Avoid type checking type aliases in stubs to avoid false
         # positives about modern type syntax available in stubs such
         # as X | Y.
@@ -4667,6 +4700,8 @@ def visit_operator_assignment_stmt(self, s: OperatorAssignmentStmt) -> None:
         if inplace:
             # There is __ifoo__, treat as x = x.__ifoo__(y)
             rvalue_type, method_type = self.expr_checker.check_op(method, lvalue_type, s.rvalue, s)
+            if isinstance(method_type := get_proper_type(method_type), (CallableType, Overloaded)):
+                self.warn_deprecated(method_type, s)
             if not is_subtype(rvalue_type, lvalue_type):
                 self.msg.incompatible_operator_assignment(s.op, s)
         else:
@@ -4992,6 +5027,8 @@ def visit_del_stmt(self, s: DelStmt) -> None:
                     )
 
     def visit_decorator(self, e: Decorator) -> None:
+        if isinstance(ct := e.func.type, CallableType):
+            self.create_deprecation_warning(ct, e.decorators)
         for d in e.decorators:
             if isinstance(d, RefExpr):
                 if d.fullname == "typing.no_type_check":
@@ -7519,6 +7556,69 @@ def has_valid_attribute(self, typ: Type, name: str) -> bool:
     def get_expression_type(self, node: Expression, type_context: Type | None = None) -> Type:
         return self.expr_checker.accept(node, type_context=type_context)
 
+    def create_deprecation_warning(
+        self, typ: CallableType | Overloaded | TypeInfo, decorators: Iterable[Expression]
+    ) -> None:
+        """Create a warning when visiting a deprecated (decorated) callable, overload or
+        class that may be used later if the deprecated feature is used."""
+
+        if isinstance(typ, CallableType):
+            if (defn := typ.definition) is None:
+                name = f"function {typ.name}"
+            else:
+                name = f"function {defn.fullname}"
+        elif isinstance(typ, Overloaded):
+            if isinstance(func := typ.items[0].definition, FuncDef):
+                name = f"function {func.fullname}"
+            else:
+                name = f"function {typ.name}"
+        else:
+            name = f"class {typ.fullname}"
+
+        overload = False
+        deprecation: str | None = None
+        for decorator in decorators:
+            if (
+                isinstance(typ, CallableType)
+                and isinstance(decorator, NameExpr)
+                and (decorator.fullname in OVERLOAD_NAMES)
+            ):
+                overload = True
+                if deprecation is not None:
+                    self.msg.note("@overload should be placed before @deprecated", decorator)
+            elif (
+                isinstance(decorator, CallExpr)
+                and isinstance(callee := decorator.callee, NameExpr)
+                and (callee.fullname in DEPRECATED_TYPE_NAMES)
+                and (len(args := decorator.args) >= 1)
+                and isinstance(arg := args[0], StrExpr)
+                and ((value := arg.value) is not None)
+            ):
+                deprecation = value
+
+        if deprecation is not None:
+            if overload:
+                typ.deprecated = f"overload {typ} of {name} is deprecated: {deprecation}"
+            else:
+                typ.deprecated = f"{name} is deprecated: {deprecation}"
+
+    def check_deprecated(
+        self, typ: CallableType | Overloaded | TypeInfo, context: Context
+    ) -> None:
+        """Warn if deprecated and not directly imported with a `from` statement."""
+        if typ.deprecated is not None:
+            for imp in self.tree.imports:
+                if isinstance(imp, ImportFrom) and any(typ.name == n[0] for n in imp.names):
+                    break
+            else:
+                self.warn_deprecated(typ, context)
+
+    def warn_deprecated(self, typ: CallableType | Overloaded | TypeInfo, context: Context) -> None:
+        """Warn if deprecated."""
+        if (deprecated := typ.deprecated) is not None:
+            warn = self.msg.fail if self.options.report_deprecated_as_error else self.msg.note
+            warn(deprecated, context, code=codes.DEPRECATED)
+
 
 class CollectArgTypeVarTypes(TypeTraverserVisitor):
     """Collects the non-nested argument types in a set."""

mypy/checkexpr.py

@@ -354,7 +354,12 @@ def visit_name_expr(self, e: NameExpr) -> Type:
         """
         self.chk.module_refs.update(extract_refexpr_names(e))
         result = self.analyze_ref_expr(e)
-        return self.narrow_type_from_binder(e, result)
+        narrowed = self.narrow_type_from_binder(e, result)
+        if isinstance(e.node, TypeInfo):
+            self.chk.check_deprecated(e.node, e)
+        elif isinstance(typ := get_proper_type(narrowed), (CallableType, Overloaded)):
+            self.chk.check_deprecated(typ, e)
+        return narrowed
 
     def analyze_ref_expr(self, e: RefExpr, lvalue: bool = False) -> Type:
         result: Type | None = None
@@ -1475,6 +1480,8 @@ def check_call_expr_with_callee_type(
             object_type=object_type,
         )
         proper_callee = get_proper_type(callee_type)
+        if isinstance(proper_callee, (CallableType, Overloaded)):
+            self.chk.check_deprecated(proper_callee, e)
         if isinstance(e.callee, RefExpr) and isinstance(proper_callee, CallableType):
             # Cache it for find_isinstance_check()
             if proper_callee.type_guard is not None:
@@ -3252,7 +3259,12 @@ def visit_member_expr(self, e: MemberExpr, is_lvalue: bool = False) -> Type:
         """Visit member expression (of form e.id)."""
         self.chk.module_refs.update(extract_refexpr_names(e))
         result = self.analyze_ordinary_member_access(e, is_lvalue)
-        return self.narrow_type_from_binder(e, result)
+        narrowed = self.narrow_type_from_binder(e, result)
+        if isinstance(e.node, TypeInfo):
+            self.chk.warn_deprecated(e.node, e)
+        elif isinstance(typ := get_proper_type(narrowed), (CallableType, Overloaded)):
+            self.chk.warn_deprecated(typ, e)
+        return narrowed
 
     def analyze_ordinary_member_access(self, e: MemberExpr, is_lvalue: bool) -> Type:
         """Analyse member expression or member lvalue."""
@@ -3477,6 +3489,8 @@ def visit_op_expr(self, e: OpExpr) -> Type:
             else:
                 assert_never(use_reverse)
             e.method_type = method_type
+            if isinstance(mt := get_proper_type(method_type), (CallableType, Overloaded)):
+                self.chk.check_deprecated(mt, e)
             return result
         else:
             raise RuntimeError(f"Unknown operator {e.op}")
@@ -3793,6 +3807,8 @@ def check_method_call_by_name(
             chk=self.chk,
             in_literal_context=self.is_literal_context(),
         )
+        if isinstance(mt := get_proper_type(method_type), (CallableType, Overloaded)):
+            self.chk.warn_deprecated(mt, context)
         return self.check_method_call(method, base_type, method_type, args, arg_kinds, context)
 
     def check_union_method_call_by_name(

mypy/checkmember.py

@@ -316,9 +316,19 @@ def analyze_instance_member_access(
 
         if method.is_property:
             assert isinstance(method, OverloadedFuncDef)
-            first_item = method.items[0]
-            assert isinstance(first_item, Decorator)
-            return analyze_var(name, first_item.var, typ, info, mx)
+            getter = method.items[0]
+            assert isinstance(getter, Decorator)
+            if (
+                mx.is_lvalue
+                and (len(items := method.items) > 1)
+                and isinstance(setter := items[1], Decorator)
+            ):
+                if isinstance(co := setter.func.type, (CallableType, Overloaded)):
+                    mx.chk.warn_deprecated(co, mx.context)
+            return analyze_var(name, getter.var, typ, info, mx)
+        elif isinstance(co := method.type, (CallableType, Overloaded)):
+            mx.chk.warn_deprecated(co, mx.context)
+
         if mx.is_lvalue:
             mx.msg.cant_assign_to_method(mx.context)
         if not isinstance(method, OverloadedFuncDef):
@@ -773,6 +783,9 @@ def analyze_var(
         result = t
         typ = get_proper_type(typ)
 
+        if var.is_property and isinstance(typ, CallableType):
+            mx.chk.warn_deprecated(typ, mx.context)
+
         call_type: ProperType | None = None
         if var.is_initialized_in_class and (not is_instance_var(var) or mx.is_operator):
             if isinstance(typ, FunctionLike) and not typ.is_type_obj():

mypy/errorcodes.py

@@ -293,5 +293,11 @@ def __hash__(self) -> int:
     "General",
 )
 
+DEPRECATED: Final = ErrorCode(
+    "deprecated",
+    "Warn when importing or using deprecated (overloaded) functions, methods or classes",
+    "General",
+)
+
 # This copy will not include any error codes defined later in the plugins.
 mypy_error_codes = error_codes.copy()

mypy/errors.py

@@ -20,7 +20,7 @@
 
 # Show error codes for some note-level messages (these usually appear alone
 # and not as a comment for a previous error-level message).
-SHOW_NOTE_CODES: Final = {codes.ANNOTATION_UNCHECKED}
+SHOW_NOTE_CODES: Final = {codes.ANNOTATION_UNCHECKED, codes.DEPRECATED}
 
 # Do not add notes with links to error code docs to errors with these codes.
 # We can tweak this set as we get more experience about what is helpful and what is not.

mypy/main.py

@@ -800,6 +800,13 @@ def add_invertible_flag(
         help="Warn about statements or expressions inferred to be unreachable",
         group=lint_group,
     )
+    add_invertible_flag(
+        "--report-deprecated-as-error",
+        default=False,
+        strict_flag=False,
+        help="Report importing or using deprecated features as errors instead of notes",
+        group=lint_group,
+    )
 
     # Note: this group is intentionally added here even though we don't add
     # --strict to this group near the end.

mypy/nodes.py

@@ -2942,6 +2942,7 @@ class is generic then it will be a type constructor of higher kind.
         "self_type",
         "dataclass_transform_spec",
         "is_type_check_only",
+        "deprecated",
     )
 
     _fullname: str  # Fully qualified name
@@ -3095,6 +3096,9 @@ class is generic then it will be a type constructor of higher kind.
     # Is set to `True` when class is decorated with `@typing.type_check_only`
     is_type_check_only: bool
 
+    # The type's deprecation message (in case it is deprecated)
+    deprecated: str | None
+
     FLAGS: Final = [
         "is_abstract",
         "is_enum",
@@ -3152,6 +3156,7 @@ def __init__(self, names: SymbolTable, defn: ClassDef, module_name: str) -> None
         self.self_type = None
         self.dataclass_transform_spec = None
         self.is_type_check_only = False
+        self.deprecated = None
 
     def add_type_vars(self) -> None:
         self.has_type_var_tuple_type = False
@@ -3374,6 +3379,7 @@ def serialize(self) -> JsonDict:
                 if self.dataclass_transform_spec is not None
                 else None
             ),
+            "deprecated": self.deprecated,
         }
         return data
 
@@ -3441,6 +3447,7 @@ def deserialize(cls, data: JsonDict) -> TypeInfo:
             ti.dataclass_transform_spec = DataclassTransformSpec.deserialize(
                 data["dataclass_transform_spec"]
             )
+        ti.deprecated = data.get("deprecated")
         return ti
 
 

mypy/options.py

@@ -172,6 +172,9 @@ def __init__(self) -> None:
         # declared with a precise type
         self.warn_return_any = False
 
+        # Report importing or using deprecated features as errors instead of notes.
+        self.report_deprecated_as_error = False
+
         # Warn about unused '# type: ignore' comments
         self.warn_unused_ignores = False