@pyscript/core 0.2.1 → 0.2.3

package/dist/error-e4fe78fd.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-e4fe78fd.js","sources":["../src/plugins/error.js"],"sourcesContent":["// PyScript Error Plugin\nimport { hooks } from \"../core.js\";\n\nhooks.onInterpreterReady.add(function override(pyScript) {\n    // be sure this override happens only once\n    hooks.onInterpreterReady.delete(override);\n\n    // trap generic `stderr` to propagate to it regardless\n    const { stderr } = pyScript.io;\n\n    // override it with our own logic\n    pyScript.io.stderr = (error, ...rest) => {\n        notify(error.message || error);\n        // let other plugins or stderr hook, if any, do the rest\n        return stderr(error, ...rest);\n    };\n\n    // be sure uncaught Python errors are also visible\n    addEventListener(\"error\", ({ message }) => {\n        if (message.startsWith(\"Uncaught PythonError\")) notify(message);\n    });\n});\n\n// Error hook utilities\n\n// Custom function to show notifications\nexport function notify(message) {\n    const div = document.createElement(\"div\");\n    div.className = \"py-error\";\n    div.textContent = message;\n    div.style.cssText = `\n    border: 1px solid red;\n    background: #ffdddd;\n    color: black;\n    font-family: courier, monospace;\n    white-space: pre;\n    overflow-x: auto;\n    padding: 8px;\n    margin-top: 8px;\n  `;\n    document.body.append(div);\n}\n"],"names":["notify","message","div","document","createElement","className","textContent","style","cssText","body","append","hooks","onInterpreterReady","add","override","pyScript","delete","stderr","io","error","rest","addEventListener","startsWith"],"mappings":"kCA0BO,SAASA,EAAOC,GACnB,MAAMC,EAAMC,SAASC,cAAc,OACnCF,EAAIG,UAAY,WAChBH,EAAII,YAAcL,EAClBC,EAAIK,MAAMC,QAAU,6MAUpBL,SAASM,KAAKC,OAAOR,EACzB,CAtCAS,EAAMC,mBAAmBC,KAAI,SAASC,EAASC,GAE3CJ,EAAMC,mBAAmBI,OAAOF,GAGhC,MAAMG,OAAEA,GAAWF,EAASG,GAG5BH,EAASG,GAAGD,OAAS,CAACE,KAAUC,KAC5BpB,EAAOmB,EAAMlB,SAAWkB,GAEjBF,EAAOE,KAAUC,IAI5BC,iBAAiB,SAAS,EAAGpB,cACrBA,EAAQqB,WAAW,yBAAyBtB,EAAOC,EAAQ,GAEvE"}
+{"version":3,"file":"error-e4fe78fd.js","sources":["../src/plugins/error.js"],"sourcesContent":["// PyScript Error Plugin\nimport { hooks } from \"../core.js\";\n\nhooks.onInterpreterReady.add(function override(pyScript) {\n    // be sure this override happens only once\n    hooks.onInterpreterReady.delete(override);\n\n    // trap generic `stderr` to propagate to it regardless\n    const { stderr } = pyScript.io;\n\n    // override it with our own logic\n    pyScript.io.stderr = (error, ...rest) => {\n        notify(error.message || error);\n        // let other plugins or stderr hook, if any, do the rest\n        return stderr(error, ...rest);\n    };\n\n    // be sure uncaught Python errors are also visible\n    addEventListener(\"error\", ({ message }) => {\n        if (message.startsWith(\"Uncaught PythonError\")) notify(message);\n    });\n});\n\n// Error hook utilities\n\n// Custom function to show notifications\n\n/**\n * Add a banner to the top of the page, notifying the user of an error\n * @param {string} message\n */\nexport function notify(message) {\n    const div = document.createElement(\"div\");\n    div.className = \"py-error\";\n    div.textContent = message;\n    div.style.cssText = `\n    border: 1px solid red;\n    background: #ffdddd;\n    color: black;\n    font-family: courier, monospace;\n    white-space: pre;\n    overflow-x: auto;\n    padding: 8px;\n    margin-top: 8px;\n  `;\n    document.body.append(div);\n}\n"],"names":["notify","message","div","document","createElement","className","textContent","style","cssText","body","append","hooks","onInterpreterReady","add","override","pyScript","delete","stderr","io","error","rest","addEventListener","startsWith"],"mappings":"kCA+BO,SAASA,EAAOC,GACnB,MAAMC,EAAMC,SAASC,cAAc,OACnCF,EAAIG,UAAY,WAChBH,EAAII,YAAcL,EAClBC,EAAIK,MAAMC,QAAU,6MAUpBL,SAASM,KAAKC,OAAOR,EACzB,CA3CAS,EAAMC,mBAAmBC,KAAI,SAASC,EAASC,GAE3CJ,EAAMC,mBAAmBI,OAAOF,GAGhC,MAAMG,OAAEA,GAAWF,EAASG,GAG5BH,EAASG,GAAGD,OAAS,CAACE,KAAUC,KAC5BpB,EAAOmB,EAAMlB,SAAWkB,GAEjBF,EAAOE,KAAUC,IAI5BC,iBAAiB,SAAS,EAAGpB,cACrBA,EAAQqB,WAAW,yBAAyBtB,EAAOC,EAAQ,GAEvE"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@pyscript/core",
-    "version": "0.2.1",
+    "version": "0.2.3",
     "type": "module",
     "description": "PyScript",
     "module": "./index.js",
@@ -38,7 +38,7 @@
     "devDependencies": {
         "@rollup/plugin-node-resolve": "^15.2.1",
         "@rollup/plugin-terser": "^0.4.3",
-        "rollup": "^3.29.2",
+        "rollup": "^3.29.3",
         "rollup-plugin-postcss": "^4.0.2",
         "rollup-plugin-string": "^3.0.0",
         "static-handler": "^0.4.2",

package/src/config.js

@@ -5,6 +5,7 @@
  */
 import { $ } from "basic-devtools";
 
+import TYPES from "./types.js";
 import allPlugins from "./plugins.js";
 import { robustFetch as fetch, getText } from "./fetch.js";
 import { ErrorCode } from "./exceptions.js";
@@ -19,9 +20,10 @@ const badURL = (url, expected = "") => {
  * Given a string, returns its trimmed content as text,
  * fetching it from a file if the content is a URL.
  * @param {string} config either JSON, TOML, or a file to fetch
+ * @param {string?} type the optional type to enforce
  * @returns {{json: boolean, toml: boolean, text: string}}
  */
-const configDetails = async (config) => {
+const configDetails = async (config, type) => {
     let text = config?.trim();
     // we only support an object as root config
     let url = "",
@@ -45,66 +47,81 @@ const syntaxError = (type, url, { message }) => {
     return new SyntaxError(`${str}\n${message}`);
 };
 
-// find the shared config for all py-script elements
-let config, plugins, parsed, error, type;
-let pyConfig = $("py-config");
-if (pyConfig) {
-    config = pyConfig.getAttribute("src") || pyConfig.textContent;
-    type = pyConfig.getAttribute("type");
-} else {
-    pyConfig = $(
-        [
-            'script[type="py"][config]:not([worker])',
-            "py-script[config]:not([worker])",
-        ].join(","),
-    );
-    if (pyConfig) config = pyConfig.getAttribute("config");
-}
+const configs = new Map();
 
-// catch possible fetch errors
-if (config) {
-    try {
-        const { json, toml, text, url } = await configDetails(config);
-        config = text;
-        if (json || type === "json") {
-            try {
-                parsed = JSON.parse(text);
-            } catch (e) {
-                error = syntaxError("JSON", url, e);
-            }
-        } else if (toml || type === "toml") {
-            try {
-                const { parse } = await import(
-                    /* webpackIgnore: true */
-                    "https://cdn.jsdelivr.net/npm/@webreflection/toml-j0.4/toml.js"
-                );
-                parsed = parse(text);
-            } catch (e) {
-                error = syntaxError("TOML", url, e);
+for (const [TYPE] of TYPES) {
+    /** @type {Promise<any> | undefined} A Promise wrapping any plugins which should be loaded. */
+    let plugins;
+
+    /** @type {any} The PyScript configuration parsed from the JSON or TOML object*. May be any of the return types of JSON.parse() or toml-j0.4's parse() ( {number | string | boolean | null | object | Array} ) */
+    let parsed;
+
+    /** @type {SyntaxError | undefined} The error thrown when parsing the PyScript config, if any.*/
+    let error;
+
+    let config,
+        type,
+        pyConfig = $(`${TYPE}-config`);
+    if (pyConfig) {
+        config = pyConfig.getAttribute("src") || pyConfig.textContent;
+        type = pyConfig.getAttribute("type");
+    } else {
+        pyConfig = $(
+            [
+                `script[type="${TYPE}"][config]:not([worker])`,
+                `${TYPE}-script[config]:not([worker])`,
+            ].join(","),
+        );
+        if (pyConfig) config = pyConfig.getAttribute("config");
+    }
+
+    // catch possible fetch errors
+    if (config) {
+        try {
+            const { json, toml, text, url } = await configDetails(config, type);
+            config = text;
+            if (json || type === "json") {
+                try {
+                    parsed = JSON.parse(text);
+                } catch (e) {
+                    error = syntaxError("JSON", url, e);
+                }
+            } else if (toml || type === "toml") {
+                try {
+                    const { parse } = await import(
+                        /* webpackIgnore: true */
+                        "https://cdn.jsdelivr.net/npm/@webreflection/toml-j0.4/toml.js"
+                    );
+                    parsed = parse(text);
+                } catch (e) {
+                    error = syntaxError("TOML", url, e);
+                }
             }
+        } catch (e) {
+            error = e;
         }
-    } catch (e) {
-        error = e;
     }
-}
 
-// parse all plugins and optionally ignore only
-// those flagged as "undesired" via `!` prefix
-const toBeAwaited = [];
-for (const [key, value] of Object.entries(allPlugins)) {
-    if (error) {
-        if (key === "error") {
-            // show on page the config is broken, meaning that
-            // it was not possible to disable error plugin neither
-            // as that part wasn't correctly parsed anyway
-            value().then(({ notify }) => notify(error.message));
+    // parse all plugins and optionally ignore only
+    // those flagged as "undesired" via `!` prefix
+    const toBeAwaited = [];
+    for (const [key, value] of Object.entries(allPlugins)) {
+        if (error) {
+            if (key === "error") {
+                // show on page the config is broken, meaning that
+                // it was not possible to disable error plugin neither
+                // as that part wasn't correctly parsed anyway
+                value().then(({ notify }) => notify(error.message));
+            }
+        } else if (!parsed?.plugins?.includes(`!${key}`)) {
+            toBeAwaited.push(value());
         }
-    } else if (!parsed?.plugins?.includes(`!${key}`)) {
-        toBeAwaited.push(value());
     }
-}
 
-// assign plugins as Promise.all only if needed
-if (toBeAwaited.length) plugins = Promise.all(toBeAwaited);
+    // assign plugins as Promise.all only if needed
+    if (toBeAwaited.length) plugins = Promise.all(toBeAwaited);
+
+    configs.set(TYPE, { config: parsed, plugins, error });
+}
 
-export { parsed as config, plugins, error };
+export default configs;

package/src/core.js

@@ -9,10 +9,11 @@ import { queryTarget } from "../node_modules/polyscript/esm/script-handler.js";
 import { dedent, dispatch } from "../node_modules/polyscript/esm/utils.js";
 import { Hook } from "../node_modules/polyscript/esm/worker/hooks.js";
 
-import { ErrorCode } from "./exceptions.js";
+import TYPES from "./types.js";
+import configs from "./config.js";
 import sync from "./sync.js";
 import stdlib from "./stdlib.js";
-import { config, plugins, error } from "./config.js";
+import { ErrorCode } from "./exceptions.js";
 import { robustFetch as fetch, getText } from "./fetch.js";
 
 const { assign, defineProperty } = Object;
@@ -20,11 +21,6 @@ const { assign, defineProperty } = Object;
 // allows lazy element features on code evaluation
 let currentElement;
 
-const TYPES = new Map([
-    ["py", "pyodide"],
-    ["mpy", "micropython"],
-]);
-
 // generic helper to disambiguate between custom element and script
 const isScript = ({ tagName }) => tagName === "SCRIPT";
 
@@ -103,7 +99,12 @@ const workerHooks = {
         [...hooks.codeAfterRunWorkerAsync].map(dedent).join("\n"),
 };
 
+const exportedConfig = {};
+export { exportedConfig as config };
+
 for (const [TYPE, interpreter] of TYPES) {
+    const { config, plugins, error } = configs.get(TYPE);
+
     // create a unique identifier when/if needed
     let id = 0;
     const getID = (prefix = TYPE) => `${prefix}-${id++}`;
@@ -273,6 +274,9 @@ for (const [TYPE, interpreter] of TYPES) {
 
     // define py-script only if the config didn't throw an error
     if (!error) customElements.define(`${TYPE}-script`, PyScriptElement);
+
+    // export the used config without allowing leaks through it
+    exportedConfig[TYPE] = structuredClone(config);
 }
 
 // TBD: I think manual worker cases are interesting in pyodide only

package/src/exceptions.js

@@ -23,7 +23,17 @@ export const ErrorCode = {
     FETCH_UNAVAILABLE_ERROR: "PY0503",
 };
 
+/**
+ * Keys of the ErrorCode object
+ * @typedef {keyof ErrorCode} ErrorCodes
+ * */
+
 export class UserError extends Error {
+    /**
+     * @param {ErrorCodes} errorCode
+     * @param {string} message
+     * @param {string} messageType
+     * */
     constructor(errorCode, message = "", messageType = "text") {
         super(`(${errorCode}): ${message}`);
         this.errorCode = errorCode;
@@ -33,6 +43,10 @@ export class UserError extends Error {
 }
 
 export class FetchError extends UserError {
+    /**
+     * @param {ErrorCodes} errorCode
+     * @param {string} message
+     * */
     constructor(errorCode, message) {
         super(errorCode, message);
         this.name = "FetchError";
@@ -40,12 +54,23 @@ export class FetchError extends UserError {
 }
 
 export class InstallError extends UserError {
+    /**
+     * @param {ErrorCodes} errorCode
+     * @param {string} message
+     * */
     constructor(errorCode, message) {
         super(errorCode, message);
         this.name = "InstallError";
     }
 }
 
+/**
+ * Internal function for creating alert banners on the page
+ * @param {string} message The message to be displayed to the user
+ * @param {string} level The alert level of the message. Can be any string; 'error' or 'warning' cause matching messages to be emitted to the console
+ * @param {string} [messageType="text"] If set to "html", the message content will be assigned to the banner's innerHTML directly, instead of its textContent
+ * @param {any} [logMessage=true] An additional flag for whether the message should be sent to the console log.
+ */
 export function _createAlertBanner(
     message,
     level,

package/src/plugins/error.js

@@ -24,6 +24,11 @@ hooks.onInterpreterReady.add(function override(pyScript) {
 // Error hook utilities
 
 // Custom function to show notifications
+
+/**
+ * Add a banner to the top of the page, notifying the user of an error
+ * @param {string} message
+ */
 export function notify(message) {
     const div = document.createElement("div");
     div.className = "py-error";

package/src/sync.js

@@ -1,4 +1,8 @@
 export default {
+    /**
+     * 'Sleep' for the given number of seconds. Used to implement Python's time.sleep in Worker threads.
+     * @param {number} seconds The number of seconds to sleep.
+     */
     sleep(seconds) {
         return new Promise(($) => setTimeout($, seconds * 1000));
     },

package/src/types.js

@@ -0,0 +1,4 @@
+export default new Map([
+    ["py", "pyodide"],
+    ["mpy", "micropython"],
+]);

package/types/config.d.ts

@@ -1,4 +1,2 @@
-declare let parsed: any;
-export let plugins: any;
-export let error: any;
-export { parsed as config };
+export default configs;
+declare const configs: Map<any, any>;

package/types/core.d.ts

@@ -21,5 +21,6 @@ export namespace hooks {
     let codeAfterRunWorker: Set<string>;
     let codeAfterRunWorkerAsync: Set<string>;
 }
-import { config } from "./config.js";
+export { exportedConfig as config };
 import sync from "./sync.js";
+declare const exportedConfig: {};

package/types/exceptions.d.ts

@@ -1,4 +1,11 @@
-export function _createAlertBanner(message: any, level: any, messageType?: string, logMessage?: boolean): void;
+/**
+ * Internal function for creating alert banners on the page
+ * @param {string} message The message to be displayed to the user
+ * @param {string} level The alert level of the message. Can be any string; 'error' or 'warning' cause matching messages to be emitted to the console
+ * @param {string} [messageType="text"] If set to "html", the message content will be assigned to the banner's innerHTML directly, instead of its textContent
+ * @param {any} [logMessage=true] An additional flag for whether the message should be sent to the console log.
+ */
+export function _createAlertBanner(message: string, level: string, messageType?: string, logMessage?: any): void;
 export namespace ErrorCode {
     let GENERIC: string;
     let CONFLICTING_CODE: string;
@@ -15,14 +22,50 @@ export namespace ErrorCode {
     let FETCH_SERVER_ERROR: string;
     let FETCH_UNAVAILABLE_ERROR: string;
 }
+/**
+ * Keys of the ErrorCode object
+ * @typedef {keyof ErrorCode} ErrorCodes
+ * */
 export class UserError extends Error {
-    constructor(errorCode: any, message?: string, messageType?: string);
-    errorCode: any;
+    /**
+     * @param {ErrorCodes} errorCode
+     * @param {string} message
+     * @param {string} messageType
+     * */
+    constructor(errorCode: ErrorCodes, message?: string, messageType?: string);
+    errorCode: "GENERIC" | "CONFLICTING_CODE" | "BAD_CONFIG" | "MICROPIP_INSTALL_ERROR" | "BAD_PLUGIN_FILE_EXTENSION" | "NO_DEFAULT_EXPORT" | "TOP_LEVEL_AWAIT" | "FETCH_ERROR" | "FETCH_NAME_ERROR" | "FETCH_UNAUTHORIZED_ERROR" | "FETCH_FORBIDDEN_ERROR" | "FETCH_NOT_FOUND_ERROR" | "FETCH_SERVER_ERROR" | "FETCH_UNAVAILABLE_ERROR";
     messageType: string;
 }
 export class FetchError extends UserError {
-    constructor(errorCode: any, message: any);
+    /**
+     * @param {ErrorCodes} errorCode
+     * @param {string} message
+     * */
+    constructor(errorCode: ErrorCodes, message: string);
 }
 export class InstallError extends UserError {
-    constructor(errorCode: any, message: any);
+    /**
+     * @param {ErrorCodes} errorCode
+     * @param {string} message
+     * */
+    constructor(errorCode: ErrorCodes, message: string);
 }
+/**
+ * Keys of the ErrorCode object
+ */
+export type ErrorCodes = keyof {
+    GENERIC: string;
+    CONFLICTING_CODE: string;
+    BAD_CONFIG: string;
+    MICROPIP_INSTALL_ERROR: string;
+    BAD_PLUGIN_FILE_EXTENSION: string;
+    NO_DEFAULT_EXPORT: string;
+    TOP_LEVEL_AWAIT: string;
+    FETCH_ERROR: string;
+    FETCH_NAME_ERROR: string;
+    FETCH_UNAUTHORIZED_ERROR: string;
+    FETCH_FORBIDDEN_ERROR: string;
+    FETCH_NOT_FOUND_ERROR: string;
+    FETCH_SERVER_ERROR: string;
+    FETCH_UNAVAILABLE_ERROR: string;
+};

package/types/plugins/error.d.ts

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

package/types/sync.d.ts

@@ -1,4 +1,8 @@
 declare namespace _default {
-    function sleep(seconds: any): Promise<any>;
+    /**
+     * 'Sleep' for the given number of seconds. Used to implement Python's time.sleep in Worker threads.
+     * @param {number} seconds The number of seconds to sleep.
+     */
+    function sleep(seconds: number): Promise<any>;
 }
 export default _default;

package/types/types.d.ts

@@ -0,0 +1,2 @@
+declare const _default: Map<string, string>;
+export default _default;