Javascript for refined palates: a Python 3 to ES6 Javascript translator
Project description
It is based on previous work by Andrew Schaaf.
- author:
Alberto Berti
- contact:
- license:
GNU General Public License version 3 or later
Goal
JavaScripthon is a small and simple Python 3.5+ translator to JavaScript which aims to be able to translate most of the Python’s core semantics without providing a full python-in-js environment, as most existing translators do. It tries to emit code which is simple to read and check and it does so by switching to ES6 construct when necessary. This allows to simplify the needs of polyfills for many of the expected Python behaviors.
The interface with the js world is completely flat, import the modules or use the expected globals (window, document, etc…) as you would do in JavaScript.
The ES6 code is then converted (if requested) to ES5 code with the aid of the popular BabelJS library together with the fantastic dukpy embedded js interpreter.
Another goal is to just convert single modules or entire dir tree structures without emitting concatenated or minified files. This is left to the Javascript tooling of your choice. I use webpack which has BabelJS integration to getting this job done. Check out the bundled example.
JavaScripthon also generates SourceMap files with the higher detail possible in order to aid development. This means that while you are debugging some piece of translated JavaScript with the browser’s tools, you can actually choose to follow the flow of the code on the original Pyhton 3 source.
This project is far from complete, but it has achieved a good deal of features, please have a look at tests/test_evaljs.py file for the currently supported ones.
Installation
Python 3.5 is required because Python’s ast has changed between 3.4 and 3.5 and as of now supporting multiple Python versions is not one of my priorities.
To install the package execute the following command:
$ pip install javascripthon
Usage
To compile or transpile a python source module, use the commandline:
$ python -m metapensiero.pj source.py
or:
$ python -m metapensiero.pj -5 source.py
to transpile.
A pj console script is also automatically installed:
$ pj --help
usage: pj [-h] [--disable-es6] [--disable-stage3] [-5] [-o OUTPUT] [-d]
[--pdb]
file [file ...]
A Python 3.5+ to ES6 JavaScript compiler
positional arguments:
file Python source file(s) or directory(ies) to convert.
When it is a directory it will be converted
recursively
optional arguments:
-h, --help show this help message and exit
--disable-es6 Disable ES6 features during conversion (Ignored if
--es5 is specified)
--disable-stage3 Disable ES7 stage3 features during conversion
-5, --es5 Also transpile to ES5 using BabelJS.
-o OUTPUT, --output OUTPUT
Output file/directory where to save the generated code
-d, --debug Enable error reporting
--pdb Enter post-mortem debug when an error occurs
Conversions Rosetta Stone
Here are brief list of examples of the conversions the tool applies, just some, but not all.
Simple stuff
Python |
JavaScript |
---|---|
|
|
Then there are special cases. Here you can see some of these conversions. JavaScripthon cannot do a full trace of the sources, so some shortcuts are taken about the conversion of some core, specific Python’s semantics. For example Python’s self is always converted to JavaScript’s this, no matter where it’s found. Or len(foo) is always translated to foo.length. Albeit this an api specific of just some objects (Strings, Arrays, etc…), it considered wide adopted and something the user may consider obvious.
The rules of thumb to treat things especially are:
Is it possible to think of a conversion that covers most of the use cases?
It’s possible to find a convention widely used on the Python world to express this special case?
Python |
JavaScript |
---|---|
|
|
for statement
The for statement by default is translated as if the object of the cycle is a list but has two special cases:
Python |
JavaScript |
---|---|
|
|
Classes
Classes with single inheritance are translated to ES6 classes, they can have only function members for now, with no generic class or method decorators, because the ES7 spec for them is being rediscussed.
Methods can be functions or async-functions.
Python`s super() calls are converted accordingly to the type of their surrounding method: super().__init__(foo) becomes super(foo) in constructors.
Functions inside methods are translated to arrow functions so that they keep the this of the surrounding method.
@property and @a_property.setter are translated to ES6 properties.
Methods decorated with @classmethod are translated to static methods.
Special methods __str__ and __len__ are translated to toString() method and get length() property, respectively.
Arrow method expression to retain the this at method level aren’t implemented yet.
Python |
JavaScript |
---|---|
|
|
Only direct descendants of Exception are threated especially, but just for them to be meaningful in js-land and to be detectable with instanceof in catch statements.
Python |
JavaScript |
---|---|
|
|
try...except...finally statement
The conversion of this statement is mostly obvious with the only exception of the except part: it translates to a catch part containing one if statement for each non catchall except. If a catchall except isn’t present, the error will be re-thrown, to mimic Python’s behavior.
Python |
JavaScript |
---|---|
|
|
import statements
import and from ... import statements are converted to ES6 imports, and the declaration of an __all__ member on the module top level is translated to ES6 exports.
Python |
JavaScript |
---|---|
|
|
function’s args and call parameters
Parmeters defaults and keyword parameters are supported and so is *foo accumulator, which is translated into the ES6 rest expression (...foo).
The only caveat is that really JS support for keyword args sucks, so you will have to remember to fill in all the arguments before specifying keywords.
On function definitions, **kwargs is supported if it’s alone, i.e. without either keyword arguments or *args.
Python |
JavaScript |
---|---|
|
|
Examples
Execute make inside the examples directory.
Testing
To run the tests you should run the following at the package root:
python setup.py test
How to contribute
So you like this project and want to contribute? Good!
These are the terse guidelines:
There are some TODO points in the readme, or even the issue #6 is quite simple to fix. Feel free to pick what you like. The guidelines are to follow PEP8 for coding where possible, so use CamelCase for classes and snake_case for variables, functions and members, and UPPERCASE for constants. An exception to this rules are the function names inside ``metapensiero.pj.transformations`` subpackage. Those are matched against names of the ast objects coming from the ``ast`` module in standard lib, so they have to to match even in case. Try to keep lines lengths under 79 chars, more or less ;-) The workflow is to fork the project, do your stuff, maybe add a test for it and then submit a pull request. Have fun
Build status
Contributing
Any contribution is welcome, drop me a line or file a pull request.
Todo
This is a brief list of what needs to be done:
refactor the comprehensions conversion to use the snippets facility;
refactor snippets rendering to write them as a module and import them in the module when tree conversion is enabled;
convert dict() calls to ES6 Map object creation. Also, update “foo in bar” to use bar.has(foo) for maps;
convert set literals to ES6 Set objects. Also, update “foo in bar” to use bar.has(foo) for sets;
multi-line strings to ES6 template strings (does this make any sense?);
class and method decorators to ES7 class and method decorators;
implement yield and generator functions;
take advantage of new duckpy features to use a JS execution context that lasts multiple calls. This way the BabelJS bootstrap affects only the initial execution;
Done
Stuff that was previously in the todo:
translate import statements to ES6;
translate __all__ definition to ES6 module exports;
write a command line interface to expose the api;
make try…except work again and implement try…finally;
convert async and await to the same proposed features for js (see BabelJS documentation);
convert argument defaults on functions to ES6;
convert call keyword arguments;
convert *iterable syntax to ES6 destructuring;
use arrow functions for functions created in functions;
properties to ES6 properties (getter and setter);
External documentation
A good documentation and explanation of ES6 features can be found on the book Exploring ES6 by Axel Rauschmayer (donate if you can).
An extensive documentation about Python’s ast objects, very handy.
Tools
Have a look at ECMAScript 6 Tools by Addy Osmani.
To debug source maps have a look at source-map-visualization and its package on npm.
Still i found these links to be helpful:
Here is an example of the latter tool showing code generated by JavaScripthon, have fun!
Notes
A benchmark of ES6 features and discussion about it on hacker’s news.
A compatibility table of ES6 features showing completeness of support feature by feature.
A story about ES6 crazyest stuff… symbols
Changes
0.1 (2016-03-21)
First cut of the features
0.2 (2016-03-29)
use arrow functions to retain this were possible
translate async/await
refactoring of the for loops
add ability to subtranslate pieces of Python code or objects. Used to template the creation of Exception sublasses
add support for param defaults and keyword arguments
updated documentation
0.3 (2016-04-08)
updates to the documentation ( with some fixes made by Hugo Herter, Daniel Kopitchinski and ironmaniiith)
Translate str(x) into x.toString()
Add support for properties and classmethods
Translate __len__ and __str__ methods to get length() and toString()
Add support for slices syntax to .slice()
Fixed two bugs in sourcemaps generation
Fixed a bug in the inport ... from translation
Correctly include BabelJS minimized code
Fix transpiling of stage3 features
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.