pyodide 0.18.2 → 0.19.0-alpha.1

package/README.md

@@ -1,4 +1,4 @@
-# Pyodide Javascript package
+# Pyodide JavaScript package
 
 <a href="https://www.npmjs.com/package/pyodide"><img src="https://img.shields.io/npm/v/pyodide" alt="npm"></a>
 
@@ -26,15 +26,15 @@ See the [documentation](https://pyodide.org/en/stable/) fore more details.
 
 ## Details
 
-The Javascript code in this package is responsible for the following tasks:
+The JavaScript code in this package is responsible for the following tasks:
 
-1. Defines the public [Javascript API](https://pyodide.org/en/stable/usage/api/js-api.html)
+1. Defines the public [JavaScript API](https://pyodide.org/en/stable/usage/api/js-api.html)
    - Package loading code to allow loading of other Python packages.
    - Can load
      [micropip](https://pyodide.org/en/stable/usage/api/micropip-api.html) to
      bootstrap loading of pure Python wheels
 2. Loads the CPython interpreter and the core/pyodide emscripten application
    which embeds the interpreter.
-3. Injects the `js/pyodide` Javascript API into `sys.modules`. This is the
+3. Injects the `js/pyodide` JavaScript API into `sys.modules`. This is the
    final runtime dependency for `core/pyodide` & `py/pyodide`, so after this step
    the interpreter is fully up and running.

package/api.js

@@ -8,17 +8,18 @@ export { loadPackage, loadedPackages, isPyProxy };
  * @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.
+ * from JavaScript.
  *
  * @type {PyProxy}
  */
-let pyodide_py = {}; // actually defined in runPythonSimple in loadPyodide (see pyodide.js)
+let pyodide_py = {}; // actually defined in loadPyodide (see pyodide.js)
 
 /**
  *
@@ -29,10 +30,10 @@ let pyodide_py = {}; // actually defined in runPythonSimple in loadPyodide (see
  *
  * @type {PyProxy}
  */
-let globals = {}; // actually defined in runPythonSimple in loadPyodide (see pyodide.js)
+let globals = {}; // actually defined in loadPyodide (see pyodide.js)
 
 /**
- * A Javascript error caused by a Python exception.
+ * 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
@@ -74,19 +75,19 @@ export class PythonError {
  *
  * @type {string}
  */
-export let version = ""; // actually defined in runPythonSimple in loadPyodide (see pyodide.js)
+export let version = ""; // actually defined in loadPyodide (see pyodide.js)
 
 /**
- * Runs a string of Python code from Javascript.
+ * 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.
+ * @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
+ * @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) {
@@ -150,22 +151,6 @@ export async function loadPackagesFromImports(
   }
 }
 
-/**
- * Access a Python object in the global namespace from Javascript.
- *
- * @deprecated This function will be removed in version 0.18.0. Use
- *    :any:`pyodide.globals.get('key') <pyodide.globals>` instead.
- *
- * @param {string} name Python variable name
- * @returns {Py2JsResult} The Python object translated to Javascript.
- */
-export function pyimport(name) {
-  console.warn(
-    "Access to the Python global namespace via pyodide.pyimport is deprecated and " +
-      "will be removed in version 0.18.0. Use pyodide.globals.get('key') instead."
-  );
-  return Module.globals.get(name);
-}
 /**
  * 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>`_.
@@ -185,36 +170,33 @@ export function pyimport(name) {
  *        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
+ *        # 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
- * @returns {Py2JsResult} The result of the Python code translated to Javascript.
+ * @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) {
-  let coroutine = Module.pyodide_py.eval_code_async(code, Module.globals);
-  try {
-    let result = await coroutine;
-    return result;
-  } finally {
-    coroutine.destroy();
-  }
+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
+ * 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
+ * @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);
@@ -229,24 +211,24 @@ export function registerComlink(Comlink) {
 }
 
 /**
- * Unregisters a Javascript module with given name that has been previously
+ * 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
+ * :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
+ * @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.
+ * 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
+ * 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.
  *
@@ -254,7 +236,7 @@ export function unregisterJsModule(name) {
  *
  * @param {*} obj
  * @param {object} options
- * @param {number} options.depth Optional argument to limit the depth of the
+ * @param {number=} options.depth Optional argument to limit the depth of the
  * conversion.
  * @returns {PyProxy} The object converted to Python.
  */
@@ -277,9 +259,13 @@ export function toPy(obj, { depth = -1 } = {}) {
   let result = 0;
   try {
     obj_id = Module.hiwire.new_value(obj);
-    py_result = Module.__js2python_convert(obj_id, new Map(), depth);
-    if (py_result === 0) {
-      Module._pythonexc2js();
+    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.
@@ -297,6 +283,56 @@ export function toPy(obj, { depth = -1 } = {}) {
   return Module.hiwire.pop_value(result);
 }
 
+/**
+ * Imports a module and returns it.
+ * Warning: this function has a completely different behavior than the old removed pyimport function!
+ * ``pyimport`` is roughly equivalent to:
+ *
+ * .. code-block:: pyodide
+ *
+ *      pyodide.runPython(`import ${pkgname}; ${pkgname}`);
+ *
+ * except that the global namespace will not change.
+ * Example:
+ *
+ * .. code-block:: pyodide
+ *
+ *    let sysmodule = pyodide.pyimport("sys");
+ *    let recursionLimit = sys.getrecursionlimit();
+ *
+ * The best way to run Python code with Pyodide is
+ * 1. write a Python package,
+ * 2. load your Python package into the Pyodide (Emscripten) file system,
+ * 3. import the package with `let mypkg = pyodide.pyimport("mypkgname")`,
+ * 4. call into your package with `mypkg.some_api(some_args)`.
+ *
+ * @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
  */
@@ -308,11 +344,34 @@ Module.saveState = () => Module.pyodide_py._state.save_state();
 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
  */
-function setInterruptBuffer(interrupt_buffer) {}
-setInterruptBuffer = Module.setInterruptBuffer;
-export { setInterruptBuffer };
+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() {
   /**
@@ -325,15 +384,14 @@ export function makePublicAPI() {
    * 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 of the file systems implementations are enabled, only the default
+   * 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} The Emscripten File System API.
+   * @type {FS}
    */
   const FS = Module.FS;
-
   let namespace = {
     globals,
     FS,
@@ -343,13 +401,15 @@ export function makePublicAPI() {
     loadPackagesFromImports,
     loadedPackages,
     isPyProxy,
-    pyimport,
     runPython,
     runPythonAsync,
     registerJsModule,
     unregisterJsModule,
     setInterruptBuffer,
+    checkInterrupt,
     toPy,
+    pyimport,
+    unpackArchive,
     registerComlink,
     PythonError,
     PyBuffer,

package/index.test-d.ts

@@ -27,8 +27,8 @@ async function main() {
       indexURL: "blah",
       fullStdLib: true,
       stdin: () => "a string",
-      stdout: (x) => {},
-      stderr: (err) => {},
+      stdout: (x: string) => {},
+      stderr: (err: string) => {},
     })
   );
 
@@ -49,29 +49,32 @@ async function main() {
 
   expectType<Promise<void>>(pyodide.loadPackagesFromImports("import some_pkg"));
   expectType<Promise<void>>(
-    pyodide.loadPackagesFromImports("import some_pkg", (x) => console.log(x))
+    pyodide.loadPackagesFromImports("import some_pkg", (x: any) =>
+      console.log(x)
+    )
   );
   expectType<Promise<void>>(
     pyodide.loadPackagesFromImports(
       "import some_pkg",
-      (x) => console.log(x),
-      (x) => console.warn(x)
+      (x: any) => console.log(x),
+      (x: any) => console.warn(x)
     )
   );
 
   expectType<Promise<void>>(pyodide.loadPackage("blah"));
   expectType<Promise<void>>(pyodide.loadPackage(["blah", "blah2"]));
-  expectType<Promise<void>>(pyodide.loadPackage("blah", (x) => console.log(x)));
+  expectType<Promise<void>>(
+    pyodide.loadPackage("blah", (x: any) => console.log(x))
+  );
   expectType<Promise<void>>(
     pyodide.loadPackage(
       ["blah", "blah2"],
-      (x) => console.log(x),
-      (x) => console.warn(x)
+      (x: any) => console.log(x),
+      (x: any) => console.warn(x)
     )
   );
   expectType<Promise<void>>(pyodide.loadPackage(px));
 
-  expectType<Py2JsResult>(pyodide.pyimport("blah"));
   expectType<PyProxy>(pyodide.pyodide_py);
   expectType<void>(pyodide.registerJsModule("blah", { a: 7 }));
   expectType<void>(pyodide.unregisterJsModule("blah"));