Prioritize .pyi from -stubs packages over bundled .pyi (#19001)

<!-- If this pull request fixes an issue, add "Fixes #NNN" with the
issue number. -->

This fixes the import resolution order for stubs from a `-stubs` package
and stubs bundled with a `py.typed` package, and fixes #18997.

Besides the unit tests, the effectiveness of this fix is also
demonstrated at
https://github.com/jorenham/mypy-pep561-numpy-issue#mypy-jorenhamfix-18997-with-numtype

After investigating a bit more, it looks like mypy's incorrect
prioritization of stubs was limited to `__init__.pyi`. I confirmed this
by adding `reveal_type(np.dtypes.StringDType())` to the `main.pyi` in
https://github.com/jorenham/mypy-pep561-numpy-issue. With `mypy==1.15.0`
installed, it correctly showed `numpy.dtypes.StringDType` *without*
NumType, and `numpy.dtypes.StringDType[Never]` *with* NumType installed.
So both #18997 and this PR only apply to `__init__.pyi`.

Author: jorenham

mypy/modulefinder.py

@@ -506,21 +506,24 @@ def _find_module(self, id: str, use_typeshed: bool) -> ModuleSearchResult:
             dir_prefix = base_dir
             for _ in range(len(components) - 1):
                 dir_prefix = os.path.dirname(dir_prefix)
+
+            # Stubs-only packages always take precedence over py.typed packages
+            path_stubs = f"{base_path}-stubs{sepinit}.pyi"
+            if fscache.isfile_case(path_stubs, dir_prefix):
+                if verify and not verify_module(fscache, id, path_stubs, dir_prefix):
+                    near_misses.append((path_stubs, dir_prefix))
+                else:
+                    return path_stubs
+
             # Prefer package over module, i.e. baz/__init__.py* over baz.py*.
             for extension in PYTHON_EXTENSIONS:
                 path = base_path + sepinit + extension
-                path_stubs = base_path + "-stubs" + sepinit + extension
                 if fscache.isfile_case(path, dir_prefix):
                     has_init = True
                     if verify and not verify_module(fscache, id, path, dir_prefix):
                         near_misses.append((path, dir_prefix))
                         continue
                     return path
-                elif fscache.isfile_case(path_stubs, dir_prefix):
-                    if verify and not verify_module(fscache, id, path_stubs, dir_prefix):
-                        near_misses.append((path_stubs, dir_prefix))
-                        continue
-                    return path_stubs
 
             # In namespace mode, register a potential namespace package
             if self.options and self.options.namespace_packages:

mypy/test/testmodulefinder.py

@@ -195,6 +195,9 @@ def test__packages_with_ns(self) -> None:
             ("pkg_typed.b", self.path("pkg_typed", "b", "__init__.py")),
             ("pkg_typed.b.c", self.path("pkg_typed", "b", "c.py")),
             ("pkg_typed.a.a_var", ModuleNotFoundReason.NOT_FOUND),
+            # Regular package with py.typed, bundled stubs, and external stubs-only package
+            ("pkg_typed_w_stubs", self.path("pkg_typed_w_stubs-stubs", "__init__.pyi")),
+            ("pkg_typed_w_stubs.spam", self.path("pkg_typed_w_stubs-stubs", "spam.pyi")),
             # Regular package without py.typed
             ("pkg_untyped", ModuleNotFoundReason.FOUND_WITHOUT_TYPE_HINTS),
             ("pkg_untyped.a", ModuleNotFoundReason.FOUND_WITHOUT_TYPE_HINTS),
@@ -250,6 +253,9 @@ def test__packages_without_ns(self) -> None:
             ("pkg_typed.b", self.path("pkg_typed", "b", "__init__.py")),
             ("pkg_typed.b.c", self.path("pkg_typed", "b", "c.py")),
             ("pkg_typed.a.a_var", ModuleNotFoundReason.NOT_FOUND),
+            # Regular package with py.typed, bundled stubs, and external stubs-only package
+            ("pkg_typed_w_stubs", self.path("pkg_typed_w_stubs-stubs", "__init__.pyi")),
+            ("pkg_typed_w_stubs.spam", self.path("pkg_typed_w_stubs-stubs", "spam.pyi")),
             # Regular package without py.typed
             ("pkg_untyped", ModuleNotFoundReason.FOUND_WITHOUT_TYPE_HINTS),
             ("pkg_untyped.a", ModuleNotFoundReason.FOUND_WITHOUT_TYPE_HINTS),

test-data/packages/modulefinder-site-packages/foo-stubs/qux.pyi

@@ -0,0 +1 @@
+qux_var: int

test-data/packages/modulefinder-site-packages/pkg_typed_w_stubs-stubs/__init__.pyi

@@ -0,0 +1 @@
+pkg_typed_w_stubs_var: str = ...

test-data/packages/modulefinder-site-packages/pkg_typed_w_stubs-stubs/spam.pyi

@@ -0,0 +1 @@
+spam_var: str

test-data/packages/modulefinder-site-packages/pkg_typed_w_stubs/__init__.py

@@ -0,0 +1 @@
+pkg_typed_w_stubs_var = "pkg_typed_w_stubs"

test-data/packages/modulefinder-site-packages/pkg_typed_w_stubs/__init__.pyi

@@ -0,0 +1 @@
+pkg_typed_w_stubs_var: object

test-data/packages/modulefinder-site-packages/pkg_typed_w_stubs/py.typed

@@ -0,0 +1 @@
+spam_var = "spam"

test-data/packages/modulefinder-site-packages/pkg_typed_w_stubs/spam.py

@@ -0,0 +1 @@
+spam_var: object