GATC - Code of Life
The Pyjsdl module is modelled on Pygame/SDL methods that wraps JavaScript functionality including HTML5 canvas. The module permits scripts coded in Python/Pygame to compile to JavaScript using the Pyjs compiler, allowing deployment of JavaScript applications without extensive editing of the script.
The following JavaScript application was deployed using Pyjsdl:
For an example, download the Python script used to compile this application, which was derived from the Serpent Duel program in Interphase Pack. This post describes the steps required to deploy an application under the Linux environment, which should provide the fundamentals for other OS environments.
To compile the script, download the Pyjsdl module and unpack into the script folder, or on the module path. A Python script requires some modification to work with Pyjsdl and to be compatible with the JavaScript. To import the Pyjsdl module, add the following statement to the script:
import pyjsdl as pygame
The statement imports the pyjsdl module and renames it pygame to maintain the validity of the Pygame statements. To adapt the script for browser compatibility, the following statement is necessary:
pyjsdl.display.setup(run, images)
The statement takes a run argument and an optional images argument, which provides the browser with a 'run' function to execute and 'images' list to preload. The importance of this statement is due to the nature of Python scripts that usually execute repetitively from a loop statement in a main function, not possible in JavaScript since the browser is single-threaded and must have its own time to do browser routines such as display update and event processing, any continuous loop would lock the browser. Place commands to be repeated for program execution in a function, for instance 'run' function, and this function is passed to the browser to call repeatedly in a time-based manner. The preloading of images is preferred since the browser will not wait until images are downloaded, once images are retrieved the application proceeds.
Other script changes required are for Pygame methods not supported by the Pyjsdl module, check the API documentation. Additional changes may be required in Python code to work with Pyjs depending on compilation mode, or code changes that are compatible to JavaScript language structure.
To compile a Python script to JavaScript, setup a Pyjs development environment. Download Pyjs, the latest update is at Pyjs git repository and follow the installation instructions - to install git build_13-06-12, unpack in a preferred folder and run 'python bootstrap.py'. Pyjs compiles JavaScript code with inclusion of browser-specific code, tests passed for the available Pyjs version with Pyjsdl to compile for the released version of Firefox, check txt file in the Pyjsdl folder for any changes that may be required for other browsers. Pyjsdl requires browsers with HTML5 canvas functionality that is supported by newer browsers. To get information on the JavaScript-compiled script, the browser needs some JavaScript tools such as browser console, check Pyjs developing information – for instance for Firefox browser the plugins Firebug and Web Developer are useful. Another tool that can be used prior to Pyjs compilation is Pyflakes that checks Python syntax.
To compile script.py, enter the following in a command terminal:
[pyjs path]/bin/pyjsbuild script.py
This command will output compiled script. Pyjs can compile in different modes as described in Pyjs guide, for instance debug mode (-d) provides Python error messages required in program development, strict mode (-S) compiles most Python syntax, and optimized mode (-O) compiles Python omitting some language constructs for smaller JavaScript code with increased performance. The optimized mode restricted Python recognition may require further changes to the script, so preferable to develop in strict mode, and make required changes for optimized mode at a later stage of development. Other useful compiling options are --enable-print-statements to enable console print output, -P that can provide list of browsers (for instance Mozilla) targeted by Pyjs, -o to choose compiling output folder, and --dynamic-link to separate Pyjs compilation of JavaScript from Html file. A couple of examples with debug -d option enabled:
pyjsbuild -S -d script.py -P Mozilla
pyjsbuild -O -d script.py --enable-print-statements -o outputdir
Pyjs compiles only code that it detects has been modified since last called, and noticed that if Pyjs compilation mode is changed, the compiled code in the output folder should be removed or choose a different output folder. The output folder will contain script.html that can be run in the browser. The script.html that is compiled runs without change in the Firefox browser.
For site deployment, script.html may need some editing such as addition of the line at the beginning of the Html file required for some browsers, and possibly other html/style changes. For possible changes to script.html, examine the demo script archive for changes made for its deployment. For deployment, my preference is to use the following compilation command:
pyjsbuild -O script.py --dynamic-link
The --dynamic-link option separates JavaScript files in the lib folder with links from the Html files, not only reducing the application size but also allowing for sharing of Pyjs/Pyjdl JavaScript files between multiple applications. For further reduction in size of the application, before deployment the JavaScript code can be compressed with YUI Compressor with the following command executed in output lib folder:
yui-compressor -o '.js$:.js' *.js
The compressed JavaScript files will replace the original. The output folder containing Html files and linked JavaScript files in the lib folder, along with images folder containing any images, can be deployed online.
For deployment of a Pyjsdl application on a website, the following Html code can be used:
<div id="app">
<div id="pyjsdl_demo" title="App: Pyjsdl Demo" class="jsapp_box">
<input type='button' value='Launch' onClick='appLauncher("pyjsdl_demo")'/>
<div class="app_title">Pyjsdl Demo</div>
</div>
</div>
This code asserts a placeholder for the application on the webpage, which is within a div section with id the application name pyjsdl_demo, with a button that calls the JavaScript function appLauncher with the application id argument to launch the application, edit this name to your application. The JavaScript function code follows:
<script type="text/javascript">
function appLauncher(app) {
var appSource = "http://website.com/apps/" + app + ".html";
document.getElementById(app).innerHTML = '<pre><iframe id=' +
app + ' name=' + app + ' src=' + appSource + '></iframe></pre>';
}
</script>
When the JavaScript function appLauncher is called from a webpage, it replaces the webpage div having the given id with an iframe containing the Pyjsdl application, adapt to your application configuration. Place this JavaScript function in an accessible location on the website, such as the webpage header or with other JavaScript functions. Further details can be found in the txt file in demo script archive. With this procedure, your Python script using the Pyjsdl module can be deployed as a JavaScript application.