0
# PyObjC
1

2
PyObjC is a comprehensive Python-to-Objective-C bridge that enables seamless integration between Python and Objective-C code on macOS. It allows developers to create full-featured Cocoa applications in pure Python, access macOS system frameworks, and mix Python with Objective-C, C, and C++ code.
3

4
## Package Information
5

6
- **Package Name**: pyobjc
7
- **Language**: Python  
8
- **Installation**: `pip install pyobjc`
9
- **Documentation**: https://pyobjc.readthedocs.io/en/latest/
10

11
## Core Imports
12

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

17
For utility tools:
18

19
```python
20
from PyObjCTools import KeyValueCoding, TestSupport
21
```
22

23
## Basic Usage
24

25
```python
26
import objc
27
from Foundation import NSString, NSArray
28

29
# Working with Objective-C classes
30
hello = NSString.stringWithString_("Hello, World!")
31
print(hello.length())  # 13
32

33
# Creating and using Objective-C objects
34
array = NSArray.arrayWithObjects_("foo", "bar", "baz", None)
35
print(array.count())  # 3
36
print(array.objectAtIndex_(1))  # bar
37

38
# Using the bridge constants
39
print(objc.YES)  # True
40
print(objc.NO)   # False
41
print(objc.nil)  # None
42

43
# Proper memory management with autorelease pools
44
with objc.autorelease_pool():
45
    # Intensive Objective-C operations that create temporary objects
46
    for i in range(1000):
47
        temp_string = NSString.stringWithFormat_("Item %d", i)
48
        # Objects are automatically released when pool exits
49

50
# Manual pool management (less common)
51
objc.recycleAutoreleasePool()
52
```
53

54
## Architecture 
55

56
PyObjC consists of two main components:
57

58
- **pyobjc-core**: The fundamental bridge implementation that handles Python-Objective-C interoperability, method calling, memory management, and type conversion
59
- **Framework packages**: 100+ specialized packages (pyobjc-framework-*) that provide Python bindings for specific macOS frameworks
60

61
### Framework Package Structure
62

63
PyObjC provides comprehensive coverage of macOS frameworks through specialized packages:
64

65
**Core Frameworks:**
66
- `pyobjc-framework-Cocoa` - Foundation, AppKit, CoreFoundation (essential UI and system APIs)
67
- `pyobjc-framework-CoreData` - Object-relational mapping and data persistence
68
- `pyobjc-framework-CoreGraphics` - 2D graphics rendering and PDF generation
69

70
**Media and Graphics:**
71
- `pyobjc-framework-AVFoundation` - Audio/video capture, playback, and editing
72
- `pyobjc-framework-Metal` - GPU programming and graphics acceleration
73
- `pyobjc-framework-Vision` - Computer vision and image analysis
74
- `pyobjc-framework-CoreImage` - Image processing and filtering
75

76
**Web and Networking:**
77
- `pyobjc-framework-WebKit` - Web browser engine integration
78
- `pyobjc-framework-Network` - Modern networking APIs
79
- `pyobjc-framework-CFNetwork` - Core networking functionality
80

81
**Development Tools:**
82
- `pyobjc-framework-Quartz` - PDF and graphics utilities
83
- `pyobjc-framework-ScriptingBridge` - Application automation
84

85
Each framework package uses lazy loading for optimal performance and automatically handles framework initialization, type bridging, and method signature resolution. The bridge provides seamless integration with over 100 system frameworks while maintaining Pythonic interfaces and automatic memory management.
86

87
## Capabilities
88

89
### Core Bridge Functions
90

91
Fundamental bridge functionality including class lookup, runtime access, memory management, and bridge configuration. These functions provide the foundation for all Python-Objective-C interoperability.
92

93
```python { .api }
94
def lookUpClass(name: str): ...
95
def getClassList(): ...
96
def recycleAutoreleasePool(): ...
97
options: object  # Bridge configuration (objc.options.verbose = True/False)
98
```
99

