[Python-modules-commits] [bond] 01/06: Import upstream version 1.4
Yuri D'Elia
wavexx-guest at moszumanska.debian.org
Tue Jan 12 11:48:05 UTC 2016
This is an automated email from the git hooks/post-receive script.
wavexx-guest pushed a commit to branch master
in repository bond.
commit 68ad6d79242dc2166ef721f11de765353ada9078
Author: Yuri D'Elia <wavexx at thregr.org>
Date: Sat Jan 9 17:44:19 2016 +0100
Import upstream version 1.4
---
COPYING.txt | 339 +++++++++++++++
MANIFEST.in | 2 +
NEWS.rst | 100 +++++
PKG-INFO | 609 +++++++++++++++++++++++++++
README.rst | 577 ++++++++++++++++++++++++++
bond/JavaScript/__init__.py | 26 ++
bond/PHP/__init__.py | 26 ++
bond/Perl/__init__.py | 26 ++
bond/Python/__init__.py | 26 ++
bond/__init__.py | 412 +++++++++++++++++++
bond/drivers/COPYING.txt | 339 +++++++++++++++
bond/drivers/JavaScript/bond.json | 18 +
bond/drivers/JavaScript/stage1.js | 31 ++
bond/drivers/JavaScript/stage2.js | 204 +++++++++
bond/drivers/PHP/bond.json | 16 +
bond/drivers/PHP/stage1.php | 14 +
bond/drivers/PHP/stage2.php | 357 ++++++++++++++++
bond/drivers/Perl/bond.json | 15 +
bond/drivers/Perl/stage1.pl | 23 ++
bond/drivers/Perl/stage2.pl | 223 ++++++++++
bond/drivers/Python/bond.json | 15 +
bond/drivers/Python/stage1.py | 14 +
bond/drivers/Python/stage2.py | 202 +++++++++
bond/drivers/README.rst | 106 +++++
bond/protocols.py | 29 ++
python_bond.egg-info/PKG-INFO | 609 +++++++++++++++++++++++++++
python_bond.egg-info/SOURCES.txt | 38 ++
python_bond.egg-info/dependency_links.txt | 1 +
python_bond.egg-info/requires.txt | 2 +
python_bond.egg-info/top_level.txt | 1 +
setup.cfg | 5 +
setup.py | 43 ++
tests/__init__.py | 60 +++
tests/test_JavaScript.py | 605 +++++++++++++++++++++++++++
tests/test_PHP.py | 659 ++++++++++++++++++++++++++++++
tests/test_PHP_Perl.py | 28 ++
tests/test_Perl.py | 605 +++++++++++++++++++++++++++
tests/test_Python.py | 607 +++++++++++++++++++++++++++
tests/test_api_v0.py | 29 ++
tests/test_bond.py | 70 ++++
40 files changed, 7111 insertions(+)
diff --git a/COPYING.txt b/COPYING.txt
new file mode 100644
index 0000000..d511905
--- /dev/null
+++ b/COPYING.txt
@@ -0,0 +1,339 @@
+ GNU GENERAL PUBLIC LICENSE
+ Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ Preamble
+
+ The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users. This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it. (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.) You can apply it to
+your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+ To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their
+rights.
+
+ We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+ Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+ Finally, any free program is threatened constantly by software
+patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary. To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+ GNU GENERAL PUBLIC LICENSE
+ TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+ 0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License. The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language. (Hereinafter, translation is included without limitation in
+the term "modification".) Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+ 1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+ 2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+ a) You must cause the modified files to carry prominent notices
+ stating that you changed the files and the date of any change.
+
+ b) You must cause any work that you distribute or publish, that in
+ whole or in part contains or is derived from the Program or any
+ part thereof, to be licensed as a whole at no charge to all third
+ parties under the terms of this License.
+
+ c) If the modified program normally reads commands interactively
+ when run, you must cause it, when started running for such
+ interactive use in the most ordinary way, to print or display an
+ announcement including an appropriate copyright notice and a
+ notice that there is no warranty (or else, saying that you provide
+ a warranty) and that users may redistribute the program under
+ these conditions, and telling the user how to view a copy of this
+ License. (Exception: if the Program itself is interactive but
+ does not normally print such an announcement, your work based on
+ the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+ 3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+ a) Accompany it with the complete corresponding machine-readable
+ source code, which must be distributed under the terms of Sections
+ 1 and 2 above on a medium customarily used for software interchange; or,
+
+ b) Accompany it with a written offer, valid for at least three
+ years, to give any third party, for a charge no more than your
+ cost of physically performing source distribution, a complete
+ machine-readable copy of the corresponding source code, to be
+ distributed under the terms of Sections 1 and 2 above on a medium
+ customarily used for software interchange; or,
+
+ c) Accompany it with the information you received as to the offer
+ to distribute corresponding source code. (This alternative is
+ allowed only for noncommercial distribution and only if you
+ received the program in object code or executable form with such
+ an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it. For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable. However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+ 4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+ 5. You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Program or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+ 6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+ 7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all. For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+ 8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded. In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+ 9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation. If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+ 10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission. For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this. Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+ NO WARRANTY
+
+ 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+ 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+ END OF TERMS AND CONDITIONS
+
+ How to Apply These Terms to Your New Programs
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+ <one line to give the program's name and a brief idea of what it does.>
+ Copyright (C) <year> <name of author>
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along
+ with this program; if not, write to the Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+ Gnomovision version 69, Copyright (C) year name of author
+ Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License. Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary. Here is a sample; alter the names:
+
+ Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+ `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+ <signature of Ty Coon>, 1 April 1989
+ Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs. If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library. If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.
diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100644
index 0000000..9b07a16
--- /dev/null
+++ b/MANIFEST.in
@@ -0,0 +1,2 @@
+graft bond/drivers
+global-exclude .git* .travis.*
diff --git a/NEWS.rst b/NEWS.rst
new file mode 100644
index 0000000..9dc94bc
--- /dev/null
+++ b/NEWS.rst
@@ -0,0 +1,100 @@
+python-bond 1.4
+---------------
+
+* Performance/documentation tweaks.
+
+
+python-bond 1.3
+---------------
+
+* Added support for "Quoted expressions". ``call()`` can now be used on remote
+ functions expecting one or more remote unserializable objects as their
+ arguments, without the need of a support function and/or ``eval()``.
+
+
+python-bond 1.2
+---------------
+
+* PHP's error level can now be controlled through the ``_BOND_error_level()``
+ function (see the PHP "Limitations" section).
+* An initialization race with PHP <= 5.3 (causing intermittent initialization
+ issues) has been fixed.
+* The license has been changed from GPLv2 to GNU GPLv2+.
+* A new mailing list for announcements and development discussions has been
+ created (see the README).
+
+
+python-bond 1.1
+---------------
+
+* PHP output redirection was broken in 1.0; it's now fixed.
+* PHP now also redirects error messages to stderr, honouring correctly
+ ``error_reporting()`` and ``display_errors``.
+
+
+python-bond 1.0
+---------------
+
+* The API has been streamlined: ``make_bond()`` is now the primary method of
+ constructing ``Bond`` objects, independently of the interpreter language.
+ The old language constructors are still supported, but are deprecated and
+ will be removed in a future release.
+* All functions/objects/methods are now documented with docstrings.
+* Bond initialization errors, especially errors related to missing
+ dependencies, are now much easier to understand.
+* Serialization exceptions on the remote side have been renamed to
+ ``_BOND_SerializationException`` for consistency with other languages.
+* JavaScript/Node.js support was previously limited to versions >= 0.10. Any
+ version of Node.js starting with 0.6.12 is now supported.
+* PHP support was previously limited to versions >= 5.6. Any version of PHP
+ starting with 5.3 is now supported.
+* A Perl dependency on ``IO::String`` was previously missing, and has now been
+ correctly documented.
+
+
+python-bond 0.5
+---------------
+
+* Python 3 support has been added, with the ability to mix major Python
+ versions between the host and the bond.
+* All languages/interpreters can now be executed with a remote shell without
+ using additional arguments.
+* On the remote side, ``__PY_BOND_SerializationException`` has been renamed to
+ ``_PY_BOND_SerializationException`` as it can be trapped by the user code.
+* The scope of a PHP code block in an exported, recursive call has been fixed.
+
+
+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
+---------------
+
+* Local exceptions are now forwarded remotely for exported functions.
+* Excluding Python, exceptions are no longer serialized, but are instead
+ propagated using their originating error message. See the ``trans_except``
+ keyword argument in constructors that allows to tune this behavior.
+* The spawned interpreter now uses a copy of the current environment.
+* PHP now triggers an exception when attempting to redefine a function.
+* JavaScript is now supported through Node.js.
+
+
+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.
+* Standard error is now also redirected.
diff --git a/PKG-INFO b/PKG-INFO
new file mode 100644
index 0000000..4ebedbb
--- /dev/null
+++ b/PKG-INFO
@@ -0,0 +1,609 @@
+Metadata-Version: 1.1
+Name: python-bond
+Version: 1.4
+Summary: transparent remote/recursive evaluation between Python and other languages
+Home-page: http://www.thregr.org/~wavexx/software/python-bond/
+Author: Yuri D'Elia
+Author-email: wavexx at thregr.org
+License: GPL2
+Description: ===============
+ python ``bond``
+ ===============
+ ---------------------------------------------------
+ Ambivalent bonds between Python and other languages
+ ---------------------------------------------------
+
+ .. contents::
+
+ The Python module ``bond`` supports transparent remote/recursive evaluation
+ between Python and another interpreter through automatic call serialization.
+
+ In poorer words, a ``bond`` lets you call functions in other languages as they
+ were normal Python functions. It *also* allows other languages to *call Python
+ functions* as if they were native.
+
+ Remote output is also transparently redirected locally, and since the
+ evaluation is performed through a persistent co-process, you can actually spawn
+ interpreters on different hosts through "ssh" efficiently.
+
+ ``bond`` currently supports PHP, Perl, JavaScript (Node.js) and Python itself.
+
+
+ Overview
+ ========
+
+ .. code:: python3
+
+ >>> # Let's bond with a PHP interpreter
+ >>> from bond import make_bond
+ >>> php = make_bond('PHP')
+ >>> php.eval_block('echo "Hello world!\n";')
+ Hello world!
+
+ >>> # Make an expensive split function using PHP's explode
+ >>> split = php.callable('explode')
+ >>> split(' ', "Hello world splitted by PHP!")
+ [u'Hello', u'world', u'splitted', u'by', u'PHP!']
+
+ >>> # Call Python from PHP
+ >>> def call_me():
+ ... print("Hi, this is Python talking!")
+ >>> php.export(call_me)
+ >>> php.eval('call_me()')
+ Hi, this is Python talking!
+
+ >>> # Use some remote resources
+ >>> remote_php = make_bond('PHP', 'ssh remote php')
+ >>> remote_php.eval_block('function call_me() { echo "Hi from " . system("hostname") . "!"; }')
+ >>> remote_php.eval('call_me()')
+ Hi from remote!
+
+ >>> # Bridge two worlds!
+ >>> perl = make_bond('Perl')
+ >>> php.proxy('explode', perl)
+ >>> # note: explode is now available to Perl, but still executes in PHP
+ >>> perl.eval('explode("=", "Mind=blown!")')
+ [u'Mind', u'blown!']
+
+
+ A concrete example
+ ==================
+
+ I needed ``bond`` for migrating a large PHP project to Python. With ``bond``
+ you can rewrite a program incrementally, while still executing all the existing
+ code unchanged. You can start by rewriting just a single function in an empty
+ shell that wraps your existing code, as follows:
+
+ .. code:: python3
+
+ from bond import make_bond
+ import sys
+
+ php = make_bond('PHP')
+ php.eval_block('include("my_original_program.php");')
+
+ def new_function(arg)
+ # do something here
+ pass
+
+ php.export(new_function, 'function_to_be_replaced')
+ php.call('main', sys.argv)
+
+ You can also use ``bond`` to mix Python 2/3 code. Python <=> Python bonds
+ automatically use pickling as a protocol, which makes serialization almost
+ invisible.
+
+ Thanks to that, you can easily use ``bond`` to perform remote/parallel
+ computation. Nobody stops you from having multiple interpreters at the same
+ time: you can create bonds to setup a poor-man's distributed system with
+ minimal effort:
+
+ .. code:: python3
+
+ # setup the workers
+ from bond import make_bond
+ hosts = ['host1', 'host2', 'host3']
+ nodes = [make_bond('Python', 'ssh {} python'.format(host)) for host in hosts]
+
+ # load our libraries first
+ for node in nodes:
+ node.eval_block('from library import *')
+
+ # 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]
+
+ Distributed producer/consumer schemes also come for free by proxying calls:
+
+ .. code:: python3
+
+ host1.eval_block(r'''def consumer(data):
+ # do something with data
+ pass
+ ''')
+
+ host2.eval_block(r'''def producer():
+ while True:
+ data = function()
+ consumer(data)
+ ''')
+
+ host1.proxy('consumer', host2)
+ host2.call('producer')
+
+ It's even more interesting if you realize that the producers/consumers don't
+ even have to be written in the same language, and don't know that the call is
+ actually being forwarded.
+
+ ``bond`` doesn't even need to be installed remotely: the required setup is
+ injected directly into a live interpreter. The wire protocol is simple enough
+ that any language supporting an interactive REPL can be called. In fact, `the
+ drivers themselves <https://github.com/wavexx/bond-drivers>`_ are designed to
+ be used from any other language.
+
+
+ API
+ ===
+
+ Initialization
+ --------------
+
+ A ``bond.Bond`` object is not normally constructed directly, but by using the
+ ``bond.make_bond()`` function:
+
+ .. code:: python3
+
+ import bond
+ interpreter = bond.make_bond('language')
+
+ The first argument should be the desired language name ("JavaScript", "PHP",
+ "Perl", "Python"). The list of supported languages can be fetched dynamically
+ using ``bond.list_drivers()``.
+
+ You can override the default interpreter command using the second argument,
+ which allows to specify any shell command to be executed:
+
+ .. code:: python3
+
+ import bond
+ py = bond.make_bond('Python', 'ssh remote python3')
+
+ An additional *list* of arguments to the interpreter can be provided using the
+ third argument, ``args``:
+
+ .. code:: python3
+
+ import bond
+ py = bond.make_bond('Python', 'ssh remote python3', ['-E', '-OO'])
+
+ The *arguments*, contrarily to the command, are automatically quoted.
+
+ Some command line arguments may be supplied automatically by the driver to
+ force an interactive shell; for example "-i" is supplied if Python is
+ requested. You can disable default arguments by using ``def_args=False``.
+
+ The following keyword arguments are supported:
+
+ ``cwd``:
+
+ Working directory for the interpreter (defaults to current working
+ directory).
+
+ ``env``:
+
+ Environment for the interpreter (defaults to ``os.environ``).
+
+ ``def_args``:
+
+ Enable (default) or suppress default, extra command-line arguments to the
+ interpreter.
+
+ ``timeout``:
+
+ Defines the timeout for the underlying communication protocol. Note that
+ ``bond`` cannot distinguish between a slow call or noise generated while the
+ interpreter is set up. Defaults to 60 seconds.
+
+ ``logfile``:
+
+ Accepts a file handle which is used to log the entire communication with the
+ underlying interpreter for debugging purposes.
+
+ ``trans_except``:
+
+ Enables/disables "transparent exceptions". Exceptions are always first class,
+ but when ``trans_except`` is enabled, the exception objects themselves will
+ be forwarded across the bond. If ``trans_except`` is disabled (the default
+ for all languages except Python), then local exceptions will always contain a
+ string representation of the remote exception instead, which avoids
+ serialization errors.
+
+
+ ``bond.Bond`` Methods
+ ---------------------
+
+ The resulting ``bond.Bond`` class has the following methods:
+
+ ``eval(code)``:
+
+ Evaluate and return the value of a *single statement* of code in the
+ interpreter.
+
+ ``eval_block(code)``:
+
+ Execute a "code" block inside the top-level of the interpreter. Any construct
+ which is legal by the current interpreter is allowed. Nothing is returned.
+
+ ``ref(code)``:
+
+ Return a reference to an *single, unevaluated statement* of code, which can
+ be later used in eval(), eval_block() or as an *immediate* argument to call().
+ See `Quoted expressions`_.
+
+ ``close()``:
+
+ Terminate the communication with the interpreter.
+
+ ``call(name, *args)``:
+
+ Call a function "name" in the interpreter using the supplied list of
+ arguments \*args (apply \*args to a callable statement defined by "name").
+ The arguments are automatically converted to their other language's
+ counterpart. The return value is captured and converted back to Python as
+ well.
+
+ ``callable(name)``:
+
+ Return a function that calls "name":
+
+ .. code:: python
+
+ explode = php.callable('explode')
+ # Now you can call explode as a normal, local function
+ explode(' ', 'Hello world')
+
+ ``export(func, name)``:
+
+ Export a local function "func" so that can be called on the remote language
+ as "name". If "name" is not specified, use the local function name directly.
+ Note that "func" must be a function *reference*, not a function name.
+
+ ``proxy(name, other, remote)``:
+
+ Export a function "name" from the current ``bond`` to "other", named as
+ "remote". If "remote" is not provided, the same value as "name" is used.
+
+ ``interact()``:
+
+ 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
+ Ctrl+C to abort a multi-line block without executing it.
+
+
+ Exceptions
+ ----------
+
+ All exceptions thrown by the ``bond`` module are of base type ``RuntimeError``
+ <= ``BondException``.
+
+ ``BondException``:
+ Thrown during initialization or unrecoverable errors.
+
+ ``TerminatedException``:
+ Thrown when the bond exits unexpectedly.
+
+ ``SerializationException``:
+ Thrown when an object/exception which is sent *or* received cannot be
+ serialized by the current protocol. The ``side`` attribute can be either
+ "local" (when attempting to *send*) or "remote" (when *receiving*). A
+ ``SerializationException`` is not fatal.
+
+ ``RemoteException``:
+ Thrown for uncaught remote exceptions. The "data" attribute contains either
+ the error message (with ``trans_except=False``) or the remote exception
+ itself (``trans_except=True``).
+
+ Beware that both ``SerializationException`` (with ``side="remote"``) and
+ ``RemoteException`` may actually be originating from uncaught *local*
+ exceptions when an exported function is called. Pay attention to the error
+ text/data in these cases, as it will contain several nested exceptions.
+
+
+ Quoted expressions
+ ------------------
+
+ ``bond`` has minimal support for quoted expressions, through the use of
+ ``Bond.ref()``. ``ref()`` returns a reference to a unevaluated statement that
+ can be fed back to ``eval()``, ``eval_block()``, or as an *immediate* (i.e.:
+ not nested) argument to ``call()``. References are bound to the interpreter
+ that created them.
+
+ ``ref()`` allows to "call" methods that take remote un-serializable arguments,
+ such as file descriptors, without the use of a support function and/or eval:
+
+ .. code:: python3
+
+ pl = make_bond('Perl')
+ pl.eval_block('open($fd, ">file.txt");')
+ fd = pl.ref('$fd')
+ pl.call('syswrite', fd, "Hello world!")
+ pl.call('close', fd)
+
+ Since ``ref()`` objects cannot be nested, there are still cases where it might
+ be necessary to use a support function. To demonstrate, we rewrite the above
+ example without quoted expressions, while still allowing an argument ("Hello
+ world!") to be local:
+
+ .. code:: python3
+
+ pl = make_bond('Perl')
+ pl.eval_block('open($fd, ">file.txt");')
+ pl.eval_block('sub syswrite_fd { syswrite($fd, shift()); };')
+ pl.call('syswrite_fd', "Hello world!")
+ pl.eval('close($fd)')
+
+ Or more succinctly:
+
+ .. code:: python3
+
+ pl.call('sub { syswrite($fd, shift()); }', "Hello world!")
+
+
+ Language support
+ ================
+
+ Python
+ ------
+
+ Python, as the identity language, has no restriction on data types. Everything
+ is pickled on both sides, including exceptions.
+
+
+ Serialization:
+
+ * Performed locally and remotely using ``cPickle`` in Python 2 or `pickle
+ <https://docs.python.org/2/library/pickle.html>`_ in Python 3.
+
+ * Serialization exceptions on the remote side are of base type
+ ``TypeError`` <= ``_BOND_SerializationException``.
+
+
+ Python 2 / Python 3:
+
+ You can freely mix Python versions between hosts/interpreters (that is: you can
+ run Python 3 code from a Python 2 host and vice-versa). You'll need to disable
+ transparent exceptions though, as the exception hierarchy is different between
+ major versions:
+
+ .. code:: python3
+
+ # assuming a python2.7 environment
+ from bond import make_bond
+ py = make_bond('Python', 'python3', trans_except=False)
+
+
+ PHP
+ ---
+
+ Requirements:
+
+ * The PHP's >= 5.3 command line interpreter needs to be installed. On
+ Debian/Ubuntu, the required package is ``php5-cli``.
+
+ Serialization:
+
+ * Performed remotely using ``JSON``. Implement the `JsonSerializable
+ <http://php.net/manual/en/jsonserializable.jsonserialize.php>`_ interface to
+ tweak which/how objects are encoded.
+
+ * Serialization exceptions on the remote side are of base type
+ ``_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:
+
+ * PHP <= 5.3 doesn't support the ``JsonSerializable`` interface, and thus lacks
+ the ability of serializing arbitrary objects.
+
+ * You cannot use ``call`` on a built-in function such as "echo". You have to
+ use a real function instead, like "print". You can still call "echo" by using
+ ``eval`` or ``eval_block``.
+
+ * Unfortunately, you cannot catch "fatal errors" in PHP. If the evaluated code
+ triggers a fatal error it will terminate the bond without appeal. A common
+ example of such error can be attempting to use an undefined variable or
+ function (which could happen while prototyping).
+
+ * Due to the inability to override built-in functions, ``error_reporting()`` is
+ not completely transparent and always returns 0. It shouldn't be used to
+ control the display error level. Use ``_BOND_error_reporting()`` instead,
+ which has the same usage/signature as the built-in function.
+
+
+ Perl
+ ----
+
+ Perl is a quirky language, due to its syntax. We assume here you're an
+ experienced Perl developer.
+
+ Requirements:
+
+ * Perl >= 5.14 is required, with the following modules:
+
+ - ``JSON``
+ - ``Data::Dump``
+ - ``IO::String``
+
+ On Debian/Ubuntu, the required packages are ``libjson-perl``
+ ``libdata-dump-perl`` and ``libio-string-perl``.
+
+ Serialization:
+
+ * Performed remotely using ``JSON``. Implement the `TO_JSON
+ <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
+ ``_BOND_SerializationException`` @ISA.
+
+ Gotchas:
+
+ * By default, evaluation is forced in array context, as otherwise most of the
+ built-ins working with arrays would return an useless scalar. Use the
+ "scalar" keyword for the rare cases when you really need it to.
+
+ * You can "call" any function-like statement, as long as the last argument is
+ expected to be an argument list. This allows you to call builtins directly:
+
+ .. code:: python3
+
+ perl.call('map { $_ + 1 }', [1, 2, 3])
+
+ * You can of course "call" a statement that returns any ``CODE``. Meaning that
+ you can call references to functions as long as you dereference them first:
+
+ .. code:: python3
+
+ perl.call('&$fun_ref', ...)
+ perl.call('&{ $any->{expression} }', ...)
+
+ Likewise you can "call" objects methods directly:
+
+ .. code:: python3
+
+ perl.call('$object->method', ...)
+
+ * ``eval_block`` introduces a new block. Variables declared as "my" will not be
+ visible into a subsequent ``eval_block``. Use a fully qualified name or "our"
+ to define variables that should persist across blocks:
+
+ .. code:: python3
... 6400 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/bond.git
More information about the Python-modules-commits
mailing list