Set up IPython for Plone Development

IPython is a powerful interactive Python shell that can be used with Zope to aid in debugging issues in your Plone development activities. Syntax highlighting, tab completion and code introspection are just a few reasons to use it.

Think of the Zope-enabled IPython shell as bin/instance debug on steroids. When you start up the default Zope instance debugger, you are only given an app variable to access the current Zope instance. The IPython Zope profile enhances this with some useful defaults. It sets the variable portal to the first Plone site that it finds, sets up a dummy request on it and then does a setSite to make the component architecture work properly. There is also a utils object that is set up to allow you to sync the database, commit your changes, switch users and a host of other things. This gives you a series of effective tools to improve your Plone development practices.

A while back, Kees Hink wrote up a blog post about using IPython with the powerful content management system Plone 4. Since then, a newer version of IPython has come out and is no longer compatible with Python 2.4. This post will help you get it working with Python 2.4 and IPython 0.10 (for Plone sites on version 3.x or earlier), then Python 2.6 and IPython 0.11 or 0.12 (for Plone sites running Plone 4+).

Add Zope enabled IPython to buildout

We will assume that your Zope instance is created with a part named [instance] and, in the case of Plone 3, Zope is installed with a part called [zope2]. Here is what the Zope enabled IPython part looks like (uncomment the Plone 3 lines if needed).

[buildout]
parts =
# NOTE: You will have a zope2 part if using Plone 3
#    zope2
    instance
    ...
    ipzope
versions = version

[versions]
...
# NOTE: Use IPython 0.10 for Plone 3
#ipython = 0.10.2
ipython = 0.12

[ipzope]
recipe = zc.recipe.egg
eggs = ipython ${instance:eggs}
initialization =
    import sys, os
    # NOTE: Include this line for Plone 3
    #os.environ["SOFTWARE_HOME"] = "${instance:zope2-location}/lib/python"
    os.environ["INSTANCE_HOME"] = "${instance:location}"
    sys.argv[1:1] = "--profile zope2".split()
# NOTE: Include this line for Plone 3
#extra-paths = ${instance:zope2-location}/lib/python
scripts = ipython=ipzope

Notice that the --profile option is new, they removed the -p option in the latest IPython. The --profile still works with IPython 0.10, so we can keep that option for both versions of our part. We are also calling the profile zope2 instead of the normal zope. This is because IPython 0.10 was bundled with the zope profile, so we won't be able to use our new and improved profile unless we rename it.

Set up the zope2 IPython profile

Now that we have this added to our buildout, we need to get IPython set up with the profile. This is where things get difficult. The profile format has changed from 0.10 to 0.12, this means we should make a copy before we do anything else. This directory will only be present if you have already used IPython in the past.

$ cd
$ cp -r .ipython .ipython_0.10

If you don't have an IPython directory, running ipython or bin/ipzope will create one for you. The 0.10 version will tell you that it is creating it, the 0.12 version just silently does it. Let's go ahead and create the config skeleton.

$ cd path/to/buildout
$ bin/ipzope

Now let's add in the Zope profile. I have merged the Plone 4 branch that Kees created and fixed up a few other things, so we can now use the trunk. Let's check that out for use later.

$ cd
$ svn co http://svn.plone.org/svn/collective/dotipython/trunk/ .dotipython

Now let's symlink into the proper places. The 0.10 profile expects this to be a file named ipy_profile_<name>.py, where <name> is the profile name.

$ cd ~/.ipython
$ ln -s ~/.dotipython/ipy_profile_zope.py ipy_profile_zope2.py

Notice that we have renamed it to zope2 here to avoid the clash with the profile included with IPython.

Now let's add a 0.12 friendly version. The latest version expects a profile to be a directory in the format profile_<name>. The actual Python file will live in a startup sub-folder of the profile.

$ cd ~/.ipython
$ mkdir -p profile_zope2/startup
$ cd profile_zope2/startup
$ ln -s ~/.dotipython/ipy_profile_zope.py .

In this case, it doesn't matter what the name of the Python file is inside the startup directory. IPython will just read each file in alphabetically.

Now we can start up ipzope and we will have all of the Zope features that we are accustomed to.

$ cd path/to/buildout
$ bin/ipzope

Just remember that you will have to change the [ipzope] part slightly and require ipython = 0.10 for use on Plone 3.

Working with 0.10 and 0.11+

The last nagging issue that you will run into is that when you run a IPython 0.12 shell, it will automatically upgrade your ~/.ipython directory. If you want the prompt to work correctly with 0.10, you will have to have a copy of your ipythonrc and ipy_user_conf.py files handy to put back in place. We can use the copy we made earlier.

$ cp ~/.ipython_10/ipythonrc ~/.ipython/.
$ cp ~/.ipython_10/ipy_user_conf.py ~/.ipython/.

Now you can use the 0.10 version properly again. If you don't have a copy of a 0.10 ~/.ipython, you can run the 0.10 version of ipython to generate a new ~/.ipython directory (you will have to move the current one out of the way first).

Conclusion

If you are doing Plone development without the use of a good interactive debugger, you are missing out because you can't run code interactively and figure out an issue efficiently. Try setting up IPython or try out bpython for an alternate option. This will take your Plone development to the next level by getting you closer to the code and making you more productive.

UPDATE: To use the 0.10 version after having used 0.12, you need the ipy_user_conf.py also. Instructions above updated.