DEP: Deprecate ndarray.tostring()

The corresponding `array.array.tostring()` in the standard library has been deprecated in favor of `tobytes` since Python 3.1 (python/cpython@1ce3eb5c5b4830e69b21865e2d723e22749544e0).

7 files changed, 71 insertions, 21 deletions

diff --git a/doc/release/upcoming_changes/15867.deprecation.rst b/doc/release/upcoming_changes/15867.deprecation.rst
new file mode 100644
index 000000000..96c0d90e8
--- /dev/null
+++ b/doc/release/upcoming_changes/15867.deprecation.rst
@@ -0,0 +1,4 @@
+``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
index ba5c0fa68..a54591ca3 100644
--- a/numpy/core/_add_newdocs.py
+++ b/numpy/core/_add_newdocs.py
@@ -3930,8 +3930,8 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('tolist',
     """))
 
 
-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.
 
@@ -3941,11 +3941,11 @@ tobytesdoc = """
     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.
 
@@ -3964,18 +3964,19 @@ tobytesdoc = """
     >>> 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
index ebdf8a4cd..7bfbeca15 100644
--- 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
index d2cf315a9..5d35bde6c 100644
--- a/numpy/core/tests/test_deprecations.py
+++ b/numpy/core/tests/test_deprecations.py
@@ -8,6 +8,7 @@ import operator
 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
index 9c266fd6b..a23ccc07e 100644
--- a/numpy/lib/user_array.py
+++ b/numpy/lib/user_array.py
@@ -231,6 +231,10 @@ class container:
         ""
         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
index e24cb956c..1ab24b228 100644
--- a/numpy/ma/core.py
+++ b/numpy/ma/core.py
@@ -5954,10 +5954,17 @@ class MaskedArray(ndarray):
         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
index 9f3368489..7e76eb054 100644
--- a/numpy/ma/tests/test_regression.py
+++ b/numpy/ma/tests/test_regression.py
@@ -86,6 +86,6 @@ class TestRegression:
         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())