Document and rename overlap-overload error code

A new error code was introduced in
python#16061

As per python#16068, we didn't previously
run doc builds on changes to errorcodes.py, causing tests to fail on
master when this was merged.

Renaming the code as per:
python#16061 (comment)
All type ignores should be unsafe, so we should save the unsafe
adjective for things that are really unsafe. As it stands, there are
many cases where overloads overlap somewhat benignly.

Author: hauntsaninja

docs/source/error_code_list.rst

@@ -1114,6 +1114,31 @@ Warn about cases where a bytes object may be converted to a string in an unexpec
     print(f"The alphabet starts with {b!r}")  # The alphabet starts with b'abc'
     print(f"The alphabet starts with {b.decode('utf-8')}")  # The alphabet starts with abc
 
+.. _code-overload-overlap:
+
+Check that overloaded functions don't overlap [overload-overlap]
+----------------------------------------------------------------
+
+Warn if multiple ``@overload`` variants overlap in unsafe ways.
+
+.. code-block:: python
+
+    from typing import overload
+
+    class A: ...
+    class B(A): ...
+
+    @overload
+    def foo(x: B) -> int: ...  # Error: Overloaded function signatures 1 and 2 overlap with incompatible return types  [overload-overlap]
+    @overload
+    def foo(x: A) -> str: ...
+    def foo(x): ...
+
+    def takes_a(a: A) -> str:
+        return foo(a)
+
+    assert isinstance(takes_a(B()), str)  # may fail when run
+
 .. _code-annotation-unchecked:
 
 Notify about an annotation in an unchecked function [annotation-unchecked]

mypy/errorcodes.py

@@ -262,8 +262,8 @@ def __hash__(self) -> int:
 # This is a catch-all for remaining uncategorized errors.
 MISC: Final = ErrorCode("misc", "Miscellaneous other checks", "General")
 
-UNSAFE_OVERLOAD: Final[ErrorCode] = ErrorCode(
-    "unsafe-overload",
+OVERLOAD_OVERLAP: Final[ErrorCode] = ErrorCode(
+    "overload-overlap",
     "Warn if multiple @overload variants overlap in unsafe ways",
     "General",
     sub_code_of=MISC,

mypy/messages.py

@@ -1604,7 +1604,7 @@ def overloaded_signatures_overlap(self, index1: int, index2: int, context: Conte
             "Overloaded function signatures {} and {} overlap with "
             "incompatible return types".format(index1, index2),
             context,
-            code=codes.UNSAFE_OVERLOAD,
+            code=codes.OVERLOAD_OVERLAP,
         )
 
     def overloaded_signature_will_never_match(

mypy/types.py

@@ -3019,7 +3019,7 @@ def get_proper_type(typ: Type | None) -> ProperType | None:
 
 
 @overload
-def get_proper_types(types: list[Type] | tuple[Type, ...]) -> list[ProperType]:  # type: ignore[unsafe-overload]
+def get_proper_types(types: list[Type] | tuple[Type, ...]) -> list[ProperType]:  # type: ignore[overload-overlap]
     ...
 
 

test-data/unit/check-errorcodes.test

@@ -1077,7 +1077,7 @@ x = 1  # type: ignore  # E: Unused "type: ignore" comment  [unused-ignore]
 from typing import overload, Union
 
 @overload
-def unsafe_func(x: int) -> int: ...  # E: Overloaded function signatures 1 and 2 overlap with incompatible return types  [unsafe-overload]
+def unsafe_func(x: int) -> int: ...  # E: Overloaded function signatures 1 and 2 overlap with incompatible return types  [overload-overlap]
 @overload
 def unsafe_func(x: object) -> str: ...
 def unsafe_func(x: object) -> Union[int, str]: