pyscript · antocuni · Nov 9, 2022 · Nov 3, 2022 · Nov 3, 2022 · Nov 3, 2022
diff --git a/pyscriptjs/src/main.ts b/pyscriptjs/src/main.ts
@@ -3,6 +3,7 @@ import './styles/pyscript_base.css';
 import { loadConfigFromElement } from './pyconfig';
 import type { AppConfig } from './pyconfig';
 import type { Runtime } from './runtime';
+import { type Plugin, PluginManager } from './plugin';
 import { make_PyScript, initHandlers, mountElements } from './components/pyscript';
 import { PyLoader } from './components/pyloader';
 import { PyodideRuntime } from './pyodide';
@@ -11,6 +12,8 @@ import { handleFetchError, showWarning, globalExport } from './utils';
 import { calculatePaths } from './plugins/fetch';
 import { createCustomElements } from './components/elements';
 import { UserError, withUserErrorHandler } from "./exceptions"
+import { type Stdio, StdioMultiplexer, DEFAULT_STDIO } from './stdio';
+import { PyTerminalPlugin } from './plugins/pyterminal';
 
 type ImportType = { [key: string]: unknown };
 type ImportMapType = {
@@ -35,6 +38,8 @@ const logger = getLogger('pyscript/main');
 
    6. setup the environment, install packages
 
+   6.5: call the Plugin.afterSetup() hook
+
    7. connect the py-script web component. This causes the execution of all the
       user scripts
 
@@ -51,16 +56,33 @@ More concretely:
   - PyScriptApp.afterRuntimeLoad() implements all the points >= 5.
 */
 
-class PyScriptApp {
+
+
+export class PyScriptApp {
     config: AppConfig;
     loader: PyLoader;
     runtime: Runtime;
     PyScript: any; // XXX would be nice to have a more precise type for the class itself
+    plugins: PluginManager;
+    _stdioMultiplexer: StdioMultiplexer;
+
+    constructor() {
+        // initialize the builtin plugins
+        this.plugins = new PluginManager();
+        this.plugins.add(new PyTerminalPlugin(this));
+
+        this._stdioMultiplexer = new StdioMultiplexer();
+        this._stdioMultiplexer.addListener(DEFAULT_STDIO);
+    }
 
     // lifecycle (1)
     main() {
         this.loadConfig();
-        this.showLoader();
+        this.plugins.configure(this.config);
+
+        this.showLoader(); // this should be a plugin
+        this.plugins.beforeLaunch(this.config);
+
         this.loadRuntime();
     }
 
@@ -108,7 +130,11 @@ class PyScriptApp {
             showWarning('Multiple runtimes are not supported yet.<br />Only the first will be used');
         }
         const runtime_cfg = this.config.runtimes[0];
-        this.runtime = new PyodideRuntime(this.config, runtime_cfg.src, runtime_cfg.name, runtime_cfg.lang);
+        this.runtime = new PyodideRuntime(this.config,
+                                          this._stdioMultiplexer,
+                                          runtime_cfg.src,
+                                          runtime_cfg.name,
+                                          runtime_cfg.lang);
         this.loader.log(`Downloading ${runtime_cfg.name}...`);
         const script = document.createElement('script'); // create a script DOM node
         script.src = this.runtime.src;
@@ -138,6 +164,9 @@ class PyScriptApp {
         await this.setupVirtualEnv(runtime);
         await mountElements(runtime);
 
+        // lifecycle (6.5)
+        this.plugins.afterSetup(runtime);
+
         this.loader.log('Executing <py-script> tags...');
         this.executeScripts(runtime);
 
@@ -195,6 +224,12 @@ class PyScriptApp {
         customElements.define('py-script', this.PyScript);
     }
 
+    // ================= registraton API ====================
+
+    registerStdioListener(stdio: Stdio) {
+        this._stdioMultiplexer.addListener(stdio);
+    }
+
     async register_importmap(runtime: Runtime) {
         // make importmap ES modules available from python using 'import'.
         //

diff --git a/pyscriptjs/src/plugin.ts b/pyscriptjs/src/plugin.ts
@@ -0,0 +1,70 @@
+import type { PyScriptApp } from './main';
+import type { AppConfig } from './pyconfig';
+import type { Runtime } from './runtime';
+
+export class Plugin {
+
+    /** Validate the configuration of the plugin and handle default values.
+     *
+     * Individual plugins are expected to check that the config keys/sections
+     * which are relevant to them contains valid values, and to raise an error
+     * if they contains unknown keys.
+     *
+     * This is also a good place where set default values for those keys which
+     * are not specified by the user.
+     *
+     * This hook should **NOT** contain expensive operations, else it delays
+     * the download of the python interpreter which is initiated later.
+     */
+    configure(config: AppConfig) {
+    }
+
+    /** The preliminary initialization phase is complete and we are about to
+     * download and launch the Python interpreter.
+     *
+     * We can assume that the page is already shown to the user and that the
+     * DOM content has been loaded. This is a good place where to add tags to
+     * the DOM, if needed.
+     *
+     * This hook should **NOT** contain expensive operations, else it delays
+     * the download of the python interpreter which is initiated later.
+     */
+    beforeLaunch(config: AppConfig) {
+    }
+
+    /** The Python interpreter has been launched, the virtualenv has been
+      * installed and we are ready to execute user code.
+      *
+      * The <py-script> tags will be executed after this hook.
+      */
+    afterSetup(runtime: Runtime) {
+    }
+}
+
+
+export class PluginManager {
+    _plugins: Plugin[];
+
+    constructor() {
+        this._plugins = [];
+    }
+
+    add(p: Plugin) {
+        this._plugins.push(p);
+    }
+
+    configure(config: AppConfig) {
+        for (const p of this._plugins)
+            p.configure(config);
+    }
+
+    beforeLaunch(config: AppConfig) {
+        for (const p of this._plugins)
+            p.beforeLaunch(config);
+    }
+
+    afterSetup(runtime: Runtime) {
+        for (const p of this._plugins)
+            p.afterSetup(runtime);
+    }
+}
diff --git a/pyscriptjs/src/plugins/pyterminal.ts b/pyscriptjs/src/plugins/pyterminal.ts
@@ -0,0 +1,123 @@
+import type { PyScriptApp } from '../main';
+import type { AppConfig } from '../pyconfig';
+import { Plugin } from '../plugin';
+import { UserError } from "../exceptions"
+import { getLogger } from '../logger';
+import { type Stdio } from '../stdio';
+
+const logger = getLogger('py-terminal');
+
+export class PyTerminalPlugin extends Plugin {
+    app: PyScriptApp;
+
+    constructor(app: PyScriptApp) {
+        super();
+        this.app = app;
+    }
+
+    configure(config: AppConfig) {
+        // validate the terminal config and handle default values
+        const t = config.terminal;
+        if (t !== undefined &&
+            t !== true &&
+            t !== false &&
+            t !== "auto") {
+            const got = JSON.stringify(t);
+            throw new UserError('Invalid value for config.terminal: the only accepted'  +
+                                `values are true, false and "auto", got "${got}".`);
+        }
+        if (t === undefined) {
+            config.terminal = "auto"; // default value
+        }
+    }
+
+    beforeLaunch(config: AppConfig) {
+        // if config.terminal is "yes" or "auto", let's add a <py-terminal> to
+        // the document, unless it's already present.
+        const t = config.terminal;
+        if (t === true || t === "auto") {
+            if (document.querySelector('py-terminal') === null) {
+                logger.info("No <py-terminal> found, adding one");
+                const termElem = document.createElement('py-terminal');
+                if (t === "auto")
+                    termElem.setAttribute("auto", "");
+                document.body.appendChild(termElem);
+            }
+        }
+    }
+
+    afterSetup() {
+        // the Python interpreter has been initialized and we are ready to
+        // execute user code:
+        //
+        //   1. define the "py-terminal" custom element
+        //
+        //   2. if there is a <py-terminal> tag on the page, it will register
+        //      a Stdio listener just before the user code executes, ensuring
+        //      that we capture all the output
+        //
+        //   3. everything which was written to stdout BEFORE this moment will
+        //      NOT be shown on the py-terminal; in particular, pyodide
+        //      startup messages will not be shown (but they will go to the
+        //      console as usual). This is by design, else we would display
+        //      e.g. "Python initialization complete" on every page, which we
+        //      don't want.
+        //
+        //   4. (in the future we might want to add an option to start the
+        //      capture earlier, but I don't think it's important now).
+        const PyTerminal = make_PyTerminal(this.app);
+        customElements.define('py-terminal', PyTerminal);
+    }
+}
+
+
+function make_PyTerminal(app: PyScriptApp) {
+
+    /** The <py-terminal> custom element, which automatically register a stdio
+     *  listener to capture and display stdout/stderr
+     */
+    class PyTerminal extends HTMLElement implements Stdio {
+        outElem: HTMLElement;
+        autoShowOnNextLine: boolean;
+
+        connectedCallback() {
+            // should we use a shadowRoot instead? It looks unnecessarily
+            // complicated to me, but I'm not really sure about the
+            // implications
+            this.outElem = document.createElement('pre');
+            this.outElem.className = 'py-terminal';
+            this.appendChild(this.outElem);
+
+            if (this.isAuto()) {
+                this.classList.add('py-terminal-hidden');
+                this.autoShowOnNextLine = true;
+            }
+            else {
+                this.autoShowOnNextLine = false;
+            }
+
+            logger.info('Registering stdio listener');
+            app.registerStdioListener(this);
+        }
+
+        isAuto() {
+            return this.hasAttribute("auto");
+        }
+
+        // implementation of the Stdio interface
+        stdout_writeline(msg: string) {
+            this.outElem.innerText += msg + "\n";
+            if (this.autoShowOnNextLine) {
+                this.classList.remove('py-terminal-hidden');
+                this.autoShowOnNextLine = false;
+            }
+        }
+
+        stderr_writeline(msg: string) {
+            this.stdout_writeline(msg);
+        }
+        // end of the Stdio interface
+    }
+
+    return PyTerminal;
+}
diff --git a/pyscriptjs/src/pyodide.ts b/pyscriptjs/src/pyodide.ts
@@ -5,6 +5,7 @@ import type { loadPyodide as loadPyodideDeclaration, PyodideInterface, PyProxy }
 // @ts-ignore
 import pyscript from './python/pyscript.py';
 import type { AppConfig } from './pyconfig';
+import type { Stdio } from './stdio';
 
 declare const loadPyodide: typeof loadPyodideDeclaration;
 
@@ -17,19 +18,22 @@ interface Micropip {
 
 export class PyodideRuntime extends Runtime {
     src: string;
+    stdio: Stdio;
     name?: string;
     lang?: string;
     interpreter: PyodideInterface;
     globals: PyProxy;
 
     constructor(
         config: AppConfig,
+        stdio: Stdio,
         src = 'https://cdn.jsdelivr.net/pyodide/v0.21.3/full/pyodide.js',
         name = 'pyodide-default',
         lang = 'python',
     ) {
         logger.info('Runtime config:', { name, lang, src });
         super(config);
+        this.stdio = stdio;
         this.src = src;
         this.name = name;
         this.lang = lang;
@@ -54,8 +58,8 @@ export class PyodideRuntime extends Runtime {
     async loadInterpreter(): Promise<void> {
         logger.info('Loading pyodide');
         this.interpreter = await loadPyodide({
-            stdout: console.log,
-            stderr: console.log,
+            stdout: (msg: string) => { this.stdio.stdout_writeline(msg); },
+            stderr: (msg: string) => { this.stdio.stderr_writeline(msg); },
             fullStdLib: false,
         });
 

diff --git a/pyscriptjs/src/stdio.ts b/pyscriptjs/src/stdio.ts
@@ -0,0 +1,61 @@
+export interface Stdio {
+    stdout_writeline: (msg: string) => void;
+    stderr_writeline: (msg: string) => void;
+}
+
+/** Default implementation of Stdio: stdout and stderr are both sent to the
+ *  console
+ */
+export const DEFAULT_STDIO: Stdio = {
+    stdout_writeline: console.log,
+    stderr_writeline: console.log
+}
+
+/** Stdio provider which captures and store the messages.
+ *  Useful for tests.
+ */
+export class CaptureStdio implements Stdio {
+    captured_stdout: string;
+    captured_stderr: string;
+
+    constructor() {
+        this.reset();
+    }
+
+    reset() {
+        this.captured_stdout = "";
+        this.captured_stderr = "";
+    }
+
+    stdout_writeline(msg: string) {
+        this.captured_stdout += msg + "\n";
+    }
+
+    stderr_writeline(msg: string) {
+        this.captured_stderr += msg + "\n";
+    }
+}
+
+/** Redirect stdio streams to multiple listeners
+ */
+export class StdioMultiplexer implements Stdio {
+    _listeners: Stdio[];
+
+    constructor() {
+        this._listeners = [];
+    }
+
+    addListener(obj: Stdio) {
+        this._listeners.push(obj);
+    }
+
+    stdout_writeline(msg: string) {
+        for(const obj of this._listeners)
+            obj.stdout_writeline(msg);
+    }
+
+    stderr_writeline(msg: string) {
+        for(const obj of this._listeners)
+            obj.stderr_writeline(msg);
+    }
+}