Jupyter Storage Explorer launcher

Adds Storage Explorer to JupyterLab's launcher (section Other) and command palette. It opens Jupyter Storage Explorer in its own tab, on the folder JupyterLab's file browser shows.

It also adds a side panel, a narrow explorer next to your notebooks:

• Open it with the Storage Explorer icon in the left side bar.
• The same storages as the tab; a folder's list, without the tree or the preview panel.
• Files you view (View, a double-click) open in new tabs.
• The filter button, left of ⚙, shows the filter.
• If it stops responding, see Restart the side panel.

It also integrates every Storage Explorer, in its tab or in a notebook, with JupyterLab:

• Drag and drop: drag files onto JupyterLab's file browser to download them there.
• Open files in a tab: double-click a file to open it in JupyterLab's own editor or viewer; Save writes it back to the storage.
• View in a new tab: open a table in the data browser, or another view (text, an image, ...), in a tab of its own.

Installation

Open a terminal in your JupyterLab and run the following. Then reload the page in your web browser.

pip install "jupyter-storage-explorer-launcher[polars]"

This installs the launcher in the Python environment of the default IPython kernel, which is usually JupyterLab's own. Requires JupyterLab 4.0 or later.

If the default kernel runs in another environment than JupyterLab's, install the launcher in both. JupyterLab loads the extension, and the kernel imports the Python package.

Persist the installation

An installation from a terminal is not kept in some environments:

• JupyterLab in a virtual environment, e.g. a venv or a conda environment: the installation stays in it.
• A Jupyter Docker Stacks image, e.g. quay.io/jupyter/scipy-notebook: the package is gone once the container is removed. To keep it, install it into the image's Python environment, in /opt/conda: RUN pip install ... in a Dockerfile starting FROM the image.
• JupyterHub: a user's server often runs in a container, e.g. a Docker Stacks image as above. Administrators install the launcher in the single-user environment.

Extras

The launcher has the same extras as jupyter-storage-explorer (Installation), of two kinds:

• Full extras, e.g. [polars]: the plugin and the libraries it uses.
• Support-only extras, e.g. [polars-support]: the plugin alone, using the libraries already installed. Nothing else is installed or upgraded.

Plugins lists the plugins, with their extras and libraries.

Full extras are handy for a quick try. Support-only extras are highly recommended for an IPython kernel whose data access packages are carefully installed and configured (e.g. a shared JupyterHub image): the plugins use what is there and never change it.

pip install "jupyter-storage-explorer-launcher[all-supports]"  # every plugin, with the libraries you have

Then read Storages to set up access to your storages, and Using the explorer.

Configuration

Click the ⚙ button at the right of the tab's toolbar, then Edit configuration.

It opens your settings, a Python file (launcher.py), in JupyterLab's editor; if you have none, it offers to create one from a template with an example of each setting.

Uncomment and edit the settings you need, then save. Open a new Storage Explorer tab, or reload the page, to apply the changes.

For example, to open each tab on the data lake and the folder it starts on, with a preview at once:

def filesystems():
    return {
        "Here": ".",  # the folder the tab opens on
        "Data lake": "abfs://lake@myaccount.dfs.core.windows.net",
    }


def parameters():
    return {"preview_panel": "open"}

Troubleshooting

Restart the side panel

The side panel runs in a kernel of its own. If the panel stops responding, restart that kernel:

1. Open JupyterLab's Running Terminals and Kernels panel in the left side bar.
2. Under Kernels, hover over the kernel named Storage Explorer (side panel), followed by its id.
3. Click its Shut Down button, a cross at the right.

The side panel then starts a new kernel and shows the explorer again.

Reloading the page is not enough when the kernel is stuck: the panel reconnects to the same kernel.

See the logs

The tabs and the side panel log nothing by default. To see what goes wrong in their kernels:

1. Click the ⚙ button at the right of the tab's toolbar, then Logging, and choose a level, e.g. INFO. The next tabs keep it.
2. Do what went wrong again.
3. Choose Open log file in the same menu, in the tab where it went wrong. The tab's file of the day opens in JupyterLab's editor, read-only.

The files are in the storage-explorer/logs folder of Jupyter's configuration directory: see Logs.

Configuration details

The configuration file, launcher.py, has some of these functions, all optional:

If your file has an error, the tab still opens, without your settings. The error shows above the explorer and in its status bar. Fix the file with the ⚙ button, then open the tab again. This covers errors raised by the file, settings that do not exist, and values the explorer refuses.

Layers of the configuration file

Administrators can set up the tab for everyone: a storage-explorer/launcher.py in any of Jupyter's configuration directories (jupyter --paths, config section) is read, e.g. /etc/jupyter/storage-explorer/launcher.py for the whole system or <environment>/etc/jupyter/storage-explorer/launcher.py for one Python environment (e.g. a JupyterHub image). Each file is a layer, applied from the system's to the user's, so users' files usually come last. A later layer adds to an earlier one's settings or replaces them.

final() returns the settings later layers cannot change: function names (except parameters) and parameter names. For example, /etc/jupyter/storage-explorer/launcher.py:

def filesystems():
    return {
        "Here": ".",
        "Data lake": "abfs://lake@myaccount.dfs.core.windows.net",
    }


def transfer_policy():
    # No downloads from the lake to users' computers or to the Jupyter server.
    return [
        {"rule": "deny", "src": r"abfs://lake@.*", "dest": "browser:///.*"},
        {"rule": "deny", "src": r"abfs://lake@.*", "dest": "jupyterlab://.*"},
    ]


def parameters():
    return {"unsafe_mode": "blocked"}  # no folder operations


def final():
    return ["filesystems", "transfer_policy", "unsafe_mode"]  # users cannot change these

Final settings are not a security boundary: users can still create explorers in notebooks.

An error in any file other than the user's stops the tab: it shows only the error, naming the file. Users' files are left out instead (see Configuration details).

Other configuration files

Your files are in Jupyter's configuration directory, which jupyter --config-dir prints: ~/.jupyter by default (on Windows, %USERPROFILE%\.jupyter), or $JUPYTER_CONFIG_DIR where that is set. launcher.py is in its storage-explorer folder.

Icons

To change the explorer's icons, use JupyterLab's custom.css (see Icons), which applies to the launcher's tabs and to explorers in notebooks alike.

Bookmarks and query settings

The tabs share bookmarks, the data browser's query settings, the engine chosen and the list's columns. They keep them in storage-explorer/states.json in the same directory, unless parameters() sets states (another file's path, or None: in each tab's memory).

The logging level chosen in the Logging menu is kept there too.