python-bond 0.4 release notes/docs

NEWS.rst

@@ -1,3 +1,16 @@
+python-bond 0.4
+---------------
+
+* Serialization exceptions generating from exported functions now correctly
+  unwind the remote stack.
+* An exception with exported functions returning no values was fixed.
+* The size of the serialization buffers was previously limited to 4k; it's now
+  bound to the available memory.
+* ``bond.interact()`` now can accept multi-line blocks by using a trailing
+  backslash at the end of the line.
+* Performance was optimized.
+
+
 python-bond 0.3
 ---------------
 
@@ -16,6 +29,6 @@ python-bond 0.2
 * Serialization errors are now intercepted by default and generate a local
   exception of type ``bond.SerializationException``.
 * PHP can now "call" any callable statement.
-* eval_block() no longer returns the value of the last statement. This avoids
-  confusion with Perl code blocks returning unserializable references.
+* ``eval_block()`` no longer returns the value of the last statement. This
+  avoids confusion with Perl code blocks returning unserializable references.
 * Standard error is now also redirected.

README.rst

@@ -82,10 +82,10 @@ function:
   php.export(new_function, 'function_to_be_replaced')
   php.call('main', sys.argv)
 
-It turns out that the same approach can be useful to perform remote/parallel
+It turns out that with the same approach you can easily perform remote/parallel
 computation as well. Nobody stops you from having multiple interpreters at the
-same time: you can use ``bond`` to setup a poor man's distributed system
-with minimal effort:
+same time: you can use ``bond`` to setup a poor-man's distributed system with
+minimal effort:
 
 .. code:: python3
 
@@ -94,13 +94,14 @@ with minimal effort:
   hosts = ['host1', 'host2', 'host3']
   nodes = [Python('ssh {} python'.format(host)) for host in hosts]
 
-  # load our libraries
+  # load our libraries first
   for node in nodes:
       node.eval_block('from library import *')
 
-  # execute do_something remotely on each worker
+  # execute "do_something" remotely on each worker
   from threading import Thread
   threads = [Thread(target=lambda: node.call('do_something')) for node in nodes]
+  for thread in threads: thread.start()
 
   # collect the results
   results = [thread.join() for thread in threads]
@@ -221,7 +222,7 @@ The ``bond`` class supports the following methods:
   Start an interactive session with the underlying interpreter. By default, all
   input lines are executed with bond.eval_block(). If "!" is pre-pended,
   execute a single statement with bond.eval() and print it's return value. You
-  can continue the statement on multiple lines by leaving a trailing "\". Type
+  can continue the statement on multiple lines by leaving a trailing "\\". Type
   Ctrl+C to abort a multi-line block without executing it.
 
 
@@ -240,7 +241,8 @@ Serialization:
 * Performed locally and remotely using `cPickle
   <https://docs.python.org/2/library/pickle.html#module-cPickle>`_.
 
-* Remote serialization exceptions are of type ``cPickle.PickingError``.
+* Serialization exceptions on the remote side are of base type
+  ``cPickle.PicklingError`` <= ``__PY_BOND_SerializationException``.
 
 
 PHP
@@ -258,10 +260,10 @@ Serialization:
   <http://php.net/manual/en/jsonserializable.jsonserialize.php>`_ interface to
   tweak which/how objects are encoded.
 
-* PHP doesn't normally throw exceptions for JSON encoding errors. ``bond``
-  generates an ``Exception`` which you can catch remotely. The detailed results
-  of the error can also be retrieved using the `json_last_error
-  <http://php.net/manual/en/function.json-last-error.php>`_ function.
+* Serialization exceptions on the remote side are of base type
+  ``__PY_BOND_SerializationException``. The detailed results of the error can
+  also be retrieved using `json_last_error
+  <http://php.net/manual/en/function.json-last-error.php>`_.
 
 Limitations:
 
@@ -291,6 +293,9 @@ Serialization:
   <http://search.cpan.org/dist/JSON/lib/JSON.pm#allow_blessed>`_ method on
   blessed references to tweak which/how objects are encoded.
 
+* Serialization exceptions on the remote side are generated by dying with a
+  ``__PY_BOND_SerializationException`` @ISA.
+
 Gotchas:
 
 * By default, evaluation is forced in array context, as otherwise most of the
@@ -327,14 +332,16 @@ JavaScript is supported through `Node.js <http://nodejs.org/>`_.
 Requirements:
 
 * Only Node.js v0.10.29 has been tested. On Debian/Ubuntu, the required package
-  is simply called ``nodejs``.
+  is ``nodejs``.
 
 Serialization:
 
-* Performed remotely using ``JSON``. Implement the "toJSON" property to tweak
-  which/how objects are encoded.
+* Performed remotely using ``JSON``. Implement the `toJSON
+  <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify>`_
+  property to tweak which/how objects are encoded.
 
-* Remote JSON serialization exceptions are of type ``TypeError``.
+* Serialization exceptions on the remote side are of base type
+  ``TypeError`` <= ``__PY_BOND_SerializationException``.
 
 Limitations:
 
@@ -343,23 +350,23 @@ Limitations:
 
 * Since there's no distinction between "plain" objects (dictionaries) and any
   other object, almost everything will be silently serialized. Define a custom
-  "toJSON" property on your objects to control this behavior.
+  "toJSON" property on your "real" objects to control this behavior.
 
 
 Common traits/limitations
 -------------------------
 
-* Except for Python, only basic types (booleans, numbers, strings, lists,
-  arrays and maps/dictionaries) can be transferred between the interpreters.
-
-  If an object that cannot be serialized reaches a "call", "eval", or even a
-  non-local return such as an *error or exception*, it will generate a
-  ``SerializationException`` on the Python side.
+* Except for Python, only basic types (booleans, numbers, strings, lists/arrays
+  and maps/dictionaries) can be transferred between the interpreters.
 
 * Serialization is performed locally using ``JSON``. Implement a custom
   `JSONEncoder <https://docs.python.org/2/library/json.html#json.JSONEncoder>`_
   to tweak which/how objects are encoded.
 
+* If an object that cannot be serialized reaches a "call", "eval", or even a
+  non-local return such as an *error or exception*, it will generate a
+  ``SerializationException`` on the local (Python) side.
+
 * Strings are *always* UTF-8 encoded.
 
 * References are implicitly broken as *objects are transferred by value*. This

setup.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 from setuptools import setup, find_packages
-setup(name='python-bond', version='0.3',
+setup(name='python-bond', version='0.4',
       description='transparent remote/recursive evaluation between Python and other languages',
 
       author="Yuri D'Elia",