Initial commit

Author: AndiH

README.md

@@ -0,0 +1,48 @@
+# Jupyter Notebook Splitter
+
+This tool splits a Jupyter Notebook into Sub-Notebooks depending on cell metadata. It converts a *Master* Notebook into a *Teacher* Notebook and a *Student* Notebook; or into a *Slides* Notebook, a *Tasks* Notebook, and a *Solutions* Notebook.
+
+## Installation
+
+Please, for now, download the script and place it into the folder where you want to split Notebooks in.
+
+## Usage
+
+### Overview
+
+**TL;DR: See `./notebook-splitter.py --help`.**
+
+1. Add [cell metadata](https://ipython.org/ipython-doc/3/notebook/nbformat.html#cell-metadata) to your Jupyter Notebook: Add an `exercise` key (default, can be changed) to the metadata (JSON); give it values (*tags*) on which to create Sub-Notebooks
+
+    ```json
+    {
+        "exercise": "task"
+    }
+    // another cell
+    {
+        "exercise": "solution"
+    }
+    ```
+
+2. Use `--keep` and `--remove` flags of the Notebook Splitter to keep and remove cells with according *tags*; export it to the respective Notebook:
+
+    ```bash
+    ./notebook-splitter.py input.ipynb --keep task --remove solution   -o tasks.ipynb
+    ./notebook-splitter.py input.ipynb --keep solution --remove task   -o solutions.ipynb
+    ./notebook-splitter.py input.ipynb --remove task --remove solution -o slides.ipynb
+    ```
+
+### Examples in Action
+
+See the `examples` directory in this repository.
+
+### Options
+
+* **Repeated Parameters**: `--keep` and `--remove` parameters on the command line of the script can be given multiple times: `--keep task --keep onlytask --remove solution`
+* **Remove *All***: As a special parameter value, `--remove all` will remove *all* cells except those for which a `--keep` value is specified (*`--keep all`* is the default)
+* **Stdin/Stdout**: If no output file is given with `-o`/`--output`, the resulting Notebook will be printed to `stdout`; if no input file as a parameter is given, the input Notebook will be read from `stdin` (good for Linux-like daisy-chaining of tools)
+* **Change *Basekey***: In the above example, the cell meta data key of discrimination is `exercise` which is the default. With `--basekey`, this can be changed.
+
+### Limitations
+
+The values to the `--keep` and `--remove` parameters create sets of values to keep and remove. One could implement this tool probably quite cleverly with set operations (with the added complication of the `--remove all` ). If you can, feel free to file a merge request!

examples/.gitignore

@@ -0,0 +1 @@
+.ipynb_checkpoints

examples/Makefile

@@ -0,0 +1,20 @@
+NB_MASTER   = Notebook-Master.ipynb
+
+NB_EMPTY    = Notebook-Empty.ipynb
+NB_TASK     = Notebook-Task.ipynb
+NB_SOLUTION = Notebook-Solution.ipynb
+
+.PHONY: all clean
+all: $(NB_SOLUTION) $(NB_TASK) $(NB_EMPTY)
+
+$(NB_TASK): $(NB_MASTER) Makefile
+	../notebook-splitter.py $< --keep task --remove solution -o $@
+	
+$(NB_SOLUTION): $(NB_MASTER) Makefile
+	../notebook-splitter.py $< --keep solution --remove task -o $@
+
+$(NB_EMPTY): $(NB_MASTER) Makefile
+	../notebook-splitter.py $< --keep even-empty --remove all -o $@
+
+clean:
+	rm $(NB_SOLUTION) $(NB_TASK) $(NB_EMPTY)

examples/Notebook-Empty.ipynb

@@ -0,0 +1 @@
+{"cells": [{"cell_type": "markdown", "metadata": {"exercise": "even-empty"}, "source": ["This cell is included in every Sub-Notebook, even the [*Empty* Notebook](Notebook-Empty.ipynb)"]}], "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.2"}}, "nbformat": 4, "nbformat_minor": 2}

examples/Notebook-Master.ipynb

