0
# Type System and Bridging
1
2
Type encoding, signature parsing, struct type creation, and bridge support utilities. The type system handles the complex conversion between Python and Objective-C type systems, enabling seamless interoperability between the two languages.
3
4
## Capabilities
5
6
### Type Signature Parsing
7
8
Functions for parsing and manipulating Objective-C type signatures.
9
10
```python { .api }
11
def splitSignature(signature: str):
12
"""
13
Parse an Objective-C method type signature into components.
14
15
Args:
16
signature (str): Objective-C type encoding string (e.g., "v@:i")
17
18
Returns:
19
tuple: (return_type, arg_types) where each is a type encoding
20
21
Usage:
22
return_type, arg_types = objc.splitSignature("i@:@@")
23
# return_type = "i" (int)
24
# arg_types = ["@", ":", "@", "@"] (object, selector, object, object)
25
"""
26
27
def splitStructSignature(signature: str):
28
"""
29
Parse a struct type signature into field components.
30
31
Args:
32
signature (str): Struct type encoding string
33
34
Returns:
35
list: List of field type encodings
36
"""
37
```
38
39
### Struct Type Management
40
41
Functions for creating and managing custom struct types that bridge between Python and Objective-C.
42
43
```python { .api }
44
def createStructType(name: str, signature: str, typeids):
45
"""
46
Create a new struct type for use in the bridge.
47
48
Args:
49
name (str): Name for the struct type
50
signature (str): Type encoding signature for the struct
51
typeids: Type identifier information
52
53
Returns:
54
A new struct type class that can be used in Python
55
56
Usage:
57
PointStruct = objc.createStructType(
58
"Point",
59
"{CGPoint=dd}", # struct with two doubles
60
None
61
)
62
point = PointStruct(10.0, 20.0)
63
"""
64
65
def createOpaquePointerType(name: str, doc: str = None):
66
"""
67
Create an opaque pointer type for the bridge.
68
69
Args:
70
name (str): Name of the opaque pointer type
71
doc (str, optional): Documentation string
72
73
Returns:
74
The new opaque pointer type class
75
76
Usage:
77
FileHandle = objc.createOpaquePointerType("FileHandle", "File handle pointer")
78
"""
79
80
def registerStructAlias(originalName: str, aliasName: str):
81
"""
82
Register an alias for an existing struct type.
83
84
Args:
85
originalName (str): Original struct type name
86
aliasName (str): Alias name to register
87
88
Usage:
89
objc.registerStructAlias("CGPoint", "NSPoint")
90
"""
91
```
92
93
### Method Metadata Registration
94
95
Functions for registering metadata about Objective-C methods to improve bridge behavior.
96
97
```python { .api }
98
def registerMetaDataForSelector(classname: str, selector: str, metadata):
99
"""
100
Register metadata for a specific method selector.
101
102
Args:
103
classname (str): Name of the Objective-C class
104
selector (str): Method selector name
105
metadata: Dictionary containing method metadata
106
107
Metadata can include:
108
- Method signature
109
- Argument type information
110
- Return type information
111
- Memory management hints
112
"""
113
```
114
115
### Method Calling Infrastructure
116
117
Low-level functions for calling Objective-C methods with proper type conversion.
118
119
```python { .api }
120
def callInstanceMethod(obj, selector: str, signature: str, args: tuple, kwds: dict):
121
"""
122
Call an instance method on an Objective-C object.
123
124
Args:
125
obj: The Objective-C object instance
126
selector (str): Method selector name
127
signature (str): Method type signature
128
args (tuple): Positional arguments
129
kwds (dict): Keyword arguments
130
131
Returns:
132
The method's return value, converted to Python types
133
"""
134
135
def callClassMethod(cls, selector: str, signature: str, args: tuple, kwds: dict):
136
"""
137
Call a class method on an Objective-C class.
138
139
Args:
140
cls: The Objective-C class
141
selector (str): Method selector name
142
signature (str): Method type signature
143
args (tuple): Positional arguments
144
kwds (dict): Keyword arguments
145
146
Returns:
147
The method's return value, converted to Python types
148
"""
149
```
150
151
### Abstract Base Class Registration
152
153
Functions for integrating with Python's ABC (Abstract Base Class) system.
154
155
```python { .api }
156
def registerABCForClass(cls):
157
"""
158
Register an Abstract Base Class for an Objective-C class.
159
160
Args:
161
cls: The Objective-C class to register ABC support for
162
163
This enables isinstance() and issubclass() checks between
164
Python ABCs and Objective-C classes.
165
"""
166
```
167
168
## Type Encoding Constants
169
170
PyObjC uses Objective-C type encoding characters to represent types:
171
172
```python { .api }
173
# Basic type encodings
174
_C_ID = b'@' # Objective-C object
175
_C_CLASS = b'#' # Class object
176
_C_SEL = b':' # Selector
177
_C_CHR = b'c' # Character (signed char)
178
_C_UCHR = b'C' # Unsigned character
179
_C_SHT = b's' # Short
180
_C_USHT = b'S' # Unsigned short
181
_C_INT = b'i' # Integer
182
_C_UINT = b'I' # Unsigned integer
183
_C_LNG = b'l' # Long
184
_C_ULNG = b'L' # Unsigned long
185
_C_FLT = b'f' # Float
186
_C_DBL = b'd' # Double
187
_C_BOOL = b'B' # Boolean
188
_C_VOID = b'v' # Void
189
_C_PTR = b'^' # Pointer
190
_C_STRUCT_B = b'{' # Structure begin
191
_C_STRUCT_E = b'}' # Structure end
192
_C_ARY_B = b'[' # Array begin
193
_C_ARY_E = b']' # Array end
194
```
195
196
## SIMD Vector and Matrix Types
197
198
High-performance vector and matrix types for mathematical operations and graphics programming.
199
200
### Integer Vector Types
201
202
```python { .api }
203
class simd_int2:
204
"""2-component 32-bit signed integer vector"""
205
206
class simd_int3:
207
"""3-component 32-bit signed integer vector"""
208
209
class simd_int4:
210
"""4-component 32-bit signed integer vector"""
211
212
class simd_uint2:
213
"""2-component 32-bit unsigned integer vector"""
214
215
class simd_uint3:
216
"""3-component 32-bit unsigned integer vector"""
217
218
class simd_uint4:
219
"""4-component 32-bit unsigned integer vector"""
220
```
221
222
### Float Vector Types
223
224
```python { .api }
225
class simd_float2:
226
"""2-component 32-bit float vector"""
227
228
class simd_float3:
229
"""3-component 32-bit float vector"""
230
231
class simd_float4:
232
"""4-component 32-bit float vector"""
233
234
class simd_double2:
235
"""2-component 64-bit double vector"""
236
237
class simd_double3:
238
"""3-component 64-bit double vector"""
239
240
class simd_double4:
241
"""4-component 64-bit double vector"""
242
```
243
244
### Short and Character Vector Types
245
246
```python { .api }
247
class simd_short2:
248
"""2-component 16-bit signed integer vector"""
249
250
class simd_ushort2:
251
"""2-component 16-bit unsigned integer vector"""
252
253
class simd_ushort3:
254
"""3-component 16-bit unsigned integer vector"""
255
256
class simd_ushort4:
257
"""4-component 16-bit unsigned integer vector"""
258
259
class simd_uchar16:
260
"""16-component 8-bit unsigned character vector"""
261
```
262
263
### Matrix Types
264
265
```python { .api }
266
class matrix_float2x2:
267
"""2x2 matrix of 32-bit floats"""
268
269
class matrix_float3x3:
270
"""3x3 matrix of 32-bit floats"""
271
272
class matrix_float4x3:
273
"""4x3 matrix of 32-bit floats"""
274
275
class matrix_float4x4:
276
"""4x4 matrix of 32-bit floats"""
277
278
class matrix_double4x4:
279
"""4x4 matrix of 64-bit doubles"""
280
```
281
282
### Quaternion Types
283
284
```python { .api }
285
class simd_quatf:
286
"""Quaternion with 32-bit float components"""
287
288
class simd_quatd:
289
"""Quaternion with 64-bit double components"""
290
```
291
292
### Legacy Vector Type Aliases
293
294
```python { .api }
295
# Legacy aliases for backward compatibility
296
vector_int2 = simd_int2
297
vector_int3 = simd_int3
298
vector_int4 = simd_int4
299
vector_uint2 = simd_uint2
300
vector_uint3 = simd_uint3
301
vector_uint4 = simd_uint4
302
vector_float2 = simd_float2
303
vector_float3 = simd_float3
304
vector_float4 = simd_float4
305
vector_double2 = simd_double2
306
vector_double3 = simd_double3
307
vector_double4 = simd_double4
308
vector_short2 = simd_short2
309
vector_ushort2 = simd_ushort2
310
vector_ushort3 = simd_ushort3
311
vector_ushort4 = simd_ushort4
312
vector_uchar16 = simd_uchar16
313
```
314
315
## Usage Examples
316
317
### Working with Method Signatures
318
319
```python
320
import objc
321
322
# Parse a method signature
323
signature = "i@:@@" # int methodWithObject:andObject:
324
return_type, arg_types = objc.splitSignature(signature)
325
326
print(f"Return type: {return_type}") # "i" (integer)
327
print(f"Argument types: {arg_types}") # ["@", ":", "@", "@"]
328
329
# The arguments are:
330
# "@" - self (object)
331
# ":" - _cmd (selector)
332
# "@" - first object parameter
333
# "@" - second object parameter
334
```
335
336
### Creating Custom Struct Types
337
338
```python
339
import objc
340
341
# Create a Point struct type
342
Point = objc.createStructType(
343
"Point",
344
"{Point=dd}", # struct with two doubles: x and y
345
None
346
)
347
348
# Use the struct type
349
point1 = Point(10.0, 20.0)
350
point2 = Point(x=30.0, y=40.0)
351
352
print(f"Point 1: ({point1.x}, {point1.y})") # (10.0, 20.0)
353
print(f"Point 2: ({point2.x}, {point2.y})") # (30.0, 40.0)
354
355
# Register an alias for the struct
356
objc.registerStructAlias("CGPoint", Point)
357
```
358
359
### Registering Method Metadata
360
361
```python
362
import objc
363
364
# Register metadata for a custom method
365
objc.registerMetaDataForSelector(
366
"MyCustomClass",
367
"processData:withOptions:",
368
{
369
'signature': b'@@:@@',
370
'arguments': {
371
2: {'type': b'@', 'description': 'Input data'},
372
3: {'type': b'@', 'description': 'Processing options'}
373
},
374
'return': {'type': b'@', 'description': 'Processed result'}
375
}
376
)
377
```
378
379
### Low-level Method Calling
380
381
```python
382
import objc
383
from Foundation import NSString
384
385
# Get a string object
386
string_obj = NSString.stringWithString_("Hello")
387
388
# Call a method using the low-level interface
389
result = objc.callInstanceMethod(
390
string_obj,
391
"uppercaseString",
392
"@@:", # return object, self object, selector
393
(), # no additional arguments
394
{} # no keyword arguments
395
)
396
397
print(result) # "HELLO"
398
```