0
# PyObjC Framework Cocoa
1

2
A comprehensive Python package providing Objective-C bindings for Apple's core Cocoa frameworks on macOS. This package enables Python developers to access native macOS APIs through CoreFoundation, Foundation, and AppKit frameworks, plus utility tools for application development.
3

4
## Package Information
5

6
- **Package Name**: pyobjc-framework-Cocoa
7
- **Language**: Python
8
- **Installation**: `pip install pyobjc-framework-Cocoa`
9
- **Dependencies**: `pyobjc-core>=10.3.2`
10

11
## Core Imports
12

13
Framework packages can be imported individually or together:
14

15
```python
16
import Cocoa           # Top-level access to AppKit functionality
17
import Foundation      # Foundation framework classes and functions
18
import CoreFoundation  # Core Foundation framework
19
import AppKit          # AppKit GUI framework
20
import CGL             # OpenGL framework bindings
21
```
22

23
Utility tools are imported separately:
24

25
```python
26
from PyObjCTools import AppHelper     # Application lifecycle utilities
27
from PyObjCTools import Conversion    # Python/ObjC conversion utilities
28
from PyObjCTools import AppCategories # AppKit class enhancements (auto-applied)
29
from PyObjCTools import FndCategories # Foundation class enhancements (auto-applied)
30
```
31

32
## Basic Usage
33

34
```python
35
import Foundation
36
import AppKit
37
from PyObjCTools import AppHelper
38

39
# Create Foundation objects
40
string = Foundation.NSString.stringWithString_("Hello, macOS!")
41
array = Foundation.NSMutableArray.array()
42
array.addObject_(string)
43

44
# Work with AppKit for GUI applications
45
app = AppKit.NSApplication.sharedApplication()
46
window = AppKit.NSWindow.alloc().initWithContentRect_styleMask_backing_defer_(
47
    Foundation.NSMakeRect(100, 100, 400, 300),
48
    AppKit.NSWindowStyleMaskTitled | AppKit.NSWindowStyleMaskClosable,
49
    AppKit.NSBackingStoreBuffered,
50
    False
51
)
52
window.setTitle_("PyObjC Window")
53
window.makeKeyAndOrderFront_(None)
54

55
# Use PyObjCTools for event loop management
56
AppHelper.runEventLoop()
57
```
58

59
## Architecture
60

61
The package provides a hierarchical framework structure:
62

63
- **Framework Bindings**: Direct Python access to Apple's Objective-C frameworks through dynamic attribute resolution
64
- **Enhanced Classes**: Python-friendly convenience methods added to native Objective-C classes
65
- **Utility Tools**: Higher-level helper functions for common application development tasks
66
- **Type System**: Complete bridging between Python and Objective-C types with automatic conversion
67

68
The framework bindings use PyObjC's metadata-driven approach to provide access to thousands of Objective-C classes, methods, and constants without requiring explicit wrapper code for each API element.
69

70
## Capabilities
71

72
### Core Foundation Framework
73

74
Low-level C API framework providing fundamental data types, memory management, and system services that form the foundation of macOS development.
75

76
```python { .api }
77
# Object creation functions
78
def CFArrayCreate(values): ...
79
def CFDictionaryCreate(keys, values): ...
80
def CFSetCreate(values): ...
81
def CFSTR(string): ...
82

83
# Localization functions
84
def CFCopyLocalizedString(key, comment): ...
85
def CFCopyLocalizedStringFromTable(key, table, comment): ...
86
```
87

88
[Core Foundation](./core-foundation.md)
89

90
### Foundation Framework
91

92
High-level Objective-C framework providing object-oriented wrappers around Core Foundation, including collections, strings, dates, and system services.
93

94
```python { .api }
95
# Special constants and types
96
NSDecimal: type
97
YES: bool
98
NO: bool
99
NSNotFound: int
100

101
# Localization functions
102
def NSLocalizedString(key, comment): ...
103
def NSLocalizedStringFromTable(key, table, comment): ...
104

105
# Utility functions
106
def MIN(a, b): ...
107
def MAX(a, b): ...
108
def ABS(x): ...
109
```
110

111
[Foundation Framework](./foundation.md)
112

113
### AppKit Framework
114

115
The Cocoa user interface framework providing windows, views, controls, and event handling for building native macOS applications.
116

117
```python { .api }
118
# Utility functions
119
def NSDictionaryOfVariableBindings(*names): ...
120

121
# Global application instance
122
NSApp: object
123

124
# Character constants
125
NSEnterCharacter: str
126
NSBackspaceCharacter: str
127
NSTabCharacter: str
128
# ... and many more special characters
129
```
130

131
[AppKit Framework](./appkit.md)
132

133
### PyObjCTools Utilities
134

135
High-level utility functions and classes that simplify common PyObjC development tasks including application lifecycle management and data conversion.
136

137
```python { .api }
138
# Application lifecycle (PyObjCTools.AppHelper)
139
def runEventLoop(): ...
140
def stopEventLoop(): ...
141
def callAfter(func, *args, **kwargs): ...
142
def callLater(delay, func, *args, **kwargs): ...
143

144
# Data conversion (PyObjCTools.Conversion)
145
def pythonCollectionFromPropertyList(collection): ...
146
def propertyListFromPythonCollection(collection): ...
147
def toPythonDecimal(decimal): ...
148
def fromPythonDecimal(decimal): ...
149
```
150

151
[PyObjCTools Utilities](./pyobjctools.md)
152

153
### Enhanced Classes
154

155
Python-friendly enhancements to native Objective-C classes providing dictionary-like access, iteration support, and context managers.
156

157
```python { .api }
158
# Foundation enhancements
159
NSCache.__getitem__(key): ...
160
NSCache.__setitem__(key, value): ...
161
NSIndexSet.__len__(): ...
162
NSIndexSet.__iter__(): ...
163

164
# AppKit enhancements  
165
NSFontDescriptor.__getitem__(key): ...
166
NSFontDescriptor.get(key, default): ...
167

168
# Context managers
169
NSDisabledAutomaticTermination: type
170
NSDisabledSuddenTermination: type
171
```
172

173
[Enhanced Classes](./enhanced-classes.md)
174

175
## Framework Coverage
176

177
This package provides comprehensive access to:
178

179
- **CoreFoundation**: 3,451+ lines of metadata covering fundamental C APIs
180
- **Foundation**: 12,192+ lines of metadata covering Objective-C foundation classes
181
- **AppKit**: 20,739+ lines of metadata covering user interface framework
182
- **OpenGL**: Basic bindings for OpenGL framework through CGL
183
- **PyObjCTools**: 25+ utility functions across 4 modules
184

185
The metadata-driven bindings provide access to thousands of Objective-C classes, methods, and constants, enabling development of native macOS applications and system integration tools in Python.