From a5da36d9f293a366cc2548a25acd9a74d1d295ff Mon Sep 17 00:00:00 2001
From: James J Balamuta <coatless@users.noreply.github.com>
Date: Thu, 29 Feb 2024 23:59:51 -0800
Subject: [PATCH] Add notes on external package installation (#10)

---
 ...qpyodide-document-engine-initialization.js |  5 +++-
 docs/qpyodide-code-cell-demo.qmd              | 24 +++++++++++++++++++
 docs/qpyodide-faq.qmd                         | 17 +++++++++++--
 3 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/_extensions/pyodide/qpyodide-document-engine-initialization.js b/_extensions/pyodide/qpyodide-document-engine-initialization.js
index 49f8106..865eb85 100644
--- a/_extensions/pyodide/qpyodide-document-engine-initialization.js
+++ b/_extensions/pyodide/qpyodide-document-engine-initialization.js
@@ -33,7 +33,10 @@ globalThis.qpyodideInstance = await import(
     // Setup a namespace for global scoping
     // await loadedPyodide.runPythonAsync("globalScope = {}"); 
 
-    // Add matplotlib
+    // Load the `micropip` package to allow installation of packages.
+    await mainPyodide.loadPackage("micropip");
+
+    // Load the `matplotlib` package with necessary environment hook
     await mainPyodide.loadPackage("matplotlib");
 
     // Set the backend for matplotlib to be interactive.
diff --git a/docs/qpyodide-code-cell-demo.qmd b/docs/qpyodide-code-cell-demo.qmd
index 1ee8ac1..1da0cef 100644
--- a/docs/qpyodide-code-cell-demo.qmd
+++ b/docs/qpyodide-code-cell-demo.qmd
@@ -148,6 +148,30 @@ import pandas as pd
 df.Age
 ```
 
+### Loading non-core Pyodide Python Packages
+
+In the above example, everything just worked as `pandas` in available as part of [Pyodide's built-in packages](https://pyodide.org/en/stable/usage/packages-in-pyodide.html). However, if we need a package that is not part of the built-in list, then there either needs to be a pure Python wheel (no compiled code present) or a specially compiled version of the Package for Python. 
+
+In this case, we can install the `seaborn` package from PyPI with: 
+
+```{pyodide-python}
+await micropip.install("seaborn")
+```
+
+Then, we have: 
+
+```{pyodide-python}
+import seaborn as sns
+
+import pandas as pd 
+
+data = np.random.multivariate_normal([0, 0], [[5, 2], [2, 2]], size=2000)
+data = pd.DataFrame(data, columns=['x', 'y'])
+
+sns.distplot(data['x'])
+sns.distplot(data['y']);
+```
+
 ## Graphing
 
 We provide support for generating graphs through the interactive HTML5 backend, e.g. [`module://matplotlib_pyodide.html5_canvas_backend`](https://github.com/pyodide/matplotlib-pyodide). At the end of each graph call, you must include a `plt.show()` call for the graph to render.
diff --git a/docs/qpyodide-faq.qmd b/docs/qpyodide-faq.qmd
index 1d19e5d..a49d9c7 100644
--- a/docs/qpyodide-faq.qmd
+++ b/docs/qpyodide-faq.qmd
@@ -58,9 +58,22 @@ To install the Quarto extension, please see our installation page.
 
 ### Can I use external libraries and packages in my Python cells?
 
-Yes, you can use external libraries and packages within your Python cells. Pyodide includes a wide range of pre-installed libraries, and you can also install additional packages by (TODO).
+Yes, you can use external libraries and packages within your Python cells. Pyodide includes a wide range of [pre-installed libraries](https://pyodide.org/en/stable/usage/packages-in-pyodide.html). These libraries can be downloaded and used on the fly once they are detected in an `import` statement. 
 
-<!-- using the standard `pip` syntax within your Python cells. -->
+You can also install additional packages by using the `micropip` package loaded at the start of each Pyodide session. These packages can either be pure Python packages (denoted by `*py3-none-any.whl` on PyPI) or Python packages compiled for Pyodide (denoted by `*-cp310-cp310-emscripten_3_1_27_wasm32.whl` that require a specific Python and Emscripten versions). For instance, the following will download and install the [`seaborn`](https://seaborn.pydata.org/) visualization library.
+
+```python
+import micropip
+micropip.install("seaborn")
+```
+
+Once done, please make sure to import the package: 
+
+```python
+import seaborn as sns
+```
+
+More details can be found on Pyodide's [Loading package](https://pyodide.org/en/stable/usage/loading-packages.html#installing-wheels-from-arbitrary-urls) documentation.
 
 
 ## Sharing Documents