Appearance

trame-jupyter-extension ​

The trame-jupyter-extension as opposed to server proxy will use the existing WebSocket connection to exchange data between the kernel and the client and serve the HTML content from the Jupyter web server.

For Jupyter Lab v3, you must use the "trame-jupyter-extension<2", while Jupyter Lab v4 will work with the latest version of the extension.

You can install the extension by running pip install trame-jupyter-extension or via the conda-forge channel.

Installation & validation steps ​

Setup your Jupyter Lab environment ​

sh
# Install MiniConda (Linux/Mac)
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

# Create env
mamba create --name trame-jupyter python=3.10 trame trame-vtk trame-vuetify jupyterlab trame-jupyter-extension
mamba activate trame-jupyter
# Install MiniConda (Linux/Mac)
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

# Create env
mamba create --name trame-jupyter python=3.10 trame trame-vtk trame-vuetify jupyterlab trame-jupyter-extension
mamba activate trame-jupyter
sh
# Create env
python3.9 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install trame trame-vtk trame-vuetify jupyterlab trame-jupyter-extension
# Create env
python3.9 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install trame trame-vtk trame-vuetify jupyterlab trame-jupyter-extension
sh
# Create env
python3.10 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install trame trame-vtk trame-vuetify jupyterlab trame-jupyter-extension
# Create env
python3.10 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install trame trame-vtk trame-vuetify jupyterlab trame-jupyter-extension
sh
# Create env
python3.11 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install trame trame-vtk trame-vuetify jupyterlab trame-jupyter-extension
# Create env
python3.11 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install trame trame-vtk trame-vuetify jupyterlab trame-jupyter-extension
sh
# Create env
python3.12 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install trame trame-vtk trame-vuetify jupyterlab trame-jupyter-extension setuptools
# Create env
python3.12 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install trame trame-vtk trame-vuetify jupyterlab trame-jupyter-extension setuptools

Enable extensions ​

Enable extensionsWhat you should see once enabled
(1) Accept warning(2) Extension in Installed list

Testing code ​

py
import os
from trame.app.demo import Cone

print(os.environ.get("TRAME_JUPYTER_WWW"))

app = Cone()
await app.ui.ready

print(app.ui._jupyter_content())

app.ui
import os
from trame.app.demo import Cone

print(os.environ.get("TRAME_JUPYTER_WWW"))

app = Cone()
await app.ui.ready

print(app.ui._jupyter_content())

app.ui
ipynb
{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "d5724592-b1fe-4209-825d-ddfd302cfd41",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "/var/folders/p_/hxjn_q0j2kg_16rfcdlc259hs_3p6n/T/tmpo5v2c2bh\n",
      "<iframe id=\"trame_trame__template_main\" src=\"http://localhost:8888/trame-jupyter-server/servers/trame/index.html?ui=main&server=trame&wsProxy&reconnect=auto\" style=\"border: none; width: 100%; height: 600px;\" data-kernel-id=\"f2e023bf-d327-4f24-9c9d-32b050d9e457\"></iframe>\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<iframe id=\"trame_trame__template_main\" src=\"http://localhost:8888/trame-jupyter-server/servers/trame/index.html?ui=main&server=trame&wsProxy&reconnect=auto\" style=\"border: none; width: 100%; height: 600px;\" data-kernel-id=\"f2e023bf-d327-4f24-9c9d-32b050d9e457\"></iframe>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import os\n",
    "from trame.app.demo import Cone\n",
    "\n",
    "print(os.environ.get(\"TRAME_JUPYTER_WWW\"))\n",
    "\n",
    "app = Cone()\n",
    "await app.ui.ready\n",
    "\n",
    "print(app.ui._jupyter_content())\n",
    "\n",
    "app.ui"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3b4c1232-7388-4025-9810-8c9f8b6ebb03",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.19"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "d5724592-b1fe-4209-825d-ddfd302cfd41",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "/var/folders/p_/hxjn_q0j2kg_16rfcdlc259hs_3p6n/T/tmpo5v2c2bh\n",
      "<iframe id=\"trame_trame__template_main\" src=\"http://localhost:8888/trame-jupyter-server/servers/trame/index.html?ui=main&server=trame&wsProxy&reconnect=auto\" style=\"border: none; width: 100%; height: 600px;\" data-kernel-id=\"f2e023bf-d327-4f24-9c9d-32b050d9e457\"></iframe>\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<iframe id=\"trame_trame__template_main\" src=\"http://localhost:8888/trame-jupyter-server/servers/trame/index.html?ui=main&server=trame&wsProxy&reconnect=auto\" style=\"border: none; width: 100%; height: 600px;\" data-kernel-id=\"f2e023bf-d327-4f24-9c9d-32b050d9e457\"></iframe>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import os\n",
    "from trame.app.demo import Cone\n",
    "\n",
    "print(os.environ.get(\"TRAME_JUPYTER_WWW\"))\n",
    "\n",
    "app = Cone()\n",
    "await app.ui.ready\n",
    "\n",
    "print(app.ui._jupyter_content())\n",
    "\n",
    "app.ui"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3b4c1232-7388-4025-9810-8c9f8b6ebb03",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.19"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}

The printed output should show that TRAME_JUPYTER_WWW exist and that the iframe(src=) use the same port as the Jupyter Lab server using a path like /trame-jupyter-server/servers/....

Illustration of validation test

Advanced Debugging Checklist ​

While the extension should just work, sometime things are not easy. This section, focus on the various steps needed to ensure that everything is a expected.

  1. The extension must be installed on the Jupyter Lab Server (not the kernel).
    • Test: In the browser, open the "Dev tools", and check if trameJupyter is available in the console.
    • TroubleShoot
      • Extension not available in python => pip install correct version
      • Extension not enabled in the Web UI
  2. Make sure the extension properly configured the Kernel
    • Test: In a Python cell the environment variable should not be empty
    python
    import os
print(os.environ.get("TRAME_JUPYTER_WWW"))
    import os
print(os.environ.get("TRAME_JUPYTER_WWW"))
    • TroubleShoot
      • Plugin failed to activate => ??
  3. Make sure the iframe_builder use the extension resolver
    • Test: In a Python cell run the following command and inspect the URL
    python
    app.ui._jupyter_content()
    app.ui._jupyter_content()
    • TroubleShoot
      • Plugin failed to activate => ??
      • Someone override the iframe_builder?

Copyright © 2021-present Kitware Inc.