Tutorial
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.
Debugger commands can be accessed from the Debug menu, by shortcut keys, or from the Debug Toolbar. For a summary of debugger commands, see the Debugger Command List.
Note: Breakspoints will not work with the Psyco Python extension enabled. The Komodo FAQ has a work-around solution.
To specify which Python interpreter Komodo should use to debug and run Python programs locally:
On the Debug menu or Debug Toolbar, click Go/Continue or Step In to invoke the debugging session. See Komodo Debugger Functions for full instructions on using Komodo's debugging functionality.
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.
To debug a Python program remotely, the Python debugger client package must be installed on the remote machine. Packages are available for download from the Komodo Remote Debugging page. Alternatively, if your remote machine uses the same platform as the machine on which you installed Komodo, you can get the Python debugger client files from the pythonlib and bin subdirectories of the Komodo installation directory for your platform. The locations are as follows:
Windows
<komodo-install-directory>\lib\support\dbgp\pythonlib\ <komodo-install-directory>\lib\support\dbgp\bin
Linux
<komodo-install-directory>/lib/support/dbgp/pythonlib/ <komodo-install-directory>/lib/support/dbgp/bin
Mac OS X
<komodo-install-directory>/Contents/SharedSupport/dbgp/pythonlib/ <komodo-install-directory>/Contents/SharedSupport/dbgp/bin
To install the Python Remote Debugger:
logging
package, which is included in Python 2.3 and
later. However, if you have Python 2.2 (the earliest supported version),
you must download and
install the logging package. To verify that the
logging
package is installed correctly, run the
following command:
python -c "import logging; print 'ok'"If this command prints the word "ok", you can move to the next step. If this command results in an
ImportError
,
you need to resolve the error before continuing.
set PYTHONPATH=%PYTHONPATH%;C:\debuggerTo verify that the setup is correct, run the following command:
python -c "import dbgp.client; print 'ok'"If this command prints the word "ok", you can move to the next step. If this command results in an
ImportError
then you need to resolve the error before continuing.
Tip: Placing the pydbgp.py script in a directory that is on your PATH environment variable, makes the script easier to run. On Windows, also make sure that your PATHEXT environment variable includes .py. On Linux and Mac OS X, ensure that the pydbgp script is executable by running this command:
chmod u+x path/to/pydbgpNow try running this command:
pydbgp --helpIf the setup is correct, the internal help documentation for running pydbgp is displayed.
Note: The debugging client relies on certain
core python library files (e.g. sys
,
os
, getopt
, socket
,
types
). If you have added custom modules to your
python site-packages, PYTHONPATH
or
sys.path
with the same name as those imported by
pydbgp
, the debugger may not work properly.
Python remote debugging sessions are started in one of three ways:
dbgp.client.brk()
directly from within your
Python program code.To start a Python remote debugging session from the command line:
python -S path/to/pydbgp.py -d host:port your-script.pywhere host:port identifies the port on which Komodo is listening. By default, Komodo listens for remote debugger connections on port 9000. For example, if the "remote" machine is the same machine on which Komodo is running, start a debugging session with this command:
python -S path/to/pydbgp.py -d localhost:9000 your-script.py
Other options for using the pydbgp.py driver are available by running:
python -S path/to/pydbgp.py --help
If you are connecting to a DBGP Proxy, you
must specify an ide_key
value with the
-k
option to pydbgp.py. Listener port
and DBGP Proxy settings are configurable via
Edit|Preferences|Debugger. Select
Debug|Listener Status to view the current
settings.
Note: If your application requires that sitecustomize.py is loaded, you must run Python with the -S argument. The debugger will load site.py at the appropriate time. Komodo is unable to debug sitecustomize.py due to how Python handles loading of that file.
Note: If you followed the tip described in Installing the Python Remote Debugger the basic command is:
pydbgp -d host:port your-script.py
dbgp.client.brk()
in your Python ProgramsTo break into a remote debugging session directly from within your Python code:
brk()
function in the
dbgp.client
module to set a hard breakpoint. For
example, the following simple Python script will break into a
debugging session when execution reaches the brk()
call:
from dbgp.client import brk def foo(): print "Hello, World!" brk(host="mybox", port=9000) print "Goodbye."
The brk()
function supports the following
arguments:
localhost
if unspecified)"Just-in-time debugging" allows the remote debugger to connect to Komodo if an uncaught exception occurs during execution (i.e. if a Python exception reaches the top level of your Python program). By adding the following lines of code to the beginning of your script, you can trap and explore the execution state of your Python program when an exception reaches the top level:
from dbgp.client import brkOnExcept brkOnExcept(host='mybox', port=9000)
If and when an exception reaches the top level of your Python program, a post-mortem debugging session is started in Komodo at the line at which the exception is raised. The debug session is automatically placed in interactive mode so that you can inspect the current program environment, exactly like a Python interactive shell.
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.
To debug CGI applications written in Python:
dbgp.client
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.