Change Python API to match subprocess API

Author: samwillis

DEVELOPMENT.md

@@ -0,0 +1,63 @@
+Node.js PyPI distribution
+=====================
+
+This repository contains the script used to repackage the [releases][nodejsdl] of [Node.js][nodejs] as [Python binary wheels][wheel]. This document is intended for maintainers; see the [package README][pkgreadme] for rationale and usage instructions.
+
+The repackaged artifacts are published as the [node-js PyPI package][pypi].
+
+[nodejs]: https://nodejs.org/
+[nodejsdl]:  https://nodejs.org/en/download/
+[wheel]: https://github.com/pypa/wheel
+[pkgreadme]: README.pypi.md
+[pypi]: https://pypi.org/project/nodejs-bin/
+
+This tool is based on the work of the creators of the [Zig language][ziglang], see [the original][basedon]. Thank you!
+
+[ziglang]: https://ziglang.org
+[basedon]: https://github.com/ziglang/zig-pypi
+
+Preparation
+-----------
+
+The script requires Python 3.5 or later.
+
+Install the dependencies:
+
+```shell
+pip install -r requirements.txt
+```
+
+The `libarchive-c` Python library requires the native [libarchive][] library to be available.
+
+[libarchive]: https://libarchive.org/
+
+Building wheels
+---------------
+
+Run the repackaging script:
+
+```shell
+python make_wheels.py
+```
+
+This command will download the Node.js release archives for every supported platform and convert them to binary wheels, which are placed under `dist/`. The Node.js version and platforms are configured in the script source.
+
+The process of converting release archives to binary wheels is deterministic, and the output of the script should be bit-for-bit identical regardless of the environment and platform it runs under. To this end, it prints the SHA256 hashes of inputs and outputs; the hashes of the inputs will match the ones on the [Node.js downloads page][nodejsdl], and the hashes of the outputs will match the ones on the [PyPI downloads page][pypidl].
+
+[pypidl]: https://pypi.org/project/node-js/#files
+
+Uploading wheels
+----------------
+
+Run the publishing utility:
+
+```shell
+twine dist/*
+```
+
+This command will upload the binary wheels built in the previous step to PyPI.
+
+License
+-------
+
+This script is distributed under the terms of the [MIT (Expat) license](LICENSE.txt).

README.md

@@ -1,63 +1,119 @@
 Node.js PyPI distribution
 =====================
 
-This repository contains the script used to repackage the [releases][nodejsdl] of [Node.js][nodejs] as [Python binary wheels][wheel]. This document is intended for maintainers; see the [package README][pkgreadme] for rationale and usage instructions.
+[Node.js][nodejs] is an open-source, cross-platform, back-end JavaScript runtime environment that runs on the V8 engine and executes JavaScript code outside a web browser. 
 
