Scripting PyDev with Jython

Version 1.0.4 has added the option of scripting PyDev with Jython, and this article aims at explaining how it works and how to add your own scripts to PyDev.

What we will see is the integration that will allow you to listen to the events generated by the editor (PyEdit class) and respond accordingly.

NOTE: In the end of this article, there are links to view things at the cvs with the referenced classes.

The examples that we will see are located in the project org.python.pydev.jython under the folder jysrc.

The first thing you'll want to do is configure the preferences so that you can see the output of the scripts in the console (so that you can do some prints and actually see them).

Now that you have your preferences correctly set, let's make some changes to see what we can play with... You just need PyDev installed (we will change the scripts that come with the default installation, so, there is no need to actually download the PyDev sources, altough it might be worth getting it for having it as a reference).

So, in your PyDev installation, go to the jysrc folder of the org.python.pydev.jython plugin that is part of PyDev (this is located under the eclipse install... something as .../eclipse/plugins/org.python.pydev.jython_1.0.4/jysrc)

You'll notice some files that start with pyedit_ (there could be many, but for this article, we'll only care about pyedit_example.py, pyedit_example2.py and pyedit_next_problem.py).

The first thing you want to know about is that the name of the script is something important in the integration. All the scripts that will listen to the PyEdit class (this is the PyDev Editor) have to start with pyedit_. Another interesting thing is that changes are gathered without the need of restarting Eclipse (but as we will be listening to the editor, you might have to reopen it, so that it triggers all of the events we may want to listen).

So, now that you're ready, let's open the file pyedit_example.py and uncomment the last line of code. After, if you close a PyDev Editor and open it again, you'll notice that you'll have some messages showing in the console, with the 'print' statement that was uncommented (and now, if you go and comment it again, you'll stop seeing the messages again, so, you can see that all the changes are automatically reloaded whenever you change the script).

TIP: You may just drag and drop files from your filesystem into PyDev to edit those files.

The image below shows the ouput you should get from uncommenting the line in the example above.

Now that you've already seen how 'easy' it should be to change an existing script and get it to work, let's now create our own script.

The first thing you want to do is create a jython project (call it pydev_scripts), then, go to the scripting preferences and put the src directory from that project in the Location of additional scripts.

Now, under the src folder of that project, create a pyedit_test1.py file. Just write print '>>', cmd and save it... When you save it, you'll notice in the console something as:

---> reloading
E:/eclipse_testing_workspace/pydev_additional_scripts/src/pyedit_test1.py
>> onSave

You will receive (currently) 4 commands:

onSetDocument: You can then link your commands to listen to changes in the document if you want (besides the standard 'editor' and 'cmd' variables, you will also be able to have access to a 'document' variable (it is an IDocument).
onCreateActions: It is called only once when the actions are being created. You should handle it to add your own actions in the PyEdit (the pyedit_example2.py shows the default way of doing this)
onSave: want to do something when the PyEdit saves its content? That's your chance...
onDispose: Called when the PyEdit is going to dispose itself.

And that's it. We've seen how to create scripts and make PyDev load them for editor actions. If you want to keep on, you should check some example scripts that come with PyDev (those come in the org.python.pydev.jython_xxx/jysrc folder – there are links to them in the resources section in the end of this page). You should check:

pyedit_example.py: this is the simple example we covered here, to see the output of the commands we have
pyedit_example2.py: this is an example on how to bind some action to the 'default' keybindig structure that is provided by PyDev for jython scripts.
pyedit_next_problem.py: This is the implementation of the go to next problem that is implemented at PyDev. Disclaimer: the way it binds to the keybinding would require you to change the plugin.xml as it is based on the Eclipse structure, which is much more static than the way of binding things to the PyDev editor presented to you on pyedit_example2.py (it would require changes in the plugin.xml file of the plugin, but on the other way, it would also allow you to change the keybinding for it).

IMPORTANT NOTES:

The directories that are added to the PYTHONPATH are the Lib dir from jython and the jysrc dir (both under the org.python.pydev.jython plugin).
There is one interpreter for each PyEdit, so, while it is not reused across editors, it is reused in the same editor... So, be careful not to mess with global things. Ideally, you should only rely on things that the editor will pass you (such as the editor, the cmd, the document...)
Some commands rely on having some specific command, so, you might not 'see' the change until you restart the editor (this is the case when registering actions depending on: onCreateActions).
If you have further doubts about scripting, you can register at the pydev-code list at sourceforge, and ask them there, and if you've been able to create some nice, useful script, you can contribute it back to PyDev by creating a bug and attaching your script there.

So, that's it... Happy Scripting!

Resources (links to github)

Scripting PyDev with Jython

PyDev development