#130 added recieveStderr function

Author: Almenon

README.md

@@ -25,8 +25,8 @@ npm test
 
 ### Running a Python script:
 
-```js
-var PythonShell = require('python-shell');
+```typescript
+import {PythonShell} from 'python-shell';
 
 PythonShell.run('my_script.py', function (err) {
   if (err) throw err;
@@ -38,10 +38,10 @@ If the script writes to stderr or exits with a non-zero code, an error will be t
 
 ### Running a Python script with arguments and options:
 
-```js
-var PythonShell = require('python-shell');
+```typescript
+import {PythonShell} from 'python-shell';
 
-var options = {
+let options = {
   mode: 'text',
   pythonPath: 'path/to/python',
   pythonOptions: ['-u'], // get print results in real-time
@@ -58,9 +58,9 @@ PythonShell.run('my_script.py', options, function (err, results) {
 
 ### Exchanging data between Node and Python:
 
-```js
-var PythonShell = require('python-shell');
-var pyshell = new PythonShell('my_script.py');
+```typescript
+import {PythonShell} from 'python-shell';
+let pyshell = new PythonShell('my_script.py');
 
 // sends a message to the Python script via stdin
 pyshell.send('hello');
@@ -92,9 +92,10 @@ For more details and examples including Python source code, take a look at the t
 
 ### 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 formatted Python traceback, the error is augmented with Python exception details including a concatenated stack trace.
+An error will be thrown if the process exits with a non-zero exit code. 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>
@@ -103,8 +104,10 @@ Traceback (most recent call last):
     print 1/0
 ZeroDivisionError: integer division or modulo by zero
 ```
+
 would result into the following error:
-```js
+
+```typescript
 { [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',
@@ -113,7 +116,9 @@ would result into the following error:
   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)
@@ -141,6 +146,7 @@ Creates an instance of `PythonShell` and starts the Python process
     * `binary`: data is streamed as-is through `stdout` and `stdin`
   * `formatter`: each message to send is transformed using this method, then appended with "\n"
   * `parser`: each line of data (ending with "\n") is parsed with this function and its result is emitted as a message
+  * `stderrParser`: each line of logs (ending with "\n") is parsed with this function and its result is emitted as a message
   * `encoding`: the text encoding to apply on the child process streams (default: "utf8")
   * `pythonPath`: The path where to locate the "python" executable. Default: "python"
   * `pythonOptions`: Array of option switches to pass to "python"
@@ -154,23 +160,25 @@ PythonShell instances have the following properties:
 * `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
+* `stderr`: the Python stderr stream, used for communicating logs & errors
 * `childProcess`: the process instance created via `child_process.spawn`
 * `terminated`: boolean indicating whether the process has exited
 * `exitCode`: the process exit code, available after the process has ended
 
 Example:
-```js
+
+```typescript
 // create a new instance
-var shell = new PythonShell('script.py', options);
+let shell = new PythonShell('script.py', options);
 ```
 
 #### `#defaultOptions`
 
 Configures default options for all new instances of PythonShell.
 
 Example:
-```js
+
+```typescript
 // setup a default "scriptPath"
 PythonShell.defaultOptions = { scriptPath: '../scripts' };
 ```
@@ -182,7 +190,8 @@ Runs the Python script and invokes `callback` with the results. The callback con
 This method is also returning the `PythonShell` instance.
 
 Example:
-```js
+
+```typescript
 // run a simple script
 PythonShell.run('script.py', function (err, results) {
   // script finished
@@ -194,20 +203,25 @@ PythonShell.run('script.py', function (err, results) {
 Sends a message to the Python script via stdin. The data is formatted according to the selected mode (text or JSON), or through a custom function when `formatter` is specified.
 
 Example:
-```js
+
+```typescript
 // send a message in text mode
-var shell = new PythonShell('script.py', { mode: 'text '});
+let shell = new PythonShell('script.py', { mode: 'text '});
 shell.send('hello world!');
 
 // send a message in JSON mode
-var shell = new PythonShell('script.py', { mode: 'json '});
+let shell = new PythonShell('script.py', { mode: 'json '});
 shell.send({ command: "do_stuff", args: [1, 2, 3] });
 ```
 
 #### `.receive(data)`
 
 Parses incoming data from the Python script written via stdout and emits `message` events. This method is called automatically as data is being received from stdout.
 
+#### `.receiveStderr(data)`
+
+Parses incoming logs from the Python script written via stderr and emits `stderr` events. This method is called automatically as data is being received from stderr.
+
 #### `.end(callback)`
 
 Closes the stdin stream, allowing the Python script to finish and exit. The optional callback is invoked when the process is terminated.
@@ -221,20 +235,35 @@ Terminates the python script, the optional end callback is invoked if specified.
 Fires when a chunk of data is parsed from the stdout stream via the `receive` method. If a `parser` method is specified, the result of this function will be the message value. This event is not emitted in binary mode.
 
 Example:
-```js
+
+```typescript
 // receive a message in text mode
-var shell = new PythonShell('script.py', { mode: 'text '});
+let shell = new PythonShell('script.py', { mode: 'text '});
 shell.on('message', function (message) {
   // handle message (a line of text from stdout)
 });
 
 // receive a message in JSON mode
-var shell = new PythonShell('script.py', { mode: 'json '});
+let shell = new PythonShell('script.py', { mode: 'json '});
 shell.on('message', function (message) {
   // handle message (a line of text from stdout, parsed as JSON)
 });
 ```
 
+#### event: `stderr`
+
+Fires when a chunk of logs is parsed from the stderr stream via the `receiveStderr` method. If a `stderrParser` method is specified, the result of this function will be the message value. This event is not emitted in binary mode.
+
+Example:
+
+```typescript
+// receive a message in text mode
+let shell = new PythonShell('script.py', { mode: 'text '});
+shell.on('stderr', function (stderr) {
+  // handle stderr (a line of text from stderr)
+});
+```
+
 #### event: `close`
 
 Fires when the process has been terminated, with an error or not.

index.ts

@@ -32,6 +32,7 @@ export interface Options extends SpawnOptions{
     mode?: 'text'|'json'|'binary'
     formatter?: (param:string)=>any
     parser?: (param:string)=>any
+    stderrParser?: (param:string)=>any
     encoding?: string
     pythonPath?: string
     pythonOptions?: string[]
@@ -56,6 +57,7 @@ export class PythonShell extends EventEmitter{
     mode:string
     formatter:(param:string|Object)=>any
     parser:(param:string)=>any
+    stderrParser:(param:string)=>any
     terminated:boolean
     childProcess:ChildProcess
     stdin: Writable;
@@ -107,6 +109,7 @@ export class PythonShell extends EventEmitter{
         this.mode = options.mode || 'text';
         this.formatter = resolve('format', options.formatter || this.mode);
         this.parser = resolve('parse', options.parser || this.mode);
+        this.stderrParser = resolve('parse', options.stderrParser || this.mode);
         this.terminated = false;
         this.childProcess = spawn(pythonPath, this.command, options);
 
@@ -123,6 +126,7 @@ export class PythonShell extends EventEmitter{
         // listen to stderr and emit errors for incoming data
         this.stderr.on('data', function (data) {
             errorData += ''+data;
+            self.receiveStderr(data);
         });
 
         this.stderr.on('end', function(){
@@ -316,6 +320,20 @@ export class PythonShell extends EventEmitter{
      * @param {string|Buffer} data The data to parse into messages
      */
     receive(data:string|Buffer) {
+        return this.recieveInternal(data, 'message');
+    };
+
+    /**
+     * Parses data received from the Python shell stderr stream and emits "stderr" events
+     * This method is not used in binary mode
+     * Override this method to parse incoming logs from the Python process into messages
+     * @param {string|Buffer} data The data to parse into messages
+     */
+    receiveStderr(data:string|Buffer) {
+        return this.recieveInternal(data, 'stderr');
+    };
+
+    private recieveInternal(data:string|Buffer, emitType:'message'|'stderr'){
         let self = this;
         let parts = (''+data).split(new RegExp(newline,'g'));
 
@@ -332,11 +350,12 @@ export class PythonShell extends EventEmitter{
         this._remaining = lastLine;
 
         parts.forEach(function (part) {
-            self.emit('message', self.parser(part));
+            if(emitType == 'message') self.emit(emitType, self.parser(part));
+            else if(emitType == 'stderr') self.emit(emitType, self.stderrParser(part));
         });
 
         return this;
-    };
+    }
 
     /**
      * Closes the stdin stream, which should cause the process to finish its work and close

test/python/stderrLogging.py

@@ -5,20 +5,15 @@
 
 # set up logging to file - see previous section for more details
 logging.basicConfig(level=logging.DEBUG)
-# define a Handler which writes INFO messages or higher to the sys.stderr
-console = logging.StreamHandler()
-console.setLevel(logging.INFO)
-# add the handler to the root logger
-logging.getLogger('').addHandler(console)
 
 # Now, we can log to the root logger, or any other logger. First the root...
 logging.info('Jackdaws love my big sphinx of quartz.')
 
 # Now, define a couple of other loggers which might represent areas in your
 # application:
 
-logger1 = logging.getLogger('myapp.area1')
-logger2 = logging.getLogger('myapp.area2')
+logger1 = logging.getLogger('log1')
+logger2 = logging.getLogger('log2')
 
 logger1.debug('Quick zephyrs blow, vexing daft Jim.')
 logger1.info('How quickly daft jumping zebras vex.')

test/test-python-shell.ts

@@ -275,6 +275,48 @@ describe('PythonShell', function () {
         });
     });
 
+    describe('.receiveStderr(data)', function () {
+        it('should emit stderr logs as strings when mode is "text"', function (done) {
+            let pyshell = new PythonShell('stderrLogging.py', {
+                mode: 'text'
+            });
+            let count = 0;
+            pyshell.on('stderr', function (stderr) {
+                count === 0 && stderr.should.be.exactly('INFO:root:Jackdaws love my big sphinx of quartz.');
+                count === 1 && stderr.should.be.exactly('DEBUG:log1:Quick zephyrs blow, vexing daft Jim.');
+                count++;
+            }).on('close', function () {
+                count.should.be.exactly(5);
+            }).send('hello').send('world').end(done);
+        });
+        it('should not be invoked when mode is "binary"', function (done) {
+            let pyshell = new PythonShell('echo_args.py', {
+                args: ['hello', 'world'],
+                mode: 'binary'
+            });
+            pyshell.receiveStderr = function () {
+                throw new Error('should not emit stderr in binary mode');
+            };
+            pyshell.end(done);
+        });
+        it('should use a custom parser function', function (done) {
+            let pyshell = new PythonShell('stderrLogging.py', {
+                mode: 'text',
+                stderrParser: function (stderr) {
+                    return stderr.toUpperCase();
+                }
+            });
+            let count = 0;
+            pyshell.on('stderr', function (stderr) {
+                count === 0 && stderr.should.be.exactly('INFO:ROOT:JACKDAWS LOVE MY BIG SPHINX OF QUARTZ.');
+                count === 1 && stderr.should.be.exactly('DEBUG:LOG1:QUICK ZEPHYRS BLOW, VEXING DAFT JIM.');
+                count++;
+            }).on('close', function () {
+                count.should.be.exactly(5);
+            }).send('hello').send('world!').end(done);
+        });
+    });
+
     describe('.end(callback)', function () {
         it('should end normally when exit code is zero', function (done) {
             let pyshell = new PythonShell('exit-code.py');