Run Python scripts from Node.js with simple (but efficient) inter-process communication through stdio
A simple way to run Python scripts from Node.js with basic but efficient inter-process communication and better error handling.
- 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 when an error is thrown
npm install python-shell
To run the tests:
var PythonShell = require'python-shell';PythonShellrun'my_script.py'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 PythonShell = require'python-shell';var options =mode: 'text'pythonPath: 'path/to/python'pythonOptions: '-u'scriptPath: 'path/to/my/scripts'args: 'value1' 'value2' 'value3';PythonShellrun'my_script.py' optionsif err throw err;// results is an array consisting of messages collected during executionconsole.log'results: %j' results;;
var PythonShell = require'python-shell';var pyshell = 'my_script.py';// sends a message to the Python script via stdinpyshellsend'hello';pyshellon'message'// received a message sent from the Python script (a simple "print" statement)console.logmessage;;// end the input stream and allow the process to exitpyshellendif err throw err;console.log'finished';;
.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 including Python source code, take a look at the 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 formatted Python traceback, the error is augmented with Python exception details including a concatenated stack trace.
Sample 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_zeroprint 1/0ZeroDivisionError: integer division or modulo by zero
would result into the following error:
Error: ZeroDivisionError: integer division or modulo by zerotraceback: '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: nullscript: 'test/python/error.py'args: nullexitCode: 1
err.stack would look like this:
Error: ZeroDivisionError: integer division or modulo by zeroat 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_zeroprint 1/0
Creates an instance of
PythonShell and starts the Python process
script: the path of the script to execute
options: the execution options, consisting of:
mode: Configures how data is exchanged when data flows through stdin and stdout. 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
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
PythonShell instances have the following properties:
script: the path of the script to execute
command: the full command arguments passed to the Python executable
stdin: the Python stdin stream, used to send data to the child process
stdout: the Python stdout stream, used for receiving data from the child process
stderr: the Python stderr stream, used for communicating errors
childProcess: the process instance created via
terminated: boolean indicating whether the process has exited
exitCode: the process exit code, available after the process has ended
// create a new instancevar shell = 'script.py' options;
Configures default options for all new instances of PythonShell.
// setup a default "scriptPath"PythonShelldefaultOptions = scriptPath: '../scripts' ;
Runs the Python script and invokes
callback with the results. The callback contains the execution error (if any) as well as an array of messages emitted from the Python script.
This method is also returning the
// run a simple scriptPythonShellrun'script.py'// script finished;
Sends a message to the Python script via stdin. The data is formatted according to the selected mode (text or JSON). This method can be overridden in order to format the data in some other way.
This method should not be used in binary mode.
// send a message in text modevar shell = 'script.py' mode: 'text ';shellsend'hello world!';// send a message in JSON modevar shell = 'script.py' mode: 'json ';shellsend command: "do_stuff" args: 1 2 3 ;
Parses incoming data from the Python script written via stdout and emits
message events. The data is parsed as JSON if mode has been set to "json". This method is called automatically as data is being received from stdout and can be overridden to parse the data differently.
Closes the stdin stream, allowing the Python script to finish and exit. The optional callback is invoked when the process is terminated.
Fires when a chunk of data is parsed from the stdout stream via the
receive method. This event is not emitted in binary mode.
// receive a message in text modevar shell = 'script.py' mode: 'text ';shellon'message'// handle message (a line of text from stdout);// receive a message in JSON modevar shell = 'script.py' mode: 'json ';shellon'message'// handle message (a line of text from stdout, parsed as JSON);
Fires when the process has been terminated, with an error or not.
Fires when the process terminates with a non-zero exit code, or if data is written to the stderr stream.
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.