Docstrings

for more information, see https://pre-commit.ci

README.md

@@ -1,6 +1,6 @@
 # PyScript
 
-## PyScrcipt is an open source platform for Python in the browser.
+## PyScript is an open source platform for Python in the browser.
 
 Using PyScript is as simple as:
 
@@ -76,7 +76,7 @@ Read the [contributing guide](https://docs.pyscript.net/latest/contributing/)
 to learn about our development process, reporting bugs and improvements,
 creating issues and asking questions.
 
-Check out the [developing process](https://docs.pyscript.net/latest/developers/)
+Check out the [development process](https://docs.pyscript.net/latest/developers/)
 documentation for more information on how to setup your development environment.
 
 ## Governance

core/package-lock.json

@@ -1,18 +1,19 @@
 {
     "name": "@pyscript/core",
-    "version": "0.6.4",
+    "version": "0.6.7",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "@pyscript/core",
-            "version": "0.6.4",
+            "version": "0.6.7",
             "license": "APACHE-2.0",
             "dependencies": {
                 "@ungap/with-resolvers": "^0.1.0",
                 "@webreflection/idb-map": "^0.3.2",
+                "add-promise-listener": "^0.1.3",
                 "basic-devtools": "^0.1.6",
-                "polyscript": "^0.16.2",
+                "polyscript": "^0.16.3",
                 "sabayon": "^0.5.2",
                 "sticky-module": "^0.1.1",
                 "to-json-callback": "^0.1.1",
@@ -25,7 +26,7 @@
                 "@codemirror/state": "^6.4.1",
                 "@codemirror/view": "^6.34.1",
                 "@playwright/test": "1.45.3",
-                "@rollup/plugin-commonjs": "^28.0.0",
+                "@rollup/plugin-commonjs": "^28.0.1",
                 "@rollup/plugin-node-resolve": "^15.3.0",
                 "@rollup/plugin-terser": "^0.4.4",
                 "@webreflection/toml-j0.4": "^1.1.3",
@@ -559,19 +560,19 @@
             }
         },
         "node_modules/@rollup/plugin-commonjs": {
-            "version": "28.0.0",
-            "resolved": "https://registry.npmjs.org/@rollup/plugin-commonjs/-/plugin-commonjs-28.0.0.tgz",
-            "integrity": "sha512-BJcu+a+Mpq476DMXG+hevgPSl56bkUoi88dKT8t3RyUp8kGuOh+2bU8Gs7zXDlu+fyZggnJ+iOBGrb/O1SorYg==",
+            "version": "28.0.1",
+            "resolved": "https://registry.npmjs.org/@rollup/plugin-commonjs/-/plugin-commonjs-28.0.1.tgz",
+            "integrity": "sha512-+tNWdlWKbpB3WgBN7ijjYkq9X5uhjmcvyjEght4NmH5fAU++zfQzAJ6wumLS+dNcvwEZhKx2Z+skY8m7v0wGSA==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
                 "@rollup/pluginutils": "^5.0.1",
                 "commondir": "^1.0.1",
                 "estree-walker": "^2.0.2",
-                "fdir": "^6.1.1",
+                "fdir": "^6.2.0",
                 "is-reference": "1.2.1",
                 "magic-string": "^0.30.3",
-                "picomatch": "^2.3.1"
+                "picomatch": "^4.0.2"
             },
             "engines": {
                 "node": ">=16.0.0 || 14 >= 14.17"
@@ -585,19 +586,6 @@
                 }
             }
         },
-        "node_modules/@rollup/plugin-commonjs/node_modules/picomatch": {
-            "version": "2.3.1",
-            "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz",
-            "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==",
-            "dev": true,
-            "license": "MIT",
-            "engines": {
-                "node": ">=8.6"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/jonschlinkert"
-            }
-        },
         "node_modules/@rollup/plugin-node-resolve": {
             "version": "15.3.0",
             "resolved": "https://registry.npmjs.org/@rollup/plugin-node-resolve/-/plugin-node-resolve-15.3.0.tgz",
@@ -1018,6 +1006,12 @@
                 "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0"
             }
         },
