feat(types) Numpy.typing.NDArray

include/pybind11/eigen/matrix.h

@@ -225,16 +225,17 @@ struct EigenProps {
         = !show_c_contiguous && show_order && requires_col_major;
 
     static constexpr auto descriptor
-        = const_name("numpy.ndarray[") + npy_format_descriptor<Scalar>::name + const_name("[")
-          + const_name<fixed_rows>(const_name<(size_t) rows>(), const_name("m")) + const_name(", ")
-          + const_name<fixed_cols>(const_name<(size_t) cols>(), const_name("n")) + const_name("]")
-          +
+        = const_name("numpy.typing.NDArray[") + npy_format_descriptor<Scalar>::name
+          + const_name("[") + const_name<fixed_rows>(const_name<(size_t) rows>(), const_name("m"))
+          + const_name(", ") + const_name<fixed_cols>(const_name<(size_t) cols>(), const_name("n"))
+          + const_name("]") +
           // For a reference type (e.g. Ref<MatrixXd>) we have other constraints that might need to
           // be satisfied: writeable=True (for a mutable reference), and, depending on the map's
           // stride options, possibly f_contiguous or c_contiguous.  We include them in the
           // descriptor output to provide some hint as to why a TypeError is occurring (otherwise
-          // it can be confusing to see that a function accepts a 'numpy.ndarray[float64[3,2]]' and
-          // an error message that you *gave* a numpy.ndarray of the right type and dimensions.
+          // it can be confusing to see that a function accepts a
+          // 'numpy.typing.NDArray[float64[3,2]]' and an error message that you *gave* a
+          // numpy.ndarray of the right type and dimensions.
           const_name<show_writeable>(", flags.writeable", "")
           + const_name<show_c_contiguous>(", flags.c_contiguous", "")
           + const_name<show_f_contiguous>(", flags.f_contiguous", "") + const_name("]");

include/pybind11/eigen/tensor.h

@@ -128,7 +128,7 @@ struct get_tensor_descriptor {
               < static_cast<int>(Type::Layout)
           == static_cast<int>(Eigen::RowMajor) > (", flags.c_contiguous", ", flags.f_contiguous");
     static constexpr auto value
-        = const_name("numpy.ndarray[") + npy_format_descriptor<typename Type::Scalar>::name
+        = const_name("numpy.typing.NDArray[") + npy_format_descriptor<typename Type::Scalar>::name
           + const_name("[") + eigen_tensor_helper<remove_cv_t<Type>>::dimensions_descriptor
           + const_name("]") + const_name<ShowDetails>(details, const_name("")) + const_name("]");
 };

include/pybind11/numpy.h

@@ -175,7 +175,6 @@ inline numpy_internals &get_numpy_internals() {
 PYBIND11_NOINLINE module_ import_numpy_core_submodule(const char *submodule_name) {
     module_ numpy = module_::import("numpy");
     str version_string = numpy.attr("__version__");
-
     module_ numpy_lib = module_::import("numpy.lib");
     object numpy_version = numpy_lib.attr("NumpyVersion")(version_string);
     int major_version = numpy_version.attr("major").cast<int>();
@@ -1445,7 +1444,9 @@ struct pyobject_caster<array_t<T, ExtraFlags>> {
     static handle cast(const handle &src, return_value_policy /* policy */, handle /* parent */) {
         return src.inc_ref();
     }
-    PYBIND11_TYPE_CASTER(type, handle_type_name<type>::name);
+    PYBIND11_TYPE_CASTER(type,
+                         io_name("numpy.typing.ArrayLike",
+                                 "numpy.typing.NDArray[" + npy_format_descriptor<T>::name + "]"));
 };
 
 template <typename T>
@@ -2183,7 +2184,7 @@ vectorize_helper<Func, Return, Args...> vectorize_extractor(const Func &f, Retur
 template <typename T, int Flags>
 struct handle_type_name<array_t<T, Flags>> {
     static constexpr auto name
-        = const_name("numpy.ndarray[") + npy_format_descriptor<T>::name + const_name("]");
+        = const_name("numpy.typing.NDArray[") + npy_format_descriptor<T>::name + const_name("]");
 };
 
 PYBIND11_NAMESPACE_END(detail)

tests/test_eigen_matrix.py

@@ -95,19 +95,20 @@ def test_mutator_descriptors():
     with pytest.raises(TypeError) as excinfo:
         m.fixed_mutator_r(zc)
     assert (
-        "(arg0: numpy.ndarray[numpy.float32[5, 6],"
+        "(arg0: numpy.typing.NDArray[numpy.float32[5, 6],"
         " flags.writeable, flags.c_contiguous]) -> None" in str(excinfo.value)
     )
     with pytest.raises(TypeError) as excinfo:
         m.fixed_mutator_c(zr)
     assert (
-        "(arg0: numpy.ndarray[numpy.float32[5, 6],"
+        "(arg0: numpy.typing.NDArray[numpy.float32[5, 6],"
         " flags.writeable, flags.f_contiguous]) -> None" in str(excinfo.value)
     )
     with pytest.raises(TypeError) as excinfo:
         m.fixed_mutator_a(np.array([[1, 2], [3, 4]], dtype="float32"))
-    assert "(arg0: numpy.ndarray[numpy.float32[5, 6], flags.writeable]) -> None" in str(
-        excinfo.value
+    assert (
+        "(arg0: numpy.typing.NDArray[numpy.float32[5, 6], flags.writeable]) -> None"
+        in str(excinfo.value)
     )
     zr.flags.writeable = False
     with pytest.raises(TypeError):
@@ -201,7 +202,7 @@ def test_negative_stride_from_python(msg):
         msg(excinfo.value)
         == """
         double_threer(): incompatible function arguments. The following argument types are supported:
-            1. (arg0: numpy.ndarray[numpy.float32[1, 3], flags.writeable]) -> None
+            1. (arg0: numpy.typing.NDArray[numpy.float32[1, 3], flags.writeable]) -> None
 
         Invoked with: """
         + repr(np.array([5.0, 4.0, 3.0], dtype="float32"))
@@ -213,7 +214,7 @@ def test_negative_stride_from_python(msg):
         msg(excinfo.value)
         == """
         double_threec(): incompatible function arguments. The following argument types are supported:
-            1. (arg0: numpy.ndarray[numpy.float32[3, 1], flags.writeable]) -> None
+            1. (arg0: numpy.typing.NDArray[numpy.float32[3, 1], flags.writeable]) -> None
 
         Invoked with: """
         + repr(np.array([7.0, 4.0, 1.0], dtype="float32"))
@@ -700,25 +701,25 @@ def test_dense_signature(doc):
     assert (
         doc(m.double_col)
         == """
-        double_col(arg0: numpy.ndarray[numpy.float32[m, 1]]) -> numpy.ndarray[numpy.float32[m, 1]]
+        double_col(arg0: numpy.typing.NDArray[numpy.float32[m, 1]]) -> numpy.typing.NDArray[numpy.float32[m, 1]]
     """
     )
     assert (
         doc(m.double_row)
         == """
-        double_row(arg0: numpy.ndarray[numpy.float32[1, n]]) -> numpy.ndarray[numpy.float32[1, n]]
+        double_row(arg0: numpy.typing.NDArray[numpy.float32[1, n]]) -> numpy.typing.NDArray[numpy.float32[1, n]]
     """
     )
     assert doc(m.double_complex) == (
         """
-        double_complex(arg0: numpy.ndarray[numpy.complex64[m, 1]])"""
-        """ -> numpy.ndarray[numpy.complex64[m, 1]]
+        double_complex(arg0: numpy.typing.NDArray[numpy.complex64[m, 1]])"""
+        """ -> numpy.typing.NDArray[numpy.complex64[m, 1]]
     """
     )
     assert doc(m.double_mat_rm) == (
         """
-        double_mat_rm(arg0: numpy.ndarray[numpy.float32[m, n]])"""
-        """ -> numpy.ndarray[numpy.float32[m, n]]
+        double_mat_rm(arg0: numpy.typing.NDArray[numpy.float32[m, n]])"""
+        """ -> numpy.typing.NDArray[numpy.float32[m, n]]
     """
     )
 

tests/test_eigen_tensor.py

@@ -271,23 +271,24 @@ def test_round_trip_references_actually_refer(m):
 @pytest.mark.parametrize("m", submodules)
 def test_doc_string(m, doc):
     assert (
-        doc(m.copy_tensor) == "copy_tensor() -> numpy.ndarray[numpy.float64[?, ?, ?]]"
+        doc(m.copy_tensor)
+        == "copy_tensor() -> numpy.typing.NDArray[numpy.float64[?, ?, ?]]"
     )
     assert (
         doc(m.copy_fixed_tensor)
-        == "copy_fixed_tensor() -> numpy.ndarray[numpy.float64[3, 5, 2]]"
+        == "copy_fixed_tensor() -> numpy.typing.NDArray[numpy.float64[3, 5, 2]]"
     )
     assert (
         doc(m.reference_const_tensor)
-        == "reference_const_tensor() -> numpy.ndarray[numpy.float64[?, ?, ?]]"
+        == "reference_const_tensor() -> numpy.typing.NDArray[numpy.float64[?, ?, ?]]"
     )
 
     order_flag = f"flags.{m.needed_options.lower()}_contiguous"
     assert doc(m.round_trip_view_tensor) == (
-        f"round_trip_view_tensor(arg0: numpy.ndarray[numpy.float64[?, ?, ?], flags.writeable, {order_flag}])"
-        f" -> numpy.ndarray[numpy.float64[?, ?, ?], flags.writeable, {order_flag}]"
+        f"round_trip_view_tensor(arg0: numpy.typing.NDArray[numpy.float64[?, ?, ?], flags.writeable, {order_flag}])"
+        f" -> numpy.typing.NDArray[numpy.float64[?, ?, ?], flags.writeable, {order_flag}]"
     )
     assert doc(m.round_trip_const_view_tensor) == (
-        f"round_trip_const_view_tensor(arg0: numpy.ndarray[numpy.float64[?, ?, ?], {order_flag}])"
-        " -> numpy.ndarray[numpy.float64[?, ?, ?]]"
+        f"round_trip_const_view_tensor(arg0: numpy.typing.NDArray[numpy.float64[?, ?, ?], {order_flag}])"
+        " -> numpy.typing.NDArray[numpy.float64[?, ?, ?]]"
     )

tests/test_numpy_array.py

@@ -321,13 +321,13 @@ def test_overload_resolution(msg):
         msg(excinfo.value)
         == """
         overloaded(): incompatible function arguments. The following argument types are supported:
-            1. (arg0: numpy.ndarray[numpy.float64]) -> str
-            2. (arg0: numpy.ndarray[numpy.float32]) -> str
-            3. (arg0: numpy.ndarray[numpy.int32]) -> str
-            4. (arg0: numpy.ndarray[numpy.uint16]) -> str
-            5. (arg0: numpy.ndarray[numpy.int64]) -> str
-            6. (arg0: numpy.ndarray[numpy.complex128]) -> str
-            7. (arg0: numpy.ndarray[numpy.complex64]) -> str
+            1. (arg0: numpy.typing.NDArray[numpy.float64]) -> str
+            2. (arg0: numpy.typing.NDArray[numpy.float32]) -> str
+            3. (arg0: numpy.typing.NDArray[numpy.int32]) -> str
+            4. (arg0: numpy.typing.NDArray[numpy.uint16]) -> str
+            5. (arg0: numpy.typing.NDArray[numpy.int64]) -> str
+            6. (arg0: numpy.typing.NDArray[numpy.complex128]) -> str
+            7. (arg0: numpy.typing.NDArray[numpy.complex64]) -> str
 
         Invoked with: 'not an array'
     """
@@ -343,8 +343,8 @@ def test_overload_resolution(msg):
     assert m.overloaded3(np.array([1], dtype="intc")) == "int"
     expected_exc = """
         overloaded3(): incompatible function arguments. The following argument types are supported:
-            1. (arg0: numpy.ndarray[numpy.int32]) -> str
-            2. (arg0: numpy.ndarray[numpy.float64]) -> str
+            1. (arg0: numpy.typing.NDArray[numpy.int32]) -> str
+            2. (arg0: numpy.typing.NDArray[numpy.float64]) -> str
 
         Invoked with: """
 
@@ -528,7 +528,7 @@ def test_index_using_ellipsis():
     ],
 )
 def test_format_descriptors_for_floating_point_types(test_func):
-    assert "numpy.ndarray[numpy.float" in test_func.__doc__
+    assert "numpy.typing.NDArray[numpy.float" in test_func.__doc__
 
 
 @pytest.mark.parametrize("forcecast", [False, True])

tests/test_numpy_dtypes.py

@@ -373,7 +373,7 @@ def test_complex_array():
 def test_signature(doc):
     assert (
         doc(m.create_rec_nested)
-        == "create_rec_nested(arg0: int) -> numpy.ndarray[NestedStruct]"
+        == "create_rec_nested(arg0: int) -> numpy.typing.NDArray[NestedStruct]"
     )
 
 

tests/test_numpy_vectorize.py

@@ -150,7 +150,7 @@ def test_docs(doc):
     assert (
         doc(m.vectorized_func)
         == """
-        vectorized_func(arg0: numpy.ndarray[numpy.int32], arg1: numpy.ndarray[numpy.float32], arg2: numpy.ndarray[numpy.float64]) -> object
+        vectorized_func(arg0: numpy.typing.NDArray[numpy.int32], arg1: numpy.typing.NDArray[numpy.float32], arg2: numpy.typing.NDArray[numpy.float64]) -> object
     """
     )
 
@@ -212,12 +212,12 @@ def test_passthrough_arguments(doc):
         + ", ".join(
             [
                 "arg0: float",
-                "arg1: numpy.ndarray[numpy.float64]",
-                "arg2: numpy.ndarray[numpy.float64]",
-                "arg3: numpy.ndarray[numpy.int32]",
+                "arg1: numpy.typing.NDArray[numpy.float64]",
+                "arg2: numpy.typing.NDArray[numpy.float64]",
+                "arg3: numpy.typing.NDArray[numpy.int32]",
                 "arg4: int",
                 "arg5: m.numpy_vectorize.NonPODClass",
-                "arg6: numpy.ndarray[numpy.float64]",
+                "arg6: numpy.typing.NDArray[numpy.float64]",
             ]
         )
         + ") -> object"