ENH: add tobytes and stop using tostring in documentation

tostring returns bytes which are not equal to string, so provide a
tobytes function alias.
tostring does not emit a deprecation warning yet so rdepends do not need
to check two names to support older versions of numpy without warnings.

12 files changed, 69 insertions, 43 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 3e115c845..be343f79d 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -4386,7 +4386,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('tofile',
     sep : str
         Separator between array items for text output.
         If "" (empty), a binary file is written, equivalent to
-        ``file.write(a.tostring())``.
+        ``file.write(a.tobytes())``.
     format : str
         Format string for text file output.
         Each entry in the array is formatted to text by first converting
@@ -4440,8 +4440,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('tolist',
     """))
 
 
-add_newdoc('numpy.core.multiarray', 'ndarray', ('tostring',
-    """
+tobytesdoc = """
     a.tostring(order='C')
 
     Construct a Python string containing the raw data bytes in the array.
@@ -4452,9 +4451,11 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('tostring',
     unless the F_CONTIGUOUS flag in the array is set, in which case it
     means 'Fortran' order.
 
+    {deprecated}
+
     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.
 
@@ -4466,15 +4467,23 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('tostring',
     Examples
     --------
     >>> x = np.array([[0, 1], [2, 3]])
-    >>> x.tostring()
+    >>> x.tobytes()
     '\\x00\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x02\\x00\\x00\\x00\\x03\\x00\\x00\\x00'
-    >>> x.tostring('C') == x.tostring()
+    >>> x.tobytes('C') == x.tobytes()
     True
-    >>> x.tostring('F')
+    >>> x.tobytes('F')
     '\\x00\\x00\\x00\\x00\\x02\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x03\\x00\\x00\\x00'
 
-    """))
+    """
 
+add_newdoc('numpy.core.multiarray', 'ndarray',
+           ('tostring', tobytesdoc.format(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(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 37b7d3c18..bf717c1f5 100644
--- a/numpy/core/src/multiarray/methods.c
+++ b/numpy/core/src/multiarray/methods.c
@@ -542,7 +542,7 @@ array_tolist(PyArrayObject *self, PyObject *args)
 
 
 static PyObject *
-array_tostring(PyArrayObject *self, PyObject *args, PyObject *kwds)
+array_tobytes(PyArrayObject *self, PyObject *args, PyObject *kwds)
 {
     NPY_ORDER order = NPY_CORDER;
     static char *kwlist[] = {"order", NULL};
@@ -2456,6 +2456,9 @@ NPY_NO_EXPORT PyMethodDef array_methods[] = {
     {"take",
         (PyCFunction)array_take,
         METH_VARARGS | METH_KEYWORDS, NULL},
+    {"tobytes",
+        (PyCFunction)array_tobytes,
+        METH_VARARGS | METH_KEYWORDS, NULL},
     {"tofile",
         (PyCFunction)array_tofile,
         METH_VARARGS | METH_KEYWORDS, NULL},
@@ -2463,7 +2466,7 @@ NPY_NO_EXPORT PyMethodDef array_methods[] = {
         (PyCFunction)array_tolist,
         METH_VARARGS, NULL},
     {"tostring",
-        (PyCFunction)array_tostring,
+        (PyCFunction)array_tobytes,
         METH_VARARGS | METH_KEYWORDS, NULL},
     {"trace",
         (PyCFunction)array_trace,
diff --git a/numpy/core/src/multiarray/scalartypes.c.src b/numpy/core/src/multiarray/scalartypes.c.src
index 9c081f150..c8e66ac42 100644
--- a/numpy/core/src/multiarray/scalartypes.c.src
+++ b/numpy/core/src/multiarray/scalartypes.c.src
@@ -1499,9 +1499,9 @@ gentype_wraparray(PyObject *NPY_UNUSED(scalar), PyObject *args)
  */
 /**begin repeat
  *
- * #name = tolist, item, tostring, astype, copy, __deepcopy__, searchsorted,
- *         view, swapaxes, conj, conjugate, nonzero, flatten, ravel, fill,
- *         transpose, newbyteorder#
+ * #name = tolist, item, tostring, tobytes, astype, copy, __deepcopy__,
+ *         searchsorted, view, swapaxes, conj, conjugate, nonzero, flatten,
+ *         ravel, fill, transpose, newbyteorder#
  */
 static PyObject *
 gentype_@name@(PyObject *self, PyObject *args)
@@ -1845,6 +1845,9 @@ static PyMethodDef gentype_methods[] = {
     {"itemset",
         (PyCFunction)gentype_itemset,
         METH_VARARGS, NULL},
+    {"tobytes",
+        (PyCFunction)gentype_tobytes,
+        METH_VARARGS, NULL},
     {"tofile",
         (PyCFunction)gentype_tofile,
         METH_VARARGS | METH_KEYWORDS, NULL},
diff --git a/numpy/core/tests/test_defchararray.py b/numpy/core/tests/test_defchararray.py
index 09fcff0d0..fe0e02a6d 100644
--- a/numpy/core/tests/test_defchararray.py
+++ b/numpy/core/tests/test_defchararray.py
@@ -138,7 +138,7 @@ class TestChar(TestCase):
 
     def test_it(self):
         assert_equal(self.A.shape, (4,))
-        assert_equal(self.A.upper()[:2].tostring(), asbytes('AB'))
+        assert_equal(self.A.upper()[:2].tobytes(), asbytes('AB'))
 
 class TestComparisons(TestCase):
     def setUp(self):
diff --git a/numpy/core/tests/test_multiarray.py b/numpy/core/tests/test_multiarray.py
index c2ac00923..b5e6fdf57 100644
--- a/numpy/core/tests/test_multiarray.py
+++ b/numpy/core/tests/test_multiarray.py
@@ -2308,7 +2308,7 @@ class TestLexsort(TestCase):
 
 
 class TestIO(object):
-    """Test tofile, fromfile, tostring, and fromstring"""
+    """Test tofile, fromfile, tobytes, and fromstring"""
 
     def setUp(self):
         shape = (2, 4, 3)
@@ -2357,11 +2357,11 @@ class TestIO(object):
         assert_array_equal(y, self.x.flat)
 
     def test_roundtrip_binary_str(self):
-        s = self.x.tostring()
+        s = self.x.tobytes()
         y = np.fromstring(s, dtype=self.dtype)
         assert_array_equal(y, self.x.flat)
 
-        s = self.x.tostring('F')
+        s = self.x.tobytes('F')
         y = np.fromstring(s, dtype=self.dtype)
         assert_array_equal(y, self.x.flatten('F'))
 
@@ -2567,7 +2567,7 @@ class TestFromBuffer(object):
             for dtype in [float, int, np.complex]:
                 dt = np.dtype(dtype).newbyteorder(byteorder)
                 x = (np.random.random((4, 7))*5).astype(dt)
-                buf = x.tostring()
+                buf = x.tobytes()
                 yield self.tst_basic, buf, x.flat, {'dtype':dt}
 
     def test_empty(self):
diff --git a/numpy/core/tests/test_regression.py b/numpy/core/tests/test_regression.py
index e35bbb320..6b0d58e22 100644
--- a/numpy/core/tests/test_regression.py
+++ b/numpy/core/tests/test_regression.py
@@ -286,11 +286,11 @@ class TestRegression(TestCase):
         b = np.array('world')
         a == b
 
-    def test_tostring_FORTRANORDER_discontiguous(self,level=rlevel):
+    def test_tobytes_FORTRANORDER_discontiguous(self,level=rlevel):
         """Fix in r2836"""
         # Create discontiguous Fortran-ordered array
         x = np.array(np.random.rand(3, 3), order='F')[:, :2]
-        assert_array_almost_equal(x.ravel(), np.fromstring(x.tostring()))
+        assert_array_almost_equal(x.ravel(), np.fromstring(x.tobytes()))
 
     def test_flat_assignment(self,level=rlevel):
         """Correct behaviour of ticket #194"""
