Notes on supported APIs and classes on Mac OS X

Contents

TODO: Add documentation about weak linking (see intro.txt).

Introduction

This document describes the restrictions with regard to supported APIs and classes on Mac OS X. In general, classes and global functions are used just as they are in Objective-C (e.g. the Apple developer documentation applies), but in some cases there are special considerations.

Global functions that are not useful for Python programs are not callable from Python, as listed below.

This document lists the exceptions to the basic rules. If a method uses pointers to return additional values, the Python wrapper for that method returns a tuple containing the original return value and the additional values. It is not necessary to provide values for pointer arguments unless their initial value is used by the method. Additionally, objc.NULL can be passed to denote that these arguments should be NULL rather than a pointer to allocated memory.

This document is targeted at the latest supported version of Mac OS X (currently Mac OS X 10.4.x). Unless specifically noted, the same restrictions apply to earlier versions of Mac OS X. Earlier versions of Mac OS X have less extensive APIs, and PyObjC does not provide a compatibility layer except when necessary to support its own operation.

This document is not entirely complete, but does cover the most used APIs. Classes not mentioned in this document may very well work properly.

Frameworks that do not have PyObjC wrappers can be loaded at runtime using the objc.loadBundle, objc.loadBundleFunctions and objc.loadBundleVariables functions. In a future version of PyObjC, there will be an Objective-C header parser that can be used to automate this process and to generate wrappers.

Core Objective-C runtime

Addressbook framework

The global functions in this framework are not wrapped, as the same functionality can be accessed by using the object-oriented interface.

AppKit framework

The callback methods for the NSSheet API's have a non-default signature and no fixed name. You should therefore explicitly specify the signature. This is done by calling the endSheetMethod function after defining your callback:

class MyClass(NSObject):
        def mySheetDidEnd(self, panel, returnCode, contextInfo):
                """ Actual implementation goes here """
                pass

        mySheetDidEnd = PyObjCTools.AppHelper.endSheetMethod(
                mySheetDidEnd)

In Python 2.4, this may be written using a decorator as such:

class MyClass(NSObject):
        @PyObjCTools.AppHelper.endSheetMethod
        def mySheetDidEnd(self, panel, returnCode, contextInfo):
                """ Actual implementation goes here """
                pass

Unless otherwise noted, all contextInfo arguments are passed as integers, not as arbitrary pointers.

Class NSApplication

NSModalSession objects are wrapped as opaque values. Two wrapper objects refer to the same session object if their ptr attributes are equal.

Class NSBezierPath

Class NSBitmapImageRep

Class NSFont

Class NSGraphicsContext

Class NSLayoutManager

Class NSMatrix

Class NSMovie

The return value of QTMovie and the sole argument of initWithMovie: are Carbon.Qt.Movie objects.

Class NSOpenGLContext

Class NSOpenGLPixelFormat

Class NSQuickDrawView

Class NSSimpleHorizontalTypesetter

Class NSView

Class NSWindow

Foundation framework

NOTE: The list below is mostly based on scripts that find methods that can not be automatically handled by the bridge. We have not yet performed a manual search for such methods in the Cocoa documentation.

The -forward:: and performv:: methods are not supported. Normal Python function invocation can be used instead.

Structs are wrapped using a struct-like type. Struct members can be accessed using the field names as attributes, or they can be accessed as sequences for backwards compatibility.

Class NSArray

Class NSAutoreleasePool

The bridge automatically manages reference counts for you, but it is still required to make an autorelease pool available.

In single-threaded programs that use NSRunLoop or are not long-lived, it is not necessary to explicitly manage NSAutoreleasePool, as NSRunLoop will push and pop one for each iteration, and PyObjC creates a NSAutoreleasePool in the thread it is imported in.

When creating a large amount of objects in a loop, it may be useful to manually create a pool to reclaim memory as soon as possible. The proper idiom for this is:

while <test>:
        pool = NSAutoreleasePool.alloc().init()

        # ... Do work here ...

        del pool

The previous pool must be deallocated before a new one is created. For example, the code below will silently leak memory:

while <test>:
        # This pool is allocated BEFORE the previous is
        # garbage collected, so the stack grows!
        pool = NSAutoreleasePool.alloc().init()

        # ... Do work here ...

In threads other than the main thread, as with Objective-C applications, it is necessary to create an NSAutoreleasePool as soon as possible before using other Objective-C objects.

Class NSCoder

The following methods are not supported in the current version of PyObjC. This limitation will be lifted in a future version of the bridge.

The method decodeBytesWithoutReturnedLength: is not supported, use decodeBytesWithReturnedLength: instead. It is not possible to safely represent the return value of this method in Python.

Class NSData

NSData subclasses support the Python buffer protocol, and any Python object that implements the Python buffer protocol (except str and unicode) are wrapped as an NSData subclass.

Class NSDecimalNumber and the NSDecimal type

NSDecimal is wrapped by a Python type.

Creating an NSDecimal instance: NSDecimal(value) or NSDecimal(mantisssa, exponent, isNegative). Value can be a string, int or long (not a float because of the representation issues for floats).

Converting an NSDecimal to a float or int: aDecimal.as_int() and aDecimal.as_float.

Class NSDictionary

The (undocumented) methods getKeys:, getObjects: and getObjects:andKeys: are not supported.

Class NSException

Class NSFault

The extraData argument/return value for -extraData and setTargetClassextraData: is represented as an integer.

Class NSIndexSet

Class NSInvocation

In some versions of Mac OS X, NSInvocation doesn't work properly with structs that contain padding for alignment. Such structs are not used in the Mac OS X API, but may be present in 3rd party code. This leads to problems when forwardInvocation: is used to call a method that has such a struct as one of its arguments.

Class NSMutableArray

Class NSMutableString

Class NSNetService

Class NSObject

Class NSScriptObjectSpecifier

Class NSString

Objective-C strings are represented as instances of a subclass of the Python type unicode. Since Python unicode objects are immutable, working with NSMutableString can be tricky. If you need to update the Python representation of the string, use aString.self(), which will be a new Python proxy for the same NSMutableString instance.

class NSThread

It is safe to call from Objective-C to Python on any thread. It is safe to start new threads using the Python threading API and run non-Cocoa code on those threads.

InterfaceBuilder framework

I (Ronald) have not found documentation for this framework, therefore the following methods with a "difficult" signature are not supported.

Please let me know if there is documentation for this framework.

Class IBObjCSourceParser

Class NSView

Class NSIBObjectData

Class IBObjectContainer

Class IBXMLDecoder

Class IBSplitScrollView

PreferencePanes framework

This framework seems to define useful classes like NSAuthorization and NSKeychain, but these are not documented and some useful methods have a hard signature.

The only documented class, NSPreferencePane, is fully supported.