jupyterlab-pioneer 0.1.7 → 0.1.9

package/README.md

@@ -11,7 +11,7 @@ A JupyterLab extension for generating and exporting JupyterLab event telemetry d
 
 ```bash
 # enter the configuration_examples directory and run
-docker compose -p jupyterlab-pioneer up --build
+docker compose -p jupyterlab_pioneer up --build
 ```
 
 A JupyterLab application with the extension installed and configured will run on localhost:8888.
@@ -23,7 +23,7 @@ A JupyterLab application with the extension installed and configured will run on
 To install the extension, execute:
 
 ```bash
-pip install jupyterlab-pioneer
+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**.
@@ -61,7 +61,7 @@ Check jupyter server [doc](https://jupyter-server.readthedocs.io/en/latest/opera
 
 ```python
 {
-    'name': string # string, event name
+    'name': # string, event name
     'logWholeNotebook': # boolean, whether to export the entire notebook content when event is triggered
 }
 ```
@@ -74,12 +74,12 @@ The extension will export the entire notebook content only for valid events with
 
 ```python
 {
-    'type': # one of 'console_exporter', 'command_line_exporter',
+    'type': # One of 'console_exporter', 'command_line_exporter',
             # 'file_exporter', 'remote_exporter',
             # or 'custom_exporter'.
-    'args': # arguments passed to the exporter function.
+    'args': # Optional. Arguments passed to the exporter function.
             # It needs to contain 'path' for file_exporter, 'url' for remote_exporter.
-    'activeEvents': # exporter's local active_events config will override global activeEvents config
+    'activeEvents': # Optional. Exporter's local activeEvents config will override global activeEvents config
 }
 ```
 
@@ -121,6 +121,14 @@ jupyter labextension list
 
 ### Development install
 
+#### (Optional) create conda environment from the provided `environment.yml` file
+
+```bash
+conda env create -f environment.yml
+```
+
+#### Clone and build the extension package
+
 Note: You will need NodeJS to build the extension package.
 
 The `jlpm` command is JupyterLab's pinned version of
@@ -129,7 +137,7 @@ The `jlpm` command is JupyterLab's pinned version of
 
 ```bash
 # Clone the repo to your local environment
-# Change directory to the jupyterlab_pioneer directory
+# Change directory to the jupyterlab-pioneer directory
 # Install package in development mode
 pip install -e "."
 # Link your development version of the extension with JupyterLab

package/lib/index.d.ts

@@ -8,13 +8,14 @@ export interface IJupyterLabPioneer {
      * Send event data to exporters defined in the configuration file.
      *
      * @param {NotebookPanel} notebookPanel The notebook panel the extension currently listens to.
-     * @param {Object} eventDetail An object containing event details
-     * @param {Boolean} logNotebookContent A boolean indicating whether to log the entire notebook or not
+     * @param {Object} eventDetail An object containing event details.
+     * @param {Exporter} exporter The exporter configuration.
+     * @param {Boolean=} logWholeNotebook A boolean indicating whether to log the entire notebook or not.
      */
-    publishEvent(notebookPanel: NotebookPanel, eventDetail: Object, logWholeNotebook?: Boolean, exporter?: Exporter): Promise<void>;
+    publishEvent(notebookPanel: NotebookPanel, eventDetail: Object, exporter: Exporter, logWholeNotebook?: Boolean): Promise<void>;
 }
 declare class JupyterLabPioneer implements IJupyterLabPioneer {
-    publishEvent(notebookPanel: NotebookPanel, eventDetail: Object, logWholeNotebook?: Boolean, exporter?: Exporter): Promise<void>;
+    publishEvent(notebookPanel: NotebookPanel, eventDetail: Object, exporter: Exporter, logWholeNotebook?: Boolean): Promise<void>;
 }
 declare const plugin: JupyterFrontEndPlugin<JupyterLabPioneer>;
 export default plugin;

package/lib/index.js