100
[Core Bridge Functions](./core-bridge.md)
101

102
### Method and Class Decorators
103

104
Decorators and utilities for creating Objective-C methods, defining method signatures, creating categories, and handling protocol conformance. Essential for creating Python classes that integrate with Objective-C.
105

106
```python { .api }
107
def signature(signature: str): ...
108
def callbackFor(signature: str): ...
109
def category(baseClass): ...
110
def synthesize(name: str, copy=None): ...
111
```
112

113
[Method and Class Decorators](./decorators.md)
114

115
### Framework and Library Loading
116

117
Dynamic loading of macOS frameworks and libraries, bundle resource access, and framework initialization. Enables runtime access to system frameworks and custom libraries.
118

119
```python { .api }
120
def dyld_framework(path: str): ...
121
def pathForFramework(name: str): ...
122
def inBundle(bundlePath: str): ...
123
```
124

125
[Framework Loading](./framework-loading.md)
126

127
### Type System and Bridging
128

129
Type encoding, signature parsing, struct type creation, and bridge support utilities. Handles the complex type conversion between Python and Objective-C type systems.
130

131
```python { .api }
132
def splitSignature(signature: str): ...
133
def createStructType(name: str, signature: str, typeids): ...
134
def registerMetaDataForSelector(classname: str, selector: str, metadata): ...
135
```
136

137
[Type System](./type-system.md)
138

139
### Protocol Support
140

141
Protocol management, formal and informal protocol definition, and protocol conformance checking. Essential for implementing Objective-C protocols in Python.
142

143
```python { .api }
144
def protocolNamed(name: str): ...
145
def informal_protocol(name: str, selectors): ...
146
def formal_protocol(name: str, supers, selectors): ...
147
```
148

149
[Protocol Support](./protocols.md)
150

151
### Utility Tools
152

153
Key-Value Coding, testing support, signal handling, and other utility functions. Provides additional functionality for common PyObjC development patterns.
154

155
```python { .api }
156
def getKey(object, key: str): ...
157
def setKey(object, key: str, value): ...
158
class TestCase: ...
159
```
160

161
[Utility Tools](./utilities.md)
162

163
### Categories and Method Addition
164

165
Dynamic method addition to existing Objective-C classes through categories. Enables extending system frameworks and third-party classes without subclassing.
166

167
```python { .api }
168
def category(baseClass): ...
169
def classAddMethod(targetClass, method, targetMethod): ...
170
class Category: ...
171
```
172

173
[Categories and Method Addition](./categories.md)
174

175
## Constants and Types
176

177
```python { .api }
178
# Bridge Constants
179
nil = None
180
YES = True  
181
NO = False
182

183
# Core Classes
184
class NSObject: 
185
    """Base class for all Objective-C objects"""
186
    
187
class selector: 
188
    """Represents an Objective-C selector (method name)"""
189
    
190
class objc_method: 
191
    """Represents an Objective-C method with type information"""
192
    
193
class autorelease_pool:
194
    """Context manager for autorelease pool management"""
195
    def __enter__(self): ...
196
    def __exit__(self, exc_type, value, tp): ...
197

198
# Exception Classes
199
class error(Exception): 
200
    """Base PyObjC exception"""
201
    
202
class nosuchclass_error(Exception): 
203
    """Raised when an Objective-C class cannot be found"""
204
    
205
class internal_error(Exception): 
206
    """Raised for internal PyObjC errors"""
207

208
# Type Encoding Constants
209
_C_ID: str       # '@' - Object pointer
210
_C_CLASS: str    # '#' - Class
211
_C_SEL: str      # ':' - Selector  
212
_C_CHR: str      # 'c' - char
213
_C_INT: str      # 'i' - int
214
_C_FLT: str      # 'f' - float
215
_C_DBL: str      # 'd' - double
216
_C_BOOL: str     # 'B' - BOOL
217
_C_VOID: str     # 'v' - void
218
_C_PTR: str      # '^' - pointer
219
```