8000 DOC: Documentation fixes by madphysicist · Pull Request #7415 · numpy/numpy · GitHub
[go: up one dir, main page]
Skip to content

DOC: Documentation fixes #7415

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 14, 2016
Merged

DOC: Documentation fixes #7415

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7a4ff44
DOC: Updates to documentation from perusing it in detail.
madphysicist Feb 24, 2016
133e892
MAINT: Wrapped some docstrings and fixed typo
madphysicist Mar 4, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions doc/source/_static/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion doc/source/reference/c-api.array.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
85 changes: 44 additions & 41 deletions doc/source/reference/c-api.types-and-structures.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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]*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

Expand Down Expand Up @@ -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 *`.


Expand Down Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -1003,18 +1006,18 @@ 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
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
Expand All @@ -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

Expand All @@ -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

Expand Down
119 changes: 61 additions & 58 deletions numpy/core/fromnumeric.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------
Expand Down Expand Up @@ -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

Expand All @@ -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
-------
Expand All @@ -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
Expand All @@ -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
--------
Expand All @@ -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

Expand All @@ -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
--------
Expand Down
0