py.js / README.rst



  • Lambdas and ternaries should be parsed but are not implemented (in the evaluator)
  • Only floats are implemented, int literals are parsed as floats.
  • Octal and hexadecimal literals are not implemented
  • Srings are backed by JavaScript strings and probably behave like unicode more than like str
  • Slices don't work


py.js currently implements the following builtins:

Restricted to creating new types, can't be used to get an object's type (yet)




Returned from rich comparison methods when the comparison is not implemented for this combination of operands. In py.js, this is also the default implementation for all rich comparison methods.



Does not inherit from int, since int is not currently implemented.



Constructor/coercer is not implemented, only handles literals
Same as tuple (list is currently an alias for tuple)
Implements trivial getting and setting, nothing beyond that.

Note that most methods are probably missing from all of these.

Data model protocols

py.js currently implements the following protocols (or sub-protocols) of the `Python 2.7 data model <>`_:

Rich comparisons

Pretty much complete (including operator fallbacks), although the behavior is currently undefined if an operation does not return either a py.bool or NotImplemented.

__hash__ is supported (and used), but it should return a javascript string. py.js's dict build on javascript objects, reimplementing numeral hashing is worthless complexity at this point.

Boolean conversion
Implementing __nonzero__ should work.
Customizing attribute access
Protocols for getting and setting attributes (including new-style extension) fully implemented but for __delattr__ (since del is a statement)
Descriptor protocol
As with attributes, __delete__ is not implemented.
Callable objects

Work, although the handling of arguments isn't exactly nailed down. For now, callables get two (javascript) arguments args and kwargs, holding (respectively) positional and keyword arguments.

Conflicts are not handled at this point.

Collections Abstract Base Classes
Container is the only implemented ABC protocol (ABCs themselves are not currently implemented) (well technically Callable and Hashable are kind-of implemented as well)
Numeric type emulation
Operators are implemented (but not tested), abs, divmod and pow builtins are not implemented yet. Neither are oct and hex but I'm not sure we care (I'm not sure we care about pow or even divmod either, for that matter)


py.js also provides (and exposes) a few utilities for "userland" implementation:


Wraps a native javascript function into a py.js function, so that it can be called from native expressions.

Does not ensure the return types are type-compatible with py.js types.

When accessing instance methods, py.js automatically wraps these in a variant of py.def, to behave as Python's (bound) methods.


Originally, to learn about Pratt parsers (which are very, very good at parsing expressions with lots of infix or mixfix symbols). The evaluator part came because "why not" and because I work on a product with the "feature" of transmitting Python expressions (over the wire) which the client is supposed to evaluate.


At this point, only three steps exist in py.js: tokenizing, parsing and evaluation. It is possible that a compilation step be added later (for performance reasons).

To evaluate a Python expression, the caller merely needs to call py.eval. py.eval takes a mandatory Python expression to evaluate (as a string) and an optional context, for the substitution of the free variables in the expression:

> py.eval("type in ('a', 'b', 'c') and foo", {type: 'c', foo: true});

This is great for one-shot evaluation of expressions. If the expression will need to be repeatedly evaluated with the same parameters, the various parsing and evaluation steps can be performed separately: py.eval is really a shortcut for sequentially calling py.tokenize, py.parse and py.evaluate.


py.eval(expr[, context])

"Do everything" function, to use for one-shot evaluation of a Python expression: it will internally handle the tokenizing, parsing and actual evaluation of the Python expression without having to perform these separately.

Python expression to evaluate
context dictionary holding the substitutions for the free variables in the expression
Python expression to tokenize

Parses a token stream and returns an abstract syntax tree of the expression (if the token stream represents a valid Python expression).

A parse tree is stateless and can be memoized and used multiple times in separate evaluations.

stream of tokens returned by py.tokenize
py.evaluate(ast[, context])
The output of py.parse
The evaluation context for the Python expression.