Package pycocoa :: Module runtime

Module runtime

Classes ObjCClass, ObjCInstance, ObjCMethod, ObjCSubclass, etc.

For debugging purposes, enable logging to the console by setting env variable PYCOCOA_OBJC_LOG to a string of one or more of the following letters:

% env PYCOCOA_OBJC_LOG=ICSMBDPX python3 ...

where I logs __new__ and __del__ Instance calls, C new Classes, S new Subclasses, M new Methods, B new BoundMethods, D draining of, P printing of NSAutoreleasePools and X send_message, send_super, (rather libobjc.objc_msgSend and libobjc.objc_msgSendSuper) calls.

Use env variable PYCOCOA_LIBOBJC_NONATOMIC=on to detect non-atomic calls of certain libobjc functions.

Version: 25.04.07

Classes
	ObjCBoundMethod Python wrapper for a bound ObjC instance method, an IMP_t.
	ObjCBoundClassMethod Python wrapper for a bound ObjC class method, only to distinguish bound class from bound instance methods.
	ObjCClass Python wrapper for an ObjC class.
	ObjCDelegate Register the `_NS_Delegate._ObjC` (sub)class and create an ObjCClass`(_NS_Delegate.__name__)`.
	ObjCInstance Python wrapper for an ObjC instance.
	ObjCConstant Python wrapper for an ObjC constant.
	ObjCMethod Python class representing an unbound ObjC instance method, actually an IMP_t.
	ObjCClassMethod Python class representing an unbound ObjC class method, only to distinguish class methods from instance methods.
	ObjCSubclass Python class creating an ObjC sub-class of an existing ObjC (super)class.

Functions

add_ivar(clas, name, ctype)
Add an instance variable to an ObjC class,

add_method(clas, name_, method, encoding)
Add a method to an ObjC class.

add_protocol(clas, protocol)
Add a protocol to an ObjC class.

add_subclass(Super, name, register=False)
Create a new sub-class of a given super-class.

drain(objc)
Release all objects in an NSAutoreleasePool instance.

isClass(objc)
Check whether an object is an ObjC class.

isImmutable(objc, *immutableClasses, **raiser_name)
Check that an ObjC object is an immutable class' instance.

isMetaClass(objc)
Check whether an object is an ObjC metaclass.

isMutable(objc, *mutableClasses, **raiser_name)
Check that an ObjC object is a mutable class' instance.

isObjCInstanceOf(objc, *Classes, **raiser_name)
Check whether an ObjC object is an instance of some ObjC class.

register_subclass(subclas)
Register an ObjC sub-class.

release(objc)
Release an ObjC instance to be deleted, eventually.

retain(objc)
Preserve an ObjC instance from destruction.

send_message(objc, sel_name_, *args, **restype_argtypes)
Send message to an ObjC object.

send_super(objc, sel_name_, *args, **restype_argtypes)
Send message to the super-class of an ObjC object.

send_super_init(objc)
Send 'init' message to the super-class of an ObjC object.

set_ivar(objc, name, value, ctype=None)
Set an instance variable of an ObjC object.

Variables
	__all__ = `_ALL_LAZY.runtime`
	OBJC_ASSOCIATION = `OBJC_ASSOCIATION.ASSIGN...` `libObjC.objc_setAssociatedObject` associations (`mask`).
	OBJC_ASSOCIATION.ASSIGN 0x0
	OBJC_ASSOCIATION.COPY 0x303
	OBJC_ASSOCIATION.COPY_NONATOMIC 0x3
	OBJC_ASSOCIATION.RETAIN 0x301
	OBJC_ASSOCIATION.RETAIN_NONATOMIC 0x1

Function Details

add_ivar(clas, name, ctype)

Add an instance variable to an ObjC class,

Parameters:

clas - Class to add the ivar to (ObjCClass/Subclass).
name - Name of the ivar (str).
ctype - The ivar type code (ctypes or encoding).

Returns:

True if the ivar was added, False otherwise.

Raises:

TypeCodeError - Invalid ctype.

Note: The ctype must be a ctypes type or a valid ObjC type encoding.

See Also: The _ObjCDeallocObserver below.

add_method(clas, name_, method, encoding)

Add a method to an ObjC class.

Parameters:

clas - Class to add the method to (ObjCClass/Subclass).
name_ - Selector name (str).
method - Decorated class or instance method (callable).
encoding - Method signature (encoding).

Returns:

The method (IMP_t) if added, None otherwise.

Raises:

TypeError - If method is not a Python callable.

add_protocol(clas, protocol)

Add a protocol to an ObjC class.

Parameters:

clas - Class to add the protocol to (ObjCClass/Subclass).
protocol - The protocol to add (str or Protocol_t instance).

Returns:

The protocol (Protocol_t) if added, None otherwise.

add_subclass(Super, name, register=False)

Create a new sub-class of a given super-class.

Parameters:

Super - The parent class (str or Object).
name - The name of the sub-class (str).
register - Optionally, register the new sub-class (bool).

Returns:

The sub-class (Class_t) if added, None otherwise.

Note: After calling add_subclass, you MUST register the new sub-class with register_subclass, before using the new sub-class. New methods can be added after the sub-class has been registered, but any ivars must be added BEFORE.

drain(objc)

Release all objects in an NSAutoreleasePool instance.

Returns:: The number of ObjC objects cleared.

Note: NSAutoreleasePool.drain invokes the dealloc method only for the pool itself, not for any of the objects held/allocated in the pool.

isClass(objc)

Check whether an object is an ObjC class.

Parameters:

objc - Object to check (Object or Class).

Returns:

True if the objc is a clas, False if not or Noneis unknown.

isImmutable(objc, *immutableClasses, **raiser_name)

Check that an ObjC object is an immutable class' instance.

Parameters:

objc - The instance to check (ObjCInstance).
immutableClasses - Optional immutable classes to use (NS... or Objects), in lieu of all predefined ones.
raiser_name - Optional instance name (str) to raise TypeError.

Returns:

True if objc is immutable, False otherwise.

Raises:

TypeError - If objc isn't immutable, but only if keyword raiser='...' is specified.

isMetaClass(objc)

Check whether an object is an ObjC metaclass.

Parameters:

objc - Object to check (Object or Class).

Returns:

True if the objc is a metaclass, False if not or None if unknown.

isMutable(objc, *mutableClasses, **raiser_name)

Check that an ObjC object is a mutable class' instance.

Parameters:

objc - The instance to check (ObjCInstance).
mutableClasses - Optional mutable classes to use (NSMutable...s or Objects), in lieu of all predefined ones.
raiser_name - Optional instance name (str) to raise TypeError.

Returns:

True if objc is mutable, False otherwise.

Raises:

TypeError - If objc isn't mutable, but only if keyword raiser='...' is specified.

isObjCInstanceOf(objc, *Classes, **raiser_name)

Check whether an ObjC object is an instance of some ObjC class.

Parameters:

objc - The instance to check (ObjCInstance or c_void_p).
Classes - One or several ObjC classes (Object).
raiser_name - Optional instance name (str) to raise TypeError.

Returns:

The matching Class from Classes, None otherwise.

Raises:

TypeError - If objc is not an ObjCInstance or c_void_p or if objc isn't any Classes' instance and only if keyword raiser='...' is specified.

See Also: Function isinstanceOf for checking Python instances.

register_subclass(subclas)

Parameters:

subclas - Class to be registered (Class).

See Also: ObjCSubclass.register.

release(objc)

Release an ObjC instance to be deleted, eventually.

Parameters:

objc - The instance to release (ObjCInstance).

Returns:

The instance objc.

Raises:

TypeError - If objc is not releasable.

Note: May result in Python memory errors, aborts and/or segfaults. Use 'python3 -X faulthandler ...' to get a Python traceback in such circumstances.

retain(objc)

Preserve an ObjC instance from destruction.

Parameters:

objc - The instance to retain (ObjCInstance).

Returns:

The retained instance objc.

Raises:

TypeError - If objc is not retainable.

Note: May result in Python memory errors, aborts and/or segfaults. Use 'python3 -X faulthandler ...' to get a Python traceback in such circumstances.

send_message(objc, sel_name_, *args, **restype_argtypes)

Send message to an ObjC object.

Parameters:

objc - The recipient (Object, Id_t, etc.) instance.
sel_name_ - Message selector (SEL_t) or name (str or bytes).
args - Message arguments (all positional).
resargtypes - Optional, result and argument types (ctypes).

Returns:

Message result (restype).

Raises:

ArgumentError - Invalid objc, sel_name_, args or resargtypes.
TypeError - Invalid objc, sel_name_, args or resargtypes type.

Note: By default, the result and any arguments are c_void_p wrapped. Use keyword arguments restype=c_void_p and argtypes=[] to change the defaults. The restype defines the ctypes type for the returned result and argtypes is the list of ctypes types for the message arguments only without the Id/self and SEL/cmd arguments.

send_super(objc, sel_name_, *args, **restype_argtypes)

Send message to the super-class of an ObjC object.

Parameters:

objc - The recipient (Object, Id_t, etc.) instance.
sel_name_ - Message selector (SEL_t) or name (str or bytes).
args - Message arguments (all positional).
resargtypes - Optional, result and argument types (ctypes).

Returns:

Message result (restype).

Raises:

ArgumentError - Invalid objc, sel_name_, args or resargtypes.
TypeError - Invalid objc, sel_name_, args or resargtypes type.

send_super_init(objc)

Send 'init' message to the super-class of an ObjC object.

Parameters:

objc - The recipient (Object, Id_t, etc.) instance.

Returns:

Message result (Id_t).

set_ivar(objc, name, value, ctype=None)

Set an instance variable of an ObjC object.

Parameters:

objc - The instance (Object).
name - Name of the ivar (str).
value - New value for the ivar (any).
ctype - Optional, the ivar type (ctypes).

Returns:

The ivar (Ivar_t).

Raises:

ArgumentError - Invalid name, value or ctype.
TypeError - Invalid name, value or ctype type.

Variables Details

OBJC_ASSOCIATION

libObjC.objc_setAssociatedObject associations (mask).

Value:

OBJC_ASSOCIATION.ASSIGN=0,
                .COPY=771,
                .COPY_NONATOMIC=3,
                .RETAIN=769,
                .RETAIN_NONATOMIC=1