An introduction to PyObjC

Preface
Objective-C for PyObjC users
Overview of the bridge
Cocoa for Python programmers
Notes on specific tasks
Building applications
- "py2app" : setup.py
- "IDE approach" : Xcode

Preface

PyObjC is a bridge between Python and Objective-C. It allows you to write Python scripts that use and extend existing Objective-C class libraries, most importantly the Cocoa libraries by Apple.

This document describes how to use Objective-C class libraries from Python scripts and how to interpret the documentation of those libraries from the point of view of a Python programmer.

It is recommended that you take the time to understand a little bit about Objective-C before jumping into PyObjC development. The class libraries that you will be using from Cocoa are not documented in Python, and their documentation will be confusing without a grasp on the semantics and syntax of Objective-C.

Objective-C is an object-oriented programming language implemented as a superset of C that borrows heavily in concept and syntax from Smalltalk. of C and borrows heavily from Smalltalk. It features single inheritance with dynamic dispatch and (in theory) multiple root classes. This is basically the same as Python with single inheritance.

An important difference between Python and Objective-C is that the latter is not a pure object-oriented language. Some values are not objects, but values of plain C types, such as int and double. These basic C types can be used as the types of arguments and the return value of methods.

Object allocation and initialization are explicit and separate actions in Objective-C. The former is done by the class-method alloc, while the latter is done by instance methods whose name customarily starts with init.

Objective-C code looks just like plain C code, with some easily recognizable Smalltalk-like extensions for the object-oriented parts of the language. An example class declaration (usually found in .h files) and implementation (usually found in .m files) are listed below. Class declarations are easily recognized as blocks of code between @interface and @end, and similarly the implementation is between @implementation and @end. An expression enclosed in brackets in Objective-C is called a message, and is the equivalent to an instance method invocation in Python. For example, this Objective-C code:

[aMutableArray addObject:@"constant string"];

Is equivalent in intent to the following in Python:

aList.append(u"constant string")

Objective-C messages have three components: a target, a selector, and zero or more arguments. The target, aMutableArray, is the object or class receiving the message. The selector, addObject: uniquely identifies the kind of message that is being sent. Finally, the arguments, @"constant string" are used by the implementation of the method upon receipt of the message. The syntax of Objective-C message dispatch is deceptively similar to keyword arguments in Python, but they are actually quite different. Objective-C messages can not have default arguments, and all arguments are passed in a specific order. The components of a selector may not be reordered. Syntactically, one argument must be interleaved at every colon in the selector. The message:

[anArray indexOfObject:someObject inRange:someRange]

Target:: anArray
Selector:: indexOfObject:inRange:
Arguments:: someObject, someRange

As you'll see later, the straightforward translation of such a message to Python is:

anArray.indexOfObject_inRange_(someObject, someRange)

This may be awkward and "unpythonic" at first, however this syntax is necessary to preserve the semantics of Objective-C message dispatch.

A class declaration:

@interface MyClass : MySuperClass
{
    id  anInstanceVariable;
    int anotherInstanceVariable;
}

// A class method that returns an initialized instance of this class.
// Similar to an implementation of __call__ on the metaclass.
+instanceWithObject:(id)anObject andInteger:(int)anInteger;

// An instance method, the designated initializer for MyClass.
// Similar to an implementation of __new__ on MyClass.
-initWithObject:(id)anObject andInteger:(int)anInteger;

// An accessor, instance variables (attributes) are in a separate
// namespace and are considered "private" in Objective-C.  Conventionally,
// there is nothing similar to this in Python.
-(int)anotherInstanceVariable;
@end

A class implementation:

@implementation MyClass

// Note that a type is not declared for the return value.  Undeclared types
// are assumed to be "id", which means any kind of instance.
+instanceWithObject:(id)anObject andInteger:(int)anInteger
{
    // 1. Create an instance of MyClass.
    // 2. Initialize it with its designated initializer
    //    "initWithObject:andInteger:".
    // 3. Autorelease it, so that it does not leak memory.
    // 4. Return the new instance.
    //
    // NOTE:
    //   By convention,initializers (such as +new, -init, -copy)
    //   are the only methods that should return retained objects.
    //
    // NOTE:
    //   Since this is a class method, "self" refers to the class!
    //
    // Very roughly similar to:
    //   return self.__new__(anObject, anInteger)
    return [[[self alloc] initWithObject:anObject andInteger:anInteger] autorelease];
}

