pyodide 0.19.1 → 0.20.1-alpha.1

package/api.js

@@ -1,421 +0,0 @@
-import { Module } from "./module.js";
-import { loadPackage, loadedPackages } from "./load-pyodide.js";
-import { isPyProxy, PyBuffer } from "./pyproxy.gen.js";
-export { loadPackage, loadedPackages, isPyProxy };
-
-/**
- * @typedef {import('./pyproxy.gen').Py2JsResult} Py2JsResult
- * @typedef {import('./pyproxy.gen').PyProxy} PyProxy
- * @typedef {import('./pyproxy.gen').TypedArray} TypedArray
- * @typedef {import('emscripten')} Emscripten
- * @typedef {import('emscripten').Module.FS} FS
- */
-
-/**
- * An alias to the Python :py:mod:`pyodide` package.
- *
- * You can use this to call functions defined in the Pyodide Python package
- * from JavaScript.
- *
- * @type {PyProxy}
- */
-let pyodide_py = {}; // actually defined in loadPyodide (see pyodide.js)
-
-/**
- *
- * An alias to the global Python namespace.
- *
- * For example, to access a variable called ``foo`` in the Python global
- * scope, use ``pyodide.globals.get("foo")``
- *
- * @type {PyProxy}
- */
-let globals = {}; // actually defined in loadPyodide (see pyodide.js)
-
-/**
- * A JavaScript error caused by a Python exception.
- *
- * In order to reduce the risk of large memory leaks, the ``PythonError``
- * contains no reference to the Python exception that caused it. You can find
- * the actual Python exception that caused this error as `sys.last_value
- * <https://docs.python.org/3/library/sys.html#sys.last_value>`_.
- *
- * See :ref:`type-translations-errors` for more information.
- *
- * .. admonition:: Avoid Stack Frames
- *    :class: warning
- *
- *    If you make a :any:`PyProxy` of ``sys.last_value``, you should be
- *    especially careful to :any:`destroy() <PyProxy.destroy>` it when you are
- *    done. You may leak a large amount of memory including the local
- *    variables of all the stack frames in the traceback if you don't. The
- *    easiest way is to only handle the exception in Python.
- *
- * @class
- */
-export class PythonError {
-  // actually defined in error_handling.c. TODO: would be good to move this
-  // documentation and the definition of PythonError to error_handling.js
-  constructor() {
-    /**
-     * The Python traceback.
-     * @type {string}
-     */
-    this.message;
-  }
-}
-
-/**
- *
- * The Pyodide version.
- *
- * It can be either the exact release version (e.g. ``0.1.0``), or
- * the latest release version followed by the number of commits since, and
- * the git hash of the current commit (e.g. ``0.1.0-1-bd84646``).
- *
- * @type {string}
- */
-export let version = ""; // actually defined in loadPyodide (see pyodide.js)
-
-/**
- * Runs a string of Python code from JavaScript.
- *
- * The last part of the string may be an expression, in which case, its value
- * is returned.
- *
- * @param {string} code Python code to evaluate
- * @param {PyProxy=} globals An optional Python dictionary to use as the globals.
- *        Defaults to :any:`pyodide.globals`. Uses the Python API
- *        :any:`pyodide.eval_code` to evaluate the code.
- * @returns {Py2JsResult} The result of the Python code translated to JavaScript. See the
- *          documentation for :any:`pyodide.eval_code` for more info.
- */
-export function runPython(code, globals = Module.globals) {
-  return Module.pyodide_py.eval_code(code, globals);
-}
-Module.runPython = runPython;
-
-/**
- * @callback LogFn
- * @param {string} msg
- * @returns {void}
- * @private
- */
-
-/**
- * Inspect a Python code chunk and use :js:func:`pyodide.loadPackage` to install
- * any known packages that the code chunk imports. Uses the Python API
- * :func:`pyodide.find\_imports` to inspect the code.
- *
- * For example, given the following code as input
- *
- * .. code-block:: python
- *
- *    import numpy as np x = np.array([1, 2, 3])
- *
- * :js:func:`loadPackagesFromImports` will call
- * ``pyodide.loadPackage(['numpy'])``.
- *
- * @param {string} code The code to inspect.
- * @param {LogFn=} messageCallback The ``messageCallback`` argument of
- * :any:`pyodide.loadPackage` (optional).
- * @param {LogFn=} errorCallback The ``errorCallback`` argument of
- * :any:`pyodide.loadPackage` (optional).
- * @async
- */
-export async function loadPackagesFromImports(
-  code,
-  messageCallback,
-  errorCallback
-) {
-  let pyimports = Module.pyodide_py.find_imports(code);
-  let imports;
-  try {
-    imports = pyimports.toJs();
-  } finally {
-    pyimports.destroy();
-  }
-  if (imports.length === 0) {
-    return;
-  }
-
-  let packageNames = Module._import_name_to_package_name;
-  let packages = new Set();
-  for (let name of imports) {
-    if (packageNames.has(name)) {
-      packages.add(packageNames.get(name));
-    }
-  }
-  if (packages.size) {
-    await loadPackage(Array.from(packages), messageCallback, errorCallback);
-  }
-}
-
-/**
- * Runs Python code using `PyCF_ALLOW_TOP_LEVEL_AWAIT
- * <https://docs.python.org/3/library/ast.html?highlight=pycf_allow_top_level_await#ast.PyCF_ALLOW_TOP_LEVEL_AWAIT>`_.
- *
- * .. admonition:: Python imports
- *    :class: warning
- *
- *    Since pyodide 0.18.0, you must call :js:func:`loadPackagesFromImports` to
- *    import any python packages referenced via `import` statements in your code.
- *    This function will no longer do it for you.
- *
- * For example:
- *
- * .. code-block:: pyodide
- *
- *    let result = await pyodide.runPythonAsync(`
- *        from js import fetch
- *        response = await fetch("./packages.json")
- *        packages = await response.json()
- *        # If final statement is an expression, its value is returned to JavaScript
- *        len(packages.packages.object_keys())
- *    `);
- *    console.log(result); // 79
- *
- * @param {string} code Python code to evaluate
- * @param {PyProxy=} globals An optional Python dictionary to use as the globals.
- *        Defaults to :any:`pyodide.globals`. Uses the Python API
- *        :any:`pyodide.eval_code_async` to evaluate the code.
- * @returns {Py2JsResult} The result of the Python code translated to JavaScript.
- * @async
- */
-export async function runPythonAsync(code, globals = Module.globals) {
-  return await Module.pyodide_py.eval_code_async(code, globals);
-}
-Module.runPythonAsync = runPythonAsync;
-
-/**
- * Registers the JavaScript object ``module`` as a JavaScript module named
- * ``name``. This module can then be imported from Python using the standard
- * Python import system. If another module by the same name has already been
- * imported, this won't have much effect unless you also delete the imported
- * module from ``sys.modules``. This calls the ``pyodide_py`` API
- * :func:`pyodide.register_js_module`.
- *
- * @param {string} name Name of the JavaScript module to add
- * @param {object} module JavaScript object backing the module
- */
-export function registerJsModule(name, module) {
-  Module.pyodide_py.register_js_module(name, module);
-}
-
-/**
- * Tell Pyodide about Comlink.
- * Necessary to enable importing Comlink proxies into Python.
- */
-export function registerComlink(Comlink) {
-  Module._Comlink = Comlink;
-}
-
-/**
- * Unregisters a JavaScript module with given name that has been previously
- * registered with :js:func:`pyodide.registerJsModule` or
- * :func:`pyodide.register_js_module`. If a JavaScript module with that name
- * does not already exist, will throw an error. Note that if the module has
- * already been imported, this won't have much effect unless you also delete
- * the imported module from ``sys.modules``. This calls the ``pyodide_py`` API
- * :func:`pyodide.unregister_js_module`.
- *
- * @param {string} name Name of the JavaScript module to remove
- */
-export function unregisterJsModule(name) {
-  Module.pyodide_py.unregister_js_module(name);
-}
-
-/**
- * Convert the JavaScript object to a Python object as best as possible.
- *
- * This is similar to :any:`JsProxy.to_py` but for use from JavaScript. If the
- * object is immutable or a :any:`PyProxy`, it will be returned unchanged. If
- * the object cannot be converted into Python, it will be returned unchanged.
- *
- * See :ref:`type-translations-jsproxy-to-py` for more information.
- *
- * @param {*} obj
- * @param {object} options
- * @param {number=} options.depth Optional argument to limit the depth of the
- * conversion.
- * @returns {PyProxy} The object converted to Python.
- */
-export function toPy(obj, { depth = -1 } = {}) {
-  // No point in converting these, it'd be dumb to proxy them so they'd just
-  // get converted back by `js2python` at the end
-  switch (typeof obj) {
-    case "string":
-    case "number":
-    case "boolean":
-    case "bigint":
-    case "undefined":
-      return obj;
-  }
-  if (!obj || Module.isPyProxy(obj)) {
-    return obj;
-  }
-  let obj_id = 0;
-  let py_result = 0;
-  let result = 0;
-  try {
-    obj_id = Module.hiwire.new_value(obj);
-    try {
-      py_result = Module.js2python_convert(obj_id, new Map(), depth);
-    } catch (e) {
-      if (e instanceof Module._PropagatePythonError) {
-        Module._pythonexc2js();
-      }
-      throw e;
-    }
-    if (Module._JsProxy_Check(py_result)) {
-      // Oops, just created a JsProxy. Return the original object.
-      return obj;
-      // return Module.pyproxy_new(py_result);
-    }
-    result = Module._python2js(py_result);
-    if (result === 0) {
-      Module._pythonexc2js();
-    }
-  } finally {
-    Module.hiwire.decref(obj_id);
-    Module._Py_DecRef(py_result);
-  }
-  return Module.hiwire.pop_value(result);
-}
-
-/**
- * Imports a module and returns it.
- *
- * .. admonition:: Warning
- *    :class: warning
- *
- *    This function has a completely different behavior than the old removed pyimport function!
- *
- *    ``pyimport`` is roughly equivalent to:
- *
- *    .. code-block:: js
- *
- *      pyodide.runPython(`import ${pkgname}; ${pkgname}`);
- *
- *    except that the global namespace will not change.
- *
- *    Example:
- *
- *    .. code-block:: js
- *
- *      let sysmodule = pyodide.pyimport("sys");
- *      let recursionLimit = sys.getrecursionlimit();
- *
- * @param {string} mod_name The name of the module to import
- * @returns A PyProxy for the imported module
- */
-export function pyimport(mod_name) {
-  return Module.importlib.import_module(mod_name);
-}
-
-/**
- * Unpack an archive into a target directory.
- *
- * @param {ArrayBuffer} buffer The archive as an ArrayBuffer (it's also fine to pass a TypedArray).
- * @param {string} format The format of the archive. Should be one of the formats recognized by `shutil.unpack_archive`.
- * By default the options are 'bztar', 'gztar', 'tar', 'zip', and 'wheel'. Several synonyms are accepted for each format, e.g.,
- * for 'gztar' any of '.gztar', '.tar.gz', '.tgz', 'tar.gz' or 'tgz' are considered to be synonyms.
- *
- * @param {string=} extract_dir The directory to unpack the archive into. Defaults to the working directory.
- */
-export function unpackArchive(buffer, format, extract_dir) {
-  if (!Module._util_module) {
-    Module._util_module = pyimport("pyodide._util");
-  }
-  Module._util_module.unpack_buffer_archive.callKwargs(buffer, {
-    format,
-    extract_dir,
-  });
-}
-
-/**
- * @private
- */
-Module.saveState = () => Module.pyodide_py._state.save_state();
-
-/**
- * @private
- */
-Module.restoreState = (state) => Module.pyodide_py._state.restore_state(state);
-
-/**
- * Sets the interrupt buffer to be `interrupt_buffer`. This is only useful when
- * Pyodide is used in a webworker. The buffer should be a `SharedArrayBuffer`
- * shared with the main browser thread (or another worker). To request an
- * interrupt, a `2` should be written into `interrupt_buffer` (2 is the posix
- * constant for SIGINT).
- *
- * @param {TypedArray} interrupt_buffer
- */
-export function setInterruptBuffer(interrupt_buffer) {
-  Module.interrupt_buffer = interrupt_buffer;
-  Module._set_pyodide_callback(!!interrupt_buffer);
-}
-
-/**
- * Throws a KeyboardInterrupt error if a KeyboardInterrupt has been requested
- * via the interrupt buffer.
- *
- * This can be used to enable keyboard interrupts during execution of JavaScript
- * code, just as `PyErr_CheckSignals` is used to enable keyboard interrupts
- * during execution of C code.
- */
-export function checkInterrupt() {
-  if (Module.interrupt_buffer[0] === 2) {
-    Module.interrupt_buffer[0] = 0;
-    Module._PyErr_SetInterrupt();
-    Module.runPython("");
-  }
-}
-
-export function makePublicAPI() {
-  /**
-   * An alias to the `Emscripten File System API
-   * <https://emscripten.org/docs/api_reference/Filesystem-API.html>`_.
-   *
-   * This provides a wide range of POSIX-`like` file/device operations, including
-   * `mount
-   * <https://emscripten.org/docs/api_reference/Filesystem-API.html#FS.mount>`_
-   * which can be used to extend the in-memory filesystem with features like `persistence
-   * <https://emscripten.org/docs/api_reference/Filesystem-API.html#persistent-data>`_.
-   *
-   * While all the file systems implementations are enabled, only the default
-   * ``MEMFS`` is guaranteed to work in all runtime settings. The implementations
-   * are available as members of ``FS.filesystems``:
-   * ``IDBFS``, ``NODEFS``, ``PROXYFS``, ``WORKERFS``.
-   *
-   * @type {FS}
-   */
-  const FS = Module.FS;
-  let namespace = {
-    globals,
-    FS,
-    pyodide_py,
-    version,
-    loadPackage,
-    loadPackagesFromImports,
-    loadedPackages,
-    isPyProxy,
-    runPython,
-    runPythonAsync,
-    registerJsModule,
-    unregisterJsModule,
-    setInterruptBuffer,
-    checkInterrupt,
-    toPy,
-    pyimport,
-    unpackArchive,
-    registerComlink,
-    PythonError,
-    PyBuffer,
-  };
-
-  namespace._module = Module; // @private
-  Module.public_api = namespace;
-  return namespace;
-}

