diff options
| -rw-r--r-- | numpy/add_newdocs.py | 110 | ||||
| -rw-r--r-- | numpy/core/getlimits.py | 38 | ||||
| -rw-r--r-- | numpy/core/numeric.py | 10 | ||||
| -rw-r--r-- | numpy/core/numerictypes.py | 70 | ||||
| -rw-r--r-- | numpy/core/shape_base.py | 14 |
5 files changed, 173 insertions, 69 deletions
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 62e656346..c631fe3d0 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -284,6 +284,36 @@ add_newdoc('numpy.core', 'broadcast', ('size', """)) +add_newdoc('numpy.core', 'broadcast', ('reset', + """ + reset() + + Reset the broadcasted result's iterator(s). + + Parameters + ---------- + None + + Returns + ------- + None + + Examples + -------- + >>> x = np.array([1, 2, 3]) + >>> y = np.array([[4], [5], [6]] + >>> b = np.broadcast(x, y) + >>> b.index + 0 + >>> b.next(), b.next(), b.next() + ((1, 4), (2, 4), (3, 4)) + >>> b.index + 3 + >>> b.reset() + >>> b.index + 0 + + """)) ############################################################################### # @@ -330,6 +360,15 @@ add_newdoc('numpy.core.multiarray', 'array', array should have. Ones will be pre-pended to the shape as needed to meet this requirement. + Returns + ------- + out : ndarray + An array object satisfying the specified requirements. + + See Also + -------- + empty, empty_like, zeros, zeros_like, ones, ones_like, fill + Examples -------- >>> np.array([1, 2, 3]) @@ -574,28 +613,29 @@ add_newdoc('numpy.core.multiarray', 'fromstring', """ fromstring(string, dtype=float, count=-1, sep='') - Return a new 1-D array initialized from raw binary or text data in string. + A new 1-D array initialized from raw binary or text data in a string. Parameters ---------- string : str A string containing the data. - dtype : dtype, optional - The data type of the array. For binary input data, the data must be - in exactly this format. + dtype : data-type, optional + The data type of the array; default: float. For binary input data, + the data must be in exactly this format. count : int, optional - Read this number of `dtype` elements from the data. If this is - negative, then the size will be determined from the length of the - data. + Read this number of `dtype` elements from the data. If this is + negative (the default), the count will be determined from the + length of the data. sep : str, optional - If provided and not empty, then the data will be interpreted as - ASCII text with decimal numbers. This argument is interpreted as the - string separating numbers in the data. Extra whitespace between - elements is also ignored. + If not provided or, equivalently, the empty string, the data will + be interpreted as binary data; otherwise, as ASCII text with + decimal numbers. Also in this latter case, this argument is + interpreted as the string separating numbers in the data; extra + whitespace between elements is also ignored. Returns ------- - arr : array + arr : ndarray The constructed array. Raises @@ -604,6 +644,10 @@ add_newdoc('numpy.core.multiarray', 'fromstring', If the string is not the correct size to satisfy the requested `dtype` and `count`. + See Also + -------- + frombuffer, fromfile, fromiter + Examples -------- >>> np.fromstring('\\x01\\x02', dtype=np.uint8) @@ -615,17 +659,6 @@ add_newdoc('numpy.core.multiarray', 'fromstring', >>> np.fromstring('\\x01\\x02\\x03\\x04\\x05', dtype=np.uint8, count=3) array([1, 2, 3], dtype=uint8) - Invalid inputs: - - >>> np.fromstring('\\x01\\x02\\x03\\x04\\x05', dtype=np.int32) - Traceback (most recent call last): - File "<stdin>", line 1, in <module> - ValueError: string size must be a multiple of element size - >>> np.fromstring('\\x01\\x02', dtype=np.uint8, count=3) - Traceback (most recent call last): - File "<stdin>", line 1, in <module> - ValueError: string is smaller than requested size - """) add_newdoc('numpy.core.multiarray', 'fromiter', @@ -639,9 +672,9 @@ add_newdoc('numpy.core.multiarray', 'fromiter', iterable : iterable object An iterable object providing data for the array. dtype : data-type - The data type of the returned array. + The data-type of the returned array. count : int, optional - The number of items to read from iterable. The default is -1, + The number of items to read from *iterable*. The default is -1, which means all data is read. Returns @@ -651,9 +684,8 @@ add_newdoc('numpy.core.multiarray', 'fromiter', Notes ----- - Specify ``count`` to improve performance. It allows - ``fromiter`` to pre-allocate the output array, instead of - resizing it on demand. + Specify `count` to improve performance. It allows ``fromiter`` to + pre-allocate the output array, instead of resizing it on demand. Examples -------- @@ -746,26 +778,26 @@ add_newdoc('numpy.core.multiarray', 'frombuffer', Parameters ---------- - buffer + buffer : buffer_like An object that exposes the buffer interface. dtype : data-type, optional - Data type of the returned array. + Data-type of the returned array; default: float. count : int, optional Number of items to read. ``-1`` means all data in the buffer. offset : int, optional - Start reading the buffer from this offset. + Start reading the buffer from this offset; default: 0. Notes ----- - If the buffer has data that is not in machine byte-order, this - should be specified as part of the data-type, e.g.:: + If the buffer has data that is not in machine byte-order, this should + be specified as part of the data-type, e.g.:: >>> dt = np.dtype(int) >>> dt = dt.newbyteorder('>') >>> np.frombuffer(buf, dtype=dt) - The data of the resulting array will not be byteswapped, - but will be interpreted correctly. + The data of the resulting array will not be byteswapped, but will be + interpreted correctly. Examples -------- @@ -1373,7 +1405,7 @@ add_newdoc('numpy.core.multiarray', 'result_type', like C++, with some slight differences. When both scalars and arrays are used, the array's type takes precedence and the actual value of the scalar is taken into account. - + For example, calculating 3*a, where a is an array of 32-bit floats, intuitively should result in a 32-bit float output. If the 3 is a 32-bit integer, the NumPy rules indicate it can't convert losslessly @@ -1536,12 +1568,12 @@ add_newdoc('numpy.core', 'einsum', The best way to understand this function is to try the examples below, which show how many common NumPy functions can be implemented as calls to einsum. - + The subscripts string is a comma-separated list of subscript labels, where each label refers to a dimension of the corresponding operand. Repeated subscripts labels in one operand take the diagonal. For example, ``np.einsum('ii', a)`` is equivalent to ``np.trace(a)``. - + Whenever a label is repeated, it is summed, so ``np.einsum('i,i', a, b)`` is equivalent to ``np.inner(a,b)``. If a label appears only once, it is not summed, so ``np.einsum('i', a)`` produces a view of ``a`` @@ -1607,7 +1639,7 @@ add_newdoc('numpy.core', 'einsum', -------- dot, inner, outer, tensordot - + Examples -------- diff --git a/numpy/core/getlimits.py b/numpy/core/getlimits.py index 198862d6a..ec1eec066 100644 --- a/numpy/core/getlimits.py +++ b/numpy/core/getlimits.py @@ -28,17 +28,19 @@ class finfo(object): Attributes ---------- eps : floating point number of the appropriate type - The smallest representable number such that ``1.0 + eps != 1.0``. + The smallest representable positive number such that + ``1.0 + eps != 1.0``. epsneg : floating point number of the appropriate type - The smallest representable number such that ``1.0 - epsneg != 1.0``. + The smallest representable positive number such that + ``1.0 - epsneg != 1.0``. iexp : int The number of bits in the exponent portion of the floating point representation. machar : MachAr - The object which calculated these parameters and holds more detailed - information. + The object which calculated these parameters and holds more + detailed information. machep : int - The exponent that yields ``eps``. + The exponent that yields `eps`. max : floating point number of the appropriate type The largest representable number. maxexp : int @@ -46,27 +48,27 @@ class finfo(object): min : floating point number of the appropriate type The smallest representable number, typically ``-max``. minexp : int - The most negative power of the base (2) consistent with there being - no leading 0's in the mantissa. + The most negative power of the base (2) consistent with there + being no leading 0's in the mantissa. negep : int - The exponent that yields ``epsneg``. + The exponent that yields `epsneg`. nexp : int The number of bits in the exponent including its sign and bias. nmant : int The number of bits in the mantissa. precision : int - The approximate number of decimal digits to which this kind of float - is precise. + The approximate number of decimal digits to which this kind of + float is precise. resolution : floating point number of the appropriate type - The approximate decimal resolution of this type, i.e. + The approximate decimal resolution of this type, i.e., ``10**-precision``. tiny : floating point number of the appropriate type - The smallest-magnitude usable number. + The smallest positive usable number. Parameters ---------- - dtype : floating point type, dtype, or instance - The kind of floating point data type to get information about. + dtype : floating point type, data-type, or instance + Kind of floating point data-type about which to get information. See Also -------- @@ -75,10 +77,10 @@ class finfo(object): Notes ----- - For developers of NumPy: do not instantiate this at the module level. The - initial calculation of these parameters is expensive and negatively impacts - import times. These objects are cached, so calling ``finfo()`` repeatedly - inside your functions is not a problem. + For developers of NumPy: do not instantiate this at the module level. + The initial calculation of these parameters is expensive and negatively + impacts import times. These objects are cached, so calling ``finfo()`` + repeatedly inside your functions is not a problem. """ diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py index fc935b4cb..fa9f19165 100644 --- a/numpy/core/numeric.py +++ b/numpy/core/numeric.py @@ -66,7 +66,7 @@ def zeros_like(a, dtype=None, order='K'): """ Return an array of zeros with the same shape and type as a given array. - With default paramters, is equivalent to ``a.copy().fill(0)``. + With default parameters, is equivalent to ``a.copy().fill(0)``. Parameters ---------- @@ -77,8 +77,8 @@ def zeros_like(a, dtype=None, order='K'): Overrides the data type of the result. order : {'C', 'F', 'A', or 'K'}, optional Overrides the memory layout of the result. '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 + '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. Returns @@ -763,7 +763,7 @@ def outer(a,b): See also -------- - numpy.inner, numpy.einsum + inner, einsum References ---------- @@ -855,7 +855,7 @@ def tensordot(a, b, axes=2): See Also -------- - numpy.dot, numpy.einsum + dot, einsum Notes ----- diff --git a/numpy/core/numerictypes.py b/numpy/core/numerictypes.py index 4c03bb2e0..9482257bc 100644 --- a/numpy/core/numerictypes.py +++ b/numpy/core/numerictypes.py @@ -601,6 +601,44 @@ def issctype(rep): return False def obj2sctype(rep, default=None): + """ + Return the scalar dtype or NumPy equivalent of Python type of an object. + + Parameters + ---------- + rep : any + The object of which the type is returned. + default : any, optional + If given, this is returned for objects whose types can not be + determined. If not given, None is returned for those objects. + + Returns + ------- + dtype : dtype or Python type + The data type of `rep`. + + See Also + -------- + sctype2char, issctype, issubsctype, issubdtype, maximum_sctype + + Examples + -------- + >>> np.obj2sctype(np.int32) + <type 'numpy.int32'> + >>> np.obj2sctype(np.array([1., 2.])) + <type 'numpy.float64'> + >>> np.obj2sctype(np.array([1.j])) + <type 'numpy.complex128'> + + >>> np.obj2sctype(dict) + <type 'numpy.object_'> + >>> np.obj2sctype('string') + <type 'numpy.string_'> + + >>> np.obj2sctype(1, default=list) + <type 'list'> + + """ try: if issubclass(rep, generic): return rep @@ -620,6 +658,38 @@ def obj2sctype(rep, default=None): def issubclass_(arg1, arg2): + """ + Determine if a class is a subclass of a second class. + + `issubclass_` is equivalent to the Python built-in ``issubclass``, + except that it returns False instead of raising a TypeError is one + of the arguments is not a class. + + Parameters + ---------- + arg1 : class + Input class. True is returned if `arg1` is a subclass of `arg2`. + arg2 : class or tuple of classes. + Input class. If a tuple of classes, True is returned if `arg1` is a + subclass of any of the tuple elements. + + Returns + ------- + out : bool + Whether `arg1` is a subclass of `arg2` or not. + + See Also + -------- + issubsctype, issubdtype, issctype + + Examples + -------- + >>> np.issubclass_(np.int32, np.int) + True + >>> np.issubclass_(np.int32, np.float) + False + + """ try: return issubclass(arg1, arg2) except TypeError: diff --git a/numpy/core/shape_base.py b/numpy/core/shape_base.py index 4c84cf397..15f188792 100644 --- a/numpy/core/shape_base.py +++ b/numpy/core/shape_base.py @@ -102,18 +102,18 @@ def atleast_3d(*arys): Parameters ---------- array1, array2, ... : array_like - One or more array-like sequences. Non-array inputs are converted - to arrays. Arrays that already have three or more dimensions are + One or more array-like sequences. Non-array inputs are converted to + arrays. Arrays that already have three or more dimensions are preserved. Returns ------- res1, res2, ... : ndarray - An array, or tuple of arrays, each with ``a.ndim >= 3``. - Copies are avoided where possible, and views with three or more - dimensions are returned. For example, a 1-D array of shape ``N`` - becomes a view of shape ``(1, N, 1)``. A 2-D array of shape ``(M, N)`` - becomes a view of shape ``(M, N, 1)``. + An array, or tuple of arrays, each with ``a.ndim >= 3``. Copies are + avoided where possible, and views with three or more dimensions are + returned. For example, a 1-D array of shape ``(N,)`` becomes a view + of shape ``(1, N, 1)``, and a 2-D array of shape ``(M, N)`` becomes a + view of shape ``(M, N, 1)``. See Also -------- |