// Note that a type is not declared for the return value.  Undeclared types
// are assumed to be "id", which means any kind of instance.
-initWithObject:(id)anObject andInteger:(int)anInteger
{
    // Call the designated initializer of the superclass.
    // Similar to:
    //     self = super(MyClass, self).__new__()
    self = [super init];

    // Bail if initialization of the superclass failed.
    // Similar to:
    //     if self is None:
    //         return None
    if (!self) {
        return nil;
    }

    // Set the instance variable (attribute).  The argument must be
    // retained, since it will persist as long as the instance does.
    // Similar to:
    //     # Reference counting is automatic in Python
    //     self.anInstanceVariable = anObject
    anInstanceVariable = [anObject retain];

    // Set the other instance variable.  Note that since anInteger is
    // a primitive "C" type, not an object, no reference counting takes
    // place.
    // Similar to:
    //     # Everything is an object in Python
    //     self.anotherInstanceVariable = anInteger
    anotherInstanceVariable = anInteger;

    // Like __new__ in Python, initializers in Objective-C must
    // explicitly return self.  Note that this is different from
    // __init__.
    // Similar to:
    //     return self
    return self;
}
    

// an accessor, instance variables (attributes) are in a separate
// namespace and are considered "private"
-(int)anotherInstanceVariable
{
    return anotherInstanceVariable;
}

// Since objects were retained as instance variables on this object,
// they must be freed when the object is.  This is similar to an
// implementation of __del__ in Python.  Since Objective-C has no
// cyclic garbage collection, this isn't discouraged like it is in
// Python.
-(void)dealloc
{
    // Very roughly similar to:
    //     del self.instanceVariable
    [instanceVariable release];

    // Very roughly similar to:
    //     super(MyClass, self).__del__()
    [super dealloc];
}

@end

Objective-C also features exceptions, but they are typically only used for disaster recovery, not error handling, so you will not encounter them very often. Read The Objective-C Programming Language if you want to know more about exceptions in Objective-C.

One thing to keep in mind when translating Objective-C snippets to Python is that any message can be sent to nil, and the return value of that message will be nil. PyObjC translates nil to None when crossing the bridge, so any such attempt will raise an AttributeError.

For more information about Objective-C see:

The Objective-C Programming Language at Apple.

Overview of the bridge

Classes

Objective-C classes are visible as (new-style) Python classes and can be subclassed just like normal Python classes. All the usual introspection mechanisms work as well, as do __slots__ and descriptors. The major differences between normal Python classes and Objective-C classes are the way that instances are created and initialized, and the fact that Objective-C selectors look strange when translated to Python methods.

You can use multiple inheritance when subclassing an Objective-C class, so long as the Objective-C class is the first base class and there is only one Objective-C base class. The Objective-C runtime does not support multiple inheritance. These mix-in classes should not contain different implementations for Objective-C methods. To achieve this behavior, Categories should be used instead.

Another thing to keep in mind is that the names of Objective-C classes must be globally unique per process, including across Python modules. That is, it is not possible to have two Python modules that define a class with the same name. It is conventional to choose class names with a short prefix that uniquely identify your project or company. For example, Apple uses NS as the prefix for all classes in the Cocoa libraries. Note that the NS prefix made much more sense when it was called NeXTstep, but persists to this day for compatibility reasons.

As described in Objective-C for PyObjC users the creation of Objective-C objects is a two-stage process. To initialize objects, you first call a class method to allocate the memory (typically alloc), and then call an initializer (typically starts with init). Some classes have class methods which perform this behind the scenes, especially classes that create cached, immutable, or singleton instances.

Messages and Functions

Objective-C methods are bridged to Python methods. Because Objective-C message dispatch syntax can not be translated directly to Python, a few simple translations must take place. The rules for these translations are:

Replace all colons in the selector with underscores:
- someMethod:withFoo:andBar: translates to someMethod_withFoo_andBar_
If the result class or raise (Python keywords), append two underscores:
- class translates to class__
- raise translates to raise__
Use this translated selector as you would a normal Python method. The arguments must be passed in the same order, and the number of arguments passed will normally be equal to the number of underscores in the method name; exceptions to this rule and the behavior of "result" are mentioned below.
- result = [someObject someMethod:firstArg withFoo:foo andBar:bar]; translates to result = someObject.someMethod_withFoo_andBar_(firstArg, foo, bar)

Note that it is currently not possible to support methods with a variable number of arguments from Python. These selectors must be wrapped by custom Objective-C code in order to be accessible by Python.

Wrapped/bridged methods (and functions) have the same number of arguments as the corresponding Objective-C method or function, unless otherwise noted in the documentation (Notes on supported APIs and classes on Mac OS X for Cocoa on Mac OS X).

Most methods or functions that take or return pointers to values will be an exception to this rule if it is callable from Python at all. In Objective-C terminology, there are three kinds of pointers that can be used in a method:

