ipyupload v0.1.3

Jupyter custom ipywidget: ipyupload

DEPRECATED
ipywidgets now includes an a file upoload core widget since version 7.5.
It is highly recommended to use it instead.

1 - Overview

This repo contains the source code and the building scripts for ipyupload a custom ipywidget.

It enables to upload a file from a Jupyter notebook - classic or JupyterLab.

It allows:

• single or multiple file upload
• to restrict the upload to certain file types
• to disable the file upload

Under the hood:

• The FileReader Web API is used.
• Data is read throught the readAsArrayBuffer() method, then converted to a DataView before syncing back to Python.
• The convertion to Python bytes uses the ipywidgets deserializer bytes_serialization already used for the Media core widget.
• The metadata are synced back as a List(Dict).
• The file contents are synced back as a List(Bytes).
• An Int counter is observed and upon change triggers the aggregation of the data and presentation to the user as a dict {filename: {metadata, file content in bytes}) in the .value property.
• Data can be compressed (optionally) from the browser (using pako.deflate) to the Python kernel (using zlib.decompress).

After an upload the button displays the number of files uploaded, to provide feedback to the user.

Naturally such an upload widget is mostly useful in a widgetized notebook and/or in a JupyterHub context, with a remote kernel.

2 - Install

2.1 - User Install

2.1.1 - Classic notebook

From terminal assuming notebook is installed:

# for notebook >= 5.3
$ pip install ipyupload

# for notebook < 5.3
$ pip install ipyupload
$ jupyter nbextension install ipyupload --py --sys-prefix

2.1.2 - JupyterLab

From terminal assuming jupyterlab is installed:

# if not installed already
$ jupyter labextension install @jupyter-widgets/jupyterlab-manager

$ jupyter labextension install ipyupload

2.2 - Developer Install

2.2.1 - Classic notebook

From terminal assuming notebook is installed:

$ git clone https://gitlab.com/oscar6echo/ipyupload.git
$ cd ipyupload/js
$ npm install
$ npm run watch # in another terminal
$ cd ..
$ pip install -e .
$ jupyter nbextension install --py --symlink --sys-prefix ipyupload
$ jupyter nbextension enable --py --sys-prefix ipyupload

2.2.2 - JupyterLab

From terminal assuming jupyterlab is installed:

# if not installed already
$ jupyter labextension install @jupyter-widgets/jupyterlab-manager

# from folder ipyupload
$ jupyter labextension link js

3 - Use

from IPython.display import display
from ipyupload import FileUpload

w = FileUpload(
    # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-accept
    # eg. '.txt', '.pdf', 'image/*', 'image/*,.pdf'
    accept='', # default
    # True to accept multiple files upload else False
    multiple=False, # default
    # True to disable the button else False to enable it
    disabled=False, # default
    # CSS transparently passed to button (a button element overlays the input[type=file] element for better styling)
    # e.g. 'color: darkblue; background-color: lightsalmon; width: 180px;'
    style_button='' # default
    # to compress data from browser to kernel
    # compress level from 1 to 9 incl. - 0 for no compression
    compress_level=0 # default
)
display(w)

For more examples:

• See the demo notebook on nbviewer.
• Run it on mybinder.org: