[stubtest] Improve checking of positional-only parameters in dunder methods (#19593)

Currently, mypy treats all special methods as being implicitly
positional-only. This creates a blind spot for stubtest, since it means
that stubtest isn't sensitive to whether special methods in stub files
are typed as being positional-only or not.

This PR adds an internal option to disable the
positional-only-special-method heuristic when running stubtest. This
way, stubtest can see the actual stub signatures as written in the stub
files, so we can meaningfully compare them against the runtime
signatures.

Now, stubtest will warn about dunder methods that are positional-only at
runtime but keyword-or-positional in the stubs. Note that it still
doesn't warn about the reverse (keyword-or-positional at runtime but
positional-only in the stubs). The latter might be worth revisiting as
well, but the typeshed hits are less obvious and there are a number of
cases where this is done deliberately that would need allowlist entries.

Author: brianschubert

mypy/fastparse.py

@@ -913,7 +913,7 @@ def do_func_def(
 
         lineno = n.lineno
         args = self.transform_args(n.args, lineno, no_type_check=no_type_check)
-        if special_function_elide_names(n.name):
+        if self.options.pos_only_special_methods and special_function_elide_names(n.name):
             for arg in args:
                 arg.pos_only = True
 

mypy/options.py

@@ -413,6 +413,9 @@ def __init__(self) -> None:
         # Export line-level, limited, fine-grained dependency information in cache data
         # (undocumented feature).
         self.export_ref_info = False
+        # Treat special methods as being implicitly positional-only.
+        # Set to False when running stubtest.
+        self.pos_only_special_methods = True
 
         self.disable_bytearray_promotion = False
         self.disable_memoryview_promotion = False

mypy/stubtest.py

@@ -1081,7 +1081,6 @@ def _verify_signature(
             and not stub_arg.variable.name.startswith("__")
             and stub_arg.variable.name.strip("_") != "self"
             and stub_arg.variable.name.strip("_") != "cls"
-            and not is_dunder(function_name, exclude_special=True)  # noisy for dunder methods
         ):
             yield (
                 f'stub parameter "{stub_arg.variable.name}" should be positional-only '
@@ -2301,6 +2300,7 @@ def test_stubs(args: _Arguments, use_builtins_fixtures: bool = False) -> int:
     options.use_builtins_fixtures = use_builtins_fixtures
     options.show_traceback = args.show_traceback
     options.pdb = args.pdb
+    options.pos_only_special_methods = False
 
     if options.config_file:
 

mypy/test/teststubtest.py

@@ -1724,6 +1724,16 @@ def test_dunders(self) -> Iterator[Case]:
             runtime="class D:\n  def __class_getitem__(cls, type): ...",
             error=None,
         )
+        yield Case(
+            stub="class E:\n  def __getitem__(self, item: object) -> object: ...",
+            runtime="class E:\n  def __getitem__(self, item: object, /) -> object: ...",
+            error="E.__getitem__",
+        )
+        yield Case(
+            stub="class F:\n  def __getitem__(self, item: object, /) -> object: ...",
+            runtime="class F:\n  def __getitem__(self, item: object) -> object: ...",
+            error=None,
+        )
 
     @collect_cases
     def test_not_subclassable(self) -> Iterator[Case]: