Source

py.js / doc / index.rst

Diff from to

doc/index.rst

 Conversions from Javascript to Python
 +++++++++++++++++++++++++++++++++++++
 
+``py.js`` will automatically attempt to convert non-:class:`py.object`
+values into their ``py.js`` equivalent in the following situations:
+
+* Values passed through the context of :func:`py.eval` or
+  :func:`py.evaluate`
+
+* Attributes accessed directly on objects
+
+* Values of mappings passed to :class:`py.dict`
+
+Notably, ``py.js`` will *not* attempt an automatic conversion of
+values returned by functions or methods, these must be
+:class:`py.object` instances.
+
+The automatic conversions performed by ``py.js`` are the following:
+
+* ``null`` is converted to :data:`py.None`
+
+* ``true`` is converted to :data:`py.True`
+
+* ``false`` is converted to :data:`py.False`
+
+* numbers are converted to :class:`py.float`
+
+* strings are converted to :class:`py.str`
+
+* functions are wrapped into :class:`py.PY_dev`
+
+* ``Array`` instances are converted to :class:`py.list`
+
+The rest generates an error, except for ``undefined`` which
+specifically generates a ``NameError``.
+
 .. _convert-js:
 
 Conversions from Python to Javascript
 +++++++++++++++++++++++++++++++++++++
 
+py.js types (extensions of :js:class:`py.object`) can be converted
+back to javascript by calling their :js:func:`py.object.toJSON`
+method.
+
+The default implementation raises an error, as arbitrary objects can
+not be converted back to javascript.
+
+Most built-in objects provide a :js:func:`py.object.toJSON`
+implementation out of the box.
+
 Calling convention
 ++++++++++++++++++
 
   ``kwargs``, holding respectively the positional and keyword
   arguments passed to the callable from the expression.
 
-  These can be parsed into a JS object via :js:func:`py.PY_parseArgs`.
+  These can be parsed into a JS object via :func:`py.PY_parseArgs`.
 
 Javascript-level exceptions
 +++++++++++++++++++++++++++