From db59c45e5d02877bb246838a7cb277e5e3eed48c Mon Sep 17 00:00:00 2001 From: solarjoe Date: Wed, 16 Aug 2017 09:23:37 +0200 Subject: DOC: Improve ndarray.shape property documentation. [ci skip] --- numpy/add_newdocs.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 55538ad1b..f81f6cb72 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -2926,11 +2926,14 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('shape', """ Tuple of array dimensions. + As with `numpy.reshape`, one shape dimension can be -1. In this case, the value is + inferred from the length of the array and remaining dimensions. Notes ----- May be used to "reshape" the array, as long as this would not require a change in the total number of elements - + Using `numpy.reshape` or `ndarray.reshape` should always be preferred. + Setting the shape directly is not really a safe thing to do. Examples -------- >>> x = np.array([1, 2, 3, 4]) @@ -2948,6 +2951,10 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('shape', Traceback (most recent call last): File "", line 1, in ValueError: total size of new array must be unchanged + See Also + -------- + numpy.reshape : equivalent function + ndarray.reshape : equivalent function """)) -- cgit v1.2.1 From 6a5e6188d938091ca1c335ae5f736b563bdca245 Mon Sep 17 00:00:00 2001 From: Charles Harris Date: Mon, 2 Oct 2017 14:30:07 -0600 Subject: DOC: Update ndarray.shape property documention. [ci skip] --- numpy/add_newdocs.py | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) (limited to 'numpy/add_newdocs.py') diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index f81f6cb72..fd6fe277f 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -2926,14 +2926,13 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('shape', """ Tuple of array dimensions. - As with `numpy.reshape`, one shape dimension can be -1. In this case, the value is - inferred from the length of the array and remaining dimensions. - Notes - ----- - May be used to "reshape" the array, as long as this would not - require a change in the total number of elements - Using `numpy.reshape` or `ndarray.reshape` should always be preferred. - Setting the shape directly is not really a safe thing to do. + The shape property is usually used to get the current shape of an array, + but may also be used to reshape the array in-place by assigning a tuple of + array dimensions to it. As with `numpy.reshape`, one of the new shape + dimensions can be -1, in which case its value is inferred from the size of + the array and the remaining dimensions. Reshaping an array in-place will + fail if a copy is required. + Examples -------- >>> x = np.array([1, 2, 3, 4]) @@ -2951,10 +2950,15 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('shape', Traceback (most recent call last): File "", line 1, in ValueError: total size of new array must be unchanged + >>> np.zeros((4,2))[::2].shape = (-1,) + Traceback (most recent call last): + File "", line 1, in + AttributeError: incompatible shape for a non-contiguous array + See Also -------- - numpy.reshape : equivalent function - ndarray.reshape : equivalent function + numpy.reshape : similar function + ndarray.reshape : similar method """)) -- cgit v1.2.1