PyObjCTools: The PyObjC Toolbox

Introduction

The package PyObjCTools contains a number of (basically unrelated) modules with useful 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.

Utility functions for use with the AppKit module.

Functions for converting between Cocoa and pure Python data structures.

A Python API for working with Key-Value Coding.

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

Module to make it possible to integrate signal handling into the main runloop.

Allows logging of NSException stack traces. This module should only be used during development.

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

Used by the PyObjC Xcode templates to derive py2app options from an Xcode project file.

PyObjCTools.AppHelper

This module exports functions that are useful when working with the AppKit framework (or more generally, run loops).

PyObjCTools.Conversion

Functions for converting between Cocoa and pure Python data structures.

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 modeled on the getattr and setattr functions.

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() 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 extracted 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 documentation, see the commandline_doc variable, or simply run the program without arguments. It also contains a simple test program.

PyObjCTools.Signals

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

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