Where's the source, Luke? How to find and debug the code behind Plone Paul Bugni < pbugni > University of Washington < u.washington.edu >

Introduction and Audience Designed for software developers new to Plone Best practices System structure Debugging Tools and tips

Designed for software developers new to Plone

Best practices

System structure

Debugging

Tools and tips

Getting Started Looking for a CMS? Plone looks to have the features And, it’s written in Python! Python is so legible - this will be easy… But after a quick install and some playing around, you find it difficult to locate the implementation code. Where is it?

Looking for a CMS?

Plone looks to have the features

And, it’s written in Python!

Python is so legible - this will be easy…

But after a quick install and some playing

around, you find it difficult to locate the

implementation code. Where is it?

[1] http://www.zope.org/zopearchitecture.gif Copyright (c) 2007 Zope Corporation - Reprinted with permission.

Buildouts: A Better Approach Binary installers are great for quick evaluation ‘ Unified Installer’ solves the distro woes Software projects require Repeatable process Source code repository Inclusion of third party Products, packages, eggs zc.buildout[1] to the rescue! Check out Martin Aspeli’s great tutorial[2] [1] http://pypi.python.org/pypi/zc.buildout [2] http://plone.org/documentation/tutorial/buildout

Binary installers are great for quick evaluation

‘ Unified Installer’ solves the distro woes

Software projects require

Repeatable process

Source code repository

Inclusion of third party Products, packages, eggs

zc.buildout[1] to the rescue!

Check out Martin Aspeli’s great tutorial[2]

Buildout a New Project Use the plone3_buildout template: > paster create -t plone3_buildout myproject Bootstrap > cd myproject > python bootstrap.py Execute buildout as per rules in buildout.cfg > ./bin/buildout Running tests, debugging, starting the instance now simply > ./bin/instance [options]

Use the plone3_buildout template: > paster create -t plone3_buildout myproject

Bootstrap > cd myproject > python bootstrap.py

Execute buildout as per rules in buildout.cfg > ./bin/buildout

Running tests, debugging, starting the instance now simply > ./bin/instance [options]

Directory Structure Highlighting several directories of special interest (installer approach defines directory structure; using the buildout paths): myproject/var/filestorage/ The contained ‘Data.fs’ file is the FileStorage representation of the ZODB[1] myproject/eggs All the downloaded eggs[2], including the portions of Plone now distributed as namespace packages myproject/parts/instance The Zope ‘instance’ directory, analogous to what ‘mkzopeinstance.py’ creates. A.K.A. $INSTANCEHOME myproduct/parts/zope2 Zope code, previously known as $SOFTWARE_HOME myproject/parts/plone All the Zope 2 style Products used in Plone [1] http://wiki.zope.org/ZODB/FileStorageBackup [2] http://peak.telecommunity.com/DevCenter/PythonEggs

Highlighting several directories of special interest (installer approach defines directory structure; using the buildout paths):

myproject/var/filestorage/ The contained ‘Data.fs’ file is the FileStorage representation of the ZODB[1]

myproject/eggs All the downloaded eggs[2], including the portions of Plone now distributed as namespace packages

myproject/parts/instance The Zope ‘instance’ directory, analogous to what ‘mkzopeinstance.py’ creates. A.K.A. $INSTANCEHOME

myproduct/parts/zope2 Zope code, previously known as $SOFTWARE_HOME

myproject/parts/plone All the Zope 2 style Products used in Plone

[1] http://wiki.zope.org/ZODB/FileStorageBackup

[2] http://peak.telecommunity.com/DevCenter/PythonEggs

Dig In! Start up the buildout instance, and add a Plone Site: > myproject/bin/instance fg WebBrowser -> http://localhost:8080/manage_main (using same user / pass provided during ` paster create... ` step above) Select 'Plone Site' (Add) Id: Plone Title: Site [Add Plone Site]

Start up the buildout instance, and add a Plone Site:

> myproject/bin/instance fg

WebBrowser -> http://localhost:8080/manage_main

(using same user / pass provided during ` paster create... ` step above)

Select 'Plone Site' (Add)

Id: Plone

Title: Site

[Add Plone Site]

Find in the ZMI Before we interact directly with the ZODB, try the [Find] tab in the ZMI first: http://localhost:8080/manage_findForm It is case sensitive No wildcards available Scope is controlled by location But it's still very fast and useful! A great place to start.

Before we interact directly with the ZODB, try the [Find] tab in the ZMI first: http://localhost:8080/manage_findForm

It is case sensitive

No wildcards available

Scope is controlled by location

But it's still very fast and useful! A great place to start.

Direct Access to the ZODB ZODB represents persisted objects, not tabled relational data. To interact with the live objects: > myproject/bin/instance debug Enable readline for tab completion (very helpful for discovery): >>> import readline, rlcompleter >>> readline.parse_and_bind('tab: complete') Purely transactional! Commits required: >>> import transaction >>> transaction.commit() Mount the ZODB as a read only file system[1] Many additional great tips for interacting with the ZODB[2] [1] http://wiki.zope.org/zope2/HowToMountZODBAsVirtualFilesystem [2] http://docs.neuroinf.de/programming-plone/debug#1-6

ZODB represents persisted objects, not tabled relational data.

To interact with the live objects: > myproject/bin/instance debug

Enable readline for tab completion (very helpful for discovery): >>> import readline, rlcompleter >>> readline.parse_and_bind('tab: complete')

