Working with PyShell in Chandler

Warning

Always save a copy of your data before attempting to use PyShell, either by exporting to a ChandlerExport^? (.chex) file via "File > Export Collections and Settings" or by backing up the repository files via "Tools > Repository > Back up".

Installing the Chandler Debug Plugin

You can quickly tell if you have the Chandler Debug Plugin installed by seeing if you have a "Tools > Debug" menu. If you do, skip this section. Otherwise, look in the "Plugins > Active" menu for "chandler-debugplugin". If it's there, clicking on it will activate the plugin and you should now have a "Tools > Debug" menu, and can skip the rest of this section. Otherwise, you'll have to install the debug plugin. Use the "Plugins > Download" menu to bring up the Python Package Index (PyPI^?) in your web browser. Next, click on the Chandler-debugPlugin link. Scroll down to find the link to Chandler-debugPlugin-0.1.tar.gz and download that file. Once that's complete, use the "Plugins > Install..." menu and choose the .tar.gz file you just downloaded. Check that the plugin is active ("Plugins > Active") and that you now have a "Tools > Debug" menu.

The PyShell Window

Using "Tools > Debug > Show Python Shell..." will open a window labelled "PyShell" which is an interactive Python environment, or "shell". The three "greater-than" brackets >>> represent a prompt where the shell is awaiting your typing input. Chandler predefines a few variables for convenience -- the most important one is "view" which is bound to the Chandler UI's repository view, and is used to access items. At this point, if you are comfortable with Python, you can interact with Chandler by typing Python statements. Any changes you make to items in the PyShell will be immediately reflected in the Chandler UI.

Finding Specific Items

The next tool we need is Chandler's built-in web server. It allows you to browse around your data using your web browser. The easiest way to activate it is to select a collection in the sidebar or any item in the calendar view or list view, then hit the F4 key. This will activate the web server (if not already running) and open your default web browser to display internal details about the selected item. By default the web server listens on port 1888 and only accepts requests from the local computer, but you can also reconfigure the web server. To get a list of all the various kinds of data in Chandler, click the link labelled "[top]", or point your web browser at http://localhost:1888/repo/ . Clicking on a kind will take you to a page with details about the schema for that kind. There will also be a special link near the top of a kind's page labelled "Run a Kind Query"; this link will display all items of that kind. For example, to see all collections in the repository...

http://localhost:1888/repo/parcels/osaf/pim/AppCollection?mode=kindquery

Clicking on an item displays details about that item, including its universally unique identifier or UUID, which is labelled as "itsUUID:". It's a long string of letters and numbers like f994b422-9d06-11dc-b3f3-0017f203802e. That UUID is the key to accessing a particular item in the PyShell.

Accessing an Item

Now that you have the UUID of an item, you can access it in the PyShell by typing at the >>> prompt...

>>> item = view.findUUID("the item's UUID")

For example...

>>> item = view.findUUID("f994b422-9d06-11dc-b3f3-0017f203802e")

Now "item" is a Python object representing the item. You can examine or modify attributes as you would any Python object, for example...

>>> print item.displayName
>>> item.displayName = "foo"

You can tell the item to dump all of its attributes via...

>>> item.printItem()

To delete an item, use...

>>> item.delete(True)

The "True" parameter tells the repository to delete the item's children as well. If an item is a collection, you can delete its contents by...

>>> for child in item:
... child.delete(True)

-- MorgenSagen - 27 Nov 2007