10000 DEP: Deprecate ndarray.tostring() · numpy/numpy@7668a33 · GitHub
[go: up one dir, main page]
Skip to content

Commit 7668a33

Browse files
eric-wiesereric-wieser
committed
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@1ce3eb5).
1 parent b3f41ee commit 7668a33

File tree

7 files changed

+71
-21
lines changed

7 files changed

+71
-21
lines changed

‎doc/release/upcoming_changes/15867.deprecation.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
``numpy.ndarray.tostring()`` is deprecated in favor of ``tobytes()``
2+
--------------------------------------------------------------------
3+
`~numpy.ndarray.tobytes` has existed since the 1.9 release, but until this release `~numpy.ndarray.tostring` emitted no warning.
4+
The change to emit a warning brings NumPy in line with the builtin `array.array` methods of the same name.

‎numpy/core/_add_newdocs.py

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -3930,8 +3930,8 @@
39303930
"""))
39313931

39323932

3933-
tobytesdoc = """
3934-
a.{name}(order='C')
3933+
add_newdoc('numpy.core.multiarray', 'ndarray', ('tobytes', """
3934+
a.tobytes(order='C')
39353935
39363936
Construct Python bytes containing the raw data bytes in the array.
39373937
@@ -3941,11 +3941,11 @@
39413941
unless the F_CONTIGUOUS flag in the array is set, in which case it
39423942
means 'Fortran' order.
39433943
3944-
{deprecated}
3944+
.. versionadded:: 1.9.0
39453945
39463946
Parameters
39473947
----------
3948-
order : {{'C', 'F', None}}, optional
3948+
order : {'C', 'F', None}, optional
39493949
Order of the data for multidimensional arrays:
39503950
C, Fortran, or the same as for the original array.
39513951
@@ -3964,18 +3964,19 @@
39643964
>>> x.tobytes('F')
39653965
b'\\x00\\x00\\x02\\x00\\x01\\x00\\x03\\x00'
39663966
3967-
"""
3967+
"""))
3968+
3969+
3970+
add_newdoc('numpy.core.multiarray', 'ndarray', ('tostring', r"""
3971+
a.tostring(order='C')
3972+
3973+
A compatibility alias for `tobytes`, with exactly the same behavior.
3974+
3975+
Despite its name, it returns `bytes` not `str`\ s.
3976+
3977+
.. deprecated:: 1.19.0
3978+
"""))
39683979

3969-
add_newdoc('numpy.core.multiarray', 'ndarray',
3970-
('tostring', tobytesdoc.format(name='tostring',
3971-
deprecated=
3972-
'This function is a compatibility '
3973-
'alias for tobytes. Despite its '
3974-
'name it returns bytes not '
3975-
'strings.')))
3976-
add_newdoc('numpy.core.multiarray', 'ndarray',
3977-
('tobytes', tobytesdoc.format(name='tobytes',
3978-
deprecated='.. versionadded:: 1.9.0')))
39793980

39803981
add_newdoc('numpy.core.multiarray', 'ndarray', ('trace',
39813982
"""

‎numpy/core/src/multiarray/methods.c

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -566,6 +566,23 @@ array_tobytes(PyArrayObject *self, PyObject *args, PyObject *kwds)
566566
return PyArray_ToString(self, order);
567567
}
568568

569+
static PyObject *
570+
array_tostring(PyArrayObject *self, PyObject *args, PyObject *kwds)
571+
{
572+
NPY_ORDER order = NPY_CORDER;
573+
static char *kwlist[] = {"order", NULL};
574+
575+
if (!PyArg_ParseTupleAndKeywords(args, kwds, "|O&:tostring", kwlist,
576+
PyArray_OrderConverter, &order)) {
577+
return NULL;
578+
}
579+
/* 2020-03-30, NumPy 1.19 */
580+
if (DEPRECATE("tostring() is deprecated. Use tobytes() instead.") < 0) {
581+
return NULL;
582+
}
583+
return PyArray_ToString(self, order);
584+
}
585+
569586

570587
/* This should grow an order= keyword to be consistent
571588
*/
@@ -2844,7 +2861,7 @@ NPY_NO_EXPORT PyMethodDef array_methods[] = {
28442861
(PyCFunction)array_tolist,
28452862
METH_VARARGS, NULL},
28462863
{"tostring",
2847-
(PyCFunction)array_tobytes,
2864+
(PyCFunction)array_tostring,
28482865
METH_VARARGS | METH_KEYWORDS, NULL},
28492866
{"trace",
28502867
(PyCFunction)array_trace,

‎numpy/core/tests/test_deprecations.py

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
import warnings
99
import pytest
1010
import tempfile
11+
import re
1112

1213
import numpy as np
1314
from numpy.testing import (
@@ -548,6 +549,22 @@ def test_deprecate_ragged_arrays():
548549
np.array(arg)
549550

550551

552+
class TestToString(_DeprecationTestCase):
553+
# 2020-03-06 1.19.0
554+
message = re.escape("tostring() is deprecated. Use tobytes() instead.")
555+
556+
def test_tostring(self):
557+
arr = np.array(list(b"test\xFF"), dtype=np.uint8)
558+
self.assert_deprecated(arr.tostring)
559+
560+
def test_tostring_matches_tobytes(self):
561+
arr = np.array(list(b"test\xFF"), dtype=np.uint8)
562+
b = arr.tobytes()
563+
with assert_warns(DeprecationWarning):
564+
s = arr.tostring()
565+
assert s == b
566+
567+
551568
class TestDTypeCoercion(_DeprecationTestCase):
552569
# 2020-02-06 1.19.0
553570
message = "Converting .* to a dtype .*is deprecated"

‎numpy/lib/user_array.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,10 @@ def tostring(self):
231231
""
232232
return self.array.tostring()
233233

234+
def tobytes(self):
235+
""
236+
return self.array.tobytes()
237+
234238
def byteswap(self):
235239
""
236240
return self._rc(self.array.byteswap())

‎numpy/ma/core.py

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5954,10 +5954,17 @@ def tolist(self, fill_value=None):
59545954
return result.tolist()
59555955

59565956
def tostring(self, fill_value=None, order='C'):
5957+
r"""
5958+
A compatibility alias for `tobytes`, with exactly the same behavior.
5959+
5960+
Despite its name, it returns `bytes` not `str`\ s.
5961+
5962+
.. deprecated:: 1.19.0
59575963
"""
5958-
This function is a compatibility alias for tobytes. Despite its name it
5959-
returns bytes not strings.
5960-
"""
5964+
# 2020-03-30, Numpy 1.19.0
5965+
warnings.warn(
5966+
"tostring() is deprecated. Use tobytes() instead.",
5967+
DeprecationWarning, stacklevel=2)
59615968

59625969
return self.tobytes(fill_value, order=order)
59635970

‎numpy/ma/tests/test_regression.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,6 @@ def test_empty_list_on_structured(self):
8686
ma = np.ma.MaskedArray([(1, 1.), (2, 2.), (3, 3.)], dtype='i4,f4')
8787
assert_array_equal(ma[[]], ma[:0])
8888

89-
def test_masked_array_tostring_fortran(self):
89+
def test_masked_array_tobytes_fortran(self):
9090
ma = np.ma.arange(4).reshape((2,2))
91-
assert_array_equal(ma.tostring(order='F'), ma.T.tostring())
91+
assert_array_equal(ma.tobytes(order='F'), ma.T.tobytes())

0 commit comments

Comments
 (0)
0