@jupyterlab/inspector 4.0.0-alpha.19 → 4.0.0-alpha.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupyterlab/inspector",
-  "version": "4.0.0-alpha.19",
+  "version": "4.0.0-alpha.20",
   "description": "JupyterLab - Code Inspector",
   "homepage": "https://github.com/jupyterlab/jupyterlab",
   "bugs": {
@@ -27,7 +27,8 @@
     "lib/*.js.map",
     "lib/*.js",
     "style/*.css",
-    "style/index.js"
+    "style/index.js",
+    "src/**/*.{ts,tsx}"
   ],
   "scripts": {
     "build": "tsc -b",
@@ -41,25 +42,25 @@
     "watch": "tsc -b --watch"
   },
   "dependencies": {
-    "@jupyterlab/apputils": "^4.0.0-alpha.19",
-    "@jupyterlab/codeeditor": "^4.0.0-alpha.19",
-    "@jupyterlab/coreutils": "^6.0.0-alpha.19",
-    "@jupyterlab/rendermime": "^4.0.0-alpha.19",
-    "@jupyterlab/services": "^7.0.0-alpha.19",
-    "@jupyterlab/statedb": "^4.0.0-alpha.19",
-    "@jupyterlab/translation": "^4.0.0-alpha.19",
-    "@lumino/coreutils": "^2.0.0-beta.0",
-    "@lumino/disposable": "^2.0.0-beta.1",
-    "@lumino/polling": "^2.0.0-beta.0",
-    "@lumino/signaling": "^2.0.0-beta.1",
-    "@lumino/widgets": "^2.0.0-beta.1"
+    "@jupyterlab/apputils": "^4.0.0-alpha.20",
+    "@jupyterlab/codeeditor": "^4.0.0-alpha.20",
+    "@jupyterlab/coreutils": "^6.0.0-alpha.20",
+    "@jupyterlab/rendermime": "^4.0.0-alpha.20",
+    "@jupyterlab/services": "^7.0.0-alpha.20",
+    "@jupyterlab/statedb": "^4.0.0-alpha.20",
+    "@jupyterlab/translation": "^4.0.0-alpha.20",
+    "@lumino/coreutils": "^2.0.0-rc.0",
+    "@lumino/disposable": "^2.0.0-rc.0",
+    "@lumino/polling": "^2.0.0-rc.0",
+    "@lumino/signaling": "^2.0.0-rc.0",
+    "@lumino/widgets": "^2.0.0-rc.0"
   },
   "devDependencies": {
-    "@jupyterlab/testing": "^4.0.0-alpha.19",
+    "@jupyterlab/testing": "^4.0.0-alpha.20",
     "@types/jest": "^29.2.0",
     "rimraf": "~3.0.0",
-    "typedoc": "~0.22.10",
-    "typescript": "~4.7.3"
+    "typedoc": "~0.23.25",
+    "typescript": "~5.0.0-beta"
   },
   "publishConfig": {
     "access": "public"

package/src/handler.ts

@@ -0,0 +1,250 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { CodeEditor } from '@jupyterlab/codeeditor';
+import { Text } from '@jupyterlab/coreutils';
+import { IRenderMimeRegistry, MimeModel } from '@jupyterlab/rendermime';
+import { IDataConnector } from '@jupyterlab/statedb';
+import { JSONExt, ReadonlyJSONObject } from '@lumino/coreutils';
+import { IDisposable } from '@lumino/disposable';
+import { Debouncer } from '@lumino/polling';
+import { ISignal, Signal } from '@lumino/signaling';
+import { IInspector } from './tokens';
+
+/**
+ * An object that handles code inspection.
+ */
+export class InspectionHandler implements IDisposable, IInspector.IInspectable {
+  /**
+   * Construct a new inspection handler for a widget.
+   */
+  constructor(options: InspectionHandler.IOptions) {
+    this._connector = options.connector;
+    this._rendermime = options.rendermime;
+    this._debouncer = new Debouncer(this.onEditorChange.bind(this), 250);
+  }
+
+  /**
+   * A signal emitted when the inspector should clear all items.
+   */
+  get cleared(): ISignal<InspectionHandler, void> {
+    return this._cleared;
+  }
+
+  /**
+   * A signal emitted when the handler is disposed.
+   */
+  get disposed(): ISignal<InspectionHandler, void> {
+    return this._disposed;
+  }
+
+  /**
+   * A signal emitted when an inspector value is generated.
+   */
+  get inspected(): ISignal<InspectionHandler, IInspector.IInspectorUpdate> {
+    return this._inspected;
+  }
+
+  /**
+   * The editor widget used by the inspection handler.
+   */
+  get editor(): CodeEditor.IEditor | null {
+    return this._editor;
+  }
+  set editor(newValue: CodeEditor.IEditor | null) {
+    if (newValue === this._editor) {
+      return;
+    }
+    // Remove all of our listeners.
+    Signal.disconnectReceiver(this);
+
+    const editor = (this._editor = newValue);
+    if (editor) {
+      // Clear the inspector in preparation for a new editor.
+      this._cleared.emit(void 0);
+      // Call onEditorChange to cover the case where the user changes
+      // the active cell
+      this.onEditorChange();
+      editor.model.selections.changed.connect(this._onChange, this);
+      editor.model.sharedModel.changed.connect(this._onChange, this);
+    }
+  }
+
+  /**
+   * Indicates whether the handler makes API inspection requests or stands by.
+   *
+   * #### Notes
+   * The use case for this attribute is to limit the API traffic when no
+   * inspector is visible.
+   */
+  get standby(): boolean {
+    return this._standby;
+  }
+  set standby(value: boolean) {
+    this._standby = value;
+  }
+
+  /**
+   * Get whether the inspection handler is disposed.
+   *
+   * #### Notes
+   * This is a read-only property.
+   */
+  get isDisposed(): boolean {
+    return this._isDisposed;
+  }
+
+  /**
+   * Dispose of the resources used by the handler.
+   */
+  dispose(): void {
+    if (this.isDisposed) {
+      return;
+    }
+    this._isDisposed = true;
+    this._debouncer.dispose();
+    this._disposed.emit(void 0);
+    Signal.clearData(this);
+  }
+
+  /**
+   * Handle a text changed signal from an editor.
+   *
+   * #### Notes
+   * Update the hints inspector based on a text change.
+   */
+  onEditorChange(customText?: string): void {
+    // If the handler is in standby mode, bail.
+    if (this._standby) {
+      return;
+    }
+
+    const editor = this.editor;
+
+    if (!editor) {
+      return;
+    }
+    const text = customText ? customText : editor.model.sharedModel.getSource();
+    const position = editor.getCursorPosition();
+    const offset = Text.jsIndexToCharIndex(editor.getOffsetAt(position), text);
+    const update: IInspector.IInspectorUpdate = { content: null };
+
+    const pending = ++this._pending;
+
+    void this._connector
+      .fetch({ offset, text })
+      .then(reply => {
+        // If handler has been disposed or a newer request is pending, bail.
+        if (!reply || this.isDisposed || pending !== this._pending) {
+          this._lastInspectedReply = null;
+          this._inspected.emit(update);
+          return;
+        }
+
+        const { data } = reply;
+
+        // Do not update if there would be no change.
+        if (
+          this._lastInspectedReply &&
+          JSONExt.deepEqual(this._lastInspectedReply, data)
+        ) {
+          return;
+        }
+
+        const mimeType = this._rendermime.preferredMimeType(data);
+        if (mimeType) {
+          const widget = this._rendermime.createRenderer(mimeType);
+          const model = new MimeModel({ data });
+
+          void widget.renderModel(model);
+          update.content = widget;
+        }
+
+        this._lastInspectedReply = reply.data;
+        this._inspected.emit(update);
+      })
+      .catch(reason => {
+        // Since almost all failures are benign, fail silently.
+        this._lastInspectedReply = null;
+        this._inspected.emit(update);
+      });
+  }
+
+  /**
+   * Handle changes to the editor state, debouncing.
+   */
+  private _onChange(): void {
+    void this._debouncer.invoke();
+  }
+
+  private _cleared = new Signal<InspectionHandler, void>(this);
+  private _connector: IDataConnector<
+    InspectionHandler.IReply,
+    void,
+    InspectionHandler.IRequest
+  >;
+  private _disposed = new Signal<this, void>(this);
+  private _editor: CodeEditor.IEditor | null = null;
+  private _inspected = new Signal<this, IInspector.IInspectorUpdate>(this);
+  private _isDisposed = false;
+  private _pending = 0;
+  private _rendermime: IRenderMimeRegistry;
+  private _standby = true;
+  private _debouncer: Debouncer;
+  private _lastInspectedReply: InspectionHandler.IReply['data'] | null = null;
+}
+
+/**
+ * A namespace for inspection handler statics.
+ */
+export namespace InspectionHandler {
+  /**
+   * The instantiation options for an inspection handler.
+   */
+  export interface IOptions {
+    /**
+     * The connector used to make inspection requests.
+     *
+     * #### Notes
+     * The only method of this connector that will ever be called is `fetch`, so
+     * it is acceptable for the other methods to be simple functions that return
+     * rejected promises.
+     */
+    connector: IDataConnector<IReply, void, IRequest>;
+
+    /**
+     * The mime renderer for the inspection handler.
+     */
+    rendermime: IRenderMimeRegistry;
+  }
+
+  /**
+   * A reply to an inspection request.
+   */
+  export interface IReply {
+    /**
+     * The MIME bundle data returned from an inspection request.
+     */
+    data: ReadonlyJSONObject;
+
+    /**
+     * Any metadata that accompanies the MIME bundle returning from a request.
+     */
+    metadata: ReadonlyJSONObject;
+  }
+
+  /**
+   * The details of an inspection request.
+   */
+  export interface IRequest {
+    /**
+     * The cursor offset position within the text being inspected.
+     */
+    offset: number;
+
+    /**
+     * The text being inspected.
+     */
+    text: string;
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+/**
+ * @packageDocumentation
+ * @module inspector
+ */
+
+export * from './handler';
+export * from './inspector';
+export * from './kernelconnector';
+export * from './tokens';

package/src/inspector.ts

@@ -0,0 +1,167 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Printing } from '@jupyterlab/apputils';
+import {
+  ITranslator,
+  nullTranslator,
+  TranslationBundle
+} from '@jupyterlab/translation';
+import { Panel, PanelLayout, Widget } from '@lumino/widgets';
+import { IInspector } from './tokens';
+
+/**
+ * The class name added to inspector panels.
+ */
+const PANEL_CLASS = 'jp-Inspector';
+
+/**
+ * The class name added to inspector content.
+ */
+const CONTENT_CLASS = 'jp-Inspector-content';
+
+/**
+ * The class name added to default inspector content.
+ */
+const DEFAULT_CONTENT_CLASS = 'jp-Inspector-default-content';
+
+/**
+ * A panel which contains a set of inspectors.
+ */
+export class InspectorPanel
+  extends Panel
+  implements IInspector, Printing.IPrintable
+{
+  /**
+   * Construct an inspector.
+   */
+  constructor(options: InspectorPanel.IOptions = {}) {
+    super();
+    this.translator = options.translator || nullTranslator;
+    this._trans = this.translator.load('jupyterlab');
+
+    if (options.initialContent instanceof Widget) {
+      this._content = options.initialContent;
+    } else if (typeof options.initialContent === 'string') {
+      this._content = InspectorPanel._generateContentWidget(
+        `<p>${options.initialContent}</p>`
+      );
+    } else {
+      this._content = InspectorPanel._generateContentWidget(
+        '<p>' +
+          this._trans.__('Click on a function to see documentation.') +
+          '</p>'
+      );
+    }
+
+    this.addClass(PANEL_CLASS);
+    (this.layout as PanelLayout).addWidget(this._content);
+  }
+
+  /**
+   * Print in iframe
+   */
+  [Printing.symbol]() {
+    return (): Promise<void> => Printing.printWidget(this);
+  }
+
+  /**
+   * The source of events the inspector panel listens for.
+   */
+  get source(): IInspector.IInspectable | null {
+    return this._source;
+  }
+  set source(source: IInspector.IInspectable | null) {
+    if (this._source === source) {
+      return;
+    }
+
+    // Disconnect old signal handler.
+    if (this._source) {
+      this._source.standby = true;
+      this._source.inspected.disconnect(this.onInspectorUpdate, this);
+      this._source.disposed.disconnect(this.onSourceDisposed, this);
+    }
+
+    // Reject a source that is already disposed.
+    if (source && source.isDisposed) {
+      source = null;
+    }
+
+    // Update source.
+    this._source = source;
+
+    // Connect new signal handler.
+    if (this._source) {
+      this._source.standby = false;
+      this._source.inspected.connect(this.onInspectorUpdate, this);
+      this._source.disposed.connect(this.onSourceDisposed, this);
+    }
+  }
+
+  /**
+   * Dispose of the resources held by the widget.
+   */
+  dispose(): void {
+    if (this.isDisposed) {
+      return;
+    }
+    this.source = null;
+    super.dispose();
+  }
+
+  /**
+   * Handle inspector update signals.
+   */
+  protected onInspectorUpdate(
+    sender: any,
+    args: IInspector.IInspectorUpdate
+  ): void {
+    const { content } = args;
+
+    // Update the content of the inspector widget.
+    if (!content || content === this._content) {
+      return;
+    }
+    this._content.dispose();
+
+    this._content = content;
+    content.addClass(CONTENT_CLASS);
+    (this.layout as PanelLayout).addWidget(content);
+  }
+
+  /**
+   * Handle source disposed signals.
+   */
+  protected onSourceDisposed(sender: any, args: void): void {
+    this.source = null;
+  }
+
+  /**
+   * Generate content widget from string
+   */
+  private static _generateContentWidget(message: string): Widget {
+    const widget = new Widget();
+    widget.node.innerHTML = message;
+    widget.addClass(CONTENT_CLASS);
+    widget.addClass(DEFAULT_CONTENT_CLASS);
+
+    return widget;
+  }
+
+  protected translator: ITranslator;
+  private _trans: TranslationBundle;
+  private _content: Widget;
+  private _source: IInspector.IInspectable | null = null;
+}
+
+export namespace InspectorPanel {
+  export interface IOptions {
+    initialContent?: Widget | string | undefined;
+
+    /**
+     * The application language translator.
+     */
+    translator?: ITranslator;
+  }
+}

package/src/kernelconnector.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { ISessionContext } from '@jupyterlab/apputils';
+import { KernelMessage } from '@jupyterlab/services';
+import { DataConnector } from '@jupyterlab/statedb';
+import { InspectionHandler } from './handler';
+
+/**
+ * The default connector for making inspection requests from the Jupyter API.
+ */
+export class KernelConnector extends DataConnector<
+  InspectionHandler.IReply,
+  void,
+  InspectionHandler.IRequest
+> {
+  /**
+   * Create a new kernel connector for inspection requests.
+   *
+   * @param options - The instantiation options for the kernel connector.
+   */
+  constructor(options: KernelConnector.IOptions) {
+    super();
+    this._sessionContext = options.sessionContext;
+  }
+
+  /**
+   * Fetch inspection requests.
+   *
+   * @param request - The inspection request text and details.
+   */
+  fetch(
+    request: InspectionHandler.IRequest
+  ): Promise<InspectionHandler.IReply> {
+    const kernel = this._sessionContext.session?.kernel;
+
+    if (!kernel) {
+      return Promise.reject(new Error('Inspection fetch requires a kernel.'));
+    }
+
+    const contents: KernelMessage.IInspectRequestMsg['content'] = {
+      code: request.text,
+      cursor_pos: request.offset,
+      detail_level: 1
+    };
+
+    return kernel.requestInspect(contents).then(msg => {
+      const response = msg.content;
+
+      if (response.status !== 'ok' || !response.found) {
+        throw new Error('Inspection fetch failed to return successfully.');
+      }
+
+      return { data: response.data, metadata: response.metadata };
+    });
+  }
+
+  private _sessionContext: ISessionContext;
+}
+
+/**
+ * A namespace for kernel connector statics.
+ */
+export namespace KernelConnector {
+  /**
+   * The instantiation options for an inspection handler.
+   */
+  export interface IOptions {
+    /**
+     * The session context used to make API requests to the kernel.
+     */
+    sessionContext: ISessionContext;
+  }
+}

package/src/tokens.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Token } from '@lumino/coreutils';
+import { ISignal } from '@lumino/signaling';
+import { Widget } from '@lumino/widgets';
+
+/**
+ * The inspector panel token.
+ */
+export const IInspector = new Token<IInspector>(
+  '@jupyterlab/inspector:IInspector'
+);
+
+/**
+ * An interface for an inspector.
+ */
+export interface IInspector {
+  /**
+   * The source of events the inspector listens for.
+   */
+  source: IInspector.IInspectable | null;
+}
+
+/**
+ * A namespace for inspector interfaces.
+ */
+export namespace IInspector {
+  /**
+   * The definition of an inspectable source.
+   */
+  export interface IInspectable {
+    /**
+     * A signal emitted when the inspector should clear all items.
+     */
+    cleared: ISignal<any, void>;
+
+    /**
+     * A signal emitted when the inspectable is disposed.
+     */
+    disposed: ISignal<any, void>;
+
+    /**
+     * A signal emitted when an inspector value is generated.
+     */
+    inspected: ISignal<any, IInspectorUpdate>;
+
+    /**
+     * Test whether the inspectable has been disposed.
+     */
+    isDisposed: boolean;
+
+    /**
+     * Indicates whether the inspectable source emits signals.
+     *
+     * #### Notes
+     * The use case for this attribute is to limit the API traffic when no
+     * inspector is visible. It can be modified by the consumer of the source.
+     */
+    standby: boolean;
+    /**
+     * Handle a text changed signal from an editor.
+     *
+     * #### Notes
+     * Update the hints inspector based on a text change.
+     */
+    onEditorChange(customText?: string): void;
+  }
+
+  /**
+   * An update value for code inspectors.
+   */
+  export interface IInspectorUpdate {
+    /**
+     * The content being sent to the inspector for display.
+     */
+    content: Widget | null;
+  }
+}