8000 API: Update copy keyword across the codebase · numpy/numpy@96ce46d · GitHub
[go: up one dir, main page]
Skip to content

Commit 96ce46d

Browse files
mtsokolmtsokol
committed
API: Update copy keyword across the codebase
1 parent 7d20c92 commit 96ce46d

38 files changed

+196
-197
lines changed

‎numpy/_core/_add_newdocs.py

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -807,10 +807,11 @@
807807
a default ``dtype`` that can represent the values (by applying promotion
808808
rules when necessary.)
809809
copy : bool, optional
810-
If true (default), then the object is copied. Otherwise, a copy will
811-
only be made if ``__array__`` returns a copy, if obj is a nested
810+
If ``True`` (default), then the object is copied. If ``False``, a copy
811+
will only be made if ``__array__`` returns a copy, if obj is a nested
812812
sequence, or if a copy is needed to satisfy any of the other
813-
requirements (``dtype``, ``order``, etc.).
813+
requirements (``dtype``, ``order``, etc.). For ``False`` it raises
814+
a ``ValueError`` if a copy cannot be avoided.
814815
order : {'K', 'A', 'C', 'F'}, optional
815816
Specify the memory layout of the array. If object is not an array, the
816817
newly created array will be in C order (row major) unless 'F' is
@@ -826,7 +827,7 @@
826827
'F' F order F order
827828
===== ========= ===================================================
828829
829-
When ``copy=False`` and a copy is made for other reasons, the result is
830+
When ``copy=None`` and a copy is made for other reasons, the result is
830831
the same as if ``copy=True``, with some exceptions for 'A', see the
831832
Notes section. The default order is 'K'.
832833
subok : bool, optional
@@ -912,7 +913,7 @@
912913

