Debugging

pikepdf does a complex job in providing bindings from Python to a C++ library, both of which have different ideas about how to manage memory. This page documents some methods that may help should it be necessary to debug the Python C++ extension (pikepdf._qpdf).

Enabling QPDF tracing

Setting the environment variables TC_SCOPE=qpdf and TC_FILENAME=your_log_file.txt will cause libqpdf to log debug messages to the designated file. For example:

env TC_SCOPE=qpdf TC_FILENAME=libqpdf_log.txt python my_pikepdf_script.py

Compiling a debug build of QPDF

It may be helpful to create a debug build of QPDF.

Download QPDF and compile a debug build:

# in QPDF source tree
cd $QPDF_SOURCE_TREE
./configure CFLAGS='-g -O0' CPPFLAGS='-g -O0' CXXFLAGS='-g -O0'
make -j

Valgrind

Valgrind may also be helpful - see the Python documentation for information on setting up Python and Valgrind.