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.

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

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

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.

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

Install it in the environment of JupyterLab and of the default kernel (on JupyterHub, usually the single-user image), then restart JupyterLab. Requires JupyterLab 4.0 or later.

Or from JupyterLab itself, without a terminal: run this in a notebook, then reload the page (no restart needed):

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

This works when the notebook's kernel runs in JupyterLab's own environment, as the default kernel usually does.

Then see 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"}

The file has some of these functions, all optional:

The side panel uses the same settings, except its own layout: height, tree_view, preview_panel and layout are not taken from parameters() there.

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.

For extending the explorer in Python (Developing plugins), tried before the defaults: supports() (FormatSupport: formats and the libraries handling them), operations() (FileSystemOperations) and filesystem_mappers() (FileSystemMapper).

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).

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 changes an earlier one's settings this way:

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).