Komodo User Guide

Debugging Python

New to Python?
Check out the Python Tutorial

You can use Komodo to debug Python programs locally or remotely, including debugging in CGI environments. See below for instructions on configuring Komodo to debug Python programs. For general information about using the Komodo debugger, see Komodo Debugger Functions.

Configuring the Python Debugger

You must specify which Python interpreter Komodo should use to debug and run Python programs.

To specify the Python interpreter:

  1. From the Edit menu, select Preferences.
  2. In the Preferences dialog, click Python.
    Komodo looks for Python interpreters on your system and lists them in this dialog.
  3. If your preferred interpreter is in this list, click to select the interpreter.
    If your preferred interpreter is not in this list, enter the path and file name or click Browse to locate your preferred interpreter.
  4. Click OK.
Top

Using the Python Remote Debugger

Komodo's Remote Debugger is used to open a program on another machine and debug the program using Komodo. In order to use Komodo's remote debugger, you must first install the Python Remote Debugger programs on the remote machine, which call the machine running Komodo. Then you use the Komodo debugger on your local machine to debug your remote program.

Installing the Python Remote Debugger on the Remote Machine

The Python Remote Debugger is a collection of Python files that need to be installed on the remote machine. These files were installed in the callkomodo directory when you installed Komodo. By default, on Windows systems, the callkomodo directory is located under C:\Program Files\Komodo-x.x\. On Linux systems, the callkomodo directory is located beneath the root install directory. These files are also available for download from the Komodo Remote Debugging page.

To install the Python Remote Debugger:

  1. Copy the files from the callkomodo directory of your local machine to a directory on your remote machine.
  2. On the remote machine, add the callkomodo directory to the PYTHONPATH environment variable.
Top

Invoking the Python Remote Debugger

You have two choices for invoking remote debugging depending on the Python program on your remote machine:

Debugging a Standalone Python Script

If you have a standalone Python script on your remote machine, follow this procedure. Ensure you have installed the Python programs on the remote computer.

To debug a standalone Python script:

  1. On the local machine, select Listen for Remote Debugger from the Debug menu.
    A Listening for Connection dialog opens and indicates the port number for the process.
  2. Connect to your remote machine and log in.
  3. Run python callkomodo.py, and specify the following four items:
  • the hostname, the domain name of the machine on which you are running Komodo
  • the port number, as configured in the Debugger Preferences (by default, port 9000)
  • the program name
  • any options for the program

A connection will be established between the target process (on which callkomodo.py is executed) and the Komodo debugger. From then on, you can use the full Komodo debugging functionality, including setting breakpoints, stepping, viewing the call stack, and watching variables. The output from the debug process appears in the Output pane in the Komodo Workspace.

To stop the debugger:

  • From the Debug menu, select Stop
    or
  • Press Shift+F5

Example

For example, if you had the following situation:

  • Komodo is running on host mybox.mycompany.com, 
  • the Listen window is listening on port 9000
  • you want to debug the program spam.py 
  • and pass it the options "eggs -3"

On the remote machine, you would enter:

python callkomodo.py mybox.mycompany.com 9000 spam.py eggs -3

Top

Debugging an Embedded Python Application

If you have an embedded Python application on your remote machine, follow this procedure. Ensure you have installed the Python programs on the remote computer

You need to import callkomodo.py to your Python program. In your embedded Python application, find a line you want to break at and set a hard breakpoint one line above. This hard breakpoint is callkomodo.brk. When your program executes this line, it calls Komodo on your local machine for a debugger connection.

You also need to set the KODEBUG_HOSTNAME environment variable on your remote machine to point to the hostname running Komodo (your local machine).

To debug an embedded Python application:

  1. Connect to your remote machine and log in.
  2. Access the Python source program you want to debug.
  3. Import callkomodo into the Python source program. At some point earlier than the line you want to break at, enter the line:
    import callkomodo
  4. One line above the line of you want to break at, enter the following:
    callkomodo.brk(<'komodo_hostname'>,<komodo_port>)
    where <komodo_hostname> is the name or IP address of the machine running Komodo and <komodo_port> is the remote debugging port configured in Komodo's Preferences. For example:

    callkomodo.brk('232.12.32.15', 9000)

  5. Alternatively, you can set the variables KODEBUG_HOSTNAME (the name of the machine running Komodo) and KODEBUG_PORT (the remote debugging port configured in Komodo's Preferences) and then invoke callkomodo.brk() without arguments.

    On Apache web servers, the Apache configuration file can be used to set these variables. Add the line

    SetEnv KODEBUG_HOSTNAME komodo_hostname
    SetEnv KODEBUG_PORT komodo_port

    to the Apache configuration file. This can also be done within a VirtualHost directive. See the Apache documentation (httpd.apache.org/docs/) for more information on configuring Virtual Hosts. Note: You must enable the mod_env Apache module (see httpd.apache.org/docs/mod/mod_env.html) for the SetEnv directive to work.

  6. In the Komodo Workspace, go to the Debug menu and select Listen for Remote Debugger.
    A Listening for Connection window opens and indicates the port number for the process.
  7. Run the program on the remote machine.
  • When the program executes callkomodo.brk, it calls Komodo on your local machine for a debugger connection.
  • The remote program appears in the Komodo Workspace with an arrow below the line with callkomodo.brk.
  • From then on you can use the Komodo debugging functionality, including setting breakpoints, stepping, viewing the call stack, and watching variables.

Limitations for Debugging Embedded Python Applications

  • Output from the debug process appears on your remote machine and not in the output pane in the Komodo Workspace.
  • You cannot send input to the debug process using Komodo. You can only send input using your remote machine.
  • If the debugger steps into code that tries to dynamically interpret a string, such as the argument to an eval function, Komodo opens a file named <string> containing:
    # Source code unavailable
    - Your program still runs, but Komodo cannot display the file.
  • If a Python source file cannot be found during debugging, Komodo opens a file of the same name containing:
    # Source code unavailable
    - Your program still runs, but Komodo cannot display the file.
  • If callkomodo.brk is executed when Komodo is not listening, then your program runs without any breakpoint.
Top

Configuring Python for 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. Be sure to test that your Python programs are functioning properly before proceeding.
  • Refer to Debugging an Embedded Python Application. The procedure is identical except that instead of running the remote application, you access it through a web browser.
Top