0
# PyObjC-Core
1

2
A comprehensive Python-to-Objective-C bridge that provides seamless interoperability between Python and Objective-C programming languages on macOS systems. PyObjC-Core enables developers to use Objective-C objects and classes as first-class Python citizens, subclass Objective-C classes from Python, and access the complete macOS development stack including Foundation and AppKit frameworks.
3

4
## Package Information
5

6
- **Package Name**: pyobjc-core
7
- **Language**: Python
8
- **Installation**: `pip install pyobjc-core`
9
- **Requires**: Python 3.8+, macOS
10

11
## Core Imports
12

13
```python
14
import objc
15
```
16

17
Common imports for specific functionality:
18

19
```python
20
# For utilities and testing
21
from PyObjCTools import TestSupport, KeyValueCoding
22

23
# Core classes and decorators
24
from objc import objc_method, python_method, IBOutlet, IBAction
25
```
26

27
## Basic Usage
28

29
```python
30
import objc
31

32
# Use Objective-C constants
33
result = objc.YES  # True
34
empty = objc.nil   # None
35

36
# Create autorelease pool context
37
with objc.autorelease_pool():
38
    # Work with Objective-C objects here
39
    pass
40

41
# Create an Objective-C method decorator
42
class MyClass:
43
    @objc_method
44
    def my_objc_method(self):
45
        return "Hello from Objective-C"
46
    
47
    @python_method
48
    def my_python_method(self):
49
        return "Hello from Python"
50

51
# Use Key-Value Coding
52
from PyObjCTools.KeyValueCoding import getKey, setKey
53

54
obj = MyClass()
55
value = getKey(obj, "someAttribute")
56
setKey(obj, "someAttribute", "new value")
57
```
58

59
## Architecture
60

61
PyObjC-Core provides a comprehensive bridge through several key components:
62

63
- **Core Bridge**: C extension module providing runtime integration
64
- **Method System**: Decorators and descriptors for method binding and Interface Builder integration
65
- **Type System**: Support for Objective-C types, SIMD vectors, and struct types
66
- **Framework Loading**: Dynamic loading and bridge support for Objective-C frameworks
67
- **Convenience Layer**: Enhanced functionality for common Objective-C classes like NSArray, NSDictionary
68

69
This architecture enables full bidirectional interoperability, allowing Python code to seamlessly interact with the entire macOS ecosystem while maintaining Python's dynamic programming model.
70

71
## Capabilities
72

73
### Core Bridge Functionality
74

75
Essential bridge components including constants, context management, and fundamental interoperability features that enable Python-Objective-C integration.
76

77
```python { .api }
78
# Constants
79
nil = None
80
YES = True  
81
NO = False
82

83
# Context management
84
class autorelease_pool:
85
    def __enter__(self): ...
86
    def __exit__(self, exc_type, value, tp): ...
87
```
88

89
[Core Bridge](./core-bridge.md)
90

91
### Method and Class Decorators
92

93
Decorators for controlling how Python methods are exposed to the Objective-C runtime, including method signatures and selector customization.
94

95
```python { .api }
96
def objc_method(value=None, *, selector=None, signature=None, isclass=None): ...
97
def python_method(value=None): ...
98
def namedSelector(name, signature=None): ...
99
def typedSelector(signature): ...
100
```
101

102
[Method Decorators](./method-decorators.md)
103

104
### Interface Builder Integration
105

106
Decorators and descriptors for creating Interface Builder-compatible outlets, actions, and properties for macOS app development.
107

108
```python { .api }
109
def IBOutlet(name=None): ...
110
def IBAction(func): ...
111
def IBInspectable(prop): ...
112
def IB_DESIGNABLE(cls): ...
113
```
114

115
[Interface Builder](./interface-builder.md)
116

117
### Property and Accessor System
118

119
Comprehensive property descriptor system for creating Key-Value Coding compliant accessors and synthesized properties.
120

121
```python { .api }
122
def accessor(func, typeSignature=b"@"): ...
123
def typedAccessor(typeSignature): ...
124
def synthesize(name, copy=False, readwrite=True, type=_C_ID, ivarName=None): ...
125
```
126

127
[Properties and Accessors](./properties-accessors.md)
128

129
### Protocol Support
130

131
Support for Objective-C formal and informal protocols, enabling proper protocol conformance and method requirements.
132

133
```python { .api }
134
def protocolNamed(name): ...
135
def informal_protocol(name): ...
136

137
class ProtocolError(Exception): ...
138
```
139

140
[Protocol Support](./protocol-support.md)
141

142
### Bridge Registration and Type System
143

144
Functions for registering Python types with the bridge system and comprehensive SIMD type support for high-performance operations.
145

146
```python { .api }
147
def registerListType(type_object): ...
148
def registerMappingType(type_object): ...
149
def registerSetType(type_object): ...
150
def registerDateType(type_object): ...
151

152
# SIMD types
153
simd_float2, simd_float3, simd_float4: type
154
matrix_float2x2, matrix_float3x3, matrix_float4x4: type
155
```
156

157
[Bridge Registration](./bridge-registration.md)
158

159
### Framework and Dynamic Loading
160

161
Utilities for loading Objective-C frameworks and libraries dynamically, including BridgeSupport file parsing and lazy module loading.
162

163
```python { .api }
164
def dyld_framework(filename, framework_name, version=None): ...
165
def dyld_library(filename, libname): ...
166
def pathForFramework(path): ...
167
def initFrameworkWrapper(...): ...
168
```
169

170
[Framework Loading](./framework-loading.md)
171

172
### Convenience Functions and Class Enhancement
173

174
Functions for adding convenience methods to Objective-C classes and registering Abstract Base Classes for better Python integration.
175

176
```python { .api }
177
def addConvenienceForClass(classname, methods): ...
178
def registerABCForClass(classname, *abc_class): ...
179
def addConvenienceForBasicMapping(name, readonly=False): ...
180
def addConvenienceForBasicSequence(name, readonly=False): ...
181
```
182

183
[Class Enhancement](./class-enhancement.md)
184

185
### PyObjCTools Utilities
186

187
Essential utilities for Key-Value Coding, signal handling, and testing support for PyObjC development.
188

189
```python { .api }
190
# Key-Value Coding
191
def getKey(obj, key): ...
192
def setKey(obj, key, value): ...
193
def getKeyPath(obj, keypath): ...
194
def setKeyPath(obj, keypath, value): ...
195

196
# Signal handling
197
def dumpStackOnFatalSignal(): ...
198
def resetFatalSignals(): ...
199
```
200

201
[PyObjCTools](./pyobjctools.md)
202

203
## Types
204

205
```python { .api }
206
# Exception types
207
class ProtocolError(Exception):
208
    """Exception for protocol-related errors."""
209

210
# Context manager
211
class autorelease_pool:
212
    """Context manager for NSAutoreleasePool management."""
213
    def __init__(self): ...
214
    def __enter__(self): ...
215
    def __exit__(self, exc_type, value, tp): ...
216

217
# Lazy loading support
218
class ObjCLazyModule:
219
    """Lazy module loading for frameworks."""
220
```