pycocoa.runtime

Package pycocoa :: Module runtime |
[frames] | no frames]

# 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 `NSAutoreleasePool`s 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.03.24

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 clas. |
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`...`` `Libs,ObjC.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 `ivar`s 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 clas. Parameters: `objc` - Object to check (`Object` or `Class`). Returns: True if the objc is a clas, False otherwise.

### 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 `Object`s), 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 otherwise.

### 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 `Object`s), 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) |
Register an ObjC sub-class. 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. 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_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 `Libs,ObjC.objc_setAssociatedObject` associations (`mask`). Value:
      OBJC_ASSOCIATION.ASSIGN=0,
                      .COPY=771,
                      .RETAIN=769