Merge branch 'main' of github.com:mwakaba2/jupyterlab-notifications into main

Author: mwakaba2

README.md

@@ -20,6 +20,10 @@
 
 <img width="394" alt="Screen Shot 2021-07-31 at 12 49 49 PM" src="https://user-images.githubusercontent.com/3497137/127746862-79012afd-caa7-4319-930d-7acfc74fa2f4.png">
 
+*Image when recieving a notification on a mobilephone using ntfy*
+
+<img width="324" height="318" src="static/images/via_ntfy_sample.png">
+
 ## Quick demos and tutorials :notebook:
 
 To test out this extension without any local set-up, please check out the [binder link](https://mybinder.org/v2/gh/mwakaba2/jupyterlab-notifications/main?urlpath=lab/tree/tutorial/py3_demo.ipynb). This will set-up the environment, install the extension, and take you to several demo notebooks for you to play around with to get familiar with the notifications extension. 
@@ -80,6 +84,12 @@ Use the following settings to update cell execution time for a notification and
     // The minimum execution time to send out notification for a particular notebook cell (in seconds).
     "minimum_cell_execution_time": 60,
 
+    // Notification Methods
+    // Option to send a notification with the specified method(s). The available options are 'browser' and 'ntfy'.
+    "notification_methods": [
+        "browser"
+    ],
+
     // Report Notebook Cell Execution Time
     // Display notebook cell execution time in the notification. 
     // If last_cell_only is set to true, the total duration of the selected cells will be displayed.
@@ -106,6 +116,47 @@ Use the following settings to update cell execution time for a notification and
 
 The cell timing doesn't need to be enabled for Jupyterlab >= 3.1 and Jupyterlab notification version >= v0.3.0.
 
+## (Optional) Notifications using `ntfy`
+
+You can recieve notifications via `ntfy`.
+
+**ntfy 2.7.0 documentation** https://ntfy.readthedocs.io/en/latest/
+
+> ntfy brings notification to your shell. It can automatically provide desktop notifications when long running code executions finish or it can send push notifications to your phone when a specific execution finishes.
+
+### How to enable notifications via `ntfy`
+
+Install `ntfy`.
+
+```console
+$ pip install ntfy
+```
+To configure ntfy, please check out [the ntfy official configuration docs](https://ntfy.readthedocs.io/en/latest/#configuring-ntfy)
+
+For example, if your OS is Linux and you want to select `pushover` for the backend, set configuration as follows.
+
+```console
+$ vim ~/.config/ntfy/ntfy.yml
+```
+
+```yaml
+backends:
+    - pushover
+pushover:
+    user_key: YOUR_PUSHOVER_USER_KEY
+```
+
+Change the notifications [settings](#settings). Append `"ntfy"` into `notification_methods` attribute.
+- NOTE: The value `browser` implies default conventional method, which uses Webbrowser's Notification API.
+
+```json5
+{
+    // ...
+    "notification_methods": ["browser", "ntfy"]
+    // ...
+}
+```
+
 ## Contributing
 
 ### Development install

schema/plugin.json

@@ -39,6 +39,16 @@
       "title": "Trigger only for the last selected notebook cell execution.",
       "description": "Trigger a notification only for the last selected executed notebook cell.",
       "default": false
+    },
+    "notification_methods": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "enum": ["browser", "ntfy"]
+      },
+      "title": "Notification Methods",
+      "description": "Option to send a notification with the specified method(s). The available options are 'browser' and 'ntfy'.",
+      "default": ["browser"]
     }
   }
 }

src/index.ts

@@ -2,13 +2,15 @@ import {
   JupyterFrontEnd,
   JupyterFrontEndPlugin
 } from '@jupyterlab/application';
+import { ISessionContext, SessionContext } from '@jupyterlab/apputils';
 import { KernelError, Notebook, NotebookActions } from '@jupyterlab/notebook';
 import { Cell } from '@jupyterlab/cells';
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
 import { ICodeCellModel } from '@jupyterlab/cells';
 import { PageConfig } from '@jupyterlab/coreutils';
 import LRU from 'lru-cache';
 import moment from 'moment';
