Merge pull request #2714 from pbugnion/update-file-upload-widget-documentation

Update file upload widget documentation

Author: jasongrout

docs/source/examples/Widget List.ipynb

@@ -958,7 +958,7 @@
    "source": [
     "## File Upload\n",
     "\n",
-    "The `FileUpload` allows to upload any type of file(s) as bytes."
+    "The `FileUpload` allows to upload any type of file(s) into memory in the kernel."
    ]
   },
   {
@@ -973,6 +973,74 @@
     ")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The upload widget exposes a `value` attribute that contains the files uploaded. The value attribute is a list with a dictionary for each upload. For instance:\n",
+    "\n",
+    "```python\n",
+    "uploader = widgets.FileUpload()\n",
+    "display(uploader)\n",
+    "\n",
+    "# upload something...\n",
+    "\n",
+    "# once a file is uploaded, use the `.value` attribute to retrieve the content:\n",
+    "uploader.value\n",
+    "#=> [\n",
+    "#=>   {\n",
+    "#=>     'metadata': {'name': 'example.txt', 'type': 'text/plain', 'size': 36, 'lastModified': 1578647380733}, \n",
+    "#=>     'content': <memory at 0x10c1b37c8>\n",
+    "#=>   }\n",
+    "#=> ]\n",
+    "```\n",
+    "\n",
+    "The contents of the file uploaded are in the value of the `content` key. They are a memory view:\n",
+    "\n",
+    "```python\n",
+    "[uploaded_file] = uploader.value\n",
+    "uploaded_file[\"content\"]\n",
+    "#=> <memory at 0x10c1b37c8>\n",
+    "```\n",
+    "\n",
+    "You can extract the content to bytes:\n",
+    "\n",
+    "```python\n",
+    "uploaded_file[\"content\"].tobytes()\n",
+    "#=> b'This is the content of example.txt.\\n'\n",
+    "```\n",
+    "\n",
+    "To get the contents as a string:\n",
+    "\n",
+    "```python\n",
+    "uploaded_file[\"content\"].tobytes().decode(\"utf-8\")\n",
+    "#=> 'This is the content of example.txt.\\n'\n",
+    "```\n",
+    "\n",
+    "You can save the uploaded file to the filesystem from the kernel:\n",
+    "\n",
+    "```python\n",
+    "with open(\"./saved-output.txt\", \"wb\") as fp:\n",
+    "    fp.write(uploaded_file[\"content\"])\n",
+    "```\n",
+    "\n",
+    "To convert the uploaded file into a Pandas dataframe, you need to convert it to a StringIO object:\n",
+    "\n",
+    "```python\n",
+    "pd.read_csv(io.StringIO(uploaded_file[\"content\"].tobytes().decode(\"utf-8\")))\n",
+    "```\n",
+    "\n",
+    "<div class=\"alert alert-info\">\n",
+    "Changes in *ipywidgets 8*:\n",
+    "    \n",
+    "The `FileUpload` changed significantly in ipywidgets 8:\n",
+    "    \n",
+    "- The `.value` traitlet is now a list of dictionaries with a `metadata` and `content` entry, rather than a dictionary mapping the uploaded name to the content. To retrieve the original form, use `{f[\"metadata\"][\"name\"]: f[\"content\"].tobytes() for f in uploader.value}`.\n",
+    "- The `.data` traitlet has been removed. To retrieve it, use `[f[\"content\"].tobytes() for f in uploader.value]`.\n",
+    "- The `.metadata` traitlet has been removed. To retrieve it, use `[f[\"metadata\"]. for f in uploader.value]`.\n",
+    "</div>"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},