After giving up on CoffeeScript, I decided to play around with Pyjaco the Python to Javascript Compiler.
While the code is readable, there is very little in the way of end-user documentation. I hope to address this with this blog post. The Pyjaco examples all embed generated javascript in an html page. I needed a way to generate an external Javascript file as I would include in an HTML file. I also wanted to find out if I could use Pyjaco with jQuery.
The first step was to install a development version of Pyjaco:
git clone https://github.com/chrivers/pyjaco.git |
Pyjaco normally requires a generated Javascript file mapping Python builtins to Javascript to be included with the created Javascripts. This must be generated:
cd pyjaco python2 generate_library.py cp py-builtins.js ~/pyjaco_test # directory for my new page |
The next step was to create an HTML file that included jquery, the py-builtins.js script above, and a yet-to be defined javascript file named clicker.js that will be generated from a yet-to-be-defined python file. I also add a couple of DOM elements (a heading and paragraph) that are to be manipulated via jQuery:
<!DOCTYPE html>
<html>
<head>
<script type=”text/javascript” src=”jquery-1.6.4.min.js”></script>
<script type=”text/javascript” src=”py-builtins.js”></script>
<script type=”text/javascript” src=”clicker.js”></script>
</head>
<body>
<h1>Click me</h1>
<p id=”when_clicked”></p>
</body>
</html>
That’s the easy part. Writing python code that compiles to correct Javascript is the hard part. Pyjaco doesn’t currently provide very useful compile-time errors, and it also does not yet map javascript errors back to the input python.
There are (at least) two ways to compile python code in Pyjaco. The first, which is used in the Pyjaco examples, and appears to be the preferred method at this time is to create a custom main() method that uses various pyjaco.Compiler methods to combine the functions into a string of text. See https://github.com/chrivers/pyjaco/tree/devel/examples for three examples.
However, I was looking to have a complete python file that compiles to a complete javascript file. Pyjaco supports this as well, using the provided pyjs.py script. It took some investigating to understand how to reference javascript variables inside python functions. Decorator syntax is used to expose the variables for jQuery, Math.random, and Math.floor in the following example. The mystifying bit is that because we will be compiling this file to javascript as a string, it is not necessary (or possible) to import the JSVar decorator, as was done in the Pyjaco examples linked above.
# clicker.py @JSVar("jQuery") def ready(): jQuery('h1').click(on_click) @JSVar("jQuery", "Math.random", "Math.floor") def on_click(): if jQuery('#when_clicked').html(): r = Math.floor(Math.random() * 255) g = Math.floor(Math.random() * 255) b = Math.floor(Math.random() * 255) color = "rgb(%d, %d, %d)" %(r,g,b) jQuery('#when_clicked').attr('style', 'background-color: ' + color) else: jQuery('#when_clicked').html("you clicked it!") jQuery(ready) |
Notice that I’m using the jQuery function instead of the $ alias, since $ is not a valid variable name in Python. This is a rather odd looking mix of Python and Javascript functions, but it works.
I had to repeat the compile and test step a few times before coming up with the above file. The script can be compiled using the pyjs.py that comes with the pyjaco source distribution (and, thanks to a simple patch I submitted, will come with the binary distribution in the next release.) Here’s how the script is run:
python2 ~/code/pyjaco/pyjs.py -N --output clicker.js clicker.py |
The -N option tells pyjs not to generate the builtin library that we created manually in the first step.
This translation step creates a clicker.js file that looks like this:
var ready = function() { var __kwargs = __kwargs_get(arguments); var __varargs = __varargs_get(arguments); var $v1 = Array.prototype.slice.call(arguments).concat(js(__varargs)); jQuery("h1").click(on_click); return None; } var on_click = function() { var __kwargs = __kwargs_get(arguments); var __varargs = __varargs_get(arguments); var $v2 = Array.prototype.slice.call(arguments).concat(js(__varargs)); if (bool(jQuery("#when_clicked").html()) === True) { var r = Math.floor((Math.random()) * (255)); var g = Math.floor((Math.random()) * (255)); var b = Math.floor((Math.random()) * (255)); var color = str('rgb(%d, %d, %d)').PY$__mod__(tuple([r, g, b])); jQuery("#when_clicked").attr("style", ("background-color: ") + (color)); } else { jQuery("#when_clicked").html("you clicked it!"); } return None; } jQuery(ready); |
I find this rather unfortunately difficult to read. There is code for argument parsing that would not have been needed if I had hand-written javascript. Further the use of “mock” python builtins makes the javascript look less javascripty. However, the original python file looks much more readable than an equivalent javascript one would. I am hopeful that improvements to pyjaco will cause it to generate more readable javascript with less extraneous code.
The entire example can be found on my github fork
Christian Iversen is actively working on Pyjaco right now. I am excited about this project and hope that further community involvement will help it evolve into a practical and useful tool. I intend my next patch to be an autocompile tool that monitors files in one directory for change and outputs .js files in another directory, one of CoffeeScript’s killer features. I am also considering a port to Python 3.