@pyscript/core 0.0.1 → 0.0.3

package/README.md

@@ -19,7 +19,7 @@ This project requires some automatic artifact creation to:
 
     * create a _Worker_ as a _Blob_ based on the same code used by this repo
     * create automatically the list of runtimes available via the module
-    * create the `min.js` file used by most integration tests
+    * create the `core.js` file used by most integration tests
     * create a sha256 version of the Blob content for CSP cases
 
 Accordingly, to build latest project:

package/cjs/custom/pyscript/exceptions.js

@@ -0,0 +1,86 @@
+'use strict';
+const CLOSEBUTTON = `<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill="currentColor" width="12px"><path d='M.293.293a1 1 0 011.414 0L8 6.586 14.293.293a1 1 0 111.414 1.414L9.414 8l6.293 6.293a1 1 0 01-1.414 1.414L8 9.414l-6.293 6.293a1 1 0 01-1.414-1.414L6.586 8 .293 1.707a1 1 0 010-1.414z'/></svg>`;
+
+/**
+ * These error codes are used to identify the type of error that occurred.
+ * @see https://docs.pyscript.net/latest/reference/exceptions.html?highlight=errors
+ */
+const ErrorCode = {
+    GENERIC: "PY0000", // Use this only for development then change to a more specific error code
+    FETCH_ERROR: "PY0001",
+    FETCH_NAME_ERROR: "PY0002",
+    // Currently these are created depending on error code received from fetching
+    FETCH_UNAUTHORIZED_ERROR: "PY0401",
+    FETCH_FORBIDDEN_ERROR: "PY0403",
+    FETCH_NOT_FOUND_ERROR: "PY0404",
+    FETCH_SERVER_ERROR: "PY0500",
+    FETCH_UNAVAILABLE_ERROR: "PY0503",
+    BAD_CONFIG: "PY1000",
+    MICROPIP_INSTALL_ERROR: "PY1001",
+    BAD_PLUGIN_FILE_EXTENSION: "PY2000",
+    NO_DEFAULT_EXPORT: "PY2001",
+    TOP_LEVEL_AWAIT: "PY9000",
+};
+exports.ErrorCode = ErrorCode;
+
+class UserError extends Error {
+    constructor(errorCode, message = "", messageType = "text") {
+        super(`(${errorCode}): ${message}`);
+        this.errorCode = errorCode;
+        this.messageType = messageType;
+        this.name = "UserError";
+    }
+}
+exports.UserError = UserError
+
+class FetchError extends UserError {
+    constructor(errorCode, message) {
+        super(errorCode, message);
+        this.name = "FetchError";
+    }
+}
+exports.FetchError = FetchError
+
+class InstallError extends UserError {
+    constructor(errorCode, message) {
+        super(errorCode, message);
+        this.name = "InstallError";
+    }
+}
+exports.InstallError = InstallError
+
+function _createAlertBanner(
+    message,
+    level,
+    messageType = "text",
+    logMessage = true,
+) {
+    switch (`log-${level}-${logMessage}`) {
+        case "log-error-true":
+            console.error(message);
+            break;
+        case "log-warning-true":
+            console.warn(message);
+            break;
+    }
+
+    const content = messageType === "html" ? "innerHTML" : "textContent";
+    const banner = Object.assign(document.createElement("div"), {
+        className: `alert-banner py-${level}`,
+        [content]: message,
+    });
+
+    if (level === "warning") {
+        const closeButton = Object.assign(document.createElement("button"), {
+            id: "alert-close-button",
+            innerHTML: CLOSEBUTTON,
+        });
+
+        banner.appendChild(closeButton).addEventListener("click", () => {
+            banner.remove();
+        });
+    }
+
+    document.body.prepend(banner);
+}
+exports._createAlertBanner = _createAlertBanner

package/cjs/custom/pyscript/fetch.js

