numarray Manual

14.1 Numarray extension basics

There's a couple things you need to do in order to access numarray's C-API in your own C extension module:

14.1.1 Include libnumarray.h

Near the top of your extension module add the lines:

  #include "Python.h"
  #include "libnumarray.h"

This gives your C-code access to the numarray typedefs, macros, and function prototypes as well as the Python C-API.

14.1.2 Alternate include method

There's an alternate form of including libnumarray.h or arrayobject.h some people may prefer provided that they're willing to ignore the case where the numarray includes are not installed in the standard location. The advantage of the following approach is that it automatically works with the default path to the Python include files which the distutils always provide.

    #include "Python.h"
    #include "numarray/libnumarray.h"

14.1.3 Import libnumarray

In your extension module's initialization function, add the line:

  import_libnumarray();

import_libnumarray() is actually a macro which sets up a pointer to the numarray C-API function pointer table. If you forget to call import_libnumarray(), your extension module will crash as soon as you call a numarray API function, because your application will attempt to dereference a NULL pointer.

Note that for the Numeric compatible API you should substitute arrayobject.h for libnumarray.h and import_array() for import_libnumarray() respectively. Unlike other versions of numarray prior to 1.0, arrayobject.h now includes only the Numeric simulation API. To use the rest of the numarray API, you must include libnumarray.h. To use both, you must include both arrayobject.h and libnumarray.h, and you must both import_array() and import_libnumarray() in your module initialization function.

14.1.4 Writing a simple setup.py file for a numarray extension

One important practice for writing an extension module is the creation of a distutils setup.py file which automates both extension installation from source and the creation of binary distributions. Here is a simple setup.py which builds a single extension module from a single C source file:

    from distutils.core import setup, Extension
    from numarray.numarrayext import NumarrayExtension
    import sys
    
    if not hasattr(sys, 'version_info') or sys.version_info < (2,2,0,'alpha',0):        raise SystemExit, "Python 2.2 or later required to build this module."
    
    setup(name = "buildHistogram",
       version = "0.1",
       description = "",
       packages=[""],
       package_dir={"":""},
       ext_modules=[NumarrayExtension("buildHistogram",['buildHistogram.c'],\
         include_dirs=["./"],
         library_dirs=["./"],
         libraries=['m'])])

NumarrayExtension is recommended rather than it's distutils baseclass Extension because NumarrayExtension knows where to find the numarray headers regardless of where the numarray installer or setup.py command line options put them. A disadvantage of using NumarrayExtension is that it is numarray specific, so it does not work for compiling Numeric versions of the extension.

See the Python manuals ``Installing Python Modules'' and ``Distributing Python Modules'' for more information on how to use distutils.

Send comments to the NumArray community.