initial commit

Author: extrabacon

.gitignore

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

.jshintrc

@@ -0,0 +1,9 @@
+{
+  "predef": [],
+  "browser": false,
+  "node": true,
+  "curly": false,
+  "strict": false,
+  "expr": true,
+  "unused": "vars"
+}

CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.0.1
+* initial version
+* independent module moved from [extrabacon/pyspreadsheet](https://github.com/extrabacon/pyspreadsheet)

README.md

@@ -0,0 +1,148 @@
+# python-shell
+
+A simple way to run Python scripts from Node.js with basic but efficient inter-process communication through stdio.
+
+## Features
+
++ Reliably spawn Python scripts in a child process
++ Text, JSON and binary modes
++ Simple and efficient data transfers through stdin and stdout streams
++ Extended stack traces in case an exception is thrown
+
+## Installation
+
+```bash
+npm install python-shell
+```
+
+To run the tests:
+```bash
+npm test
+```
+
+## Documentation
+
+### Running a Python script:
+
+```js
+PythonShell.run('my_script.py', function (err) {
+  if (err) throw err;
+  console.log('finished');
+});
+```
+
+If the script writes to stderr or exits with a non-zero code, an error will be thrown.
+
+### Running a Python script with arguments and options:
+
+```js
+var options = {
+  mode: 'text',
+  pythonPath: 'path/to/python',
+  pythonOptions: ['-u'],
+  scriptPath: 'path/to/my/scripts',
+  args: ['value1', 'value2', 'value3']
+};
+
+PythonShell.run('my_script.py', options, function (err) {
+  if (err) throw err;
+});
+```
+
+The options are:
+
+* `mode`: Configures how data is exchanged between the child process and its parent. The possible values are:
+  * `text`: each line of data (ending with "\n") is emitted as a message (default)
+  * `json`: each line of data (ending with "\n") is parsed as JSON and emitted as a message
+  * `binary`: data is streamed as-is through `stdout` nd `stdin`
+* `pythonPath`: The path where to locate the "python" executable. Default: "python"
+* `pythonOptions`: Array of option switches to pass to "python"
+* `scriptPath`: The default path where to look for scripts. Default: "./python"
+* `args`: Array of arguments to pass to the script
+
+Other options are forwarded to `child_process.spawn`.
+
+### Exchanging data between Node and Python:
+
+```js
+var pyshell = new PythonShell('my_script.py');
+
+// send a message to the Python script via stdin
+pyshell.send('hello');
+
+pyshell.on('message', function (message) {
+  // received a message emitted from the script via stdout
+  console.log(message);
+});
+
+// end the input stream and allow the process to exit
+pyshell.end(function (err) {
+  if (err) throw err;
+  console.log('finished');
+});
+```
+
+Use `.send(message)` to send a message to the Python script. Attach the `message` event to listen to messages emitted from the Python script.
+
+For more details and examples, take a look at the unit tests.
+
+### Error Handling and extended stack traces
+
+An error will be thrown if the process exits with a non-zero exit code or if data has been written to stderr. Additionally, if "stderr" contains a standard Python traceback, the error is augmented with Python exception details including a concatenated stack trace.
+
+Example error with traceback (from test/python/error.py):
+```
+Traceback (most recent call last):
+  File "test/python/error.py", line 6, in <module>
+    divide_by_zero()
+  File "test/python/error.py", line 4, in divide_by_zero
+    print 1/0
+ZeroDivisionError: integer division or modulo by zero
+```
+would result into:
+```js
+{ [Error: ZeroDivisionError: integer division or modulo by zero]
+  traceback: 'Traceback (most recent call last):\n  File "test/python/error.py", line 6, in <module>\n    divide_by_zero()\n  File "test/python/error.py", line 4, in divide_by_zero\n    print 1/0\nZeroDivisionError: integer division or modulo by zero\n',
+  executable: 'python',
+  options: null,
+  script: 'test/python/error.py',
+  args: null,
+  exitCode: 1 }
+```
+and `err.stack` would look like this:
+```
+Error: ZeroDivisionError: integer division or modulo by zero
+    at PythonShell.parseError (python-shell/index.js:131:17)
+    at ChildProcess.<anonymous> (python-shell/index.js:67:28)
+    at ChildProcess.EventEmitter.emit (events.js:98:17)
+    at Process.ChildProcess._handle.onexit (child_process.js:797:12)
+    ----- Python Traceback -----
+    File "test/python/error.py", line 6, in <module>
+      divide_by_zero()
+    File "test/python/error.py", line 4, in divide_by_zero
+      print 1/0
+```
+
+## License
+
+The MIT License (MIT)
+
+Copyright (c) 2014 Nicolas Mercier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

index.js

@@ -0,0 +1,207 @@
+var EventEmitter = require('events').EventEmitter;
+var path = require('path');
+var util = require('util');
+var spawn = require('child_process').spawn;
+
+function toArray(source) {
+    if (typeof source === 'undefined' || source === null) {
+        return [];
+    } else if (!Array.isArray(source)) {
+        return [source];
+    }
+    return source;
+}
+
+function extend(obj) {
+    Array.prototype.slice.call(arguments, 1).forEach(function (source) {
+        if (source) {
+            for (var key in source) {
+                obj[key] = source[key];
+            }
+        }
+    });
+    return obj;
+}
+
+/**
+ * An interactive Python shell exchanging data through stdio
+ * @param {string} script    The python script to execute
+ * @param {object} [options] The launch options (also passed to child_process.spawn)
+ * @constructor
+ */
+var PythonShell = function (script, options) {
+    var self = this;
+    var errorData = '';
+    EventEmitter.call(this);
+
+    options = extend({}, PythonShell.defaultOptions, options);
+    var pythonPath = options.pythonPath || 'python';
+    var pythonOptions = toArray(options.pythonOptions);
+    var scriptArgs = toArray(options.args);
+
+    this.script = path.join(options.scriptPath || './python', script);
+    this.command = pythonOptions.concat(this.script, scriptArgs);
+    this.mode = options.mode || 'text';
+    this.terminated = false;
+    this.childProcess = spawn(pythonPath, this.command, options);
+
+    ['stdout', 'stdin', 'stderr'].forEach(function (name) {
+        self[name] = self.childProcess[name];
+        self.mode !== 'binary' && self[name].setEncoding('utf8');
+    });
+
+    // listen for incoming data on stdout
+    this.stdout.on('data', function (data) {
+        self.mode !== 'binary' && self.receive(data);
+    });
+
+    // listen to stderr and emit errors for incoming data
+    this.stderr.on('data', function (data) {
+        errorData += ''+data;
+    });
+
+    this.childProcess.on('exit', function (code) {
+        var err;
+        if (errorData || code !== 0) {
+            if (errorData) {
+                err = self.parseError(errorData);
+            } else {
+                err = new Error('process exited with code ' + code);
+            }
+            err = extend(err, {
+                executable: pythonPath,
+                options: pythonOptions.length ? pythonOptions : null,
+                script: self.script,
+                args: scriptArgs.length ? scriptArgs : null,
+                exitCode: code
+            });
+            // do not emit error if only a callback is used
+            if (self.listeners('ererrror').length || !self._endCallback) {
+                self.emit('error', err);
+            }
+        }
+        self.exitCode = code;
+        self.terminated = true;
+        self.emit('close');
+        self._endCallback && self._endCallback(err);
+    });
+};
+util.inherits(PythonShell, EventEmitter);
+
+// allow global overrides for options
+PythonShell.defaultOptions = {};
+
+/**
+ * Runs a Python script and returns collected messages
+ * @param  {string}   script   The script to execute
+ * @param  {Object}   options  The execution options
+ * @param  {Function} callback The callback function to invoke with the script results
+ * @return {PythonShell}       The PythonShell instance
+ */
+PythonShell.run = function (script, options, callback) {
+    if (typeof options === 'function') {
+        callback = options;
+        options = null;
+    }
+
+    var pyshell = new PythonShell(script, options);
+    var output = [];
+
+    return pyshell.on('message', function (message) {
+        output.push(message);
+    }).end(function (err) {
+        if (err) return callback(err);
+        return callback(null, output.length ? output : null);
+    });
+};
+
+/**
+ * Parses an error thrown from the Python process through stderr
+ * @param  {string|Buffer} data The stderr contents to parse
+ * @return {Error} The parsed error with extended stack trace when traceback is available
+ */
+PythonShell.prototype.parseError = function (data) {
+    var text = ''+data;
+    var error;
+
+    if (/^Traceback/.test(text)) {
+        // traceback data is available
+        var lines = (''+data).trim().split(/\n/g);
+        var exception = lines.pop();
+        error = new Error(exception);
+        error.traceback = data;
+        // extend stack trace
+        error.stack += '\n    ----- Python Traceback -----\n  ';
+        error.stack += lines.slice(1).join('\n  ');
+    } else {
+        // otherwise, create a simpler error with stderr contents
+        error = new Error(text);
+    }
+
+    return error;
+};
+
+/**
+ * Sends a message to the Python shell through stdin
+ * This method
+ * Override this method to format data to be sent to the Python process
+ * @param {string|Object} data The message to send
+ * @returns {PythonShell} The same instance for chaining calls
+ */
+PythonShell.prototype.send = function (message) {
+    if (this.mode === 'binary') {
+        throw new Error('cannot send a message in binary mode, use stdin directly instead');
+    } else if (this.mode === 'json') {
+        // write a JSON formatted message
+        this.stdin.write(JSON.stringify(message) + '\n');
+    } else {
+        // write text-based message (default)
+        if (typeof message !== 'string') message = message.toString();
+        this.stdin.write(message + '\n');
+    }
+    return this;
+};
+
+/**
+ * Parses data received from the Python shell stdout stream and emits "message" events
+ * This method is not used in binary mode
+ * Override this method to parse incoming data from the Python process into messages
+ * @param {string|Buffer} data The data to parse into messages
+ */
+PythonShell.prototype.receive = function (data) {
+    var self = this;
+    var lines = (''+data).split(/\n/g);
+    var lastLine = lines.pop();
+
+    // fix the first line with the remaining from the previous iteration of 'receive'
+    lines[0] = (this._remaining || '') + lines[0];
+    // keep the remaining for the next iteration of 'receive'
+    this._remaining = lastLine;
+
+    lines.forEach(function (line) {
+        if (self.mode === 'json') {
+            try {
+                self.emit('message', JSON.parse(line));
+            } catch (err) {
+                self.emit('error', extend(
+                    new Error('invalid JSON message: ' + data),
+                    { inner: err, data: data}
+                ));
+            }
+        } else {
+            self.emit('message', line);
+        }
+    });
+};
+
+/**
+ * Closes the stdin stream, which should cause the process to finish its work and close
+ * @returns {PythonShell} The same instance for chaining calls
+ */
+PythonShell.prototype.end = function (callback) {
+    this.childProcess.stdin.end();
+    this._endCallback = callback;
+    return this;
+};
+
+module.exports = PythonShell;