Provide fix guidance

mtsokol · mtsokol · commit d2e40341c7f0 · 2025-05-16T19:48:12.000Z
diff --git a/doc/release/upcoming_changes/28678.deprecation.rst b/doc/release/upcoming_changes/28678.deprecation.rst
@@ -1,2 +1,4 @@
-* ``arr.T`` property has been deprecated for array scalars and arrays with
-  dimensionality different than ``2``.
+* ``arr.T`` property has been deprecated for array scalars and arrays with dimensionality
+  different than ``2`` to be compatible with the Array API standard. To achieve the same
+  behavior when ``arr.ndim != 2``, either ``np.permute_dims(arr, range(arr.ndim)[::-1])``
+  (also compatible with the Array API) or ``arr.transpose()`` can be used.
diff --git a/numpy/_core/src/multiarray/getset.c b/numpy/_core/src/multiarray/getset.c
@@ -852,7 +852,10 @@ array_transpose_get(PyArrayObject *self, void *NPY_UNUSED(ignored))
     if (ndim != 2) {
         if (PyErr_WarnFormat(PyExc_UserWarning, 1,
                 "In the future `.T` property will be supported for "
-                "2-dim arrays only. Here it is %d-dim array.",
+                "2-dim arrays only. Received %d-dim array. Either "
+                "`np.permute_dims(arr, range(arr.ndim)[::-1])` "
+                "(compatible with the Array API) or `arr.transpose()` "
+                "should be used instead.",
                 ndim) < 0) {
             return NULL;
         }
diff --git a/numpy/_core/src/multiarray/scalartypes.c.src b/numpy/_core/src/multiarray/scalartypes.c.src
@@ -1927,7 +1927,11 @@ gentype_transpose_get(PyObject *self, void *NPY_UNUSED(ignored))
 {
     if (PyErr_WarnEx(PyExc_UserWarning,
             "In the future `.T` property for array scalars will "
-            "raise an error.", 1) < 0) {
+            "raise an error. If you call `.T` on an array scalar "
+            "intentionally you can safely drop it. In other cases "
+            "`np.permute_dims(arr, range(arr.ndim)[::-1])` "
+            "(compatible with the Array API) or `arr.transpose()` "
+            "should be used instead.", 1) < 0) {
         return NULL;
     }
     Py_INCREF(self);
diff --git a/numpy/_core/tests/test_deprecations.py b/numpy/_core/tests/test_deprecations.py
@@ -464,5 +464,5 @@ def test_deprecated_T_non_2dim():
                 UserWarning,
                 match="In the future `.T` property will be "
                       "supported for 2-dim arrays only. "
-                      f"Here it is {len(shape)}-dim array."):
+                      f"Received {len(shape)}-dim array."):
             np.ones(shape).T

Original file line number	Diff line number	Diff line change
`@@ -1927,7 +1927,11 @@ gentype_transpose_get(PyObject self, void NPY_UNUSED(ignored))`
`1927`	`1927`	`{`
`1928`	`1928`	`if (PyErr_WarnEx(PyExc_UserWarning,`
`1929`	`1929`	"In the future `.T` property for array scalars will "
`1930`		`- "raise an error.", 1) < 0) {`
	`1930`	+ "raise an error. If you call `.T` on an array scalar "
	`1931`	`+ "intentionally you can safely drop it. In other cases "`
	`1932`	+ "`np.permute_dims(arr, range(arr.ndim)[::-1])` "
	`1933`	+ "(compatible with the Array API) or `arr.transpose()` "
	`1934`	`+ "should be used instead.", 1) < 0) {`
`1931`	`1935`	`return NULL;`
`1932`	`1936`	`}`
`1933`	`1937`	`Py_INCREF(self);`