Metadata-Version: 2.5
Name: jupyter-storage-explorer-launcher
Version: 0.31.1
Summary: Adds Jupyter Storage Explorer to the JupyterLab launcher, opening it in a tab
Project-URL: Homepage, https://github.com/sugibuchi/jupyter-storage-explorer/tree/main/launcher
Project-URL: Source, https://github.com/sugibuchi/jupyter-storage-explorer
Project-URL: Issues, https://github.com/sugibuchi/jupyter-storage-explorer/issues
Project-URL: Changelog, https://github.com/sugibuchi/jupyter-storage-explorer/releases
Author: Tsuyoshi SUGIBUCHI
License-Expression: MIT
License-File: LICENSE
Keywords: azure,data lake,file browser,fsspec,gcs,jupyter,jupyterlab,jupyterlab-extension,launcher,s3
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.11
Requires-Dist: jupyter-core>=5
Requires-Dist: jupyter-storage-explorer==0.31.1
Provides-Extra: abfs
Requires-Dist: jupyter-storage-explorer[abfs]; extra == 'abfs'
Provides-Extra: abfs-support
Requires-Dist: jupyter-storage-explorer[abfs-support]; extra == 'abfs-support'
Provides-Extra: all
Requires-Dist: jupyter-storage-explorer[all]; extra == 'all'
Provides-Extra: all-supports
Requires-Dist: jupyter-storage-explorer[all-supports]; extra == 'all-supports'
Provides-Extra: dask
Requires-Dist: jupyter-storage-explorer[dask]; extra == 'dask'
Provides-Extra: dask-support
Requires-Dist: jupyter-storage-explorer[dask-support]; extra == 'dask-support'
Provides-Extra: databricks
Requires-Dist: jupyter-storage-explorer[databricks]; extra == 'databricks'
Provides-Extra: databricks-support
Requires-Dist: jupyter-storage-explorer[databricks-support]; extra == 'databricks-support'
Provides-Extra: duckdb
Requires-Dist: jupyter-storage-explorer[duckdb]; extra == 'duckdb'
Provides-Extra: duckdb-support
Requires-Dist: jupyter-storage-explorer[duckdb-support]; extra == 'duckdb-support'
Provides-Extra: pandas
Requires-Dist: jupyter-storage-explorer[pandas]; extra == 'pandas'
Provides-Extra: pandas-support
Requires-Dist: jupyter-storage-explorer[pandas-support]; extra == 'pandas-support'
Provides-Extra: polars
Requires-Dist: jupyter-storage-explorer[polars]; extra == 'polars'
Provides-Extra: polars-support
Requires-Dist: jupyter-storage-explorer[polars-support]; extra == 'polars-support'
Provides-Extra: pyspark
Requires-Dist: jupyter-storage-explorer[pyspark]; extra == 'pyspark'
Provides-Extra: pyspark-support
Requires-Dist: jupyter-storage-explorer[pyspark-support]; extra == 'pyspark-support'
Description-Content-Type: text/markdown

# Jupyter Storage Explorer launcher

[![PyPI - Version](https://img.shields.io/pypi/v/jupyter-storage-explorer-launcher?color=blue)](https://pypi.org/project/jupyter-storage-explorer-launcher/)

Adds **Storage Explorer** to JupyterLab's launcher (section *Other*) and command palette. It opens
[Jupyter Storage Explorer](https://github.com/sugibuchi/jupyter-storage-explorer/blob/main/README.md) in its own tab, on
the folder JupyterLab's file browser shows.

![The Storage Explorer item in JupyterLab's launcher](https://raw.githubusercontent.com/sugibuchi/jupyter-storage-explorer/main/launcher/figs/launcher.png)

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](https://github.com/sugibuchi/jupyter-storage-explorer/blob/main/launcher/README.md#restart-the-side-panel).

<img src="https://raw.githubusercontent.com/sugibuchi/jupyter-storage-explorer/main/launcher/figs/side-panel.png" width="867" alt="The side panel in JupyterLab's left side bar, a Parquet file selected, beside the tab its View button opened in the data browser">


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.

```bash
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](https://jupyter-docker-stacks.readthedocs.io/) 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: see
  the example below.
- **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.

For a Docker Stacks image, a `Dockerfile` like this one builds an image with the launcher:

```dockerfile
FROM quay.io/jupyter/scipy-notebook

RUN pip install --no-cache-dir "jupyter-storage-explorer-launcher[polars]" && \
    fix-permissions "${CONDA_DIR}" && \
    fix-permissions "/home/${NB_USER}"
```

`fix-permissions` is the images' own script. It keeps the installed files writable by the notebook user.

### Extras

The launcher has the same extras as `jupyter-storage-explorer`
([Installation](https://github.com/sugibuchi/jupyter-storage-explorer/blob/main/docs/storage-explorer.md#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](https://github.com/sugibuchi/jupyter-storage-explorer/blob/main/plugins/README.md) 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.

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

Then read [Storages](https://github.com/sugibuchi/jupyter-storage-explorer/blob/main/docs/storage-explorer.md#storages)
to set up access to your storages, and
[Using the explorer](https://github.com/sugibuchi/jupyter-storage-explorer/blob/main/docs/storage-explorer.md#using-the-explorer).

## Configuration

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

<img src="https://raw.githubusercontent.com/sugibuchi/jupyter-storage-explorer/main/launcher/figs/settings-button.png" width="195" alt="The settings menu (a gear) after Unsafe mode in the tab's toolbar: Columns, Actions, Logging, Edit configuration and About">

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.

<img src="https://raw.githubusercontent.com/sugibuchi/jupyter-storage-explorer/main/launcher/figs/settings-editor.png" width="834" alt="launcher.py, created from the template, open in JupyterLab's editor beside the Storage Explorer tab">

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:

```python
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"}
```

[Configuration files](https://github.com/sugibuchi/jupyter-storage-explorer/blob/main/docs/storage-explorer.md#configuration-files)
describes the settings:

- each function of the file;
- `common.py`, the settings of every explorer, in notebooks too;
- the files administrators set up for everyone.

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

<img src="https://raw.githubusercontent.com/sugibuchi/jupyter-storage-explorer/main/launcher/figs/side-panel-restart.png" width="422" alt="JupyterLab's Running Terminals and Kernels panel, the Storage Explorer (side panel) kernel hovered, its Shut Down button 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](https://github.com/sugibuchi/jupyter-storage-explorer/blob/main/docs/storage-explorer.md#logs).