@@ -1200,7 +1200,7 @@ class TestRegression(TestCase):
         #that void scalar contains original data.
         test_string = np.array("test")
         test_string_void_scalar = np.core.multiarray.scalar(
-            np.dtype(("V", test_string.dtype.itemsize)), test_string.tostring())
+            np.dtype(("V", test_string.dtype.itemsize)), test_string.tobytes())
 
         assert_(test_string_void_scalar.view(test_string.dtype) == test_string)
 
@@ -1208,7 +1208,7 @@ class TestRegression(TestCase):
         #reconstructed scalar is correct.
         test_record = np.ones((), "i,i")
         test_record_void_scalar = np.core.multiarray.scalar(
-            test_record.dtype, test_record.tostring())
+            test_record.dtype, test_record.tobytes())
 
         assert_(test_record_void_scalar == test_record)
 
@@ -1378,10 +1378,10 @@ class TestRegression(TestCase):
             y = x.byteswap()
             if x.dtype.byteorder == z.dtype.byteorder:
                 # little-endian machine
-                assert_equal(x, np.fromstring(y.tostring(), dtype=dtype.newbyteorder()))
+                assert_equal(x, np.fromstring(y.tobytes(), dtype=dtype.newbyteorder()))
             else:
                 # big-endian machine
-                assert_equal(x, np.fromstring(y.tostring(), dtype=dtype))
+                assert_equal(x, np.fromstring(y.tobytes(), dtype=dtype))
             # double check real and imaginary parts:
             assert_equal(x.real, y.real.byteswap())
             assert_equal(x.imag, y.imag.byteswap())
