Debugging your Cython program

Cython comes with an extension for the GNU Debugger that helps users debugCython code. To use this functionality, you will need to install gdb 7.2 orhigher, built with Python support (linked to Python 2.6 or higher).The debugger supports debuggees with versions 2.6 and higher. For Python 3,code should be built with Python 3 and the debugger should be run withPython 2 (or at least it should be able to find the Python 2 Cythoninstallation). Note that in recent versions of Ubuntu, for instance, gdbinstalled with apt-get is configured with Python 3. On such systems, theproper configuration of gdb can be obtained by downloading the gdbsource, and then running:

  1. ./configure --with-python=python2
  2. make
  3. sudo make install

The debugger will need debug information that the Cython compiler can export.This can be achieved from within the setup script by passing gdb_debug=Trueto cythonize():

  1. from setuptools import Extension, setup
  2.  
  3. extensions = [Extension('source', ['source.pyx'])]
  4.  
  5. setup(..., ext_modules=cythonize(extensions, gdb_debug=True))

For development it’s often helpful to pass the —inplace flag tothe setup.py script, which makes setuptools build your project“in place”, i.e., not in a separate build directory.

When invoking Cython from the command line directly you can have it writedebug information using the —gdb flag:

  1. cython --gdb myfile.pyx

Running the Debugger

To run the Cython debugger and have it import the debug information exportedby Cython, run cygdb in the build directory:

  1. $ python setup.py build_ext --inplace
  2. $ cygdb
  3. GNU gdb (GDB) 7.2
  4. ...
  5. (gdb)

When using the Cython debugger, it’s preferable that you build and run your codewith an interpreter that is compiled with debugging symbols (i.e. configuredwith —with-pydebug or compiled with the -g CFLAG). If your Python isinstalled and managed by your package manager you probably need to install debugsupport separately. If using NumPy then you also need to install numpy debugging, or you’llsee an import error for multiarray.E.G. for ubuntu:

  1. $ sudo apt-get install python-dbg python-numpy-dbg
  2. $ python-dbg setup.py build_ext --inplace

Then you need to run your script with python-dbg also. Ensure that whenbuilding your package with debug symbols that cython extensions are re-compiledif they had been previously compiled. If your package is version controlled, youmight want to perform git clean -fxd or hg purge —all before building.

You can also pass additional arguments to gdb:

  1. $ cygdb /path/to/build/directory/ GDBARGS

i.e.:

  1. $ cygdb . -- --args python-dbg mainscript.py

To tell cygdb not to import any debug information, supply — as the firstargument:

  1. $ cygdb --

Using the Debugger

The Cython debugger comes with a set of commands that support breakpoints,stack inspection, source code listing, stepping, stepping over, etc. Mostof these commands are analogous to their respective gdb command.

  • cy break breakpoints…
  • Break in a Python, Cython or C function. First it will look for a Cythonfunction with that name, if cygdb doesn’t know about a function (or method)with that name, it will set a (pending) C breakpoint. The -p option canbe used to specify a Python breakpoint.

Breakpoints can be set for either the function or method name, or they canbe fully “qualified”, which means that the entire “path” to a function isgiven:

  1. (gdb) cy break cython_function_or_method
  2. (gdb) cy break packagename.cython_module.cython_function
  3. (gdb) cy break packagename.cython_module.ClassName.cython_method
  4. (gdb) cy break c_function

You can also break on Cython line numbers:

  1. (gdb) cy break :14
  2. (gdb) cy break cython_module:14
  3. (gdb) cy break packagename.cython_module:14

Python breakpoints currently support names of the module (not the entirepackage path) and the function or method:

  1. (gdb) cy break -p python_module.python_function_or_method
  2. (gdb) cy break -p python_function_or_method

Note