package/error_handling.gen.ts

@@ -1,294 +0,0 @@
-import ErrorStackParser from "error-stack-parser";
-import { Module, API, Hiwire, Tests } from "./module.js";
-
-/**
- * Dump the Python traceback to the browser console.
- *
- * @private
- */
-API.dump_traceback = function () {
-  const fd_stdout = 1;
-  Module.__Py_DumpTraceback(fd_stdout, Module._PyGILState_GetThisThreadState());
-};
-
-let fatal_error_occurred = false;
-/**
- * Signal a fatal error.
- *
- * Dumps the Python traceback, shows a JavaScript traceback, and prints a clear
- * message indicating a fatal error. It then dummies out the public API so that
- * further attempts to use Pyodide will clearly indicate that Pyodide has failed
- * and can no longer be used. pyodide._module is left accessible, and it is
- * possible to continue using Pyodide for debugging purposes if desired.
- *
- * @argument e {Error} The cause of the fatal error.
- * @private
- */
-API.fatal_error = function (e: any) {
-  if (e.pyodide_fatal_error) {
-    return;
-  }
-  if (fatal_error_occurred) {
-    console.error("Recursive call to fatal_error. Inner error was:");
-    console.error(e);
-    return;
-  }
-  if (typeof e === "number") {
-    // A C++ exception. Have to do some conversion work.
-    e = convertCppException(e);
-  } else if (typeof e === "string") {
-    e = new Error(e);
-  } else if (typeof e !== "object") {
-    e = new Error(
-      `An object of type ${typeof e} was thrown as an error. toString returns ${e.toString()}`
-    );
-  }
-  // Mark e so we know not to handle it later in EM_JS wrappers
-  e.pyodide_fatal_error = true;
-  fatal_error_occurred = true;
-  console.error(
-    "Pyodide has suffered a fatal error. Please report this to the Pyodide maintainers."
-  );
-  console.error("The cause of the fatal error was:");
-  if (API.inTestHoist) {
-    // Test hoist won't print the error object in a useful way so convert it to
-    // string.
-    console.error(e.toString());
-    console.error(e.stack);
-  } else {
-    console.error(e);
-  }
-  try {
-    API.dump_traceback();
-    for (let key of Object.keys(API.public_api)) {
-      if (key.startsWith("_") || key === "version") {
-        continue;
-      }
-      Object.defineProperty(API.public_api, key, {
-        enumerable: true,
-        configurable: true,
-        get: () => {
-          throw new Error(
-            "Pyodide already fatally failed and can no longer be used."
-          );
-        },
-      });
-    }
-    if (API.on_fatal) {
-      API.on_fatal(e);
-    }
-  } catch (err2) {
-    console.error("Another error occurred while handling the fatal error:");
-    console.error(err2);
-  }
-  throw e;
-};
-
-class CppException extends Error {
-  ty: string;
-  constructor(ty: string, msg: string) {
-    super(msg);
-    this.ty = ty;
-  }
-}
-Object.defineProperty(CppException.prototype, "name", {
-  get() {
-    return `${this.constructor.name} ${this.ty}`;
-  },
-});
-
-/**
- *
- * Return the type name, whether the pointer inherits from exception, and the
- * vtable pointer for the type.
- *
- * This code is based on imitating:
- * 1. the implementation of __cxa_find_matching_catch
- * 2. the disassembly from:
- * ```C++
- * try {
- *    ...
- * } catch(exception e){
- *    ...
- * }
- *
- * @param ptr
- * @returns
- * exc_type_name : the type name of the exception, as would be reported by
- * `typeid(type).name()` but also demangled.
- *
- * is_exception_subclass : true if the object is a subclass of exception. In
- * this case we will use `exc.what()` to get an error message.
- *
- * adjusted_ptr : The adjusted vtable pointer for the exception to use to invoke
- * exc.what().
- *
- * @private
- */
-function cppExceptionInfo(ptr: number): [string, boolean, number] {
-  const base_exception_type = Module._exc_type();
-  const ei = new Module.ExceptionInfo(ptr);
-  const caught_exception_type = ei.get_type();
-  const stackTop = Module.stackSave();
-  const exceptionThrowBuf = Module.stackAlloc(4);
-  Module.HEAP32[exceptionThrowBuf / 4] = ptr;
-  const exc_type_name = Module.demangle(
-    Module.UTF8ToString(Module._exc_typename(caught_exception_type))
-  );
-  const is_exception_subclass = !!Module.___cxa_can_catch(
-    base_exception_type,
-    caught_exception_type,
-    exceptionThrowBuf
-  );
-  const adjusted_ptr = Module.HEAP32[exceptionThrowBuf / 4];
-  Module.stackRestore(stackTop);
-  return [exc_type_name, is_exception_subclass, adjusted_ptr];
-}
-
-function convertCppException(ptr: number): CppException {
-  const [exc_type_name, is_exception_subclass, adjusted_ptr] =
-    cppExceptionInfo(ptr);
-  let msg;
-  if (is_exception_subclass) {
-    // If the ptr inherits from exception, we can use exception.what() to
-    // generate a message
-    const msgPtr = Module._exc_what(adjusted_ptr);
-    msg = Module.UTF8ToString(msgPtr);
-  } else {
-    msg = `The exception is an object of type ${exc_type_name} at address ${ptr} which does not inherit from std::exception`;
-  }
-  return new CppException(exc_type_name, msg);
-}
-// Expose for testing
-Tests.convertCppException = convertCppException;
-
-function isPyodideFrame(frame: ErrorStackParser.StackFrame): boolean {
-  const fileName = frame.fileName || "";
-  if (fileName.includes("pyodide.asm")) {
-    return true;
-  }
-  if (fileName.includes("wasm-function")) {
-    return true;
-  }
-  if (!fileName.includes("pyodide.js")) {
-    return false;
-  }
-  let funcName = frame.functionName || "";
-  if (funcName.startsWith("Object.")) {
-    funcName = funcName.slice("Object.".length);
-  }
-  if (funcName in API.public_api && funcName !== "PythonError") {
-    frame.functionName = funcName;
-    return false;
-  }
-  return true;
-}
-
-function isErrorStart(frame: ErrorStackParser.StackFrame): boolean {
-  if (!isPyodideFrame(frame)) {
-    return false;
-  }
-  const funcName = frame.functionName;
-  return funcName === "PythonError" || funcName === "new_error";
-}
-
-Module.handle_js_error = function (e: any) {
-  if (e.pyodide_fatal_error) {
-    throw e;
-  }
-  if (e instanceof Module._PropagatePythonError) {
-    // Python error indicator is already set in this case. If this branch is
-    // not taken, Python error indicator should be unset, and we have to set
-    // it. In this case we don't want to tamper with the traceback.
-    return;
-  }
-  let restored_error = false;
-  if (e instanceof API.PythonError) {
-    // Try to restore the original Python exception.
-    restored_error = Module._restore_sys_last_exception(e.__error_address);
-  }
-  if (!restored_error) {
-    // Wrap the JavaScript error
-    let eidx = Hiwire.new_value(e);
-    let err = Module._JsProxy_create(eidx);
-    Module._set_error(err);
-    Module._Py_DecRef(err);
-    Hiwire.decref(eidx);
-  }
-  let stack = ErrorStackParser.parse(e);
-  if (isErrorStart(stack[0])) {
-    while (isPyodideFrame(stack[0])) {
-      stack.shift();
-    }
-  }
-  // Add the Javascript stack frames to the Python traceback
-  for (const frame of stack) {
-    if (isPyodideFrame(frame)) {
-      break;
-    }
-    const funcnameAddr = Module.stringToNewUTF8(frame.functionName || "???");
-    const fileNameAddr = Module.stringToNewUTF8(frame.fileName || "???.js");
-    Module.__PyTraceback_Add(funcnameAddr, fileNameAddr, frame.lineNumber);
-    Module._free(funcnameAddr);
-    Module._free(fileNameAddr);
-  }
-};
-
-/**
- * A JavaScript error caused by a Python exception.
- *
- * In order to reduce the risk of large memory leaks, the ``PythonError``
- * contains no reference to the Python exception that caused it. You can find
- * the actual Python exception that caused this error as `sys.last_value
- * <https://docs.python.org/3/library/sys.html#sys.last_value>`_.
- *
- * See :ref:`type-translations-errors` for more information.
- *
- * .. admonition:: Avoid Stack Frames
- *    :class: warning
- *
- *    If you make a :any:`PyProxy` of ``sys.last_value``, you should be
- *    especially careful to :any:`destroy() <PyProxy.destroy>` it when you are
- *    done. You may leak a large amount of memory including the local
- *    variables of all the stack frames in the traceback if you don't. The
- *    easiest way is to only handle the exception in Python.
- */
-export class PythonError extends Error {
-  /**  The address of the error we are wrapping. We may later compare this
-   * against sys.last_value.
-   * WARNING: we don't own a reference to this pointer, dereferencing it
-   * may be a use-after-free error!
-   * @private
-   */
-  __error_address: number;
-
-  constructor(message: string, error_address: number) {
-    const oldLimit = Error.stackTraceLimit;
-    Error.stackTraceLimit = Infinity;
-    super(message);
-    Error.stackTraceLimit = oldLimit;
-    this.__error_address = error_address;
-  }
-}
-Object.defineProperty(PythonError.prototype, "name", {
-  value: PythonError.name,
-});
-API.PythonError = PythonError;
-// A special marker. If we call a CPython API from an EM_JS function and the
-// CPython API sets an error, we might want to return an error status back to
-// C keeping the current Python error flag. This signals to the EM_JS wrappers
-// that the Python error flag is set and to leave it alone and return the
-// appropriate error value (either NULL or -1).
-class _PropagatePythonError extends Error {
-  constructor() {
-    API.fail_test = true;
-    super(
-      "If you are seeing this message, an internal Pyodide error has " +
-        "occurred. Please report it to the Pyodide maintainers."
-    );
-  }
-}
-Object.defineProperty(_PropagatePythonError.prototype, "name", {
-  value: _PropagatePythonError.name,
-});
-Module._PropagatePythonError = _PropagatePythonError;

package/index.d.ts

@@ -1 +0,0 @@
-// This file is just needed to make "npx tsd" work (otherwise it will quit with an error).