@@ -0,0 +1,65 @@
+'use strict';
+const { FetchError, ErrorCode } = require("./exceptions");
+
+/**
+ * This is a fetch wrapper that handles any non 200 responses and throws a
+ * FetchError with the right ErrorCode. This is useful because our FetchError
+ * will automatically create an alert banner.
+ *
+ * @param {string} url - URL to fetch
+ * @param {Request} [options] - options to pass to fetch
+ * @returns {Promise<Response>}
+ */
+async function robustFetch(url, options) {
+    let response;
+
+    // Note: We need to wrap fetch into a try/catch block because fetch
+    // throws a TypeError if the URL is invalid such as http://blah.blah
+    try {
+        response = await fetch(url, options);
+    } catch (err) {
+        const error = err;
+        let errMsg;
+        if (url.startsWith("http")) {
+            errMsg =
+                `Fetching from URL ${url} failed with error ` +
+                `'${error.message}'. Are your filename and path correct?`;
+        } else {
+            errMsg = `PyScript: Access to local files
+        (using [[fetch]] configurations in &lt;py-config&gt;)
+        is not available when directly opening a HTML file;
+        you must use a webserver to serve the additional files.
+        See <a style="text-decoration: underline;" href="https://github.com/pyscript/pyscript/issues/257#issuecomment-1119595062">this reference</a>
+        on starting a simple webserver with Python.
+            `;
+        }
+        throw new FetchError(ErrorCode.FETCH_ERROR, errMsg);
+    }
+
+    // Note that response.ok is true for 200-299 responses
+    if (!response.ok) {
+        const errorMsg = `Fetching from URL ${url} failed with error ${response.status} (${response.statusText}). Are your filename and path correct?`;
+        switch (response.status) {
+            case 404:
+                throw new FetchError(ErrorCode.FETCH_NOT_FOUND_ERROR, errorMsg);
+            case 401:
+                throw new FetchError(
+                    ErrorCode.FETCH_UNAUTHORIZED_ERROR,
+                    errorMsg,
+                );
+            case 403:
+                throw new FetchError(ErrorCode.FETCH_FORBIDDEN_ERROR, errorMsg);
+            case 500:
+                throw new FetchError(ErrorCode.FETCH_SERVER_ERROR, errorMsg);
+            case 503:
+                throw new FetchError(
+                    ErrorCode.FETCH_UNAVAILABLE_ERROR,
+                    errorMsg,
+                );
+            default:
+                throw new FetchError(ErrorCode.FETCH_ERROR, errorMsg);
+        }
+    }
+    return response;
+}
+exports.robustFetch = robustFetch

package/cjs/custom/pyscript.js