+import { issueNtfyNotification } from './ntfy';
 import { checkBrowserNotificationSettings } from './settings';
 
 interface ICellExecutionMetadata {
@@ -19,16 +21,18 @@ interface ICellExecutionMetadata {
 /**
  * Constructs notification message and displays it.
  */
-function displayNotification(
+async function displayNotification(
   cellDuration: string,
   cellNumber: number,
   notebookName: string,
   reportCellNumber: boolean,
   reportCellExecutionTime: boolean,
   failedExecution: boolean,
   error: KernelError | null,
-  lastCellOnly: boolean
-): void {
+  lastCellOnly: boolean,
+  notificationMethods: string[],
+  sessionContext: ISessionContext | null
+): Promise<void> {
   const base = PageConfig.getBaseUrl();
   const notificationPayload = {
     icon: base + 'static/favicon.ico',
@@ -52,13 +56,19 @@ function displayNotification(
   }
 
   notificationPayload.body = message;
-  new Notification(title, notificationPayload);
+
+  if (notificationMethods.includes('browser')) {
+    new Notification(title, notificationPayload);
+  }
+  if (notificationMethods.includes('ntfy') && sessionContext) {
+    await issueNtfyNotification(title, notificationPayload, sessionContext);
+  }
 }
 
 /**
  * Trigger notification.
  */
-function triggerNotification(
+async function triggerNotification(
   cell: Cell,
   notebook: Notebook,
   cellExecutionMetadataTable: LRU<string, ICellExecutionMetadata>,
@@ -69,7 +79,9 @@ function triggerNotification(
   cellNumberType: string,
   failedExecution: boolean,
   error: KernelError | null,
-  lastCellOnly: boolean
+  lastCellOnly: boolean,
+  notificationMethods: string[],
+  sessionContext: ISessionContext | null
 ) {
   const cellEndTime = new Date();
   const codeCellModel = cell.model as ICodeCellModel;
@@ -102,15 +114,17 @@ function triggerNotification(
           ? cellExecutionMetadata.index
           : codeCellModel.executionCount;
       const notebookName = notebook.title.label.replace(/\.[^/.]+$/, '');
-      displayNotification(
+      await displayNotification(
         cellDuration,
         cellNumber,
         notebookName,
         reportCellNumber,
         reportCellExecutionTime,
         failedExecution,
         error,
-        lastCellOnly
+        lastCellOnly,
+        notificationMethods,
+        sessionContext
       );
     }
   }
@@ -128,6 +142,8 @@ const extension: JupyterFrontEndPlugin<void> = {
     let reportCellNumber = true;
     let cellNumberType = 'cell_index';
     let lastCellOnly = false;
+    let notificationMethods = ['browser'];
+
     const cellExecutionMetadataTable: LRU<
       string,
       ICellExecutionMetadata
@@ -138,6 +154,13 @@ const extension: JupyterFrontEndPlugin<void> = {
       max: 500
     });
 
+    // SessionContext is used for running python codes
+    const manager = app.serviceManager;
+    const sessionContext = new SessionContext({
+      sessionManager: manager.sessions as any,
+      specsManager: manager.kernelspecs
+    });
+
     if (settingRegistry) {
       const setting = await settingRegistry.load(extension.id);
       const updateSettings = (): void => {
@@ -150,6 +173,8 @@ const extension: JupyterFrontEndPlugin<void> = {
           .composite as boolean;
         cellNumberType = setting.get('cell_number_type').composite as string;
         lastCellOnly = setting.get('last_cell_only').composite as boolean;
+        notificationMethods = setting.get('notification_methods')
+          .composite as string[];
       };
       updateSettings();
       setting.changed.connect(updateSettings);
@@ -165,10 +190,10 @@ const extension: JupyterFrontEndPlugin<void> = {
       }
     });
 
-    NotebookActions.executed.connect((_, args) => {
+    NotebookActions.executed.connect(async (_, args) => {
       if (enabled && !lastCellOnly) {
         const { cell, notebook, success, error } = args;
-        triggerNotification(
+        await triggerNotification(
           cell,
           notebook,
           cellExecutionMetadataTable,
@@ -179,16 +204,18 @@ const extension: JupyterFrontEndPlugin<void> = {
           cellNumberType,
           !success,
           error,
-          lastCellOnly
+          lastCellOnly,
+          notificationMethods,
+          sessionContext
         );
       }
     });
 
-    NotebookActions.selectionExecuted.connect((_, args) => {
+    NotebookActions.selectionExecuted.connect(async (_, args) => {
       if (enabled && lastCellOnly) {
         const { lastCell, notebook } = args;
         const failedExecution = false;
-        triggerNotification(
+        await triggerNotification(
           lastCell,
           notebook,
           cellExecutionMetadataTable,
@@ -199,7 +226,9 @@ const extension: JupyterFrontEndPlugin<void> = {
           cellNumberType,
           failedExecution,
           null,
-          lastCellOnly
+          lastCellOnly,
+          notificationMethods,
+          sessionContext
         );
       }
     });

src/ntfy.ts

@@ -0,0 +1,43 @@
+import { ISessionContext } from '@jupyterlab/apputils';
+import { Kernel, KernelAPI, KernelMessage } from '@jupyterlab/services';
+
+export async function ensureSessionContextKernelActivated(
+  sessionContext: ISessionContext
+): Promise<void> {
+  if (sessionContext.hasNoKernel) {
+    await sessionContext
+      .initialize()
+      .then(async value => {
+        if (value) {
+          const py3kernel = await KernelAPI.startNew({ name: 'python3' });
+          await sessionContext.changeKernel(py3kernel);
+        }
+      })
+      .catch(reason => {
+        console.error(
+          `Failed to initialize the session in jupyterlab-notifications.\n${reason}`
+        );
+      });
+  }
+}
+
+export async function issueNtfyNotification(
+  title: string,
+  notificationPayload: { body: string },
+  sessionContext: ISessionContext
+): Promise<
+  Kernel.IShellFuture<
+    KernelMessage.IExecuteRequestMsg,
+    KernelMessage.IExecuteReplyMsg
+  >
+> {
+  const { body } = notificationPayload;
+  await ensureSessionContextKernelActivated(sessionContext);
+  if (!sessionContext || !sessionContext.session?.kernel) {
+    return;
+  }
+  const titleEscaped = title.replace(/"/g, '\\"');
+  const bodyEscaped = body.replace(/"/g, '\\"');
+  const code = `from ntfy import notify; notify("${bodyEscaped}", "${titleEscaped}")`;
+  return sessionContext.session?.kernel?.requestExecute({ code });
+}