Merge pull request #27 from takluyver/parameters-tag

Select parameters cell based on a 'parameters' tag

Author: takluyver

README.rst

@@ -1,5 +1,6 @@
 This is a tool to run notebooks with input values. When you write the notebook,
-these are defined in the first code cell, with regular assignments like this:
+these are defined in the first code cell - or a cell with a 'parameters' cell
+tag - with regular assignments like this:
 
 .. code-block:: python
 

nbparameterise/__init__.py

@@ -3,5 +3,5 @@
 __version__ = '0.5'
 
 from .code import (
-    Parameter, extract_parameters, replace_definitions, parameter_values,
+    Parameter, extract_parameters, replace_definitions, parameter_values, get_parameter_cell,
 )

nbparameterise/code.py

@@ -37,6 +37,21 @@ def __eq__(self, other):
                 and self.value == other.value
             )
 
+def get_parameter_cell(nb, tag='parameters'):
+    cell = find_first_tagged_cell(nb, tag)
+    if cell is None:
+        cell = first_code_cell(nb)
+    return cell
+
+def find_first_tagged_cell(nb, tag):
+    tag = tag.lower()
+    for cell in nb.cells:
+        if cell.cell_type == 'code':
+            tags = cell.get('metadata', {}).get('tags', [])
+            if any([i.lower() == tag for i in tags]):
+                return cell
+
+
 def first_code_cell(nb):
     for cell in nb.cells:
         if cell.cell_type == 'code':
@@ -52,31 +67,41 @@ def get_driver_module(nb, override=None):
     assert kernel_name_re.match(module_name)
     return importlib.import_module('nbparameterise.code_drivers.%s' % module_name)
 
-def extract_parameter_dict(nb, lang=None):
+def extract_parameter_dict(nb, lang=None, tag='Parameters'):
     """Returns a dictionary of Parameter objects derived from the notebook.
 
     This looks for assignments (like 'n = 50') in the first code cell of the
-    notebook. The parameters may also have some metadata stored in the notebook
-    metadata; this will be attached as the .metadata instance on each one.
+    notebook, or the first cell with a 'parameters' tag. The parameters may also
+    have some metadata stored in the notebook metadata; this will be attached as
+    the .metadata instance on each one.
 
-    lang may be used to override the kernel name embedded in the notebook. For
+    *lang* may be used to override the kernel name embedded in the notebook. For
     now, nbparameterise only handles 'python'.
+
+    *tag* specifies the cell tag which it will look for, with case-insensitive
+    matching. If no code cell has the tag, it will take the first code cell.
     """
-    params = extract_parameters(nb, lang)
+    params = extract_parameters(nb, lang, tag=tag)
     return {p.name: p for p in params}
 
-def extract_parameters(nb, lang=None):
+def extract_parameters(nb, lang=None, tag='Parameters'):
     """Returns a list of Parameter instances derived from the notebook.
 
     This looks for assignments (like 'n = 50') in the first code cell of the
-    notebook. The parameters may also have some metadata stored in the notebook
-    metadata; this will be attached as the .metadata instance on each one.
+    notebook, or the first cell with a 'parameters' tag. The parameters may also
+    have some metadata stored in the notebook metadata; this will be attached as
+    the .metadata instance on each one.
 
-    lang may be used to override the kernel name embedded in the notebook. For
+    *lang* may be used to override the kernel name embedded in the notebook. For
     now, nbparameterise only handles 'python'.
+
+    *tag* specifies the cell tag which it will look for, with case-insensitive
+    matching. If no code cell has the tag, it will take the first code cell.
     """
     drv = get_driver_module(nb, override=lang)
-    params = list(drv.extract_definitions(first_code_cell(nb).source))
+    cell = get_parameter_cell(nb,tag)
+
+    params = list(drv.extract_definitions(cell.source))
 
     # Add extra info from notebook metadata
     for param in params:
@@ -126,8 +151,8 @@ def parameter_values(params, new_values=None, new='ignore', **kwargs):
     return res
 
 def replace_definitions(nb, values, execute=False, execute_resources=None,
-                        lang=None, *, comments=True):
-    """Return a copy of nb with the first code cell defining the given parameters.
+                        lang=None, *, comments=True, tag='Parameters'):
+    """Return a copy of nb with the parameter cell defining the given parameters.
 
     values should be a dict (from :func:`extract_parameter_dict`) or a list
     (from :func:`extract_parameters`) of :class:`Parameter` objects,