in:: Used to pass data by reference to the function. This is not a special case from Python.
out:: Used to pass data from the function (e.g. an additional return value). From Python, these values will be missing from the argument list (there will be more underscores than arguments passed). See below for notes on how out arguments change the return value.
inout:: A combination of in and out (a value is passed by reference, and mutated upon return). Unlike out, these arguments remain in the argument list, and thus do not have an effect on the number of arguments a method expects. See below for notes on how inout arguments change the return value.

In order to determine what the return value of such an exceptional message will look like, you must "make a list" of the return values with the following rules:

If the return type of the method or function is not void, add it to the list.
For each argument in the method or function, add it to the list if it is out or inout.

After creating this list, you will have one of three cases:

Empty:: The return value of this call will always be None.
One element:: The return value of this call will correspond to the one element of the list.
More than one element:: The return value of this call will be a tuple in the same order as the list.

The rules for pass by reference arguments may look quite complicated, but it turns out this is very straightforward when working with them.

As an example of a method with two output arguments, NSMatrix implements a selector named getNumberOfRows:columns: with the following signature:

(void)getNumberOfRows:(int *)rowCount columns:(int *)columnCount

You use this method in python like this:

rowCount, columnCount = matrix.getNumberOfRows_columns_()

When a function or method has an array of values and the length of that array as arguments, you can pass None as the length. The length of the sequence that is used for the array of values is passed to Objective-C as the length argument.

Python's array.array type may be used to represent a C array if the typestr and size match what is expected by the selector. Numeric, numarray, and other third party array types are not supported in PyObjC 1.3.

When you define methods in a subclass of an Objective-C class, the bridge has to tell the Objective-C runtime what the signature of those methods is. The basic rule is that all arguments as well as the return value are objects (just like with normal Python methods). The bridge will automatically pick a better signature when it has more information available. Specifically, if you override an existing method the bridge will assume you want to use the same method signature. Furthermore, if you implement a method in an (informal) protocol known to the bridge it will use the signature from the corresponding method in that signature.

The end result is that you rarely have to add information about the signature of methods. For the two most common cases where this is necessary, we have provided convenience decorators (used like staticmethod or classmethod):

objc.accessor:: Use this to wrap a Key-Value Coding or Key-Value Observing compliant accessor.
PyObjCTools.AppHelper.endSheetMethod:: Use this to wrap the implementation of a sheet's "didEndSelector" callback.

For complete control of the mapping to Objective-C you can use the function objc.selector to create custom descriptors. See the documentation of the objc module for the arguments you can use with this function. It is normally used like this:

class MyObject (NSObject):
        def someMethod_(self, arg):
                pass

        someMethod_ = objc.selector(someMethod_, ...)

Reference counting

The Cocoa libraries, and most (if not all) other class libraries for Objective-C use explicit reference counting to manage memory. The methods retain, release and autorelease are used to manage these reference counts. You won't have to manage reference counts in Python, the bridge does all that work for you (but see Notes on supported APIs and classes on Mac OS X for some advanced issues).

The only reasons reference counts are mentioned at all are to tell you about ignoring them, and more importantly to introduce you to some issues w.r.t. reference counting.

It turns out that Cocoa uses a primitive form of weak references. Those are not true weak references as in Python, but use-cases where an object stores a reference to another object without increasing the reference count for that other object. The bridge cannot solve the issues this introduces for you, which means that you get hard crashes when you're not careful when dealing with those weak references.

The basic rule to deal with weak references is: make sure objects stays alive as long as someone might have a weak reference to them. Due to the way the bridge works, this means that you must make sure that you don't create weak references from Objective-C to a plain Python object. The Python object stays alive, but the proxy object as seen by the Objective-C code is actually an autoreleased object that will be cleaned up unless the Objective-C code increases its reference count.

The document Notes on supported APIs and classes on Mac OS X contains information about classes that work with weak references. The most important are notification centers and NSOutlineView, to be exact: the outline view stores weak references to the objects return by the method outlineView:child:ofItem: of its data source. The easiest way to avoid crashes with outline views is to make sure that you model for the view uses subclasses of NSObject to represent the nodes in the outline view.

Another gotcha is that obj.setDelegate_() often does not retain the delegate, so a reference should be maintained elsewhere.

(Informal) protocols

Cocoa defines a number of formal and informal protocols that specify methods that should be implemented by a class if it is to be used in a specific role, such as the data source for an NSTableView.

Those protocols are represented by instances of objc.informal_protocol. The only ones that have to care about these objects are the maintainers of wrappers around Objective-C frameworks: they have to keep these protocol wrappers up-to-date.

PyObjC will automatically use the information in the informal_protocol objects to add the right method signatures to methods, and to warn about classes that partially implement a protocol.

