Debugging Python

Komodo can be used to debug Python programs locally or remotely, including debugging in CGI environments. The instructions below describe how to configure Komodo and Python for debugging. For general information about using the Komodo debugger, see Komodo Debugger Functions.

Tutorial

Configuring the Python Debugger

To specify which Python interpreter Komodo should use to debug and run Python programs locally:

  1. On the Edit menu, click Preferences.
  2. In the Preferences dialog box under Languages, click Python. Komodo searches for Python interpreters on your system and displays them in the drop-down list.
  3. If the preferred interpreter is in this list, click to select the interpreter. If not, click Browse to locate it.
  4. Click OK.

On the Debug menu or Debug Toolbar, click Go/Continue ('F5') or Step In ('F11') to invoke the debugging session. See Komodo Debugger Functions for full instructions on using Komodo's debugging functionality.

 

Using the Python Remote Debugger

When debugging a Python program remotely, the program is executed on the remote machine, and the debug output is sent to Komodo. Komodo controls the debugging session once the session starts on the remote machine.

 

Installing the Python Remote Debugger on the Remote Machine

To debug a Python program remotely, the Python debugger modules must be installed on the remote machine. These files can be found in the python/dbgp sub-directory of the Komodo installation and are also are also available for download from the Komodo Remote Debugging page.

To install the Python Remote Debugger:

  1. Copy all files from the python/dbgp sub-directory of the local Komodo installation to a directory on the remote machine. The Python Remote Debugger requires the logging module. To verify that this module installed, run the following command on the remote machine:
      python -c "import logging"
    
    If this command returns an "ImportError", copy the python/dbgp/logging sub-directory to the remote machine as well.
  2. On the remote machine, add the directory containing the copied files to the PYTHONPATH environment variable. For example, on Windows, if you copied the files to a directory called C:\debugger, enter the following at the command line:
      set PYTHONPATH=%PATH%;C:\debugger
    

 

Invoking the Python Remote Debugger

Python remote debugging sessions can be started from the command line or from within the Python program itself. Both methods require the installation of the Python remote debugger modules on the remote machine (see Installing the Python Remote Debugger).

 

Running dbgpClient.py from the Command Line

To start a Python remote debugging session from the command line:

  1. In Komodo, On the Debug menu, click Listen for Remote Debugger.
  2. Log in to the remote machine.
  3. On the remote machine, run the dbgpClient.py program:
        python dbgpClient.py -d <komodo_host:port> script.py [script args]
    

    The following options are available:

    • -d: Sets the hostname (or IP address) and port where Komodo or DBGP Proxy is running. See Debug|Listener Status in Komodo to check the current port setting.
    • -k: Sets the ide_key used with DBGP Proxy.
    • -h: Displays a complete list of options.

  4. A Python Debug tab opens in Komodo. Use 'F11' to Step In, or 'F5' (Go/Continue) to run to the first breakpoint. See Komodo Debugger Functions for full instructions on using Komodo's debugging functionality.

The port number set with the "-d" switch must match the port number configured in Komodo under Edit|Preferences|Debugger. Click Debug|Listener Status to check your current settings.

If you are connecting to a DBGP Proxy, be sure to specify an ide_key value with the "-k" switch. For example:

    python dbgpClient.py -d <komodo_host:port> -k <ide_key> script.py [script args]

Set the ide_key to the value listed in Debug|Listener Status|Proxy Key. It is taken from the environment variable specified under Proxy Key in Komodo's Debugger Preferences (USER or USERNAME by default).

 

Using dbgpClient Functions in Python Programs

To start a Python remote debugging session from within a Python program:

  • Ensure that the Python remote debugging programs are installed on the remote computer as per the instructions in Installing the Python Remote Debugger.
  • Import dbgpClient.py into your Python program (import dbgpClient) or import just the brk() function (from dbgpClient import brk).
  • Set a hard breakpoint with brk() one line above where you want the program to break. The brk() function takes the following arguments:
    • host: machine running Komodo or the DBGP Proxy (uses localhost if unspecified)
    • port: port to connect on (uses 9000 if unspecified)
    • idekey: key used to identify the debugging session to Komodo or the DBGP Proxy (uses the value of the USER or USERNAME environment variable if unspecified)
  • The brk() function connects to the host and port specified, then breaks on the current line of the script. Under local debugging, calling brk() causes the debugger engine to break on the current line, since the engine is already connected to Komodo.

The following script uses this method to initiate debugging:

	from dbgpClient import brk
	def foo():
	    print "hello ",
	    brk(host='mybox', port=3210)
	    print "world!"
	
	foo()
	

This example initiates a debugging connection to Komodo running on a machine called "mybox" on port 3210.

 

Just-in-Time Debugging

"Just-in-time debugging" allows the remote debugger to connect to Komodo if an uncaught exception occurs during execution. To prevent these uncaught exceptions from ending your program, add the following lines of code to the beginning of your script:

	from dbgpClient import brkOnExcept
	brkOnExcept(host='mybox', port=3210)

The script runs until an exception occurs, at which point a Python interactive shell starts in Komodo. The traceback appears in the Output tab, and the variables from the traceback appear in the Variables tabs. The Call Stack tab displays the call stack location of the exception.

The brkOnExcept() function takes the same arguments as brk(). As with brk(), brkOnExcept() attempts to connect to localhost on port 9000 with an idekey of USER or USERNAME if no arguments are specified.

Caveats

  • Output from the debug process appears on both the remote machine and in Komodo.
  • If dbgpClient.brk is executed when Komodo is not listening, the program runs without any breakpoint.

 

CGI Debugging

To debug CGI applications written in Python:

  • Configure Python to be used as the CGI (or embedded extension) for your Web server. For information on configuring Python, refer to the Python documentation.
  • Follow the steps outlined in Using dbgpClient Functions in Python Programs to call the Python remote debugger from within the application. Start the remote application through a web browser instead of running it from the command line.