Merge pull request #233 from extrabacon/version2

Version3

Author: Almenon

.vscode/launch.json

@@ -45,4 +45,4 @@
       "protocol": "inspector"
     }
   ]
-}
+}

CHANGELOG.md

@@ -1,20 +1,35 @@
-## 1.0.8
-* @joaoe fixed a bug with pythonshell not working with unset std streams
-* https://github.com/extrabacon/python-shell/milestone/9
+## [3.0.0] - 2021-03-07
+### Changed
+- **BREAKING** Default python path changed back to `python` on Windows. [#237](https://github.com/extrabacon/python-shell/issues/237)
+- **BREAKING** `error` event renamed to `pythonError` event. [#118](https://github.com/extrabacon/python-shell/issues/118)
+- **BREAKING** `receive` methods removed in favor of `splitter` arguments in the constructor. This lets the default splitting logic reside in a reuseable stream transformer. Now if you have extra pipes you can reuse `newlineTransformer` to split incoming data into newline-seperated lines.
 
-## 1.0.7
-* default python path updated to py on windows
+### Added
+- `error` event that is fired upon failure to launch process, among other things. [#118](https://github.com/extrabacon/python-shell/issues/118)
 
-## 1.0.4
-* added getVersionSync
+## [1.0.8]
+### Fixed
+- @joaoe fixed a bug with pythonshell not working with unset std streams
+- https://github.com/extrabacon/python-shell/milestone/9
 
-## 0.0.3
-* fixed buffering in `PythonShell.receive`, fixing [#1](https://github.com/extrabacon/python-shell/issues/1)
+## [1.0.7]
+### Changed
+- default python path updated to py on windows
 
-## 0.0.2
-* improved documentation
+## [1.0.4]
+### Added
+- added getVersionSync
 
-## 0.0.1
-* initial version
-* independent module moved from [extrabacon/pyspreadsheet](https://github.com/extrabacon/pyspreadsheet)
+## [0.0.3]
+### Fixed
+- fixed buffering in `PythonShell.receive`, fixing [#1](https://github.com/extrabacon/python-shell/issues/1)
+
+## [0.0.2]
+### Changed
+- improved documentation
+
+## [0.0.1]
+### Added
+- initial version
+- independent module moved from [extrabacon/pyspreadsheet](https://github.com/extrabacon/pyspreadsheet)
 

README.md

@@ -1,6 +1,6 @@
 # [python-shell](https://www.npmjs.com/package/python-shell) [![Build status](https://ci.appveyor.com/api/projects/status/m8e3h53vvxg5wb2q/branch/master?svg=true)](https://ci.appveyor.com/project/Almenon/python-shell/branch/master) [![codecov](https://codecov.io/gh/extrabacon/python-shell/branch/master/graph/badge.svg)](https://codecov.io/gh/extrabacon/python-shell)
 
-<!-- chage above url accroding to repo -->
+<!-- change above url according to repo -->
 A simple way to run Python scripts from Node.js with basic but efficient inter-process communication and better error handling.
 
 ## Features
@@ -11,17 +11,15 @@ A simple way to run Python scripts from Node.js with basic but efficient inter-p
 + Simple and efficient data transfers through stdin and stdout streams
 + Extended stack traces when an error is thrown
 
+## Requirements
+First make sure you are able to run `python3` (Mac/Linux) or `python` (Windows) from the terminal. If you are not then you might need to add it to the PATH. If you want to use a version of python not in the PATH you should specify `options.pythonPath`.
+
 ## Installation
 
 ```bash
 npm install python-shell
 ```
 
-To run the tests:
-```bash
-npm test
-```
-
 ## Documentation
 
 ### Running python code:
@@ -163,17 +161,19 @@ 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
+    * `text`: each line of data is emitted as a message (default)
+    * `json`: each line of data is parsed as JSON and emitted as a message
     * `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
+  * `formatter`: each message to send is transformed using this method, then appended with a newline
+  * `parser`: each line of data is parsed with this function and its result is emitted as a message
+  * `stderrParser`: each line of logs 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: "python3" ("py" for Windows)
+  * `pythonPath`: The path where to locate the "python" executable. Default: "python3" ("python" for Windows)
   * `pythonOptions`: Array of option switches to pass to "python"
   * `scriptPath`: The default path where to look for scripts. Default is the current working directory.
   * `args`: Array of arguments to pass to the script
+* `stdoutSplitter`: splits stdout into chunks, defaulting to splitting into newline-seperated lines
+* `stderrSplitter`: splits stderr into chunks, defaulting to splitting into newline-seperated lines
 
 Other options are forwarded to `child_process.spawn`.
 
@@ -271,14 +271,6 @@ 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.
@@ -289,7 +281,7 @@ Terminates the python script. A kill signal may be provided by `signal`, if `sig
 
 #### event: `message`
 
-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.
+After the stdout stream is split into chunks by stdoutSplitter the chunks are parsed by the parser and a message event is emitted for each parsed chunk. This event is not emitted in binary mode.
 
 Example:
 
@@ -309,7 +301,7 @@ shell.on('message', function (message) {
 
 #### 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.
+After the stderr stream is split into chunks by stderrSplitter the chunks are parsed by the parser and a message event is emitted for each parsed chunk. This event is not emitted in binary mode.
 
 Example:
 
@@ -325,10 +317,23 @@ shell.on('stderr', function (stderr) {
 
 Fires when the process has been terminated, with an error or not.
 
-#### event: `error`
+#### event: `pythonError`
 
 Fires when the process terminates with a non-zero exit code.
 
+#### event: `error`
+
+Fires when:
+* The process could not be spawned, or
+* The process could not be killed, or
+* Sending a message to the child process failed.
+
+If the process could not be spawned please double-check that python can be launched from the terminal.
+
+### NewlineTransformer
+
+A utility class for splitting stream data into newlines. Used as the default for stdoutSplitter and stderrSplitter if they are unspecified. You can use this class for any extra python streams if you'd like.
+
 ## Used By:
 
 Python-Shell is used by [arepl-vscode](https://github.com/almenon/arepl-vscode), [gitinspector](https://github.com/ejwa/gitinspector), [pyspreadsheet](https://github.com/extrabacon/pyspreadsheet), [AtlantOS Ocean Data QC](https://github.com/ocean-data-qc/ocean-data-qc) and more!