From 818c73843f639fe50feab1ca92d14b5d496df025 Mon Sep 17 00:00:00 2001 From: Yuri D'Elia Date: Thu, 7 Aug 2014 00:11:49 +0200 Subject: [PATCH] python-bond 0.4 release notes/docs --- NEWS.rst | 17 +++++++++++++++-- README.rst | 51 +++++++++++++++++++++++++++++---------------------- setup.py | 2 +- 3 files changed, 45 insertions(+), 25 deletions(-) diff --git a/NEWS.rst b/NEWS.rst index 96c87f5..16a35cd 100644 --- a/NEWS.rst +++ b/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. diff --git a/README.rst b/README.rst index 3797b14..74c1644 100644 --- a/README.rst +++ b/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 `_. -* 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: `_ 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 - `_ 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 + `_. Limitations: @@ -291,6 +293,9 @@ Serialization: `_ 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 `_. 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 + `_ + 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 `_ 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 diff --git a/setup.py b/setup.py index 4414d7d..74f9d75 100755 --- a/setup.py +++ b/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",