JpyDbg plugin for NETBEANS and JEDITuser's guide

Figure 1.1.

http://www.sourceforge.net

--

JPyDbg is hosted and managed as a FSF sourceforge project. you can reach sourceforge JpyDebug project homepage and last news from here

JpyDbg is a Multi Ide Python / Jython development environment which has been originally implemented inside JEdit as a JEdit plugin . Starting with version 0.0.14 most of JEdit Python Development Environment have been made available from inside the Netbeans IDE as well as a standard NBM package.

Starting with version 0.0.11 JPyDbg is able to debug CPYTHON and a JPYTHON(JYTHON) sources.

I Started working on JpyDbg since summer of 2002 and as time goes on I added numerous complementary functionalities to it since. By beeing maintained by a Python / Java daily developper (who is by the way the first user of JpyDbg) most annoyances should be fixed quickly... BTW version number is still 0.0.xx just because I consider that even if the debugger is pretty stable now, there is still on going improvement on it , which makes me keep the current version number starting with 0.0.

As far as I know JPydbg was the first python debugger which implements the Jython and CPython debugging facility, which by the way make it also a very powerfull tool for checking the portability of python code between CPython and Jython.

Installing and using either netbeans or jedit is a prerequisite for using JPyDbg : jedit and netbeans are both opensource projects.

Usually version found at jpydbg site and in jedit downloadable pluggins are in sync ; so you can pick it at both locations ; But sometimes the version found at jpydg site may be more recent.

I Try to provide only stable versions allthough some bugs may pass through my checks.

Figure 1.2. JpyDbg clean client/server based debugging architecture

JPyDbg server side is a Python Module and the currently provided client side are written in Java , this implies that JPyDbg is platform independent and can be used on any platform where Python and Java are available.

The jedit jpydbg plugin may be easily automatically installed from jedit plugin central using the jedit Plugin Manager from inside jEdit. The only problem is that the available jpydbg version available from plugin central may not be the most recent version of jpydbg. In that case use the following procedure to install

jpydbg pluggin jar must be installed as usual in the JEdit jar directory details follow for UNIX/MAC OSX and WINDOWS

    rm .jedit/jars/jpydebug*.jar                                      # remove any previous version of jpydbg jar
    cp jpydebug-x.x.xx.jar .jedit/jars                                # copy last version of jpydebug jar under user .jedit home jars (visible for current user)
 or cp jpydebug-x.x.xx.jar $JEDIT_HOME/jars                           # copy jpydebug jar under $JEDIT_HOME/jars path (visible to multiple users if  
                                                                      # Jedit is under /usr/local + su root requested   
              

    delete C:\Documents and Settings\userid\.jedit\jars\jpydebug*.jar  # remove any previous version of jpydbg
    copy jpydebug-x.x.xx.jar C:\Documents and Settings\userid\.jedit\jars\jpydebug.jar # copy jpydebug jar under user .jedit home jars (current user)
 or copy jpydebug-x.x.xx.jar %JEDIT_HOME%\jars\                        # copy jpydebug jar under $JEDIT_HOME/jars path (visible to multiple users) 
              

A python counterpart module, used for the backend part of debugger is also provided in source format using a standard python module distribution , so a separate complementary jpydaemon-xxx.zip (where xxx represents the current version number of the module) is provided and need to be downloaded as well , unzipped into a work directory (/tmp).

Next in order to install the python backend debugger stuff for remote debugging just proceed as follow on the remote machine:

    cd /tmp
    unzip jpydaemon-xxx.zip
    python setup.py install   # root priviledges may be requested here on unix 
              

A running version of Jython is only requested if you plan to use the Jython debugging framework. Even if you only use Jython ; a working version of CPython is still requested , since the Python syntax checker uses the CPython AST tree analyzer

JEDIT : JPyDbg customization panels are made accessible through the Global options-pluggin-python-debugger's option menu bar

NETBEANS : JpyDbgcustomization panels are made accessibles through the Tools / jpydbg configuration menu.

Next the layout of the misc configuration panels are almost the same for both IDE environments

Figure 2.1. CPython options for JEDIT

Figure 2.2. CPython options for NETBEANS

Figure 2.3. JPython options for JEDIT

Figure 2.4. JPython options for NETBEANS

.

Figure 2.5. Debugger's options for JEDIT

Figure 2.6. Debugger's options for NETBEANS

Figure 2.7. JpyDbg debuggee's program argument settings for JEDIT

Figure 2.8. JpyDbg debuggee's program argument settings for NETBEANS

Figure 2.9. JpyDbg debuggee's PyLint options settings for JEDIT

Figure 2.10. JpyDbg debuggee's PyLint options settings for NETBEANS

Figure 2.11. JpyDbg python shell coloring and font chooser settings for JEDIT

Figure 2.12. JpyDbg python shell coloring and font chooser settings for NETBEANS

Starting with V0.0.10 version, JPyDbg is both able to handle standard CPYTHON debugging session as before , but alsos JPython debugging session as well. (BTW AFAIK JpyDbg is the only debugger able to handle Cross Python debugging).

This feature is very usefull when you need to maintain Python module compatibility between both available Python environments

This feature is also possible because JpyDbg debugging kernel is fully written in Python and inherits the standard bdb.py debugging module as a starting point

Switching from CPython debugging To Jython debugging is straigforward and provided through a simple toggle button on JpyDbg toolbar

Since The Jython debugging feature is new in V 0.0.10, it may be less stable than the CPython debugging environment

The choice between a CPython debugging session and a Jython one must be made before the debugging session starts , as soon as the debugger is active the JPython/CPython toggle button is disabled until the end of the debugging session.

Figure 3.1. JpyDbg Cpython debugging toggled

Figure 3.2. JpyDbg Jython debugging toggled

"""\
Equivalent to the ../awt/simple.py example but using swing components
instead of AWT ones.
"""

# This line will import the appropriate swing library for your system (jdk 1.1 or 1.2)
import org.python.core
from pawt import swing
import java
leaving =0

def exit(e): 
  leaving = 1 
  java.lang.System.exit(0)

frame = swing.JFrame('Swing Example', visible=1)
button = swing.JButton('Close Me!', actionPerformed=exit)
frame.contentPane.add(button)
frame.pack()
frame.show()

import time
while not leaving:
  time.sleep(1)
                  

Starting with V0.0.5 version of JPyDbg which integrates the SideKick plugging facility , JPyDbg automatically checks the current PythonSource view for Syntax errors and populates any python Syntax Error found inside the ErrorList as shown bellow.

Figure 4.1. JpyDbg python syntax error checking

As soon as a given Python source is syntaxically correct the structure of the vurrent view Python source will be displayed inside a Jedit SideKick windows as shown on the following figure :

Figure 4.2. JpyDbg python syntax error checking

All the above syntax and semantic goodies are provided through the call of the inspector.py python module checker which is part of the jpydbg python package

Depending on the way you configured your JEdit environment the Sidekick window may be either floating or docked on left or right side of the jedit ; the python structure is provided to the JPyDbg Java browser through an xml file having the same name as the py file but with an .xml extension.

The sidekick Python syntax tree provides an interesting way to use JEdit to develop complex Python project. The figure below shows JpyDbg debug session over the Zope kernel.

Figure 4.3. a JpyDbg Debugging session of Zope kernel

Inside This chapter , I will point out the most important usage diferences that you may encounter using jpydbg with NETBEANS or JEDIT

Since both NETBEANS and JEDIT have Java/Swing Based GUI A lot of panel are shared between both Plugin implementation ; this make the compatibility between both plugin easier to maintain as well ; By the way let me emphasize here about the nighmare it would have been to port this to the ECLIPSE / SWT framework ... Almost every GUI stuff should have been completely rewriten ... Don't bet on SWT/SWING compatibility box there ; it's just a Marketing toy !!!!

OK back to the JEDT/NETBEANS stuff : One of the main difference is the location of the debugging bar

WITH JEDIT : Since there is no Debugging standard framework defined for JEdit , the debugger toolbar is located in the 'NORTH area' of the 'Python Environment' window panel.

WITH NETBEANS : The debugging launcher bar has been integrated with the current selected Python source action bar ; and the Debugging actions follows the standard Netbean's debugger partern using the NETBEANS standard debugging bar. (On the first version ; the stack and variable debuger's frames are still hosted inside the JpyDbg panel as in jEdit ... But I plan to improve this topic in the near future.

The rest of the functionalities are the same for both IDE environments.

Figure 5.1. NETBEANS jpydbg python plugin overview

This chapter will describe a simple Python debugging session using JpyDbg pluggin.

Let's use the python source below as a sample source candidate for the debug session :

#
# A sample List returning function
#
def buildList():
    print "this will return a sample constant list back"
    list=["dave" , "mark" , "ann" , "phil"]
    return list
#
# A sample multiplication function
#
def multiply(  a , b ):
    print "this shall add " , a , "times " , b
    c = 0
    for i in range ( 0, long(a) ):
        c = c + long(b)
    return c
#
# Unit testing startup
#
if __name__ == '__main__':
    print "testing multiply = " , multiply ("5","6")
    print "testing multiply = " , multiply (5,6)
#    print "testing multiply = " , multiply (5,6,7)
    print "testing buildlist = " , buildList()    
                  

First start JEdit environment as usual and load the firstsample.py python source :

Figure 6.1. Jedit Python debugging integration overview

Two prerequisites are necessary in order to start a debugging session : you must choose a python source candidate and setup the command line arguments which will be populated to the __main__ python entry.

In order to define a python source candidate just bring your python program as current Jedit edited buffer , this action will populate the full path name to jpydbg toolbar textfield as follow :

Figure 6.2. candidate source to debugging session field

Next in order to set the debuggee's command line argv you just need to select an argv configuration key using the argument combo box located on the jpydbg toolbar :

Figure 6.3. combo box to be used to bind debuggee with an argument configuration

The selected configuration bind will be saved for later debugging session with the selected source.

Finallly in order to start debugging current source just push the green arrow located on the jpydbg toolbar.

The pluggin will then start the jpdaemon.py debuggin daemon and the debugging session will be active

The current source line will be highlited by a tiny arrow :

Figure 6.4. stopped in source illustration

setting a breakpoint at a given line in the source is achieved by clicking in the corresponding line gutter ; a red circle indicates that the breakpoint has been set . set Breakpoints are saved on disk inside jpydbg user's configuration file.

Figure 6.5. a breakpoint has been set

As soon as the debugger is active , the command field in the bottom of the debugging tabpane may be used to enter Python commands , corresponding results are populated inside the textarea panel above :

Figure 6.6. python shell dynamic command input

On top of JPyDbg pluggin , a button bar is made available and contains misc debugging action buttons :

Figure 6.7. debugging command button bar

from left to right corresponding button's actions are : Stop debugging session , Run , Step over , step into.

When clicking on the 'Variables' tabpane a view of the stack and the Global + Local variables values are displayed on the Screen inside the 'Python Object Memory Browser' panel ; Python Object instances are sorted 'by name' , object types icons are provided as a practical eye catcher between different object types and last but not least double clicking on final object nodes value provide the capalbility of changing the current object value. The call stack frame is also populated and stack positions are selectables from the corresponding combo box.

Figure 6.8. stack selection + Python execution value display and modification

finally when you need to stop current python debugging session , just click on the red cross button , the current python debugding session will be terminated and following display will show up on the screen indicating that the socket connection with the debugger's daemon is now over .

Figure 6.9. current python debugging session is over

One of the fundamental debugging functionality consists in the capability of changing variables value content during a debugging session.

Jpydbg provides multiple ways of addressing this functionality.

first one is through the python command line shell, as shown below for changing dynamicaly the multiply a and b parameters value of the multiply method.

Figure 7.1. changing a , b values thru python shell

second is through the variables tabpane, as shown below for changing dynamicaly the multiply a parameters value of the multiply method.

multiple values may be changed inside the table , the changes will be populated just before execution of next debugger instruction.

Figure 7.2. changing a values by double clicking the value field of the variable table

In this chapter will show how to start and operate remote debugging python sessions.