@@ -0,0 +1,59 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Notebook Splitter Demo"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "exercise": "even-empty"
+   },
+   "source": [
+    "This cell is included in every Sub-Notebook, even the [*Empty* Notebook](Notebook-Empty.ipynb)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "exercise": "task"
+   },
+   "source": [
+    "This cell is included in the [*Task* Notebook](Notebook-Task.ipynb), but not in the *Solution* Notebook"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "exercise": "solution"
+   },
+   "source": [
+    "This cell is included in the [*Solution* Notebook](Notebook-Solution.ipynb), but not in the *Task* Notebook"
+   ]
+  }
+ ],
+ "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.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

examples/Notebook-Solution.ipynb

@@ -0,0 +1 @@
+{"cells": [{"cell_type": "markdown", "metadata": {}, "source": ["# Notebook Splitter Demo"]}, {"cell_type": "markdown", "metadata": {"exercise": "even-empty"}, "source": ["This cell is included in every Sub-Notebook, even the [*Empty* Notebook](Notebook-Empty.ipynb)"]}, {"cell_type": "markdown", "metadata": {"exercise": "solution"}, "source": ["This cell is included in the [*Solution* Notebook](Notebook-Solution.ipynb), but not in the *Task* Notebook"]}], "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.2"}}, "nbformat": 4, "nbformat_minor": 2}

examples/Notebook-Task.ipynb

@@ -0,0 +1 @@
+{"cells": [{"cell_type": "markdown", "metadata": {}, "source": ["# Notebook Splitter Demo"]}, {"cell_type": "markdown", "metadata": {"exercise": "even-empty"}, "source": ["This cell is included in every Sub-Notebook, even the [*Empty* Notebook](Notebook-Empty.ipynb)"]}, {"cell_type": "markdown", "metadata": {"exercise": "task"}, "source": ["This cell is included in the [*Task* Notebook](Notebook-Task.ipynb), but not in the *Solution* Notebook"]}], "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.2"}}, "nbformat": 4, "nbformat_minor": 2}

notebook-splitter.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+# Andreas Herten, 25 February 2019
+import json
+import copy
+import os
+import sys
+import argparse
+import textwrap
+
+
+def parse(inputfile, keep, remove, basekey):
+    """
+    From inputfile, parse the JSON and remove those cells which have values of the basekey, which are in the list of tags to remove but not in the list of tags to remove.
+    """
+    notebook = json.load(inputfile)
+
+    if isinstance(keep, str): keep = [keep]
+    if isinstance(remove, str): remove = [remove]
+
+    notebook_new = copy.deepcopy(notebook)
+    notebook_new["cells"] = []
+
+    for cell in notebook["cells"]:
+        keepcell = True
+        for key in remove:
+            cell_tags = None
+            if basekey in cell["metadata"]:
+                cell_tags = cell["metadata"][basekey]
+                if isinstance(cell_tags, str): cell_tags = [cell_tags]
+            if cell_tags == None:
+                if key == "all":
+                    keepcell = False
+            if cell_tags != None:
+                if key in cell_tags or key == "all":
+                    for tag in cell_tags:
+                        if tag not in keep:
+                            keepcell = False
+        if keepcell == True:
+            notebook_new["cells"].append(cell)
+
+    return notebook_new
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=textwrap.dedent("""
+        Split up Jupyter Notebook to Sub-Notebooks by cell metadata.
+
+        Specify tags to keep with `--keep`, specify tags to remove with `--remove`; multiple instances are ok. Special `--remove` tag: all (which removes all cells except those specified with `--keep`).
+        All tags will be read from BASEKEY, which usually is `exercise`, if you do not specify it differently.
+        """), formatter_class=argparse.RawTextHelpFormatter)
+    parser.add_argument('infile', type=argparse.FileType('r'), nargs='?', default=sys.stdin, help="Input file to parse")
+    parser.add_argument('--output', "-o", nargs='?', type=argparse.FileType('w'), default=sys.stdout, help="Output file to parse to")
+    parser.add_argument('--keep',   "-k", action="append", help="Keep these tags.")
+    parser.add_argument('--remove', "-r", action="append", help="Remove these tags. Special: all (remove all except for those of --keep).")
+    parser.add_argument('--basekey', type=str, help="Basekey to use for discriminating the tags.", default="exercise")
+    args = parser.parse_args()
+    notebook = parse(inputfile=args.infile, keep=args.keep, remove=args.remove, basekey=args.basekey)
+
+    json.dump(notebook, args.output)