diff options
Diffstat (limited to 'numpy/add_newdocs.py')
| -rw-r--r-- | numpy/add_newdocs.py | 173 |
1 files changed, 76 insertions, 97 deletions
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 62ca6dca3..86ea4b8b6 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -1598,6 +1598,14 @@ add_newdoc('numpy.core.multiarray', 'can_cast', out : bool True if cast can occur according to the casting rule. + Notes + ----- + Starting in NumPy 1.9, can_cast function now returns False in 'safe' + casting mode for integer/float dtype and string dtype if the string dtype + length is not long enough to store the max integer/float value converted + to a string. Previously can_cast in 'safe' mode returned True for + integer/float dtype and a string dtype of any length. + See also -------- dtype, result_type @@ -1618,7 +1626,7 @@ add_newdoc('numpy.core.multiarray', 'can_cast', >>> np.can_cast('i8', 'f4') False >>> np.can_cast('i4', 'S4') - True + False Casting scalars @@ -1693,6 +1701,11 @@ add_newdoc('numpy.core.multiarray', 'promote_types', Notes ----- .. versionadded:: 1.6.0 + Starting in NumPy 1.9, promote_types function now returns a valid string + length when given an integer or float dtype as one argument and a string + dtype as another argument. Previously it always returned the input string + dtype, even if it wasn't long enough to store the max integer/float value + converted to a string. See Also -------- @@ -1709,10 +1722,8 @@ add_newdoc('numpy.core.multiarray', 'promote_types', >>> np.promote_types('>i8', '<c8') dtype('complex128') - >>> np.promote_types('i1', 'S8') - Traceback (most recent call last): - File "<stdin>", line 1, in <module> - TypeError: invalid type promotion + >>> np.promote_types('i4', 'S8') + dtype('S11') """) @@ -2078,6 +2089,8 @@ add_newdoc('numpy.core', 'einsum', array([ 30, 80, 130, 180, 230]) >>> np.dot(a, b) array([ 30, 80, 130, 180, 230]) + >>> np.einsum('...j,j', a, b) + array([ 30, 80, 130, 180, 230]) >>> np.einsum('ji', c) array([[0, 3], @@ -2147,6 +2160,18 @@ add_newdoc('numpy.core', 'einsum', [ 4796., 5162.], [ 4928., 5306.]]) + >>> a = np.arange(6).reshape((3,2)) + >>> b = np.arange(12).reshape((4,3)) + >>> np.einsum('ki,jk->ij', a, b) + array([[10, 28, 46, 64], + [13, 40, 67, 94]]) + >>> np.einsum('ki,...k->i...', a, b) + array([[10, 28, 46, 64], + [13, 40, 67, 94]]) + >>> np.einsum('k...,jk', a, b) + array([[10, 28, 46, 64], + [13, 40, 67, 94]]) + """) add_newdoc('numpy.core', 'alterdot', @@ -3053,7 +3078,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('argsort', add_newdoc('numpy.core.multiarray', 'ndarray', ('argpartition', """ - a.argpartition(kth, axis=-1, kind='quickselect', order=None) + a.argpartition(kth, axis=-1, kind='introselect', order=None) Returns the indices that would partition this array. @@ -3112,6 +3137,13 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('astype', is a new array of the same shape as the input array, with dtype, order given by `dtype`, `order`. + Notes + ----- + Starting in NumPy 1.9, astype method now returns an error if the string + dtype to cast to is not long enough in 'safe' casting mode to hold the max + value of integer/float array that is being casted. Previously the casting + was allowed even if the result was truncated. + Raises ------ ComplexWarning @@ -4372,7 +4404,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('tofile', 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 @@ -4426,8 +4458,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('tolist', """)) -add_newdoc('numpy.core.multiarray', 'ndarray', ('tostring', - """ +tobytesdoc = """ a.tostring(order='C') Construct a Python string containing the raw data bytes in the array. @@ -4438,9 +4469,11 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('tostring', 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. @@ -4452,15 +4485,23 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('tostring', 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', """ @@ -4652,45 +4693,6 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('view', # ############################################################################## -add_newdoc('numpy.core.umath', 'frexp', - """ - Return normalized fraction and exponent of 2 of input array, element-wise. - - Returns (`out1`, `out2`) from equation ``x` = out1 * 2**out2``. - - Parameters - ---------- - x : array_like - Input array. - - Returns - ------- - (out1, out2) : tuple of ndarrays, (float, int) - `out1` is a float array with values between -1 and 1. - `out2` is an int array which represent the exponent of 2. - - See Also - -------- - ldexp : Compute ``y = x1 * 2**x2``, the inverse of `frexp`. - - Notes - ----- - Complex dtypes are not supported, they will raise a TypeError. - - Examples - -------- - >>> x = np.arange(9) - >>> y1, y2 = np.frexp(x) - >>> y1 - array([ 0. , 0.5 , 0.5 , 0.75 , 0.5 , 0.625, 0.75 , 0.875, - 0.5 ]) - >>> y2 - array([0, 1, 2, 2, 3, 3, 3, 3, 4]) - >>> y1 * 2**y2 - array([ 0., 1., 2., 3., 4., 5., 6., 7., 8.]) - - """) - add_newdoc('numpy.core.umath', 'frompyfunc', """ frompyfunc(func, nin, nout) @@ -4731,44 +4733,6 @@ add_newdoc('numpy.core.umath', 'frompyfunc', """) -add_newdoc('numpy.core.umath', 'ldexp', - """ - Compute y = x1 * 2**x2. - - Parameters - ---------- - x1 : array_like - The array of multipliers. - x2 : array_like - The array of exponents. - - Returns - ------- - y : array_like - The output array, the result of ``x1 * 2**x2``. - - See Also - -------- - frexp : Return (y1, y2) from ``x = y1 * 2**y2``, the inverse of `ldexp`. - - Notes - ----- - Complex dtypes are not supported, they will raise a TypeError. - - `ldexp` is useful as the inverse of `frexp`, if used by itself it is - more clear to simply use the expression ``x1 * 2**x2``. - - Examples - -------- - >>> np.ldexp(5, np.arange(4)) - array([ 5., 10., 20., 40.], dtype=float32) - - >>> x = np.arange(6) - >>> np.ldexp(*np.frexp(x)) - array([ 0., 1., 2., 3., 4., 5.]) - - """) - add_newdoc('numpy.core.umath', 'geterrobj', """ geterrobj() @@ -5672,12 +5636,13 @@ add_newdoc('numpy.core', 'ufunc', ('reduceat', ``ufunc.reduce(a[indices[i]:indices[i+1]])``, which becomes the i-th generalized "row" parallel to `axis` in the final result (i.e., in a 2-D array, for example, if `axis = 0`, it becomes the i-th row, but if - `axis = 1`, it becomes the i-th column). There are two exceptions to this: + `axis = 1`, it becomes the i-th column). There are three exceptions to this: - * when ``i = len(indices) - 1`` (so for the last index), - ``indices[i+1] = a.shape[axis]``. - * if ``indices[i] >= indices[i + 1]``, the i-th generalized "row" is - simply ``a[indices[i]]``. + * when ``i = len(indices) - 1`` (so for the last index), + ``indices[i+1] = a.shape[axis]``. + * if ``indices[i] >= indices[i + 1]``, the i-th generalized "row" is + simply ``a[indices[i]]``. + * if ``indices[i] >= len(a)`` or ``indices[i] < 0``, an error is raised. The shape of the output depends on the size of `indices`, and may be larger than `a` (this happens if ``len(indices) > a.shape[axis]``). @@ -5836,6 +5801,8 @@ add_newdoc('numpy.core', 'ufunc', ('at', increment the first element once because of buffering, whereas `add.at(a, [0,0], 1)` will increment the first element twice. + .. versionadded:: 1.8.0 + Parameters ---------- a : array_like @@ -6151,7 +6118,19 @@ add_newdoc('numpy.core.multiarray', 'dtype', ('itemsize', add_newdoc('numpy.core.multiarray', 'dtype', ('kind', """ - A character code (one of 'biufcSUV') identifying the general kind of data. + A character code (one of 'biufcOSUV') identifying the general kind of data. + + = ====================== + b boolean + i signed integer + u unsigned integer + f floating-point + c complex floating-point + O object + S (byte-)string + U Unicode + V void + = ====================== """)) |