PyObjCTools: The PyObjC Toolbox

Introduction

The package PyObjCTools contains a number of (basicly unrelated) modules with usefull functionality. These have been placed inside a module to avoid cluttering the global namespace.

The rest of this document provides documentation for these modules, but lets start with a short overview.

• PyObjCTools.AppHelper

Utility functions for use with the AppKit module.

• PyObjCTools.Conversion.py

Functions for converting between Cocoa and pure Python data structures.

• PyObjCTools.KeyValueCoding.py

A python API for working with Key-Value Coding.

• PyObjCTools.NibClassBuilder.py

Module containing a magic super-class that can read information about the actual super-class and implemented actions and outlets from a NIB file.

• PyObjCTools.pluginbuilder.py

Extension of bundlebuilder (XXX: Link) that allows you to build python-based plugin bundles, such as panes for the System Preferences application and screen savers.

• PyObjCTools.Signals.py

Module that tries to print usefull information when the program gets a fatal exception. This module should only be used during development.

PyObjCTools.AppHelper

This module exports two functions that are usefull when working with the AppKit framework.

• endSheetMethod(method) -> selector

  Convert a method to a form that is suitable to use as the delegate callback for sheet methods.

• runEventLoop(argv=None, unexpectedErrorAlert=unexpectedErrorAlert) -> None

  Run the evenloop using NSApplicationMain and ask the user if we should continue if an exception is caught.

  This function doesn't return unless it throws an exception.

PyObjCTools.Conversion.py

Functions for converting between Cocoa and pure Python data structures.

• propertyListFromPythonCollection(pyCol, conversionHelper=None) -> ocCol

  Convert a Python collection (dictionary, array, tuple, string) into an Objective-C collection.

  If conversionHelper is defined, it must be a callable. It will be called for any object encountered for which propertyListFromPythonCollection() cannot automatically convert the object. The supplied helper function should convert the object and return the converted form. If the conversion helper cannot convert the type, it should raise an exception or return None.

• pythonCollectionFromPropertyList(ocCol, conversionHelper=None) -> pyCol

  Converts a Foundation based collection-- a property list-- into a Python collection. Like propertyListFromPythonCollection(), conversionHelper is an optional callable that will be invoked any time an encountered object cannot be converted.

PyObjCTools.KeyValueCoding

A module for working with Key-Value Coding in python. Key-Value coding is explained on the apple website

This module provides a python interface to some of that functionality. The interface is modelled on the getattr and setattr functions.

• getKey(object, key) -> value

  Find the value for key. Raises KeyError if the key is not a valid attribute of the object.

  To find the value of a key the following values are tried for a key named key (first match wins):

  • the return value of object.get_key()
  • the return value of object.getKey()
  • the return value of object._get_key()
  • the return value of object._getKey()
  • the value of the attribute key, or the value of object.key() if object.key is a method.
  • the value of the attribue _key, or the vale of object._key() if object._key is a method.
• getKeyPath(object, keypath) -> value

  Like getKey but using a key path. The keypath is a sequence of keys seperated by dots. It calls getKey to follow the path and returns the final value.

• setKey(object, key, value) -> None

  Set the value of key to value.

  The following values are used for setting the value for a key named key (first match wins):

  • Call object.set_key(value)
  • Call object.setKey(value)
  • Call object._set_key(value)
  • Call object._setKey(value)
  • Check if _key is an attribute and if so, set its value
  • Try to set the attribute key.

  Raises KeyError if the key cannot be changed.

• setKeyPath(object, keypath, value) -> None

  The same as setKey, but now using a key path. A key path is a sequence of keys seperated by dots. The getKey function is used to traverse the path upto the last item, and then setKey is used to change the value.

PyObjCTools.NibClassBuilder

Extracting class definitions from nibs

The module maintains a global set of class definitions, extracted from nibs. To add the classes from a nib to this set, use the extractClasses() function. It can be called in two ways:

• extractClasses(nibName, bundle=<main-bundle>)

  This finds the nib by name from a bundle. If no bundle if given, the main bundle is searched.

• extractClasses(path=pathToNib)

  This uses an explicit path to a nib.

extractClasses() can be called multiple times for the same bundle: the results are cached so no almost extra overhead is caused.

Using the class definitions

The module contains a "magic" base (super) class called AutoBaseClass. Subclassing AutoBaseClass will invoke some magic that will look up the proper base class in the class definitions extraced from the nib(s). If you use multiple inheritance to use Cocoa's "informal protocols", you must list AutoBaseClass as the first base class. For example:

class PyModel(AutoBaseClass, NSTableSource):
    ...

The NibInfo class

The parsing of nibs and collecting the class definition is done by the NibInfo class. You normally don't use it directly, but it's here if you have special needs.

The command line tool

When run from the command line, this module invokes a simple command line program, which you feed paths to nibs. This will print a Python template for all classes defined in the nib(s). For more doco, see the commandline_doc variable, or simply run the program wothout arguments. It also contains a simple test program.

PyObjCTools.Signals

This module provides two functions that can be usefull while investigating random crashes of a PyObjC program. These crashes are often caused by Objective-C style weak references or incorrectly implemented protocols.

• dumpStackOnFatalSignal()

  This function will install signal handlers that print a stacktrace and then reraise the signal.

• resetFatalSignals()

  Restores the signal handlers to the state they had before the call to dumpStackOnFatalSignal.

This module is not designed to provide fine grained control over signal handling. Nor is it intended to be terribly robust. It may give usefull information when your program gets unexpected signals, but it might just as easily cause a crash when such a signal gets in.

PyObjCTools.pluginbuilder

This module defines one class to build python based plugin bundles for MacOS X. Examples of plugin bundles include PreferencePanes and InterfaceBuilder palletes.

The PluginBuilder class is instantated with a number of keyword arguments and have a build() method that will do all the work.

XXX: Add documentation about the constructor arguments

The module contains a main program that can be used in two ways:

% python pluginbuilder.py [options] build

% python buildplugin.py [options] build

Where "buildplugin.py" is a user-supplied setup.py-like script following this model:

from PyObjCTools.pluginbuilder import buildplugin

buildplugin(<lots-of-keyword-args>)

The script will tell you about the supported arguments if you run it without any arguments.