10. C extension API
This chapter describes the different available C-APIs for numarray
based extension modules.
While this chapter describes the numarray-specifics for writing
extension modules, a basic understanding of Pythonextension modules is
expected. See Python's Extending and
Embedding tutorial and the
Python/C API.
The numarray C-API has several different facets, and the first three facets
each make different tradeoffs between memory use, speed, and ease of use. An
additional facet provides backwards compatability with legacy Numeric code.
The final facet consists of miscellaneous function calls used to implement
and utilize numarray, that were not part of Numeric.
In addition to most of the basic functionality provided by Numeric, these APIs
provide access to misaligned, byteswapped, and discontiguous numarrays.
Byteswapped arrays arise in the context of portable binary data formats where
the byteorder specified by the data format is not the same as the host
processor byte order. Misaligned arrays arise in the context of tabular data:
files of records where arrays are superimposed on the column formed by a single
field in the record. Discontiguous arrays arise from operations which permute
the shape and strides of an array, such as reshape.
- high-level
- This is the cleanest and eaisiest to use API. It creates
temporary arrays to handle difficult cases (discontiguous, byteswapped,
misaligned) in C code. Code using this API is written in terms of a pointer
to a contiguous 1D array of C data. See section
10.3.
- element-wise
- This API handles misbehaved arrays without creating
temporaries. Code using this API is written to access single elements of
an array via macros or functions. Note:
These macros are probably slow,
and the functions even slower. See section
10.4.
- 1-dimensional
- Code using this API get/sets consecutive elements of the
inner dimension of an array, enabling the API to factor out tests for
aligment and byteswapping to one test per call. Fewer tests means better
performance, but at a cost of some temporary data and more difficult usage.
See section 10.5.
- Numeric compatability functions
- This API aims to provide a reasonable
(if not complete) emulation of the Numeric C-API. It is written in terms of
the numarray high level API so that misbehaved numarrays are copied prior to
processing with legacy Numeric code. See section
10.6.
- New numarray functions
- This last facet of the C-API consists of function
calls which have been added to numarray which are orthogonal to each of the 3
native access APIs and not part of the original Numeric. See section
10.7
Subsections
Send comments to the NumArray community.