{

"predef": [],

"browser": false,

"node": true,

"curly": false,

"strict": false,

"expr": true,

"unused": "vars"

}

* initial version

* independent module moved from [extrabacon/pyspreadsheet](https://github.com/extrabacon/pyspreadsheet)

A simple way to run Python scripts from Node.js with basic but efficient inter-process communication through stdio.

+ 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

npm install python-shell

To run the tests:

npm test

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.

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`.

var pyshell = new PythonShell('my_script.py');

pyshell.send('hello');

pyshell.on('message', function (message) {

// received a message emitted from the script via stdout

console.log(message);

});

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.

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):

would result into:

{ [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:

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.

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;

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);

PythonShell.defaultOptions = {};

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);

});

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;

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;

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);

}

});

PythonShell.prototype.end = function (callback) {

this.childProcess.stdin.end();

this._endCallback = callback;

return this;

module.exports = PythonShell;