@@ -5,7 +5,7 @@ import { producerCollection } from './producer';
 const PLUGIN_ID = 'jupyterlab-pioneer:plugin';
 export const IJupyterLabPioneer = new Token(PLUGIN_ID);
 class JupyterLabPioneer {
-    async publishEvent(notebookPanel, eventDetail, logWholeNotebook, exporter) {
+    async publishEvent(notebookPanel, eventDetail, exporter, logWholeNotebook) {
         var _a, _b;
         if (!notebookPanel) {
             throw Error('router is listening to a null notebook panel');
@@ -44,7 +44,7 @@ const plugin = {
             await notebookPanel.sessionContext.ready;
             const activeEvents = config.activeEvents;
             const exporters = ((_a = notebookPanel.content.model) === null || _a === void 0 ? void 0 : _a.getMetadata('exporters')) ||
-                config.exporters;
+                config.exporters; // The exporters configuration in the notebook metadata overrides the configuration in the configuration file "jupyter_jupyterlab_pioneer_config.py"
             const processedExporters = activeEvents && activeEvents.length
                 ? exporters.map(e => {
                     if (!e.activeEvents) {
@@ -56,6 +56,8 @@ const plugin = {
                     }
                 })
                 : exporters.filter(e => e.activeEvents && e.activeEvents.length);
+            // Exporters without specifying the corresponding activeEvents will use the global activeEvents configuration.
+            // When the global activeEvents configuration is null, exporters that do not have corresponding activeEvents will be ignored.
             console.log(processedExporters);
             processedExporters.forEach(exporter => {
                 producerCollection.forEach(producer => {

package/lib/producer.d.ts

@@ -46,7 +46,7 @@ export declare class NotebookSaveEventProducer {
     static id: string;
     listen(notebookPanel: NotebookPanel, pioneer: IJupyterLabPioneer, exporter: Exporter): void;
 }
-export declare class NotebookScrollProducer {
+export declare class NotebookScrollEventProducer {
     static id: string;
     private timeout;
     listen(notebookPanel: NotebookPanel, pioneer: IJupyterLabPioneer, exporter: Exporter): void;

package/lib/producer.js

@@ -17,7 +17,7 @@ class ActiveCellChangeEventProducer {
                         cells: [activatedCell] // activated cell
                     }
                 };
-                await pioneer.publishEvent(notebookPanel, event, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == ActiveCellChangeEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook, exporter);
+                await pioneer.publishEvent(notebookPanel, event, exporter, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == ActiveCellChangeEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook);
             }
         });
     }
@@ -41,7 +41,7 @@ class CellAddEventProducer {
                         cells: [addedCell]
                     }
                 };
-                await pioneer.publishEvent(notebookPanel, event, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == CellAddEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook, exporter);
+                await pioneer.publishEvent(notebookPanel, event, exporter, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == CellAddEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook);
             }
         });
     }
@@ -63,7 +63,7 @@ class CellEditEventProducer {
                     doc: (_b = (_a = editor === null || editor === void 0 ? void 0 : editor.state) === null || _a === void 0 ? void 0 : _a.doc) === null || _b === void 0 ? void 0 : _b.toJSON() // send entire cell content if this is a new cell
                 }
             };
-            await pioneer.publishEvent(notebookPanel, event, (_d = (_c = exporter.activeEvents) === null || _c === void 0 ? void 0 : _c.find(o => o.name == CellEditEventProducer.id)) === null || _d === void 0 ? void 0 : _d.logWholeNotebook, exporter);
+            await pioneer.publishEvent(notebookPanel, event, exporter, (_d = (_c = exporter.activeEvents) === null || _c === void 0 ? void 0 : _c.find(o => o.name == CellEditEventProducer.id)) === null || _d === void 0 ? void 0 : _d.logWholeNotebook);
         };
         const addDocChangeListener = async (cell) => {
             await (cell === null || cell === void 0 ? void 0 : cell.ready); // wait until cell is ready, to prevent errors when creating new cells
@@ -78,8 +78,8 @@ class CellEditEventProducer {
                             changes: v.changes.toJSON() // send changes
                         }
                     };
-                    await pioneer.publishEvent(notebookPanel, event, false, // do not log whole notebook for doc changes
-                    exporter);
+                    await pioneer.publishEvent(notebookPanel, event, exporter, false // do not log whole notebook for doc changes
+                    );
                 }
             }));
         };
@@ -116,7 +116,7 @@ class CellExecuteEventProducer {
                         kernelError: args.success ? null : args.error
                     }
                 };
