Skip to content

Commit

Permalink
DOC: Refactor description of PyArray_FromAny/PyArray_CheckFromAny
Browse files Browse the repository at this point in the history 
Fixed incorrectly indented and duplicated documents
while preserving internal links.
  • Loading branch information
@F3eQnxN3RriK
F3eQnxN3RriK committed Aug 4, 2023
1 parent 09dac65 commit e3e8cf2
Showing 1 changed file with 65 additions and 113 deletions.
178 changes: 65 additions & 113 deletions doc/source/reference/c-api/array.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -435,45 +435,37 @@ From other objects
have :c:data:`NPY_ARRAY_DEFAULT` as its flags member. The *context*
argument is unused.
.. c:macro:: NPY_ARRAY_C_CONTIGUOUS
:c:macro:`NPY_ARRAY_C_CONTIGUOUS`
Make sure the returned array is C-style contiguous
.. c:macro:: NPY_ARRAY_F_CONTIGUOUS
:c:macro:`NPY_ARRAY_F_CONTIGUOUS`
Make sure the returned array is Fortran-style contiguous.
.. c:macro:: NPY_ARRAY_ALIGNED
:c:macro:`NPY_ARRAY_ALIGNED`
Make sure the returned array is aligned on proper boundaries for its
data type. An aligned array has the data pointer and every strides
factor as a multiple of the alignment factor for the data-type-
descriptor.
.. c:macro:: NPY_ARRAY_WRITEABLE
:c:macro:`NPY_ARRAY_WRITEABLE`
Make sure the returned array can be written to.
.. c:macro:: NPY_ARRAY_ENSURECOPY
:c:macro:`NPY_ARRAY_ENSURECOPY`
Make sure a copy is made of *op*. If this flag is not
present, data is not copied if it can be avoided.
.. c:macro:: NPY_ARRAY_ENSUREARRAY
:c:macro:`NPY_ARRAY_ENSUREARRAY`
Make sure the result is a base-class ndarray. By
default, if *op* is an instance of a subclass of
ndarray, an instance of that same subclass is returned. If
this flag is set, an ndarray object will be returned instead.
.. c:macro:: NPY_ARRAY_FORCECAST
:c:macro:`NPY_ARRAY_FORCECAST`
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 raised.
.. c:macro:: NPY_ARRAY_WRITEBACKIFCOPY
:c:macro:`NPY_ARRAY_WRITEBACKIFCOPY`
If *op* is already an array, but does not satisfy the
requirements, then a copy is made (which will satisfy the
requirements). If this flag is present and a copy (of an object
Expand All @@ -485,68 +477,7 @@ From other objects
will be made writeable again. If *op* is not writeable to begin
with, or if it is not already an array, then an error is raised.
.. c:macro:: NPY_ARRAY_BEHAVED
:c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEABLE`
.. c:macro:: NPY_ARRAY_CARRAY
:c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_BEHAVED`
.. c:macro:: NPY_ARRAY_CARRAY_RO
:c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED`
.. c:macro:: NPY_ARRAY_FARRAY
:c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_BEHAVED`
.. c:macro:: NPY_ARRAY_FARRAY_RO
:c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED`
.. c:macro:: NPY_ARRAY_DEFAULT
:c:data:`NPY_ARRAY_CARRAY`
..
dedented to allow internal linking, pending a refactoring
.. c:macro:: NPY_ARRAY_IN_ARRAY
:c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED`
.. c:macro:: NPY_ARRAY_IN_FARRAY
:c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED`
.. c:macro:: NPY_OUT_ARRAY
:c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_WRITEABLE` \|
:c:data:`NPY_ARRAY_ALIGNED`
.. c:macro:: NPY_ARRAY_OUT_ARRAY
:c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED` \|
:c:data:`NPY_ARRAY_WRITEABLE`
.. c:macro:: NPY_ARRAY_OUT_FARRAY
:c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_WRITEABLE` \|
:c:data:`NPY_ARRAY_ALIGNED`
..
dedented to allow internal linking, pending a refactoring
.. c:macro:: NPY_ARRAY_INOUT_ARRAY
:c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_WRITEABLE` \|
:c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEBACKIFCOPY`
.. c:macro:: NPY_ARRAY_INOUT_FARRAY
:c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_WRITEABLE` \|
:c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEBACKIFCOPY`
`Combinations of array flags`_ can also be added.
.. c:function:: PyObject* PyArray_CheckFromAny( \
PyObject* op, PyArray_Descr* dtype, int min_depth, int max_depth, \
Expand All @@ -558,37 +489,6 @@ From other objects
indicates that the array should be aligned in the sense that the
strides are multiples of the element size.
In versions 1.6 and earlier of NumPy, the following flags
did not have the _ARRAY_ macro namespace in them. That form
of the constant names is deprecated in 1.7.
..
dedented to allow internal linking, pending a refactoring
.. c:macro:: NPY_ARRAY_NOTSWAPPED
Make sure the returned array has a data-type descriptor that is in
machine byte-order, over-riding any specification in the *dtype*
argument. Normally, the byte-order requirement is determined by
the *dtype* argument. If this flag is set and the dtype argument
does not indicate a machine byte-order descriptor (or is NULL and
the object is already an array with a data-type descriptor that is
not in machine byte- order), then a new data-type descriptor is
created and used with its byte-order field set to native.
.. c:macro:: NPY_ARRAY_BEHAVED_NS
:c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEABLE` \|
:c:data:`NPY_ARRAY_NOTSWAPPED`
..
dedented to allow internal linking, pending a refactoring
.. c:macro:: NPY_ARRAY_ELEMENTSTRIDES
Make sure the returned array has strides that are multiples of the
element size.
.. c:function:: PyObject* PyArray_FromArray( \
PyArrayObject* op, PyArray_Descr* newtype, int requirements)
Expand Down Expand Up @@ -1377,6 +1277,10 @@ a certain kind of array (like :c:data:`NPY_ARRAY_C_CONTIGUOUS` and
:c:data:`NPY_ARRAY_BEHAVED`), then pass these requirements into the
PyArray_FromAny function.
In versions 1.6 and earlier of NumPy, the following flags
did not have the _ARRAY_ macro namespace in them. That form
of the constant names is deprecated in 1.7.
Basic Array Flags
~~~~~~~~~~~~~~~~~
Expand All @@ -1389,10 +1293,6 @@ might not be writeable. It might be in Fortran-contiguous order. The
array flags are used to indicate what can be said about data
associated with an array.
In versions 1.6 and earlier of NumPy, the following flags
did not have the _ARRAY_ macro namespace in them. That form
of the constant names is deprecated in 1.7.
.. c:macro:: NPY_ARRAY_C_CONTIGUOUS
The data area is in C-style contiguous order (last index varies the
Expand Down Expand Up @@ -1488,6 +1388,34 @@ Combinations of array flags
:c:data:`NPY_ARRAY_CARRAY`
.. c:macro:: NPY_ARRAY_IN_ARRAY
:c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED`
.. c:macro:: NPY_ARRAY_IN_FARRAY
:c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED`
.. c:macro:: NPY_ARRAY_OUT_ARRAY
:c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_WRITEABLE` \|
:c:data:`NPY_ARRAY_ALIGNED`
.. c:macro:: NPY_ARRAY_OUT_FARRAY
:c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_WRITEABLE` \|
:c:data:`NPY_ARRAY_ALIGNED`
.. c:macro:: NPY_ARRAY_INOUT_ARRAY
:c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_WRITEABLE` \|
:c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEBACKIFCOPY`
.. c:macro:: NPY_ARRAY_INOUT_FARRAY
:c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_WRITEABLE` \|
:c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEBACKIFCOPY`
.. c:macro:: NPY_ARRAY_UPDATE_ALL
:c:data:`NPY_ARRAY_C_CONTIGUOUS` \| :c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_ALIGNED`
Expand All @@ -1512,6 +1440,30 @@ specify desired properties of the new array.
Make sure the resulting object is an actual ndarray, and not a sub-class.
These constants are used in :c:func:`PyArray_CheckFromAny` (and its macro forms)
to specify desired properties of the new array.
.. c:macro:: NPY_ARRAY_NOTSWAPPED
Make sure the returned array has a data-type descriptor that is in
machine byte-order, over-riding any specification in the *dtype*
argument. Normally, the byte-order requirement is determined by
the *dtype* argument. If this flag is set and the dtype argument
does not indicate a machine byte-order descriptor (or is NULL and
the object is already an array with a data-type descriptor that is
not in machine byte- order), then a new data-type descriptor is
created and used with its byte-order field set to native.
.. c:macro:: NPY_ARRAY_BEHAVED_NS
:c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEABLE` \|
:c:data:`NPY_ARRAY_NOTSWAPPED`
.. c:macro:: NPY_ARRAY_ELEMENTSTRIDES
Make sure the returned array has strides that are multiples of the
element size.
Flag checking
~~~~~~~~~~~~~
Expand Down

0 comments on commit e3e8cf2

Please sign in to comment.