From 7a4ff44b056eb8f8a53fbc196ef53666523bfca3 Mon Sep 17 00:00:00 2001 From: Joseph Fox-Rabinovitz Date: Tue, 23 Feb 2016 19:23:47 -0500 Subject: [PATCH 1/2] DOC: Updates to documentation from perusing it in detail. [ci skip] --- doc/source/reference/c-api.array.rst | 2 +- doc/source/reference/c-api.types-and-structures.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst index aba5f9caa86f..049c7b5379f1 100644 --- a/doc/source/reference/c-api.array.rst +++ b/doc/source/reference/c-api.array.rst @@ -421,7 +421,7 @@ From other objects Force a cast to the output type even if it cannot be done safely. Without this flag, a data cast will occur only if it - can be done safely, otherwise an error is reaised. + can be done safely, otherwise an error is raised. .. c:var:: NPY_ARRAY_UPDATEIFCOPY diff --git a/doc/source/reference/c-api.types-and-structures.rst b/doc/source/reference/c-api.types-and-structures.rst index c5165fef3c6f..38f1acb60105 100644 --- a/doc/source/reference/c-api.types-and-structures.rst +++ b/doc/source/reference/c-api.types-and-structures.rst @@ -871,8 +871,8 @@ PyArrayIter_Type .. c:member:: npy_intp *PyArrayIterObject.backstrides How many bytes needed to jump from the end of a dimension back - to its beginning. Note that *backstrides* [k]= *strides* [k]*d - *ims_m1* [k], but it is stored here as an optimization. + to its beginning. Note that `backstrides`[k]= `strides`[k] * + `dims_m1`[k], but it is stored here as an optimization. .. c:member:: npy_intp *PyArrayIterObject.factors From 133e8927eb6d8f4855fc13013d82c8be4900304e Mon Sep 17 00:00:00 2001 From: Joseph Fox-Rabinovitz Date: Thu, 3 Mar 2016 23:04:24 -0500 Subject: [PATCH 2/2] MAINT: Wrapped some docstrings and fixed typo --- doc/source/_static/.gitignore | 2 + .../reference/c-api.types-and-structures.rst | 85 +++++++------ numpy/core/fromnumeric.py | 119 +++++++++--------- 3 files changed, 107 insertions(+), 99 deletions(-) create mode 100644 doc/source/_static/.gitignore diff --git a/doc/source/_static/.gitignore b/doc/source/_static/.gitignore new file mode 100644 index 000000000000..60da04706174 --- /dev/null +++ b/doc/source/_static/.gitignore @@ -0,0 +1,2 @@ +# This file is here to avoid a sphinx warning about a missing _static folder. +# Empty folders are not allowed into git. diff --git a/doc/source/reference/c-api.types-and-structures.rst b/doc/source/reference/c-api.types-and-structures.rst index 38f1acb60105..7f0fd9f635bb 100644 --- a/doc/source/reference/c-api.types-and-structures.rst +++ b/doc/source/reference/c-api.types-and-structures.rst @@ -711,9 +711,10 @@ PyUFunc_Type .. c:member:: int PyUFuncObject.identity - Either :c:data:`PyUFunc_One`, :c:data:`PyUFunc_Zero`, or - :c:data:`PyUFunc_None` to indicate the identity for this operation. - It is only used for a reduce-like call on an empty array. + Either :c:data:`PyUFunc_One`, :c:data:`PyUFunc_Zero`, + :c:data:`PyUFunc_None` or :c:data:`PyUFunc_AllOnes` to indicate + the identity for this operation. It is only used for a + reduce-like call on an empty array. .. c:member:: void PyUFuncObject.functions(char** args, npy_intp* dims, npy_intp* steps, void* extradata) @@ -745,8 +746,8 @@ PyUFunc_Type .. c:member:: int PyUFuncObject.ntypes The number of supported data types for the ufunc. This number - specifies how many different 1-d loops (of the builtin data types) are - available. + specifies how many different 1-d loops (of the builtin data + types) are available. .. c:member:: char *PyUFuncObject.name @@ -755,7 +756,7 @@ PyUFunc_Type .. c:member:: char *PyUFuncObject.types - An array of *nargs* :math:`\times` *ntypes* 8-bit type_numbers + An array of :math:`nargs \times ntypes` 8-bit type_numbers which contains the type signature for the function for each of the supported (builtin) data types. For each of the *ntypes* functions, the corresponding set of type numbers in this array @@ -771,9 +772,9 @@ PyUFunc_Type .. c:member:: void *PyUFuncObject.ptr - Any dynamically allocated memory. Currently, this is used for dynamic - ufuncs created from a python function to store room for the types, - data, and name members. + Any dynamically allocated memory. Currently, this is used for + dynamic ufuncs created from a python function to store room for + the types, data, and name members. .. c:member:: PyObject *PyUFuncObject.obj @@ -782,10 +783,11 @@ PyUFunc_Type .. c:member:: PyObject *PyUFuncObject.userloops - A dictionary of user-defined 1-d vector loops (stored as CObject ptrs) - for user-defined types. A loop may be registered by the user for any - user-defined type. It is retrieved by type number. User defined type - numbers are always larger than :c:data:`NPY_USERDEF`. + A dictionary of user-defined 1-d vector loops (stored as CObject + ptrs) for user-defined types. A loop may be registered by the + user for any user-defined type. It is retrieved by type number. + User defined type numbers are always larger than + :c:data:`NPY_USERDEF`. .. c:member:: npy_uint32 PyUFuncObject.op_flags @@ -801,14 +803,15 @@ PyArrayIter_Type .. c:var: PyArrayIter_Type - This is an iterator object that makes it easy to loop over an N-dimensional - array. It is the object returned from the flat attribute of an - ndarray. It is also used extensively throughout the implementation - internals to loop over an N-dimensional array. The tp_as_mapping - interface is implemented so that the iterator object can be indexed - (using 1-d indexing), and a few methods are implemented through the - tp_methods table. This object implements the next method and can be - used anywhere an iterator can be used in Python. + This is an iterator object that makes it easy to loop over an + N-dimensional array. It is the object returned from the flat + attribute of an ndarray. It is also used extensively throughout the + implementation internals to loop over an N-dimensional array. The + tp_as_mapping interface is implemented so that the iterator object + can be indexed (using 1-d indexing), and a few methods are + implemented through the tp_methods table. This object implements the + next method and can be used anywhere an iterator can be used in + Python. .. c:type:: PyArrayIterObject @@ -871,8 +874,8 @@ PyArrayIter_Type .. c:member:: npy_intp *PyArrayIterObject.backstrides How many bytes needed to jump from the end of a dimension back - to its beginning. Note that `backstrides`[k]= `strides`[k] * - `dims_m1`[k], but it is stored here as an optimization. + to its beginning. Note that ``backstrides[k] == strides[k] * + dims_m1[k]``, but it is stored here as an optimization. .. c:member:: npy_intp *PyArrayIterObject.factors @@ -900,8 +903,8 @@ How to use an array iterator on a C-level is explained more fully in later sections. Typically, you do not need to concern yourself with the internal structure of the iterator object, and merely interact with it through the use of the macros :c:func:`PyArray_ITER_NEXT` (it), -:c:func:`PyArray_ITER_GOTO` (it, dest), or :c:func:`PyArray_ITER_GOTO1D` (it, -index). All of these macros require the argument *it* to be a +:c:func:`PyArray_ITER_GOTO` (it, dest), or :c:func:`PyArray_ITER_GOTO1D` +(it, index). All of these macros require the argument *it* to be a :c:type:`PyArrayIterObject *`. @@ -938,8 +941,8 @@ PyArrayMultiIter_Type .. c:macro: PyArrayMultiIterObject.PyObject_HEAD - Needed at the start of every Python object (holds reference count and - type identification). + Needed at the start of every Python object (holds reference count + and type identification). .. c:member:: int PyArrayMultiIterObject.numiter @@ -963,17 +966,17 @@ PyArrayMultiIter_Type .. c:member:: PyArrayIterObject **PyArrayMultiIterObject.iters - An array of iterator objects that holds the iterators for the arrays - to be broadcast together. On return, the iterators are adjusted for - broadcasting. + An array of iterator objects that holds the iterators for the + arrays to be broadcast together. On return, the iterators are + adjusted for broadcasting. PyArrayNeighborhoodIter_Type ---------------------------- .. c:var: PyArrayNeighborhoodIter_Type - This is an iterator object that makes it easy to loop over an N-dimensional - neighborhood. + This is an iterator object that makes it easy to loop over an + N-dimensional neighborhood. .. c:type:: PyArrayNeighborhoodIterObject @@ -1003,8 +1006,8 @@ are :c:data:`Py{TYPE}ArrType_Type` where ``{TYPE}`` can be **Bool**, **Byte**, **Short**, **Int**, **Long**, **LongLong**, **UByte**, **UShort**, **UInt**, **ULong**, **ULongLong**, - **Half**, **Float**, **Double**, **LongDouble**, **CFloat**, **CDouble**, - **CLongDouble**, **String**, **Unicode**, **Void**, and + **Half**, **Float**, **Double**, **LongDouble**, **CFloat**, + **CDouble**, **CLongDouble**, **String**, **Unicode**, **Void**, and **Object**. These type names are part of the C-API and can therefore be created in @@ -1012,9 +1015,9 @@ extension C-code. There is also a :c:data:`PyIntpArrType_Type` and a :c:data:`PyUIntpArrType_Type` that are simple substitutes for one of the integer types that can hold a pointer on the platform. The structure of these scalar objects is not exposed to C-code. The function -:c:func:`PyArray_ScalarAsCtype` (..) can be used to extract the C-type value -from the array scalar and the function :c:func:`PyArray_Scalar` (...) can be -used to construct an array scalar from a C-value. +:c:func:`PyArray_ScalarAsCtype` (..) can be used to extract the C-type +value from the array scalar and the function :c:func:`PyArray_Scalar` +(...) can be used to construct an array scalar from a C-value. Other C-Structures @@ -1032,8 +1035,8 @@ PyArray_Dims .. c:type:: PyArray_Dims - This structure is very useful when shape and/or strides information is - supposed to be interpreted. The structure is: + This structure is very useful when shape and/or strides information + is supposed to be interpreted. The structure is: .. code-block:: c @@ -1046,8 +1049,8 @@ PyArray_Dims .. c:member:: npy_intp *PyArray_Dims.ptr - A pointer to a list of (:c:type:`npy_intp`) integers which usually - represent array shape or array strides. + A pointer to a list of (:c:type:`npy_intp`) integers which + usually represent array shape or array strides. .. c:member:: int PyArray_Dims.len diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py index 52a15e30d7d1..ed5e2410abfb 100644 --- a/numpy/core/fromnumeric.py +++ b/numpy/core/fromnumeric.py @@ -135,20 +135,21 @@ def reshape(a, newshape, order='C'): newshape : int or tuple of ints The new shape should be compatible with the original shape. If an integer, then the result will be a 1-D array of that length. - One shape dimension can be -1. In this case, the value is inferred - from the length of the array and remaining dimensions. + One shape dimension can be -1. In this case, the value is + inferred from the length of the array and remaining dimensions. order : {'C', 'F', 'A'}, optional - Read the elements of `a` using this index order, and place the elements - into the reshaped array using this index order. 'C' means to - read / write the elements using C-like index order, with the last axis - index changing fastest, back to the first axis index changing slowest. - 'F' means to read / write the elements using Fortran-like index order, - with the first index changing fastest, and the last index changing - slowest. - Note that the 'C' and 'F' options take no account of the memory layout - of the underlying array, and only refer to the order of indexing. 'A' - means to read / write the elements in Fortran-like index order if `a` - is Fortran *contiguous* in memory, C-like order otherwise. + Read the elements of `a` using this index order, and place the + elements into the reshaped array using this index order. 'C' + means to read / write the elements using C-like index order, + with the last axis index changing fastest, back to the first + axis index changing slowest. 'F' means to read / write the + elements using Fortran-like index order, with the first index + changing fastest, and the last index changing slowest. Note that + the 'C' and 'F' options take no account of the memory layout of + the underlying array, and only refer to the order of indexing. + 'A' means to read / write the elements in Fortran-like index + order if `a` is Fortran *contiguous* in memory, C-like order + otherwise. Returns ------- @@ -560,11 +561,12 @@ def partition(a, kth, axis=-1, kind='introselect', order=None): """ Return a partitioned copy of an array. - Creates a copy of the array with its elements rearranged in such a way that - the value of the element in kth position is in the position it would be in - a sorted array. All elements smaller than the kth element are moved before - this element and all equal or greater are moved behind it. The ordering of - the elements in the two partitions is undefined. + Creates a copy of the array with its elements rearranged in such a + way that the value of the element in k-th position is in the + position it would be in a sorted array. All elements smaller than + the k-th element are moved before this element and all equal or + greater are moved behind it. The ordering of the elements in the two + partitions is undefined. .. versionadded:: 1.8.0 @@ -573,23 +575,23 @@ def partition(a, kth, axis=-1, kind='introselect', order=None): a : array_like Array to be sorted. kth : int or sequence of ints - Element index to partition by. The kth value of the element will be in - its final sorted position and all smaller elements will be moved before - it and all equal or greater elements behind it. - The order all elements in the partitions is undefined. - If provided with a sequence of kth it will partition all elements - indexed by kth of them into their sorted position at once. + Element index to partition by. The k-th value of the element + will be in its final sorted position and all smaller elements + will be moved before it and all equal or greater elements behind + it. The order all elements in the partitions is undefined. If + provided with a sequence of k-th it will partition all elements + indexed by k-th of them into their sorted position at once. axis : int or None, optional Axis along which to sort. If None, the array is flattened before sorting. The default is -1, which sorts along the last axis. kind : {'introselect'}, optional Selection algorithm. Default is 'introselect'. order : str or list of str, optional - When `a` is an array with fields defined, this argument specifies - which fields to compare first, second, etc. A single field can - be specified as a string. Not all fields need be specified, but - unspecified fields will still be used, in the order in which they - come up in the dtype, to break ties. + When `a` is an array with fields defined, this argument + specifies which fields to compare first, second, etc. A single + field can be specified as a string. Not all fields need be + specified, but unspecified fields will still be used, in the + order in which they come up in the dtype, to break ties. Returns ------- @@ -604,10 +606,11 @@ def partition(a, kth, axis=-1, kind='introselect', order=None): Notes ----- - The various selection algorithms are characterized by their average speed, - worst case performance, work space size, and whether they are stable. A - stable sort keeps items with the same key in the same relative order. The - available algorithms have the following properties: + The various selection algorithms are characterized by their average + speed, worst case performance, work space size, and whether they are + stable. A stable sort keeps items with the same key in the same + relative order. The available algorithms have the following + properties: ================= ======= ============= ============ ======= kind speed worst case work space stable @@ -616,14 +619,14 @@ def partition(a, kth, axis=-1, kind='introselect', order=None): ================= ======= ============= ============ ======= All the partition algorithms make temporary copies of the data when - partitioning along any but the last axis. Consequently, partitioning - along the last axis is faster and uses less space than partitioning - along any other axis. + partitioning along any but the last axis. Consequently, + partitioning along the last axis is faster and uses less space than + partitioning along any other axis. - The sort order for complex numbers is lexicographic. If both the real - and imaginary parts are non-nan then the order is determined by the - real parts except when they are equal, in which case the order is - determined by the imaginary parts. + The sort order for complex numbers is lexicographic. If both the + real and imaginary parts are non-nan then the order is determined by + the real parts except when they are equal, in which case the order + is determined by the imaginary parts. Examples -------- @@ -646,10 +649,10 @@ def partition(a, kth, axis=-1, kind='introselect', order=None): def argpartition(a, kth, axis=-1, kind='introselect', order=None): """ - Perform an indirect partition along the given axis using the algorithm - specified by the `kind` keyword. It returns an array of indices of the - same shape as `a` that index data along the given axis in partitioned - order. + Perform an indirect partition along the given axis using the + algorithm specified by the `kind` keyword. It returns an array of + indices of the same shape as `a` that index data along the given + axis in partitioned order. .. versionadded:: 1.8.0 @@ -658,29 +661,29 @@ def argpartition(a, kth, axis=-1, kind='introselect', order=None): a : array_like Array to sort. kth : int or sequence of ints - Element index to partition by. The kth element will be in its final - sorted position and all smaller elements will be moved before it and - all larger elements behind it. - The order all elements in the partitions is undefined. - If provided with a sequence of kth it will partition all of them into - their sorted position at once. + Element index to partition by. The k-th element will be in its + final sorted position and all smaller elements will be moved + before it and all larger elements behind it. The order all + elements in the partitions is undefined. If provided with a + sequence of k-th it will partition all of them into their sorted + position at once. axis : int or None, optional - Axis along which to sort. The default is -1 (the last axis). If None, - the flattened array is used. + Axis along which to sort. The default is -1 (the last axis). If + None, the flattened array is used. kind : {'introselect'}, optional Selection algorithm. Default is 'introselect' order : str or list of str, optional - When `a` is an array with fields defined, this argument specifies - which fields to compare first, second, etc. A single field can - be specified as a string, and not all fields need be specified, - but unspecified fields will still be used, in the order in which - they come up in the dtype, to break ties. + When `a` is an array with fields defined, this argument + specifies which fields to compare first, second, etc. A single + field can be specified as a string, and not all fields need be + specified, but unspecified fields will still be used, in the + order in which they come up in the dtype, to break ties. Returns ------- index_array : ndarray, int Array of indices that partition `a` along the specified axis. - In other words, ``a[index_array]`` yields a sorted `a`. + In other words, ``a[index_array]`` yields a partitioned `a`. See Also --------