Introduction

This tutorial is intended for technical artists or developers who already know how to run Python scripts in Nuke.

What is debugging? If you already know, skip on ahead.

Debugging offers you the ability to pause code execution and interact with a live session. Most debuggers allow you to run commands, view variables, and step (run) through lines of code one at a time. They allow you to view the call "stack". (e.g. which methods have called which methods).

Some even allow you to change variables or import modules in the middle of code execution, and to view the call stack, (e.g. which methods have called which methods). PyDev for Eclipse IDE supports all of the above, and as open source it's free to download and use!

Local debugging Python scripts with Eclipse

At my last studio Eclipse was our IDE of choice and we used it for all of our python writing needs. You'll need Eclipse installed with the PyDev plugin.

Running the active python script in debug mode is straightforward. Press F11 on your keyboard or the bug button : 

In a nutshell, this is how it works. F11 in your keyboard runs the current script- in debugging mode. It will pause at the breakpoints you set. You can set breakpoints by double clicking on the margin to the left of line numbers. For example, double click on the grey space just to the left of the number 13 in your editor to tell the program (debugger) to pause when it reaches that line. When it has paused, you have access to shortcuts to work through the action; F5 will step into any function/method calls, F6 will move simply to the next line after executing the current line, F7 will finish executing the current function/clause and step out/return to the host call, and finally F8 will resume running as normal until the debugger finds another breakpoint. When the debugger is paused, you can run commmands in the Console (cool!) and view/change variables in the Variables window.

For a more detailed breakdown, check out this page.

http://pydev.org/manual_adv_debugger.html 

Remote debugging another application or computer

Now the fun begins. This is how we can debug our scripts IN Nuke from Eclipse. We can view the modules in memory (including nuke) and read stdout text returned from Nuke.

First you you need to be in Debug Perspective. If the button isn't there as it is in the screenshot, you'll need to use Window > Open Perspective > Other to find the PyDev debug perspective.

Secondly you'll need to have a debug server running, which you can access as indicated above. 

The debug server will listen for any scripts attempting to connect to it, and once the connection is made, you're in control of the session from Eclipse regardless of where the script is running, be it on your machine, in another program, or even on another computer. The only catch is the file-path needs to be the same- so debugging on another machine takes extra care.

Now the script you wish to debug must have access to the pydevd module which comes with PyDev. This is how I set up the path on my computer. This goes into the top of the script I want to step through in Nuke. This path will vary depending on your version, so don't just copy-paste what I've got here.

import sys
sys.path.append(r'C:/eclipse/plugins/org.python.pydev_2.7.4.2013051601/pysrc')

Alternatively you can copy the folder into your PYTHONPATH.  By appending the path into the sys module, I have given this python session (only) the ability to import pydevd, which it needs to communicate with the debug server.

import pydevd

Next, the settrace() method is what connects the script to the debugger server. 

Best yet- with Nuke- you can tell the python script to send text and errors to the Eclipse console. Note these optional arguments in settrace().

pydevd.settrace(stdoutToServer=True, stderrToServer=True, suspend=False)

In this screenshot I've imported a script in Nuke which has triggered Eclipse to stop at the highlighted line. Now I can inspect the nuke module, send commands to Nuke via the Console, view variables, and step through code. 

Finally, you can also debug a script over the local area network (LAN) running on another machine by specifying an IP address.

pydevd.settrace('192.168.5.108', stdoutToServer=True, stderrToServer=True, suspend=False)

Might come in handy next time that comper has a bug you can't replicate?

Important notes

Debugging does not work well with Threads- if you're running python Threads or QThreads in your application, debugging can be tricky. I recommend making an additional method to permit non-threaded operation as a backup for ease of debugging.

Here is an example of how I've done so in one python Qt application.

Threaded Class declaration

class Interface(QThread):
   def __init__(self, **kwargs):
       QThread.__init__(self)
   def non_threaded_run(self):
       # by not calling QThread.start() we bypass Qt's thread creation methods
       self.run()
       
   def run(self):
       # this method is called by the QThread.start() method which creates a thread
       self.action = pipeline.action('AutomaticCompAction')
       self.action.execute()

Summary

After asking colleagues if they knew how to debug in Maya or Nuke, I was surprised to find that few TDs actually were aware of how to debug in the first place! Coming from a background of Mel and PyMel in Maya, most of the technical developers I worked with just were unaware of this time-saving technique. So after running a training session, this tutorial is my attempt to help other TDs have an easier time developing code for Nuke.