What
====
``py.js`` is a parser and evaluator of Python expressions, written in
pure javascript.
``py.js`` is not intended to implement a full Python interpreter
(although it could be used for such an effort later on), its
specification document is the `Python 2.7 Expressions spec
<http://docs.python.org/reference/expressions.html>`_ (along with the
lexical analysis part).
Syntax
------
* 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
Builtins
--------
``py.js`` currently implements the following builtins:
``type``
Restricted to creating new types, can't be used to get an object's
type (yet)
``None``
``True``
``False``
``NotImplemented``
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.
``issubclass``
``object``
``bool``
Does not inherit from ``int``, since ``int`` is not currently
implemented.
``float``
``str``
``tuple``
Constructor/coercer is not implemented, only handles literals
``list``
Same as tuple (``list`` is currently an alias for ``tuple``)
``dict``
Implements just about nothing
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
<http://docs.python.org/reference/datamodel.html>`_:
Rich comparisons
Roughly complete implementation but for two limits: ``__eq__`` and
``__ne__`` can't return ``NotImplemented`` (well they can but it's
not going to work right), and the behavior is undefined if a
rich-comparison operation does not return a ``py.bool``.
Also, a ``NotImplemented`` result does not try the reverse
operation, not sure if it's supposed to. It directly falls back to
comparing type names.
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
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)
Utilities
---------
``py.js`` also provides (and exposes) a few utilities for "userland"
implementation:
``def``
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`` automatically, to behave as
Python's (bound) methods.
Why
===
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.
How
===
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});
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`_.
API
===
.. _py.eval:
``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.
``expr``
Python expression to evaluate
``context``
context dictionary holding the substitutions for the free
variables in the expression
.. _py.tokenize:
``py.tokenize(expr)``
``expr``
Python expression to tokenize
.. _py.parse:
``py.parse(tokens)``
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.
``tokens``
stream of tokens returned by `py.tokenize`_
.. _py.evaluate:
``py.evaluate(ast[, context])``
``ast``
The output of `py.parse`_
``context``
The evaluation context for the Python expression.
2a8d78c88c