diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/reference/c-api.array.rst | 224 | ||||
| -rw-r--r-- | doc/source/reference/c-api.types-and-structures.rst | 41 | ||||
| -rw-r--r-- | doc/source/reference/internals.code-explanations.rst | 28 | ||||
| -rw-r--r-- | doc/source/user/c-info.how-to-extend.rst | 53 |
4 files changed, 176 insertions, 170 deletions
diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst index 98b91d805..02aa03ff0 100644 --- a/doc/source/reference/c-api.array.rst +++ b/doc/source/reference/c-api.array.rst @@ -154,7 +154,7 @@ From scratch provided. If *strides* is ``NULL``, then the array strides are computed as C-style contiguous (default) or Fortran-style contiguous (*flags* is nonzero for *data* = ``NULL`` or *flags* & - :cdata:`NPY_F_CONTIGUOUS` is nonzero non-NULL *data*). Any provided + :cdata:`NPY_ARRAY_F_CONTIGUOUS` is nonzero non-NULL *data*). Any provided *dims* and *strides* are copied into newly allocated dimension and strides arrays for the new array object. @@ -297,108 +297,112 @@ From other objects the array is constructed that way. Almost always this parameter is ``NULL``. - .. cvar:: NPY_C_CONTIGUOUS + 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. + + .. cvar:: NPY_ARRAY_C_CONTIGUOUS Make sure the returned array is C-style contiguous - .. cvar:: NPY_F_CONTIGUOUS + .. cvar:: NPY_ARRAY_F_CONTIGUOUS Make sure the returned array is Fortran-style contiguous. - .. cvar:: NPY_ALIGNED + .. cvar:: 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. - .. cvar:: NPY_WRITEABLE + .. cvar:: NPY_ARRAY_WRITEABLE Make sure the returned array can be written to. - .. cvar:: NPY_ENSURECOPY + .. cvar:: 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. - .. cvar:: NPY_ENSUREARRAY + .. cvar:: NPY_ARRAY_ENSUREARRAY Make sure the result is a base-class ndarray or bigndarray. By default, if *op* is an instance of a subclass of the bigndarray, an instance of that same subclass is returned. If this flag is set, an ndarray object will be returned instead. - .. cvar:: NPY_FORCECAST + .. cvar:: 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 reaised. - .. cvar:: NPY_UPDATEIFCOPY + .. cvar:: NPY_ARRAY_UPDATEIFCOPY 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 that is already an array) must be made, then the - corresponding :cdata:`NPY_UPDATEIFCOPY` flag is set in the returned + requirements). If this flag is present and a copy (of an object + that is already an array) must be made, then the corresponding + :cdata:`NPY_ARRAY_UPDATEIFCOPY` flag is set in the returned copy and *op* is made to be read-only. When the returned copy is deleted (presumably after your calculations are complete), its contents will be copied back into *op* and the *op* array - will be made writeable again. If *op* is not writeable to - begin with, then an error is raised. If *op* is not already an - array, then this flag has no effect. + will be made writeable again. If *op* is not writeable to begin + with, then an error is raised. If *op* is not already an array, + then this flag has no effect. - .. cvar:: NPY_BEHAVED + .. cvar:: NPY_ARRAY_BEHAVED - :cdata:`NPY_ALIGNED` \| :cdata:`NPY_WRITEABLE` + :cdata:`NPY_ARRAY_ALIGNED` \| :cdata:`NPY_ARRAY_WRITEABLE` - .. cvar:: NPY_CARRAY + .. cvar:: NPY_ARRAY_CARRAY - :cdata:`NPY_C_CONTIGUOUS` \| :cdata:`NPY_BEHAVED` + :cdata:`NPY_ARRAY_C_CONTIGUOUS` \| :cdata:`NPY_ARRAY_BEHAVED` - .. cvar:: NPY_CARRAY_RO + .. cvar:: NPY_ARRAY_CARRAY_RO - :cdata:`NPY_C_CONTIGUOUS` \| :cdata:`NPY_ALIGNED` + :cdata:`NPY_ARRAY_C_CONTIGUOUS` \| :cdata:`NPY_ARRAY_ALIGNED` - .. cvar:: NPY_FARRAY + .. cvar:: NPY_ARRAY_FARRAY - :cdata:`NPY_F_CONTIGUOUS` \| :cdata:`NPY_BEHAVED` + :cdata:`NPY_ARRAY_F_CONTIGUOUS` \| :cdata:`NPY_ARRAY_BEHAVED` - .. cvar:: NPY_FARRAY_RO + .. cvar:: NPY_ARRAY_FARRAY_RO - :cdata:`NPY_F_CONTIGUOUS` \| :cdata:`NPY_ALIGNED` + :cdata:`NPY_ARRAY_F_CONTIGUOUS` \| :cdata:`NPY_ARRAY_ALIGNED` - .. cvar:: NPY_DEFAULT + .. cvar:: NPY_ARRAY_DEFAULT - :cdata:`NPY_CARRAY` + :cdata:`NPY_ARRAY_CARRAY` - .. cvar:: NPY_IN_ARRAY + .. cvar:: NPY_ARRAY_IN_ARRAY - :cdata:`NPY_CONTIGUOUS` \| :cdata:`NPY_ALIGNED` + :cdata:`NPY_ARRAY_CONTIGUOUS` \| :cdata:`NPY_ARRAY_ALIGNED` - .. cvar:: NPY_IN_FARRAY + .. cvar:: NPY_ARRAY_IN_FARRAY - :cdata:`NPY_F_CONTIGUOUS` \| :cdata:`NPY_ALIGNED` + :cdata:`NPY_ARRAY_F_CONTIGUOUS` \| :cdata:`NPY_ARRAY_ALIGNED` .. cvar:: NPY_OUT_ARRAY - :cdata:`NPY_C_CONTIGUOUS` \| :cdata:`NPY_WRITEABLE` \| - :cdata:`NPY_ALIGNED` + :cdata:`NPY_ARRAY_C_CONTIGUOUS` \| :cdata:`NPY_ARRAY_WRITEABLE` \| + :cdata:`NPY_ARRAY_ALIGNED` - .. cvar:: NPY_OUT_FARRAY + .. cvar:: NPY_ARRAY_OUT_FARRAY - :cdata:`NPY_F_CONTIGUOUS` \| :cdata:`NPY_WRITEABLE` \| - :cdata:`NPY_ALIGNED` + :cdata:`NPY_ARRAY_F_CONTIGUOUS` \| :cdata:`NPY_ARRAY_WRITEABLE` \| + :cdata:`NPY_ARRAY_ALIGNED` - .. cvar:: NPY_INOUT_ARRAY + .. cvar:: NPY_ARRAY_INOUT_ARRAY - :cdata:`NPY_C_CONTIGUOUS` \| :cdata:`NPY_WRITEABLE` \| - :cdata:`NPY_ALIGNED` \| :cdata:`NPY_UPDATEIFCOPY` + :cdata:`NPY_ARRAY_C_CONTIGUOUS` \| :cdata:`NPY_ARRAY_WRITEABLE` \| + :cdata:`NPY_ARRAY_ALIGNED` \| :cdata:`NPY_ARRAY_UPDATEIFCOPY` - .. cvar:: NPY_INOUT_FARRAY + .. cvar:: NPY_ARRAY_INOUT_FARRAY - :cdata:`NPY_F_CONTIGUOUS` \| :cdata:`NPY_WRITEABLE` \| - :cdata:`NPY_ALIGNED` \| :cdata:`NPY_UPDATEIFCOPY` + :cdata:`NPY_ARRAY_F_CONTIGUOUS` \| :cdata:`NPY_ARRAY_WRITEABLE` \| + :cdata:`NPY_ARRAY_ALIGNED` \| :cdata:`NPY_ARRAY_UPDATEIFCOPY` .. cfunction:: int PyArray_GetArrayParamsFromObject(PyObject* op, PyArray_Descr* requested_dtype, npy_bool writeable, PyArray_Descr** out_dtype, int* out_ndim, npy_intp* out_dims, PyArrayObject** out_arr, PyObject* context) @@ -421,7 +425,7 @@ From other objects If writing to the value in 'op' is desired, set the boolean 'writeable' to 1. This raises an error when 'op' is a scalar, list of lists, or other non-writeable 'op'. This differs from passing - NPY_WRITEABLE to PyArray_FromAny, where the writeable array may + NPY_ARRAY_WRITEABLE to PyArray_FromAny, where the writeable array may be a copy of the input. When success (0 return value) is returned, either out_arr @@ -447,7 +451,7 @@ From other objects // Could make custom strides here too arr = PyArray_NewFromDescr(&PyArray_Type, dtype, ndim, dims, NULL, - fortran ? NPY_F_CONTIGUOUS : 0, + fortran ? NPY_ARRAY_F_CONTIGUOUS : 0, NULL); if (arr == NULL) { return NULL; @@ -466,12 +470,12 @@ From other objects .. cfunction:: PyObject* PyArray_CheckFromAny(PyObject* op, PyArray_Descr* dtype, int min_depth, int max_depth, int requirements, PyObject* context) Nearly identical to :cfunc:`PyArray_FromAny` (...) except - *requirements* can contain :cdata:`NPY_NOTSWAPPED` (over-riding the - specification in *dtype*) and :cdata:`NPY_ELEMENTSTRIDES` which + *requirements* can contain :cdata:`NPY_ARRAY_NOTSWAPPED` (over-riding the + specification in *dtype*) and :cdata:`NPY_ARRAY_ELEMENTSTRIDES` which indicates that the array should be aligned in the sense that the strides are multiples of the element size. -.. cvar:: NPY_NOTSWAPPED +.. cvar:: 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* @@ -482,11 +486,11 @@ From other objects not in machine byte- order), then a new data-type descriptor is created and used with its byte-order field set to native. -.. cvar:: NPY_BEHAVED_NS +.. cvar:: NPY_ARRAY_BEHAVED_NS - :cdata:`NPY_ALIGNED` \| :cdata:`NPY_WRITEABLE` \| :cdata:`NPY_NOTSWAPPED` + :cdata:`NPY_ARRAY_ALIGNED` \| :cdata:`NPY_ARRAY_WRITEABLE` \| :cdata:`NPY_ARRAY_NOTSWAPPED` -.. cvar:: NPY_ELEMENTSTRIDES +.. cvar:: NPY_ARRAY_ELEMENTSTRIDES Make sure the returned array has strides that are multiples of the element size. @@ -545,7 +549,7 @@ From other objects This function **steals a reference** to ``op`` and makes sure that ``op`` is a base-class ndarray. It special cases array scalars, but otherwise calls :cfunc:`PyArray_FromAny` ( ``op``, NULL, 0, 0, - :cdata:`NPY_ENSUREARRAY`). + :cdata:`NPY_ARRAY_ENSUREARRAY`). .. cfunction:: PyObject* PyArray_FromString(char* string, npy_intp slen, PyArray_Descr* dtype, npy_intp num, char* sep) @@ -579,7 +583,7 @@ From other objects object, ``buf``, that exports the (single-segment) buffer protocol (or has an attribute __buffer\__ that returns an object that exports the buffer protocol). A writeable buffer will be tried - first followed by a read- only buffer. The :cdata:`NPY_WRITEABLE` + first followed by a read- only buffer. The :cdata:`NPY_ARRAY_WRITEABLE` flag of the returned array will reflect which one was successful. The data is assumed to start at ``offset`` bytes from the start of the memory location for the object. The type of the @@ -625,11 +629,11 @@ From other objects Similar to :cfunc:`PyArray_FROM_O` except it can take an argument of *requirements* indicating properties the resulting array must have. Available requirements that can be enforced are - :cdata:`NPY_CONTIGUOUS`, :cdata:`NPY_F_CONTIGUOUS`, - :cdata:`NPY_ALIGNED`, :cdata:`NPY_WRITEABLE`, - :cdata:`NPY_NOTSWAPPED`, :cdata:`NPY_ENSURECOPY`, - :cdata:`NPY_UPDATEIFCOPY`, :cdata:`NPY_FORCECAST`, and - :cdata:`NPY_ENSUREARRAY`. Standard combinations of flags can also + :cdata:`NPY_ARRAY_C_CONTIGUOUS`, :cdata:`NPY_ARRAY_F_CONTIGUOUS`, + :cdata:`NPY_ARRAY_ALIGNED`, :cdata:`NPY_ARRAY_WRITEABLE`, + :cdata:`NPY_ARRAY_NOTSWAPPED`, :cdata:`NPY_ARRAY_ENSURECOPY`, + :cdata:`NPY_ARRAY_UPDATEIFCOPY`, :cdata:`NPY_ARRAY_FORCECAST`, and + :cdata:`NPY_ARRAY_ENSUREARRAY`. Standard combinations of flags can also be used: .. cfunction:: PyObject* PyArray_FROM_OT(PyObject* obj, int typenum) @@ -648,7 +652,7 @@ From other objects specified using a typenumber. :cfunc:`PyArray_DescrFromType` (*typenum*) is passed directly to :cfunc:`PyArray_FromAny`. This macro also adds :cdata:`NPY_DEFAULT` to requirements if - :cdata:`NPY_ENSURECOPY` is passed in as requirements. + :cdata:`NPY_ARRAY_ENSURECOPY` is passed in as requirements. .. cfunction:: PyObject *PyArray_CheckAxis(PyObject* obj, int* axis, int requirements) @@ -1187,11 +1191,11 @@ determine the bit-position of the flag. Python exposes a nice attribute- based interface as well as a dictionary-like interface for getting (and, if appropriate, setting) these flags. -Memory areas of all kinds can be pointed to by an ndarray, -necessitating these flags. If you get an arbitrary ``PyArrayObject`` -in C-code, you need to be aware of the flags that are set. If you -need to guarantee a certain kind of array (like :cdata:`NPY_C_CONTIGUOUS` and -:cdata:`NPY_BEHAVED`), then pass these requirements into the +Memory areas of all kinds can be pointed to by an ndarray, necessitating +these flags. If you get an arbitrary ``PyArrayObject`` in C-code, you +need to be aware of the flags that are set. If you need to guarantee +a certain kind of array (like :cdata:`NPY_ARRAY_C_CONTIGUOUS` and +:cdata:`NPY_ARRAY_BEHAVED`), then pass these requirements into the PyArray_FromAny function. @@ -1206,38 +1210,38 @@ might not be writeable. It might be in Fortan-contiguous order. The array flags are used to indicate what can be said about data associated with an array. -.. cvar:: NPY_C_CONTIGUOUS +.. cvar:: NPY_ARRAY_C_CONTIGUOUS The data area is in C-style contiguous order (last index varies the fastest). -.. cvar:: NPY_F_CONTIGUOUS +.. cvar:: NPY_ARRAY_F_CONTIGUOUS The data area is in Fortran-style contiguous order (first index varies the fastest). -Notice that contiguous 1-d arrays are always both Fortran -contiguous and C contiguous. Both of these flags can be checked and -are convenience flags only as whether or not an array is -:cdata:`NPY_C_CONTIGUOUS` or :cdata:`NPY_F_CONTIGUOUS` can be determined by the -``strides``, ``dimensions``, and ``itemsize`` attributes. +Notice that contiguous 1-d arrays are always both Fortran contiguous +and C contiguous. Both of these flags can be checked and are convenience +flags only as whether or not an array is :cdata:`NPY_ARRAY_C_CONTIGUOUS` +or :cdata:`NPY_ARRAY_F_CONTIGUOUS` can be determined by the ``strides``, +``dimensions``, and ``itemsize`` attributes. -.. cvar:: NPY_OWNDATA +.. cvar:: NPY_ARRAY_OWNDATA The data area is owned by this array. -.. cvar:: NPY_ALIGNED +.. cvar:: NPY_ARRAY_ALIGNED The data area is aligned appropriately (for all strides). -.. cvar:: NPY_WRITEABLE +.. cvar:: NPY_ARRAY_WRITEABLE The data area can be written to. Notice that the above 3 flags are are defined so that a new, well- behaved array has these flags defined as true. -.. cvar:: NPY_UPDATEIFCOPY +.. cvar:: NPY_ARRAY_UPDATEIFCOPY The data area represents a (well-behaved) copy whose information should be transferred back to the original when this array is deleted. @@ -1250,47 +1254,47 @@ are convenience flags only as whether or not an array is array (which is set read_only). When the array with this flag set is deallocated, it will copy its contents back to the "misbehaved" array (casting if necessary) and will reset the "misbehaved" array - to :cdata:`NPY_WRITEABLE`. If the "misbehaved" array was not - :cdata:`NPY_WRITEABLE` to begin with then :cfunc:`PyArray_FromAny` - would have returned an error because :cdata:`NPY_UPDATEIFCOPY` + to :cdata:`NPY_ARRAY_WRITEABLE`. If the "misbehaved" array was not + :cdata:`NPY_ARRAY_WRITEABLE` to begin with then :cfunc:`PyArray_FromAny` + would have returned an error because :cdata:`NPY_ARRAY_UPDATEIFCOPY` would not have been possible. -:cfunc:`PyArray_UpdateFlags` (obj, flags) will update the -``obj->flags`` for ``flags`` which can be any of -:cdata:`NPY_C_CONTIGUOUS`, :cdata:`NPY_F_CONTIGUOUS`, :cdata:`NPY_ALIGNED`, -or :cdata:`NPY_WRITEABLE`. +:cfunc:`PyArray_UpdateFlags` (obj, flags) will update the ``obj->flags`` +for ``flags`` which can be any of :cdata:`NPY_ARRAY_C_CONTIGUOUS`, +:cdata:`NPY_ARRAY_F_CONTIGUOUS`, :cdata:`NPY_ARRAY_ALIGNED`, or +:cdata:`NPY_ARRAY_WRITEABLE`. Combinations of array flags ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. cvar:: NPY_BEHAVED +.. cvar:: NPY_ARRAY_BEHAVED - :cdata:`NPY_ALIGNED` \| :cdata:`NPY_WRITEABLE` + :cdata:`NPY_ARRAY_ALIGNED` \| :cdata:`NPY_ARRAY_WRITEABLE` -.. cvar:: NPY_CARRAY +.. cvar:: NPY_ARRAY_CARRAY - :cdata:`NPY_C_CONTIGUOUS` \| :cdata:`NPY_BEHAVED` + :cdata:`NPY_ARRAY_C_CONTIGUOUS` \| :cdata:`NPY_ARRAY_BEHAVED` -.. cvar:: NPY_CARRAY_RO +.. cvar:: NPY_ARRAY_CARRAY_RO - :cdata:`NPY_C_CONTIGUOUS` \| :cdata:`NPY_ALIGNED` + :cdata:`NPY_ARRAY_C_CONTIGUOUS` \| :cdata:`NPY_ARRAY_ALIGNED` -.. cvar:: NPY_FARRAY +.. cvar:: NPY_ARRAY_FARRAY - :cdata:`NPY_F_CONTIGUOUS` \| :cdata:`NPY_BEHAVED` + :cdata:`NPY_ARRAY_F_CONTIGUOUS` \| :cdata:`NPY_ARRAY_BEHAVED` -.. cvar:: NPY_FARRAY_RO +.. cvar:: NPY_ARRAY_FARRAY_RO - :cdata:`NPY_F_CONTIGUOUS` \| :cdata:`NPY_ALIGNED` + :cdata:`NPY_ARRAY_F_CONTIGUOUS` \| :cdata:`NPY_ARRAY_ALIGNED` -.. cvar:: NPY_DEFAULT +.. cvar:: NPY_ARRAY_DEFAULT - :cdata:`NPY_CARRAY` + :cdata:`NPY_ARRAY_CARRAY` -.. cvar:: NPY_UPDATE_ALL +.. cvar:: NPY_ARRAY_UPDATE_ALL - :cdata:`NPY_C_CONTIGUOUS` \| :cdata:`NPY_F_CONTIGUOUS` \| :cdata:`NPY_ALIGNED` + :cdata:`NPY_ARRAY_C_CONTIGUOUS` \| :cdata:`NPY_ARRAY_F_CONTIGUOUS` \| :cdata:`NPY_ARRAY_ALIGNED` Flag-like constants @@ -1299,28 +1303,28 @@ Flag-like constants These constants are used in :cfunc:`PyArray_FromAny` (and its macro forms) to specify desired properties of the new array. -.. cvar:: NPY_FORCECAST +.. cvar:: NPY_ARRAY_FORCECAST Cast to the desired type, even if it can't be done without losing information. -.. cvar:: NPY_ENSURECOPY +.. cvar:: NPY_ARRAY_ENSURECOPY Make sure the resulting array is a copy of the original. -.. cvar:: NPY_ENSUREARRAY +.. cvar:: NPY_ARRAY_ENSUREARRAY Make sure the resulting object is an actual ndarray (or bigndarray), and not a sub-class. -.. cvar:: NPY_NOTSWAPPED +.. cvar:: NPY_ARRAY_NOTSWAPPED Only used in :cfunc:`PyArray_CheckFromAny` to over-ride the byteorder of the data-type object passed in. -.. cvar:: NPY_BEHAVED_NS +.. cvar:: NPY_ARRAY_BEHAVED_NS - :cdata:`NPY_ALIGNED` \| :cdata:`NPY_WRITEABLE` \| :cdata:`NPY_NOTSWAPPED` + :cdata:`NPY_ARRAY_ALIGNED` \| :cdata:`NPY_ARRAY_WRITEABLE` \| :cdata:`NPY_ARRAY_NOTSWAPPED` Flag checking @@ -1334,9 +1338,9 @@ For all of these macros *arr* must be an instance of a (subclass of) The first parameter, arr, must be an ndarray or subclass. The parameter, *flags*, should be an integer consisting of bitwise combinations of the possible flags an array can have: - :cdata:`NPY_C_CONTIGUOUS`, :cdata:`NPY_F_CONTIGUOUS`, - :cdata:`NPY_OWNDATA`, :cdata:`NPY_ALIGNED`, - :cdata:`NPY_WRITEABLE`, :cdata:`NPY_UPDATEIFCOPY`. + :cdata:`NPY_ARRAY_C_CONTIGUOUS`, :cdata:`NPY_ARRAY_F_CONTIGUOUS`, + :cdata:`NPY_ARRAY_OWNDATA`, :cdata:`NPY_ARRAY_ALIGNED`, + :cdata:`NPY_ARRAY_WRITEABLE`, :cdata:`NPY_ARRAY_UPDATEIFCOPY`. .. cfunction:: PyArray_ISCONTIGUOUS(arr) @@ -1392,8 +1396,8 @@ For all of these macros *arr* must be an instance of a (subclass of) .. cfunction:: void PyArray_UpdateFlags(PyArrayObject* arr, int flagmask) - The :cdata:`NPY_C_CONTIGUOUS`, :cdata:`NPY_ALIGNED`, and - :cdata:`NPY_F_CONTIGUOUS` array flags can be "calculated" from the + The :cdata:`NPY_ARRAY_C_CONTIGUOUS`, :cdata:`NPY_ARRAY_ALIGNED`, and + :cdata:`NPY_ARRAY_F_CONTIGUOUS` array flags can be "calculated" from the array object itself. This routine updates one or more of these flags of *arr* as specified in *flagmask* by performing the required calculation. @@ -2607,7 +2611,7 @@ to. to hold on to the memory be sure to INCREF the base member. The chunk of memory is pointed to by *buf* ->ptr member and has length *buf* ->len. The flags member of *buf* is :cdata:`NPY_BEHAVED_RO` with - the :cdata:`NPY_WRITEABLE` flag set if *obj* has a writeable buffer + the :cdata:`NPY_ARRAY_WRITEABLE` flag set if *obj* has a writeable buffer interface. .. cfunction:: int PyArray_AxisConverter(PyObject \* obj, int* axis) @@ -3097,11 +3101,11 @@ Miscellaneous Macros .. cfunction:: PyArray_XDECREF_ERR(PyObject \*obj) - DECREF's an array object which may have the :cdata:`NPY_UPDATEIFCOPY` + DECREF's an array object which may have the :cdata:`NPY_ARRAY_UPDATEIFCOPY` flag set without causing the contents to be copied back into the - original array. Resets the :cdata:`NPY_WRITEABLE` flag on the base + original array. Resets the :cdata:`NPY_ARRAY_WRITEABLE` flag on the base object. This is useful for recovering from an error condition when - :cdata:`NPY_UPDATEIFCOPY` is used. + :cdata:`NPY_ARRAY_UPDATEIFCOPY` is used. Enumerated Types diff --git a/doc/source/reference/c-api.types-and-structures.rst b/doc/source/reference/c-api.types-and-structures.rst index 770aac995..8c813faf5 100644 --- a/doc/source/reference/c-api.types-and-structures.rst +++ b/doc/source/reference/c-api.types-and-structures.rst @@ -129,14 +129,14 @@ PyArray_Type .. cmember:: PyObject *PyArrayObject.base - This member is used to hold a pointer to another Python object - that is related to this array. There are two use cases: 1) If - this array does not own its own memory, then base points to the - Python object that owns it (perhaps another array object), 2) - If this array has the :cdata:`NPY_UPDATEIFCOPY` flag set, then this - array is a working copy of a "misbehaved" array. As soon as - this array is deleted, the array pointed to by base will be - updated with the contents of this array. + This member is used to hold a pointer to another Python object that + is related to this array. There are two use cases: 1) If this array + does not own its own memory, then base points to the Python object + that owns it (perhaps another array object), 2) If this array has + the :cdata:`NPY_ARRAY_UPDATEIFCOPY` flag set, then this array is + a working copy of a "misbehaved" array. As soon as this array is + deleted, the array pointed to by base will be updated with the + contents of this array. .. cmember:: PyArray_Descr *PyArrayObject.descr @@ -151,9 +151,10 @@ PyArray_Type .. cmember:: int PyArrayObject.flags Flags indicating how the memory pointed to by data is to be - interpreted. Possible flags are :cdata:`NPY_C_CONTIGUOUS`, - :cdata:`NPY_F_CONTIGUOUS`, :cdata:`NPY_OWNDATA`, :cdata:`NPY_ALIGNED`, - :cdata:`NPY_WRITEABLE`, and :cdata:`NPY_UPDATEIFCOPY`. + interpreted. Possible flags are :cdata:`NPY_ARRAY_C_CONTIGUOUS`, + :cdata:`NPY_ARRAY_F_CONTIGUOUS`, :cdata:`NPY_ARRAY_OWNDATA`, + :cdata:`NPY_ARRAY_ALIGNED`, :cdata:`NPY_ARRAY_WRITEABLE`, and + :cdata:`NPY_ARRAY_UPDATEIFCOPY`. .. cmember:: PyObject *PyArrayObject.weakreflist @@ -850,8 +851,8 @@ PyArrayIter_Type .. cmember:: Bool PyArrayIterObject.contiguous This flag is true if the underlying array is - :cdata:`NPY_C_CONTIGUOUS`. It is used to simplify calculations when - possible. + :cdata:`NPY_ARRAY_C_CONTIGUOUS`. It is used to simplify + calculations when possible. How to use an array iterator on a C-level is explained more fully in @@ -1057,8 +1058,8 @@ PyArray_Chunk .. cmember:: int PyArray_Chunk.flags - Any data flags (*e.g.* :cdata:`NPY_WRITEABLE` ) that should be used - to interpret the memory. + Any data flags (*e.g.* :cdata:`NPY_ARRAY_WRITEABLE` ) that should + be used to interpret the memory. PyArrayInterface @@ -1117,12 +1118,12 @@ PyArrayInterface .. cmember:: int PyArrayInterface.flags - Any of the bits :cdata:`NPY_C_CONTIGUOUS` (1), - :cdata:`NPY_F_CONTIGUOUS` (2), :cdata:`NPY_ALIGNED` (0x100), - :cdata:`NPY_NOTSWAPPED` (0x200), or :cdata:`NPY_WRITEABLE` + Any of the bits :cdata:`NPY_ARRAY_C_CONTIGUOUS` (1), + :cdata:`NPY_ARRAY_F_CONTIGUOUS` (2), :cdata:`NPY_ARRAY_ALIGNED` (0x100), + :cdata:`NPY_ARRAY_NOTSWAPPED` (0x200), or :cdata:`NPY_ARRAY_WRITEABLE` (0x400) to indicate something about the data. The - :cdata:`NPY_ALIGNED`, :cdata:`NPY_C_CONTIGUOUS`, and - :cdata:`NPY_F_CONTIGUOUS` flags can actually be determined from + :cdata:`NPY_ARRAY_ALIGNED`, :cdata:`NPY_ARRAY_C_CONTIGUOUS`, and + :cdata:`NPY_ARRAY_F_CONTIGUOUS` flags can actually be determined from the other parameters. The flag :cdata:`NPY_ARR_HAS_DESCR` (0x800) can also be set to indicate to objects consuming the version 3 array interface that the descr member of the diff --git a/doc/source/reference/internals.code-explanations.rst b/doc/source/reference/internals.code-explanations.rst index cceb1a60d..580661cb3 100644 --- a/doc/source/reference/internals.code-explanations.rst +++ b/doc/source/reference/internals.code-explanations.rst @@ -41,20 +41,20 @@ called a rank-0 array), then the strides and dimensions variables are NULL. Besides the structural information contained in the strides and -dimensions members of the :ctype:`PyArrayObject`, the flags contain important -information about how the data may be accessed. In particular, the -:cdata:`NPY_ALIGNED` flag is set when the memory is on a suitable boundary -according to the data-type array. Even if you have a contiguous chunk -of memory, you cannot just assume it is safe to dereference a data- -type-specific pointer to an element. Only if the :cdata:`NPY_ALIGNED` flag is -set is this a safe operation (on some platforms it will work but on -others, like Solaris, it will cause a bus error). The :cdata:`NPY_WRITEABLE` -should also be ensured if you plan on writing to the memory area of -the array. It is also possible to obtain a pointer to an unwriteable -memory area. Sometimes, writing to the memory area when the -:cdata:`NPY_WRITEABLE` flag is not set will just be rude. Other times it can -cause program crashes ( *e.g.* a data-area that is a read-only -memory-mapped file). +dimensions members of the :ctype:`PyArrayObject`, the flags contain +important information about how the data may be accessed. In particular, +the :cdata:`NPY_ARRAY_ALIGNED` flag is set when the memory is on a +suitable boundary according to the data-type array. Even if you have +a contiguous chunk of memory, you cannot just assume it is safe to +dereference a data- type-specific pointer to an element. Only if the +:cdata:`NPY_ARRAY_ALIGNED` flag is set is this a safe operation (on +some platforms it will work but on others, like Solaris, it will cause +a bus error). The :cdata:`NPY_ARRAY_WRITEABLE` should also be ensured +if you plan on writing to the memory area of the array. It is also +possible to obtain a pointer to an unwriteable memory area. Sometimes, +writing to the memory area when the :cdata:`NPY_ARRAY_WRITEABLE` flag is not +set will just be rude. Other times it can cause program crashes ( *e.g.* +a data-area that is a read-only memory-mapped file). Data-type encapsulation diff --git a/doc/source/user/c-info.how-to-extend.rst b/doc/source/user/c-info.how-to-extend.rst index 6c5e25aff..2d10c36a3 100644 --- a/doc/source/user/c-info.how-to-extend.rst +++ b/doc/source/user/c-info.how-to-extend.rst @@ -432,64 +432,65 @@ writeable). The syntax is converting the Python object into an array that is more "well-behaved" for your specific usage. - The requirements flag allows specification of what kind of array is - acceptable. If the object passed in does not satisfy this requirements - then a copy is made so that thre returned object will satisfy the - requirements. these ndarray can use a very generic pointer to memory. - This flag allows specification of the desired properties of the - returned array object. All of the flags are explained in the detailed - API chapter. The flags most commonly needed are :cdata:`NPY_IN_ARRAY`, - :cdata:`NPY_OUT_ARRAY`, and :cdata:`NPY_INOUT_ARRAY`: - - .. cvar:: NPY_IN_ARRAY - - Equivalent to :cdata:`NPY_CONTIGUOUS` \| - :cdata:`NPY_ALIGNED`. This combination of flags is useful + The requirements flag allows specification of what kind of + array is acceptable. If the object passed in does not satisfy + this requirements then a copy is made so that thre returned + object will satisfy the requirements. these ndarray can use a + very generic pointer to memory. This flag allows specification + of the desired properties of the returned array object. All + of the flags are explained in the detailed API chapter. The + flags most commonly needed are :cdata:`NPY_ARRAY_IN_ARRAY`, + :cdata:`NPY_OUT_ARRAY`, and :cdata:`NPY_ARRAY_INOUT_ARRAY`: + + .. cvar:: NPY_ARRAY_IN_ARRAY + + Equivalent to :cdata:`NPY_ARRAY_C_CONTIGUOUS` \| + :cdata:`NPY_ARRAY_ALIGNED`. This combination of flags is useful for arrays that must be in C-contiguous order and aligned. These kinds of arrays are usually input arrays for some algorithm. - .. cvar:: NPY_OUT_ARRAY + .. cvar:: NPY_ARRAY_OUT_ARRAY - Equivalent to :cdata:`NPY_CONTIGUOUS` \| - :cdata:`NPY_ALIGNED` \| :cdata:`NPY_WRITEABLE`. This + Equivalent to :cdata:`NPY_ARRAY_C_CONTIGUOUS` \| + :cdata:`NPY_ARRAY_ALIGNED` \| :cdata:`NPY_ARRAY_WRITEABLE`. This combination of flags is useful to specify an array that is in C-contiguous order, is aligned, and can be written to as well. Such an array is usually returned as output (although normally such output arrays are created from scratch). - .. cvar:: NPY_INOUT_ARRAY + .. cvar:: NPY_ARRAY_INOUT_ARRAY - Equivalent to :cdata:`NPY_CONTIGUOUS` \| - :cdata:`NPY_ALIGNED` \| :cdata:`NPY_WRITEABLE` \| - :cdata:`NPY_UPDATEIFCOPY`. This combination of flags is + Equivalent to :cdata:`NPY_ARRAY_C_CONTIGUOUS` \| + :cdata:`NPY_ARRAY_ALIGNED` \| :cdata:`NPY_ARRAY_WRITEABLE` \| + :cdata:`NPY_ARRAY_UPDATEIFCOPY`. This combination of flags is useful to specify an array that will be used for both input and output. If a copy is needed, then when the temporary is deleted (by your use of :cfunc:`Py_DECREF` at the end of the interface routine), the temporary array will be copied back into the original array passed in. Use - of the :cdata:`UPDATEIFCOPY` flag requires that the input + of the :cdata:`NPY_ARRAY_UPDATEIFCOPY` flag requires that the input object is already an array (because other objects cannot be automatically updated in this fashion). If an error occurs use :cfunc:`PyArray_DECREF_ERR` (obj) on an array - with the :cdata:`NPY_UPDATEIFCOPY` flag set. This will + with the :cdata:`NPY_ARRAY_UPDATEIFCOPY` flag set. This will delete the array without causing the contents to be copied back into the original array. Other useful flags that can be OR'd as additional requirements are: - .. cvar:: NPY_FORCECAST + .. cvar:: NPY_ARRAY_FORCECAST Cast to the desired type, even if it can't be done without losing information. - .. cvar:: NPY_ENSURECOPY + .. cvar:: NPY_ARRAY_ENSURECOPY Make sure the resulting array is a copy of the original. - .. cvar:: NPY_ENSUREARRAY + .. cvar:: NPY_ARRAY_ENSUREARRAY Make sure the resulting object is an actual ndarray and not a sub- class. @@ -499,7 +500,7 @@ writeable). The syntax is Whether or not an array is byte-swapped is determined by the data-type of the array. Native byte-order arrays are always requested by :cfunc:`PyArray_FROM_OTF` and so there is no need for - a :cdata:`NPY_NOTSWAPPED` flag in the requirements argument. There + a :cdata:`NPY_ARRAY_NOTSWAPPED` flag in the requirements argument. There is also no way to get a byte-swapped array from this routine. |