See PyObjC protocol support for more information.

Cocoa Bindings

In Mac OS X 10.3 Apple introduced Cocoa Bindings, a method to make it easier to create and use Controller objects using Key-Value Observing and Key-Value Coding. In order to create accessors compatible with this, you must use objc.accessor to create an appropriate selector descriptor.

Cocoa for Python programmers

Cocoa frameworks are mapped onto Python packages with the same name; that is the classes, constants and functions from the AppKit framework are available after you import AppKit in your Python script.

These helper modules contain only functions, constants and classes that wrap items in the corresponding framework. All utility functions and classes are located in the PyObjCTools package and objc module. Note that it is possible to use pydoc (or the help()) function with the framework wrappers, but that this is not very useful for the entire module due to the size of these modules.

This makes it easier to find documentation for an item: if you import it from the wrapper module for an Objective-C framework the documentation for that item can be found in the documentation for the framework; otherwise the item is documented in the PyObjC documentation.

The module PyObjCTools.NibClassBuilder can be used to make working with NIB files more convenient. This module can be used to extract information about classes from NIB files, both as a standalone tool generating source code and during runtime. See the online documentation for this module for more information.

PyObjC includes a number of examples that show how to use Cocoa from Python. The PyObjC Example index contains an overview of those examples.

More information on Cocoa programming can be found at:

Cocoa documentation at the Apple developer website
Cocoa examples at the Apple developer website
stepwise.com
Your local bookstore or library

Notes on specific tasks

Working with threads

When you create a thread and want to use PyObjC from that thread you will have to create an NSAutoreleasePool in that thread and clean it up when you're done. The easiest way to that is to create an instance of that class bound to a local variable. If the thread is long-lived you may want to arrange for recycling the pool once in a while.

Finalizers

In Python you can use the method __del__ to clean up resources when your object is garbage collected. In Objective-C/Cocoa this is done with a method named dealloc.

In Python subclasses of Objective-C classes you can use either convention. You should pick one convention for your own code, the order in which __del__ and dealloc methods are called is undefined.

Copying

It is possible to implement the NSCopying protocol in your classes. Some care must be taken when you inherit from a class that already implements that protocol.

Some classes copy the template object manually, you'll have to copy your own fields manually in that case. Other classes use a convenience function that creates the copy. In that case you wont have to copy your own fields. However, the fields in the copy will rever to the same objects as the fields in the original (that is, the copy will share some state with the original). This is no problem when the fields rever to immutable values (such as integers), but is probably not what you want when the fields rever to mutable values (such as lists).

NOTE: PyObjC might introduce a helper class when you inherit from a class that implements NSCopying. You should not rely on the existance of this class.

NOTE2: You shouldn't assign to SomeClass.copyWithZone_ unless that class already implements copyWithZone:. If you do you may end up with seemingly random memory coruption.

Building applications

There are two different ways to build applications with PyObjC. py2app should be the preferred method, however using the Xcode template can be convenient for development.

"py2app" : setup.py

The PyObjC installer includes a copy of the py2app package. This package offers a way to build distutils scripts for building (standalone) applications and plugin bundles.

An example setup.py script:

from distutils.core import setup
import py2app

setup(
    app = ["iClass.py"],
    data_files = ["English.lproj"],
)

During development you typically invoke it from the command line like this:

python setup.py py2app -A

This will build an application bundle in a folder named dist in the current folder. The -A option tells py2app to add symbolic links for data folders and files and an Alias to your main script, allowing you quickly rebuild the application without doing a full dependency scan, with the additional bonus that you can edit them without rebuild. To build a standalone application, simply do not use the -A option. Note that if you are using a version of Python shipped with your operating system, it will not be included in the application. Otherwise, your application will include stripped down version of the Python runtime that you ran setup.py with.

For more information about py2app usage, read through some of the setup.py scripts used by the examples in the Examples folder. On any setup.py script that imports py2app, you can use the following command to see the list of options:

python setup.py py2app --help

"IDE approach" : Xcode

PyObjC includes a number of Xcode templates that can be used to develop applications. Those templates are used like any other Xcode template. The only non-obvious detail is that you have to add your sources as resources, but Project Builder usually does the right thing when you add a new file.

The templates will build an application that makes use of the installed copy /System/Library/Frameworks/Python.framework (e.g. the one shipped by Apple in Mac OS X 10.3) and will copy the PyObjC modules into the application bundle. This means that this application bundle should be useable on any Mac OS X 10.3 system, if you do not have any additional dependencies. Using py2app to deploy your application is a more reliable method, and builds more compact bundles.

See the documentation for the templates for more details.

An introduction to PyObjC

Contents