stubtest: additional guidance on errors when runtime is object.__init__ (#19733)

Fixes #19732

This is a simple check to point users in the right direction when they
get errors because their class uses `__new__` but they wrote stubs for
`__init__`. I don't feel strongly about the exact wording used here. I
also considered "Maybe you meant to define `__new__` instead of
`__init__`?".

(cherry picked from commit 530bdc5)

Author: tungol

mypy/stubtest.py

@@ -1053,7 +1053,10 @@ def get_kind(arg_name: str) -> nodes.ArgKind:
 
 
 def _verify_signature(
-    stub: Signature[nodes.Argument], runtime: Signature[inspect.Parameter], function_name: str
+    stub: Signature[nodes.Argument],
+    runtime: Signature[inspect.Parameter],
+    function_name: str,
+    warn_runtime_is_object_init: bool = False,
 ) -> Iterator[str]:
     # Check positional arguments match up
     for stub_arg, runtime_arg in zip(stub.pos, runtime.pos):
@@ -1098,6 +1101,8 @@ def _verify_signature(
                     msg = f'runtime does not have parameter "{stub_arg.variable.name}"'
                     if runtime.varkw is not None:
                         msg += ". Maybe you forgot to make it keyword-only in the stub?"
+                    elif warn_runtime_is_object_init:
+                        msg += ". You may need to write stubs for __new__ instead of __init__."
                     yield msg
                 else:
                     yield f'stub parameter "{stub_arg.variable.name}" is not keyword-only'
@@ -1137,7 +1142,11 @@ def _verify_signature(
                 if arg not in {runtime_arg.name for runtime_arg in runtime.pos[len(stub.pos) :]}:
                     yield f'runtime parameter "{arg}" is not keyword-only'
             else:
-                yield f'runtime does not have parameter "{arg}"'
+                msg = f'runtime does not have parameter "{arg}"'
+                if warn_runtime_is_object_init:
+                    msg += ". You may need to write stubs for __new__ instead of __init__."
+                yield msg
+
     for arg in sorted(set(runtime.kwonly) - set(stub.kwonly)):
         if arg in {stub_arg.variable.name for stub_arg in stub.pos}:
             # Don't report this if we've reported it before
@@ -1223,7 +1232,12 @@ def verify_funcitem(
     if not signature:
         return
 
-    for message in _verify_signature(stub_sig, runtime_sig, function_name=stub.name):
+    for message in _verify_signature(
+        stub_sig,
+        runtime_sig,
+        function_name=stub.name,
+        warn_runtime_is_object_init=runtime is object.__init__,
+    ):
         yield Error(
             object_path,
             "is inconsistent, " + message,
@@ -1333,7 +1347,12 @@ def verify_overloadedfuncdef(
     stub_sig = Signature.from_overloadedfuncdef(stub)
     runtime_sig = Signature.from_inspect_signature(signature)
 
-    for message in _verify_signature(stub_sig, runtime_sig, function_name=stub.name):
+    for message in _verify_signature(
+        stub_sig,
+        runtime_sig,
+        function_name=stub.name,
+        warn_runtime_is_object_init=runtime is object.__init__,
+    ):
         # TODO: This is a little hacky, but the addition here is super useful
         if "has a default value of type" in message:
             message += (