BUG: no module named 'numpy._typing._ufunc'

[jeertmans]

Describe the issue:

When importing numpy.testing with type checking enable, I get the following error message (see context below).

Reproduce the code example:

import typing

typing.TYPE_CHECKING=True

import numpy.typing  # This fails

Error message:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/home/eertmans/.local/lib/python3.10/site-packages/numpy/typing/__init__.py", line 158, in <module>
    from numpy._typing import (
  File "/home/eertmans/.local/lib/python3.10/site-packages/numpy/_typing/__init__.py", line 209, in <module>
    from ._ufunc import (
ModuleNotFoundError: No module named 'numpy._typing._ufunc'

Runtime information:

1.23.0
3.10.12 (main, Jun 11 2023, 05:26:28) [GCC 11.4.0]

Context for the issue:

So I initially faced some issue in Sphinx 7.2, see sphinx-doc/sphinx#11652, and it turns out it was because they now import with typing.TYPE_CHECKING=True with autodoc, which causes some import error.

After filing an issue on the Jax repo, see google/jax#17385, I am now filing an issue here, because the earliest traces of the error are found when importing numpy.testing.

[BvB93]

This is not a bug though? The numpy._typing._ufunc import is placed behind the if TYPE_CHECKING guard exactly because it doesn't exist at runtime; it's a stub-only module that exclusively contains type definitions (_typeshed being another very prominent example).

This very much looks like a sphinx issue to me, as in its current state a global constant is altered while they lack a way of dealing with all the ramifications of doing so.

[jeertmans]

Oops me example code is wrong, this is typing I imported, not testing (I will edit).

To me, it looks like each module has its own view of what the TYPE_CHECKING implies, and it’s quite hard to know where the bug really is 😅

[BvB93]

While the official docs are admittedly somewhat slim they do state clearly that its value should be assumed as True by type checkers and False at runtime.

In addition, PEP 484 clearly states that the constant is intended to be used for code that "must be seen by a type checker (or other static analysis tools) but should not be executed". The latter very much means that stub files, which are intended for type checkers (among others) rather than runtime, are fair game, if not one of its primary intended use cases.

[aphearin]

In this recent PR I encountered a very similar issue with the same traceback to a ModuleNotFoundError in numpy. This is only a problem for my docs builds with Sphinx v7.2.5 on RTD (my docs render a notebook that uses numpy and jax, so this seems very similar). When I pin to Sphinx v7.2.4 I no longer get this error. This seems consistent with the original suggestion that this is somehow an issue with sphinx, and also with the coincidental timing of Sphinx v7.2.5 release date of August 31, 2023.

[BvB93]

I'm going to close this issue though as this is very much a sphinx issue, and one that will persist as such as long as they'll keep using typing.TYPE_CHECKING = True during runtime without a way of dealing with things like stub-only modules and more other type-check specific code that one might find in such blocks. Apparently they are reconsidering their approach to TYPE_CHECKING (xref sphinx-doc/sphinx#11652 (comment)), but again: this is a discussion that belongs on the Sphinx repo.