ENH: add tobytes and stop using tostring in documentation

doc/numpybook/capi.lyx

@@ -9384,7 +9384,7 @@ self
 \emph default
 .
 \series bold
-tostring
+tobytes
 \series default
 (
 \emph on

doc/numpybook/numpybook.lyx

@@ -6062,9 +6062,9 @@ name "ndarray!methods!itemset"
 \end_layout
 
 \begin_layout Description
-tostring
+tobytes
 \begin_inset LatexCommand index
-name "ndarray!methods!tostring"
+name "ndarray!methods!tobytes"
 
 \end_inset
 
@@ -6134,7 +6134,7 @@ format
  the shape, type, or endianness of an array.
  When written in binary mode, tofile is functionally equivalent to 
 \family typewriter
-fid.write(self.tostring())
+fid.write(self.tobytes())
 \family default
 .
 \end_layout
@@ -6836,7 +6836,7 @@ Insert scalar (last argument) into array
 \begin_layout Standard
 
 \series bold
-tostring
+tobytes
 \end_layout
 
 \end_inset
@@ -9450,7 +9450,7 @@ name "ndarray!special methods!setstate"
 ).
  In this tuple, isfortran is a Bool stating whether the following flattened
  data is in Fortran order or not, and string_or_list is a string formed
- by self.tostring() if the data type is not object.
+ by self.tobytes() if the data type is not object.
  If the data type of self is an object array, then string_or_list is a flat
  list equivalent to self.ravel().tolist().
 
@@ -17719,7 +17719,7 @@ __reduce__ ()
 \InsetSpace ~
  This is called to pickle an array scalar.
  It returns a tuple of (numpy.core.multiarray.scalar, self.dtypestr, obj or
- self.tostring()) which can be used to reconstruct the scalar on unpickling.
+ self.tobytes()) which can be used to reconstruct the scalar on unpickling.
  Notice that no state is written, because the entire scalar can be constructed
  from just the string.
  Also, if this is an object array scalar, then the Python object being reference

doc/release/1.9.0-notes.rst

@@ -74,6 +74,14 @@ Dtype parameter added to `np.linspace` and `np.logspace`
 The returned data type from the `linspace` and `logspace` functions
 can now be specificed using the dtype parameter.
 
+
+`tobytes` alias for `tostring` method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`ndarray.tobytes` and `MaskedArray.tobytes` have been added as aliases for
+`tostring` which exports arrays as `bytes`. This is more consistent in Python 3
+where `str` and `bytes` are not the same.
+
+
 Improvements
 ============
 

doc/source/reference/arrays.ndarray.rst

@@ -294,6 +294,7 @@ Array conversion
    ndarray.itemset
    ndarray.setasflat
    ndarray.tostring
+   ndarray.tobytes
    ndarray.tofile
    ndarray.dump
    ndarray.dumps

doc/source/reference/c-api.array.rst

@@ -1574,7 +1574,7 @@ Conversion
 
 .. cfunction:: PyObject* PyArray_ToString(PyArrayObject* self, NPY_ORDER order)
 
-    Equivalent to :meth:`ndarray.tostring` (*self*, *order*). Return the bytes
+    Equivalent to :meth:`ndarray.tobytes` (*self*, *order*). Return the bytes
     of this array in a Python string.
 
 .. cfunction:: PyObject* PyArray_ToFile(PyArrayObject* self, FILE* fp, char* sep, char* format)

doc/source/reference/maskedarray.baseclass.rst

@@ -200,6 +200,7 @@ Conversion
    MaskedArray.tolist
    MaskedArray.torecords
    MaskedArray.tostring
+   MaskedArray.tobytes
 
 
 Shape manipulation

doc/source/reference/routines.ma.rst

@@ -251,7 +251,7 @@ Conversion operations
    ma.MaskedArray.tofile
    ma.MaskedArray.tolist
    ma.MaskedArray.torecords
-   ma.MaskedArray.tostring
+   ma.MaskedArray.tobytes
 
 
 Pickling and unpickling

numpy/add_newdocs.py

@@ -4386,7 +4386,7 @@ def luf(lamdaexpr, *args, **kwargs):
     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 @@ def luf(lamdaexpr, *args, **kwargs):
     """))
 
 
-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 @@ def luf(lamdaexpr, *args, **kwargs):
     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 @@ def luf(lamdaexpr, *args, **kwargs):
     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',
     """

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,14 +2456,17 @@ 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},
     {"tolist",
         (PyCFunction)array_tolist,
         METH_VARARGS, NULL},
     {"tostring",
-        (PyCFunction)array_tostring,
+        (PyCFunction)array_tobytes,
         METH_VARARGS | METH_KEYWORDS, NULL},
     {"trace",
         (PyCFunction)array_trace,

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},

numpy/core/tests/test_defchararray.py

@@ -138,7 +138,7 @@ def setUp(self):
 
     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):

numpy/core/tests/test_multiarray.py

@@ -2308,7 +2308,7 @@ def test_datetime(self):
 
 
 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 @@ def test_roundtrip_filename(self):
         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 @@ def test_ip_basic(self):
             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):

numpy/core/tests/test_regression.py

@@ -286,11 +286,11 @@ def test_unicode_string_comparison(self,level=rlevel):
         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,15 +1200,15 @@ def test_void_scalar_constructor(self):
         #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)
 
         #Create record scalar, construct from data and assert that
         #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 @@ def test_byteswap_complex_scalar(self):
             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 @@ def test_fromfile_tofile_seeks(self):
         # 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 @@ def test_complex64_alignment(self):
         # 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,

numpy/doc/byteswapping.py

@@ -101,7 +101,7 @@
 
 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 @@
 
 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 @@
 >>> 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 @@
 >>> 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
 
 """

numpy/f2py/tests/test_array_from_pyobj.py

@@ -227,7 +227,8 @@ def __init__(self, typ, dims, intent, obj):
         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],\

numpy/lib/format.py

@@ -407,15 +407,15 @@ 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)
         else:
             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):