@@ -10,134 +10,10 @@ __ https://scipy.org/scipylib/mailing-lists.html
1010
1111The C API of NumPy is (mostly) backward compatible with Numeric.
1212
13- There are a few non-standard Numeric usages (that were not really part
14- of the API) that will need to be changed:
15-
16- * If you used any of the function pointers in the ``PyArray_Descr ``
17- structure you will have to modify your usage of those. First,
18- the pointers are all under the member named ``f ``. So ``descr->cast ``
19- is now ``descr->f->cast ``. In addition, the
20- casting functions have eliminated the strides argument (use
21- ``PyArray_CastTo `` if you need strided casting). All functions have
22- one or two ``PyArrayObject * `` arguments at the end. This allows the
23- flexible arrays and mis-behaved arrays to be handled.
24-
25- * The ``descr->zero `` and ``descr->one `` constants have been replaced with
26- function calls, ``PyArray_Zero ``, and ``PyArray_One `` (be sure to read the
27- code and free the resulting memory if you use these calls).
28-
29- * If you passed ``array->dimensions `` and ``array->strides `` around
30- to functions, you will need to fix some code. These are now
31- ``npy_intp* `` pointers. On 32-bit systems there won't be a problem.
32- However, on 64-bit systems, you will need to make changes to avoid
33- errors and segfaults.
34-
35-
36- The header files ``arrayobject.h `` and ``ufuncobject.h `` contain many defines
37- that you may find useful. The files ``__ufunc_api.h `` and
38- ``__multiarray_api.h `` contain the available C-API function calls with
39- their function signatures.
40-
4113All of these headers are installed to
4214``<YOUR_PYTHON_LOCATION>/site-packages/numpy/core/include ``
4315
4416
45- Getting arrays in C-code
46- =========================
47-
48- All new arrays can be created using ``PyArray_NewFromDescr ``. A simple interface
49- equivalent to ``PyArray_FromDims `` is ``PyArray_SimpleNew(nd, dims, typenum) ``
50- and to ``PyArray_FromDimsAndData `` is
51- ``PyArray_SimpleNewFromData(nd, dims, typenum, data) ``.
52-
53- This is a very flexible function.
54-
55- ::
56-
57- PyObject * PyArray_NewFromDescr(PyTypeObject *subtype, PyArray_Descr *descr,
58- int nd, npy_intp *dims,
59- npy_intp *strides, char *data,
60- int flags, PyObject *obj);
61-
62- ``subtype `` : ``PyTypeObject * ``
63- The subtype that should be created (either pass in
64- ``&PyArray_Type ``, or ``obj->ob_type ``,
65- where ``obj `` is an instance of a subtype (or subclass) of
66- ``PyArray_Type ``).
67-
68- ``descr `` : ``PyArray_Descr * ``
69- The type descriptor for the array. This is a Python object (this
70- function steals a reference to it). The easiest way to get one is
71- using ``PyArray_DescrFromType(<typenum>) ``. If you want to use a
72- flexible size array, then you need to use
73- ``PyArray_DescrNewFromType(<flexible typenum>) `` and set its ``elsize ``
74- parameter to the desired size. The typenum in both of these cases
75- is one of the ``PyArray_XXXX `` enumerated types.
76-
77- ``nd `` : ``int ``
78- The number of dimensions (<``MAX_DIMS ``)
79-
80- ``*dims `` : ``npy_intp * ``
81- A pointer to the size in each dimension. Information will be
82- copied from here.
83-
84- ``*strides `` : ``npy_intp * ``
85- The strides this array should have. For new arrays created by this
86- routine, this should be ``NULL ``. If you pass in memory for this array
87- to use, then you can pass in the strides information as well
88- (otherwise it will be created for you and default to C-contiguous
89- or Fortran contiguous). Any strides will be copied into the array
90- structure. Do not pass in bad strides information!!!!
91-
92- ``PyArray_CheckStrides(...) `` can help but you must call it if you are
93- unsure. You cannot pass in strides information when data is ``NULL ``
94- and this routine is creating its own memory.
95-
96- ``*data `` : ``char * ``
97- ``NULL `` for creating brand-new memory. If you want this array to wrap
98- another memory area, then pass the pointer here. You are
99- responsible for deleting the memory in that case, but do not do so
100- until the new array object has been deleted. The best way to
101- handle that is to get the memory from another Python object,
102- ``INCREF `` that Python object after passing it's data pointer to this
103- routine, and set the ``->base `` member of the returned array to the
104- Python object. *You are responsible for * setting ``PyArray_BASE(ret) ``
105- to the base object. Failure to do so will create a memory leak.
106-
107- If you pass in a data buffer, the ``flags `` argument will be the flags
108- of the new array. If you create a new array, a non-zero flags
109- argument indicates that you want the array to be in Fortran order.
110-
111- ``flags `` : ``int ``
112- Either the flags showing how to interpret the data buffer passed
113- in, or if a new array is created, nonzero to indicate a Fortran
114- order array. See below for an explanation of the flags.
115-
116- ``obj `` : ``PyObject * ``
117- If subtypes is ``&PyArray_Type ``, this argument is
118- ignored. Otherwise, the ``__array_finalize__ `` method of the subtype
119- is called (if present) and passed this object. This is usually an
120- array of the type to be created (so the ``__array_finalize__ `` method
121- must handle an array argument. But, it can be anything...)
122-
123- Note: The returned array object will be uninitialized unless the type is
124- ``PyArray_OBJECT `` in which case the memory will be set to ``NULL ``.
125-
126- ``PyArray_SimpleNew(nd, dims, typenum) `` is a drop-in replacement for
127- ``PyArray_FromDims `` (except it takes ``npy_intp* `` dims instead of ``int* `` dims
128- which matters on 64-bit systems) and it does not initialize the memory
129- to zero.
130-
131- ``PyArray_SimpleNew `` is just a macro for ``PyArray_New `` with default arguments.
132- Use ``PyArray_FILLWBYTE(arr, 0) `` to fill with zeros.
133-
134- The ``PyArray_FromDims `` and family of functions are still available and
135- are loose wrappers around this function. These functions still take
136- ``int * `` arguments. This should be fine on 32-bit systems, but on 64-bit
137- systems you may run into trouble if you frequently passed
138- ``PyArray_FromDims `` the dimensions member of the old ``PyArrayObject `` structure
139- because ``sizeof(npy_intp) != sizeof(int) ``.
140-
14117
14218Getting an arrayobject from an arbitrary Python object
14319======================================================
0 commit comments