From 6d92318ee951bd42b01787109d385aa35dcbf3a1 Mon Sep 17 00:00:00 2001
From: Christoph Tyralla <c.tyralla@bjoernsen.de>
Date: Thu, 4 Jul 2024 09:18:35 +0200
Subject: [PATCH] document the new option

---
 docs/source/command_line.rst     |  6 ++++++
 docs/source/error_code_list2.rst | 34 ++++++++++++++++++++++++++++++++
 mypy/main.py                     |  7 +++++++
 3 files changed, 47 insertions(+)

diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst
index 50a6ef65f4d0..8a23ce8301e0 100644
--- a/docs/source/command_line.rst
+++ b/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:: --warn-deprecated
+
+    This flag will make mypy report an error whenever your code imports a deprecated
+    function or class with a ``from mod import depr" statement or uses a deprecated
+    function, method or class imported otherwise or defined locally.  Features are
+    considered deprecated when decorated with ``warnings.deprecated``.
 
 .. _miscellaneous-strictness-flags:
 
diff --git a/docs/source/error_code_list2.rst b/docs/source/error_code_list2.rst
index 0655ef2d35d8..84edbe948cbf 100644
--- a/docs/source/error_code_list2.rst
+++ b/docs/source/error_code_list2.rst
@@ -231,6 +231,40 @@ 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]
+--------------------------------------------------------------
+
+If you use :option:`--warn-deprecated <mypy --warn-deprecated>`, mypy generates a note if
+your code imports a deprecated function or class with a ``from mod import depr" statement
+or uses a deprecated function, method or class 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>`_.
+
+.. 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: warn-deprecated
+
+    # Note: 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")
+
+    # Note: __main__.old_function is deprecated: use new_function
+    old_function()
+
 .. _code-redundant-expr:
 
 Check that expression is redundant [redundant-expr]
diff --git a/mypy/main.py b/mypy/main.py
index 05044335ecee..514aa916dfa1 100644
--- a/mypy/main.py
+++ b/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(
+        "--warn-deprecated",
+        default=False,
+        strict_flag=False,
+        help="Warn when importing or using deprecated features",
+        group=lint_group,
+    )
 
     # Note: this group is intentionally added here even though we don't add
     # --strict to this group near the end.