-The repackaged artifacts are published as the [node-js PyPI package][pypi].
+The [nodejs-bin][pypi] Python package redistributes Node.js so that it can be used as a dependency of Python projects. With `nodejs-bin` you can call `nodejs`, `npm` and `npx` from both the [command line](#command-line-usage) and a [Python API](#python-api-usage).
+
+**Note: this is an unofficial Node.js distribution.**
+
+**This is intended for use within Python virtual environments and containers, it should probably not be used for global instillation.**
+
+This PyPI distribution is provided by <https://github.com/samwillis/nodejs-pypi>.
 
 [nodejs]: https://nodejs.org/
-[nodejsdl]:  https://nodejs.org/en/download/
-[wheel]: https://github.com/pypa/wheel
-[pkgreadme]: README.pypi.md
 [pypi]: https://pypi.org/project/nodejs-bin/
 
-This tool is based on the work of the creators of the [Zig language][ziglang], see [the original][basedon]. Thank you!
+Install
+-------
+
+To install:
+
+```shell
+pip install nodejs-bin
+```
+
+You can specify the Node.js version to install with:
 
-[ziglang]: https://ziglang.org
-[basedon]: https://github.com/ziglang/zig-pypi
+```shell
+pip install nodejs-bin==<version>
 
-Preparation
------------
+# Example:
+pip install nodejs-bin==16.15.1
+```
 
-The script requires Python 3.5 or later.
+Command Line Usage
+------------------
 
-Install the dependencies:
+To run Node.js from the command line, use:
 
 ```shell
-pip install wheel twine libarchive-c
+python -m nodejs
+# or (see below)
+node
 ```
 
-The `libarchive-c` Python library requires the native [libarchive][] library to be available.
+`npm` and `npx` are also available as `python -m nodejs.npm` and `python -m nodejs.npx`.
+
+Additionally, the standard `node`, `npm` and `npx` commands are also added to your Python environment's `bin` directory. This is usually on your `PATH` and so they should be available in your shell environment.
 
-[libarchive]: https://libarchive.org/
+Python API Usage
+----------------
 
-Building wheels
----------------
+`node-bin` has a simple Python API that wraps the Node.js command line with the [Python `subprocess`](https://docs.python.org/3/library/subprocess.html).
 
-Run the repackaging script:
+For `node`, `npm` and `npx` there are `.call()`, `.run()` and `.Popen()` methods that match the equivalent `subprocess` methods.
 
-```shell
-python make_wheels.py
+To run Node.js from a Python program and return the exit code:
+
+```python
+from nodejs import node, npm, npx
+
+# Run Node.js and return the exit code.
+node.call(['script.js', 'arg1', ...], **kwargs)
+
+# Run npm and return the exit code.
+npm.call(['command', 'arg1', ...], **kwargs)
+
+# Run npx and return the exit code.
+npx.call(['command', 'arg1', ...], **kwargs)
 ```
 
-This command will download the Node.js release archives for every supported platform and convert them to binary wheels, which are placed under `dist/`. The Node.js version and platforms are configured in the script source.
+The `call(args, **kwargs)` functions wrap [`subprocess.call()`](https://docs.python.org/3/library/subprocess.html#subprocess.call), passes though all `kwargs` and returns the exit code of the process.
 
-The process of converting release archives to binary wheels is deterministic, and the output of the script should be bit-for-bit identical regardless of the environment and platform it runs under. To this end, it prints the SHA256 hashes of inputs and outputs; the hashes of the inputs will match the ones on the [Node.js downloads page][nodejsdl], and the hashes of the outputs will match the ones on the [PyPI downloads page][pypidl].
+To run Node.js from a Python program and return a [CompletedProcess](https://docs.python.org/3/library/subprocess.html#subprocess.CompletedProcess) object:
 
-[pypidl]: https://pypi.org/project/node-js/#files
+```python
+from nodejs import node, npm, npx
 
-Uploading wheels
-----------------
+# Run Node.js and return the exit code.
+node.run(['script.js', 'arg1', ...], **kwargs)
 
-Run the publishing utility:
+# Run npm and return the exit code.
+npm.run(['command', 'arg1', ...], **kwargs)
 
-```shell
-twine dist/*
+# Run npx and return the exit code.
+npx.run(['command', 'arg1', ...], **kwargs)
 ```
 
-This command will upload the binary wheels built in the previous step to PyPI.
+The `run(args, **kwargs)` functions wrap [`subprocess.run()`](https://docs.python.org/3/library/subprocess.html#subprocess.run), passes though all `kwargs` and returns a `CompletedProcess`.
+
+Additionally, to start a Node.js process and return a `subprocess.Popen` object, you can use the `Popen(args, **kwargs)` functions:
+
+```python
+from nodejs import node, npm, npx
+
+# Start Node.js and return the Popen object.
+node_process = node.Popen(['script.js', 'arg1', ...], **kwargs)
+
+# Start npm and return the Popen object.
+npm_process = npm.Popen(['command', 'arg1', ...], **kwargs)
+
+# Start npx and return the Popen object.
+npx_process = npx.Popen(['command', 'arg1', ...], **kwargs)
+```
+
+The `Popen(args, **kwargs)` functions wrap [`subprocess.Popen()`](https://docs.python.org/3/library/subprocess.html#subprocess.Popen), passes though all `kwargs` and returns a [`Popen` object](https://docs.python.org/3/library/subprocess.html#popen-objects).
+
+The `nodejs.node` api is also available as `nodejs.run` and `nodejs.call` and `nodejs.Popen`.
+
+Finally, there are a number of convenient attributes on the `nodejs` module:
+
+  * `nodejs.node_version`: the version of Node.js that is installed.
+  * `nodejs.path`: the path to the Node.js executable.
+
 
 License
 -------
 
-This script is distributed under the terms of the [MIT (Expat) license](LICENSE.txt).
+The [Node.js license](https://raw.githubusercontent.com/nodejs/node/master/LICENSE).