Issue 1185 jupyter notebook

spine_items/category.py

@@ -16,7 +16,7 @@
 :date:   6.5.2020
 """
 # The categories will appear in the main window in the same order they are declared here.
-CATEGORIES = ("Data Stores", "Data Connections", "Tools", "Views", "Importers", "Exporters", "Manipulators")
+CATEGORIES = ("Data Stores", "Data Connections", "Tools", "Notebooks", "Views", "Importers", "Exporters", "Manipulators")
 
 
 CATEGORY_DESCRIPTIONS = {
@@ -25,6 +25,7 @@
     "Exporters": "Data conversion from Spine to an external format",
     "Importers": "Data conversion from an external format to Spine",
     "Tools": "Custom data processing",
+    "Notebooks": "Custom data processing with Jupyter notebooks",
     "Views": "Data visualization",
     "Manipulators": "Data conversion from Spine to Spine",
 }

spine_items/notebook/README.md

@@ -0,0 +1,96 @@
+## Overview
+
+This project item requires some initial configuration of conda environments in order to work correctly.
+
+In the context of this project item there are two classes of environment:
+
+1. Base environment: The base env is the conda environment from where the toolbox is launched. 
+
+   This environment along with having the usual dependencies, now requires the 
+   [nb_conda_kernels](https://github.com/Anaconda-Platform/nb_conda_kernels). <br>
+   This package allows the base env to discover kernels that have been configured to run Jupyter notebooks. <br>
+   This enables the user to configure environments per notebook they would like to execute.
+
+
+2. Notebook environment:  A notebook env is configured with the desired packages required by a notebook to execute.
+
+   To make a notebook env discoverable to the base env some setup is required. The notebook env requires ipykernel, 
+   with ipykernel installed the kernelspec for the env needs to be installed, this allows the base env to discover it. <br>
+   For installing the kernel spec see 
+   [Kernels for different environments](https://ipython.readthedocs.io/en/stable/install/kernel_install.html). 
+   With ipykernel and the kernelspec installed the user should install the packages required by the notebook.
+
+### Example env setup
+Below is an example of the steps required to setup both the base (toolbox) env and the notebook env.
+
+With Anaconda Prompt or equivalent terminal open.
+##### toolbox env setup
+
+> conda activate toolbox_env
+> 
+> conda install nb_conda_kernels
+
+#### notebook env setup
+> conda create test_env
+> 
+> conda activate test_env
+> 
+> conda install ipykernel
+> 
+> python -m ipykernel install --user --name test_env --display-name "Python (test_env)"
+
+The test_env will now be available to select from the notebook specification editor kernel select drop down menu. <br>
+The **--display-name** argument determines what is shown in the dropdown menu, so for the above env **Python (test_env)** <br>
+will be listed. 
+
+#### Configure environment for executing papermill
+For python environment setup 
+> pip install papermill
+
+Julia environment setup, in julia terminal.
+> add Conda
+> 
+> Conda.pip_interop(true)
+> 
+> Conda.pip("install", "papermill")
+> 
+> add PyCall
+
+See Julia packages [Conda](https://github.com/JuliaPy/Conda.jl) and [PyCall](https://github.com/JuliaPy/PyCall.jl)
+
+#### Discovering kernels on backend
+To discover installed kernel specs and add them to the drop down menu in the notebook specification editor <br>
+the notebook item uses **jupyter_client.kernelspec.KernelSpec** and **jupyter_client.kernelspec.KernelSpecManager** <br>
+see [kernelspec - discovering kernels](https://jupyter-client.readthedocs.io/en/stable/api/kernelspec.html). 
+
+In [notebook_specification_editor_window.py](https://github.com/Spine-project/spine-items/blob/issue_1185_jupyter_notebook/spine_items/notebook/widgets/notebook_specification_editor_window.py)
+kernels are discovered and added to the dropdown menu using the method **populate_available_kernel_list**. 
+
+```python
+    def populate_available_kernel_list(self):
+        ksm = KernelSpecManager()
+        specs = ksm.find_kernel_specs()
+        available_kernels = list()
+        for k_name, k_path in specs.items():
+            available_kernels.append(k_name)
+        return available_kernels
+```
+
+### Configure Jupyter notebook for execution
+For passing resources to the notebook at runtime, the notebook requires cell tags to be enabled, and a cell defined <br> 
+with the **parameters** tag. See image below to enable cell tags in Jupyter.
+
+![enable cell tags](readme_img/jupyter_cell_tags.png)
+
+Now add the **parameters** tag to the first cell in the notebook, this allows the notebook to be parameterized. <br>
+See [parameterize papermill](https://papermill.readthedocs.io/en/latest/usage-parameterize.html).
+
+In the notebook specification editor add the input/output variables that have been added to the parameters cell. <br> 
+
+
+
+
+
+
+
+

spine_items/notebook/__init__.py

@@ -0,0 +1,17 @@
+######################################################################################################################
+# Copyright (C) 2017-2020 Spine project consortium
+# This file is part of Spine Items.
+# Spine Items is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General
+# Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option)
+# any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+# without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
+# Public License for more details. You should have received a copy of the GNU Lesser General Public License along with
+# this program. If not, see <http://www.gnu.org/licenses/>.
+######################################################################################################################
+
+"""
+Notebook plugin.
+
+:author: R. Brady (UCD)
+:date:   29.12.2020
+"""

spine_items/notebook/commands.py

@@ -0,0 +1,38 @@
+######################################################################################################################
+# Copyright (C) 2017-2021 Spine project consortium
+# This file is part of Spine Items.
+# Spine Items is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General
+# Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option)
+# any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+# without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
+# Public License for more details. You should have received a copy of the GNU Lesser General Public License along with
+# this program. If not, see <http://www.gnu.org/licenses/>.
+######################################################################################################################
+
+"""
+Undo/redo commands for the Tool project item.
+
+:authors: M. Marin (KTH)
+:date:   5.5.2020
+"""
+from spine_items.commands import SpineToolboxCommand
+
+
+class UpdateToolExecuteInWorkCommand(SpineToolboxCommand):
+    def __init__(self, notebook, execute_in_work):
+        """Command to update Tool execute_in_work setting.
+
+        Args:
+            notebook (Notebook): the Notebook
+            execute_in_work (bool): True or False
+        """
+        super().__init__()
+        self.notebook = notebook
+        self.execute_in_work = execute_in_work
+        self.setText(f"change execute in work setting of {notebook.name}")
+
+    def redo(self):
+        self.notebook.do_update_execution_mode(self.execute_in_work)
+
+    def undo(self):
+        self.notebook.do_update_execution_mode(not self.execute_in_work)