Package: pythonista-wkwebview
pythonista-webviewWKWebView implementation for Pythonista.The underlying component used to implement ui.WebView in Pythonista is
UIWebView, which has been deprecated since iOS 8. This module implements a
Python webview API using the current iOS-provided view, WKWebView. Besides
being Apple-supported, WKWebView brings other benefits such as better
Javascript performance and an official communication channel from
Javascript to Python. This implementation of a Python API also has the
additional benefit of being inheritable.Available as asingle fileon GitHub, or install with:pip install pythonista-wkwebviewin stash.Run the file as-is to try out some of the capabilities; check the end of the
file for demo code.Credits: This would not exist without @JonB and @mithrendal (Pythonista
forum handles).Basic usageWKWebView matches ui.WebView API as defined in Pythonista docs. For example:v = WKWebView()
v.present()
v.load_html('<body>Hello world</body>')
v.load_url('http://omz-software.com/pythonista/')For compatibility, there is also the same delegate API that ui.WebView has,
withwebview_should_start_loadetc. methods.Deviations from ui.WebView APISynchronous vs. asynchronous JS evaluationApple's WKWebView only provides an async Javascript evaluation function.
This is available as aneval_js_asyncmethod, with an optionalcallbackargument that will be called with a single argument containing the result of
the JS evaluation (or None).We also provide a synchronouseval_jsmethod, which essentially waits for
the callback before returning the result. For this to work, you have to call
theeval_jsmethod outside the main UI thread, e.g. from a method decorated
withui.in_background.Handling page scalingUIWebView had a property calledscales_page_to_fit, WKWebView does not. See
below for the variousdisablemethods that can be used instead.Additional features and noteshttp allowedLooks like Pythonista has the specific plist entry required to allow fetching
non-secure http urls.Cache and timeoutsFor remote (non-file)load_urlrequests, there are two additional options:Setno_cachetoTrueto skip the local cache, default isFalseSettimeoutto a specific timeout value, default is 10 (seconds)You can also explicitly clear all data types from the default data store with
theclear_cacheinstance method. The method takes an optional parameter, a
plain function that will be called when the async cache clearing operation is
finished:def cleared():
  print('Cache cleared')

WKWebView().clear_cache(cleared)Media playbackFollowing media playback options are available as WKWebView constructor
parameters:inline_media- whether HTML5 videos play inline or use the native
full-screen controller. The default value for iPhone is False and the
default value for iPad is True.airplay_media- whether AirPlay is allowed. The default value is True.pip_media- whether HTML5 videos can play picture-in-picture.
The default value is True.Other url schemesIf you try to open a url not natively supported by WKWebView, such astel:for phone numbers, thewebbrowsermodule is used to open it.Swipe navigationThere is a new property,swipe_navigation, False by default. If set to True,
horizontal swipes navigate backwards and forwards in the browsing history.Note that browsing history is only updated for calls toload_url-load_htmlis ignored (Apple feature that has some security justification).Data detectionBy default, no Apple data detectors are active for WKWebView. You can activate
them by including one or a tuple of the following values as thedata_detectorsargument to the constructor: NONE, PHONE_NUMBER, LINK,
ADDRESS, CALENDAR_EVENT, TRACKING_NUMBER, FLIGHT_NUMBER, LOOKUP_SUGGESTION,
ALL.For example, activating just the phone and link detectors:v = WKWebView(data_detectors=(WKWebView.PHONE_NUMBER, WKWebView.LINK))Messages from JS to PythonWKWebView comes with support for JS-to-container messages. Use this by
subclassing WKWebView and implementing methods that start withon_and
accept one message argument. These methods are then callable from JS with the
pithywindow.webkit.messageHandler.<name>.postMessagecall, where<name>corresponds to whatever you have on the method name after theon_prefix.Here's a minimal example:class MagicWebView(WKWebView):
  
  def on_magic(self, message):
    print('WKWebView magic ' + message)
    
html = '''
<body>
<button onclick="window.webkit.messageHandlers.magic.postMessage(\'spell\')">
Cast a spell
</button>
</body>
'''

v = MagicWebView()
v.load_html(html)Note that JS postMessage must have a parameter, and the message argument to
the Python handler is always a string version of that parameter. For
structured data, you need to use e.g. JSON at both ends.User scripts a.k.a. script injectionWKWebView supports defining JS scripts that will be automatically loaded with
every page.Use theadd_script(js_script, add_to_end=True)method for this.Scripts are added to all frames. Removing scripts is currently not implemented.Following two convenience methods are also available:add_style(css)to add a style tag containing the given CSS style
definition.add_meta(name, content)to add a meta tag with the given name and content.Making a web page behave more like an appThese methods set various style and meta tags to disable typical web
interaction modes:disable_zoomdisable_user_selectiondisable_font_resizingdisable_scrolling(alias for settingscroll_enabledto False)There is also a convenience method,disable_all, which calls all of the
above.Note that disabling user selection will also disable the automatic data
detection of e.g. phone numbers, described earlier.Javascript debuggingJavascript errors and console messages are sent to Python side and printed to
Pythonista console. Supported JS console methods arelog,info,warnanderror.For further JS debugging and experimentation, there is a simple convenience
command-line utility that can be used to evaluate load URLs and evaluate
javascript. If youpresentyour app as a 'panel', you can easily switch
between the tabs for your web page and this console.Or you can just create a WKWebView manually for quick experimentation, like
in the usage example below.>>> from wkwebview import *
>>> v = WKWebView(name='Demo')
>>> WKWebView.console()
Welcome to WKWebView console. Evaluate javascript in any active WKWebView.
Special commands: list, switch #, load <url>, quit
js> list
0 - Demo - 
js> load http://omz-software.com/pythonista/
js> list
0 - Demo - Pythonista for iOS
js> document.title
Pythonista for iOS
js> quit
>>> v2 = WKWebView(name='Other view')
>>> WKWebView.console()
Welcome to WKWebView console. Evaluate javascript in any active WKWebView.
Special commands: list, switch #, load <url>, quit
js> list
0 - Demo - Pythonista for iOS
1 - Other view - 
js> switch 1
js> load https://www.python.org
js> document.title
Welcome to Python.org
js> window.doesNotExist.wrongFunction()
ERROR: TypeError: undefined is not an object
(evaluating 'window.doesNotExist.wrongFunction')
(https://www.python.org/, line: 1, column: 20)
None
js> quitSetting a custom user agentWKWebView has auser_agentproperty that can be used to retrieve or set a
value reported to the server when requesting pages.Customize Javascript popupsJavascript alert, confirm and prompt dialogs are now implemented with simple
Pythonista equivalents. If you need something fancier or e.g.
internationalization support, subclass WKWebView and re-implement the
following methods as needed:def _javascript_alert(self, host, message):
  console.alert(host, message, 'OK', hide_cancel_button=True)
  
def _javascript_confirm(self, host, message):
  try:
    console.alert(host, message, 'OK')
    return True
  except KeyboardInterrupt:
    return False
  
def _javascript_prompt(self, host, prompt, default_text):
  try:
    return console.input_alert(host, prompt, default_text, 'OK')
  except KeyboardInterrupt:
    return None