From a4aa23a04099bb472110e127ceda70b3d58897e9 Mon Sep 17 00:00:00 2001
From: Will Lachance <wrlach@gmail.com>
Date: Sun, 25 Jul 2021 15:35:56 -0400
Subject: [PATCH] Improve documentation around runPythonAsync (#1748) [skip ci]

---
 src/js/api.js | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/src/js/api.js b/src/js/api.js
index 993ec35fb..b30cd51ac 100644
--- a/src/js/api.js
+++ b/src/js/api.js
@@ -102,8 +102,8 @@ Module.runPython = runPython;
  */
 
 /**
- * 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
+ * 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
@@ -113,7 +113,7 @@ Module.runPython = runPython;
  *    import numpy as np x = np.array([1, 2, 3])
  *
  * :js:func:`loadPackagesFromImports` will call
- * ``pyodide.loadPackage(['numpy'])``. See also :js:func:`runPythonAsync`.
+ * ``pyodide.loadPackage(['numpy'])``.
  *
  * @param {string} code The code to inspect.
  * @param {LogFn=} messageCallback The ``messageCallback`` argument of
@@ -170,6 +170,13 @@ export function pyimport(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>`_.
  *
+ * .. 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
@@ -178,10 +185,10 @@ 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 len(packages['packages'].object_keys())
+ *        # If final statement is an expression, its value is returned to Javascript
+ *        len(packages.packages.object_keys())
  *    `);
- *    console.log(result); // 72
+ *    console.log(result); // 79
  *
  * @param {string} code Python code to evaluate
  * @returns {Py2JsResult} The result of the Python code translated to Javascript.