Debugging tools

pyglet includes a number of debug paths that can be enabled during or before application startup. These were primarily developed to aid in debugging pyglet itself, however some of them may also prove useful for understanding and debugging pyglet applications.

Each debug option is a key in the pyglet.options dictionary. Options can be set directly on the dictionary before any other modules are imported:

import pyglet
pyglet.options['debug_api'] = False

They can also be set with environment variables before pyglet is imported. The corresponding environment variable for each option is the string PYGLET_ prefixed to the uppercase option key. For example, the environment variable for debug_api is PYGLET_DEBUG_API. Boolean options are set or unset with 1 and 0 values.

A summary of the debug environment variables appears in the table below.

Option	Environment variable	Type
debug_font	PYGLET_DEBUG_FONT	bool
debug_api	PYGLET_DEBUG_API	bool
debug_api_trace	PYGLET_debug_api_trace	bool
debug_api_trace_args	PYGLET_debug_api_trace_ARGS	bool
debug_graphics_batch	PYGLET_DEBUG_GRAPHICS_BATCH	bool
debug_lib	PYGLET_DEBUG_LIB	bool
debug_media	PYGLET_DEBUG_MEDIA	bool
debug_trace	PYGLET_DEBUG_TRACE	bool
debug_trace_args	PYGLET_DEBUG_TRACE_ARGS	bool
debug_trace_depth	PYGLET_DEBUG_TRACE_DEPTH	int
debug_win32	PYGLET_DEBUG_WIN32	bool
debug_x11	PYGLET_DEBUG_X11	bool

The debug_media and debug_font options are used to debug the pyglet.media and pyglet.font modules, respectively. Their behaviour is platform-dependent and useful only for pyglet developers.

The remaining debug options are detailed below.

Debugging OpenGL

The debug_graphics_batch option causes all Batch objects to dump their rendering tree to standard output before drawing, after any change (so two drawings of the same tree will only dump once). This is useful to debug applications making use of Group and Batch rendering.

Error checking

The debug_api option intercepts most OpenGL calls and calls glGetError afterwards (it only does this where such a call would be legal). If an error is reported, an exception is raised immediately.

This option is enabled by default unless the -O flag (optimisation) is given to Python, or the script is running from within a py2exe or py2app package.

Tracing

The debug_api_trace option causes all OpenGL functions called to be dumped to standard out. When combined with debug_api_trace_args, the arguments given to each function are also printed (they are abbreviated if necessary to avoid dumping large amounts of buffer data).

Tracing execution

The debug_trace option enables Python-wide function tracing. This causes every function call to be printed to standard out. Due to the large number of function calls required just to initialise pyglet, it is recommended to redirect standard output to a file when using this option.

The debug_trace_args option additionally prints the arguments to each function call.

When debug_trace_depth is greater than 1 the caller(s) of each function (and their arguments, if debug_trace_args is set) are also printed. Each caller is indented beneath the callee. The default depth is 1, specifying that no callers are printed.

Platform-specific debugging

The debug_lib option causes the path of each loaded library to be printed to standard out. This is performed by the undocumented pyglet.lib module, which on Linux and Mac OS X must sometimes follow complex procedures to find the correct library. On Windows not all libraries are loaded via this module, so they will not be printed (however, loading Windows DLLs is sufficiently simple that there is little need for this information).

Linux

X11 errors are caught by pyglet and suppressed, as there are plenty of X servers in the wild that generate errors that can be safely ignored. The debug_x11 option causes these errors to be dumped to standard out, along with a traceback of the Python stack (this may or may not correspond to the error, depending on whether or not it was reported asynchronously).

Windows

The debug_win32 option causes all library calls into user32.dll, kernel32.dll and gdi32.dll to be intercepted. Before each library call SetLastError(0) is called, and afterwards GetLastError() is called. Any errors discovered are written to a file named debug_win32.log. Note that an error is only valid if the function called returned an error code, but the interception function does not check this.