Initial commit

Author: Ryan Munro

.gitignore

@@ -0,0 +1 @@
+node_modules

.travis.yml

@@ -0,0 +1,32 @@
+language: python
+os:
+    - "linux"
+    # - "osx"
+env:
+    - NODE_VERSION="5.1"
+    - NODE_VERSION="5.0"
+    - NODE_VERSION="4.2"
+    - NODE_VERSION="4.1"
+    - NODE_VERSION="4.0"
+    # - NODE_VERSION="0.12"
+    # - NODE_VERSION="0.10"
+python:
+    - "3.5"
+    - "3.4"
+    - "3.3"
+    - "3.2"
+    - "2.7"
+    - "2.6"
+before_install:
+  - rm -rf ~/.nvm
+  - git clone https://github.com/creationix/nvm.git ~/.nvm
+  - source ~/.nvm/nvm.sh
+  - nvm install $NODE_VERSION
+install:
+    - pip install six
+    - npm install
+before_script:
+    - python -V
+    - node --version
+script:
+    npm test

README.md

@@ -0,0 +1,220 @@
+# python-bridge [![Build Status](https://secure.travis-ci.org/Submersible/node-python-bridge.png?branch=master)](http://travis-ci.org/Submersible/node-python-bridge)
+
+Most robust and simple Python bridge.  [Features](#features), and [comparisons](#comparisons) to other Python bridges below.
+
+```
+npm install python-bridge
+```
+
+```javascript
+'use strict';
+
+let assert = require('assert');
+let pythonBridge = require('python-bridge');
+
+let python = pythonBridge();
+
+python.ex`import math`;
+python`math.sqrt(9)`.then(x => assert.equal(x, 3));
+
+let list = [3, 4, 2, 1];
+python`sorted(${list})`.then(x => assert.deepEqual(x, list.sort()));
+
+python.end();
+```
+
+# API
+
+## var python = pythonBridge(options)
+
+Spawns a Python interpreter pipe to execute code, and receive data.
+
+* `options.python` - Python interpreter, defaults to `python`
+
+Also inherits the following from [`child_process.spawn([options])`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options).
+
+* `options.cwd` - String Current working directory of the child process
+* `options.env` - Object Environment key-value pairs
+* `options.stdio` - Array Child's stdio configuration. Defaults to `['pipe', process.stdout, process.stderr]`
+* `options.uid` - Number Sets the user identity of the process.
+* `options.gid` - Number Sets the group identity of the process.
+
+```javascript
+var python = pythonBridge({
+    python: 'python3',
+    env: {PYTHONPATH: '/foo/bar'}
+});
+```
+
+## python`` `expression(args...)` ``.then(...)
+
+Evaluates an expression.
+
+```javascript
+// Interpolates arguments using JSON serialization.
+python`sorted(${[6, 4, 1, 3]})`.then(x => assert.deepEqual(x, [1, 3, 4, 6]));
+
+// Passing key-value arguments
+let obj = {hello: 'world', foo: 'bar'};
+python`dict(baz=123, **${obj})`.then(x => {
+    assert.deepEqual(x, {baz: 123, hello: 'world', foo: 'bar'});
+});
+```
+
+## python.ex`` `statement` ``.then(...)
+
+Execute a statement that does not return a value.
+
+```javascript
+let a = 123, b = 321;
+python.ex`
+    def hello(a, b):
+        return a + b
+`;
+python`hello(${a}, ${b})`.then(x => assert.equal(x, a + b));
+```
+
+## python.lock(...).then(...)
+
+Locks access to the Python interpreter so code can be executed atomically.  If possible, it's recommend to define a function in Python to handle atomicity.  
+
+```javascript
+python.lock(python => {
+    python.ex`hello = 123`;
+    return python`hello + 321'`;
+}).then(x => assert.equal(x, 444));
+
+// Recommended to define function in Python
+python.ex`
+    def atomic():
+        hello = 123
+        return hello + 321
+`;
+python`atomic()`.then(x => assert.equal(x, 444));
+```
+
+## python.stdin, python.stdout, python.stderr
+
+Pipes going into the Python process, separate from execution & evaluation.  This can be used to stream data between processes, without buffering.
+
+```javascript
+let Promise = require('bluebird');
+let fs = Promise.promisifyAll(require('fs'));
+
+let fileWriter = fs.createWriteStream('output.txt');
+
+python.stdout.pipe(fileWriter);
+
+// listen on Python process's stdout
+python.ex`
+    import sys
+    for line in sys.stdin:
+        sys.stdout.write(line)
+        sys.stdout.flush()
+`.then(function () {
+    fileWriter.end();
+    fs.readFileAsync('output.txt', {encoding: 'utf8'}).then(x => assert.equal(x, 'hello\nworld\n'));
+});
+
+// write to Python process's stdin
+python.stdin.write('hello\n');
+setTimeout(() => {
+    python.stdin.write('world\n');
+    python.stdin.end();
+}, 10);
+```
+
+## python.end()
+
+Stops accepting new Python commands, and waits for queue to finish then gracefully closes the Python process.
+
+## python.disconnect()
+
+_Alias to [`python.end()`](#python-end)_
+
+## python.kill([signal])
+
+Send signal to Python process, same as [`child_process child.kill`](https://nodejs.org/api/child_process.html#child_process_event_exit).
+
+```javascript
+let Promise = require('bluebird');
+
+python.ex`
+    from time import sleep
+    sleep(9000)
+`.timeout(100).then(x => {
+    assert.ok(false);
+}).catch(Promise.TimeoutError, (exit_code) => {
+    console.error('Python process taking too long, restarted.');
+    python.kill('SIGKILL');
+    python = pythonBridge();
+});
+```
+
+# Handling Exceptions
+
+We can use Bluebird's [`promise.catch(...)`](http://bluebirdjs.com/docs/api/catch.html) catch handler in combination with Python's typed Exceptions to make exception handling easy.
+
+
+## python.Exception
+
+Catch any raised Python exception.
+
+```javascript
+python.ex`
+    hello = 123
+    print(hello + world)
+    world = 321
+`.catch(python.Exception, () => console.log('Woops!  `world` was used before it was defined.'));
+```
+
+## python.isException(name)
+
+Catch a Python exception matching the passed name.
+
+```javascript
+function pyDivide(numerator, denominator) {
+    return python`${numerator} / ${denominator}`
+        .catch(python.isException('ZeroDivisionError'), () => Promise.resolve(Infinity));
+}
+pyDivide(1, 0).then(x => {
+    assert.equal(x, Infinity);
+    assert.equal(1 / 0, Infinity);
+});
+```
+
+## pythonBridge.PythonException
+
+_Alias to `python.Exception`, this is useful if you want to import the function to at the root of the module._
+
+## pythonBridge.isPythonException
+
+_Alias to `python.isException`, this is useful if you want to import the function to at the root of the module._
+
+----
+
+# Features
+
+* Does not affect Python's stdin, stdout, or stderr pipes.
+* Exception stack traces forwarded to Node for easy debugging.
+* Python 2 & 3 support, end-to-end tested.
+* Command queueing, with promises.
+* Long running Python sessions.
+* ES6 template tags for easy interpolation & multiline code.
+
+# Comparisons
+
+After evaluating of the existing landscape of Python bridges, the following issues are why python-bridge was built.
+
+* [python-shell](https://github.com/extrabacon/python-shell) — No promises for queued requests; broken evaluation parser; conflates evaluation and stdout; complex configuration.
+* [python](https://github.com/73rhodes/node-python) — Broken evaluation parsing; no exception handling; conflates evaluation, stdout, and stderr.
+* [node-python](https://github.com/JeanSebTr/node-python) — Complects execution protocol with incomplete Python embedded DSL.
+* [python-runner](https://github.com/teamcarma/node-python-runner) — No long running sessions; `child_process.spawn` wrapper with unintuitive API; no serialization.
+* [python.js](https://github.com/monkeycz/python.js) — Embeds specific version of CPython; requires compiler and CPython dev packages; incomplete Python embedded DSL.
+* [cpython](https://github.com/eljefedelrodeodeljefe/node-cpython) — Complects execution protocol with incomplete Python embedded DSL.
+* [eval.py](https://www.npmjs.com/package/eval.py) — Can only evaluate single line expressions.
+* [py.js](https://www.npmjs.com/package/py.js) — For setting up virtualenvs only.
+
+# License
+
+MIT

TODO.md

@@ -0,0 +1,34 @@
+# TODO
+
+# Non-ES6 API
+
+## python(expression, args...).then(...)
+
+Evaluates an expression, or calls an expression with arguments.
+
+```javascript
+python('2 + 2').then((x) => assert.equal(x, 4));
+python('sorted', [6, 4, 1, 3]).then((x) => assert.deepEqual(x, [1, 3, 4, 6]));
+```
+
+## python.ex(statement).then(...)
+
+Execute a statement that does not return a value.
+
+```javascript
+python.ex('import math').then(function () {
+    console.log('Python library `math` imported');
+});
+```
+
+## python.kw(expression, args..., kwargs).then(...)
+
+Calls an expression, with arguments, and the last being an object of key-value arguments.
+
+```javascript
+let obj = {hello: 'world', foo: 'bar'};
+python.kw('dict', obj).then(function (x) {
+    assert.notStrictEqual(x, obj);
+    assert.deepEqual(x, obj);
+});
+```