@@ -1527,7 +1527,7 @@ class TestRegression(TestCase):
         # file handle out of sync
         f0 = tempfile.NamedTemporaryFile()
         f = f0.file
-        f.write(np.arange(255, dtype='u1').tostring())
+        f.write(np.arange(255, dtype='u1').tobytes())
 
         f.seek(20)
         ret = np.fromfile(f, count=4, dtype='u1')
@@ -1904,7 +1904,7 @@ class TestRegression(TestCase):
         # 2D array
         arr2 = np.reshape(arr, (2, 5))
         # Fortran write followed by (C or F) read caused bus error
-        data_str = arr2.tostring('F')
+        data_str = arr2.tobytes('F')
         data_back = np.ndarray(arr2.shape,
                               arr2.dtype,
                               buffer=data_str,
diff --git a/numpy/doc/byteswapping.py b/numpy/doc/byteswapping.py
index ffefe3168..430683d30 100644
--- a/numpy/doc/byteswapping.py
+++ b/numpy/doc/byteswapping.py
@@ -101,7 +101,7 @@ the correct endianness:
 
 Note the the array has not changed in memory:
 
->>> fixed_end_dtype_arr.tostring() == big_end_str
+>>> fixed_end_dtype_arr.tobytes() == big_end_str
 True
 
 Data and type endianness don't match, change data to match dtype
@@ -117,7 +117,7 @@ that needs a certain byte ordering.
 
 Now the array *has* changed in memory:
 
->>> fixed_end_mem_arr.tostring() == big_end_str
+>>> fixed_end_mem_arr.tobytes() == big_end_str
 False
 
 Data and dtype endianness match, swap data and dtype
@@ -131,7 +131,7 @@ the previous operations:
 >>> swapped_end_arr = big_end_arr.byteswap().newbyteorder()
 >>> swapped_end_arr[0]
 1
->>> swapped_end_arr.tostring() == big_end_str
+>>> swapped_end_arr.tobytes() == big_end_str
 False
 
 An easier way of casting the data to a specific dtype and byte ordering
@@ -140,7 +140,7 @@ can be achieved with the ndarray astype method:
 >>> swapped_end_arr = big_end_arr.astype('<i2')
 >>> swapped_end_arr[0]
 1
->>> swapped_end_arr.tostring() == big_end_str
+>>> swapped_end_arr.tobytes() == big_end_str
 False
 
 """
diff --git a/numpy/f2py/tests/test_array_from_pyobj.py b/numpy/f2py/tests/test_array_from_pyobj.py
index 09d613293..3a148e72c 100644
--- a/numpy/f2py/tests/test_array_from_pyobj.py
+++ b/numpy/f2py/tests/test_array_from_pyobj.py
@@ -227,7 +227,8 @@ class Array(object):
         assert_(self.arr_attr[2]==self.pyarr_attr[2]) # dimensions
         if self.arr_attr[1]<=1:
             assert_(self.arr_attr[3]==self.pyarr_attr[3],\
-                   repr((self.arr_attr[3], self.pyarr_attr[3], self.arr.tostring(), self.pyarr.tostring()))) # strides
+                   repr((self.arr_attr[3], self.pyarr_attr[3],
+                         self.arr.tobytes(), self.pyarr.tobytes()))) # strides
         assert_(self.arr_attr[5][-2:]==self.pyarr_attr[5][-2:],\
                repr((self.arr_attr[5], self.pyarr_attr[5]))) # descr
         assert_(self.arr_attr[6]==self.pyarr_attr[6],\
diff --git a/numpy/lib/format.py b/numpy/lib/format.py
index 4cfbbe05d..631e92959 100644
--- a/numpy/lib/format.py
+++ b/numpy/lib/format.py
@@ -407,7 +407,7 @@ def write_array(fp, array, version=(1, 0)):
             for chunk in numpy.nditer(
                     array, flags=['external_loop', 'buffered', 'zerosize_ok'],
                     buffersize=buffersize, order='F'):
-                fp.write(chunk.tostring('C'))
+                fp.write(chunk.tobytes('C'))
     else:
         if isfileobj(fp):
             array.tofile(fp)
@@ -415,7 +415,7 @@ def write_array(fp, array, version=(1, 0)):
             for chunk in numpy.nditer(
                     array, flags=['external_loop', 'buffered', 'zerosize_ok'],
                     buffersize=buffersize, order='C'):
-                fp.write(chunk.tostring('C'))
+                fp.write(chunk.tobytes('C'))
 
 
 def read_array(fp):
diff --git a/numpy/ma/core.py b/numpy/ma/core.py
index 42787e3c7..e4116fbd8 100644
--- a/numpy/ma/core.py
+++ b/numpy/ma/core.py
@@ -5382,10 +5382,20 @@ class MaskedArray(ndarray):
     #........................
     def tostring(self, fill_value=None, order='C'):
         """
+        This function is a compatibility alias for tobytes. Despite its name it
+        returns bytes not strings.
+        """
+
+        return self.tobytes(fill_value, order='C')
+    #........................
+    def tobytes(self, fill_value=None, order='C'):
+        """
         Return the array data as a string containing the raw bytes in the array.
 
         The array is filled with a fill value before the string conversion.
 
+        .. versionadded:: 1.9.0
+
         Parameters
         ----------
         fill_value : scalar, optional
@@ -5401,22 +5411,22 @@ class MaskedArray(ndarray):
 
         See Also
         --------
-        ndarray.tostring
+        ndarray.tobytes
         tolist, tofile
 
         Notes
         -----
-        As for `ndarray.tostring`, information about the shape, dtype, etc.,
+        As for `ndarray.tobytes`, information about the shape, dtype, etc.,
         but also about `fill_value`, will be lost.
 
         Examples
         --------
         >>> x = np.ma.array(np.array([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
-        >>> x.tostring()
+        >>> x.tobytes()
         '\\x01\\x00\\x00\\x00?B\\x0f\\x00?B\\x0f\\x00\\x04\\x00\\x00\\x00'
 
         """
-        return self.filled(fill_value).tostring(order=order)
+        return self.filled(fill_value).tobytes(order=order)
     #........................
     def tofile(self, fid, sep="", format="%s"):
         """
@@ -5498,9 +5508,9 @@ class MaskedArray(ndarray):
                  self.shape,
                  self.dtype,
                  self.flags.fnc,
-                 self._data.tostring(cf),
+                 self._data.tobytes(cf),
                  #self._data.tolist(),
-                 getmaskarray(self).tostring(cf),
+                 getmaskarray(self).tobytes(cf),
                  #getmaskarray(self).tolist(),
                  self._fill_value,
                  )
diff --git a/numpy/ma/mrecords.py b/numpy/ma/mrecords.py
index a2380d813..e66596509 100644
--- a/numpy/ma/mrecords.py
+++ b/numpy/ma/mrecords.py
@@ -426,8 +426,8 @@ The fieldname base is either `_data` or `_mask`."""
                  self.shape,
                  self.dtype,
                  self.flags.fnc,
-                 self._data.tostring(),
-                 self._mask.tostring(),
+                 self._data.tobytes(),
+                 self._mask.tobytes(),
                  self._fill_value,
                  )
         return state
diff --git a/numpy/matrixlib/tests/test_defmatrix.py b/numpy/matrixlib/tests/test_defmatrix.py
index d1a4e4ab5..a06a564aa 100644
--- a/numpy/matrixlib/tests/test_defmatrix.py
+++ b/numpy/matrixlib/tests/test_defmatrix.py
@@ -285,8 +285,8 @@ class TestMatrixReturn(TestCase):
             'getA', 'getA1', 'item', 'nonzero', 'put', 'putmask', 'resize',
             'searchsorted', 'setflags', 'setfield', 'sort',
             'partition', 'argpartition',
-            'take', 'tofile', 'tolist', 'tostring', 'all', 'any', 'sum',
-            'argmax', 'argmin', 'min', 'max', 'mean', 'var', 'ptp',
+            'take', 'tofile', 'tolist', 'tostring', 'tobytes', 'all', 'any',
+            'sum', 'argmax', 'argmin', 'min', 'max', 'mean', 'var', 'ptp',
             'prod', 'std', 'ctypes', 'itemset', 'setasflat'
             ]
         for attrib in dir(a):