add notebook_vars utility with example notebook and unit test depicti…

…ng how it can be ised to construct a pytest fixture with the notebook state after execution (#39)

Co-authored-by: Sylwester Arabas <sylwester.arabas@agh.edu.pl>

.github/workflows/pylint.yml

@@ -20,7 +20,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip setuptools
-        pip install pylint
+        pip install pylint pytest
         python setup.py egg_info
         pip install -r *.egg-info/requires.txt
     - name: Analysing the code with pylint

README.md

@@ -10,5 +10,6 @@ Utility routines used in Jupyter notebooks in [PySDM](https://github.com/open-at
 - [``show_anim()``](https://open-atmos.github.io/jupyter-utils/open_atmos_jupyter_utils/show_anim.html) - a replacement for matplotlib's FuncAnimate() that inline-displays animations in gif format (thus github renderer compatible) and offers a way to download the .gif file (on Colab the widget triggers Google Drive download) 
 - [``TemporaryFile``](https://open-atmos.github.io/jupyter-utils/open_atmos_jupyter_utils/temporary_file.html) - a class equipped with ``make_link_widget()`` method returning a click-to-download Colab-compatible widget to be display()-ed in a Jupyter notebook
 - [``pip_install_on_colab('package_a', 'package_b', ...)``](https://open-atmos.github.io/jupyter-utils/open_atmos_jupyter_utils/pip_install_on_colab.html) - a function handling execution of ``pip`` (and ``ldconfig``) on Colab 
+- [``notebook_vars``](https://open-atmos.github.io/jupyter-utils/open_atmos_jupyter_utils/notebook_vars) - a function that executes Jupyter notebook and returns a dictionary with all variables notebook variables (variable names as keys) - useful in setting up automated tests for notebooks without modifying the notebooks (e.g., using pytest fixtures)
 
 public API docs are maintained at: https://open-atmos.github.io/jupyter-utils/

examples/notebook_vars_example.ipynb

@@ -0,0 +1,37 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "51913260-f89a-4237-bc7b-af5a0b1785f9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "a = 44\n",
+    "b = 666\n",
+    "c = a + b"
+   ]
+  }
+ ],
+ "metadata": {
+  "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.12.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

open_atmos_jupyter_utils/__init__.py

@@ -5,3 +5,4 @@
 from open_atmos_jupyter_utils.temporary_file import TemporaryFile
 from open_atmos_jupyter_utils.show_plot import show_plot, save_and_make_link
 from open_atmos_jupyter_utils.show_anim import show_anim
+from open_atmos_jupyter_utils.notebook_vars import notebook_vars

open_atmos_jupyter_utils/notebook_vars.py

@@ -0,0 +1,31 @@
+""" helper routines for use in smoke tests """
+
+from pathlib import Path
+
+import nbformat
+
+
+def notebook_vars(file: Path, plot: bool):
+    """Executes the code from all cells of the Jupyter notebook `file` and
+    returns a dictionary with the notebook variables. If the `plot` argument
+    is set to `True`, any code line within the notebook starting with `show_plot(`
+    (see [open_atmos_jupyter_utils docs](https://pypi.org/p/open_atmos_jupyter_utils))
+    is replaced with `pyplot.show() #`, otherwise it is replaced with `pyplot.gca().clear() #`
+    to match the smoke-test conventions."""
+    notebook = nbformat.read(file, nbformat.NO_CONVERT)
+    context = {}
+    for cell in notebook.cells:
+        if cell.cell_type != "markdown":
+            lines = cell.source.splitlines()
+            for i, line in enumerate(lines):
+                if line.strip().startswith("!"):
+                    lines[i] = line.replace("!", "pass #")
+                if line.strip().startswith("show_plot("):
+                    lines[i] = line.replace(
+                        "show_plot(",
+                        "from matplotlib import pyplot; "
+                        + ("pyplot.show() #" if plot else "pyplot.gca().clear() #"),
+                    )
+
+            exec("\n".join(lines), context)  # pylint: disable=exec-used
+    return context

pyproject.toml

@@ -18,6 +18,7 @@ dependencies = [
     "IPython",
     "matplotlib",
     "imageio",
+    "nbformat"
 ]
 [project.urls]
 "Homepage" = "https://github.com/open-atmos/jupyter-utils"

tests/test_notebook_vars.py

@@ -0,0 +1,22 @@
+"""
+test checking notebook_vars function
+"""
+
+from pathlib import Path
+import pytest
+
+from open_atmos_jupyter_utils import notebook_vars
+import examples
+
+@pytest.fixture(scope="session", name="notebook_variables")
+def notebook_variables_fixture():
+    """returns variables from the notebook """
+    print(examples.__file__)
+    return notebook_vars(
+        file=Path(examples.__file__).parent / "notebook_vars_example.ipynb",
+        plot=False,
+    )
+
+def test_notebook_vars(notebook_variables):
+    """ checks for a value known only after notebook execution"""
+    assert notebook_variables["c"] == notebook_variables["a"] + notebook_variables["b"]