janusnic / batavia

Tools to run Python bytecode in the browser.

Batavia

Tools to run Python bytecode in the browser.

This is experimental code. If it breaks, you get to keep all the shiny pieces.

What it does:

• Implements a Python 3.4 Bytecode machine that can handle function calls and basic class definitions.
• Unmarshals Base64 encoded bytecode into Code objects
• Implements most of the common Python VM opcodes
• Allows access to the DOM using import dom,

What it doesn't do:

• Make a good distinction between integer and floating point math
• Any attempt at unicode handling.
• Raise errors (especially TypeErrors during math operations) in exactly the same way as Python
• Support all Python's builtin functions
• Support the full Python standard library
• Allow for class inheritance

Quickstart

The testserver directory contains a minimal Django project that will serve Python bytecode to your browser and execute it. To run this project, you'll need to be running Python 3.4. Install Django 1.8 into your virtual environment; then, at a shell prompt:

$ cd testserver
$ ./manage.py runserver

You can then load http://127.0.0.1:8000 in your browser. When the page loads, you will see a set of buttons corresponding to Python modules that have been embedded in the page:

• The PyStone performance benchmark. The Python bytecode is embedded as a string in the HTML file.

• sample.py, a simple Python example demonstrating basic VM features.

  The PYC content that is dynamically generated on the server and served to the client. This file imports a second file, other.py, to demonstrate how imports work.

Click one of the buttons, and the code will run; stdout/stderr has been redirected to the webpage, so if the script has any output, you'll see it.

To start tinkering, make changes to testserver/sample.py, reload the page, and click the button.

Documentation

Documentation for Batavia can be found on Read The Docs.

Why "Batavia?"

On 27 October, 1628, Commandeur Francisco Pelsaert took command of the Batavia, and with 340 passengers and crew, set sail from Texel. Their destination? The Spice Islands - or more specifically, island of Java in the Dutch East Indies (now part of Indonesia).

The Batavia was... a Java ship (rimshot!).

Interestingly, during the voyage, Ariaen Jacobsz and onderkoopman Jeronimus Cornelisz incited a mutiny, because they didn't want to go to Java - they wanted to escape to start a new life somewhere else. As a result of the mutiny, on 4 June 1629, the Batavia ran aground on Morning Reef, part of the Houtman Abrolhos, about 450km North of Perth, Western Australia, where this project was conceived.

The full story of the Batavia is known to most Western Australian schoolchildren, and is a harrowing tale of intrigue, savagery, and murder. It serves as a reminder of what can happen when you force people to go to Java :-)

The wreck of the Batavia was recovered in the 1970s, and now stands in the shipwrecks gallery of the Western Australian Maritime Museum.

Community

Batavia is part of the BeeWare suite. You can talk to the community through:

• @pybeeware on Twitter
• The BeeWare Users Mailing list, for questions about how to use the BeeWare suite.
• The BeeWare Developers Mailing list, for discussing the development of new features in the BeeWare suite, and ideas for new tools for the suite.

Contributing

If you experience problems with Batavia, log them on GitHub. If you want to contribute code, please fork the code and submit a pull request.