@pyscript/core 0.2.2 → 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.2",
+    "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

@@ -20,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 = "",
@@ -49,9 +50,18 @@ const syntaxError = (type, url, { message }) => {
 const configs = new Map();
 
 for (const [TYPE] of TYPES) {
-    // find the shared config for all py-script elements
-    let config, plugins, parsed, error, type;
-    let pyConfig = $(`${TYPE}-config`);
+    /** @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");
@@ -68,7 +78,7 @@ for (const [TYPE] of TYPES) {
     // catch possible fetch errors
     if (config) {
         try {
-            const { json, toml, text, url } = await configDetails(config);
+            const { json, toml, text, url } = await configDetails(config, type);
             config = text;
             if (json || type === "json") {
                 try {

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/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;