-                await pioneer.publishEvent(notebookPanel, event, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == CellExecuteEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook, exporter);
+                await pioneer.publishEvent(notebookPanel, event, exporter, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == CellExecuteEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook);
             }
         });
     }
@@ -130,8 +130,7 @@ class CellRemoveEventProducer {
             var _a, _b;
             if (args.type === 'remove') {
                 const removedCell = {
-                    newIndex: args.newIndex,
-                    oldIndex: args.oldIndex
+                    index: args.oldIndex
                 };
                 const event = {
                     eventName: CellRemoveEventProducer.id,
@@ -140,7 +139,7 @@ class CellRemoveEventProducer {
                         cells: [removedCell]
                     }
                 };
-                await pioneer.publishEvent(notebookPanel, event, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == CellRemoveEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook, exporter);
+                await pioneer.publishEvent(notebookPanel, event, exporter, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == CellRemoveEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook);
             }
         });
     }
@@ -164,7 +163,7 @@ class ClipboardCopyEventProducer {
                     selection: text
                 }
             };
-            await pioneer.publishEvent(notebookPanel, event, (_d = (_c = exporter.activeEvents) === null || _c === void 0 ? void 0 : _c.find(o => o.name == ClipboardCopyEventProducer.id)) === null || _d === void 0 ? void 0 : _d.logWholeNotebook, exporter);
+            await pioneer.publishEvent(notebookPanel, event, exporter, (_d = (_c = exporter.activeEvents) === null || _c === void 0 ? void 0 : _c.find(o => o.name == ClipboardCopyEventProducer.id)) === null || _d === void 0 ? void 0 : _d.logWholeNotebook);
         });
     }
 }
@@ -187,7 +186,7 @@ class ClipboardCutEventProducer {
                     selection: text
                 }
             };
-            await pioneer.publishEvent(notebookPanel, event, (_d = (_c = exporter.activeEvents) === null || _c === void 0 ? void 0 : _c.find(o => o.name == ClipboardCutEventProducer.id)) === null || _d === void 0 ? void 0 : _d.logWholeNotebook, exporter);
+            await pioneer.publishEvent(notebookPanel, event, exporter, (_d = (_c = exporter.activeEvents) === null || _c === void 0 ? void 0 : _c.find(o => o.name == ClipboardCutEventProducer.id)) === null || _d === void 0 ? void 0 : _d.logWholeNotebook);
         });
     }
 }
@@ -210,7 +209,7 @@ class ClipboardPasteEventProducer {
                     selection: text
                 }
             };
-            await pioneer.publishEvent(notebookPanel, event, (_c = (_b = exporter.activeEvents) === null || _b === void 0 ? void 0 : _b.find(o => o.name == ClipboardPasteEventProducer.id)) === null || _c === void 0 ? void 0 : _c.logWholeNotebook, exporter);
+            await pioneer.publishEvent(notebookPanel, event, exporter, (_c = (_b = exporter.activeEvents) === null || _b === void 0 ? void 0 : _b.find(o => o.name == ClipboardPasteEventProducer.id)) === null || _c === void 0 ? void 0 : _c.logWholeNotebook);
         });
     }
 }
@@ -227,7 +226,7 @@ class NotebookHiddenEventProducer {
                     eventTime: Date.now(),
                     eventInfo: null
                 };
-                await pioneer.publishEvent(notebookPanel, event, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == NotebookHiddenEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook, exporter);
+                await pioneer.publishEvent(notebookPanel, event, exporter, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == NotebookHiddenEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook);
             }
         });
     }
@@ -248,7 +247,7 @@ class NotebookOpenEventProducer {
                     environ: await requestAPI('environ')
                 }
             };
-            await pioneer.publishEvent(notebookPanel, event, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == NotebookOpenEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook, exporter);
+            await pioneer.publishEvent(notebookPanel, event, exporter, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == NotebookOpenEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook);
             this.produced = true;
         }
     }
@@ -265,7 +264,7 @@ class NotebookSaveEventProducer {
                     eventTime: Date.now(),
                     eventInfo: null
                 };
-                await pioneer.publishEvent(notebookPanel, event, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == NotebookSaveEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook, exporter);
+                await pioneer.publishEvent(notebookPanel, event, exporter, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == NotebookSaveEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook);
             }
         });
     }
@@ -290,7 +289,7 @@ const getVisibleCells = (notebookPanel) => {
     }
     return visibleCells;
 };
-class NotebookScrollProducer {
+class NotebookScrollEventProducer {
     constructor() {
         this.timeout = 0;
     }
@@ -301,18 +300,18 @@ class NotebookScrollProducer {
             clearTimeout(this.timeout);
             await new Promise(resolve => (this.timeout = window.setTimeout(resolve, 1500))); // wait 1.5 seconds before preceding
             const event = {
-                eventName: NotebookScrollProducer.id,
+                eventName: NotebookScrollEventProducer.id,
                 eventTime: Date.now(),
                 eventInfo: {
                     cells: getVisibleCells(notebookPanel)
                 }
             };
-            await pioneer.publishEvent(notebookPanel, event, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == NotebookScrollProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook, exporter);
+            await pioneer.publishEvent(notebookPanel, event, exporter, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == NotebookScrollEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook);
         });
     }
 }
-NotebookScrollProducer.id = 'NotebookScrollEvent';
-export { NotebookScrollProducer };
+NotebookScrollEventProducer.id = 'NotebookScrollEvent';
+export { NotebookScrollEventProducer };
 class NotebookVisibleEventProducer {
     listen(notebookPanel, pioneer, exporter) {
         document.addEventListener('visibilitychange', async () => {
@@ -326,7 +325,7 @@ class NotebookVisibleEventProducer {
                         cells: getVisibleCells(notebookPanel)
                     }
                 };
-                await pioneer.publishEvent(notebookPanel, event, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == NotebookVisibleEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook, exporter);
+                await pioneer.publishEvent(notebookPanel, event, exporter, (_b = (_a = exporter.activeEvents) === null || _a === void 0 ? void 0 : _a.find(o => o.name == NotebookVisibleEventProducer.id)) === null || _b === void 0 ? void 0 : _b.logWholeNotebook);
             }
         });
     }
@@ -345,6 +344,6 @@ export const producerCollection = [
     NotebookHiddenEventProducer,
     NotebookOpenEventProducer,
     NotebookSaveEventProducer,
-    NotebookScrollProducer,
+    NotebookScrollEventProducer,
     NotebookVisibleEventProducer
 ];

package/lib/types.d.ts

@@ -1,20 +1,58 @@
 export interface ActiveEvent {
+    /**
+     * Name of the active event (the static id associate with the event class)
+     */
     name: string;
+    /**
+     * Whether to log the whole notebook or not when the event is triggered
+     */
     logWholeNotebook: boolean;
 }
 export interface ExporterArgs {
+    /**
+     * Exporter ID
+     */
     id: string;
+    /**
+     * Local file path (required for file exporter)
+     */
+    path?: string;
+    /**
+     * Http endpoint (required for remote exporter)
+     */
     url?: string;
+    /**
+     * Additional parameters to pass to the http endpoint (optional for remote exporter)
+     */
     params?: Object;
-    path?: string;
+    /**
+     * Environment variables to pass to the http endpoint (optional for remote exporter)
+     */
     env?: Object[];
 }
 export interface Exporter {
+    /**
+     * Exporter type, should be one of "console_exporter", "command_line_exporter", "file_exporter", "remote_exporter" or "custom_exporter"
+     */
     type: string;
+    /**
+     * Arguments to pass to the exporter function
+     */
     args?: ExporterArgs;
+    /**
+     * An array of active events defined inside of individual exporters. It overrides the global activeEvents configuration defined in the configuration file.
+     * The extension would only generate and export data for valid events ( 1. that have an id associated with the event class, 2. the event name is included in activeEvents ).
+     * The extension will export the entire notebook content only for valid events when the logWholeNotebook flag is True.
+     */
     activeEvents?: ActiveEvent[];
 }
 export interface Config {
+    /**
+     * An array of active events
+     */
     activeEvents: ActiveEvent[];
+    /**
+     * An array of exporters
+     */
     exporters: Exporter[];
 }

package/package.json

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