Merge pull request #15867 from eric-wieser/deprecate-tostring

mattip · web-flow · commit ad5d58c29ab4 · 2020-04-01T12:23:05.000+03:00
DEP: Deprecate ndarray.tostring()
diff --git a/doc/release/upcoming_changes/15867.deprecation.rst b/doc/release/upcoming_changes/15867.deprecation.rst
@@ -0,0 +1,6 @@
+``numpy.ndarray.tostring()`` is deprecated in favor of ``tobytes()``
+--------------------------------------------------------------------
+`~numpy.ndarray.tobytes` has existed since the 1.9 release, but until this
+release `~numpy.ndarray.tostring` emitted no warning. The change to emit a
+warning brings NumPy in line with the builtin `array.array` methods of the
+same name.
diff --git a/numpy/core/_add_newdocs.py b/numpy/core/_add_newdocs.py
@@ -3932,8 +3932,8 @@
     """))
 
 
-tobytesdoc = """
-    a.{name}(order='C')
+add_newdoc('numpy.core.multiarray', 'ndarray', ('tobytes', """
+    a.tobytes(order='C')
 
     Construct Python bytes containing the raw data bytes in the array.
 
@@ -3943,11 +3943,11 @@
     unless the F_CONTIGUOUS flag in the array is set, in which case it
     means 'Fortran' order.
 
-    {deprecated}
+    .. versionadded:: 1.9.0
 
     Parameters
     ----------
-    order : {{'C', 'F', None}}, optional
+    order : {'C', 'F', None}, optional
         Order of the data for multidimensional arrays:
         C, Fortran, or the same as for the original array.
 
@@ -3966,18 +3966,19 @@
     >>> x.tobytes('F')
     b'\\x00\\x00\\x02\\x00\\x01\\x00\\x03\\x00'
 
-    """
+    """))
+
+
+add_newdoc('numpy.core.multiarray', 'ndarray', ('tostring', r"""
+    a.tostring(order='C')
+
+    A compatibility alias for `tobytes`, with exactly the same behavior.
+
+    Despite its name, it returns `bytes` not `str`\ s.
+
+    .. deprecated:: 1.19.0
+    """))
 
-add_newdoc('numpy.core.multiarray', 'ndarray',
-           ('tostring', tobytesdoc.format(name='tostring',
-                                          deprecated=
-                                          'This function is a compatibility '
-                                          'alias for tobytes. Despite its '
-                                          'name it returns bytes not '
-                                          'strings.')))
-add_newdoc('numpy.core.multiarray', 'ndarray',
-           ('tobytes', tobytesdoc.format(name='tobytes',
-                                         deprecated='.. versionadded:: 1.9.0')))
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('trace',
     """
diff --git a/numpy/core/src/multiarray/methods.c b/numpy/core/src/multiarray/methods.c
@@ -566,6 +566,23 @@ array_tobytes(PyArrayObject *self, PyObject *args, PyObject *kwds)
     return PyArray_ToString(self, order);
 }
 
+static PyObject *
+array_tostring(PyArrayObject *self, PyObject *args, PyObject *kwds)
+{
+    NPY_ORDER order = NPY_CORDER;
+    static char *kwlist[] = {"order", NULL};
+
+    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|O&:tostring", kwlist,
+                                     PyArray_OrderConverter, &order)) {
+        return NULL;
+    }
+    /* 2020-03-30, NumPy 1.19 */
+    if (DEPRECATE("tostring() is deprecated. Use tobytes() instead.") < 0) {
+        return NULL;
+    }
+    return PyArray_ToString(self, order);
+}
+
 
 /* This should grow an order= keyword to be consistent
  */
@@ -2844,7 +2861,7 @@ NPY_NO_EXPORT PyMethodDef array_methods[] = {
         (PyCFunction)array_tolist,
         METH_VARARGS, NULL},
     {"tostring",
-        (PyCFunction)array_tobytes,
+        (PyCFunction)array_tostring,
         METH_VARARGS | METH_KEYWORDS, NULL},
     {"trace",
         (PyCFunction)array_trace,
diff --git a/numpy/core/tests/test_deprecations.py b/numpy/core/tests/test_deprecations.py
@@ -8,6 +8,7 @@
 import warnings
 import pytest
 import tempfile
+import re
 
 import numpy as np
 from numpy.testing import (
@@ -548,6 +549,22 @@ def test_deprecate_ragged_arrays():
         np.array(arg)
 
 
+class TestToString(_DeprecationTestCase):
+    # 2020-03-06 1.19.0
+    message = re.escape("tostring() is deprecated. Use tobytes() instead.")
+
+    def test_tostring(self):
+        arr = np.array(list(b"test\xFF"), dtype=np.uint8)
+        self.assert_deprecated(arr.tostring)
+
+    def test_tostring_matches_tobytes(self):
+        arr = np.array(list(b"test\xFF"), dtype=np.uint8)
+        b = arr.tobytes()
+        with assert_warns(DeprecationWarning):
+            s = arr.tostring()
+        assert s == b
+
+
 class TestDTypeCoercion(_DeprecationTestCase):
     # 2020-02-06 1.19.0
     message = "Converting .* to a dtype .*is deprecated"
diff --git a/numpy/lib/user_array.py b/numpy/lib/user_array.py
@@ -227,6 +227,10 @@ def tostring(self):
         ""
         return self.array.tostring()
 
+    def tobytes(self):
+        ""
+        return self.array.tobytes()
+
     def byteswap(self):
         ""
         return self._rc(self.array.byteswap())
diff --git a/numpy/ma/core.py b/numpy/ma/core.py
@@ -5941,10 +5941,17 @@ def tolist(self, fill_value=None):
         return result.tolist()
 
     def tostring(self, fill_value=None, order='C'):
+        r"""
+        A compatibility alias for `tobytes`, with exactly the same behavior.
+
+        Despite its name, it returns `bytes` not `str`\ s.
+
+        .. deprecated:: 1.19.0
         """
-        This function is a compatibility alias for tobytes. Despite its name it
-        returns bytes not strings.
-        """
+        # 2020-03-30, Numpy 1.19.0
+        warnings.warn(
+            "tostring() is deprecated. Use tobytes() instead.",
+            DeprecationWarning, stacklevel=2)
 
         return self.tobytes(fill_value, order=order)
 
diff --git a/numpy/ma/tests/test_regression.py b/numpy/ma/tests/test_regression.py
@@ -86,6 +86,6 @@ def test_empty_list_on_structured(self):
         ma = np.ma.MaskedArray([(1, 1.), (2, 2.), (3, 3.)], dtype='i4,f4')
         assert_array_equal(ma[[]], ma[:0])
 
-    def test_masked_array_tostring_fortran(self):
+    def test_masked_array_tobytes_fortran(self):
         ma = np.ma.arange(4).reshape((2,2))
-        assert_array_equal(ma.tostring(order='F'), ma.T.tostring())
+        assert_array_equal(ma.tobytes(order='F'), ma.T.tobytes())
