Add option to selectively disable deprecation warnings (#18641)

Suggested in
#18192 (comment)

Fixes #18435

Author: cdce8p

Diff for: docs/source/command_line.rst

@@ -556,6 +556,26 @@ potentially problematic or redundant in some way.
     notes, causing mypy to eventually finish with a zero exit code. Features
     are considered deprecated when decorated with ``warnings.deprecated``.
 
+.. option:: --deprecated-calls-exclude
+
+    This flag allows to selectively disable :ref:`deprecated<code-deprecated>` warnings
+    for functions and methods defined in specific packages, modules, or classes.
+    Note that each exclude entry acts as a prefix. For example (assuming ``foo.A.func`` is deprecated):
+
+    .. code-block:: python
+
+        # mypy --enable-error-code deprecated
+        #      --deprecated-calls-exclude=foo.A
+        import foo
+
+        foo.A().func()  # OK, the deprecated warning is ignored
+
+        # file foo.py
+        from typing_extensions import deprecated
+        class A:
+            @deprecated("Use A.func2 instead")
+            def func(self): pass
+
 .. _miscellaneous-strictness-flags:
 
 Miscellaneous strictness flags

Diff for: docs/source/config_file.rst

@@ -666,6 +666,16 @@ section of the command line docs.
     Shows a warning when encountering any code inferred to be unreachable or
     redundant after performing type analysis.
 
+.. confval:: deprecated_calls_exclude
+
+    :type: comma-separated list of strings
+
+    Selectively excludes functions and methods defined in specific packages,
+    modules, and classes from the :ref:`deprecated<code-deprecated>` error code.
+    This also applies to all submodules of packages (i.e. everything inside
+    a given prefix). Note, this option does not support per-file configuration,
+    the exclusions list is defined globally for all your code.
+
 
 Suppressing errors
 ******************

Diff for: docs/source/error_code_list2.rst

@@ -243,6 +243,8 @@ locally.  Features are considered deprecated when decorated with ``warnings.depr
 specified in `PEP 702 <https://peps.python.org/pep-0702>`_.
 Use the :option:`--report-deprecated-as-note <mypy --report-deprecated-as-note>` option to
 turn all such errors into notes.
+Use :option:`--deprecated-calls-exclude <mypy --deprecated-calls-exclude>` to hide warnings
+for specific functions, classes and packages.
 
 .. note::
 

Diff for: mypy/checker.py

@@ -7865,6 +7865,10 @@ def warn_deprecated(self, node: Node | None, context: Context) -> None:
             isinstance(node, (FuncDef, OverloadedFuncDef, TypeInfo))
             and ((deprecated := node.deprecated) is not None)
             and not self.is_typeshed_stub
+            and not any(
+                node.fullname == p or node.fullname.startswith(f"{p}.")
+                for p in self.options.deprecated_calls_exclude
+            )
         ):
             warn = self.msg.note if self.options.report_deprecated_as_note else self.msg.fail
             warn(deprecated, context, code=codes.DEPRECATED)

Diff for: mypy/main.py

@@ -826,6 +826,14 @@ def add_invertible_flag(
         help="Report importing or using deprecated features as notes instead of errors",
         group=lint_group,
     )
+    lint_group.add_argument(
+        "--deprecated-calls-exclude",
+        metavar="MODULE",
+        action="append",
+        default=[],
+        help="Disable deprecated warnings for functions/methods coming"
+        " from specific package, module, or class",
+    )
 
     # Note: this group is intentionally added here even though we don't add
     # --strict to this group near the end.
@@ -1369,6 +1377,7 @@ def set_strict_flags() -> None:
         )
 
     validate_package_allow_list(options.untyped_calls_exclude)
+    validate_package_allow_list(options.deprecated_calls_exclude)
 
     options.process_error_codes(error_callback=parser.error)
     options.process_incomplete_features(error_callback=parser.error, warning_callback=print)

Diff for: mypy/options.py

@@ -182,6 +182,10 @@ def __init__(self) -> None:
         # Report importing or using deprecated features as errors instead of notes.
         self.report_deprecated_as_note = False
 
+        # Allow deprecated calls from function coming from modules/packages
+        # in this list (each item effectively acts as a prefix match)
+        self.deprecated_calls_exclude: list[str] = []
+
         # Warn about unused '# type: ignore' comments
         self.warn_unused_ignores = False
 

Diff for: mypy/typeanal.py

@@ -823,6 +823,10 @@ def check_and_warn_deprecated(self, info: TypeInfo, ctx: Context) -> None:
             (deprecated := info.deprecated)
             and not self.is_typeshed_stub
             and not (self.api.type and (self.api.type.fullname == info.fullname))
+            and not any(
+                info.fullname == p or info.fullname.startswith(f"{p}.")
+                for p in self.options.deprecated_calls_exclude
+            )
         ):
             for imp in self.cur_mod_node.imports:
                 if isinstance(imp, ImportFrom) and any(info.name == n[0] for n in imp.names):

Diff for: test-data/unit/check-deprecated.test

@@ -797,5 +797,56 @@ def g(x: int) -> int: ...
 @overload
 def g(x: str) -> str: ...
 def g(x: Union[int, str]) -> Union[int, str]: ...
+[builtins fixtures/tuple.pyi]
+
+[case testDeprecatedExclude]
+# flags: --enable-error-code=deprecated --deprecated-calls-exclude=m.C --deprecated-calls-exclude=m.D --deprecated-calls-exclude=m.E.f --deprecated-calls-exclude=m.E.g --deprecated-calls-exclude=m.E.__add__
+from m import C, D, E
+
+[file m.py]
+from typing import Union, overload
+from typing_extensions import deprecated
+
+@deprecated("use C2 instead")
+class C:
+    def __init__(self) -> None: ...
+
+c: C
+C()
+C.__init__(c)
+
+class D:
+    @deprecated("use D.g instead")
+    def f(self) -> None: ...
+
+    def g(self) -> None: ...
+
+D.f
+D().f
+D().f()
+
+class E:
+    @overload
+    def f(self, x: int) -> int: ...
+    @overload
+    def f(self, x: str) -> str: ...
+    @deprecated("use E.f2 instead")
+    def f(self, x: Union[int, str]) -> Union[int, str]: ...
+
+    @deprecated("use E.h instead")
+    def g(self) -> None: ...
+
+    @overload
+    @deprecated("no A + int")
+    def __add__(self, v: int) -> None: ...
+    @overload
+    def __add__(self, v: str) -> None: ...
+    def __add__(self, v: Union[int, str]) -> None: ...
+
+E().f(1)
+E().f("x")
 
+e = E()
+e.g()
+e + 1
 [builtins fixtures/tuple.pyi]