DEP: fastCopyAndTranspose and PyArray_CopyAndTranspose

Deprecate the fastCopyAndTranspose function from the Python API, and the
underlying PyArray_CopyAndTranspose function from the C-API.

Also removes an internal, private function _fastCopyAndTranspose which
was the original Python wrapper around the C-function.

8 files changed, 51 insertions, 32 deletions

diff --git a/doc/release/upcoming_changes/22313.deprecation.rst b/doc/release/upcoming_changes/22313.deprecation.rst
new file mode 100644
index 000000000..c4a0a4a9a
--- /dev/null
+++ b/doc/release/upcoming_changes/22313.deprecation.rst
@@ -0,0 +1,10 @@
+Deprecate fastCopyAndTranspose and PyArray_CopyAndTranspose
+-----------------------------------------------------------
+
+The ``numpy.fastCopyAndTranspose`` function has been deprecated. Use the
+corresponding copy and transpose methods directly::
+
+    arr.T.copy()
+
+The underlying C function ``PyArray_CopyAndTranspose`` has also been
+deprecated from the NumPy C-API.
diff --git a/numpy/core/_add_newdocs.py b/numpy/core/_add_newdocs.py
index 251dc305b..0405bfbe0 100644
--- a/numpy/core/_add_newdocs.py
+++ b/numpy/core/_add_newdocs.py
@@ -1674,7 +1674,14 @@ add_newdoc('numpy.core.multiarray', 'from_dlpack',
     """)
 
 add_newdoc('numpy.core', 'fastCopyAndTranspose',
-    """_fastCopyAndTranspose(a)""")
+    """
+    fastCopyAndTranspose(a)
+
+    .. deprecated:: 1.24
+
+       fastCopyAndTranspose is deprecated and will be removed. Use the copy and
+       transpose methods instead, e.g. ``arr.T.copy()``
+    """)
 
 add_newdoc('numpy.core.multiarray', 'correlate',
     """cross_correlate(a,v, mode=0)""")
diff --git a/numpy/core/multiarray.py b/numpy/core/multiarray.py
index 2d0725e2f..cfb7639a7 100644
--- a/numpy/core/multiarray.py
+++ b/numpy/core/multiarray.py
@@ -14,7 +14,7 @@ from ._multiarray_umath import *  # noqa: F403
 # do not change them. issue gh-15518
 # _get_ndarray_c_version is semi-public, on purpose not added to __all__
 from ._multiarray_umath import (
-    _fastCopyAndTranspose, _flagdict, from_dlpack, _insert, _reconstruct,
+    fastCopyAndTranspose, _flagdict, from_dlpack, _insert, _reconstruct,
     _vec_string, _ARRAY_API, _monotonicity, _get_ndarray_c_version,
     _get_madvise_hugepage, _set_madvise_hugepage,
     _get_promotion_state, _set_promotion_state,
@@ -24,7 +24,7 @@ __all__ = [
     '_ARRAY_API', 'ALLOW_THREADS', 'BUFSIZE', 'CLIP', 'DATETIMEUNITS',
     'ITEM_HASOBJECT', 'ITEM_IS_POINTER', 'LIST_PICKLE', 'MAXDIMS',
     'MAY_SHARE_BOUNDS', 'MAY_SHARE_EXACT', 'NEEDS_INIT', 'NEEDS_PYAPI',
-    'RAISE', 'USE_GETITEM', 'USE_SETITEM', 'WRAP', '_fastCopyAndTranspose',
+    'RAISE', 'USE_GETITEM', 'USE_SETITEM', 'WRAP',
     '_flagdict', 'from_dlpack', '_insert', '_reconstruct', '_vec_string',
     '_monotonicity', 'add_docstring', 'arange', 'array', 'asarray',
     'asanyarray', 'ascontiguousarray', 'asfortranarray', 'bincount',
diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
index 092e42470..5b92972d1 100644
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -8,7 +8,7 @@ import numbers
 import numpy as np
 from . import multiarray
 from .multiarray import (
-    _fastCopyAndTranspose as fastCopyAndTranspose, ALLOW_THREADS,
+    fastCopyAndTranspose, ALLOW_THREADS,
     BUFSIZE, CLIP, MAXDIMS, MAY_SHARE_BOUNDS, MAY_SHARE_EXACT, RAISE,
     WRAP, arange, array, asarray, asanyarray, ascontiguousarray,
     asfortranarray, broadcast, can_cast, compare_chararrays,
diff --git a/numpy/core/src/multiarray/multiarraymodule.c b/numpy/core/src/multiarray/multiarraymodule.c
index 618119443..a5b66f5a8 100644
--- a/numpy/core/src/multiarray/multiarraymodule.c
+++ b/numpy/core/src/multiarray/multiarraymodule.c
@@ -1139,6 +1139,15 @@ fail:
 NPY_NO_EXPORT PyObject *
 PyArray_CopyAndTranspose(PyObject *op)
 {
+    /* DEPRECATED 2022-09-30, NumPy 1.24 - see gh-22313 */
+    if (DEPRECATE(
+            "fastCopyAndTranspose and the underlying C function "
+            "PyArray_CopyAndTranspose have been deprecated.\n\n"
+            "Use the transpose method followed by a C-order copy instead, "
+            "e.g. ``arr.T.copy()``") < 0) {
+        return NULL;
+    }
+
     PyArrayObject *arr, *tmp, *ret;
     int i;
     npy_intp new_axes_values[NPY_MAXDIMS];
@@ -2986,7 +2995,7 @@ array_fastCopyAndTranspose(PyObject *NPY_UNUSED(dummy), PyObject *args)
 {
     PyObject *a0;
 
-    if (!PyArg_ParseTuple(args, "O:_fastCopyAndTranspose", &a0)) {
+    if (!PyArg_ParseTuple(args, "O:fastCopyAndTranspose", &a0)) {
         return NULL;
     }
     return PyArray_Return((PyArrayObject *)PyArray_CopyAndTranspose(a0));
@@ -4396,7 +4405,7 @@ static struct PyMethodDef array_module_methods[] = {
     {"c_einsum",
         (PyCFunction)array_einsum,
         METH_VARARGS|METH_KEYWORDS, NULL},
-    {"_fastCopyAndTranspose",
+    {"fastCopyAndTranspose",
         (PyCFunction)array_fastCopyAndTranspose,
         METH_VARARGS, NULL},
     {"correlate",
diff --git a/numpy/core/tests/test_api.py b/numpy/core/tests/test_api.py
index b3f3e947d..29e4a511d 100644
--- a/numpy/core/tests/test_api.py
+++ b/numpy/core/tests/test_api.py
@@ -150,24 +150,20 @@ def test_array_impossible_casts(array):
         np.array(rt, dtype="M8")
 
 
-def test_fastCopyAndTranspose():
-    # 0D array
-    a = np.array(2)
-    b = np.fastCopyAndTranspose(a)
-    assert_equal(b, a.T)
-    assert_(b.flags.owndata)
-
-    # 1D array
-    a = np.array([3, 2, 7, 0])
-    b = np.fastCopyAndTranspose(a)
-    assert_equal(b, a.T)
-    assert_(b.flags.owndata)
-
-    # 2D array
-    a = np.arange(6).reshape(2, 3)
-    b = np.fastCopyAndTranspose(a)
-    assert_equal(b, a.T)
-    assert_(b.flags.owndata)
+# TODO: remove when fastCopyAndTranspose deprecation expires
+@pytest.mark.parametrize("a",
+    (
+        np.array(2),  # 0D array
+        np.array([3, 2, 7, 0]),  # 1D array
+        np.arange(6).reshape(2, 3)  # 2D array
+    ),
+)
+def test_fastCopyAndTranspose(a):
+    with pytest.deprecated_call():
+        b = np.fastCopyAndTranspose(a)
+        assert_equal(b, a.T)
+        assert b.flags.owndata
+
 
 def test_array_astype():
     a = np.arange(6, dtype='f4').reshape(2, 3)
diff --git a/numpy/linalg/linalg.py b/numpy/linalg/linalg.py
index 6d7dda2b6..6f3400450 100644
--- a/numpy/linalg/linalg.py
+++ b/numpy/linalg/linalg.py
@@ -21,7 +21,7 @@ import warnings
 from numpy.core import (
     array, asarray, zeros, empty, empty_like, intc, single, double,
     csingle, cdouble, inexact, complexfloating, newaxis, all, Inf, dot,
-    add, multiply, sqrt, fastCopyAndTranspose, sum, isfinite,
+    add, multiply, sqrt, sum, isfinite,
     finfo, errstate, geterrobj, moveaxis, amin, amax, product, abs,
     atleast_2d, intp, asanyarray, object_, matmul,
     swapaxes, divide, count_nonzero, isnan, sign, argsort, sort,
@@ -158,10 +158,6 @@ def _commonType(*arrays):
     return t, result_type
 
 
-# _fastCopyAndTranpose assumes the input is 2D (as all the calls in here are).
-
-_fastCT = fastCopyAndTranspose
-
 def _to_native_byte_order(*arrays):
     ret = []
     for arr in arrays:
@@ -174,12 +170,13 @@ def _to_native_byte_order(*arrays):
     else:
         return ret
 
+
 def _fastCopyAndTranspose(type, *arrays):
     cast_arrays = ()
     for a in arrays:
         if a.dtype.type is not type:
             a = a.astype(type)
-        cast_arrays = cast_arrays + (_fastCT(a),)
+        cast_arrays = cast_arrays + (a.T.copy(),)
     if len(cast_arrays) == 1:
         return cast_arrays[0]
     else:
@@ -1172,7 +1169,7 @@ def eigvalsh(a, UPLO='L'):
 
 def _convertarray(a):
     t, result_t = _commonType(a)
-    a = _fastCT(a.astype(t))
+    a = a.astype(t).T.copy()
     return a, t, result_t
 
 
diff --git a/numpy/tests/test_public_api.py b/numpy/tests/test_public_api.py
index 882a48d2f..92a34bf91 100644
--- a/numpy/tests/test_public_api.py
+++ b/numpy/tests/test_public_api.py
@@ -43,7 +43,7 @@ def test_numpy_namespace():
         'deprecate': 'numpy.lib.utils.deprecate',
         'deprecate_with_doc': 'numpy.lib.utils.deprecate_with_doc',
         'disp': 'numpy.lib.function_base.disp',
-        'fastCopyAndTranspose': 'numpy.core._multiarray_umath._fastCopyAndTranspose',
+        'fastCopyAndTranspose': 'numpy.core._multiarray_umath.fastCopyAndTranspose',
         'get_array_wrap': 'numpy.lib.shape_base.get_array_wrap',
         'get_include': 'numpy.lib.utils.get_include',
         'recfromcsv': 'numpy.lib.npyio.recfromcsv',