MAINT: Deprecate `.T` property for non-2dim arrays and scalars #28678

mtsokol · 2025-04-10T11:52:46Z

As the title says, this PR deprecates .T property for non-2dim arrays and scalars, in order to be compatible with the Array API: link.

mattip · 2025-04-10T13:24:33Z

I agree with @charris’s relabeling: this should not target a point release rather 2.3

mtsokol · 2025-04-10T14:17:53Z

I agree with @charris’s relabeling: this should not target a point release rather 2.3

That's right - done!

mtsokol · 2025-04-10T14:19:54Z

To get docs build green we need matplotlib/matplotlib#29896 in first (and matplotlib bugfix release)

ngoldbaum

Given the number of places the tests needed to be updated, I bet this will be a noisy deprecation. Maybe worth pinging the mailing list?

ngoldbaum · 2025-04-11T16:27:33Z

numpy/_core/src/multiarray/getset.c

+    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.",


Suggested change

"2-dim arrays only. Here it is %d-dim array.",

"2-dim arrays only. Received %d-dim array.",

This should also suggest how to fix code triggering the warning

ngoldbaum · 2025-04-11T16:27:44Z

doc/release/upcoming_changes/28678.deprecation.rst

@@ -0,0 +1,2 @@
+* ``arr.T`` property has been deprecated for array scalars and arrays with
+  dimensionality different than ``2``.


This should also suggest how to fix the deprecation warning.

seberg · 2025-04-14T13:11:45Z

numpy/_core/src/multiarray/getset.c

+                "In the future `.T` property will be supported for "
+                "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()` "


I would delete the note and at least re-order this. It nudges users to something less convenient for what seems very little reason to me.
A user who needs array API is a library author and will already not use .T here anyway.

It may be good to note that .mT exists to swap the last two axes only (If just to increase awareness).

And what if someone uses .T to reverse axes for ndim>2 cases anyway? I can remove Array API suggestion but how about keeping arr.transpose() for people who want to retain existing behavior.

I think that's what Sebastian is saying - to leave arr.transpose() or at least mention it first and mention .mT as well.

I feel it currently makes it seem that arr.transpose() is somehow a not the preferred solution, but for those users who run into it it will almost certainly be the preferred one.

Thanks for an explanation! I updated the message as you suggested.

seberg · 2025-04-14T13:15:36Z

numpy/_core/tests/test_deprecations.py

+
+def test_deprecated_T_non_2dim():
+    # Deprecated in Numpy 2.3, 2025-04
+    with pytest.warns(UserWarning, match="In the future `.T` property for "


Please use assert_deprecated as all other tests in this file. That ensures that the error path is also tested, even if that is rather trivial here.

I didn't use assert_deprecated because it's missing match= parameter to actually match the warning message, but I can use it instead.

because it's missing match= parameter to actually match the warning message

Seems reasonable to add it, assuming that's easy.

IIRC it does, but takes the message from the class, but not sure. And yeah, I don't actually care about using it but I do care abot a habit of testing the error path.

because it's missing match= parameter to actually match the warning message

Seems reasonable to add it, assuming that's easy.

I like this idea - added msg_patterns argument to assert_deprecated.

seberg · 2025-04-14T13:16:23Z

numpy/_core/src/multiarray/getset.c

@@ -848,6 +848,18 @@ array_flat_set(PyArrayObject *self, PyObject *val, void *NPY_UNUSED(ignored))
 static PyObject *
 array_transpose_get(PyArrayObject *self, void *NPY_UNUSED(ignored))
 {
+    int ndim = PyArray_NDIM(self);
+    if (ndim != 2) {


Add a comment /* DEPRECATED ... (you can find similar ones elsewhere).

seberg · 2025-04-14T13:16:44Z

numpy/_core/src/multiarray/getset.c

+                "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.",


Add (Deprecated NumPy 2....) as all our deprecation warnings should have.

seberg · 2025-04-14T13:19:57Z

numpy/_core/src/multiarray/getset.c

@@ -848,6 +848,18 @@ array_flat_set(PyArrayObject *self, PyObject *val, void *NPY_UNUSED(ignored))
 static PyObject *
 array_transpose_get(PyArrayObject *self, void *NPY_UNUSED(ignored))
 {
+    int ndim = PyArray_NDIM(self);
+    if (ndim != 2) {
+        if (PyErr_WarnFormat(PyExc_UserWarning, 1,


Why a UserWarning? Please use a DeprecationWarning, or actually, use the DEPRECATE macro.

We could use a visible deprecation warning if we want to inform new users who accidentally get it wrong. But only if we take the trouble to check that very few libraries use this (i.e. there are few places in existing code where DeprecationWarning would be hidden, but VisibleDeprecationWarning wouldn't be).

Given the number of places the tests needed to be updated, I bet this will be a noisy deprecation.

So, it must clearly be a DeprecationWarning. This should be taken very slowly, i.e. in a year or so a VisibleDeprecationWarning.

Done - for array scalars in scalartypes.c.src I used DEPRECATE macro, but here I kept PyErr_WarnFormat, now with a DeprecationWarning, because it allows formatting contrary to DEPRECATE.

tylerjereddy · 2025-04-19T21:32:20Z

doc/release/upcoming_changes/28678.deprecation.rst

+  different than ``2`` to be compatible with the Array API standard. To achieve similar
+  behavior when ``arr.ndim != 2``, either ``arr.transpose()``, or ``arr.mT`` (swaps
+  the last two axes only), or ``np.permute_dims(arr, range(arr.ndim)[::-1])`` (compatible
+  with the Array API) or can be used.


minor: dangling "or" at the end here

mtsokol · 2025-05-10T09:21:10Z

@seberg Yesterday new matplotlib version got released. Docs build is passing so this PR can go in as well now.

mtsokol added 03 - Maintenance 40 - array API standard PRs and issues related to support for the array API standard labels Apr 10, 2025

mtsokol added this to the 2.2.5 release milestone Apr 10, 2025

mtsokol self-assigned this Apr 10, 2025

mtsokol force-pushed the T-non-2dim-depr branch from 7772cdc to 80bf35a Compare April 10, 2025 12:14

charris modified the milestones: 2.2.5 release, 2.3.0 release Apr 10, 2025

mtsokol force-pushed the T-non-2dim-depr branch 2 times, most recently from 621e40a to 0163784 Compare April 10, 2025 13:15

mtsokol force-pushed the T-non-2dim-depr branch from 0163784 to 76387e3 Compare April 10, 2025 13:56

mtsokol mentioned this pull request Apr 10, 2025

Change .T to .transpose() in _reshape_2D matplotlib/matplotlib#29896

Merged

ngoldbaum reviewed Apr 11, 2025

View reviewed changes

seberg reviewed Apr 14, 2025

View reviewed changes

tylerjereddy reviewed Apr 19, 2025

View reviewed changes

mtsokol added 3 commits May 10, 2025 08:58

MAINT: Deprecate .T property for non-2dim arrays and scalars

db2c7df

Provide fix guidance

ee99663

Apply review comments

4b970ff

mtsokol force-pushed the T-non-2dim-depr branch from 85cae50 to 4b970ff Compare May 10, 2025 09:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MAINT: Deprecate `.T` property for non-2dim arrays and scalars #28678

MAINT: Deprecate `.T` property for non-2dim arrays and scalars #28678

mtsokol commented Apr 10, 2025 •

edited

Loading

mattip commented Apr 10, 2025

mtsokol commented Apr 10, 2025

mtsokol commented Apr 10, 2025

ngoldbaum left a comment

ngoldbaum Apr 11, 2025

mtsokol Apr 12, 2025

ngoldbaum Apr 11, 2025

mtsokol Apr 12, 2025

seberg Apr 14, 2025

mtsokol Apr 14, 2025

ngoldbaum Apr 14, 2025

seberg Apr 14, 2025

mtsokol Apr 19, 2025

seberg Apr 14, 2025

mtsokol Apr 14, 2025

ngoldbaum Apr 14, 2025

seberg Apr 14, 2025

mtsokol Apr 19, 2025

seberg Apr 14, 2025

mtsokol Apr 19, 2025

seberg Apr 14, 2025

mtsokol Apr 19, 2025

seberg Apr 14, 2025

seberg Apr 14, 2025

mtsokol Apr 19, 2025

tylerjereddy Apr 19, 2025

mtsokol May 10, 2025

mtsokol commented May 10, 2025

	"2-dim arrays only. Here it is %d-dim array.",
	"2-dim arrays only. Received %d-dim array.",

		@@ -0,0 +1,2 @@
		* ``arr.T`` property has been deprecated for array scalars and arrays with
		dimensionality different than ``2``.

MAINT: Deprecate .T property for non-2dim arrays and scalars #28678

Are you sure you want to change the base?

MAINT: Deprecate .T property for non-2dim arrays and scalars #28678

Conversation

mtsokol commented Apr 10, 2025 • edited Loading

mattip commented Apr 10, 2025

mtsokol commented Apr 10, 2025

mtsokol commented Apr 10, 2025

ngoldbaum left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mtsokol commented May 10, 2025

MAINT: Deprecate `.T` property for non-2dim arrays and scalars #28678

MAINT: Deprecate `.T` property for non-2dim arrays and scalars #28678

mtsokol commented Apr 10, 2025 •

edited

Loading