0
# PyObjC Framework WebKit
1

2
Python bindings for Apple's WebKit and JavaScriptCore frameworks on macOS, enabling developers to integrate web browser functionality and JavaScript execution capabilities into their Python applications. This framework provides comprehensive wrappers for WebKit's web view components, navigation controls, and browser engine features, along with JavaScriptCore's JavaScript interpreter and execution environment.
3

4
## Package Information
5

6
- **Package Name**: pyobjc-framework-WebKit
7
- **Language**: Python (binding to Objective-C frameworks)
8
- **Installation**: `pip install pyobjc-framework-WebKit`
9
- **Platform**: macOS only
10
- **Dependencies**: `pyobjc-core`, `pyobjc-framework-Cocoa`
11

12
## Core Imports
13

14
```python
15
import WebKit
16
import JavaScriptCore
17
```
18

19
For accessing specific WebKit classes:
20

21
```python
22
from WebKit import WKWebView, WKWebViewConfiguration, WebView
23
from JavaScriptCore import JSContext, JSValue
24
```
25

26
## Basic Usage
27

28
### WebKit Web View
29

30
```python
31
import WebKit
32
from Foundation import NSURL
33
from AppKit import NSApplication, NSWindow, NSWindowStyleMask
34

35
# Create a modern web view
36
config = WebKit.WKWebViewConfiguration.alloc().init()
37
web_view = WebKit.WKWebView.alloc().initWithFrame_configuration_(
38
    ((0, 0), (800, 600)), config
39
)
40

41
# Load a web page
42
url = NSURL.URLWithString_("https://www.example.com")
43
request = WebKit.WKWebViewNavigationAction.alloc().init()
44
web_view.loadRequest_(request)
45

46
# Handle navigation
47
class NavigationDelegate:
48
    def webView_didFinishNavigation_(self, web_view, navigation):
49
        print("Page loaded successfully")
50

51
delegate = NavigationDelegate()
52
web_view.setNavigationDelegate_(delegate)
53
```
54

55
### JavaScript Execution
56

57
```python
58
import JavaScriptCore
59

60
# Create JavaScript context
61
context = JavaScriptCore.JSContext.alloc().init()
62

63
# Execute JavaScript code
64
result = context.evaluateScript_("1 + 2 * 3")
65
print(result.toNumber())  # Output: 7
66

67
# Handle exceptions
68
def exception_handler(context, exception):
69
    print(f"JavaScript error: {exception}")
70

71
context.setExceptionHandler_(exception_handler)
72

73
# Create JavaScript values
74
number_value = JavaScriptCore.JSValue.valueWithDouble_inContext_(42.5, context)
75
string_value = JavaScriptCore.JSValue.valueWithObject_inContext_("Hello World", context)
76
bool_value = JavaScriptCore.JSValue.valueWithBool_inContext_(True, context)
77
```
78

79
## Architecture
80

81
The pyobjc-framework-WebKit package provides two distinct but complementary frameworks:
82

83
### WebKit Framework Architecture
84
- **Legacy WebView**: Original WebKit web view component (WebView class)
85
- **Modern WKWebView**: Current WebKit web view with improved security and performance
86
- **DOM Classes**: Complete Document Object Model representation for web content manipulation
87
- **Navigation System**: URL loading, history management, and navigation policies
88
- **Configuration System**: User scripts, content rules, and web view behavior customization
89

90
### JavaScriptCore Framework Architecture
91
- **JSContext**: JavaScript execution environment and global object management
92
- **JSValue**: Bridge between JavaScript values and Python objects
93
- **Low-level C API**: Direct access to JavaScript engine functions for advanced use cases
94
- **Export System**: Mechanisms for exposing Python objects to JavaScript code
95

96
This dual-framework approach enables creating everything from simple web content display to sophisticated browser applications with custom JavaScript integration, making it ideal for macOS developers building applications that need to display web content, execute JavaScript code, or create browser-like interfaces.
97

98
## Capabilities
99

100
### Modern WebKit Components
101

102
Modern WKWebView-based web browsing with security, performance, and feature improvements over legacy WebView. Includes configuration, navigation, user content management, and delegate-based event handling.
103

104
```python { .api }
105
class WKWebView:
106
    def initWithFrame_configuration_(self, frame, configuration): ...
107
    def loadRequest_(self, request): ...
108
    def loadHTMLString_baseURL_(self, string, baseURL): ...
109
    def goBack(self): ...
110
    def goForward(self): ...
111
    def reload(self): ...
112
    def evaluateJavaScript_completionHandler_(self, javaScriptString, completionHandler): ...
113

114
class WKWebViewConfiguration:
115
    def init(self): ...
116
    @property
117
    def userContentController(self): ...
118
    @property 
119
    def preferences(self): ...
120
    @property
121
    def websiteDataStore(self): ...
122
```
123

124
[Modern WebKit](./modern-webkit.md)
125

126
### Legacy WebKit Components
127

128
Original WebView component and related classes for backward compatibility. While superseded by WKWebView, still used in some applications and provides additional DOM manipulation capabilities.
129

130
```python { .api }
131
class WebView:
132
    def initWithFrame_frameName_groupName_(self, frame, frameName, groupName): ...
133
    def canShowMIMEType_(self, MIMEType): ...
134
    def goBack(self): ...
135
    def goForward(self): ...
136
    def searchFor_direction_caseSensitive_wrap_(self, string, forward, caseFlag, wrapFlag): ...
137
    def isLoading(self): ...
138
    def setDrawsBackground_(self, flag): ...
139

140
class WebPreferences:
141
    def init(self): ...
142
    def setJavaEnabled_(self, flag): ...
143
    def setJavaScriptEnabled_(self, flag): ...
144
```
145