Python breakpoints only work in Python builds where the Python frameinformation can be read from the debugger. To ensure this, use aPython debug build or a non-stripped build compiled with debugsupport.

  • cy step
  • Step through Python, Cython or C code. Python, Cython and C functionscalled directly from Cython code are considered relevant and will bestepped into.
  • cy next
  • Step over Python, Cython or C code.
  • cy run
  • Run the program. The default interpreter is the interpreter that was usedto build your extensions with, or the interpreter cygdb is run within case the “don’t import debug information” option was in effect.The interpreter can be overridden using gdb’s file command.
  • cy cont
  • Continue the program.
  • cy up
  • cy down
  • Go up and down the stack to what is considered a relevant frame.
  • cy finish
  • Execute until an upward relevant frame is met or something haltsexecution.
  • cy bt
  • cy backtrace
  • Print a traceback of all frames considered relevant. The -a optionmakes it print the full traceback (all C frames).
  • cy select
  • Select a stack frame by number as listed by cy backtrace. Thiscommand is introduced because cy backtrace prints a reversed stacktrace, so frame numbers differ from gdb’s bt.
  • cy print varname
  • Print a local or global Cython, Python or C variable (depending on thecontext). Variables may also be dereferenced:
  1. (gdb) cy print x
  2. x = 1
  3. (gdb) cy print *x
  4. *x = (PyObject) {
  5.     _ob_next = 0x93efd8,
  6.     _ob_prev = 0x93ef88,
  7.     ob_refcnt = 65,
  8.     ob_type = 0x83a3e0
  9. }
  • cy set cython_variable = value
  • Set a Cython variable on the Cython stack to value.
  • cy list
  • List the source code surrounding the current line.
  • cy locals
  • cy globals
  • Print all the local and global variables and their values.
  • cy import FILE…
  • Import debug information from files given as arguments. The easiest way toimport debug information is to use the cygdb command line tool.
  • cy exec code
  • Execute code in the current Python or Cython frame. This works likePython’s interactive interpreter.

For Python frames it uses the globals and locals from the Python frame,for Cython frames it uses the dict of globals used on the Cython moduleand a new dict filled with the local Cython variables.

Note

cy exec modifies state and executes code in the debuggee and istherefore potentially dangerous.

Example:

  1. (gdb) cy exec x + 1
  2. 2
  3. (gdb) cy exec import sys; print sys.version_info
  4. (2, 6, 5, 'final', 0)
  5. (gdb) cy exec
  6. >global foo
  7. >
  8. >foo = 'something'
  9. >end

Convenience functions

The following functions are gdb functions, which means they can be used in agdb expression.

  • cycname(_varname)
  • Returns the C variable name of a Cython variable. For globalvariables this may not be actually valid.
  • cycvalue(_varname)
  • Returns the value of a Cython variable.
  • cyeval(_expression)
  • Evaluates Python code in the nearest Python or Cython frame and returnsthe result of the expression as a gdb value. This gives a new referenceif successful, NULL on error.
  • cy_lineno()
  • Returns the current line number in the selected Cython frame.

Example:

  1. (gdb) print $cy_cname("x")
  2. $1 = "__pyx_v_x"
  3. (gdb) watch $cy_cvalue("x")
  4. Hardware watchpoint 13: $cy_cvalue("x")
  5. (gdb) cy set my_cython_variable = $cy_eval("{'spam': 'ham'}")
  6. (gdb) print $cy_lineno()
  7. $2 = 12

Configuring the Debugger

A few aspects of the debugger are configurable with gdb parameters. Forinstance, colors can be disabled, the terminal background colorand breakpoint autocompletion can be configured.

  • cy_complete_unqualified
  • Tells the Cython debugger whether cy break should also completeplain function names, i.e. not prefixed by their module name.E.g. if you have a function named spam,in module M, it tells whether to only complete M.spam or also justspam.

The default is true.

  • cy_colorize_code
  • Tells the debugger whether to colorize source code. The default is true.
  • cy_terminal_background_color
  • Tells the debugger about the terminal background color, which affectssource code coloring. The default is “dark”, another valid option is“light”.

This is how these parameters can be used:

  1. (gdb) set cy_complete_unqualified off
  2. (gdb) set cy_terminal_background_color light
  3. (gdb) show cy_colorize_code