This document describes how you can wrap on Objective-C class library using a Python module or package. This document assumes that your class library is located in a framework.
Wrapping can be pretty easy for most classes, but you may have to write some C code for specific methods.
The code for loading a framework and exporting its classes is pretty simple:
import objc
objc.loadBundle("MyFramework", globals(),
bundle_path=objc.pathForFramework(u'/path/to/MyFramework.framework'))
del objc
In general you should not load frameworks this way, but you should write a package or module to do this for you (e.g. place this code in MyFramework.py or MyFramework/__init__.py. This makes it possible to import MyFramework which is much more convenient.
If your class library does not require helper functions for some methods this is all that is needed.
It is currently necessary to import the wrapper modules for all frameworks that are used by your framework. Not doing this may lead to subtle bugs in other parts of the code. This is a limitation of PyObjC that will be lifted in a future version.
The code above only provides wrappers for Objective-C classes, if the library also defines global functions and/or constants you'll have to write an extension module to make these available to Python.
You can use the PyObjC C-API (to be documented) when writing this module. With some luck you can adapt the scripts in Scripts/CodeGenerators to generate this module for you. These scripts are both very rough and tuned for the Apple headers, so YMMV.
Note that we currently do not install the pyobjc-api.h header, you'll have to copy it from the source-tree until we do. This header is not installed because the interface is not yet stable, please let us know if you want to use the API.
Methods with pointer arguments (other then arguments that are equivalent to an 'id') require more work. If the pointer arguments are used to pass a single value to/from a function ('pass-by-reference arguments') you'll just have to provide more specific method signatures. In other cases you'll have to write custom wrappers for these methods.
Check Modules/Foundation for examples of these custom wrappers.
Pass-by-reference arguments can be 'in' (data passed into the function), 'out' (data is returned from the function) or 'inout' (data is passed into and then returned from the function).
Given the following class interface:
@interface ClassName {}
-(void)selector:(id*)outArgument withArguments:(NSArray*)data;
@end
The compiler will generate a method signature for this method and this can be accessed from Python using the property 'signature' of Objective-C methods. You can also just make up the signature, which is quite easy once you get the hang of it. The signature for this method is 'v@:^@@'. See Type Encodings for the list of valid encoding characters for the Apple Objective-C runtime.
Let's say the first argument is an output parameter. Output parameters are denoted in the signature string using the character 'o' before the actual argument signature. The 'correct' signature for method is therefore 'v@:o^@@'. The following code tells the bridge about this better method signature:
import objc
objc.setSignatureForSelector("ClassName", "selector:withArguments:",
"v@:o^@:@")
To annotate method signatures you'll have to add a single character before all '^' characters in the signature of a method. The characters are:
If the method has pointer arguments that are not pass-by-reference arguments, or if the default method wrappers are not suitable for other reasons, you'll have to write custom wrappers. For every custom wrapper you'll have to write three functions: 1 to call the method from Python, 1 to call the superclass implementation of the method from Python and 1 to call a Python implementation of the method from Objective-C.
You also must write a custom wrapper when the method has a variable number of arguments. It is often advisable to documented varargs method as unsupported, or to support them only using a fixed number of arguments.
For now it is best to check the source code for the wrappers for the Cocoa class library for more information. We'll add documentation for this in the future.
If the framework defines any (informal) protocols you should add objc.informal_protocol objects for those protocols to your module. These can be defined in a submodule, as long as you arrange for that module to be loaded whenever someone imports your package.
See Lib/Foundation/protocols.py for examples of protocol definitions.