adding a binder example

MANIFEST.in

@@ -32,3 +32,8 @@ global-exclude *.pyc
 global-exclude *.pyo
 global-exclude .git
 global-exclude .ipynb_checkpoints
+
+# Binder files to be excluded
+exclude binder
+recursive-exclude binder *.ipynb
+recursive-exclude binder *.txt

README.md

@@ -1,3 +1,4 @@
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jupyter/nbclient/master?filepath=binder%2Frun_nbclient.ipynb)
 [![Travis Build Status](https://travis-ci.org/jupyter/nbclient.svg?branch=master)](https://travis-ci.org/jupyter/nbclient)
 [![image](https://codecov.io/github/jupyter/nbclient/coverage.svg?branch=master)](https://codecov.io/github/jupyter/nbclient?branch=master)
 [![Python 3.5](https://img.shields.io/badge/python-3.5-blue.svg)](https://www.python.org/downloads/release/python-350/)

binder/empty_notebook.ipynb

@@ -0,0 +1,98 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Show a pandas dataframe"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pandas as pd\n",
+    "import numpy as np\n",
+    "import scrapbook as sb"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data = pd.DataFrame(np.random.randn(20, 2), columns=['a', 'b'])\n",
+    "data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Use scrapbook to store this data in the notebook\n",
+    "sb.glue('dataframe', data.to_dict())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Make a matplotlib plot"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Make and display a plot\n",
+    "fig, ax = plt.subplots()\n",
+    "ax.scatter(data['a'], data['b'])\n",
+    "sb.glue('plot', fig, 'display')"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.3"
+  },
+  "widgets": {
+   "application/vnd.jupyter.widget-state+json": {
+    "state": {},
+    "version_major": 2,
+    "version_minor": 0
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

binder/requirements.txt

@@ -0,0 +1,5 @@
+numpy
+pandas
+matplotlib
+nteract-scrapbook
+nbformat

binder/run_nbclient.ipynb

@@ -0,0 +1,118 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import nbclient\n",
+    "import nbformat as nbf\n",
+    "import pandas as pd\n",
+    "import scrapbook as sb"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Background\n",
+    "\n",
+    "This notebook uses `nbclient` to read and execute an *empty* notebook.\n",
+    "The empty notebook generates some fake data, makes a plot, and stores\n",
+    "both the data and the plot inside the notebook using the\n",
+    "[scrapbook package](https://github.com/nteract/scrapbook). We will\n",
+    "then be able to access the generated contents of the notebook here.\n",
+    "\n",
+    "You can see the empty notebook by clicking this button:\n",
+    "\n",
+    "<a href=\"empty_notebook.ipynb\"><button>Empty notebook</button></a>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Read and execute the empty notebook"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# We use nbformat to represent our empty notebook in-memory\n",
+    "nb = nbf.read('./empty_notebook.ipynb', nbf.NO_CONVERT)\n",
+    "\n",
+    "# Execute our in-memory notebook, which will now have outputs\n",
+    "nb = nbclient.execute(nb)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Inspect the new notebook for its contents"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# First we'll convert our nbformat NotebokNote into a *scrapbook* NotebookNode\n",
+    "nb = sb.read_notebook(nb)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# We can access the dataframe that was created and glued into the empty notebook\n",
+    "pd.DataFrame.from_dict(nb.scraps.get('dataframe').data).head()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# We can also access the generated plot by \"re-gluing\" the notebook here\n",
+    "nb.reglue('plot')"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.3"
+  },
+  "widgets": {
+   "application/vnd.jupyter.widget-state+json": {
+    "state": {},
+    "version_major": 2,
+    "version_minor": 0
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

docs/index.rst

@@ -10,6 +10,11 @@ NBClient lets you:
 Similar in nature to jupyter_client, as the jupyter_client is to the jupyter
 protocol nbclient is to notebooks allowing for execution contexts to be run.
 
+To demo **NBClient** interactively, click the Binder link below:
+
+.. image:: https://mybinder.org/badge_logo.svg
+    :target: https://mybinder.org/v2/gh/jupyter/nbclient/master?filepath=binder%2Frun_nbclient.ipynb
+
 Origins
 -------
 

setup.py

@@ -38,7 +38,8 @@ def read_reqs(fname):
 long_description = read(os.path.join(os.path.dirname(__file__), "README.md"))
 requirements = read(os.path.join(os.path.dirname(__file__), "requirements.txt"))
 dev_reqs = read_reqs('requirements-dev.txt')
-extras_require = {"test": dev_reqs, "dev": dev_reqs}
+binder_reqs = read_reqs(os.path.join('binder', 'requirements.txt'))
+extras_require = {"test": dev_reqs, "dev": dev_reqs, "binder": binder_reqs}
 
 setup(
     name=name,

tox.ini

@@ -51,3 +51,10 @@ basepython =
 deps = .[dev]
 commands =
     pytest -vv --maxfail=2 --cov=nbclient -W always {posargs}
+
+# Binder
+[testenv:binder]
+description = ensure /binder/*ipynb are runnable
+deps =
+    -r binder/requirements.txt
+commands = python -c "from glob import glob; from nbclient import execute; import nbformat as nbf; [execute(nbf.read(input, nbf.NO_CONVERT), cwd='./binder') for input in glob('binder/**/*.ipynb')]"