@@ -0,0 +1,197 @@
+'use strict';
+require("@ungap/with-resolvers");
+const { $ } = require("basic-devtools");
+
+const { define } = require("../index.js");
+const { queryTarget } = require("../script-handler.js");
+const { defineProperty } = require("../utils.js");
+const { getText } = require("../fetch-utils.js");
+
+// TODO: should this utility be in core instead?
+const { robustFetch: fetch } = require("./pyscript/fetch.js");
+
+// append ASAP CSS to avoid showing content
+document.head.appendChild(document.createElement("style")).textContent = `
+  py-script, py-config {
+    display: none;
+  }
+`;
+
+(async () => {
+    // create a unique identifier when/if needed
+    let id = 0;
+    const getID = (prefix = "py") => `${prefix}-${id++}`;
+
+    // find the shared config for all py-script elements
+    let config;
+    let pyConfig = $("py-config");
+    if (pyConfig) config = pyConfig.getAttribute("src") || pyConfig.textContent;
+    else {
+        pyConfig = $('script[type="py"]');
+        config = pyConfig?.getAttribute("config");
+    }
+
+    if (/^https?:\/\//.test(config)) config = await fetch(config).then(getText);
+
+    // generic helper to disambiguate between custom element and script
+    const isScript = (element) => element.tagName === "SCRIPT";
+
+    // helper for all script[type="py"] out there
+    const before = (script) => {
+        defineProperty(document, "currentScript", {
+            configurable: true,
+            get: () => script,
+        });
+    };
+
+    const after = () => {
+        delete document.currentScript;
+    };
+
+    /**
+     * Given a generic DOM Element, tries to fetch the 'src' attribute, if present.
+     * It either throws an error if the 'src' can't be fetched or it returns a fallback
+     * content as source.
+     */
+    const fetchSource = async (tag) => {
+        if (tag.hasAttribute("src")) {
+            try {
+                const response = await fetch(tag.getAttribute("src"));
+                return response.then(getText);
+            } catch (error) {
+                // TODO _createAlertBanner(err) instead ?
+                alert(error.message);
+                throw error;
+            }
+        }
+        return tag.textContent;
+    };
+
+    // common life-cycle handlers for any node
+    const bootstrapNodeAndPlugins = (pyodide, element, callback, hook) => {
+        if (isScript(element)) callback(element);
+        for (const fn of hooks[hook]) fn(pyodide, element);
+    };
+
+    const addDisplay = (element) => {
+        const id = isScript(element) ? element.target.id : element.id;
+        return `
+            # this code is just for demo purpose but the basics work
+            def _display(what, target="${id}", append=True):
+                from js import document
+                element = document.getElementById(target)
+                element.textContent = what
+            display = _display
+        `;
+    };
+
+    // define the module as both `<script type="py">` and `<py-script>`
+    define("py", {
+        config,
+        env: "py-script",
+        interpreter: "pyodide",
+        codeBeforeRunWorker() {
+            const { codeBeforeRunWorker: set } = hooks;
+            const prefix = 'print("codeBeforeRunWorker")';
+            return [prefix].concat(...set).join("\n");
+        },
+        codeAfterRunWorker() {
+            const { codeAfterRunWorker: set } = hooks;
+            const prefix = 'print("codeAfterRunWorker")';
+            return [prefix].concat(...set).join("\n");
+        },
+        onBeforeRun(pyodide, element) {
+            bootstrapNodeAndPlugins(pyodide, element, before, "onBeforeRun");
+            pyodide.interpreter.runPython(addDisplay(element));
+        },
+        onBeforeRunAync(pyodide, element) {
+            pyodide.interpreter.runPython(addDisplay(element));
+            bootstrapNodeAndPlugins(
+                pyodide,
+                element,
+                before,
+                "onBeforeRunAync",
+            );
+        },
+        onAfterRun(pyodide, element) {
+            bootstrapNodeAndPlugins(pyodide, element, after, "onAfterRun");
+        },
+        onAfterRunAsync(pyodide, element) {
+            bootstrapNodeAndPlugins(pyodide, element, after, "onAfterRunAsync");
+        },
+        async onRuntimeReady(pyodide, element) {
+            // allows plugins to do whatever they want with the element
+            // before regular stuff happens in here
+            for (const callback of hooks.onRuntimeReady)
+                callback(pyodide, element);
+            if (isScript(element)) {
+                const {
+                    attributes: { async: isAsync, target },
+                } = element;
+                const hasTarget = !!target?.value;
+                const show = hasTarget
+                    ? queryTarget(target.value)
+                    : document.createElement("script-py");
+
+                if (!hasTarget) element.after(show);
+                if (!show.id) show.id = getID();
+
+                // allows the code to retrieve the target element via
+                // document.currentScript.target if needed
+                defineProperty(element, "target", { value: show });
+
+                pyodide[`run${isAsync ? "Async" : ""}`](
+                    await fetchSource(element),
+                );
+            } else {
+                // resolve PyScriptElement to allow connectedCallback
+                element._pyodide.resolve(pyodide);
+            }
+        },
+    });
+
+    class PyScriptElement extends HTMLElement {
+        constructor() {
+            if (!super().id) this.id = getID();
+            this._pyodide = Promise.withResolvers();
+            this.srcCode = "";
+            this.executed = false;
+        }
+        async connectedCallback() {
+            if (!this.executed) {
+                this.executed = true;
+                const { run } = await this._pyodide.promise;
+                this.srcCode = await fetchSource(this);
+                this.textContent = "";
+                const result = run(this.srcCode);
+                if (!this.textContent && result) this.textContent = result;
+                this.style.display = "block";
+            }
+        }
+    }
+
+    customElements.define("py-script", PyScriptElement);
+})();
+
+const hooks = {
+    /** @type {Set<function>} */
+    onBeforeRun: new Set(),
+    /** @type {Set<function>} */
+    onBeforeRunAync: new Set(),
+    /** @type {Set<function>} */
+    onAfterRun: new Set(),
+    /** @type {Set<function>} */
+    onAfterRunAsync: new Set(),
+    /** @type {Set<function>} */
+    onRuntimeReady: new Set(),
+
+    /** @type {Set<string>} */
+    codeBeforeRunWorker: new Set(),
+    /** @type {Set<string>} */
+    codeBeforeRunWorkerAsync: new Set(),
+    /** @type {Set<string>} */
+    codeAfterRunWorker: new Set(),
+    /** @type {Set<string>} */
+    codeAfterRunWorkerAsync: new Set(),
+};
+exports.hooks = hooks;

package/cjs/custom.js

@@ -0,0 +1,193 @@
+'use strict';
+require("@ungap/with-resolvers");
+const { $$ } = require("basic-devtools");
+
+const { assign, create } = require("./utils.js");
+const { getDetails } = require("./script-handler.js");
+const {
+    registry: defaultRegistry,
+    prefixes,
+    configs
+} = require("./interpreters.js");
+const { getRuntimeID } = require("./loader.js");
+const { io } = require("./interpreter/_utils.js");
+const { addAllListeners } = require("./listeners.js");
+const { Hook } = require("./worker/hooks.js");
+
+const CUSTOM_SELECTORS = [];
+exports.CUSTOM_SELECTORS = CUSTOM_SELECTORS;
+
+/**
+ * @typedef {Object} Runtime custom configuration
+ * @prop {object} interpreter the bootstrapped interpreter
+ * @prop {(url:string, options?: object) => Worker} XWorker an XWorker constructor that defaults to same interpreter on the Worker.
+ * @prop {object} config a cloned config used to bootstrap the interpreter
+ * @prop {(code:string) => any} run an utility to run code within the interpreter
+ * @prop {(code:string) => Promise<any>} runAsync an utility to run code asynchronously within the interpreter
+ * @prop {(path:string, data:ArrayBuffer) => void} writeFile an utility to write a file in the virtual FS, if available
+ */
+
+const types = new Map();
+const waitList = new Map();
+
+// REQUIRES INTEGRATION TEST
+/* c8 ignore start */
+/**
+ * @param {Element} node any DOM element registered via define.
+ */
+const handleCustomType = (node) => {
+    for (const selector of CUSTOM_SELECTORS) {
+        if (node.matches(selector)) {
+            const type = types.get(selector);
+            const { resolve } = waitList.get(type);
+            const { options, known } = registry.get(type);
+            if (!known.has(node)) {
+                known.add(node);
+                const {
+                    interpreter: runtime,
+                    version,
+                    config,
+                    env,
+                    onRuntimeReady,
+                } = options;
+                const name = getRuntimeID(runtime, version);
+                const id = env || `${name}${config ? `|${config}` : ""}`;
+                const { interpreter: engine, XWorker: Worker } = getDetails(
+                    runtime,
+                    id,
+                    name,
+                    version,
+                    config,
+                );
+                engine.then((interpreter) => {
+                    const module = create(defaultRegistry.get(runtime));
+
+                    const {
+                        onBeforeRun,
+                        onBeforeRunAsync,
+                        onAfterRun,
+                        onAfterRunAsync,
+                    } = options;
+
+                    const hooks = new Hook(options);
+
+                    const XWorker = function XWorker(...args) {
+                        return Worker.apply(hooks, args);
+                    };
+
+                    // These two loops mimic a `new Map(arrayContent)` without needing
+                    // the new Map overhead so that [name, [before, after]] can be easily destructured
+                    // and new sync or async patches become easy to add (when the logic is the same).
+
+                    // patch sync
+                    for (const [name, [before, after]] of [
+                        ["run", [onBeforeRun, onAfterRun]],
+                    ]) {
+                        const method = module[name];
+                        module[name] = function (interpreter, code) {
+                            if (before) before.call(this, resolved, node);
+                            const result = method.call(this, interpreter, code);
+                            if (after) after.call(this, resolved, node);
+                            return result;
+                        };
+                    }
+
+                    // patch async
+                    for (const [name, [before, after]] of [
+                        ["runAsync", [onBeforeRunAsync, onAfterRunAsync]],
+                    ]) {
+                        const method = module[name];
+                        module[name] = async function (interpreter, code) {
+                            if (before) await before.call(this, resolved, node);
+                            const result = await method.call(
+                                this,
+                                interpreter,
+                                code,
+                            );
+                            if (after) await after.call(this, resolved, node);
+                            return result;
+                        };
+                    }
+
+                    module.setGlobal(interpreter, "XWorker", XWorker);
+
+                    const resolved = {
+                        type,
+                        interpreter,
+                        XWorker,
+                        io: io.get(interpreter),
+                        config: structuredClone(configs.get(name)),
+                        run: module.run.bind(module, interpreter),
+                        runAsync: module.runAsync.bind(module, interpreter),
+                    };
+
+                    resolve(resolved);
+
+                    onRuntimeReady?.(resolved, node);
+                });
+            }
+        }
+    }
+};
+exports.handleCustomType = handleCustomType;
+
+/**
+ * @type {Map<string, {options:object, known:WeakSet<Element>}>}
+ */
+const registry = new Map();
+
+/**
+ * @typedef {Object} PluginOptions custom configuration
+ * @prop {'pyodide' | 'micropython' | 'wasmoon' | 'ruby-wasm-wasi'} interpreter the interpreter to use
+ * @prop {string} [version] the optional interpreter version to use
+ * @prop {string} [config] the optional config to use within such interpreter
+ * @prop {(environment: object, node: Element) => void} [onRuntimeReady] the callback that will be invoked once
+ */
+
+/**
+ * Allows custom types and components on the page to receive interpreters to execute any code
+ * @param {string} type the unique `<script type="...">` identifier
+ * @param {PluginOptions} options the custom type configuration
+ */
+const define = (type, options) => {
+    if (defaultRegistry.has(type) || registry.has(type))
+        throw new Error(`<script type="${type}"> already registered`);
+
+    if (!defaultRegistry.has(options?.interpreter))
+        throw new Error(`Unspecified interpreter`);
+
+    // allows reaching out the interpreter helpers on events
+    defaultRegistry.set(type, defaultRegistry.get(options?.interpreter));
+
+    // ensure a Promise can resolve once a custom type has been bootstrapped
+    whenDefined(type);
+
+    // allows selector -> registry by type
+    const selectors = [`script[type="${type}"]`, `${type}-script`];
+    for (const selector of selectors) types.set(selector, type);
+
+    CUSTOM_SELECTORS.push(...selectors);
+    prefixes.push(`${type}-`);
+
+    // ensure always same env for this custom type
+    registry.set(type, {
+        options: assign({ env: type }, options),
+        known: new WeakSet(),
+    });
+
+    addAllListeners(document);
+    $$(selectors.join(",")).forEach(handleCustomType);
+};
+exports.define = define;
+
+/**
+ * Resolves whenever a defined custom type is bootstrapped on the page
+ * @param {string} type the unique `<script type="...">` identifier
+ * @returns {Promise<object>}
+ */
+const whenDefined = (type) => {
+    if (!waitList.has(type)) waitList.set(type, Promise.withResolvers());
+    return waitList.get(type).promise;
+};
+exports.whenDefined = whenDefined;
+/* c8 ignore stop */

package/cjs/index.js

@@ -5,13 +5,13 @@ const xworker = (m => /* c8 ignore start */ m.__esModule ? m.default : m /* c8 i
 const { handle } = require("./script-handler.js");
 const { assign } = require("./utils.js");
 const { selectors, prefixes } = require("./interpreters.js");
-const { CUSTOM_SELECTORS, handleCustomType } = require("./custom-types.js");
+const { CUSTOM_SELECTORS, handleCustomType } = require("./custom.js");
 const { listener, addAllListeners } = require("./listeners.js");
 
 (m => {
   exports.define = m.define;
   exports.whenDefined = m.whenDefined;
-})(require("./custom-types.js"));
+})(require("./custom.js"));
 const XWorker = xworker();
 exports.XWorker = XWorker;
 

package/cjs/interpreter/_python.js

@@ -10,6 +10,14 @@ const runAsync = (interpreter, code) =>
     interpreter.runPythonAsync(clean(code));
 exports.runAsync = runAsync;
 
+const setGlobal = (interpreter, name, value) =>
+    interpreter.globals.set(name, value);
+exports.setGlobal = setGlobal;
+
+const deleteGlobal = (interpreter, name) =>
+    interpreter.globals.delete(name);
+exports.deleteGlobal = deleteGlobal;
+
 const writeFile = ({ FS }, path, buffer) =>
     writeFileUtil(FS, path, buffer);
 exports.writeFile = writeFile;

package/cjs/interpreter/micropython.js

@@ -1,6 +1,12 @@
 'use strict';
 const { fetchPaths, stdio } = require("./_utils.js");
-const { run, runAsync, writeFile } = require("./_python.js");
+const {
+    run,
+    runAsync,
+    setGlobal,
+    deleteGlobal,
+    writeFile
+} = require("./_python.js");
 
 const type = "micropython";
 
@@ -17,16 +23,8 @@ module.exports = {
         if (config.fetch) await fetchPaths(this, runtime, config.fetch);
         return runtime;
     },
-    setGlobal(interpreter, name, value) {
-        const id = `__pyscript_${this.type}_${name}`;
-        globalThis[id] = value;
-        this.run(interpreter, `from js import ${id};${name}=${id};`);
-    },
-    deleteGlobal(interpreter, name) {
-        const id = `__pyscript_${this.type}_${name}`;
-        this.run(interpreter, `del ${id};del ${name}`);
-        delete globalThis[id];
-    },
+    setGlobal,
+    deleteGlobal,
     run,
     runAsync,
     writeFile,

package/cjs/interpreter/pyodide.js

@@ -1,6 +1,12 @@
 'use strict';
 const { fetchPaths, stdio } = require("./_utils.js");
-const { run, runAsync, writeFile } = require("./_python.js");
+const {
+    run,
+    runAsync,
+    setGlobal,
+    deleteGlobal,
+    writeFile
+} = require("./_python.js");
 
 const type = "pyodide";
 
@@ -25,12 +31,8 @@ module.exports = {
         }
         return interpreter;
     },
-    setGlobal(interpreter, name, value) {
-        interpreter.globals.set(name, value);
-    },
-    deleteGlobal(interpreter, name) {
-        interpreter.globals.delete(name);
-    },
+    setGlobal,
+    deleteGlobal,
     run,
     runAsync,
     writeFile,

package/cjs/worker/class.js

@@ -4,7 +4,7 @@ const coincident = (m => /* c8 ignore start */ m.__esModule ? m.default : m /* c
 const xworker = (m => /* c8 ignore start */ m.__esModule ? m.default : m /* c8 ignore stop */)(require("./xworker.js"));
 const { assign, defineProperties, absoluteURL } = require("../utils.js");
 const { getText } = require("../fetch-utils.js");
-const workerHooks = (m => /* c8 ignore start */ m.__esModule ? m.default : m /* c8 ignore stop */)(require("./hooks.js"));
+const { Hook } = require("./hooks.js");
 
 /**
  * @typedef {Object} WorkerOptions custom configuration
@@ -21,7 +21,6 @@ module.exports = (...args) =>
      * @returns {Worker}
      */
     function XWorker(url, options) {
-        const hooks = workerHooks.get(XWorker);
         const worker = xworker();
         const { postMessage } = worker;
         if (args.length) {
@@ -32,7 +31,10 @@ module.exports = (...args) =>
         if (options?.config) options.config = absoluteURL(options.config);
         const bootstrap = fetch(url)
             .then(getText)
-            .then((code) => postMessage.call(worker, { options, code, hooks }));
+            .then((code) => {
+                const hooks = this instanceof Hook ? this : void 0;
+                postMessage.call(worker, { options, code, hooks });
+            });
         return defineProperties(worker, {
             postMessage: {
                 value: (data, ...rest) =>