Working with Python arrays

    Compared to the manual approach with malloc() and free(), this gives the safe and automatic memory management of Python, and compared to a Numpy array there is no need to install a dependency, as the array module is built into both Python and Cython.

    NB: the import brings the regular Python array object into the namespace while the cimport adds functions accessible from Cython.

    A Python array is constructed with a type signature and sequence of initial values. For the possible type signatures, refer to the Python documentation for the .

    Notice that when a Python array is assigned to a variable typed as memory view, there will be a slight overhead to construct the memory view. However, from that point on the variable can be passed to other functions without overhead, so long as it is typed:

    1. from cpython cimport array
    2. import array
    4. cdef array.array a = array.array('i', [1, 2, 3])
    5. cdef int[:] ca = a
    7. cdef int overhead(object a):
    8.     cdef int[:] ca = a
    9.     return ca[0]
    11. cdef int no_overhead(int[:] ca):
    12.     return ca[0]
    14. print(no_overhead(ca))  # ca is already a memory view, so no overhead

    To avoid any overhead and to be able to pass a C pointer to other functions, it is possible to access the underlying contiguous array as a pointer. There is no type or bounds checking, so be careful to use the right type and signedness.

    1. from cpython cimport array
    4. cdef array.array a = array.array('i', [1, 2, 3])
    6. # access underlying pointer:
    7. print(a.data.as_ints[0])
    9. from libc.string cimport memset
    11. memset(a.data.as_voidptr, 0, len(a) * sizeof(int))

    To avoid having to use the array constructor from the Python module, it is possible to create a new array with the same type as a template, and preallocate a given number of elements. The array is initialized to zero when requested.

    1. from cpython cimport array
    2. import array
    4. cdef array.array int_array_template = array.array('i', [])
    5. cdef array.array newarray
    7. # create an array with 3 elements with same type as template

    An array can also be extended and resized; this avoids repeated memory reallocation which would occur if elements would be appended or removed one by one.

    1. data.as_voidptr
    2. data.as_chars
    4. data.as_uchars
    5. data.as_shorts
    6. data.as_ushorts
    7. data.as_ints
    8. data.as_uints
    9. data.as_longs
    10. data.as_ulongs
    11. data.as_longlongs  # requires Python >=3
    12. data.as_ulonglongs  # requires Python >=3
    13. data.as_floats
    14. data.as_doubles
    15. data.as_pyunicodes

    Direct access to the underlying contiguous C array, with given type; e.g., myarray.data.as_ints.

    Functions

    The following functions are available to Cython from the array module:

    1. int resize(array self, Py_ssize_t n) except -1

    Fast resize / realloc. Not suitable for repeated, small increments; resizes underlying array to exactly the requested amount.

    1. int resize_smart(array self, Py_ssize_t n) except -1

    Fast creation of a new array, given a template array. Type will be same as template. If zero is True, new array will be initialized with zeroes.

    1. cdef inline array copy(array self)

    Make a copy of an array.

    1. cdef inline int extend_buffer(array self, char* stuff, Py_ssize_t n) except -1

    Efficient appending of new data of same type (e.g. of same array type) : number of elements (not number of bytes!)

      Extend array with data from another array; types must match.

      Set all elements of array to zero.