@@ -138,8 +163,12 @@ def replace_definitions(nb, values, execute=False, execute_resources=None,
     and if possible should contain a 'path' key for the working directory in
     which to run the notebook.
 
-    lang may be used to override the kernel name embedded in the notebook. For
+    *lang* may be used to override the kernel name embedded in the notebook. For
     now, nbparameterise only handles 'python3' and 'python2'.
+
+    *tag* specifies the cell tag which the parameter cell should have, with
+    case-insensitive matching. If no code cell has the tag, it will replace the
+    first code cell.
     """
     if isinstance(values, list):
         values = {p.name: p for p in values}
@@ -148,12 +177,10 @@ def replace_definitions(nb, values, execute=False, execute_resources=None,
         warn("comments=False is now ignored", stacklevel=2)
 
     nb = copy.deepcopy(nb)
-    params_cell = first_code_cell(nb)
 
     drv = get_driver_module(nb, override=lang)
-    params_cell.source = drv.build_definitions(
-        values, prev_code=params_cell.source
-    )
+    cell = get_parameter_cell(nb, tag)
+    cell.source = drv.build_definitions(values, prev_code=cell.source)
     if execute:
         resources = execute_resources or {}
         nb, resources = ExecutePreprocessor().preprocess(nb, resources)

tests/sample_parameters_tag.ipynb

@@ -0,0 +1,69 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "woooo=\"1123\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "Parameters"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "a = \"Some text\"\n",
+    "b = 12\n",
+    "b2 = -7\n",
+    "c = 14.0\n",
+    "d = False  # comment:bool\n",
+    "e = [0, 1.0, True, \"text\", [0, 1]]\n",
+    "f = {0: 0, \"item\": True, \"dict\": {0: \"text\"}}  # comment:dict\n",
+    "print(\"This should be ignored\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "a, b, c, d, woooo"
+   ]
+  }
+ ],
+ "metadata": {
+  "celltoolbar": "Tags",
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.8.10"
+  },
+  "parameterise": {
+   "c": {
+    "display_name": "Sea"
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}

tests/test_basic.py

@@ -2,7 +2,7 @@
 import unittest
 
 import nbformat
-from nbparameterise import code, Parameter
+from nbparameterise import code, Parameter,get_parameter_cell
 
 samplenb = os.path.join(os.path.dirname(__file__), 'sample.ipynb')
 
@@ -50,11 +50,11 @@ def test_rebuild(self):
             self.params[4].with_value(True),
         ]
         nb = code.replace_definitions(self.nb, from_form, execute=False)
-
-        assert "# comment:bool" in nb.cells[0].source
+        cell = get_parameter_cell(nb)
+        assert "# comment:bool" in cell.source
 
         ns = {}
-        exec(nb.cells[0].source, ns)
+        exec(cell.source, ns)
         assert ns['a'] == "New text"
         assert ns['b'] == 21
         assert ns['b2'] == -3

tests/test_parameters_tag.py

@@ -0,0 +1,53 @@
+import os.path
+
+import pytest
+
+import nbformat
+from nbparameterise import (
+    extract_parameters, replace_definitions, Parameter, get_parameter_cell,
+)
+
+samplenb = os.path.join(os.path.dirname(__file__), 'sample_parameters_tag.ipynb')
+
+@pytest.fixture()
+def tagged_cell_nb():
+    return nbformat.read(samplenb, as_version=4)
+
+
+def test_extract(tagged_cell_nb):
+    # Tag is not case-sensitive
+    params =  extract_parameters(tagged_cell_nb, tag='paraMeters')
+    assert params == [
+        Parameter('a', str, "Some text"),
+        Parameter('b', int, 12),
+        Parameter('b2', int, -7),
+        Parameter('c', float, 14.0),
+        Parameter('d', bool, False),
+        Parameter('e', list, [0, 1.0, True, "text", [0, 1]]),
+        Parameter('f', dict, {0: 0, "item": True, "dict": {0: "text"}}),
+    ]
+    assert params[4].comment == '# comment:bool'
+    assert params[6].comment == '# comment:dict'
+    assert params[3].metadata == {'display_name': 'Sea'}
+
+def test_rebuild(tagged_cell_nb):
+    params = extract_parameters(tagged_cell_nb)
+    from_form = [
+        params[0].with_value("New text"),
+        params[1].with_value(21),
+        params[2].with_value(-3),
+        params[3].with_value(0.25),
+        params[4].with_value(True),
+    ]
+    nb = replace_definitions(tagged_cell_nb, from_form, execute=False)
+    cell = get_parameter_cell(nb, 'ParametErs')  # Not case-sensitive
+    assert "# comment:bool" in cell.source
+
+    ns = {}
+    exec(cell.source, ns)
+    assert ns['a'] == "New text"
+    assert ns['b'] == 21
+    assert ns['b2'] == -3
+    assert ns['c'] == 0.25
+    assert ns['d'] == True
+