Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jpmorganchase/jupyter-fs

A filesystem-like contents manager for multiple backends in Jupyter
https://github.com/jpmorganchase/jupyter-fs

jupyter jupyter-lab jupyter-notebook jupyterlab jupyterlab-extension

Last synced: about 2 months ago
JSON representation

A filesystem-like contents manager for multiple backends in Jupyter

Host: GitHub
URL: https://github.com/jpmorganchase/jupyter-fs
Owner: jpmorganchase
License: apache-2.0
Created: 2019-09-24T17:44:10.000Z (almost 5 years ago)
Default Branch: main
Last Pushed: 2024-04-11T12:43:03.000Z (3 months ago)
Last Synced: 2024-04-14T03:11:27.375Z (3 months ago)
Topics: jupyter, jupyter-lab, jupyter-notebook, jupyterlab, jupyterlab-extension
Language: TypeScript
Homepage:
Size: 4.51 MB
Stars: 181
Watchers: 15
Forks: 35
Open Issues: 22
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Authors: AUTHORS

Lists

awesome-jupyter - jupyter-fs - A filesystem-like content manager for multiple backends in Jupyter. (JupyterLab Extensions)
awesome-jupyter-resources - GitHub - 23% open · ⏱️ 29.04.2022): (JupyterLab扩展)
best-of-jupyter - GitHub - 20% open · ⏱️ 04.06.2024): (JupyterLab Extensions)

README

A plugin for JupyterLab that lets you set up and use as many filebrowsers as you like, connected to whatever local and/or remote filesystem-like resources you want.

The backend is built on top of [PyFilesystem](https://github.com/PyFilesystem/pyfilesystem2), while the frontend is built on top of [JupyterLab Filetree](https://github.com/youngthejames/jupyterlab_filetree).

## Install

```bash
pip install jupyter-fs
```

## Configure

Add the following to your `jupyter_server_config.json`:

```json
{
"ServerApp": {
"contents_manager_class": "jupyterfs.metamanager.MetaManager",
"jpserver_extensions": {
"jupyterfs.extension": true
}
}
}
```

## Simple use (no auth/credentials)

Add specifications for additional contents managers in your user settings (in the **Settings** menu under **Advanced Settings Editor** -> **jupyter-fs**). Here's an example config that sets up several new filebrowsers side-by-side:

```json
{
"resources": [
{
"name": "root at test dir",
"url": "osfs:///Users/foo/test"
},
{
"name": "s3 test bucket",
"url": "s3://test"
},
{
"name": "s3 test key",
"url": "s3://test-2/prefix/",
"defaultWritable": false
},
{
"name": "samba guest share",
"url": "smb://[email protected]/test?name-port=3669"
}
]
}
```

You should see your new filebrowsers pop up in the left-hand sidebar instantly when you save your settings:

![](https://raw.githubusercontent.com/jpmorganchase/jupyter-fs/main/docs/osfs_example.png)

## Use with auth/credentials

Any stretch of a `"url"` that is enclosed in double-brackets `{{VAR}}` will be treated as a template, and will be handled by jupyter-fs's auth system. For example, you can pass a username/password to the `"samba guest share"` resource in the `Simple use` example above by modifying its `"url"` like so:

```json
{
"resources": [
...

{
"name": "samba share",
"url": "smb://{{user}}:{{passwd}}@127.0.0.1/test?name-port=3669"
}
]
}
```

When you save the above `"resouces"` config, a dialog box will pop asking for the `username` and `passwd` values:

![](https://raw.githubusercontent.com/jpmorganchase/jupyter-fs/main/docs/remote_example.png)

Once you enter those values and hit ok, the new filebrowsers will then immediately appear in the sidebar:

## The auth dialog will only appear when needed

The jupyter-fs auth dialog will only appear when:
- JupyterLab first loads, if any fs resources reqiure auth
- a new fs resouce is added that requires auth, or its `"url"` field is modified

## Supported filesystems

The type of resource each filebrowser will point to is determined by the protocol at the start of its url:

- **osfs**: **os** **f**ile**s**ystem. The will open a new view of your local filesystem, with the specified root
- **s3**: opens a filesystem pointing to an Amazon S3 bucket
- **smb**: opens a filesystem pointing to a Samba share

jupyter-fs can open a filebrowser pointing to any of the diverse [resources supported by PyFilesystem](). Currently, we test only test the S3 and smb/samba backends as part of our CI, so your milleage may vary with the other PyFilesystem backends.

## The filesystem url

The `"url"` field jupyter-fs config is based on the PyFilesystem [opener url](https://docs.pyfilesystem.org/en/latest/openers.html) standard. For more info on how to write these urls, see the documentation of the relevant PyFilesystem plugin:
- S3: [S3FS docs](https://fs-s3fs.readthedocs.io/en/latest/)
- smb: [fs.smbfs docs](https://github.com/althonos/fs.smbfs#usage)

## Server-side settings

If you prefer to set up your filesystem resources in the server-side config, you can do so. For example, you can set up a local filesystem by adding the following to your `jupyter_server_config.py` file:

```python
c.JupyterFs.resources = [
{
"name": "local_test",
"url": "osfs:///Users/foo/test"
},
]
```

ALternatively, you can add resource specifications alongside the basic jupyter-fs config in your `jupyter_server_config.json` file:

```json
{
"ServerApp": {
"contents_manager_class": "jupyterfs.metamanager.MetaManager",
"jpserver_extensions": {
"jupyterfs.extension": true
}
},
"JupyterFs": {
"resources": [
{
"name": "local_test",
"url": "osfs:///Users/foo/test"
}
]
}
}
```

Any filesystem resources specified in any server-side config file will be merged with the resources given in a user's settings.

## Development

See [CONTRIBUTING.md](https://github.com/jpmorganchase/jupyter-fs/blob/main/CONTRIBUTING.md) for guidelines.

## License

This software is licensed under the Apache 2.0 license. See the
[LICENSE](https://github.com/jpmorganchase/jupyter-fs/blob/main/LICENSE) and [AUTHORS](https://github.com/jpmorganchase/jupyter-fs/blob/main/AUTHORS) files for details.