8000 DEP: Deprecate `.T` property for non-2dim arrays and scalars by mtsokol · Pull Request #28678 · numpy/numpy · GitHub
[go: up one dir, main page]
Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
May 16, 2025
Merged

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bc88f60
MAINT: Deprecate `.T` property for non-2dim arrays and scalars
mtsokol Apr 10, 2025
d2e4034
Provide fix guidance
mtsokol Apr 12, 2025
0892ed3
Apply review comments
mtsokol Apr 19, 2025
13b5692
Apply review comments
mtsokol May 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Provide fix guidance
  • Loading branch information
@mtsokol
mtsokol committed May 16, 2025
commit d2e40341c7f09364126289b7984b403ff17d7e27
6 changes: 4 additions & 2 deletions doc/release/upcoming_changes/28678.deprecation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
5 changes: 4 additions & 1 deletion numpy/_core/src/multiarray/getset.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -852,7 +852,10 @@ array_transpose_get(PyArrayObject *self, void *NPY_UNUSED(ignored))
if (ndim != 2) {
if (PyErr_WarnFormat(PyExc_UserWarning, 1,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

"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()` "
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

"should be used instead.",
ndim) < 0) {
return NULL;
}
Expand Down
6 changes: 5 additions & 1 deletion numpy/_core/src/multiarray/scalartypes.c.src
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
2 changes: 1 addition & 1 deletion numpy/_core/tests/test_deprecations.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
0