feat(types) Numpy.typing.NDArray

[InvincibleRMC]

Description

Switches to using numpy.typing.NDArray for typing annotations over numpy.ndarray. This is because numpy.ndarray is implemented with the first argument for some future size annotation. See numpy/numpy#16544. Since the first argument is for the size annotation the typing of the numpy.ndarray is basically not being used. I also modified the eigen matrix/tensor to numpy.typing.NDArray as well even though stubgen fails to generate stubs since numpy.typing.NDArray[numpy.float64[...]] is not a valid type.

def foo(x: numpy.typing.NDArray[numpy.float64]) -> None:
    reveal_type(x)  # ndarray[Any, dtype[floating[_64Bit]]
    reveal_type(x.dtype)  # dtype[float64]

def bar(x: numpy.ndarray[numpy.float64]) -> None:
    reveal_type(x)  # ndarray[float64, Any]
    reveal_type(x.dtype)  # Any

Suggested changelog entry:

    Switched to `numpy.typing.NDArray` 

[rwgk]

I don't know enough about typing to meaningfully weigh the pros and cons of changing from ndarray to NDArray. @henryiii could you help with that?

Regarding the tuple[()] change, we have this already:

pybind11/include/pybind11/typing.h

Lines 138 to 142 in 51c2aa1

	template <>
	struct handle_type_name<typing::Tuple<>> {
	// PEP 484 specifies this syntax for an empty tuple
	static constexpr auto name = const_name("tuple[()]");
	};

Is your change needed anyway? Could you send a separate, small PR for that, including a test that fails without your change?

[henryiii]

NDArray is the public type for NDArrays, and hides the "size" related type (as described above). It also uses a different form for the DType. Just curious, what about changing it to numpy.ndarray[Any, numpy.float64]?

FYI, I get an error on your example:

$ bat tmp.py
───────┬─────────────────────────────────────────
       │ File: tmp.py
───────┼─────────────────────────────────────────
   1   │ import numpy
   2   │ from typing import Any
   3   │
   4   │ v: numpy.typing.NDArray[numpy.float64]
   5   │ reveal_type(v)
   6   │ reveal_type(v.dtype)
   7   │
   8   │ q: numpy.ndarray[Any, numpy.float64]
   9   │ reveal_type(q)
  10   │ reveal_type(q.dtype)
  11   │
  12   │
───────┴─────────────────────────────────────────
$ pipx install mypy
$ pipx inject mypy numpy
$ mypy tmp.py
tmp.py:5: note: Revealed type is "numpy.ndarray[Any, numpy.dtype[numpy.floating[numpy._typing._64Bit]]]"
tmp.py:6: note: Revealed type is "numpy.dtype[numpy.floating[numpy._typing._64Bit]]"
tmp.py:8: error: Type argument "floating[_64Bit]" of "ndarray" must be a subtype of "dtype[Any]"  [type-var]
tmp.py:9: note: Revealed type is "numpy.ndarray[Any, numpy.floating[numpy._typing._64Bit]]"
tmp.py:10: note: Revealed type is "numpy.floating[numpy._typing._64Bit]"
Found 1 error in 1 file (checked 1 source file)

[InvincibleRMC]

In my example I have numpy.ndarray[numpy.float64] which is what was currently being done to shown the error. You have numpy.ndarray[Any, numpy.float64] which is also incorrect. It would need to be numpy.ndarray[Any, numpy.dtype[numpy.float64]]] to create the proper type annotation without numpy.typing. If you would prefer numpy.ndarray[Any, numpy.dtype[numpy.float64]]] I can update it to be that.