+        "node_modules/add-promise-listener": {
+            "version": "0.1.3",
+            "resolved": "https://registry.npmjs.org/add-promise-listener/-/add-promise-listener-0.1.3.tgz",
+            "integrity": "sha512-hQ6IgGJ7NvvlPYbwdekhdVwPb4QzEptNZ5v7B4XRKz7FukUPDuF/v+R5EFHArWmhmq4d+xv0G4/B5bu2GSiz9Q==",
+            "license": "MIT"
+        },
         "node_modules/ajv": {
             "version": "6.12.6",
             "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz",
@@ -1197,9 +1191,9 @@
             }
         },
         "node_modules/caniuse-lite": {
-            "version": "1.0.30001667",
-            "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001667.tgz",
-            "integrity": "sha512-7LTwJjcRkzKFmtqGsibMeuXmvFDfZq/nzIjnmgCGzKKRVzjD72selLDK1oPF/Oxzmt4fNcPvTDvGqSDG4tCALw==",
+            "version": "1.0.30001668",
+            "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001668.tgz",
+            "integrity": "sha512-nWLrdxqCdblixUO+27JtGJJE/txpJlyUy5YN1u53wLZkP0emYCo5zgS6QYft7VUYR42LGgi/S5hdLZTrnyIddw==",
             "dev": true,
             "funding": [
                 {
@@ -1626,9 +1620,9 @@
             }
         },
         "node_modules/electron-to-chromium": {
-            "version": "1.5.33",
-            "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.33.tgz",
-            "integrity": "sha512-+cYTcFB1QqD4j4LegwLfpCNxifb6dDFUAwk6RsLusCwIaZI6or2f+q8rs5tTB2YC53HhOlIbEaqHMAAC8IOIwA==",
+            "version": "1.5.36",
+            "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.36.tgz",
+            "integrity": "sha512-HYTX8tKge/VNp6FGO+f/uVDmUkq+cEfcxYhKf15Akc4M5yxt5YmorwlAitKWjWhWQnKcDRBAQKXkhqqXMqcrjw==",
             "dev": true,
             "license": "ISC"
         },
@@ -2342,9 +2336,9 @@
             "license": "MIT"
         },
         "node_modules/magic-string": {
-            "version": "0.30.11",
-            "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.11.tgz",
-            "integrity": "sha512-+Wri9p0QHMy+545hKww7YAu5NyzF8iomPL/RQazugQ9+Ez4Ic3mERMd8ZTX5rfK944j+560ZJi8iAwgak1Ac7A==",
+            "version": "0.30.12",
+            "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.12.tgz",
+            "integrity": "sha512-Ea8I3sQMVXr8JhN4z+H/d8zwo+tYDgHE9+5G4Wnrwhs0gaK9fXTKx0Tw5Xwsd/bCPTTZNRAdpyzvoeORe9LYpw==",
             "dev": true,
             "license": "MIT",
             "dependencies": {
@@ -2581,8 +2575,6 @@
             "integrity": "sha512-M7BAV6Rlcy5u+m6oPhAPFgJTzAioX/6B0DxyvDlo9l8+T3nLKbrczg2WLUyzd45L8RqfUMyGPzekbMvX2Ldkwg==",
             "dev": true,
             "license": "MIT",
-            "optional": true,
-            "peer": true,
             "engines": {
                 "node": ">=12"
             },
@@ -2642,9 +2634,9 @@
             }
         },
         "node_modules/polyscript": {
-            "version": "0.16.2",
-            "resolved": "https://registry.npmjs.org/polyscript/-/polyscript-0.16.2.tgz",
-            "integrity": "sha512-S+RHW3ogB4nFlajp+Pd+YWuoEJMRBNuFwcke3H/lxlq8ZkX2lEZhvvda+QcwAsQXitmWg3Wi0Oz8fuwXyIKZeg==",
+            "version": "0.16.3",
+            "resolved": "https://registry.npmjs.org/polyscript/-/polyscript-0.16.3.tgz",
+            "integrity": "sha512-I3kHxt62FMRAX2iVl24iCEtG4UnUInMSbv/LnwevkmjOErLPAQtES4CNzU/fgKRpXYCqp0WWQaRvRYkJhpMIbA==",
             "license": "APACHE-2.0",
             "dependencies": {
                 "@ungap/structured-clone": "^1.2.0",

core/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@pyscript/core",
-    "version": "0.6.4",
+    "version": "0.6.7",
     "type": "module",
     "description": "PyScript",
     "module": "./index.js",
@@ -60,8 +60,9 @@
     "dependencies": {
         "@ungap/with-resolvers": "^0.1.0",
         "@webreflection/idb-map": "^0.3.2",
+        "add-promise-listener": "^0.1.3",
         "basic-devtools": "^0.1.6",
-        "polyscript": "^0.16.2",
+        "polyscript": "^0.16.3",
         "sabayon": "^0.5.2",
         "sticky-module": "^0.1.1",
         "to-json-callback": "^0.1.1",
@@ -74,7 +75,7 @@
         "@codemirror/state": "^6.4.1",
         "@codemirror/view": "^6.34.1",
         "@playwright/test": "1.45.3",
-        "@rollup/plugin-commonjs": "^28.0.0",
+        "@rollup/plugin-commonjs": "^28.0.1",
         "@rollup/plugin-node-resolve": "^15.3.0",
         "@rollup/plugin-terser": "^0.4.4",
         "@webreflection/toml-j0.4": "^1.1.3",

core/src/config.js

@@ -146,6 +146,8 @@ for (const [TYPE] of TYPES) {
             }
         } else if (!parsed?.plugins?.includes(`!${key}`)) {
             toBeAwaited.push(value().then(({ default: p }) => p));
+        } else if (key === "error") {
+            toBeAwaited.push(value().then(({ notOnDOM }) => notOnDOM()));
         }
     }
 

core/src/plugins/donkey.js

@@ -1,64 +1,113 @@
+import addPromiseListener from "add-promise-listener";
 import { assign, dedent } from "polyscript/exports";
 
+const { stringify } = JSON;
+
 const invoke = (name, args) => `${name}(code, ${args.join(", ")})`;
 
-export default (options = {}) => {
-    const type = options.type || "py";
-    const args = options.persistent
-        ? ["globals()", "__locals__"]
-        : ["{}", "{}"];
+const donkey = ({ type = "py", persistent, terminal, config }) => {
+    const args = persistent ? ["globals()", "__locals__"] : ["{}", "{}"];
+
     const src = URL.createObjectURL(
         new Blob([
-            dedent(`
-                from pyscript import sync, config
-                __message__ = lambda e,v: f"\x1b[31m\x1b[1m{e.__name__}\x1b[0m: {v}"
-                __locals__ = {}
-                if config["type"] == "py":
-                    import sys
-                    def __error__(_):
-                        info = sys.exc_info()
-                        return __message__(info[0], info[1])
-                else:
-                    __error__ = lambda e: __message__(e.__class__, e.value)
-                def execute(code):
-                    try: return ${invoke("exec", args)};
-                    except Exception as e: print(__error__(e));
-                def evaluate(code):
-                    try: return ${invoke("eval", args)};
-                    except Exception as e: print(__error__(e));
-                sync.execute = execute
-                sync.evaluate = evaluate
-            `),
+            [
+                // this array is to better minify this code once in production
+                "from pyscript import sync, config",
+                '__message__ = lambda e,v: f"\x1b[31m\x1b[1m{e.__name__}\x1b[0m: {v}"',
+                "__locals__ = {}",
+                'if config["type"] == "py":',
+                "	import sys",
+                "	def __error__(_):",
+                "		info = sys.exc_info()",
+                "		return __message__(info[0], info[1])",
+                "else:",
+                "	__error__ = lambda e: __message__(e.__class__, e.value)",
+                "def execute(code):",
+                `	try: return ${invoke("exec", args)};`,
+                "	except Exception as e: print(__error__(e));",
+                "def evaluate(code):",
+                `	try: return ${invoke("eval", args)};`,
+                "	except Exception as e: print(__error__(e));",
+                "sync.execute = execute",
+                "sync.evaluate = evaluate",
+            ].join("\n"),
         ]),
     );
 
+    // create the script that exposes the code to execute or evaluate
     const script = assign(document.createElement("script"), { type, src });
-
     script.toggleAttribute("worker", true);
     script.toggleAttribute("terminal", true);
-    if (options.terminal) script.setAttribute("target", options.terminal);
-    if (options.config)
-        script.setAttribute("config", JSON.stringify(options.config));
+    if (terminal) script.setAttribute("target", terminal);
+    if (config) {
+        script.setAttribute(
+            "config",
+            typeof config === "string" ? config : stringify(config),
+        );
+    }
 
-    return new Promise((resolve) => {
-        script.addEventListener(`${type}:done`, (event) => {
-            event.stopPropagation();
+    return addPromiseListener(
+        document.body.appendChild(script),
+        `${type}:done`,
+        { stopPropagation: true },
+    ).then(() => {
         URL.revokeObjectURL(src);
+        return script;
+    });
+};
+
+const utils = async (options) => {
+    const script = await donkey(options);
     const { xworker, process, terminal } = script;
     const { execute, evaluate } = xworker.sync;
     script.remove();
-            resolve({
+    return {
+        xworker,
         process,
-                execute: (code) => execute(dedent(code)),
-                evaluate: (code) => evaluate(dedent(code)),
-                clear: () => terminal.clear(),
-                reset: () => terminal.reset(),
-                kill: () => {
-                    xworker.terminate();
-                    terminal.dispose();
-                },
-            });
-        });
-        document.body.append(script);
-    });
+        terminal,
+        execute,
+        evaluate,
+    };
+};
+
+export default async (options = {}) => {
+    let farmer = await utils(options);
+    let working = false;
+    const kill = () => {
+        if (farmer) {
+            farmer.xworker.terminate();
+            farmer.terminal.dispose();
+            farmer = null;
+        }
+        working = false;
+    };
+    const reload = async () => {
+        kill();
+        farmer = await utils(options);
+    };
+    const asyncTask = (method) => async (code) => {
+        // race condition ... a new task has been
+        // assigned while the previous one didn't finish
+        if (working) await reload();
+        working = true;
+        try {
+            return await farmer[method](dedent(code));
+        } catch (e) {
+            console.error(e);
+        } finally {
+            working = false;
+        }
+    };
+    const asyncMethod = (method) => async () => {
+        if (working) await reload();
+        else farmer?.terminal[method]();
+    };
+    return {
+        process: asyncTask("process"),
+        execute: asyncTask("execute"),
+        evaluate: asyncTask("evaluate"),
+        clear: asyncMethod("clear"),
+        reset: asyncMethod("reset"),
+        kill,
+    };
 };

core/src/plugins/error.js

@@ -1,6 +1,12 @@
 // PyScript Error Plugin
+import { buffered } from "polyscript/exports";
 import { hooks } from "../core.js";
 
+let dontBotherDOM = false;
+export function notOnDOM() {
+    dontBotherDOM = true;
+}
+
 hooks.main.onReady.add(function override(pyScript) {
     // be sure this override happens only once
     hooks.main.onReady.delete(override);
@@ -8,13 +14,15 @@ hooks.main.onReady.add(function override(pyScript) {
     // trap generic `stderr` to propagate to it regardless
     const { stderr } = pyScript.io;
 
-    // override it with our own logic
-    pyScript.io.stderr = (error, ...rest) => {
+    const cb = (error, ...rest) => {
         notify(error.message || error);
         // let other plugins or stderr hook, if any, do the rest
         return stderr(error, ...rest);
     };
 
+    // override it with our own logic
+    pyScript.io.stderr = pyScript.type === "py" ? cb : buffered(cb);
+
     // be sure uncaught Python errors are also visible
     addEventListener("error", ({ message }) => {
         if (message.startsWith("Uncaught PythonError")) notify(message);
@@ -30,6 +38,7 @@ hooks.main.onReady.add(function override(pyScript) {
  * @param {string} message
  */
 export function notify(message) {
+    if (dontBotherDOM) return;
     const div = document.createElement("div");
     div.className = "py-error";
     div.textContent = message;

core/src/stdlib/pyscript.js

@@ -1,9 +1,9 @@
 // ⚠️ This file is an artifact: DO NOT MODIFY
 export default {
   "pyscript": {
-    "__init__.py": "from polyscript import lazy_py_modules as py_import\nfrom pyscript.display import HTML,display\nfrom pyscript.fetch import fetch\nfrom pyscript.magic_js import RUNNING_IN_WORKER,PyWorker,config,current_target,document,js_import,js_modules,sync,window\nfrom pyscript.storage import Storage,storage\nfrom pyscript.websocket import WebSocket\nif not RUNNING_IN_WORKER:from pyscript.workers import create_named_worker,workers\ntry:from pyscript.event_handling import when\nexcept:from pyscript.util import NotSupported;when=NotSupported('pyscript.when','pyscript.when currently not available with this interpreter')",
+    "__init__.py": "from polyscript import lazy_py_modules as py_import\nfrom pyscript.event_handling import when\nfrom pyscript.display import HTML,display\nfrom pyscript.fetch import fetch\nfrom pyscript.magic_js import RUNNING_IN_WORKER,PyWorker,config,current_target,document,js_import,js_modules,sync,window\nfrom pyscript.storage import Storage,storage\nfrom pyscript.websocket import WebSocket\nif not RUNNING_IN_WORKER:from pyscript.workers import create_named_worker,workers",
     "display.py": "_L='_repr_mimebundle_'\n_K='image/svg+xml'\n_J='application/json'\n_I='__repr__'\n_H='savefig'\n_G='text/html'\n_F='image/jpeg'\n_E='application/javascript'\n_D='utf-8'\n_C='text/plain'\n_B='image/png'\n_A=None\nimport base64,html,io,re\nfrom pyscript.magic_js import current_target,document,window\n_MIME_METHODS={_H:_B,'_repr_javascript_':_E,'_repr_json_':_J,'_repr_latex':'text/latex','_repr_png_':_B,'_repr_jpeg_':_F,'_repr_pdf_':'application/pdf','_repr_svg_':_K,'_repr_markdown_':'text/markdown','_repr_html_':_G,_I:_C}\ndef _render_image(mime,value,meta):\n\tA=value\n\tif isinstance(A,bytes):A=base64.b64encode(A).decode(_D)\n\tB=re.compile('^([A-Za-z0-9+/]{4})*([A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}==)?$')\n\tif len(A)>0 and not B.match(A):A=base64.b64encode(A.encode(_D)).decode(_D)\n\tC=f\"data:{mime};charset=utf-8;base64,{A}\";D=' '.join(['{k}=\"{v}\"'for(A,B)in meta.items()]);return f'<img src=\"{C}\" {D}></img>'\ndef _identity(value,meta):return value\n_MIME_RENDERERS={_C:html.escape,_G:_identity,_B:lambda value,meta:_render_image(_B,value,meta),_F:lambda value,meta:_render_image(_F,value,meta),_K:_identity,_J:_identity,_E:lambda value,meta:f\"<script>{value}<\\\\/script>\"}\nclass HTML:\n\tdef __init__(A,html):A._html=html\n\tdef _repr_html_(A):return A._html\ndef _eval_formatter(obj,print_method):\n\tB=obj;A=print_method\n\tif A==_I:return repr(B)\n\telif hasattr(B,A):\n\t\tif A==_H:C=io.BytesIO();B.savefig(C,format='png');C.seek(0);return base64.b64encode(C.read()).decode(_D)\n\t\treturn getattr(B,A)()\n\telif A==_L:return{},{}\ndef _format_mime(obj):\n\tC=obj\n\tif isinstance(C,str):return html.escape(C),_C\n\tD=_eval_formatter(C,_L)\n\tif isinstance(D,tuple):E,I=D\n\telse:E=D\n\tA,F=_A,[]\n\tfor(H,B)in _MIME_METHODS.items():\n\t\tif B in E:A=E[B]\n\t\telse:A=_eval_formatter(C,H)\n\t\tif A is _A:continue\n\t\telif B not in _MIME_RENDERERS:F.append(B);continue\n\t\tbreak\n\tif A is _A:\n\t\tif F:window.console.warn(f\"Rendered object requested unavailable MIME renderers: {F}\")\n\t\tA=repr(A);B=_C\n\telif isinstance(A,tuple):A,G=A\n\telse:G={}\n\treturn _MIME_RENDERERS[B](A,G),B\ndef _write(element,value,append=False):\n\tB=element;C,D=_format_mime(value)\n\tif C=='\\\\n':return\n\tif append:A=document.createElement('div');B.append(A)\n\telse:\n\t\tA=B.lastElementChild\n\t\tif A is _A:A=B\n\tif D in(_E,_G):E=document.createRange().createContextualFragment(C);A.append(E)\n\telse:A.innerHTML=C\ndef display(*D,target=_A,append=True):\n\tC=append;A=target\n\tif A is _A:A=current_target()\n\telif not isinstance(A,str):raise TypeError(f\"target must be str or None, not {A.__class__.__name__}\")\n\telif A=='':raise ValueError('Cannot have an empty target')\n\telif A.startswith('#'):A=A[1:]\n\tB=document.getElementById(A)\n\tif B is _A:raise ValueError(f\"Invalid selector with id={A}. Cannot be found in the page.\")\n\tif B.tagName=='SCRIPT'and hasattr(B,'target'):B=B.target\n\tfor E in D:\n\t\tif not C:B.replaceChildren()\n\t\t_write(B,E,append=C)",
-    "event_handling.py": "import inspect\ntry:from pyodide.ffi.wrappers import add_event_listener\nexcept ImportError:\n\tdef add_event_listener(el,event_type,func):el.addEventListener(event_type,func)\nfrom pyscript.magic_js import document\ndef when(event_type=None,selector=None):\n\tA=selector\n\tdef B(func):\n\t\tB=func;from pyscript.web import Element as E,ElementCollection as F\n\t\tif isinstance(A,str):C=document.querySelectorAll(A)\n\t\telif isinstance(A,E):C=[A._dom_element]\n\t\telif isinstance(A,F):C=[A._dom_element for A in A]\n\t\telif isinstance(A,list):C=A\n\t\telse:C=[A]\n\t\ttry:\n\t\t\tG=inspect.signature(B)\n\t\t\tif not G.parameters:\n\t\t\t\tif inspect.iscoroutinefunction(B):\n\t\t\t\t\tasync def D(*A,**C):await B()\n\t\t\t\telse:\n\t\t\t\t\tdef D(*A,**C):B()\n\t\t\telse:D=B\n\t\texcept AttributeError:\n\t\t\tdef D(*C,**D):\n\t\t\t\ttry:return B(*C,**D)\n\t\t\t\texcept TypeError as A:\n\t\t\t\t\tif'takes'in str(A)and'positional arguments'in str(A):return B()\n\t\t\t\t\traise\n\t\tfor H in C:add_event_listener(H,event_type,D)\n\t\treturn B\n\treturn B",
+    "event_handling.py": "import inspect\ntry:from pyodide.ffi.wrappers import add_event_listener\nexcept ImportError:\n\tdef add_event_listener(el,event_type,func):el.addEventListener(event_type,func)\nfrom pyscript.magic_js import document\ndef when(target,*B,**C):\n\tI='handler';F=target;E=None\n\tif B and callable(B[0]):E=B[0];B=B[1:]\n\telif callable(C.get(I)):E=C.pop(I)\n\tG=hasattr(F,'__when__')\n\tif not G:\n\t\tif B:A=B[0]\n\t\telif C:A=C.get('selector')\n\t\tif not A:raise ValueError('No selector provided.')\n\t\tfrom pyscript.web import Element as J,ElementCollection as K\n\t\tif isinstance(A,str):D=document.querySelectorAll(A)\n\t\telif isinstance(A,J):D=[A._dom_element]\n\t\telif isinstance(A,K):D=[A._dom_element for A in A]\n\t\telif isinstance(A,list):D=A\n\t\telse:D=[A]\n\tdef H(func):\n\t\tA=func\n\t\ttry:\n\t\t\tH=inspect.signature(A)\n\t\t\tif not H.parameters:\n\t\t\t\tif inspect.iscoroutinefunction(A):\n\t\t\t\t\tasync def E(*B,**C):await A()\n\t\t\t\telse:\n\t\t\t\t\tdef E(*B,**C):A()\n\t\t\telse:E=A\n\t\texcept AttributeError:\n\t\t\tdef E(*C,**D):\n\t\t\t\ttry:return A(*C,**D)\n\t\t\t\texcept TypeError as B:\n\t\t\t\t\tif'takes'in str(B)and'positional arguments'in str(B):return A()\n\t\t\t\t\traise\n\t\tif G:F.__when__(E,*B,**C)\n\t\telse:\n\t\t\tfor I in D:add_event_listener(I,F,E)\n\t\treturn A\n\tif E:H(E)\n\telse:return H",
     "fetch.py": "import json,js\nfrom pyscript.util import as_bytearray\nclass _Response:\n\tdef __init__(A,response):A._response=response\n\tdef __getattr__(A,attr):return getattr(A._response,attr)\n\tasync def arrayBuffer(B):\n\t\tA=await B._response.arrayBuffer()\n\t\tif hasattr(A,'to_py'):return A.to_py()\n\t\treturn memoryview(as_bytearray(A))\n\tasync def blob(A):return await A._response.blob()\n\tasync def bytearray(A):B=await A._response.arrayBuffer();return as_bytearray(B)\n\tasync def json(A):return json.loads(await A.text())\n\tasync def text(A):return await A._response.text()\nclass _DirectResponse:\n\t@staticmethod\n\tdef setup(promise,response):A=promise;A._response=_Response(response);return A._response\n\tdef __init__(B,promise):A=promise;B._promise=A;A._response=None;A.arrayBuffer=B.arrayBuffer;A.blob=B.blob;A.bytearray=B.bytearray;A.json=B.json;A.text=B.text\n\tasync def _response(A):\n\t\tif not A._promise._response:await A._promise\n\t\treturn A._promise._response\n\tasync def arrayBuffer(A):B=await A._response();return await B.arrayBuffer()\n\tasync def blob(A):B=await A._response();return await B.blob()\n\tasync def bytearray(A):B=await A._response();return await B.bytearray()\n\tasync def json(A):B=await A._response();return await B.json()\n\tasync def text(A):B=await A._response();return await B.text()\ndef fetch(url,**B):C=js.JSON.parse(json.dumps(B));D=lambda response,*B:_DirectResponse.setup(A,response);A=js.fetch(url,C).then(D);_DirectResponse(A);return A",
     "ffi.py": "try:\n\timport js;from pyodide.ffi import create_proxy as _cp,to_js as _py_tjs;from_entries=js.Object.fromEntries\n\tdef _tjs(value,**A):\n\t\tB='dict_converter'\n\t\tif not hasattr(A,B):A[B]=from_entries\n\t\treturn _py_tjs(value,**A)\nexcept:from jsffi import create_proxy as _cp;from jsffi import to_js as _tjs\ncreate_proxy=_cp\nto_js=_tjs",
     "flatted.py": "import json as _json\nclass _Known:\n\tdef __init__(A):A.key=[];A.value=[]\nclass _String:\n\tdef __init__(A,value):A.value=value\ndef _array_keys(value):\n\tA=[];B=0\n\tfor C in value:A.append(B);B+=1\n\treturn A\ndef _object_keys(value):\n\tA=[]\n\tfor B in value:A.append(B)\n\treturn A\ndef _is_array(value):A=value;return isinstance(A,list)or isinstance(A,tuple)\ndef _is_object(value):return isinstance(value,dict)\ndef _is_string(value):return isinstance(value,str)\ndef _index(known,input,value):B=value;A=known;input.append(B);C=str(len(input)-1);A.key.append(B);A.value.append(C);return C\ndef _loop(keys,input,known,output):\n\tA=output\n\tfor B in keys:\n\t\tC=A[B]\n\t\tif isinstance(C,_String):_ref(B,input[int(C.value)],input,known,A)\n\treturn A\ndef _ref(key,value,input,known,output):\n\tB=known;A=value\n\tif _is_array(A)and not A in B:B.append(A);A=_loop(_array_keys(A),input,B,A)\n\telif _is_object(A)and not A in B:B.append(A);A=_loop(_object_keys(A),input,B,A)\n\toutput[key]=A\ndef _relate(known,input,value):\n\tB=known;A=value\n\tif _is_string(A)or _is_array(A)or _is_object(A):\n\t\ttry:return B.value[B.key.index(A)]\n\t\texcept:return _index(B,input,A)\n\treturn A\ndef _transform(known,input,value):\n\tB=known;A=value\n\tif _is_array(A):\n\t\tC=[]\n\t\tfor F in A:C.append(_relate(B,input,F))\n\t\treturn C\n\tif _is_object(A):\n\t\tD={}\n\t\tfor E in A:D[E]=_relate(B,input,A[E])\n\t\treturn D\n\treturn A\ndef _wrap(value):\n\tA=value\n\tif _is_string(A):return _String(A)\n\tif _is_array(A):\n\t\tB=0\n\t\tfor D in A:A[B]=_wrap(D);B+=1\n\telif _is_object(A):\n\t\tfor C in A:A[C]=_wrap(A[C])\n\treturn A\ndef parse(value,*C,**D):\n\tA=value;E=_json.loads(A,*C,**D);B=[]\n\tfor A in E:B.append(_wrap(A))\n\tinput=[]\n\tfor A in B:\n\t\tif isinstance(A,_String):input.append(A.value)\n\t\telse:input.append(A)\n\tA=input[0]\n\tif _is_array(A):return _loop(_array_keys(A),input,[A],A)\n\tif _is_object(A):return _loop(_object_keys(A),input,[A],A)\n\treturn A\ndef stringify(value,*D,**E):\n\tB=_Known();input=[];C=[];A=int(_index(B,input,value))\n\twhile A<len(input):C.append(_transform(B,input,input[A]));A+=1\n\treturn _json.dumps(C,*D,**E)",

core/src/stdlib/pyscript/__init__.py

@@ -30,6 +30,7 @@
 #     as it works transparently in both the main thread and worker cases.
 
 from polyscript import lazy_py_modules as py_import
+from pyscript.event_handling import when
 from pyscript.display import HTML, display
 from pyscript.fetch import fetch
 from pyscript.magic_js import (
@@ -48,14 +49,3 @@ from pyscript.websocket import WebSocket
 
 if not RUNNING_IN_WORKER:
     from pyscript.workers import create_named_worker, workers
-
-try:
-    from pyscript.event_handling import when
-except:
-    # TODO: should we remove this? Or at the very least, we should capture
-    # the traceback otherwise it's very hard to debug
-    from pyscript.util import NotSupported
-
-    when = NotSupported(
-        "pyscript.when", "pyscript.when currently not available with this interpreter"
-    )

core/src/stdlib/pyscript/event_handling.py

@@ -12,14 +12,42 @@ except ImportError:
 from pyscript.magic_js import document
 
 
-def when(event_type=None, selector=None):
+def when(target, *args, **kwargs):
     """
-    Decorates a function and passes py-* events to the decorated function
-    The events might or not be an argument of the decorated function
+    A decorator and function for attaching event handlers to DOM elements or
+    whenable objects.
+
+    When used as a decorator, the target is the object that will trigger the
+    event. The handler function is the decorated function. The handler function
+    will be called when the target is triggered.
+
+    When used as a function, the target is the object that will trigger the
+    event. The handler function is the next argument. The remaining arguments
+    and keyword arguments are passed to the target when it is triggered.
     """
+    # If "when" is called as a function, try to grab the handler from the
+    # arguments. If there's no handler, this must be a decorator based call.
+    handler = None
+    if args and callable(args[0]):
+        handler = args[0]
+        args = args[1:]
+    elif callable(kwargs.get("handler")):
+        handler = kwargs.pop("handler")
 
-    def decorator(func):
-
+    # Does the target implement the when protocol?
+    whenable = hasattr(target, "__when__")
+    # If not when-able, the DOM selector for the target event.
+    if not whenable:
+        # The target is an event linked to a DOM selector. Extract the
+        # selector from the arguments or keyword arguments.
+        if args:
+            selector = args[0]
+        elif kwargs:
+            selector = kwargs.get("selector")
+        if not selector:
+            # There must be a selector if the target is not when-able.
+            raise ValueError("No selector provided.")
+        # Grab the DOM elements to which the target event will be attached.
         from pyscript.web import Element, ElementCollection
 
         if isinstance(selector, str):
@@ -36,11 +64,11 @@ def when(event_type=None, selector=None):
             else:
                 elements = [selector]
 
+    def decorator(func):
         try:
             sig = inspect.signature(func)
             # Function doesn't receive events
             if not sig.parameters:
-
                 # Function is async: must be awaited
                 if inspect.iscoroutinefunction(func):
 
@@ -54,7 +82,6 @@ def when(event_type=None, selector=None):
 
             else:
                 wrapper = func
-
         except AttributeError:
             # TODO: this is very ugly hack to get micropython working because inspect.signature
             #       doesn't exist, but we need to actually properly replace inspect.signature.
@@ -68,9 +95,15 @@ def when(event_type=None, selector=None):
 
                     raise
 
+        if whenable:
+            target.__when__(wrapper, *args, **kwargs)
+        else:
             for el in elements:
-            add_event_listener(el, event_type, wrapper)
+                add_event_listener(el, target, wrapper)
 
         return func
 
+    if handler:
+        decorator(handler)
+    else:
         return decorator

core/tests/index.html

@@ -14,5 +14,5 @@
             a:hover { opacity: 1; }
         </style>
     </head>
-    <body><ul><li><strong><span>javascript</span></strong><ul><li><a href="./javascript/async-listener.html">async-listener<small>.html</small></a></li><li><a href="./javascript/config-url.html">config-url<small>.html</small></a></li><li><a href="./javascript/config_type.html">config_type<small>.html</small></a></li><li><strong><a href="./javascript/fetch/index.html">fetch</a></strong></li><li><a href="./javascript/ffi.html">ffi<small>.html</small></a></li><li><a href="./javascript/hooks.html">hooks<small>.html</small></a></li><li><strong><a href="./javascript/issue-2093/index.html">issue-2093</a></strong></li><li><a href="./javascript/js-storage.html">js-storage<small>.html</small></a></li><li><a href="./javascript/js_modules.html">js_modules<small>.html</small></a></li><li><strong><a href="./javascript/loader/index.html">loader</a></strong></li><li><a href="./javascript/mpy.html">mpy<small>.html</small></a></li><li><a href="./javascript/py-terminal-main.html">py-terminal-main<small>.html</small></a></li><li><a href="./javascript/py-terminal-worker.html">py-terminal-worker<small>.html</small></a></li><li><a href="./javascript/py-terminal.html">py-terminal<small>.html</small></a></li><li><a href="./javascript/py-terminals.html">py-terminals<small>.html</small></a></li><li><strong><a href="./javascript/pyodide-cache/index.html">pyodide-cache</a></strong></li><li><a href="./javascript/storage.html">storage<small>.html</small></a></li><li><strong><span>workers</span></strong><ul><li><strong><a href="./javascript/workers/create_named/index.html">create_named</a></strong></li><li><strong><a href="./javascript/workers/mpy/index.html">mpy</a></strong></li><li><strong><a href="./javascript/workers/py/index.html">py</a></strong></li></ul></li></ul></li><li><strong><a href="./manual/index.html">manual</a></strong><ul><li><a href="./manual/all-done.html">all-done<small>.html</small></a></li><li><a href="./manual/async.html">async<small>.html</small></a></li><li><a href="./manual/camera.html">camera<small>.html</small></a></li><li><a href="./manual/click.html">click<small>.html</small></a></li><li><a href="./manual/code-a-part.html">code-a-part<small>.html</small></a></li><li><a href="./manual/combo.html">combo<small>.html</small></a></li><li><a href="./manual/config.html">config<small>.html</small></a></li><li><a href="./manual/create-element.html">create-element<small>.html</small></a></li><li><a href="./manual/dialog.html">dialog<small>.html</small></a></li><li><a href="./manual/display.html">display<small>.html</small></a></li><li><strong><a href="./manual/donkey/index.html">donkey</a></strong></li><li><a href="./manual/error.html">error<small>.html</small></a></li><li><a href="./manual/html-decode.html">html-decode<small>.html</small></a></li><li><a href="./manual/input.html">input<small>.html</small></a></li><li><a href="./manual/interpreter.html">interpreter<small>.html</small></a></li><li><strong><a href="./manual/issue-7015/index.html">issue-7015</a></strong></li><li><a href="./manual/multi.html">multi<small>.html</small></a></li><li><a href="./manual/multiple-editors.html">multiple-editors<small>.html</small></a></li><li><a href="./manual/no-error.html">no-error<small>.html</small></a></li><li><strong><a href="./manual/no_sab/index.html">no_sab</a></strong></li><li><strong><a href="./manual/piratical/index.html">piratical</a></strong></li><li><a href="./manual/py-editor.html">py-editor<small>.html</small></a></li><li><a href="./manual/py-editor-failure.html">py-editor-failure<small>.html</small></a></li><li><strong><a href="./manual/py-terminals/index.html">py-terminals</a></strong><ul><li><a href="./manual/py-terminals/no-repl.html">no-repl<small>.html</small></a></li><li><a href="./manual/py-terminals/repl.html">repl<small>.html</small></a></li></ul></li><li><a href="./manual/py_modules.html">py_modules<small>.html</small></a></li><li><strong><a href="./manual/service-worker/index.html">service-worker</a></strong></li><li><a href="./manual/split-config.html">split-config<small>.html</small></a></li><li><a href="./manual/submit.html">submit<small>.html</small></a></li><li><a href="./manual/target.html">target<small>.html</small></a></li><li><a href="./manual/test_display_HTML.html">test_display_HTML<small>.html</small></a></li><li><a href="./manual/test_when.html">test_when<small>.html</small></a></li><li><a href="./manual/worker.html">worker<small>.html</small></a></li></ul></li><li><strong><a href="./python/index.html">python</a></strong></li></ul></body>
+    <body><ul><li><strong><span>javascript</span></strong><ul><li><a href="./javascript/async-listener.html">async-listener<small>.html</small></a></li><li><a href="./javascript/config-url.html">config-url<small>.html</small></a></li><li><a href="./javascript/config_type.html">config_type<small>.html</small></a></li><li><strong><a href="./javascript/fetch/index.html">fetch</a></strong></li><li><a href="./javascript/ffi.html">ffi<small>.html</small></a></li><li><a href="./javascript/hooks.html">hooks<small>.html</small></a></li><li><strong><a href="./javascript/issue-2093/index.html">issue-2093</a></strong></li><li><a href="./javascript/js-storage.html">js-storage<small>.html</small></a></li><li><a href="./javascript/js_modules.html">js_modules<small>.html</small></a></li><li><strong><a href="./javascript/loader/index.html">loader</a></strong></li><li><a href="./javascript/mpy-error.html">mpy-error<small>.html</small></a></li><li><a href="./javascript/mpy-no-error.html">mpy-no-error<small>.html</small></a></li><li><a href="./javascript/mpy.html">mpy<small>.html</small></a></li><li><a href="./javascript/py-terminal-main.html">py-terminal-main<small>.html</small></a></li><li><a href="./javascript/py-terminal-worker.html">py-terminal-worker<small>.html</small></a></li><li><a href="./javascript/py-terminal.html">py-terminal<small>.html</small></a></li><li><a href="./javascript/py-terminals.html">py-terminals<small>.html</small></a></li><li><strong><a href="./javascript/pyodide-cache/index.html">pyodide-cache</a></strong></li><li><a href="./javascript/storage.html">storage<small>.html</small></a></li><li><strong><span>workers</span></strong><ul><li><strong><a href="./javascript/workers/create_named/index.html">create_named</a></strong></li><li><strong><a href="./javascript/workers/mpy/index.html">mpy</a></strong></li><li><strong><a href="./javascript/workers/py/index.html">py</a></strong></li></ul></li></ul></li><li><strong><a href="./manual/index.html">manual</a></strong><ul><li><a href="./manual/all-done.html">all-done<small>.html</small></a></li><li><a href="./manual/async.html">async<small>.html</small></a></li><li><a href="./manual/camera.html">camera<small>.html</small></a></li><li><a href="./manual/click.html">click<small>.html</small></a></li><li><a href="./manual/code-a-part.html">code-a-part<small>.html</small></a></li><li><a href="./manual/combo.html">combo<small>.html</small></a></li><li><a href="./manual/config.html">config<small>.html</small></a></li><li><a href="./manual/create-element.html">create-element<small>.html</small></a></li><li><a href="./manual/dialog.html">dialog<small>.html</small></a></li><li><a href="./manual/display.html">display<small>.html</small></a></li><li><strong><a href="./manual/donkey/index.html">donkey</a></strong></li><li><a href="./manual/error.html">error<small>.html</small></a></li><li><a href="./manual/html-decode.html">html-decode<small>.html</small></a></li><li><a href="./manual/input.html">input<small>.html</small></a></li><li><a href="./manual/interpreter.html">interpreter<small>.html</small></a></li><li><strong><a href="./manual/issue-7015/index.html">issue-7015</a></strong></li><li><a href="./manual/multi.html">multi<small>.html</small></a></li><li><a href="./manual/multiple-editors.html">multiple-editors<small>.html</small></a></li><li><a href="./manual/no-error.html">no-error<small>.html</small></a></li><li><strong><a href="./manual/no_sab/index.html">no_sab</a></strong></li><li><strong><a href="./manual/piratical/index.html">piratical</a></strong></li><li><a href="./manual/py-editor.html">py-editor<small>.html</small></a></li><li><a href="./manual/py-editor-failure.html">py-editor-failure<small>.html</small></a></li><li><strong><a href="./manual/py-terminals/index.html">py-terminals</a></strong><ul><li><a href="./manual/py-terminals/no-repl.html">no-repl<small>.html</small></a></li><li><a href="./manual/py-terminals/repl.html">repl<small>.html</small></a></li></ul></li><li><a href="./manual/py_modules.html">py_modules<small>.html</small></a></li><li><strong><a href="./manual/service-worker/index.html">service-worker</a></strong></li><li><a href="./manual/split-config.html">split-config<small>.html</small></a></li><li><a href="./manual/submit.html">submit<small>.html</small></a></li><li><a href="./manual/target.html">target<small>.html</small></a></li><li><a href="./manual/test_display_HTML.html">test_display_HTML<small>.html</small></a></li><li><a href="./manual/test_when.html">test_when<small>.html</small></a></li><li><a href="./manual/worker.html">worker<small>.html</small></a></li></ul></li><li><strong><a href="./python/index.html">python</a></strong></li></ul></body>
 </html>

core/tests/javascript/mpy-error.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <script type="module" src="../../dist/core.js"></script>
+        <script type="mpy">
+            from pyscript import document
+            import sys
+            print("This is an error", file=sys.stderr)
+            document.documentElement.classList.add("ok");
+        </script>
+    </head>
+</html>

core/tests/javascript/mpy-no-error.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <script type="module" src="../../dist/core.js"></script>
+        <script type="mpy" config="mpy-no-error.toml">
+            from pyscript import document
+            import sys
+            print("This is an error", file=sys.stderr)
+            document.documentElement.classList.add("ok");
+        </script>
+    </head>
+</html>

core/tests/javascript/mpy-no-error.toml

@@ -0,0 +1 @@
+plugins = ["!error"]

core/tests/js_tests.spec.js

@@ -138,3 +138,17 @@ test('Pyodide lockFileURL vs CDN', async ({ page }) => {
   const body = await page.evaluate(() => document.body.textContent);
   await expect(body).toBe('OK');
 });
+
+test('MicroPython buffered error', async ({ page }) => {
+  await page.goto('http://localhost:8080/tests/javascript/mpy-error.html');
+  await page.waitForSelector('html.ok');
+  const body = await page.evaluate(() => document.body.textContent.trim());
+  await expect(body).toBe('This is an error');
+});
+
+test('MicroPython buffered NO error', async ({ page }) => {
+  await page.goto('http://localhost:8080/tests/javascript/mpy-no-error.html');
+  await page.waitForSelector('html.ok');
+  const body = await page.evaluate(() => document.body.textContent.trim());
+  await expect(body).toBe('');
+});

core/tests/manual/donkey/index.js

@@ -12,13 +12,23 @@ const {
   kill,
 } = await donkey({ terminal: '#container' });
 
-clearButton.onclick = clear;
-killButton.onclick = kill;
+clearButton.onclick = async () => {
+  killButton.disabled = true;
+  clearButton.disabled = true;
+  await clear();
+  runButton.disabled = false;
+};
+killButton.onclick = () => {
+  killButton.disabled = true;
+  clearButton.disabled = true;
+  runButton.disabled = true;
+  kill();
+};
 
 runButton.disabled = false;
 runButton.onclick = async () => {
   killButton.disabled = false;
-  clearButton.disabled = true;
+  clearButton.disabled = false;
   runButton.disabled = true;
   // multiline code
   await execute(`
@@ -29,6 +39,5 @@ runButton.onclick = async () => {
   const name = await evaluate('input("what is your name? ")');
   alert(`Hello ${name}`);
   killButton.disabled = true;
-  clearButton.disabled = false;
   runButton.disabled = false;
 };

core/tests/manual/error/index.html

@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PyScript Error Bug?</title>
+  <link rel="stylesheet" href="../../../dist/core.css">
+  <script type="module" src="../../../dist/core.js"></script>
+</head>
+<body>
+  <py-config>
+      plugins = ["!error"]
+  </py-config>
+  <script type="py">
+    import sys
+    print("This is normal content")
+    print("This is error content", file=sys.stderr)
+  </script>
+  <!-- Attempt 2; inline config
+  <script type="py" config='plugins=["!error"]'>
+    import sys
+    print("This is normal content")
+    print("This is error content", file=sys.stderr)
+  </script> -->
+  <!-- Attempt 3; external pyscript.toml
+  <script type="py" config="pyscript.toml">
+    import sys
+    print("This is normal content")
+    print("This is error content", file=sys.stderr)
+  </script> -->
+  <!-- Attempt 4; micropython
+  <script type="mpy">
+    import sys
+    print("This is normal content")
+    print("This is error content", file=sys.stderr)
+  </script> -->
+  <div id="result"></div>
+</body>
+</html>

core/tests/manual/error/pyscript.toml

@@ -0,0 +1 @@
+plugins = ["!error"]

core/tests/python/tests/test_when.py

@@ -214,3 +214,130 @@ def test_when_decorator_invalid_selector():
         def foo(evt): ...
 
     assert "'#.bad' is not a valid selector" in str(e.exception), str(e.exception)
+
+
+def test_when_decorates_a_whenable():
+    """
+    When the @when decorator is used on a function to handle a whenable object,
+    the function should be called when the whenable object is triggered.
+    """
+
+    class MyWhenable:
+        """
+        A simple whenable object that can be triggered.
+        """
+
+        def __init__(self):
+            self.handler = None
+            self.args = None
+            self.kwargs = None
+
+        def trigger(self):
+            """
+            Triggers the whenable object, resulting in the handler being
+            called.
+            """
+            if self.handler:
+                result = {
+                    "args": self.args,
+                    "kwargs": self.kwargs,
+                }
+                self.handler(result)  # call the handler
+
+        def __when__(self, handler, *args, **kwargs):
+            """
+            These implementation details depend on the sort of thing the
+            whenable object represents. This is just a simple example.
+            """
+            self.handler = handler
+            self.args = args
+            self.kwargs = kwargs
+
+    whenable = MyWhenable()
+    counter = 0
+
+    # When as a decorator.
+    @web.when(whenable, "foo", "bar", baz="qux")
+    def foo(result):
+        """
+        A function that should be called when the whenable object is triggered.
+
+        The result generated by the whenable object should be passed to the
+        function.
+        """
+        nonlocal counter
+        counter += 1
+        assert result["args"] == ("foo", "bar")
+        assert result["kwargs"] == {"baz": "qux"}
+
+    # The function should not be called until the whenable object is triggered.
+    assert counter == 0
+    # Trigger the whenable object.
+    whenable.trigger()
+    # The function should have been called when the whenable object was
+    # triggered.
+    assert counter == 1
+
+
+def test_when_called_with_a_whenable():
+    """
+    The when function should be able to be called with a whenable object,
+    a handler function, and arguments.
+    """
+
+    class MyWhenable:
+        """
+        A simple whenable object that can be triggered.
+        """
+
+        def __init__(self):
+            self.handler = None
+            self.args = None
+            self.kwargs = None
+
+        def trigger(self):
+            """
+            Triggers the whenable object, resulting in the handler being
+            called.
+            """
+            if self.handler:
+                result = {
+                    "args": self.args,
+                    "kwargs": self.kwargs,
+                }
+                self.handler(result)  # call the handler
+
+        def __when__(self, handler, *args, **kwargs):
+            """
+            These implementation details depend on the sort of thing the
+            whenable object represents. This is just a simple example.
+            """
+            self.handler = handler
+            self.args = args
+            self.kwargs = kwargs
+
+    whenable = MyWhenable()
+    counter = 0
+
+    def handler(result):
+        """
+        A function that should be called when the whenable object is triggered.
+
+        The result generated by the whenable object should be passed to the
+        function.
+        """
+        nonlocal counter
+        counter += 1
+        assert result["args"] == ("foo", "bar")
+        assert result["kwargs"] == {"baz": "qux"}
+
+    # When as a function.
+    web.when(whenable, handler, "foo", "bar", baz="qux")
+
+    # The function should not be called until the whenable object is triggered.
+    assert counter == 0
+    # Trigger the whenable object.
+    whenable.trigger()
+    # The function should have been called when the whenable object was
+    # triggered.
+    assert counter == 1

core/types/core.d.ts

@@ -1,4 +1,11 @@
-export function donkey(options: any): Promise<any>;
+export function donkey(options: any): Promise<{
+    process: (code: any) => Promise<any>;
+    execute: (code: any) => Promise<any>;
+    evaluate: (code: any) => Promise<any>;
+    clear: () => Promise<void>;
+    reset: () => Promise<void>;
+    kill: () => void;
+}>;
 export function offline_interpreter(config: any): string;
 import { stdlib } from "./stdlib.js";
 import { optional } from "./stdlib.js";

core/types/plugins/donkey.d.ts

@@ -1,2 +1,9 @@
-declare function _default(options?: {}): Promise<any>;
+declare function _default(options?: {}): Promise<{
+    process: (code: any) => Promise<any>;
+    execute: (code: any) => Promise<any>;
+    evaluate: (code: any) => Promise<any>;
+    clear: () => Promise<void>;
+    reset: () => Promise<void>;
+    kill: () => void;
+}>;
 export default _default;

core/types/plugins/error.d.ts

@@ -1,3 +1,4 @@
+export function notOnDOM(): void;
 /**
  * Add a banner to the top of the page, notifying the user of an error
  * @param {string} message