Chapter 4. Debugging Cython

Since Cython programs compile down to their native code, we cannot use the Python debugger to step through your code. We can, however, use GDB. GNU Project Debugger (GDB) is a cross platform debugger. Python plugin support was added in version 7.0, which was used to add the Cython support into gdb as a simple script; this means that you can seamlessly step through the C/C++ code into Cython and back again.

When it comes to language binding, it's good practice to keep interfaces as simple as possible. This will make debugging much simpler until you are happy with your bindings in terms of resource management or stability. I will iterate over some GDB and caveats examples.

In this chapter, we will cover the following topics:

• Using GFB with Cython

• Cython caveats

Using GDB with Cython

To debug Cython, you need GDB >= 7.0. On Mac OS X Xcode, build tools have moved to LLVM and lldb as respective debuggers. You can install gdb using homebrew:

$ brew install gdb

We cannot use the Python debugger since the Cython code is compiled down to C/C++. Therefore, when debugging without the Cython plugin, you will be stepping through the generated C/C++ code, which won't be helpful as it won't understand the context of the Cython program.

Running cygdb

Cygdb is installed as a part of Cython and is a wrapper over GDB (it invokes GDB with arguments to set up the Cython plugin). Before you can debug the Cython code, we need to generate the debugging information. Just like C/C++, we need to specify compiler options to generated debuggable code we can pass –gdb when invoking the Cython compiler:

$ cython --gdb cycode.pyx

Note

Before you start debugging on Debian, you need to install the Python debug information package and GDB as it is not installed with build-essential...

Cython caveats

There are some caveats worth noting while mixing C and the Python code when it comes to Cython. It's a good idea to refer to these when building something to be production ready.

Type checking

You may have noticed that in the previous code examples, we were able to cast the void * pointer from malloc to our extension types using malloc. Cython supports some more advanced type checking as follows:

char * buf = <char *> malloc (sizeof (...))

In basic type casting, Cython supports <type?> for type checking:

char * buf  = <char *?> malloc (...)

This will do some type checking and throw an error if the type that is being cast is not a subclass of char *. So, in this case, it will pass; however, if you were to do the following:

cdef class A:
     pass
cdef class B (A):
     pass

def myfunc ():
    cdef A class1 = A ()
    cdef B class2 = B ()
    cdef B x = <B?> class1

This will return an error (at runtime):

Traceback (most recent call last):
  File "main.py", line...

Summary

Overall, we have seen some basic debugging using the cygdb wrapper. More importantly, we have examined some caveats and features of Cython. In the next chapter, we will see how we can bind C++ code and work with C++ constructs, such as templates and the STL library, in particular, directly from Cython. We will also see how the GIL can affect working with code in Cython and C/C++.