diff options
Diffstat (limited to 'numpy/add_newdocs.py')
| -rw-r--r-- | numpy/add_newdocs.py | 157 |
1 files changed, 85 insertions, 72 deletions
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index cf4af9f84..55538ad1b 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -931,7 +931,7 @@ add_newdoc('numpy.core.multiarray', 'zeros', >>> np.zeros(5) array([ 0., 0., 0., 0., 0.]) - >>> np.zeros((5,), dtype=np.int) + >>> np.zeros((5,), dtype=int) array([0, 0, 0, 0, 0]) >>> np.zeros((2, 1)) @@ -1038,7 +1038,7 @@ add_newdoc('numpy.core.multiarray', 'fromiter', Examples -------- >>> iterable = (x*x for x in range(5)) - >>> np.fromiter(iterable, np.float) + >>> np.fromiter(iterable, float) array([ 0., 1., 4., 9., 16.]) """) @@ -1158,7 +1158,7 @@ add_newdoc('numpy.core.multiarray', 'frombuffer', add_newdoc('numpy.core.multiarray', 'concatenate', """ - concatenate((a1, a2, ...), axis=0) + concatenate((a1, a2, ...), axis=0, out=None) Join a sequence of arrays along an existing axis. @@ -1169,6 +1169,10 @@ add_newdoc('numpy.core.multiarray', 'concatenate', corresponding to `axis` (the first, by default). axis : int, optional The axis along which the arrays will be joined. Default is 0. + out : ndarray, optional + If provided, the destination to place the result. The shape must be + correct, matching that of what concatenate would have returned if no + out argument were specified. Returns ------- @@ -1338,7 +1342,8 @@ add_newdoc('numpy.core.multiarray', 'arange', step : number, optional Spacing between values. For any output `out`, this is the distance between two adjacent values, ``out[i+1] - out[i]``. The default - step size is 1. If `step` is specified, `start` must also be given. + step size is 1. If `step` is specified as a position argument, + `start` must also be given. dtype : dtype The type of the output array. If `dtype` is not given, infer the data type from the other input arguments. @@ -1452,8 +1457,8 @@ add_newdoc('numpy.core.multiarray', 'where', condition : array_like, bool When True, yield `x`, otherwise yield `y`. x, y : array_like, optional - Values from which to choose. `x` and `y` need to have the same - shape as `condition`. + Values from which to choose. `x`, `y` and `condition` need to be + broadcastable to some shape. Returns ------- @@ -1500,7 +1505,7 @@ add_newdoc('numpy.core.multiarray', 'where', Find the indices of elements of `x` that are in `goodvalues`. >>> goodvalues = [3, 4, 7] - >>> ix = np.in1d(x.ravel(), goodvalues).reshape(x.shape) + >>> ix = np.isin(x, goodvalues) >>> ix array([[False, False, False], [ True, True, False], @@ -1589,7 +1594,7 @@ add_newdoc('numpy.core.multiarray', 'lexsort', add_newdoc('numpy.core.multiarray', 'can_cast', """ - can_cast(from, totype, casting = 'safe') + can_cast(from_, to, casting='safe') Returns True if cast between data types can occur according to the casting rule. If from is a scalar or array scalar, also returns @@ -1598,9 +1603,9 @@ add_newdoc('numpy.core.multiarray', 'can_cast', Parameters ---------- - from : dtype, dtype specifier, scalar, or array + from_ : dtype, dtype specifier, scalar, or array Data type, scalar, or array to cast from. - totype : dtype or dtype specifier + to : dtype or dtype specifier Data type to cast to. casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Controls what kind of data casting may occur. @@ -1635,9 +1640,9 @@ add_newdoc('numpy.core.multiarray', 'can_cast', >>> np.can_cast(np.int32, np.int64) True - >>> np.can_cast(np.float64, np.complex) + >>> np.can_cast(np.float64, complex) True - >>> np.can_cast(np.complex, np.float) + >>> np.can_cast(complex, float) False >>> np.can_cast('i8', 'f8') @@ -3096,7 +3101,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('__copy__', add_newdoc('numpy.core.multiarray', 'ndarray', ('__deepcopy__', - """a.__deepcopy__() -> Deep copy of array. + """a.__deepcopy__(memo, /) -> Deep copy of array. Used if copy.deepcopy is called on an array. @@ -3112,9 +3117,12 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('__reduce__', add_newdoc('numpy.core.multiarray', 'ndarray', ('__setstate__', - """a.__setstate__(version, shape, dtype, isfortran, rawdata) + """a.__setstate__(state, /) For unpickling. + + The `state` argument must be a sequence that contains the following + elements: Parameters ---------- @@ -3292,7 +3300,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('astype', add_newdoc('numpy.core.multiarray', 'ndarray', ('byteswap', """ - a.byteswap(inplace) + a.byteswap(inplace=False) Swap the bytes of the array elements @@ -3315,7 +3323,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('byteswap', >>> A = np.array([1, 256, 8755], dtype=np.int16) >>> map(hex, A) ['0x1', '0x100', '0x2233'] - >>> A.byteswap(True) + >>> A.byteswap(inplace=True) array([ 256, 1, 13090], dtype=int16) >>> map(hex, A) ['0x100', '0x1', '0x3322'] @@ -3418,7 +3426,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('copy', Controls the memory layout of the copy. 'C' means C-order, 'F' means F-order, 'A' means 'F' if `a` is Fortran contiguous, 'C' otherwise. 'K' means match the layout of `a` as closely - as possible. (Note that this function and :func:numpy.copy are very + as possible. (Note that this function and :func:`numpy.copy` are very similar, but have different default values for their order= arguments.) @@ -3764,7 +3772,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('itemset', add_newdoc('numpy.core.multiarray', 'ndarray', ('max', """ - a.max(axis=None, out=None) + a.max(axis=None, out=None, keepdims=False) Return the maximum along a given axis. @@ -5107,7 +5115,7 @@ add_newdoc('numpy.core.multiarray', 'digitize', add_newdoc('numpy.core.multiarray', 'bincount', """ - bincount(x, weights=None, minlength=None) + bincount(x, weights=None, minlength=0) Count number of occurrences of each value in array of non-negative ints. @@ -5141,7 +5149,7 @@ add_newdoc('numpy.core.multiarray', 'bincount', ------ ValueError If the input is not 1-dimensional, or contains elements with negative - values, or if `minlength` is non-positive. + values, or if `minlength` is negative. TypeError If the type of the input is float or complex. @@ -5163,7 +5171,7 @@ add_newdoc('numpy.core.multiarray', 'bincount', The input array needs to be of integer dtype, otherwise a TypeError is raised: - >>> np.bincount(np.arange(5, dtype=np.float)) + >>> np.bincount(np.arange(5, dtype=float)) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: array cannot be safely cast to required type @@ -5421,40 +5429,19 @@ add_newdoc('numpy.core', 'ufunc', """ Functions that operate element by element on whole arrays. - To see the documentation for a specific ufunc, use np.info(). For - example, np.info(np.sin). Because ufuncs are written in C + To see the documentation for a specific ufunc, use `info`. For + example, ``np.info(np.sin)``. Because ufuncs are written in C (for speed) and linked into Python with NumPy's ufunc facility, Python's help() function finds this page whenever help() is called on a ufunc. - A detailed explanation of ufuncs can be found in the "ufuncs.rst" - file in the NumPy reference guide. - - Unary ufuncs: - ============= - - op(X, out=None) - Apply op to X elementwise + A detailed explanation of ufuncs can be found in the docs for :ref:`ufuncs`. - Parameters - ---------- - X : array_like - Input array. - out : array_like - An array to store the output. Must be the same shape as `X`. - - Returns - ------- - r : array_like - `r` will have the same shape as `X`; if out is provided, `r` - will be equal to out. + Calling ufuncs: + =============== - Binary ufuncs: - ============== - - op(X, Y, out=None) - Apply `op` to `X` and `Y` elementwise. May "broadcast" to make - the shapes of `X` and `Y` congruent. + op(*x[, out], where=True, **kwargs) + Apply `op` to the arguments `*x` elementwise, broadcasting the arguments. The broadcasting rules are: @@ -5463,18 +5450,25 @@ add_newdoc('numpy.core', 'ufunc', Parameters ---------- - X : array_like - First input array. - Y : array_like - Second input array. - out : array_like - An array to store the output. Must be the same shape as the - output would have. + *x : array_like + Input arrays. + out : ndarray, None, or tuple of ndarray and None, optional + Alternate array object(s) in which to put the result; if provided, it + must have a shape that the inputs broadcast to. A tuple of arrays + (possible only as a keyword argument) must have length equal to the + number of outputs; use `None` for outputs to be allocated by the ufunc. + where : array_like, optional + Values of True indicate to calculate the ufunc at that position, values + of False indicate to leave the value in the output alone. + **kwargs + For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`. Returns ------- - r : array_like - The return value; if out is provided, `r` will be equal to out. + r : ndarray or tuple of ndarray + `r` will have the shape that the arrays in `x` broadcast to; if `out` is + provided, `r` will be equal to `out`. If the function has more than one + output, then the result will be a tuple of arrays. """) @@ -5683,9 +5677,14 @@ add_newdoc('numpy.core', 'ufunc', ('reduce', The type used to represent the intermediate results. Defaults to the data-type of the output array if this is provided, or the data-type of the input array if no output array is provided. - out : ndarray, optional - A location into which the result is stored. If not provided, a - freshly-allocated array is returned. + out : ndarray, None, or tuple of ndarray and None, optional + A location into which the result is stored. If not provided or `None`, + a freshly-allocated array is returned. For consistency with + :ref:`ufunc.__call__`, if given as a keyword, this may be wrapped in a + 1-element tuple. + + .. versionchanged:: 1.13.0 + Tuples are allowed for keyword argument. keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, @@ -5728,7 +5727,7 @@ add_newdoc('numpy.core', 'ufunc', ('reduce', add_newdoc('numpy.core', 'ufunc', ('accumulate', """ - accumulate(array, axis=0, dtype=None, out=None, keepdims=None) + accumulate(array, axis=0, dtype=None, out=None) Accumulate the result of applying the operator to all elements. @@ -5757,11 +5756,14 @@ add_newdoc('numpy.core', 'ufunc', ('accumulate', The data-type used to represent the intermediate results. Defaults to the data-type of the output array if such is provided, or the the data-type of the input array if no output array is provided. - out : ndarray, optional - A location into which the result is stored. If not provided a - freshly-allocated array is returned. - keepdims : bool - Has no effect. Deprecated, and will be removed in future. + out : ndarray, None, or tuple of ndarray and None, optional + A location into which the result is stored. If not provided or `None`, + a freshly-allocated array is returned. For consistency with + :ref:`ufunc.__call__`, if given as a keyword, this may be wrapped in a + 1-element tuple. + + .. versionchanged:: 1.13.0 + Tuples are allowed for keyword argument. Returns ------- @@ -5836,9 +5838,14 @@ add_newdoc('numpy.core', 'ufunc', ('reduceat', The type used to represent the intermediate results. Defaults to the data type of the output array if this is provided, or the data type of the input array if no output array is provided. - out : ndarray, optional - A location into which the result is stored. If not provided a - freshly-allocated array is returned. + out : ndarray, None, or tuple of ndarray and None, optional + A location into which the result is stored. If not provided or `None`, + a freshly-allocated array is returned. For consistency with + :ref:`ufunc.__call__`, if given as a keyword, this may be wrapped in a + 1-element tuple. + + .. versionchanged:: 1.13.0 + Tuples are allowed for keyword argument. Returns ------- @@ -6100,7 +6107,7 @@ add_newdoc('numpy.core.multiarray', 'dtype', Using tuples. ``int`` is a fixed type, 3 the field's shape. ``void`` is a flexible type, here of size 10: - >>> np.dtype([('hello',(np.int,3)),('world',np.void,10)]) + >>> np.dtype([('hello',(int,3)),('world',np.void,10)]) dtype([('hello', '<i4', 3), ('world', '|V10')]) Subdivide ``int16`` into 2 ``int8``'s, called x and y. 0 and 1 are @@ -6739,7 +6746,7 @@ add_newdoc('numpy.core.multiarray', 'busday_count', add_newdoc('numpy.core.multiarray', 'normalize_axis_index', """ - normalize_axis_index(axis, ndim) + normalize_axis_index(axis, ndim, msg_prefix=None) Normalizes an axis index, `axis`, such that is a valid positive index into the shape of array with `ndim` dimensions. Raises an AxisError with an @@ -6756,6 +6763,8 @@ add_newdoc('numpy.core.multiarray', 'normalize_axis_index', ndim : int The number of dimensions of the array that `axis` should be normalized against + msg_prefix : str + A prefix to put before the message, typically the name of the argument Returns ------- @@ -6780,6 +6789,10 @@ add_newdoc('numpy.core.multiarray', 'normalize_axis_index', Traceback (most recent call last): ... AxisError: axis 3 is out of bounds for array of dimension 3 + >>> normalize_axis_index(-4, ndim=3, msg_prefix='axes_arg') + Traceback (most recent call last): + ... + AxisError: axes_arg: axis -4 is out of bounds for array of dimension 3 """) ############################################################################## |