ENH: Add JupyterLite-powered shell for the website (reprise of #47428) (#60758)

Co-authored-by: Jeremy Tuloup <jtp@jtp.io>

Author: agriyakhetarpal

.github/workflows/docbuild-and-upload.yml

@@ -59,6 +59,10 @@ jobs:
     - name: Build documentation
       run: doc/make.py --warnings-are-errors
 
+    - name: Build the interactive terminal
+      working-directory: web/interactive_terminal
+      run: jupyter lite build
+
     - name: Build documentation zip
       run: doc/make.py zip_html
 

environment.yml

@@ -116,6 +116,13 @@ dependencies:
   - requests
   - pygments # Code highlighting
 
+  # web interactive REPL
+  # see the following links for more context:
+  # 1. https://jupyterlite-pyodide-kernel.readthedocs.io/en/stable/#compatibility
+  # 2. https://pyodide.org/en/stable/usage/packages-in-pyodide.html
+  - jupyterlite-core
+  - jupyterlite-pyodide-kernel
+
   - pip:
       - adbc-driver-postgresql>=0.10.0
       - adbc-driver-sqlite>=0.8.0

requirements-dev.txt

@@ -85,6 +85,8 @@ feedparser
 pyyaml
 requests
 pygments
+jupyterlite-core
+jupyterlite-pyodide-kernel
 adbc-driver-postgresql>=0.10.0
 adbc-driver-sqlite>=0.8.0
 typing_extensions; python_version<"3.11"

web/interactive_terminal/README.md

@@ -0,0 +1,38 @@
+# The interactive `pandas` REPL
+
+An interactive REPL to easily try `pandas` in the browser, powered by JupyterLite.
+
+![image](https://user-images.githubusercontent.com/591645/175000291-e8c69f6f-5f2c-48d7-817c-cff05ab2cde9.png)
+
+## Build
+
+The interactive REPL is built with the `jupyter lite` CLI.
+
+First make sure `jupyterlite` and a kernel are installed:
+
+```bash
+python -m pip install jupyterlite-core
+python -m pip install jupyterlite-pyodide-kernel
+```
+
+Then in `web/interactive_terminal`, run the following command:
+
+```bash
+jupyter lite build
+```
+
+## Configuration
+
+This folder contains configuration files for the interactive terminal powered by JupyterLite:
+
+- `jupyter_lite_config.json`: build time configuration, used when building the assets with the `jupyter lite build` command
+- `jupyter-lite.json` run time configuration applied when launching the application in the browser
+
+This interactive `pandas` JupyterLite deployment enables a couple of optimizations to only include the `repl` app in the generated static assets, and disables source maps, which can make the assets smaller and faster to load, at the cost of
+debugging capabilities.
+
+To learn more about it, check out the JupyterLite documentation:
+
+- Optimizations: https://jupyterlite.readthedocs.io/en/latest/howto/configure/advanced/optimizations.html
+- JupyterLite schema: https://jupyterlite.readthedocs.io/en/latest/reference/schema-v0.html
+- CLI reference: https://jupyterlite.readthedocs.io/en/latest/reference/cli.html

web/interactive_terminal/jupyter-lite.json

@@ -0,0 +1,10 @@
+{
+  "jupyter-lite-schema-version": 0,
+  "jupyter-config-data": {
+    "appName": "Pandas REPL",
+    "appUrl": "./repl",
+    "enableMemoryStorage": true,
+    "settingsStorageDrivers": ["memoryStorageDriver"],
+    "contentsStorageDrivers": ["memoryStorageDriver"]
+  }
+}

web/interactive_terminal/jupyter_lite_config.json

@@ -0,0 +1,8 @@
+{
+  "LiteBuildConfig": {
+    "apps": ["repl"],
+    "no_unused_shared_packages": true,
+    "output_dir": "../build/lite",
+    "no_sourcemaps": true
+  }
+}

web/pandas/getting_started.md

@@ -22,11 +22,23 @@ by [Wes McKinney](https://wesmckinney.com/), creator of pandas.
 
 ## Videos
 
-<iframe width="560" height="315" frameborder="0"
-src="https://www.youtube.com/embed/_T8LGqJtuGc"
-allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
-allowfullscreen></iframe>
+<iframe
+  src="https://www.youtube.com/embed/_T8LGqJtuGc"
+  style="width: 100%; max-width: 560px; height: 315px;"
+  frameborder="0"
+  allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+></iframe>
 
 ## Cheat sheet
 
 [pandas cheat sheet](https://pandas.pydata.org/Pandas_Cheat_Sheet.pdf)
+
+## Try pandas in your browser (experimental)
+
+You can try pandas in your browser with the following interactive shell
+without needing to install anything on your system.
+
+<p>
+    <a class="btn btn-primary" href="{{ base_url }}try.html">Try it in your browser</a>
+</p>

web/pandas/index.html

@@ -18,9 +18,9 @@ <h1>pandas</h1>
                     <div class="col-md-4">
                         <h5>Getting started</h5>
                         <ul>
-                            <!-- <li><a href="{{ base_url }}/try.html">Try pandas online</a></li> -->
                             <li><a href="{{ base_url }}getting_started.html">Install pandas</a></li>
                             <li><a href="{{ base_url }}docs/getting_started/index.html">Getting started</a></li>
+                            <li><a href="{{ base_url }}try.html">Try pandas online</a></li>
                         </ul>
                     </div>
                     <div class="col-md-4">

web/pandas/try.md

@@ -0,0 +1,12 @@
+# Try pandas in your browser (experimental)
+
+Try our experimental [JupyterLite](https://jupyterlite.readthedocs.io/en/stable/) live shell with `pandas`, powered by [Pyodide](https://pyodide.org/en/stable/).
+
+**Please note it can take a while (>30 seconds) before the shell is initialized and ready to run commands.**
+
+**Running it requires a reasonable amount of bandwidth and resources (>70 MiB on the first load), so it may not work properly on all devices or networks.**
+
+<iframe
+  src="./lite/repl/index.html?toolbar=1&kernel=python&execute=0&code=import%20pandas%20as%20pd%0Adf%20%3D%20pd.DataFrame%28%7B%22num_legs%22%3A%20%5B2%2C%204%5D%2C%20%22num_wings%22%3A%20%5B2%2C%200%5D%7D%2C%20index%3D%5B%22falcon%22%2C%20%22dog%22%5D%29%0Adf"
+  style="width: 100%; max-width: 650px; height: 600px; border: 1px solid #130753;"
+></iframe>