[#9] start adding typescript support

Author: Ryan Munro

.gitignore

@@ -1 +1,3 @@
 node_modules
+package-lock.json
+test_typescript.js

README.ts.md

@@ -0,0 +1,247 @@
+# python-bridge [![Build Status](https://secure.travis-ci.org/Submersible/node-python-bridge.png?branch=master)](http://travis-ci.org/Submersible/node-python-bridge) [![Build Status](https://ci.appveyor.com/api/projects/status/8h64yyve684nn900/branch/master?svg=true)](https://ci.appveyor.com/project/munro/node-python-bridge/branch/master)
+
+Most robust and simple Python bridge.  [Features](#features), and [comparisons](#comparisons) to other Python bridges below, supports Windows.
+
+```
+npm install python-bridge
+```
+
+```typescript
+import assert from 'assert';
+import { pythonBridge } from 'python-bridge';
+
+async function main() {
+    const python = pythonBridge();
+
+    await python.ex`import math`;
+    const x = await python`math.sqrt(9)`;
+    assert.equal(x, 3);
+
+    const list = [3, 4, 2, 1];
+    const sorted = await python`sorted(${list})`;
+    assert.deepEqual(sorted, list.sort());
+
+    await python.end();
+}
+
+main().catch(console.error);
+```
+
+# API
+
+## var python = pythonBridge(options)
+
+Spawns a Python interpreter, exposing a bridge to the running processing.  Configurable via `options`.
+
+* `options.python` - Python interpreter, defaults to `python`
+
+Also inherits the following from [`child_process.spawn([options])`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options).
+
+* `options.cwd` - String Current working directory of the child process
+* `options.env` - Object Environment key-value pairs
+* `options.stdio` - Array Child's stdio configuration. Defaults to `['pipe', process.stdout, process.stderr]`
+* `options.uid` - Number Sets the user identity of the process.
+* `options.gid` - Number Sets the group identity of the process.
+
+```javascript
+const python = pythonBridge({
+    python: 'python3',
+    env: {PYTHONPATH: '/foo/bar'}
+});
+```
+
+## python`` `expression(args...)` ``.then(...)
+
+Evaluates Python code, returning the value back to Node.
+
+```javascript
+// Interpolates arguments using JSON serialization.
+assert.deepEqual([1, 3, 4, 6], await python`sorted(${[6, 4, 1, 3]})`);
+
+// Passing key-value arguments
+const obj = {hello: 'world', foo: 'bar'};
+assert.deepEqual(
+    {baz: 123, hello: 'world', foo: 'bar'},
+    await python`dict(baz=123, **${obj})`
+);
+```
+
+## python.ex`` `statement` ``.then(...)
+
+Execute Python statements.
+
+```javascript
+const a = 123, b = 321;
+python.ex`
+    def hello(a, b):
+        return a + b
+`;
+assert.equal(a + b, await python`hello(${a}, ${b})`);
+```
+
+## python.lock(...).then(...)
+
+Locks access to the Python interpreter so code can be executed atomically.  If possible, it's recommend to define a function in Python to handle atomicity.  
+
+```javascript
+const x: number = await python.lock(async python =>{
+    await python.ex`hello = 123`;
+    return await python`hello + 321`;
+});
+assert.equal(x, 444);
+
+// Recommended to define function in Python
+await python.ex`
+    def atomic():
+        hello = 123
+        return hello + 321
+`;
+assert.equal(444, await python`atomic()`);
+```
+
+## python.stdin, python.stdout, python.stderr
+
+Pipes going into the Python process, separate from execution & evaluation.  This can be used to stream data between processes, without buffering.
+
+```javascript
+import { delay, promisifyAll } from 'bluebird';
+const { createWriteStream, readFileAsync } = promisifyAll(require('fs'));
+
+const fileWriter = createWriteStream('hello.txt');
+python.stdout.pipe(fileWriter);
+
+// listen on Python process's stdout
+const stdinToStdout = python.ex`
+    import sys
+    for line in sys.stdin:
+        sys.stdout.write(line)
+        sys.stdout.flush()
+`;
+
+// write to Python process's stdin
+python.stdin.write('hello\n');
+await delay(10);
+python.stdin.write('world\n');
+
+// close python's stdin, and wait for python to finish writing
+python.stdin.end();
+await stdinToStdout;
+
+// assert file contents is the same as what was written
+const fileContents = await readFileAsync('hello.txt', {encoding: 'utf8'});
+assert.equal(fileContents.replace(/\r/g, ''), 'hello\nworld\n');
+```
+
+## python.end()
+
+Stops accepting new Python commands, and waits for queue to finish then gracefully closes the Python process.
+
+## python.disconnect()
+
+_Alias to [`python.end()`](#python-end)_
+
+## python.kill([signal])
+
+Send signal to Python process, same as [`child_process child.kill`](https://nodejs.org/api/child_process.html#child_process_event_exit).
+
+```javascript
+import { TimeoutError } from 'bluebird';
+
+let python = pythonBridge();
+
+try {
+    await python.ex`
+        from time import sleep
+        sleep(9000)
+    `.timeout(100);
+    assert.ok(false); // should not reach this
+} catch (e) {
+    if (e instanceof TimeoutError) {
+        python.kill('SIGKILL');
+        python = pythonBridge();
+    } else {
+        throw e;
+    }
+}
+python.end();
+```
+
+# Handling Exceptions
+
+We can use Bluebird's [`promise.catch(...)`](http://bluebirdjs.com/docs/api/catch.html) catch handler in combination with Python's typed Exceptions to make exception handling easy.
+
+
+## python.Exception
+
+Catch any raised Python exception.
+
+```javascript
+python.ex`
+    hello = 123
+    print(hello + world)
+    world = 321
+`.catch(python.Exception, () => console.log('Woops!  `world` was used before it was defined.'));
+```
+
+## python.isException(name)
+
+Catch a Python exception matching the passed name.
+
+```javascript
+import { isPythonException } from 'python-bridge';
+
+async function pyDivide(numerator, denominator) {
+    try {
+        await python`${numerator} / ${denominator}`;
+    } catch (e) {
+        if (isPythonException('ZeroDivisionError', e)) {
+            return Infinity;
+        }
+        throw e;
+    }
+}
+
+async function main() {
+    assert.equal(Infinity, await pyDivide(1, 0));
+    assert.equal(1 / 0, await pyDivide(1, 0));
+}
+
+main().catch(console.error);
+```
+
+## pythonBridge.PythonException
+
+_Alias to `python.Exception`, this is useful if you want to import the function to at the root of the module._
+
+## pythonBridge.isPythonException
+
+_Alias to `python.isException`, this is useful if you want to import the function to at the root of the module._
+
+----
+
+# Features
+
+* Does not affect Python's stdin, stdout, or stderr pipes.
+* Exception stack traces forwarded to Node for easy debugging.
+* Python 2 & 3 support, end-to-end tested.
+* Windows support, end-to-end tested.
+* Command queueing, with promises.
+* Long running Python sessions.
+* ES6 template tags for easy interpolation & multiline code.
+
+# Comparisons
+
+After evaluating of the existing landscape of Python bridges, the following issues are why python-bridge was built.
+
+* [python-shell](https://github.com/extrabacon/python-shell) — No promises for queued requests; broken evaluation parser; conflates evaluation and stdout; complex configuration.
+* [python](https://github.com/73rhodes/node-python) — Broken evaluation parsing; no exception handling; conflates evaluation, stdout, and stderr.
+* [node-python](https://github.com/JeanSebTr/node-python) — Complects execution protocol with incomplete Python embedded DSL.
+* [python-runner](https://github.com/teamcarma/node-python-runner) — No long running sessions; `child_process.spawn` wrapper with unintuitive API; no serialization.
+* [python.js](https://github.com/monkeycz/python.js) — Embeds specific version of CPython; requires compiler and CPython dev packages; incomplete Python embedded DSL.
+* [cpython](https://github.com/eljefedelrodeodeljefe/node-cpython) — Complects execution protocol with incomplete Python embedded DSL.
+* [eval.py](https://www.npmjs.com/package/eval.py) — Can only evaluate single line expressions.
+* [py.js](https://www.npmjs.com/package/py.js) — For setting up virtualenvs only.
+
+# License
+
+MIT

index.d.ts

@@ -1,16 +1,12 @@
-import {
-    Writable, 
-    Readable,
-}               from "stream";
-
 declare module "python-bridge" {
   interface pythonBridge extends Function {
-      (option?: PythonBridgeOptions): PythonBridge;
+      (options?: PythonBridgeOptions): PythonBridge;
   }
+
   export const pythonBridge: pythonBridge
 
   export interface PythonBridgeOptions {
-    intepreter: string;
+    intepreter?: string;
     stdio?: [PipeStdin, PipeStdout, PipeStderr];
     cwd?: string;
     env?: { [key:string]: string; };
@@ -26,13 +22,14 @@ declare module "python-bridge" {
     end(): Promise<void>;  
     disconnect(): Promise<void>;
     kill(signal: string | number): void;
-    stdin: Writable;
-    stdout: Readable;
-    stderr: Readable;
+    stdin: NodeJS.WritableStream;
+    stdout: NodeJS.ReadableStream;
+    stderr: NodeJS.ReadableStream;
     connected: boolean;
   }
 
-  export function isPythonException(e: any): boolean;
+  export function isPythonException(name: string): (e: any) => boolean;
+  export function isPythonException(name: string, e: any): boolean;
 
   export class PythonException extends Error {
     exception: {
@@ -50,7 +47,7 @@ declare module "python-bridge" {
   }
 
   export type Pipe = "pipe" | "ignore" | "inherit";
-  export type PipeStdin = Pipe | Readable;
-  export type PipeStdout = Pipe | Writable;
-  export type PipeStderr = Pipe | Writable;
+  export type PipeStdin = Pipe | NodeJS.ReadableStream;
+  export type PipeStdout = Pipe | NodeJS.WritableStream;
+  export type PipeStderr = Pipe | NodeJS.WritableStream;
 }

index.js

@@ -123,12 +123,16 @@ class PythonBridgeNotConnected extends Error {
     }
 }
 
-function isPythonException(name) {
-    return exc => (
+function isPythonException(name, exc) {
+    const thunk = exc => (
         exc instanceof PythonException &&
         exc.exception &&
         exc.exception.type.name === name
     );
+    if (exc === undefined) {
+        return thunk;
+    }
+    return thunk(exc);
 }
 
 function singleQueue() {
@@ -175,6 +179,7 @@ function json(text_nodes) {
     return dedent(text_nodes.reduce((cur, acc, i) => cur + JSON.stringify(values[i - 1]) + acc));
 }
 
+pythonBridge.pythonBridge = pythonBridge;
 pythonBridge.PythonException = PythonException;
 pythonBridge.PythonBridgeNotConnected = PythonBridgeNotConnected;
 pythonBridge.isPythonException = isPythonException;

package.json

@@ -9,7 +9,9 @@
     "lint:ts": "tslint --project tsconfig.json --type-check",
     "test": "npm run test:js && npm run test:ts",
     "test:js": "tap test.js",
-    "test:ts": "ts-node test.ts"
+    "test:ts": "ts-node test.ts",
+
+    "test_ts": "ts-node node_modules/blue-tape/bin/blue-tape test_typescript.ts"
   },
   "repository": {
     "type": "git",
@@ -31,10 +33,11 @@
   },
   "devDependencies": {
     "@types/node": "^8.0.14",
-    "tap": "^2.3.4",
+    "tap": "^10.7.0",
     "temp": "^0.8.3",
     "ts-node": "^3.2.0",
     "tslint": "^5.5.0",
+    "blue-tape": "^1.0.0",
     "typescript": "^2.4.1"
   }
 }