This functionality is not implemented yet for NETBEANS plugin ... It's in the todo list.

Beeing able to supervise and debug a remotely running Python program may be interesting when for instance you are not able to setup a GUI Jedit environment on the remote computer , or for debugging remotely runnnin daemons. We will now describe how to be able to use this functionality using jpydbg

Let's use the same python firstsample.py source as in previous chapter.

First we need to check that the configuration field 'temporary work directory' is pointing to en existing acceptable local work directory. This directory will be used to locally store the remote debugged python sources.

The first step will consist in pushing the yellow arrow button on the right of the toolbar in order to put the jpydbg in listening mode over an IP session ; the port used for listening on incoming connection is configured in the 'listening port' field of the jpydbg configuration panel.

As soon as the yellow arrow button has been pressed , jpydbg waits listening for incoming connections and the debug toolbar looks as follow :

Figure 8.1. jpydbg listening for incoming remote debug connection

Pressing the red cross will then terminate the listening state and return back to the inactive stopped state of the debugger.

Next action will consist in starting a jpydeamon.py debugging instance on the remote debugged station , in order to do that we only need to have a telnet or X11 session available , let's do that through a telnet jta windows plugging instance ( you may use also any external telnet or X11 window session to do that as well ):

Figure 8.2. Launch of the jpydaemon from a telnet session

the following parameters need to be provided at jpydaemon launch time:

jpydaemon.py desthostaddress destport debuggeesname [optional python debuggee's param]

The python import navigator panel has been introduced in version 0.0.9 of jpydbg , in order to provide a practical way of both managing the PYTHONPATH location for jpydbg session, quickly checking that requested modules inside a project are loaded without any error , and finally providing a complementary semantic navigation tools accross the python source modules used by a given python module.

to activate the import navigator panel from the Jedit Python environment just click on the 'Python Environment tabpane button , the following panel will show up for the jedit current source

Figure 9.1. initial view of the imports navigator pane

The left part of the pane represents a tree containing the python modules requested to be imported by the current jedit python source.

The right part of the pane represents the list of the directories appended to sys.path by during a debugging session : the directories where Python will look for a requested python module. This panel is the same as the one available inside the CPython / Jpython configuration panels

Element of the list may be updated by double clicking on the element

after selecting a row inside the PYTHONPATH table, clicking on the left mouse button over this table will show up a complementary popup menu , which may be used to add or remove elements to the path relative to the current selected row, or save the list on disk

The module tree on the left side of the pane may be used to recursively view the import semantics of a given python project , and to navigate between python module sources

The picture bellow shows a more sophisticated view of a python imports expanded tree in action

Figure 9.2. final overview of import navigator panel

This chapter asumes that pylint has been previously installed as described on the pylint site http://www.logilab.org/projects/pylint

As soon as the use pylint option is toggled in the pylint option pane ; pylint module is called on python source load and save actions ; pylint messages are shown inside the jEdit error list as shown on the screen shot below

pylint ERRORS and FATAL are populated as jEdit errors and located inside the source as red underlined lines ; a tiny red marker is also visible on the right gutter of the editor as well ; pointing the mouse on the erroneous line will popup a tooltiptext with the associated pylint error message inside.

pylint WARNINGS , CONVENTION and REFACTOR are populated as jEdit warnings and located inside the source as yellow underlined lines ; a tiny yellow marker is also visible on the right gutter of the editor as well ; pointing the mouse on the erroneous line will popup a tooltiptext with the associated pylint error message inside

To correct an error just modify the erroneous line inside the editor and save the source ; this action will relaunch pylint to check youor correction.

Figure 10.1. Source with pylint messages

The left part of the pane represents a tree containing the python modules requested to be imported by the current jedit python source.

The right part of the pane represents the list of the directories appended to sys.path by during a debugging session : the directories where Python will look for a requested python module. This panel is the same as the one available inside the CPython / Jpython configuration panels

Element of the list may be updated by double clicking on the element

after selecting a row inside the PYTHONPATH table, clicking on the left mouse button over this table will show up a complementary popup menu , which may be used to add or remove elements to the path relative to the current selected row, or save the list on disk