PEP 561 stub packages should take precedence over bundled .pyi stubs

NumPy relies on bundled .pyi stubs for static typing. They live side-by-side with the .py (if they exist). See e.g. https://github.com/numpy/numpy/tree/main/numpy.

NumType is a static-typing project that we are developing. It comes with (different) numpy-stubs stubs-only package for numpy. It is a backwards-incompatible rework of the stubs that are bundled with numpy containing experimental new features, and will therefore be opt-in (once released).

If both numpy and NumType's numpy-stubs are installed, PEP 561 states that numpy-stubs should take precedence over the ones from numpy. Mypy does this the other way around, effectively ignoring the new numpy-stubs.

This effectively means that we currently cannot support mypy. So I consider this to be a big problem.

The only workaround I was able find is to delete all .pyi in the local numpy installation directory. But this isn't something we can realistically ask of our users.
So if any other workarounds come to mind, please let me know :)

Repro-repo with additional details

https://github.com/jorenham/mypy-pep561-numpy-issue.

Relevant section of the spec: https://typing.python.org/en/latest/spec/distributing.html#import-resolution-ordering

I'm not familiar with the mypy codebase, but maybe it's related to the order of these conditions mypy.modulefinder.FindModuleCache._find_module?

mypy/mypy/modulefinder.py

Lines 513 to 523 in 7b4f631

    
           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

reproduce python#18997

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

Navigation Menu

Repository navigation

PEP 561 stub packages should take precedence over bundled `.pyi` stubs #18997

Repro-repo with additional details

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

	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

PEP 561 stub packages should take precedence over bundled .pyi stubs #18997

Description

Repro-repo with additional details

Activity

JelleZijlstra commented on Apr 29, 2025

jorenham commented on Apr 29, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

PEP 561 stub packages should take precedence over bundled `.pyi` stubs #18997