Merge pull request #11 from Submersible/typescript

Add Typescript Type Definition

Author: Ryan Munro

.gitignore

@@ -1 +1,10 @@
+.*.swp
+.DS_Store
+.node_repl_history
+.npm
 node_modules
+npm-debug.log*
+npm-shrinkwrap.json
+package-lock.json
+package-lock.json
+test_typescript.js

README.md

@@ -2,6 +2,10 @@
 
 Most robust and simple Python bridge.  [Features](#features), and [comparisons](#comparisons) to other Python bridges below, supports Windows.
 
+# API
+
+[View documentation for TypeScript examples.](README.ts.md)
+
 ```
 npm install python-bridge
 ```
@@ -23,8 +27,6 @@ python`sorted(${list})`.then(x => assert.deepEqual(x, list.sort()));
 python.end();
 ```
 
-# API
-
 ## var python = pythonBridge(options)
 
 Spawns a Python interpreter, exposing a bridge to the running processing.  Configurable via `options`.
@@ -76,7 +78,7 @@ python`hello(${a}, ${b})`.then(x => assert.equal(x, 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.  
+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
 python.lock(python => {

README.ts.md

@@ -0,0 +1,249 @@
+# 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.
+
+# API for TypeScript
+
+[View documentation with TypeScript examples.](README.ts.md)
+
+```
+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);
+```
+
+## 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

appveyor.yml

@@ -28,6 +28,3 @@ test_script:
   - "npm test"
 
 build: off
-
-cache:
-  - node_modules

index.d.ts

@@ -0,0 +1,59 @@
+interface pythonBridge extends Function {
+    (options?: PythonBridgeOptions): PythonBridge;
+}
+
+export const pythonBridge: pythonBridge
+
+export interface PythonBridgeOptions {
+  intepreter?: string;
+  stdio?: [PipeStdin, PipeStdout, PipeStderr];
+  cwd?: string;
+  env?: { [key:string]: string; };
+  uid?: number;
+  gid?: number;
+}
+
+export interface PythonBridge {
+  (literals: TemplateStringsArray | string, ...placeholders: any[]): Bluebird.Promise<any>;
+  ex(literals: TemplateStringsArray | string, ...placeholders: any[]): Bluebird.Promise<void>;
+  lock<T>(withLock: (python: PythonBridge) => Promise<T>): Bluebird.Promise<T>
+  pid: number;
+  end(): Promise<void>;
+  disconnect(): Promise<void>;
+  kill(signal: string | number): void;
+  stdin: NodeJS.WritableStream;
+  stdout: NodeJS.ReadableStream;
+  stderr: NodeJS.ReadableStream;
+  connected: boolean;
+}
+
+export function isPythonException(name: string): (e: any) => boolean;
+export function isPythonException(name: string, e: any): boolean;
+
+export class PythonException extends Error {
+  exception: {
+    message: string;
+    args: any[];
+    type: { name: string; module: string; }
+    format: string[];
+  };
+  traceback: {
+    lineno: number;
+    strack: string[];
+    format: string[]
+  };
+  format: string[]
+}
+
+export type Pipe = "pipe" | "ignore" | "inherit";
+export type PipeStdin = Pipe | NodeJS.ReadableStream;
+export type PipeStdout = Pipe | NodeJS.WritableStream;
+export type PipeStderr = Pipe | NodeJS.WritableStream;
+
+export namespace Bluebird {
+  interface Promise<T> extends _Promise<T>  {
+    timeout(number): Bluebird.Promise<T>;
+  }
+}
+
+type _Promise<T> = Promise<T>;

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,8 +179,10 @@ 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;
 pythonBridge.json = json;
-module.exports = pythonBridge;
+
+module.exports = pythonBridge.pythonBridge = pythonBridge;