Purely transactional! Commits required: >>> import transaction >>> transaction.commit()

Mount the ZODB as a read only file system[1]

Many additional great tips for interacting with the ZODB[2]

Browser Tools Web Developer[1] Firebug[2] Selenium[3] Clouseau[4] [1] http://chrispederick.com/work/web-developer/ [2] http://www.getfirebug.com/ [3] http://www.openqa.org/selenium/ [4] http://plone.org/products/clouseau

Web Developer[1]

Firebug[2]

Selenium[3]

Clouseau[4]

Exuberant CTAGS[1] Index tables for other tools to use; available for cygwin[2], TextMate[3], and the old standards: vi & emacs. Create anywhere, using defaults or selectively feed files of interest (limiting scope makes quicker, increasing scope expands coverage): > ctags -Re A few emacs keybindings for flavor: M-. <tag> Takes you to tag definition M-0 M-. Go to next definition For invocations of a tag: M-x tags-search <regex> M-, Go to the next match [1] http://ctags.sourceforge.net/ [2] http://tulrich.com/geekstuff/emacs.html [3] http://gerd.knops.org/?p=7

Index tables for other tools to use; available for cygwin[2], TextMate[3], and the old standards: vi & emacs.

Create anywhere, using defaults or selectively feed files of interest (limiting scope makes quicker, increasing scope expands coverage): > ctags -Re A few emacs keybindings for flavor: M-. <tag> Takes you to tag definition M-0 M-. Go to next definition

For invocations of a tag: M-x tags-search <regex> M-, Go to the next match

PDB Entry Simplest way to get to the debugger, add this line in any source file in the execution path: import pdb; pdb.set_trace() Re-launch in foreground, and trigger execution: > myproject/bin/instance fg Browse to trigger This is not however easy to do within python scripts and page templates[1]. The best solution is to move code into file system packages. This will also allow unit testing! > myproject/bin/instance test -m plone.portlets [1] http://plone.org/documentation/how-to/debug-script-python-with-pdb

Simplest way to get to the debugger, add this line in any source file in the execution path: import pdb; pdb.set_trace()

Re-launch in foreground, and trigger execution: > myproject/bin/instance fg Browse to trigger

This is not however easy to do within python scripts and page templates[1]. The best solution is to move code into file system packages. This will also allow unit testing! > myproject/bin/instance test -m plone.portlets

PDB Usage The pdb interface is designed to be fast and easy to work with. A complete list of commands is available here[1]. A few important navigation commands: n Next - executes the line and moves to the next s Step - steps into the execution r Return - resume to end of the current function c Continue - resume program execution w Where - display the call stack u Up - move one frame up the call stack d Down - move one frame down the call stack p expr Print - print expression Check out conditional breakpoints! [1] http://docs.python.org/lib/debugger-commands.html

The pdb interface is designed to be fast and easy to work with. A complete list of commands is available here[1]. A few important navigation commands:

n Next - executes the line and moves to the next

s Step - steps into the execution

r Return - resume to end of the current function

c Continue - resume program execution

w Where - display the call stack

u Up - move one frame up the call stack

d Down - move one frame down the call stack

p expr Print - print expression

Check out conditional breakpoints!

Logging Logging from most anywhere can be quite useful. Within Zope Page Templates (ZPT) : <span tal:content='python: context.plone_log(&quot;details to log: %s&quot; % details)' /> Within a python script: context.plone_log(&quot;more details: %s&quot; % more_details) In any python file on the filesystem: import logging logger = logging.getLogger(&quot;Plone&quot;) logger.info(&quot;Code being executed here...'&quot;) The log file for the example buildout is located in myproject/var/log/instance.log If running in 'fg' mode, the logged data will also be written to standard out.

Logging from most anywhere can be quite useful.

Within Zope Page Templates (ZPT) : <span tal:content='python: context.plone_log(&quot;details to log: %s&quot; % details)' />

Within a python script: context.plone_log(&quot;more details: %s&quot; % more_details)

In any python file on the filesystem: import logging logger = logging.getLogger(&quot;Plone&quot;) logger.info(&quot;Code being executed here...'&quot;)

The log file for the example buildout is located in myproject/var/log/instance.log

If running in 'fg' mode, the logged data will also be written to standard out.

IDEs A number of other IDEs (Integraded Development Environments) exist (some free, some commercial) and promise simple integration and debugging: Wing IDE Professional[1] Eclipse with Pydev[2] PIDA[3] BoaConstructor[4] Komodo[4] [1] http://wingware.com/doc/howtos/zope [2] http://pydev.sourceforge.net/ [3] http://plone.org/documentation/tutorial/ debugging-plone-products-with-pida/debugging-with-pida [4] http://boa-constructor.sourceforge.net/ [5] http://www.activestate.com/Products/komodo_ide/

A number of other IDEs (Integraded Development Environments) exist (some free, some commercial) and promise simple integration and debugging:

Wing IDE Professional[1]

Eclipse with Pydev[2]

PIDA[3]

BoaConstructor[4]

Komodo[4]

Conclusion This isn’t a replacement for the ever improving available documentation[1]. Consider file system development (and don’t cheat the tests!) Take advantage of the many great tools out there. Thanks to the open source community! [1] http://plone.org/documentation/how-to/read-documentation

This isn’t a replacement for the ever improving available documentation[1].

Consider file system development (and don’t cheat the tests!)

Take advantage of the many great tools out there.

Thanks to the open source community!