913914
add_newdoc('numpy._core.multiarray', 'asarray',
914915
"""
915-
asarray(a, dtype=None, order=None, *, like=None)
916+
asarray(a, dtype=None, order=None, *, copy=None, like=None)
916917
917918
Convert the input to an array.
918919
@@ -932,12 +933,12 @@
932933
'K' (keep) preserve input order
933934
Defaults to 'K'.
934935
copy : bool, optional
935-
If true, then the object is copied. If false then the object is
936+
If ``True``, then the object is copied. If ``None`` then the object is
936937
copied only if needed, i.e. if ``__array__`` returns a copy, if obj
937938
is a nested sequence, or if a copy is needed to satisfy any of
938939
the other requirements (``dtype``, ``order``, etc.).
939-
For ``np._CopyMode.NEVER`` it raises a ``ValueError`` if a copy
940-
cannot be avoided. Default: false.
940+
For ``False`` it raises a ``ValueError`` if a copy cannot be avoided.
941+
Default: ``None``.
941942
${ARRAY_FUNCTION_LIKE}
942943
943944
.. versionadded:: 1.20.0

‎numpy/_core/_asarray.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ def require(a, dtype=None, requirements=None, *, like=None):
123123
order = 'C'
124124
requirements.remove('C')
125125

126-
arr = array(a, dtype=dtype, order=order, copy=False, subok=subok)
126+
arr = array(a, dtype=dtype, order=order, copy=None, subok=subok)
127127

128128
for prop in requirements:
129129
if not arr.flags[prop]:

‎numpy/_core/function_base.py

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -181,9 +181,9 @@ def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None,
181181
_nx.floor(y, out=y)
182182

183183
if retstep:
184-
return y.astype(dtype, copy=False), step
184+
return y.astype(dtype, copy=None), step
185185
else:
186-
return y.astype(dtype, copy=False)
186+
return y.astype(dtype, copy=None)
187187

188188

189189
def _logspace_dispatcher(start, stop, num=None, endpoint=None, base=None,
@@ -293,14 +293,14 @@ def logspace(start, stop, num=50, endpoint=True, base=10.0, dtype=None,
293293
"""
294294
ndmax = np.broadcast(start, stop, base).ndim
295295
start, stop, base = (
296-
np.array(a, copy=False, subok=True, ndmin=ndmax)
296+
np.array(a, copy=None, subok=True, ndmin=ndmax)
297297
for a in (start, stop, base)
298298
)
299299
y = linspace(start, stop, num=num, endpoint=endpoint, axis=axis)
300300
base = np.expand_dims(base, axis=axis)
301301
if dtype is None:
302302
return _nx.power(base, y)
303-
return _nx.power(base, y).astype(dtype, copy=False)
303+
return _nx.power(base, y).astype(dtype, copy=None)
304304

305305

306306
def _geomspace_dispatcher(start, stop, num=None, endpoint=None, dtype=None,
@@ -463,7 +463,7 @@ def geomspace(start, stop, num=50, endpoint=True, dtype=None, axis=0):
463463
if axis != 0:
464464
result = _nx.moveaxis(result, 0, axis)
465465

466-
return result.astype(dtype, copy=False)
466+
return result.astype(dtype, copy=None)
467467

468468

469469
def _needs_add_docstring(obj):

‎numpy/_core/numeric.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -478,7 +478,7 @@ def count_nonzero(a, axis=None, *, keepdims=False):
478478
if np.issubdtype(a.dtype, np.character):
479479
a_bool = a != a.dtype.type()
480480
else:
481-
a_bool = a.astype(np.bool, copy=False)
481+
a_bool = a.astype(np.bool, copy=None)
482482

483483
return a_bool.sum(axis=axis, dtype=np.intp, keepdims=keepdims)
484484

@@ -820,7 +820,7 @@ def convolve(a, v, mode='full'):
820820
array([2.5])
821821
822822
"""
823-
a, v = array(a, copy=False, ndmin=1), array(v, copy=False, ndmin=1)
823+
a, v = array(a, copy=None, ndmin=1), array(v, copy=None, ndmin=1)
824824
if (len(v) > len(a)):
825825
a, v = v, a
826826
if len(a) == 0:

‎numpy/_core/shape_base.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -552,7 +552,7 @@ def _block_check_depths_match(arrays, parent_index=[]):
552552
def _atleast_nd(a, ndim):
553553
# Ensures `a` has at least `ndim` dimensions by prepending
554554
# ones to `a.shape` as necessary
555-
return array(a, ndmin=ndim, copy=False, subok=True)
555+
return array(a, ndmin=ndim, copy=None, subok=True)
556556

557557

558558
def _accumulate(values):

‎numpy/_core/src/multiarray/conversion_utils.c

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -228,9 +228,8 @@ PyArray_OptionalIntpConverter(PyObject *obj, PyArray_Dims *seq)
228228
NPY_NO_EXPORT int
229229
PyArray_CopyConverter(PyObject *obj, NPY_COPYMODE *copymode) {
230230
if (obj == Py_None) {
231-
PyErr_SetString(PyExc_ValueError,
232-
"NoneType copy mode not allowed.");
233-
return NPY_FAIL;
231+
*copymode = NPY_COPY_IF_NEEDED;
232+
return NPY_SUCCEED;
234233
}
235234

236235
int int_copymode;

‎numpy/_core/src/multiarray/conversion_utils.h

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@ NPY_NO_EXPORT int
1313
PyArray_OptionalIntpConverter(PyObject *obj, PyArray_Dims *seq);
1414

1515
typedef enum {
16-
NPY_COPY_IF_NEEDED = 0,
16+
NPY_COPY_NEVER = 0,
1717
NPY_COPY_ALWAYS = 1,
18-
NPY_COPY_NEVER = 2,
18+
NPY_COPY_IF_NEEDED = 2,
1919
} NPY_COPYMODE;
2020

2121
NPY_NO_EXPORT int

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -831,7 +831,8 @@ array_astype(PyArrayObject *self,
831831

832832
if (forcecopy == NPY_COPY_NEVER) {
833833
PyErr_SetString(PyExc_ValueError,
834-
"Unable to avoid copy while casting in never copy mode.");
834+
"Unable to avoid copy while casting in never copy mode. "
835+
"Use copy=None to copy only if necessary.");
835836
Py_DECREF(dtype);
836837
return NULL;
837838
}

‎numpy/_core/src/multiarray/multiarraymodule.c

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1827,7 +1827,7 @@ array_asanyarray(PyObject *NPY_UNUSED(ignored),
18271827
}
18281828

18291829
PyObject *res = _array_fromobject_generic(
1830-
op, dt_info.descr, dt_info.dtype, NPY_FALSE, order, NPY_TRUE, 0);
1830+
op, dt_info.descr, dt_info.dtype, NPY_COPY_IF_NEEDED, order, NPY_TRUE, 0);
18311831
Py_XDECREF(dt_info.descr);
18321832
Py_XDECREF(dt_info.dtype);
18331833
return res;
@@ -1868,7 +1868,7 @@ array_ascontiguousarray(PyObject *NPY_UNUSED(ignored),
18681868
}
18691869

18701870
PyObject *res = _array_fromobject_generic(
1871-
op, dt_info.descr, dt_info.dtype, NPY_FALSE, NPY_CORDER, NPY_FALSE,
1871+
op, dt_info.descr, dt_info.dtype, NPY_COPY_IF_NEEDED, NPY_CORDER, NPY_FALSE,
18721872
1);
18731873
Py_XDECREF(dt_info.descr);
18741874
Py_XDECREF(dt_info.dtype);
@@ -1910,7 +1910,7 @@ array_asfortranarray(PyObject *NPY_UNUSED(ignored),
19101910
}
19111911

19121912
PyObject *res = _array_fromobject_generic(
1913-
op, dt_info.descr, dt_info.dtype, NPY_FALSE, NPY_FORTRANORDER,
1913+
op, dt_info.descr, dt_info.dtype, NPY_COPY_IF_NEEDED, NPY_FORTRANORDER,
19141914
NPY_FALSE, 1);
19151915
Py_XDECREF(dt_info.descr);
19161916
Py_XDECREF(dt_info.dtype);

‎numpy/_core/tests/test_api.py

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -177,18 +177,18 @@ def test_array_astype():
177177
assert_equal(a, b)
178178
assert_(not (a is b))
179179

180-
# copy=False parameter can sometimes skip a copy
180+
# copy=False parameter skips a copy
181181
b = a.astype('f4', copy=False)
182182
assert_(a is b)
183183

184184
# order parameter allows overriding of the memory layout,
185185
# forcing a copy if the layout is wrong
186-
b = a.astype('f4', order='F', copy=False)
186+
b = a.astype('f4', order='F', copy=None)
187187
assert_equal(a, b)
188188
assert_(not (a is b))
189189
assert_(b.flags.f_contiguous)
190190

191-
b = a.astype('f4', order='C', copy=False)
191+
b = a.astype('f4', order='C', copy=None)
192192
assert_equal(a, b)
193193
assert_(a is b)
194194
assert_(b.flags.c_contiguous)
@@ -214,12 +214,12 @@ class MyNDArray(np.ndarray):
214214
assert_(a is b)
215215

216216
# subok=True is default, and creates a subtype on a cast
217-
b = a.astype('i4', copy=False)
217+
b = a.astype('i4', copy=None)
218218
assert_equal(a, b)
219219
assert_equal(type(b), MyNDArray)
220220

221221
# subok=False never returns a subclass
222-
b = a.astype('f4', subok=False, copy=False)
222+
b = a.astype('f4', subok=False, copy=None)
223223
assert_equal(a, b)
224224
assert_(not (a is b))
225225
assert_(type(b) is not MyNDArray)
@@ -536,9 +536,9 @@ def check_contig(a, ccontig, fcontig):
536536
check_contig(np.empty((2, 2), order='F'), False, True)
537537

538538
# Check that np.array creates correct contiguous flags:
539-
check_contig(np.array(a, copy=False), False, False)
540-
check_contig(np.array(a, copy=False, order='C'), True, False)
541-
check_contig(np.array(a, ndmin=4, copy=False, order='F'), False, True)
539+
check_contig(np.array(a, copy=None), False, False)
540+
check_contig(np.array(a, copy=None, order='C'), True, False)
541+
check_contig(np.array(a, ndmin=4, copy=None, order='F'), False, True)
542542

543543
# Check slicing update of flags and :
544544
check_contig(a[0], True, True)
@@ -577,18 +577,15 @@ def test_astype_copyflag():
577577
res_false = arr.astype(np.intp, copy=False)
578578
# `res_false is arr` currently, but check `may_share_memory`.
579579
assert np.may_share_memory(arr, res_false)
580-
res_if_needed = arr.astype(np.intp, copy=np._CopyMode.IF_NEEDED)
580+
res_if_needed = arr.astype(np.intp, copy=None)
581581
# `res_if_needed is arr` currently, but check `may_share_memory`.
582582
assert np.may_share_memory(arr, res_if_needed)
583583

584584
res_never = arr.astype(np.intp, copy=np._CopyMode.NEVER)
585585
assert np.may_share_memory(arr, res_never)
586586

587587
# Simple tests for when a copy is necessary:
588-
res_false = arr.astype(np.float64, copy=False)
589-
assert_array_equal(res_false, arr)
590-
res_if_needed = arr.astype(np.float64,
591-
copy=np._CopyMode.IF_NEEDED)
588+
res_if_needed = arr.astype(np.float64, copy=None)
592589
assert_array_equal(res_if_needed, arr)
593590
assert_raises(ValueError, arr.astype, np.float64,
594-
C2EE copy=np._CopyMode.NEVER)
591+
copy=False)

‎numpy/_core/tests/test_multiarray.py

Lines changed: 32 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -477,7 +477,14 @@ def test_array_copy_false(self):
477477
e = np.array(d, copy=False)
478478
d[1] = 3
479479
assert_array_equal(e, [1, 3, 3])
480-
e = np.array(d, copy=False, order='F')
480+
np.array(d, copy=False, order='F')
481+
482+
def test_array_copy_if_needed(self):
483+
d = np.array([1, 2, 3])
484+
e = np.array(d, copy=None)
485+
d[1] = 3
486+
assert_array_equal(e, [1, 3, 3])
487+
e = np.array(d, copy=None, order='F')
481488
d[1] = 4
482489
assert_array_equal(e, [1, 4, 3])
483490
e[2] = 7
@@ -8326,7 +8333,8 @@ def __bool__(self):
83268333
raise ValueError
83278334

83288335
true_vals = [True, np._CopyMode.ALWAYS, np.True_]
8329-
false_vals = [False, np._CopyMode.IF_NEEDED, np.False_]
8336+
if_needed_vals = [None, np._CopyMode.IF_NEEDED]
8337+
false_vals = [False, np._CopyMode.NEVER, np.False_]
83308338

83318339
def test_scalars(self):
83328340
# Test both numpy and python scalars
@@ -8336,17 +8344,16 @@ def test_scalars(self):
83368344 48DA
pyscalar = arr.item(0)
83378345

83388346
# Test never-copy raises error:
8339-
assert_raises(ValueError, np.array, scalar,
8340-
copy=np._CopyMode.NEVER)
8341-
assert_raises(ValueError, np.array, pyscalar,
8342-
copy=np._CopyMode.NEVER)
83438347
assert_raises(ValueError, np.array, pyscalar,
83448348
copy=self.RaiseOnBool())
83458349
assert_raises(ValueError, _multiarray_tests.npy_ensurenocopy,
83468350
[1])
8347-
# Casting with a dtype (to unsigned integers) can be special:
8348-
with pytest.raises(ValueError):
8349-
np.array(pyscalar, dtype=np.int64, copy=np._CopyMode.NEVER)
8351+
for copy in self.false_vals:
8352+
assert_raises(ValueError, np.array, scalar, copy=copy)
8353+
assert_raises(ValueError, np.array, pyscalar, copy=copy)
8354+
# Casting with a dtype (to unsigned integers) can be special:
8355+
with pytest.raises(ValueError):
8356+
np.array(pyscalar, dtype=np.int64, copy=copy)
83508357

83518358
def test_compatible_cast(self):
83528359

@@ -8371,27 +8378,23 @@ def int_types(byteswap=False):
83718378

83728379
if int1 == int2:
83738380
# Casting is not necessary, base check is sufficient here
8374-
for copy in self.false_vals:
8381+
for copy in self.if_needed_vals:
83758382
res = np.array(arr, copy=copy, dtype=int2)
83768383
assert res is arr or res.base is arr
83778384

8378-
res = np.array(arr,
8379-
copy=np._CopyMode.NEVER,
8380-
dtype=int2)
8381-
assert res is arr or res.base is arr
8385+
for copy in self.false_vals:
8386+
res = np.array(arr, copy=copy, dtype=int2)
8387+
assert res is arr or res.base is arr
83828388

83838389
else:
83848390
# Casting is necessary, assert copy works:
8385-
for copy in self.false_vals:
8391+
for copy in self.if_needed_vals:
83868392
res = np.array(arr, copy=copy, dtype=int2)
83878393
assert res is not arr and res.flags.owndata
83888394
assert_array_equal(res, arr)
83898395

83908396
assert_raises(ValueError, np.array,
8391-
arr, copy=np._CopyMode.NEVER,
8392-
dtype=int2)
8393-
assert_raises(ValueError, np.array,
8394-
arr, copy=None,
8397+
arr, copy=False,
83958398
dtype=int2)
83968399

83978400
def test_buffer_interface(self):
@@ -8445,13 +8448,14 @@ def __array__(self):
84458448
# may be open for change:
84468449
assert res is not base_arr
84478450

8448-
for copy in self.false_vals:
8449-
res = np.array(arr, copy=False)
8451+
for copy in self.if_needed_vals:
8452+
res = np.array(arr, copy=copy)
84508453
assert_array_equal(res, base_arr)
84518454
assert res is base_arr # numpy trusts the ArrayLike
84528455

8453-
with pytest.raises(ValueError):
8454-
np.array(arr, copy=np._CopyMode.NEVER)
8456+
for copy in self.false_vals:
8457+
with pytest.raises(ValueError):
8458+
np.array(arr, copy=copy)
84558459

84568460
@pytest.mark.parametrize(
84578461
"arr", [np.ones(()), np.arange(81).reshape((9, 9))])
@@ -8491,26 +8495,18 @@ def test_order_mismatch(self, arr, order1, order2):
84918495
assert_array_equal(arr, res)
84928496

84938497
if no_copy_necessary:
8494-
for copy in self.false_vals:
8498+
for copy in self.if_needed_vals + self.false_vals:
84958499
res = np.array(view, copy=copy, order=order2)
84968500
# res.base.obj refers to the memoryview
84978501
if not IS_PYPY:
84988502
assert res is arr or res.base.obj is arr
8499-
8500-
res = np.array(view, copy=np._CopyMode.NEVER,
8501-
order=order2)
8502-
if not IS_PYPY:
8503-
assert res is arr or res.base.obj is arr
85048503
else:
8505-
for copy in self.false_vals:
8504+
for copy in self.if_needed_vals:
85068505
res = np.array(arr, copy=copy, order=order2)
85078506
assert_array_equal(arr, res)
8508-
assert_raises(ValueError, np.array,
8509-
view, copy=np._CopyMode.NEVER,
8510-
order=order2)
8511-
assert_raises(ValueError, np.array,
8512-
view, copy=None,
8513-
order=order2)
8507+
for copy in self.false_vals:
8508+
assert_raises(ValueError, np.array,
8509+
view, copy=copy, order=order2)
85148510

85158511
def test_striding_not_ok(self):
85168512
arr = np.array([[1, 2, 4], [3, 4, 5]])

0 commit comments

Comments
 (0)
0