Line coverage analysis for Cython modules
The coverage analysis tool for Python has recently
gained a plugin API that allows external tools to provide source code
information. Cython has line tracing support since release 0.19, but
the new API allows it to support coverage.py
for line coverage
reporting.
To test this, you need the latest developer versions of both coverage.py (pre-4.0) and Cython (post-0.22.0):
https://bitbucket.org/ned/coveragepy
https://github.com/cython/cython
Then, enable the Cython plugin in the .coveragerc
config file of
your project:
[run] plugins = Cython.Coverage
And compile your Cython modules with line tracing support. This can be done by putting the following two comment lines at the top of the modules that you want to trace:
# cython: linetrace=True # distutils: define_macros=CYTHON_TRACE=1
That's a double opt-in. The first line instructs Cython to generate
verbose line tracing code (and thus increase the size of the resulting
C/C++ file), and the second line enables this code at C compile time,
which will most likely slow down your program. You can also configure
both settings globally in your setup.py
script, see the Cython
documentation.
Then make sure you build your project in place (python setup.py
build_ext --inplace
) so that the generated C/C++ code files can be
found right next to the binary modules and their sources.
That's it. Now your Cython modules should show up in your coverage reports. Any questions, bug reports or suggestions regarding this new feature can be discussed on the Cython-users mailing list.
Update: Coverage reporting is now also available for code that
frees the GIL if the C macro CYTHON_TRACE_NOGIL=1
is set, i.e.:
# cython: linetrace=True # distutils: define_macros=CYTHON_TRACE_NOGIL=1
All reporting formats of coverage.py are supported: plain text, XML and annotated HTML sources.