WKApp is a modern, lightweight and minimal application framework for developing Python applications with desktop-class HTML 5 based user interfaces on Apple iOS devices in the Pythonista 3 IDE for iOS.
It is a comprehensive and fully featured alternative to Pythonista's native app ui library, allowing user interfaces to be created with standard web technologies. Using powerful Python templating for dynamic HTML5/CSS/JavaScript views rendering with Mako, simple instanced view state binding supporting auto-wiring GET/POST values and two way Python/JavaScript interop via JSON over thread-safe message handlers.
Creating user interfaces for Python Apps in Pythonista becomes as simple as adding new .html view template files into your project. Which are then served locally from a Bottle.py HTTP/WSGI server and shown in a native WKWebView browser component. WKApp supports creating user interfaces with anything supported by modern web browsers using HTML5, CSS, JavaScript or even WebAssembly and browser based 2D/3D graphics!
Pip is the recommended installation method for WKApp.
Install StaSh for Pythonista 3 using the installation instructions from its README first.
Then install the pythonista-wkapp module with pip.
pip install pythonista-wkapp
Alternatively you can also clone or download a zip of this repository and copy/extract the project files into site-packages/wkapp.
To create an app, simply add a folder somewhere containing an app.py file as follows.
from wkapp import *
app = WKApp(__file__)
app.run()Run this file and you should see a fullscreen browser control and the main view index.html placeholder page shown. You can then start making your own views straight away!
To replace the initial main view / index.html placeholder page:
- Create a
viewsfolder in the same folder as yourapp.pyfile. - Create a file
views/index.html. - Then add your html and setup a
view_classmixin definition like as below.- An instance of this class will be maintained with your view which can be used to store state, bind/manipulate elements, provide functions to be called from Javascript and evaluate Javascript from Python in the view to inspect and alter the DOM or backend state.
A simple views/index.html view example:
<%!
class ViewClass:
def on_init(self):
self.name = ''
def view_action(self, text,*args):
print(text,args)
self.element('header').set('text',f'hello javascript! text was {text} args were {args}')
view_class = ViewClass
%><!-- inherit from the view.html template to render the views content inside the apps customisable base layout and structure -->
<%inherit file="view.html"/>
<!-- Your page content goes here -->
<script type="text/javascript">
function invoke_view_action() {
view.invoke('view_action', 'hello python!',
{pass:'any',json:['compatible'], args:{ints:1}, floats:0.5},
['lists',{},1,2.2],
'strings',
'numbers',1,1.5
);
}
</script>
<button onclick="invoke_view_action()">Call Python</button>
<button onclick="app.exit()">Exit Application</button>
<div>
<h1 id="header">Hello World!</h1>
<form method="POST">
<label>Enter your name:</label>
<input name="name" type="text" value="${view.name}" />
<br />
<input type="submit" value="Submit" />
</form>
% if view.name != '':
<h2> Hello ${view.name}! </h2>
% endif
</div>Note: Code above is one file, it is just shown in two parts here for code highlighting purposes.
Disclaimer: DeepWiki documentation is AI generated, some inaccuracies or incorrect details are present and should be expected, if in doubt always reference the code. Further content with more agent guidance and wrangling to attempt to improve this documentations accuracy will be added on-going.
WKApp requires the Pythonista 3 app on iOS to run but otherwise uses a minimal set of dependencies:
- Bottle.py 0.13.4
- Mako 1.13.10
- pythonista-wkwebview 1.2 (Bundled)
- 1.2 is an extended version for WKApp, updated with fixes and new features for using the native WKWebView from UIKit on iOS. Including a WKURLSchemeHandler implementation allowing creating custom url schemes with a single handler in a subclass, simplified javascript handlers threading concerns with a Dispatcher, arbitrary arguments passing from javascript to python via json.
- 1.1 Gist (@sbbosco)
- 1.0 Github (@mikaelho)
The base app html template bundles with it Bootstrap and JQuery to offer a way to just start developing apps rapidly right away straight out of the box.
However if you prefer other frameworks the base/app.html template can also be customised.
Simply create a copy of views/base/app.html from the repository and add it to your views folder in the same structure views/base/app.html.
Any base template file may be replaced in this same way.