jupyterlab-pioneer 0.1.2 → 0.1.4

package/README.md

@@ -1,4 +1,4 @@
-# JupyterLab Pioneer 
+# JupyterLab Pioneer
 
 [![PyPI](https://img.shields.io/pypi/v/jupyterlab-pioneer.svg)](https://pypi.org/project/jupyterlab-pioneer)
 [![npm](https://img.shields.io/npm/v/jupyterlab-pioneer.svg)](https://www.npmjs.com/package/jupyterlab-pioneer)
@@ -8,12 +8,16 @@ A JupyterLab extension for generating and exporting JupyterLab event telemetry d
 ## Get started
 
 ### Run the extension with docker compose
+
 ```bash
 # enter the configuration_examples directory and run
 docker compose -p jupyterlab-pioneer up --build
 ```
- A JupyterLab application with the extension installed and configured will run on localhost:8888.
- 
+
+A JupyterLab application with the extension installed and configured will run on localhost:8888.
+
+(To play with different exporter configurations, edit [Dockerfile](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/configuration_examples/Dockerfile#L32-L36) and run docker compose again)
+
 ### Or install the extension and configure it manually
 
 To install the extension, execute:
@@ -21,15 +25,27 @@ To install the extension, execute:
 ```bash
 pip install jupyterlab-pioneer
 ```
+
 Before starting Jupyter Lab, users need to write their own configuration files (or use the provided configuration examples) and **place them in the correct directory**.
 
 Examples of configurations are [here](#configurations).
 
 ## Configurations
+
 ### Overview
+
 The configuration file controls the activated events and data exporters.
 
-To add a data exporter, users should assign a callable function along with function arguments when configuring `exporters`. This extension provides 4 [default exporters](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/b7eda5f4b286c7b0f7aa50df716b2795f180cc6e/jupyterlab_pioneer/handlers.py#L9), `command_line_exporter`, `console_exporter`, `file_exporter` and `remote_exporter`. Users can import default exporters or write customized exporters in the configuration file.
+To add a data exporter, users should assign a callable function along with function arguments when configuring `exporters`.
+
+This extension provides 4 default exporters.
+
+- [`console_exporter`](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/jupyterlab_pioneer/handlers.py#L10), which sends telemetry data to the browser console
+- [`command_line_exporter`](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/jupyterlab_pioneer/handlers.py#L33), which sends telemetry data to the python console jupyter is running on
+- [`file_exporter`](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/jupyterlab_pioneer/handlers.py#L55), which saves telemetry data to local file
+- [`remote_exporter`](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/jupyterlab_pioneer/handlers.py#L81), which sends telemetry data to a remote http endpoint
+
+Additionally, users can import default exporters or write customized exporters in the configuration file.
 
 ### Configuration file name & path
 
@@ -38,6 +54,7 @@ Jupyter Server expects the configuration file to be named after the extension’
 Jupyter Server looks for an extension’s config file in a set of specific paths. **The configuration file should be saved into one of the config directories provided by `jupyter --path`.**
 
 Check jupyter server [doc](https://jupyter-server.readthedocs.io/en/latest/operators/configuring-extensions.html) for more details.
+
 ### Syntax
 
 `activateEvents`: An array of the ids of the events. Only valid events (1. has an id associated with the event class, and 2. the event id is included in `activatedEvents`) will be activated.
@@ -45,16 +62,23 @@ Check jupyter server [doc](https://jupyter-server.readthedocs.io/en/latest/opera
 `logNotebookContentEvents`: An array of the ids of the events. The extension will export the entire notebook content only for valid events (1. has an id associated with the event class, and 2. the event id is included in `logNotebookContentEvents`).
 
 `exporters`: An array of exporters. Each exporter should have the following structure:
+
 ```python
 {
     exporter: # a callable exporter function. Need to contain 'path' for file_exporter, 'url' for remote_exporter.
     args: # arguments passed to the exporter function
 }
 ```
-**The configuration file should be saved into one of the config directories provided by `jupyter --path`.**
 
 ### Example
-[jupyter_jupyterlab_pioneer_config.py](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/configuration_examples/jupyter_jupyterlab_pioneer_config.py)
+
+#### Default exporters
+
+[all_exporters/jupyter_jupyterlab_pioneer_config.py](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/configuration_examples/all_exporters/jupyter_jupyterlab_pioneer_config.py)
+
+#### Custom exporter function
+
+[custom_exporter/jupyter_jupyterlab_pioneer_config.py](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/configuration_examples/custom_exporter/jupyter_jupyterlab_pioneer_config.py)
 
 ## Uninstall
 

package/lib/index.d.ts

@@ -1,3 +1,13 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
-declare const plugin: JupyterFrontEndPlugin<void>;
+import { Token } from '@lumino/coreutils';
+import { Router } from './router';
+export declare const IJupyterLabPioneer: Token<IJupyterLabPioneer>;
+export interface IJupyterLabPioneer {
+    router: Router;
+}
+declare class JupyterLabPioneer implements IJupyterLabPioneer {
+    router: Router;
+    constructor();
+}
+declare const plugin: JupyterFrontEndPlugin<JupyterLabPioneer>;
 export default plugin;

package/lib/index.js

@@ -1,26 +1,35 @@
 import { INotebookTracker } from '@jupyterlab/notebook';
-import { TelemetryRouter } from './router';
+import { Token } from '@lumino/coreutils';
 import { requestAPI } from './handler';
-import { producerCollection } from './events';
+import { Router } from './router';
+import { producerCollection } from './producer';
 const PLUGIN_ID = 'jupyterlab-pioneer:plugin';
+export const IJupyterLabPioneer = new Token(PLUGIN_ID);
+class JupyterLabPioneer {
+    constructor() {
+        this.router = new Router();
+    }
+}
 const plugin = {
     id: PLUGIN_ID,
     autoStart: true,
     requires: [INotebookTracker],
+    provides: IJupyterLabPioneer,
     activate: async (app, notebookTracker) => {
         const version = await requestAPI('version');
         console.log(`${PLUGIN_ID}: ${version}`);
         const config = await requestAPI('config');
-        const telemetryRouter = new TelemetryRouter();
+        const pioneer = new JupyterLabPioneer();
         notebookTracker.widgetAdded.connect(async (_, notebookPanel) => {
             await notebookPanel.sessionContext.ready; // wait until session id is created
-            await telemetryRouter.loadNotebookPanel(notebookPanel);
+            await pioneer.router.loadNotebookPanel(notebookPanel);
             producerCollection.forEach(producer => {
                 if (config.activeEvents.includes(producer.id)) {
-                    new producer().listen(notebookPanel, telemetryRouter, config.logNotebookContentEvents.includes(producer.id));
+                    new producer().listen(notebookPanel, pioneer, config.logNotebookContentEvents.includes(producer.id));
                 }
             });
         });
+        return pioneer;
     }
 };
 export default plugin;

package/lib/producer.d.ts

@@ -0,0 +1,53 @@
+import { NotebookPanel } from '@jupyterlab/notebook';
+import { IJupyterLabPioneer } from './index';
+export declare class NotebookOpenEventProducer {
+    static id: string;
+    private produced;
+    listen(_: NotebookPanel, pioneer: IJupyterLabPioneer, logNotebookContentEvent: boolean): Promise<void>;
+}
+export declare class NotebookScrollProducer {
+    static id: string;
+    private timeout;
+    listen(notebookPanel: NotebookPanel, pioneer: IJupyterLabPioneer, logNotebookContentEvent: boolean): void;
+}
+export declare class NotebookVisibleEventProducer {
+    static id: string;
+    listen(notebookPanel: NotebookPanel, pioneer: IJupyterLabPioneer, logNotebookContentEvent: boolean): void;
+}
+export declare class NotebookHiddenEventProducer {
+    static id: string;
+    listen(_: NotebookPanel, pioneer: IJupyterLabPioneer, logNotebookContentEvent: boolean): void;
+}
+export declare class ClipboardCopyEventProducer {
+    static id: string;
+    listen(notebookPanel: NotebookPanel, pioneer: IJupyterLabPioneer, logNotebookContentEvent: boolean): void;
+}
+export declare class ClipboardCutEventProducer {
+    static id: string;
+    listen(notebookPanel: NotebookPanel, pioneer: IJupyterLabPioneer, logNotebookContentEvent: boolean): void;
+}
+export declare class ClipboardPasteEventProducer {
+    static id: string;
+    listen(notebookPanel: NotebookPanel, pioneer: IJupyterLabPioneer, logNotebookContentEvent: boolean): void;
+}
+export declare class ActiveCellChangeEventProducer {
+    static id: string;
+    listen(notebookPanel: NotebookPanel, pioneer: IJupyterLabPioneer, logNotebookContentEvent: boolean): void;
+}
+export declare class NotebookSaveEventProducer {
+    static id: string;
+    listen(notebookPanel: NotebookPanel, pioneer: IJupyterLabPioneer, logNotebookContentEvent: boolean): void;
+}
+export declare class CellExecuteEventProducer {
+    static id: string;
+    listen(_: any, pioneer: IJupyterLabPioneer, logNotebookContentEvent: boolean): void;
+}
+export declare class CellAddEventProducer {
+    static id: string;
+    listen(notebookPanel: NotebookPanel, pioneer: IJupyterLabPioneer, logNotebookContentEvent: boolean): void;
+}
+export declare class CellRemoveEventProducer {
+    static id: string;
+    listen(notebookPanel: NotebookPanel, pioneer: IJupyterLabPioneer, logNotebookContentEvent: boolean): void;
+}
+export declare const producerCollection: (typeof NotebookVisibleEventProducer)[];

package/lib/{events.js → producer.js}

@@ -4,7 +4,7 @@ class NotebookOpenEventProducer {
     constructor() {
         this.produced = false;
     }
-    async listen(_, router, logNotebookContentEvent) {
+    async listen(_, pioneer, logNotebookContentEvent) {
         if (!this.produced) {
             const event = {
                 eventName: NotebookOpenEventProducer.id,
@@ -13,7 +13,7 @@ class NotebookOpenEventProducer {
                     environ: await requestAPI('environ')
                 }
             };
-            await router.publishEvent(event, logNotebookContentEvent);
+            await pioneer.router.publishEvent(event, logNotebookContentEvent);
             this.produced = true;
         }
     }
@@ -42,7 +42,7 @@ class NotebookScrollProducer {
     constructor() {
         this.timeout = 0;
     }
-    listen(notebookPanel, router, logNotebookContentEvent) {
+    listen(notebookPanel, pioneer, logNotebookContentEvent) {
         notebookPanel.content.node.addEventListener('scroll', async (e) => {
             e.stopPropagation();
             clearTimeout(this.timeout);
@@ -54,14 +54,14 @@ class NotebookScrollProducer {
                     cells: getVisibleCells(notebookPanel)
                 }
             };
-            await router.publishEvent(event, logNotebookContentEvent);
+            await pioneer.router.publishEvent(event, logNotebookContentEvent);
         });
     }
 }
 NotebookScrollProducer.id = 'NotebookScrollEvent';
 export { NotebookScrollProducer };
 class NotebookVisibleEventProducer {
-    listen(notebookPanel, router, logNotebookContentEvent) {
+    listen(notebookPanel, pioneer, logNotebookContentEvent) {
         document.addEventListener('visibilitychange', async () => {
             if (document.visibilityState === 'visible') {
                 const event = {
@@ -71,7 +71,7 @@ class NotebookVisibleEventProducer {
                         cells: getVisibleCells(notebookPanel)
                     }
                 };
-                await router.publishEvent(event, logNotebookContentEvent);
+                await pioneer.router.publishEvent(event, logNotebookContentEvent);
             }
         });
     }
@@ -79,14 +79,14 @@ class NotebookVisibleEventProducer {
 NotebookVisibleEventProducer.id = 'NotebookVisibleEvent';
 export { NotebookVisibleEventProducer };
 class NotebookHiddenEventProducer {
-    listen(_, router, logNotebookContentEvent) {
+    listen(_, pioneer, logNotebookContentEvent) {
         document.addEventListener('visibilitychange', async (e) => {
             if (document.visibilityState === 'hidden') {
                 const event = {
                     eventName: NotebookHiddenEventProducer.id,
                     eventTime: Date.now()
                 };
-                await router.publishEvent(event, logNotebookContentEvent);
+                await pioneer.router.publishEvent(event, logNotebookContentEvent);
             }
         });
     }
@@ -94,7 +94,7 @@ class NotebookHiddenEventProducer {
 NotebookHiddenEventProducer.id = 'NotebookHiddenEvent';
 export { NotebookHiddenEventProducer };
 class ClipboardCopyEventProducer {
-    listen(notebookPanel, router, logNotebookContentEvent) {
+    listen(notebookPanel, pioneer, logNotebookContentEvent) {
         notebookPanel.node.addEventListener('copy', async () => {
             var _a, _b;
             const cell = {
@@ -110,14 +110,14 @@ class ClipboardCopyEventProducer {
                     selection: text
                 }
             };
-            await router.publishEvent(event, logNotebookContentEvent);
+            await pioneer.router.publishEvent(event, logNotebookContentEvent);
         });
     }
 }
 ClipboardCopyEventProducer.id = 'ClipboardCopyEvent';
 export { ClipboardCopyEventProducer };
 class ClipboardCutEventProducer {
-    listen(notebookPanel, router, logNotebookContentEvent) {
+    listen(notebookPanel, pioneer, logNotebookContentEvent) {
         notebookPanel.node.addEventListener('cut', async () => {
             var _a, _b;
             const cell = {
@@ -133,14 +133,14 @@ class ClipboardCutEventProducer {
                     selection: text
                 }
             };
-            await router.publishEvent(event, logNotebookContentEvent);
+            await pioneer.router.publishEvent(event, logNotebookContentEvent);
         });
     }
 }
 ClipboardCutEventProducer.id = 'ClipboardCutEvent';
 export { ClipboardCutEventProducer };
 class ClipboardPasteEventProducer {
-    listen(notebookPanel, router, logNotebookContentEvent) {
+    listen(notebookPanel, pioneer, logNotebookContentEvent) {
         notebookPanel.node.addEventListener('paste', async (e) => {
             var _a;
             const cell = {
@@ -156,14 +156,14 @@ class ClipboardPasteEventProducer {
                     selection: text
                 }
             };
-            await router.publishEvent(event, logNotebookContentEvent);
+            await pioneer.router.publishEvent(event, logNotebookContentEvent);
         });
     }
 }
 ClipboardPasteEventProducer.id = 'ClipboardPasteEvent';
 export { ClipboardPasteEventProducer };
 class ActiveCellChangeEventProducer {
-    listen(notebookPanel, router, logNotebookContentEvent) {
+    listen(notebookPanel, pioneer, logNotebookContentEvent) {
         notebookPanel.content.activeCellChanged.connect(async (_, cell) => {
             if (cell && notebookPanel.content.widgets) {
                 const activatedCell = {
@@ -177,7 +177,7 @@ class ActiveCellChangeEventProducer {
                         cells: [activatedCell] // activated cell
                     }
                 };
-                await router.publishEvent(event, logNotebookContentEvent);
+                await pioneer.router.publishEvent(event, logNotebookContentEvent);
             }
         });
     }
@@ -185,14 +185,14 @@ class ActiveCellChangeEventProducer {
 ActiveCellChangeEventProducer.id = 'ActiveCellChangeEvent';
 export { ActiveCellChangeEventProducer };
 class NotebookSaveEventProducer {
-    listen(notebookPanel, router, logNotebookContentEvent) {
+    listen(notebookPanel, pioneer, logNotebookContentEvent) {
         notebookPanel.context.saveState.connect(async (_, saveState) => {
             if (saveState.match('completed')) {
                 const event = {
                     eventName: NotebookSaveEventProducer.id,
                     eventTime: Date.now()
                 };
-                await router.publishEvent(event, logNotebookContentEvent);
+                await pioneer.router.publishEvent(event, logNotebookContentEvent);
             }
         });
     }
@@ -200,7 +200,7 @@ class NotebookSaveEventProducer {
 NotebookSaveEventProducer.id = 'NotebookSaveEvent';
 export { NotebookSaveEventProducer };
 class CellExecuteEventProducer {
-    listen(_, router, logNotebookContentEvent) {
+    listen(_, pioneer, logNotebookContentEvent) {
         NotebookActions.executed.connect(async (_, args) => {
             const executedCell = {
                 id: args.cell.model.id,
@@ -215,14 +215,14 @@ class CellExecuteEventProducer {
                     kernelError: args.success ? null : args.error
                 }
             };
-            await router.publishEvent(event, logNotebookContentEvent);
+            await pioneer.router.publishEvent(event, logNotebookContentEvent);
         });
     }
 }
 CellExecuteEventProducer.id = 'CellExecuteEvent';
 export { CellExecuteEventProducer };
 class CellAddEventProducer {
-    listen(notebookPanel, router, logNotebookContentEvent) {
+    listen(notebookPanel, pioneer, logNotebookContentEvent) {
         var _a;
         (_a = notebookPanel.content.model) === null || _a === void 0 ? void 0 : _a.cells.changed.connect(async (_, args) => {
             if (args.type === 'add') {
@@ -237,7 +237,7 @@ class CellAddEventProducer {
                         cells: [addedCell]
                     }
                 };
-                await router.publishEvent(event, logNotebookContentEvent);
+                await pioneer.router.publishEvent(event, logNotebookContentEvent);
             }
         });
     }
@@ -245,7 +245,7 @@ class CellAddEventProducer {
 CellAddEventProducer.id = 'CellAddEvent';
 export { CellAddEventProducer };
 class CellRemoveEventProducer {
-    listen(notebookPanel, router, logNotebookContentEvent) {
+    listen(notebookPanel, pioneer, logNotebookContentEvent) {
         var _a;
         (_a = notebookPanel.content.model) === null || _a === void 0 ? void 0 : _a.cells.changed.connect(async (_, args) => {
             if (args.type === 'remove') {
@@ -260,7 +260,7 @@ class CellRemoveEventProducer {
                         cells: [removedCell]
                     }
                 };
-                await router.publishEvent(event, logNotebookContentEvent);
+                await pioneer.router.publishEvent(event, logNotebookContentEvent);
             }
         });
     }

package/lib/router.d.ts

@@ -1,9 +1,5 @@
 import { NotebookPanel } from '@jupyterlab/notebook';
-export interface ITelemetryRouter {
-    loadNotebookPanel(notebookPanel: NotebookPanel): void;
-    publishEvent(eventDetail: Object, logNotebookContent?: Boolean): void;
-}
-export declare class TelemetryRouter implements ITelemetryRouter {
+export declare class Router {
     private sessionID?;
     private notebookPanel?;
     /**

package/lib/router.js

@@ -1,5 +1,5 @@
 import { requestAPI } from './handler';
-export class TelemetryRouter {
+export class Router {
     /**
      * Load notebookPanel.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "jupyterlab-pioneer",
-    "version": "0.1.2",
+    "version": "0.1.4",
     "description": "A JupyterLab extension.",
     "keywords": [
         "jupyter",

package/lib/events.d.ts

@@ -1,53 +0,0 @@
-import { NotebookPanel } from '@jupyterlab/notebook';
-import { ITelemetryRouter } from './router';
-export declare class NotebookOpenEventProducer {
-    static id: string;
-    private produced;
-    listen(_: NotebookPanel, router: ITelemetryRouter, logNotebookContentEvent: boolean): Promise<void>;
-}
-export declare class NotebookScrollProducer {
-    static id: string;
-    private timeout;
-    listen(notebookPanel: NotebookPanel, router: ITelemetryRouter, logNotebookContentEvent: boolean): void;
-}
-export declare class NotebookVisibleEventProducer {
-    static id: string;
-    listen(notebookPanel: NotebookPanel, router: ITelemetryRouter, logNotebookContentEvent: boolean): void;
-}
-export declare class NotebookHiddenEventProducer {
-    static id: string;
-    listen(_: NotebookPanel, router: ITelemetryRouter, logNotebookContentEvent: boolean): void;
-}
-export declare class ClipboardCopyEventProducer {
-    static id: string;
-    listen(notebookPanel: NotebookPanel, router: ITelemetryRouter, logNotebookContentEvent: boolean): void;
-}
-export declare class ClipboardCutEventProducer {
-    static id: string;
-    listen(notebookPanel: NotebookPanel, router: ITelemetryRouter, logNotebookContentEvent: boolean): void;
-}
-export declare class ClipboardPasteEventProducer {
-    static id: string;
-    listen(notebookPanel: NotebookPanel, router: ITelemetryRouter, logNotebookContentEvent: boolean): void;
-}
-export declare class ActiveCellChangeEventProducer {
-    static id: string;
-    listen(notebookPanel: NotebookPanel, router: ITelemetryRouter, logNotebookContentEvent: boolean): void;
-}
-export declare class NotebookSaveEventProducer {
-    static id: string;
-    listen(notebookPanel: NotebookPanel, router: ITelemetryRouter, logNotebookContentEvent: boolean): void;
-}
-export declare class CellExecuteEventProducer {
-    static id: string;
-    listen(_: any, router: ITelemetryRouter, logNotebookContentEvent: boolean): void;
-}
-export declare class CellAddEventProducer {
-    static id: string;
-    listen(notebookPanel: NotebookPanel, router: ITelemetryRouter, logNotebookContentEvent: boolean): void;
-}
-export declare class CellRemoveEventProducer {
-    static id: string;
-    listen(notebookPanel: NotebookPanel, router: ITelemetryRouter, logNotebookContentEvent: boolean): void;
-}
-export declare const producerCollection: (typeof NotebookVisibleEventProducer)[];