User guide

NumPy User Guide, Release 1.9.0

2. Set the argtypes attribute to a list whose entries contain objects with a classmethod named from_param that

knows how to convert your object to an object that ctypes can understand (an int/long, string, unicode, or object

with the _as_parameter_ attribute).

NumPy uses both methods with a preference for the second method because it can be safer. The ctypes attribute of the

ndarray returns an object that has an _as_parameter_ attribute which returns an integer representing the address of the

ndarray to which it is associated. As a result, one can pass this ctypes attribute object directly to a function expecting

a pointer to the data in your ndarray. The caller must be sure that the ndarray object is of the correct type, shape, and

has the correct ﬂags set or risk nasty crashes if the data-pointer to inappropriate arrays are passsed in.

To implement the second method, NumPy provides the class-factory function ndpointer in the ctypeslib mod-

ule. This class-factory function produces an appropriate class that can be placed in an argtypes attribute entry of a

ctypes function. The class will contain a from_param method which ctypes will use to convert any ndarray passed in

to the function to a ctypes-recognized object. In the process, the conversion will perform checking on any properties

of the ndarray that were speciﬁed by the user in the call to ndpointer. Aspects of the ndarray that can be checked

include the data-type, the number-of-dimensions, the shape, and/or the state of the ﬂags on any array passed. The re-

turn value of the from_param method is the ctypes attribute of the array which (because it contains the _as_parameter_

attribute pointing to the array data area) can be used by ctypes directly.

The ctypes attribute of an ndarray is also endowed with additional attributes that may be convenient when passing

additional information about the array into a ctypes function. The attributes data, shape, and strides can provide

c-types compatible types corresponding to the data-area, the shape, and the strides of the array. The data attribute

reutrns a c_void_p representing a pointer to the data area. The shape and strides attributes each return an array of

ctypes integers (or None representing a NULL pointer, if a 0-d array). The base ctype of the array is a ctype integer

of the same size as a pointer on the platform. There are also methods data_as({ctype}), shape_as(<base ctype>), and

strides_as(<base ctype>). These return the data as a ctype object of your choice and the shape/strides arrays using an

underlying base type of your choice. For convenience, the ctypeslib module also contains c_intp as a ctypes integer

data-type whose size is the same as the size of c_void_p on the platform (it’s value is None if ctypes is not installed).

Calling the function

The function is accessed as an attribute of or an item from the loaded shared-library. Thus, if ”./mylib.so” has a

function named “cool_function1” , I could access this function either as:

lib = numpy.ctypeslib.load_library(’mylib’,’.’)

func1 = lib.cool_function1 # or equivalently

func1 = lib[’cool_function1’]

In ctypes, the return-value of a function is set to be ‘int’ by default. This behavior can be changed by setting the

restype attribute of the function. Use None for the restype if the function has no return value (‘void’):

func1.restype = None

As previously discussed, you can also set the argtypes attribute of the function in order to have ctypes check the types

of the input arguments when the function is called. Use the ndpointer factory function to generate a ready-made

class for data-type, shape, and ﬂags checking on your new function. The ndpointer function has the signature

ndpointer(dtype=None, ndim=None, shape=None, ﬂags=None)

Keyword arguments with the value None are not checked. Specifying a keyword enforces checking of that

aspect of the ndarray on conversion to a ctypes-compatible object. The dtype keyword can be any object

understood as a data-type object. The ndim keyword should be an integer, and the shape keyword should be

an integer or a sequence of integers. The ﬂags keyword speciﬁes the minimal ﬂags that are required on any

array passed in. This can be speciﬁed as a string of comma separated requirements, an integer indicating the

requirement bits OR’d together, or a ﬂags object returned from the ﬂags attribute of an array with the necessary

requirements.

74 Chapter 5. Using Numpy C-API