146
[Legacy WebKit](./legacy-webkit.md)
147

148
### DOM Manipulation
149

150
Complete Document Object Model classes for programmatic web content manipulation. Provides access to HTML elements, events, CSS styles, and document structure.
151

152
```python { .api }
153
class DOMDocument:
154
    def getElementById_(self, elementId): ...
155
    def createElement_(self, tagName): ...
156
    def execCommand_(self, command): ...
157
    def hasFocus(self): ...
158

159
class DOMElement:
160
    def getAttribute_(self, name): ...
161
    def setAttribute_value_(self, name, value): ...
162
    def hasAttribute_(self, name): ...
163
    def scrollIntoView_(self, alignToTop): ...
164

165
class DOMHTMLInputElement(DOMElement):
166
    @property
167
    def value(self): ...
168
    @property
169
    def checked(self): ...
170
    @property
171
    def disabled(self): ...
172
```
173

174
[DOM Manipulation](./dom-manipulation.md)
175

176
### JavaScript Integration
177

178
JavaScript execution environment and value management through JavaScriptCore. Enables running JavaScript code, bridging between Python and JavaScript objects, and handling JavaScript exceptions.
179

180
```python { .api }
181
class JSContext:
182
    def init(self): ...
183
    def evaluateScript_(self, script): ...
184
    def setExceptionHandler_(self, handler): ...
185
    def isInspectable(self): ...
186
    def setInspectable_(self, inspectable): ...
187

188
class JSValue:
189
    def isArray(self): ...
190
    def isBoolean(self): ...
191
    def isNumber(self): ...
192
    def isString(self): ...
193
    def isObject(self): ...
194
    def isNull(self): ...
195
    def isUndefined(self): ...
196
    def toBool(self): ...
197
    def toNumber(self): ...
198
    def toString(self): ...
199
    def hasProperty_(self, property): ...
200
    def deleteProperty_(self, property): ...
201

202
def JSExportAs(PropertyName, Selector): ...
203
```
204

205
[JavaScript Integration](./javascript-integration.md)
206

207
### Navigation and URL Handling
208

209
URL loading, navigation management, browser history, and network request handling. Includes both modern WKNavigation system and legacy navigation approaches.
210

211
```python { .api }
212
class WKNavigation:
213
    pass  # Opaque navigation identifier
214

215
class WKNavigationAction:
216
    @property
217
    def request(self): ...
218
    @property
219
    def navigationType(self): ...
220
    @property
221
    def sourceFrame(self): ...
222
    @property
223
    def targetFrame(self): ...
224

225
class WKNavigationResponse:
226
    @property
227
    def response(self): ...
228
    @property
229
    def isForMainFrame(self): ...
230
    @property
231
    def canShowMIMEType(self): ...
232

233
class WKBackForwardList:
234
    @property
235
    def currentItem(self): ...
236
    @property
237
    def backItem(self): ...
238
    @property
239
    def forwardItem(self): ...
240
    def itemAtIndex_(self, index): ...
241
```
242

243
[Navigation and URL Handling](./navigation.md)
244

245
### Content Management
246

247
User scripts, content rules, cookie management, and website data handling. Provides control over web content behavior, security policies, and data storage.
248

249
```python { .api }
250
class WKUserContentController:
251
    def init(self): ...
252
    def addUserScript_(self, userScript): ...
253
    def removeAllUserScripts(self): ...
254
    def addScriptMessageHandler_name_(self, scriptMessageHandler, name): ...
255
    def addContentRuleList_(self, contentRuleList): ...
256

257
class WKUserScript:
258
    def initWithSource_injectionTime_forMainFrameOnly_(self, source, injectionTime, forMainFrameOnly): ...
259

260
class WKScriptMessage:
261
    @property
262
    def body(self): ...
263
    @property
264
    def webView(self): ...
265
    @property
266
    def frameInfo(self): ...
267
    @property
268
    def name(self): ...
269

270
class WKHTTPCookieStore:
271
    def getAllCookies_(self, completionHandler): ...
272
    def setCookie_completionHandler_(self, cookie, completionHandler): ...
273
    def deleteCookie_completionHandler_(self, cookie, completionHandler): ...
274
```
275

276
[Content Management](./content-management.md)
277

278
### Constants and Enumerations
279

280
Navigation types, error codes, content policies, and other enumerated values used throughout the WebKit and JavaScriptCore frameworks.
281

282
```python { .api }
283
# WK Navigation Types
284
WKNavigationTypeLinkActivated = 0
285
WKNavigationTypeFormSubmitted = 1
286
WKNavigationTypeBackForward = 2
287
WKNavigationTypeReload = 3
288
WKNavigationTypeFormResubmitted = 4
289
WKNavigationTypeOther = -1
290

291
# WK Navigation Policies
292
WKNavigationActionPolicyCancel = 0
293
WKNavigationActionPolicyAllow = 1
294
WKNavigationActionPolicyDownload = 2
295

296
# JavaScript Types
297
kJSTypeUndefined = 0
298
kJSTypeNull = 1
299
kJSTypeBoolean = 2
300
kJSTypeNumber = 3
301
kJSTypeString = 4
302
kJSTypeObject = 5
303
kJSTypeSymbol = 6
304

305
# Error Codes
306
WKErrorUnknown = 1
307
WKErrorWebContentProcessTerminated = 2
308
WKErrorWebViewInvalidated = 3
309
WKErrorJavaScriptExceptionOccurred = 4
310
```
311

312
[Constants and Enumerations](./constants.md)