objc
– The PyObjC bridge¶
Introduction¶
The module objc
is the core of PyObjC and provides the automatic
bridging between Python and Objective-C. It also provides a number of
utility functions and types that make it easier to integrate Python
and Objective-C code.
The module objc
defines a number of functions whose names start with
an underscore. Those functions are private and should not be used, they can
be removed from release without warning.
NOTE: This document is currently mostly an exhaustive list of stuff and needs to be reorganised once I’ve filled in the technical details.
Bridge options¶
- objc.options¶
The object
options
has attributes for reading and setting a number of configuration options for the bridge.Attributes whose names start with an underscore are reserved for use by the bridge and can appear or disappear with every release of PyObjC.
Added in version 3.0.
- objc.options.verbose¶
When the value is
True
the bridge will log more information.This currently results in output on the standard error stream whenever an exception is translated from Python to Objective-C.
- objc.options.use_kvo¶
The default value for the __useKVO__ attribute on classes.
When the __useKVO__ attribute of a class is true instances of the class will generate Key-Value Observation notifications when setting attributes from Python.
- objc.options.unknown_pointer_raises¶
When True (the default) the bridge will raise an exception when it encounters a pointer value that cannot be converted to Python, otherwise it it creates instances of
ObjCPointer
.
- objc.options.strbridge_enabled¶
Python 2 only: When True (the default) instances of
str
are bridged as instances of a subclass of NSString, otherwise strings are not bridged.
- objc.options.deprecation_warnings¶
When
"0.0"
(the default) the bridge will not emit deprecation warnings, otherwise the value should be a platform version in the form of a string (e.g."10.15"
) and the bridge will emit a deprecation warning for APIs that were deprecated in the SDK (or earlier).Set to
None
or"0.0"
to disable warnings.Deprecation warnings are emitted using the
warnings
module, using the warningobjc.ApiDeprecationWarning
.Added in version 3.3.
- objc.options.structs_indexable¶
When True (the default) PyObjC’s wrappers for C structs can be indexed as if they are (writable) tuples. When False this isn’t possible.
Note
This is primarily an experimental option, that will likely be removed in a future version.
- objc.options.structs_writable¶
When True (the default) PyObjC’s wrappers for C structs are writable, otherwise they are read-only.
Note
This is an experimental option. I don’t know yet if making structs read-only will be a better.
Deprecated functions for changing options¶
- objc.setVerbose(yesOrNo)¶
When the argument is
True
the bridge will log more information.This currently results in output on the standard error stream whenever an exception is translated from Python to Objective-C.
Deprecated since version 3.0: Use
objc.options
instead
- objc.getVerbose()¶
Returns the current value of the verbose flag.
Deprecated since version 3.0: Use
objc.options
instead
- objc.setUseKVOForSetattr()¶
Sets the default value for the __useKVO__ attribute on classes defined after this call. Returns the previous value.
When the __useKVO__ attribute of a class is true instances of the class will generate Key-Value Observation notifications when setting attributes from Python.
Deprecated since version 3.0: Use
objc.options
instead
- objc.setStrBridgeEnabled(yesOrNo)¶
If yesOrNo is true instances of
str
are bridged as NSString instances, otherwise bridging issues aPyObjCStrBridgeWarning
warning and still bridges as an NSString instances.By default PyObjC behaves as if
setStrBridgeEnabled(True)
was called.Note
This function is not available in Python 3.x
Note
Setting this option to false is discouraged and is mostly useful when porting to Python 3.
Deprecated since version 3.0: Use
objc.options
instead
- objc.getStrBridgeEnabled()¶
Returns
True
if the str bridge is enabled andFalse
when it is not.Note
This function is not available in Python 3.x
Deprecated since version 3.0: Use
objc.options
instead
Weak references¶
- class objc.WeakRef(object)¶
It is not possible to use the
weakref
module to create weak references to Cocoa objects due to implementation restrictions (at best it would be possible to create a weakref to the Python proxy for such objects).PyObjC implements a zero-ing weakref object when running on macOS 10.7 or later. These objects more or less behave the same as
__weak
variables in Objective-C.The object must be a Cocoa object, and must not be a CoreFoundation object (unless the CoreFoundation type is transparently bridged to Cocoa).
- __call__()¶
Returns the weakly references object when that is still alive, otherwise returns
None
.Note
Unlike
weakref.ref
this class cannot be subclasses, and does not have a callback option. The callback option cannot be reliably be implemented with the current Objective-C runtime API.Warning
Some Cocoa classes do not support weak references, see Apple’s documentation for more information. Creating a weak reference to instances of such classes can be a hard error (that is, the interpreter crashes, you won’t get a nice exception).
Associated Objects¶
On macOS 10.6 or later the Objective-C runtime has an API for associated objects, which are more or less additional instance variables for objects.
- objc.setAssociatedObject(object, key, value, policy)¶
- Parameters:
object – the base object (a Cocoa instance)
value – value for the associated object
policy – policy for the association (see below)
Associate assoc with object under name name.
- objc.getAssociatedObject(object, key)¶
- Parameters:
object – an object (a Cocoa instance)
key – the key object that was used with
setAssociatedObject()
- Returns:
the value for the key, or
None
.
Returns the value of an associated object.
- objc.removeAssociatedObjects(object)¶
- Parameters:
object – an object (a Cocoa instance)
Remove all associations for object. It is generally a bad idea to use this function, because other libraries might have set associations as well.
- objc.OBJC_ASSOCIATION_ASSIGN¶
Policy for creating a weak reference to the associated object
Note
Don’t use this when the value is a pure python object, unless you arrange to keep the proxy object alive some other way.
- objc.OBJC_ASSOCIATION_RETAIN_NONATOMIC¶
Policy for creating a strong reference to the associated object.
- objc.OBJC_ASSOCIATION_COPY_NONATOMIC¶
Policy for creating a strong reference to a copy of the associated object.
- objc.OBJC_ASSOCIATION_RETAIN¶
Policy for creating a strong reference to the associated object, the association is made atomically.
- objc.OBJC_ASSOCIATION_COPY¶
Policy for creating a strong reference to a copy of the associated object, the association is made atomically.
Utilities¶
- objc.macos_available(major, minor, patch=0)¶
Returns true iff the current macOS version is at least the version specified. Use this like the “@available” construct in Objective-C.
- objc.allocateBuffer(length)¶
Returns a writable buffer object of length bytes. This function is equivalent to bytearray(length)
- objc.CFToObject()¶
Converts an object from the standard library
CF
module to a PyObjC wrapper for the same CoreFoundation object. Raises an exception when the conversion fails.Deprecated since version 2.4: part of support for the CF module in the python 2 std. library, will be removed in PyObjC 3.0.
Note
this function is not available for Python 3.
- objc.ObjectToCF()¶
Converts a PyObjC wrapper for a CoreFoundation object to an object from the standard library
CF
module for the same CoreFoundation object. Raises an exception when the conversion fails.Deprecated since version 2.4: part of support for the CF module in the python 2 std. library, will be removed in PyObjC 3.0.
Note
this function is not available for Python 3.
Accessing classes and protocols¶
- objc.lookUpClass(classname)¶
- Parameters:
classname (string) – the name of an Objective-C class
- Returns:
the named Objective-C class
- Raise:
objc.nosuchclass_error
when the class does not exist
- getClassList([ignore_invalid_identifiers]
- Returns:
a list of a classes known to the Objective-C runtime
When
ignore_invalid_identifiers
is false (the default) all classes known to the Objective-C runtime are returned, if it is true only the classes whose’s full name is a valid Python identifier are returned as well as a number of names that are known to be problematic (FB12286520)
- objc.protocolsForClass(cls)¶
Returns a list of Protocol objects that the class claims to implement directly. The cls object must a subclass of NSObject.
- objc.protocolsForProcess()¶
Returns a list of all Protocol objects known to the Objective-C runtime.
- objc.propertiesForClass(objcClass)¶
- Returns:
a list of properties from the Objective-C runtime
The return value is a list with information about properties on this class or protocol from the Objective-C runtime. This does not include properties superclasses.
Every entry in the list is dictionary with the following keys:
Key
Description
name
Name of the property (a string)
raw_attr
Raw value of the attribute string (a byte string)
typestr
The type string for this attribute (a byte string)
classname
When the type string is
objc._C_ID
this is the name of the Objective-C class (a string).readonly
True iff the property is read-only (bool)
copy
True iff the property is copying the value (bool)
retain
True iff the property is retaining the value (bool)
nonatomic
True iff the property is not atomic (bool)
dynamic
True iff the property is dynamic (bool)
weak
True iff the property is weak (bool)
collectable
True iff the property is collectable (bool)
getter
Non-standard selector for the getter method (a byte string)
setter
Non-standard selector for the setter method (a byte string)
All values but name and raw_attr are optional. The other attributes contain a decoded version of the raw_attr value. The boolean attributes should be interpreted as
False
when the aren’t present.The documentation for the Objective-C runtime contains more information about property definitions.
This function only returns information about properties as they are defined in the Objective-C runtime, that is using
@property
definitions in an Objective-C interface. Not all properties as they are commonly used in Objective-C are defined using that syntax, especially properties in classes that were introduced before MacOSX 10.5.This function always returns an empty list on macOS 10.4.
Added in version 2.3.
- objc.listInstanceVariables(classOrInstance)¶
Returns a list of information about all instance variables for a class or instance. ClassOrInstance must be a subclass of NSObject, or an instance of such a class.
The elements of the list are tuples with two elements: a string with the name of the instance variable and a byte string with the type encoding of the instance variable.
- objc.getInstanceVariable(object, name)¶
Returns the value of the instance variable name.
Warning
Direct access of instance variables should only be used as a debugging tool and could negatively affect the invariants that a class tries to maintain.
- objc.setInstanceVariable(object, name, value[, updateRefCounts])¶
Set the value of instance variable name to value. When the instance variable type encoding is
objc._C_ID
updateRefCounts must be specified and tells whether or not the retainCount of the old and new values are updated.Warning
Direct access of instance variables should only be used as a debugging tool and could negatively affect the invariants that a class tries to maintain.
Warning
It is very easy to introduce memory corruption when updateRefCounts is false. In particular the caller of this method must ensure that the Objective-C representation of value is kept alive, when value is not a Cocoa object just keeping value alive isn’t good enough.
- objc.protocolNamed(name)¶
Returns a Protocol object for the named protocol. Raises
ProtocolError
when the protocol does not exist.This is the equivalent of
@protocol(name)
in Objective-C.
- exception objc.ProtocolError¶
Raised by
protocolNamed()
when looking up a protocol that does not exist.
Dynamic modification of classes¶
- objc.classAddMethods(cls, methods)¶
Add a sequence of methods to the given class.
The effect is similar to how categories work in Objective-C. If the class already implements a method that is defined in methods the existing implementation is replaced by the new one.
The objects in methods should be one of:
selector
instances with a callable (that is, the first argument toselector
must not beNone
).classmethod
orstaticmethod
instances that wrap a function object.functions
unbound methods
For the last two the method selector is calculated using the regular algorithm for this (e.g. as if
selector(item)
was called). The last two are instance methods by default, but automatically made class methods when the class (or a superclass) has a class method with the same selector.
- objc.classAddMethod(cls, name, method)¶
Adds function method as selector name to the given class. When method is a selector the signature and class-method-ness are copied from the selector.
Note
Adding a selector that’s defined in Objective-C to another class will raise an exception.
- class objc.Category¶
A helper class for adding a category to an existing Objecive-C class (subclass of NSObject).
Usage:
class NSObject (Category(NSObject)): def method(self): pass
The metaclass uses
classAddMethods()
to add the methods in the category body to the base class.The name of the class must be the same as the argument to
Category
.This will only add new methods to existing Objective-C classes, it is in particular not possible to add new members/slots to existing classes.
Plugin bundles¶
Memory management¶
PyObjC automatically manages Cocoa reference counts for you, the functions in this section help in finetuning this behaviour.
- objc.recycleAutoreleasePool()¶
Flush the NSAutoreleasePool that PyObjC creates on import. Use this before entering the application main loop when you do a lot of work before starting the main loop.
- objc.removeAutoreleasePool()¶
Use this in plugin bundles to remove the release pool that PyObjC creates on import. In plugins this pool will interact in unwanted ways with the embedding application.
- objc.autorelease_pool()¶
A context manager that runs the body of the block with a fresh autorelease pool. The actual release pool is not accessible.
Usage:
with autorelease_pool(): pass
Test support¶
The functions in this section are present as support code for PyObjC’s unittests and are not part of the stable API. Please let us know if you use these functions in your code.
- objc.splitSignature(typestring)¶
Split an encoded Objective-C signature string into the encoding strings for separate types.
- Parameters:
typestring (byte string) – an encoded method signature (byte string)
- Returns:
list of type signatures
- Return type:
list of byte strings
- objc.splitStructSignature(typestring)¶
Returns (structname, fields). Structname is a string or
None
and fields is a list of (name, typestr) values. The name is a string orNone
and the typestr is a byte string.Raises
ValueError
when the type is not the type string for a struct type.
- objc.repythonify(object[, type])¶
Internal API for converting an object to a given Objetive-C type and converting it back again.
Framework wrappers¶
Types¶
- class objc.objc_class¶
This class is the metatype for Objective-C classes and provides no user-visible behavior.
- class objc.objc_object([cobject[, c_void_p]])¶
This class is the root class for Objective-C classes, that is all wrappers for Objective-C classes are a subclass of this class. It is not possible to instantiate instances of Objective-C classes by using the class as a callable, instances are created using the standard Objective-C mechanisms instead.
The cobject and c_void_p arguments should always be passed as keyword arguments, and at most one of them should be provided. This will construct a proxy object of the right subclass of
objc_object
for the Cocoa object that the passed in value refers to. Cobject should be a Python capsule created using the__cobject__()
method, c_void_p should be actypes.c_void_p
.Note
The normal way to create instances of (subclasses of)
objc_object
is to call the normal Cocoa allocation method. Calling the class should only be used to construct a proxy from a pre-existing pointer value (for interoperability with other libraries).- pyobjc_ISA¶
Read-only property that returns the current Objective-C classes of an object.
- pyobjc_instanceMethods¶
Read-only property that provides explicit access to just the instance methods of an object.
- __hasdict__¶
True if instances of this class have a
__dict__
and False otherwise.
- __cobject__()¶
Returns a capsule object with identifier “objc.__object__” and the a reference to the Objective-C object as the value.
- __c_void_p__()¶
Returns a
ctypes.c_void_p
instance for this object.
- __reduce__()¶
This method ensures that Objective-C objects will not be pickled unless the subclass explicitly implements the pickle protocol. This is needed because the pickle will write an incomplete serialization of Objective-C objects for protocol 2 or later.
- classmethod __class_getitem__(*args)¶
Return an object representing the specialization of a generic class by type arguments found in key.
Note
This feature requires Python 3.9 or later.
Note
The wrapper classes for the NSString class cluster aren’t subclasses of
objc_object
, but are subclasses of the builtinunicode
type (str:
in Python 3).
- class objc.pyobjc_unicode¶
This class is used to wrap instances of the NSString class cluster and is a subclass of the builtin Unicode type (
unicode
for python 2 andstr
for Python 3).Methods of the underlying NSString class can be accessed at as methods of the python type, unless they have the same name as a method of the built-in Unicode type.
- nsstring()¶
Returns an instance of a subclass of
objc_object
that represents the string. This provides full access to the Cocoa string API, but without easy interoperability with Python APIs.
Note
Instances of NSString can be mutable. Mutations to mutable Cocoa strings are not reflected in instances of
pyobjc_unicode
, usensstring()
and explicit conversion to the built-in unicode type when you work with mutable NSString values.Note
Cocoa strings are wrapped using a subclass of the built-in unicode string to get better interaction between Python and Cocoa. Because Cocoa strings are instances of the built-in unicode type they can be passed to functions in extension modules that expect unicode arguments (in particular the file system access APIs such as
open()
).
- class objc.selector(function[, selector[, signature[, isClassMethod[, returnType[, argumentTypes[, isRequired]]]]]])¶
This type is used to represent an Objective-C method.
- Parameters:
function – The Python callable that is used for the method. Can be a
classmethod
, but not astaticmethod
.selector – The Objective-C selector for the method. The default is calculated from the __name__ attribute for function
signature – The type encoding for the method, the default signature assumes that all arguments and the result are objects (or ‘void’ when the function does not contain a return statement with a value).
isClassMethod – Used to specify if a method is a class method (default is
True
if function is aclassmethod
andFalse
otherwise)isRequired – Specify if the method is required (defaults to
True
), used in the definition of protocols.
- callable¶
Read-only property with access to the underlying callable (the function argument to the constructor).
- __doc__¶
Documentation string for the selector
- __signature__¶
An
inspect.Signature
for the objectAdded in version 3.0.
Note
Only available for Python 3.3 or later.
- __metadata__()¶
Returns a copy of the metadata dictionary for the selector. See the metadata system documentation for more information.
- class objc.objc_method(callable, \*, selector=None, signature=None, isclass=None)¶
Use this as a decorator in a Cococa class definition to signal that the method should definitely be converted to on Objective-C selector, and optional set a non-default selector or signature, or signal that the method should or should-not be a class method.
- Parameters:
selector – The Objective-C selector name (byte string)
signature – The Obejctive-C method signature
isclass – If true the method is a class method, if false the method is an instance method, if
None
use the default algorithm.
Usage:
class MyClass(NSObject): @objc_method() def myAction_(self, sender): pass @objc_method(selector="buttonClicked:") def button_clicked(self, sender): pass
- class objc.python_method(callable)¶
Use this as a decorator in a Cocoa class definition to avoid creating a selector object for a method.
This is used to add “normal” python methods to a class that’s inheriting from a Cocoa class and makes it possible to use normal Python idioms in the part of the class that does not have to interact with the Objective-C world.
For example:
class MyClass (NSObject): @python_method @classmethod def fromkeys(self, keys): pass @python_method def items(self): pass
In this example class MyClass has a Python classmethod “fromkeys” and a normal method “items”, neither of which are converted to a selector object and neither of which are registered with the Objective-C runtime.
Instances of this type have an attribute named callable containing the wrapped callable, but are themselves not callable.
Added in version 3.0.
Note
If you use multiple decorators the
python_method
decorator should be the outermost decorator (that is, the first one in the list of decorators).
- class objc.ivar([name[, type[, isOutlet]]])¶
Creates a descriptor for accessing an Objective-C instance variable. This should only be used in the definition of an Objective-C subclass, the bridge will use this information to create an instance variable with the same name on the Objective-C class itself.
- Parameters:
name – Name of the instance variable. The name defaults to the name the instance variable is bound to in a class definition.
type – Type encoding for the instance variable. Defaults to
_C_ID
(that is, an object)isOutlet – If
True
the instance variable is used as an outlet, by default the instance variable is not an outlet.
Note
Sharing an ivar object between multiple class definitions is not supported.
Instances of
ivar
have a number of attributes that help with introspection:__typestr__: The type encoding of the Objective-C type of the variable. See Objective-C type strings for more information.
__name__: The Objective-C name of the variable
__isOutlet__:
True
if the variable is anIBOutlet()
__isSlot__:
True
if the variable is a Python slot.
The
ivar
has convenience class methods for creatingivar
objects for specific C types:- bool([name])¶
Create an instance variable that stores a value of C type
bool
. See the class description for a description of the name argument.
- char([name])¶
Create an instance variable that stores a value of C type
char
. See the class description for a description of the name argument. In general it is better to usechar_text()
orchar_int()
.
- int([name])¶
Create an instance variable that stores a value of C type
int
. See the class description for a description of the name argument.
- short([name])¶
Create an instance variable that stores a value of C type
short
. See the class description for a description of the name argument.
- long([name])¶
Create an instance variable that stores a value of C type
long
. See the class description for a description of the name argument.
- long_long([name])¶
Create an instance variable that stores a value of C type
long long
. See the class description for a description of the name argument.
- unsigned_char([name])¶
Create an instance variable that stores a value of C type
unsigned char
. See the class description for a description of the name argument.
- unsigned_int([name])¶
Create an instance variable that stores a value of C type
unsigned int
. See the class description for a description of the name argument.
- unsigned_short([name])¶
Create an instance variable that stores a value of C type
unsigned short
. See the class description for a description of the name argument.
- unsigned_long([name])¶
Create an instance variable that stores a value of C type
unsigned long
. See the class description for a description of the name argument.
- unsigned_long_long([name])¶
Create an instance variable that stores a value of C type
unsigned long long
. See the class description for a description of the name argument.
- float([name])¶
Create an instance variable that stores a value of C type
float
. See the class description for a description of the name argument.
- double([name])¶
Create an instance variable that stores a value of C type
double
. See the class description for a description of the name argument.
- BOOL([name])¶
Create an instance variable that stores a value of C type
BOOL
. See the class description for a description of the name argument.
- UniChar([name])¶
Create an instance variable that stores a value of C type
UniChar
. See the class description for a description of the name argument. Values are (unicode) strings of length 1.
- char_text([name])¶
Create an instance variable that stores a value of C type
char
. See the class description for a description of the name argument. Values are byte-strings of length 1.
- char_int([name])¶
Create an instance variable that stores a value of C type
char
. See the class description for a description of the name argument. Values are integers in the range of asigned char
in C.
Framework bindings introduce new class methods for creating instance variables whose type is a particular C struct, as an example the Foundation bindings introduce a class method named
NSRange
with the same signature as the methods mentioned earlier.Note
You cannot access these attributes through an Objective-C instance, you have to access them through the class object. That’s because
ivar
is a data descriptor.See also
- Function
IBOutlet()
Definition of outlets.
- class objc.informal_protocol(name, selector_list)¶
This class is used to specify which methods are part of an informal protocol in Objective-C. Informal protocols are a documentation construct in Objective-C and as such are not present in the Objective-C runtime (as opposed to formal protocols).
Informal protocols are used by the bridge to automatically update method signatures when a class appears to implement an informal protocol. This makes it possible the define a large subset of Cocoa functionality without manually setting method signatures.
- Parameters:
name – Name of the protocol
selector_list – A sequence of
selector
instances, all of which should have no callable.
- __name__¶
Read-only property with the protocol name
- selectors¶
Read-only property with the sequence of selectors for this protocol
- class objc.formal_protocol(name, supers, selector_list)¶
This class is used to represent formal protocols in Python, and is comparabile with the “@protocol” construct in Objective-C.
- Parameters:
name – The name of the protocol
supers – A list of protocols this protocol inherits from
selector_list – A sequence of
selector
instances, all of which should have no callable.
Note
Constructing new protocols is supported on a subset of macOS platforms:
All 32-bit programs
64-bit programs starting from macOS 10.7, but only when PyObjC was build with the 10.7 SDK (or later)
Note
The protocols created by PyObjC are not compatible with NSXPCInterface because that class needs information (“extended method signature”) that cannot be registered through the public API for the Objective-C runtime. See Using NSXPCInterface from Python for more information.
- __name__¶
Read-only property with the name of the protocol
- name()¶
Returns the name of the protocol
- conformsTo_(proto)¶
Returns
True
if this protocol conforms to protocol proto, returnsFalse
otherwise.
- descriptionForInstanceMethod_(selector)¶
Returns a tuple with 2 byte strings: the selector name and the type signature for the selector.
Returns
None
when the selector is not part of the protocol.
- descriptionForClassMethod_(selector)¶
Returns a tuple with 2 byte strings: the selector name and the type signature for the selector.
Returns
None
when the selector is not part of the protocol.
- instanceMethods()¶
Returns a list of instance methods in this protocol.
- classMethods()¶
Returns a list of instance methods in this protocol.
Note
The interface of this class gives the impression that a protocol instance is an Objective-C object. That was true in earlier versions of macOS, but not in more recent versions.
- class objc.varlist¶
A C array of unspecified length. Instances of this type cannot be created in Python code.
This type is used when the API does not specify the amount of items in an array in a way that is usable by the bridge.
Warning
Access through a
varlist
object can easily read or write beyond the end of the wrapped C array. Read the Apple documentation for APIs that return a varlist to determine how many elements you can safely access and whether or not the array is mutable.The C array might also be freed by C code before the
varlist
instance is garbage collected. The Apple documentation for the API should mention how long the reference is safe to use.- __typestr__¶
The type encoding for elements of the array. See Objective-C type strings for more information.
- as_tuple(count)¶
Returns a tuple containing the first count elements of the array.
- as_buffer(count)¶
Returns a writable
memoryview
referencing the memory for the first count elements of the array.Note
The returned
memoryview
is currently always a byte view, future versions might return a view with a format attribute that’s appropriate for the__typestr__
of the varlist object.
- __getitem__(index)¶
Returns the value of the index-th element of the array. Supports numeric indexes as well as slices with step 1 and a specified stop index.
Negative indexes are not supported because these objects have an unspecified length.
- __setitem__(index, value)¶
Sets the value of the index-th element of the array. Supports numeric indexes as well as slices with step 1 and a specified stop index (but assigning to a slice is only possible when that does not resize the array).
Negative indexes are not supported because these objects have an unspecified length.
Warning
When underlying data type is
objc._C_ID
(that is, an array of Cocoa objects it is very likely that the retain count of the object needs to be adjusted. The__setitem__()
method stores a reference to the object without adjusting any reference counts.The correct behavior depends on the kind of array used, when the array is documented as containing strong references you should increase the retain count of the new value and lower the retain of the old value (in that order).
- class objc.function¶
Instances of this class represent global functions from Cocoa frameworks. These objects are created using
loadBundleFunctions()
andloadFunctionList()
.- __doc__¶
Read-only property with the documentation string for the function.
- __name__¶
Read-only property with the name of the function
- __module__¶
Read-write property with the module that defined the function
- __signature__¶
An
inspect.Signature
for the objectAdded in version 3.0.
Note
Only available for Python 3.3 or later.
- __metadata__()¶
Returns a copy of the metadata dictionary for the selector. See the metadata system documentation for more information.
- class objc.IMP¶
This class is used to represent the actual implementation of an Objective-C method (basically a C function). Instances behave the same as unbound methods: you can call them but need to specify the “self” argument.
- isAlloc¶
Read-only attribute that specifies if the IMP is an allocator (that is, the implementation of “+alloc” or one of its variant)
- isClassMethod¶
Read-only attribute that specified if the IMP is for a class method.
- signature¶
Read-only attribute with the type encoding for the IMP.
- selector¶
Read-only attribute with the selector for the method that this IMP is associated with.
- __signature__¶
An
inspect.Signature
for the objectAdded in version 3.0.
Note
Only available for Python 3.3 or later.
- __metadata__()¶
Returns a copy of the metadata dictionary for the selector. See the metadata system documentation for more information.
- class objc.super¶
This is a subclass of
super
that works properly for Objective-C classes as well as regular Python classes.The regular
super
does not work correctly for Cocoa classes, the default function doesn’t support custom attribute getters as used by PyObjC.
Constants¶
- objc.nil¶
Alias for
None
, for easier translation of existing Objective-C code.
- objc.YES¶
Alias for
True
, for easier translation of existing Objective-C code.
- objc.NO¶
Alias for
False
, for easier translation of existing Objective-C code.
- objc.NULL¶
Singleton that tells the bridge to pass a
NULL
pointer as an argument when the (Objective-)C type of that argument is a pointer.This behavior of the bridge is slightly different from using
None
: withNone
the bridge will allocate some memory for output parameters and pass a pointer to that buffer, withNULL
the bridge will always pass aNULL
pointer.
- objc.PyObjC_BUILD_RELEASE¶
The version number of the SDK used to build PyObjC, the value is
major * 100 + minor
(e.g.1305
for macOS 13.5).
- objc.platform¶
This always has the value “MACOSX”.
Objective-C type strings¶
The Objective-C runtime and the PyObjC bridge represent the types of
instance variables and methods arguments and return values as a string
with a compact representation. The Python representation of that string is
a byte string (that is type bytes
in Python 3.x and str
in Python 2.x).
Basic types¶
The representation for basic types is a single character, the table below lists symbolic constants in the for those constants.
Name |
Objective-C type |
---|---|
|
id (an Objective-C instance) |
|
an Objective-C class |
|
a method selector |
|
char |
|
unsigned char |
|
short |
|
unsigned short |
|
bool (or _Bool) |
|
int |
|
unsigned int |
|
long |
|
unsigned long |
|
long long |
|
unsigned long long |
|
float |
|
double |
|
void |
|
“other” (such a function) |
|
C string (char*) |
|
BOOL |
|
UniChar |
|
char when uses as text or a byte array |
|
int8_t (or char when used as a number) |
The values _C_NSBOOL
, _C_UNICHAR
, _C_CHAR_AS_TEXT
,
and _C_CHAR_AS_INT
are inventions of PyObjC and are not used in
the Objective-C runtime.
The value _C_NSBOOL
is deprecated as of PyObjC 9, use _C_BOOL
instead. The two constants are treated exactly the same in PyObjC now that
the corresponding C types have the same representation (which wasn’t true
for PowerPC).
Complex types¶
More complex types can be represented using longer type strings:
a pointer to some type is
_C_PTR
followed by the type string of the pointed-to type.a bitfield in a structure is represented as
_C_BFLD
followed by an integer with the number of bits.Note that PyObjC cannot convert bitfields at this time.
a C structure is represented as
_C_STRUCT_B
followed by the struct name, followed by'='
, followed by the encoded types of all fields followed by_C_STRUCT_E
. The field name (including the closing equals sign) is optional.Structures are assumed to have the default field alignment, although it is possible to use a custom alignment when creating a custom type for a struct using
objc.createStructType()
.a C union is represented as
_C_UNION_B
followed by the struct name, followed by'='
, followed by the encoded types of all fields followed by_C_UNION_E
. The field name (including the closing equals sign) is optional.Note that PyObjC cannot convert C unions at this time.
a C array is represented as
_C_ARY_B
followed by an integer representing the number of items followed by the encoded element type, followed by_C_ARY_E
.The C construct ‘const’ is mapped to
_C_CONST
, that is a const char* is represented as_C_CONST
+_C_CHARPTR
.A C SIMD vector type (e.g.
vector_float3
) is represented as follows:_C_VECTOR_B
N type_C_VECTOR_E
.Matrix types (e.g.
matrix_float2x3
) are C structs containing SIMD vectors, and are represented in the usual way.These representations are not supported in the Objective-C runtime, but are inventions by PyObjC. Because libffi does not support the corresponding C types these encodings are supported in limited subset of possible method signatures (basically only those signatures that are used by Apple system libraries).
Additional prefixes¶
_C_ATOMIC
can prefix any basic C type and denotes that the value should be accessed using atomic instructions.This value is currently ignored by PyObjC.
_C_COMPLEX
can prefix any basic C type and denotes a C complex type.This value is currently not supported by PyObjC (and is not used in frameworks).
Additional annotations for method and function arguments¶
Method arguments can have prefixes that closer describe their functionality. Those prefixes are inherited from Distributed Objects are not used by the Objective-C runtime, but are used by PyObjC.
When a pointer argument is an input argument it is prefixed by
_C_IN
.When a pointer argument is an output argument it is prefixed by
_C_OUT
.When a pointer argument is an input and output argument it is prefixed by
_C_INOUT
.Distributed objects uses the prefix
_C_BYCOPY
to tell that a value should be copied to the other side instead of sending a proxy reference. This is not used by PyObjC.Distributed objects uses the prefix
_C_ONEWAY
on the method return type to tell that the method result is not used and the caller should not wait for a result from the other side. This is not used by PyObjC.
When a pointer argument to a function prefixed by _C_IN
,
_C_OUT
or _C_INOUT
the bridge assumes that it is a pass by
reference argument (that is, a pointer to a single value), unless other
information is provided to the bridge.
The _C_IN
, _C_INOUT
and _C_OUT
encodings
correspond to the keyword in
, inout
and out
in Objective-C
code. This can be used to add the right information to the Objective-C
runtime without using the metadata system. For
example:
@interface OCSampleClass
-(void)copyResourceOfName:(NSString*)name error:(out NSError**)error;
@end
This tells the compiler that error is an output argument, which doesn’t
affect code generation or compiler warnings but does result in _C_OUT
being present in the type encoding for the argument.
Special encoded types¶
The table below shows constants for a number of C types that are used in Cocoa but are not basic C types.
Constant
Objective-C type
_C_CFTYPEID
CFTypeID
_C_NSInteger
NSInteger
_C_NSUInteger
NSUInteger
_C_CFIndex
CFIndex
_C_CGFloat
CGFloat
_C_NSRange
NSRange
_C_CFRange
CFRange
_sockaddr_type
struct sockaddr
..versionadded:: 8.3
_C_NSRange, _C_CFRange
Context pointers¶
A number of Objective-C APIs have one argument that is a context pointer, which is a void*. In Objective-C your can pass a pointer to an arbitrary value, in Python this must be an integer.
PyObjC provides a context
object that can be used to allocate
unique integers and map those to objects.
- context.register(value)¶
Add a value to the context registry.
- Parameters:
value – An arbitrary object
- Returns:
A unique integer that’s suitable to be used as a context pointer (the handle).
- context.unregister(value):
Remove an object from the context registry, this object must be have been added to the registry before.
- Parameters:
value – An object in the context registry
- context.get(handle)¶
Retrieve an object from the registry given the return value from
context.register()
.
Descriptors¶
- objc.IBOutlet([name])¶
Creates an instance variable that can be used as an outlet in Interface Builder. When the name is not specified the bridge will use the name from the class dictionary.
The code block below defines an instance variable named “button” and makes that available as an outlet in Interface Builder.
class SomeObject (NSObject): button = IBOutlet()
Note
The IBOutlet function is recognized by Interface Builder when it reads Python code.
- objc.IBAction(function)¶
Mark an method as an action for use in Interface Builder. Raises
TypeError
when the argument is not a function.Usage:
class SomeObject (NSObject): @IBAction def saveDocument_(self, sender): pass
Note
The IBOutlet decorator is recognized by Interface Builder when it reads Python code. Beyond that the decoerator has no effect.
- objc.IBInspectable(prop)¶
Mark a property as a value that can be introspected in IB.
See the Xcode documentation <https://developer.apple.com/library/ios/recipes/xcode_help-IB_objects_media/chapters/CreatingaLiveViewofaCustomObject.html> for more information on this decorator.
- objc.IB_DESIGNABLE(cls)¶
Class decorator to tell IB that the class can be used in IB designs.
See the Xcode documentation <https://developer.apple.com/library/ios/recipes/xcode_help-IB_objects_media/chapters/CreatingaLiveViewofaCustomObject.html> for more information on this decorator.
- objc.instancemethod()¶
Explicitly mark a method as an instance method. Use this when PyObjC incorrectly deduced that a method should be a class method.
Usage:
class SomeObject (NSObject): @instancemethod def alloc(self): pass
Note
There is no function named objc.classmethod, use
classmethod
to explicitly mark a function as a class method.
- objc.accessor()¶
Use this decorator on the definition of accessor methods to ensure that it gets the right method signature in the Objective-C runtime.
The conventions for accessor names that can be used with Key-Value Coding is described in the Apple documentation for Key-Value Coding
The table below describes the convention for methods for a property named ‘<property>’, with a short description and notes. The Apple documentation for Key-Value Coding contains more information.
Name
Description
Notes
property
Getter for a basic property.
isProperty
Likewise, for a boolean property.
PyObjC won’t automatically set the correct property type, use
typeAccessor()
instead ofaccessor()
.setProperty_
Setter for a basic property
countOfProperty
Returns the number of items in a indexed property, or unordered property
objectInPropertyAtIndex_
Returns the object at a specific index for an indexed property
propertyAtIndexes_
Returns an array of object values at specific indexes for an indexed property. The argument is an NSIndexSet.
Don’t use this with
typedAccessor()
.getProperty_range_
Optimized accessor
Not supported by PyObjC, don’t use
insertObject_inPropertyAtIndex_
Add an object to an indexed property at a specific index.
insertProperty_atIndexes_
Insert the values from a list of at specific indices. The arguments are an NSArray and an NSIndexSet.
Don’t use this with
typedAccessor()
.removeObjectFromPropertyAtIndex_
Remove the value at a specific index of an indexed property.
removePropertyAtIndexes_
Remove the values at specific indices of an indexed property. The argument is an NSIndexSet.
replaceObjectInPropertyAtIndex_withObject_
Replace the value at a specific index of an indexed property.
replacePropertyAtIndexes_withProperty_
Replace the values at specific indices of an indexed property.
Don’t use with
typedAccessor()
enumeratorOfProperty
Returns an NSEnumerator for an unordered property.
memberOfProperty_
Returns True if the value is a member of an unordered property
addPropertyObject_
Insert a specific object in an unordered property.
addProperty_
Add a set of new values to an unordered property.
removePropertyObject_
Remove an object from an unordered property.
removeProperty_
Remove a set of objects from an unordered property.
intersectProperty_
Remove all objects from an unordered property that are not in the set argument.
validateProperty_error_
Validate the new value of a property
For typed accessor’s the value is wrapped in an NSValue (but numbers and booleans are automatically unwrapped by the bridge)
PyObjC provides another mechanism for defining properties:
object_property
.Changed in version 2.5: Added support for unordered properties. Also fixed some issues for 64-bit builds.
- objc.typedAccessor(valueType)¶
Use this decorator on the definition of accessor methods to ensure that it gets the right method signature in the Objective-C runtime.
The valueType is the encoded string for a single value.
Note
When you use a typed accessor you must also implement “setNilValueForKey_”, as described in the Apple documentation for Key-Value Coding
- objc.typedSelector(signature)¶
Use this decorator to explicitly set the type signature for a method.
An example:
@typedSelector(b'I@:d') def makeUnsignedIntegerOfDouble_(self, d): return d
Changed in version 8.3: The decorated function can now also be a
classmethod()
- objc.namedSelector(name[, signature])¶
Use this decorator to explicitly set the Objective-C method name instead of deducing it from the Python name. You can optionally set the method signature as well.
Changed in version 8.3: The decorated function can now also be a
classmethod()
- objc.callbackFor(callable[, argIndex=])¶
Use this decorator to tell that this function is the callback for an (Objective-C) API that stores a reference to the callback function.
You only have to use this API when the Objective-C API can store the callback function for later usage. For other functions the bridge can create a temporary callback stub.
Using this decorator for methods is not supported
Usage:
@objc.callbackFor(NSArray.sortedArrayUsingFunction_context\_) def compare(left, right, context): return 1
This tells the bridge that ‘compare’ is used as the sort function for NSArray, and ensures that the function will get the correct Objective-C signature.
Note
The example will also work without the decorator because NSArray won’t store a reference to the compare function that is used after ‘sortedArrayUsingFunction_context_’ returns.
- objc.callbackPointer(closure)¶
Returns a value that can be passed to a function expecting a
void *
argument. The value for closure must be a function that’s decorated withcallbackFor()
.Added in version 3.1.
- objc.selectorFor(callable[, argIndex])¶
Decorator to tell that this is the “callback” selector for another API.
Usage:
@objc.selectorFor(NSApplication.beginSheet_modalForWindow_modalDelegate_didEndSelector_contextInfo_) def sheetDidEnd_returnCode_contextInfo_(self, sheet, returnCode, info): pass
This will tell the bridge that this method is used as the end method for a sheet API, and will ensure that the method is registered with the correct Objective-C signature.
- objc.synthesize(name[, copy[, readwrite[, type[, ivarName]]]])¶
- Parameters:
name – name of the property
copy – if false (default) values are stored as is, otherwise new values are copied.
readwrite – If true (default) the property is read-write
type – an encoded type for the property, defaults to
_C_ID
.iVarName – Name of the instance variable used to store the value. Default to the name of the property prefixed by and underscore.
This synthensizes a getter, and if necessary, setter method with the correct signature. The getter and setter provide access to an instance variable.
This can be used when specific semantics are required (such as copying values before storing them).
The class
object_property
provides similar features with a nicer python interface: with that class the property behaves itself like a property for python code, with this function you still have to call accessor methods in your code.
Interacting with @synchronized
blocks¶
PyObjC provides an API that implements locking in the same way as the
@synchronized
statement in Objective-C.
with object_lock(anNSObject):
pass
Archiving Python and Objective-C objects¶
Python and Objective-C each provide a native object serialization method,
the pickle
module in Python and the NSCoding protocol in Objective-C.
It is possible to use an NSKeyedArchiver to store any Python object that can be pickled in an Objective-C serialized data object.
Due to technical details it is not possible to pickle an Objective-C object, unless someone explicitly implements the pickle protocol for such an object.
Properties¶
Introduction¶
Both Python and Objective-C have support for properties, which are object attributes that are accessed using attribute access syntax but which result in a method call.
The Python built-in property <__builtin__.property__
is used to define new
properties in plain Python code. These properties don’t full interoperate with
Objective-C code though because they do not necessarily implement the Objective-C
methods that mechanisms like Key-Value Coding use to interact with a class.
PyObjC therefore has a number of property classes that allow you to define new properties that do interact fully with the Key-Value Coding and Observation frameworks.
- class objc.object_property(name=None, read_only=False, copy=False, dynamic=False, ivar=None, typestr=_C_ID, depends_on=None)¶
- Parameters:
name – Name of the property, the default is to extract the name from the class dictionary
read_only – Is this a read-only property? The default is a read-write property.
copy – Should the default setter method copy values? The default retains the new value without copying.
dynamic – If this argument is
True
the property will not generate default accessor, but will rely on some external process to create them.ivar – Name of the instance variable that’s used to store the value. When this value is
None
the name will be calculated from the property name. If it isNULL
there will be no instance variable.typestr – The Objective-C type for this property, defaults to an arbitrary object.
depends_on – A sequence of names of properties the value of this property depends on.
During the class definition you can add accessor methods by using the property as a decorator
- object_property.getter()¶
Decorator for defining the getter method for a property. The name of the method should be the same as the property:
class MyObject (NSObject): prop = objc.object_property() @prop.getter def prop(self): return 42
- object_property.setter()¶
Decorator for defining the setter method for a property. The name of the method should be the same as the property.
- object_property.validate()¶
Decorator for defining a Key-Value Coding validator for this property.
It is possible to override property accessor in a subclass:
class MySubclass (MyObject):
@MyObject.prop.getter
def getter(self):
return "the world"
This can also be used to convert a read-only property to a read-write one by adding a setter accessor.
Properties for structured types¶
Key-Value Coding is slightly different for structured types like sets and
lists (ordered and unordered collections). For this reason PyObjC also provides
subclasses of object_property
that are tuned for these types.
- class objc.array_property¶
This property implements a list-like property. When you access the property you will get an object that implements the
MutableSequence
ABC, and that will generate the correct Key-Value Observation notifications when the datastructure is updated.
- class objc.set_property¶
This property implements a set-like property. When you access the property you will get an object that implements the
MutableSet
ABC, and that will generate the correct Key-Value Observation notifications when the datastructure is updated.
- class objc.dict_property¶
This property is like an
object_property
, but has an empty NSMutableDictionary object as its default value. This type is mostly provided to have a complete set of property types.
These collection properties are at this time experimental and do not yet provide proper hooks for tweaking their behavior. Future versions of PyObjC will provide such hooks (for example a method that will be called when an item is inserted in an array property).
Unconvertible pointer values¶
With incomplete metadata the bridge can run into pointer values that
it cannot convert to normal Python values. When
options.unknown_pointer_raises
is false such pointer values are bridged as instances of ObjCPointer
.
The bridge will unconditionally emit a warning before creating such instances,
the reason for this is that the use of ObjCPointer
is unwanted
(that’s why the creation of such objects is disabled by default in PyObjC 3.0).
“FILE*” support¶
- class objc.FILE¶
This class is only present when using Python 3 and is used to represent “FILE*” handles in Python. For Python 2 the regular “file” type is used for that.
This types provides a fairly limited file-like API for binary I/O. Instances of this type don’t close the stream automatically and don’t implement a contextmanager.
- at_eof()¶
Returns True iff the stream is at the EOF marker
- has_errors()¶
Return True iff the stream has errors.
- close()¶
Closes the stream.
- flush()¶
Flushes the file buffers.
- readline()¶
Read a single line from the stream.
- read(buffer_size)¶
Read buffer_size bytes. This returns an empty bytes object when the stream has reached end-of-file.
- write(buffer)¶
Write buffer to the stream. Returns the number of bytes that are actually written.
- tell()¶
Returns the current offset of the stream.
- seek(offset, whence)¶
Seek to the specified offset.