From 9e9ef0cb882d232640fdf9be5f61ff43dab3adb9 Mon Sep 17 00:00:00 2001
From: Noah <33094578+coolreader18@users.noreply.github.com>
Date: Mon, 7 Dec 2020 14:00:44 -0600
Subject: [PATCH] Add docs for injectPython et al in notebook/README

---
 wasm/notebook/README.md | 90 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 75 insertions(+), 15 deletions(-)

diff --git a/wasm/notebook/README.md b/wasm/notebook/README.md
index 97111a5a1..0e4d07d0e 100644
--- a/wasm/notebook/README.md
+++ b/wasm/notebook/README.md
@@ -2,17 +2,18 @@
 
 The RustPython Notebook is a **toy** notebook inspired by the now inactive Iodide project ([https://alpha.iodide.io/](https://alpha.iodide.io/)).
 
-Here is how it looks like:  
+Here is how it looks like:
 
 ![notebook](./screenshot.png)
 
-You can use the notebook to experiment with using Python and Javascript in the browser together.   
+You can use the notebook to experiment with using Python and Javascript in the browser together.
 
 The main use case is for scientific communication where you can have:
-- text or thesis in markdown,
-- math with Tex, 
-- a model or analysis written in python, 
-- a user interface and interactive visualization with JS.
+
+-   text or thesis in markdown,
+-   math with Tex,
+-   a model or analysis written in python,
+-   a user interface and interactive visualization with JS.
 
 The Notebook loads python in your browser (so you don't have to install it) then let yous play with those languages.
 
@@ -24,18 +25,77 @@ To read more about the reasoning behind certain features, check the blog on [htt
 
 Sample notebooks are under `snippets`
 
--  `snippets/python-markdown-math.txt`: python, markdown and math
--  `snippets/python-js.txt`, adds javascript
--  `snippets/python-js-css-md/` adds styling with css in separate, more organized files.
+-   `snippets/python-markdown-math.txt`: python, markdown and math
+-   `snippets/python-js.txt`, adds javascript
+-   `snippets/python-js-css-md/` adds styling with css in separate, more organized files.
 
 ## How to use
 
-- Run locally with `npm run dev`
-- Build with `npm run dist`
+-   Run locally with `npm run dev`
+-   Build with `npm run dist`
+
+## JS API
+
+```typescript
+// adds `values[name]` to the python scope under `name`
+function injectPython(values: { [name: string]: PythonValue });
+type PythonValue =
+    // null -> None
+    | null
+    | undefined
+    // n -> int(n) if Number.isInteger(n) else float(n)
+    | number
+    // s -> str(s)
+    | string
+    // typedArray -> bytes(typedArray)
+    | Uint8Array
+    // arr -> list(arr)
+    | Array<PythonValue>
+    // obj -> dict(Object.entries(obj))
+    | { [k: string]: PythonValue }
+    // js callback in python: positional args are passed as
+    // arguments, kwargs is the `this` variable
+    // f -> lambda *args, **kwargs: f.apply(kwargs, args)
+    //
+    // python callback in js: pass the positional args an array and
+    // kwargs as an object
+    // f -> (args, kwargs) => f(*args, **kwargs)
+    | Function;
+
+// appends an element to the notebook
+function pushNotebook(el: HTMLElement);
+
+// find and displays the traceback of a python error from a callback
+function handlePyError(err: any);
+// e.g.
+try {
+    pyCb([], {});
+} catch (err) {
+    handlePyError(err);
+}
+```
+
+`injectPython` demo:
+
+```js
+injectPython({
+    foo(a, b) {
+        console.log(a);
+        if (this.x != null) {
+            console.log(`got kwarg! x=${this.x}`);
+        }
+        return (y) => y + 1 + b;
+    },
+});
+```
+
+```py
+adder = foo("hy from python", 3, x=[1, 2, 3])
+assert adder(5) == 9
+```
 
 ## Wish list / TO DO
 
-- Better javascript support
-- Collaborative peer-to-peer editing with WebRTC. Think Google Doc or Etherpad editing but for code in the browser
-- `%%load` command for dynamically adding javascript libraries or css framework
-- Clean up and organize the code. Seriously rethink if we want to make it more than a toy.
\ No newline at end of file
+-   Collaborative peer-to-peer editing with WebRTC. Think Google Doc or Etherpad editing but for code in the browser
+-   `%%load` command for dynamically adding javascript libraries or css framework
+-   Clean up and organize the code. Seriously rethink if we want to make it more than a toy.