jupyterpack 0.2.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Trung Le
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,79 @@
+<h1 align="center">jupyterpack</h1>
+
+[![Github Actions Status](https://github.com/trungleduc/jupyterpack/workflows/Build/badge.svg)](https://github.com/trungleduc/specta/actions/workflows/build.yml)
+[![Try on lite](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)](https://trungleduc.github.io/jupyterpack/lab/)
+
+<h2 align="center"> A JupyterLite extension to serve in-browser Python and Javascript web application</h2>
+
+## Features
+
+- **Python Web Apps**: Serve Python web applications directly in the browser using JupyterLite's in-browser Python kernel. `jupyterpack` currently supports Dash.
+- **JavaScript Web Apps**: Bundle and serve JavaScript web applications using in-browser bundlers.
+
+## Installation
+
+You can install `jupyterpack` using `pip` or `conda`
+
+```bash
+# Install using pip
+pip install jupyterpack
+
+# Install using conda
+conda install -c conda-forge jupyterpack
+```
+
+## Usage
+
+To use `jupyterpack`, you need to create a `.spk` file that defines your web application. Here's an example structure of a React application:
+
+```bash
+my_app/
+├── app.spk
+├── App.js         # Your JS code
+├── package.json   # Your JS dependencies
+└── index.html      # HTML entry for JS apps
+```
+
+the `app.spk` is the entry point of your React app, it should contain the following content:
+
+```json
+{
+  "name": "React Example",
+  "entry": "/index.html",
+  "framework": "react"
+}
+```
+
+Double clicking the `spk` file to open the web app as a tab of JupyterLab.
+
+### Dash application
+
+Same as the React application, here is the structure of a Dash application:
+
+```bash
+my_app/
+├── app.spk
+├── server.py         # Your Dash code
+```
+
+the `app.spk` is the entry point of your Dash app, it should contain the following content:
+
+```json
+{
+  "name": "Dash Example",
+  "entry": "server.py",
+  "framework": "dash"
+}
+```
+
+For the Dash code, you need to define your Dash app variable as `app` and do not call `app.run_server` directly, `jupyterpack` will handle the server for you. Just as the case of React app, double clicking the spk file will open the Dash app in a new JupyterLab tab.
+
+## Try it online!
+
+You can try it online by clicking on this badge:
+
+[![Try on lite](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)](https://trungleduc.github.io/jupyterpack/lab/)
+
+## License
+
+jupyterpack is licensed under the BSD-3-Clause license.

package/lib/document/iframePanel.d.ts

@@ -0,0 +1,7 @@
+import { Widget } from '@lumino/widgets';
+export declare class IFramePanel extends Widget {
+    constructor();
+    toggleSpinner(show: boolean): void;
+    protected _iframe: HTMLIFrameElement;
+    protected _spinner: HTMLDivElement;
+}

package/lib/document/iframePanel.js

@@ -0,0 +1,20 @@
+import { Widget } from '@lumino/widgets';
+export class IFramePanel extends Widget {
+    constructor() {
+        super();
+        this.addClass('jupyterpack-iframe-panel');
+        this._iframe = document.createElement('iframe');
+        this._spinner = document.createElement('div');
+        this._spinner.classList.add('jupyterpack-spinner');
+        this.node.appendChild(this._spinner);
+        this.node.appendChild(this._iframe);
+    }
+    toggleSpinner(show) {
+        if (show) {
+            this._spinner.style.display = 'unset';
+        }
+        else {
+            this._spinner.style.display = 'none';
+        }
+    }
+}

package/lib/document/jupyterpackDocWidget.d.ts

@@ -0,0 +1,9 @@
+import { DocumentWidget } from '@jupyterlab/docregistry';
+export declare class JupyterPackDocWidget extends DocumentWidget {
+    constructor(options: DocumentWidget.IOptions);
+    /**
+     * Dispose of the resources held by the widget.
+     */
+    dispose(): void;
+    onResize: (msg: any) => void;
+}

package/lib/document/jupyterpackDocWidget.js

@@ -0,0 +1,16 @@
+import { DocumentWidget } from '@jupyterlab/docregistry';
+export class JupyterPackDocWidget extends DocumentWidget {
+    constructor(options) {
+        super(options);
+        this.onResize = (msg) => {
+            window.dispatchEvent(new Event('resize'));
+        };
+    }
+    /**
+     * Dispose of the resources held by the widget.
+     */
+    dispose() {
+        this.content.dispose();
+        super.dispose();
+    }
+}

package/lib/document/plugin.d.ts

@@ -0,0 +1,2 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+export declare const spkPlugin: JupyterFrontEndPlugin<void>;

package/lib/document/plugin.js

@@ -0,0 +1,31 @@
+import { JupyterPackWidgetFactory } from './widgetFactory';
+import { IConnectionManagerToken } from '../token';
+const FACTORY = 'jupyterpack';
+const CONTENT_TYPE = 'jupyterpack';
+export const spkPlugin = {
+    id: 'jupyterpack:spkplugin',
+    requires: [IConnectionManagerToken],
+    autoStart: true,
+    activate: (app, connectionManager) => {
+        const widgetFactory = new JupyterPackWidgetFactory({
+            name: FACTORY,
+            modelName: 'text',
+            fileTypes: [CONTENT_TYPE],
+            defaultFor: [CONTENT_TYPE],
+            commands: app.commands,
+            manager: app.serviceManager,
+            connectionManager
+        });
+        // Registering the widget factory
+        app.docRegistry.addWidgetFactory(widgetFactory);
+        // register the filetype
+        app.docRegistry.addFileType({
+            name: CONTENT_TYPE,
+            displayName: 'SPK',
+            mimeTypes: ['text/json'],
+            extensions: ['.spk', '.SPK'],
+            fileFormat: 'json',
+            contentType: CONTENT_TYPE
+        });
+    }
+};

package/lib/document/widgetFactory.d.ts

@@ -0,0 +1,23 @@
+import { ABCWidgetFactory, DocumentRegistry } from '@jupyterlab/docregistry';
+import { ServiceManager } from '@jupyterlab/services';
+import { CommandRegistry } from '@lumino/commands';
+import { IConnectionManager } from '../type';
+import { JupyterPackDocWidget } from './jupyterpackDocWidget';
+interface IOptions extends DocumentRegistry.IWidgetFactoryOptions {
+    commands: CommandRegistry;
+    manager: ServiceManager.IManager;
+    connectionManager: IConnectionManager;
+}
+export declare class JupyterPackWidgetFactory extends ABCWidgetFactory<JupyterPackDocWidget> {
+    private options;
+    constructor(options: IOptions);
+    /**
+     * Create a new widget given a context.
+     *
+     * @param context Contains the information of the file
+     * @returns The widget
+     */
+    protected createNewWidget(context: DocumentRegistry.IContext<DocumentRegistry.IModel>): JupyterPackDocWidget;
+    private _contentsManager;
+}
+export {};

package/lib/document/widgetFactory.js

@@ -0,0 +1,60 @@
+import { ABCWidgetFactory } from '@jupyterlab/docregistry';
+import { Panel } from '@lumino/widgets';
+import { JupyterPackFramework } from '../type';
+import { SandpackPanel } from '../sandpackWidget/sandpackPanel';
+import { JupyterPackDocWidget } from './jupyterpackDocWidget';
+import { PythonWidgetModel } from '../pythonWidget/pythonWidgetModel';
+import { UUID } from '@lumino/coreutils';
+import { PythonWidget } from '../pythonWidget/pythonWidget';
+export class JupyterPackWidgetFactory extends ABCWidgetFactory {
+    constructor(options) {
+        super(options);
+        this.options = options;
+        this._contentsManager = options.manager.contents;
+    }
+    /**
+     * Create a new widget given a context.
+     *
+     * @param context Contains the information of the file
+     * @returns The widget
+     */
+    createNewWidget(context) {
+        const content = new Panel();
+        content.addClass('jp-jupyterpack-document-panel');
+        context.ready.then(() => {
+            const jpackModel = context.model.toJSON();
+            switch (jpackModel.framework) {
+                case JupyterPackFramework.REACT: {
+                    const jpContent = new SandpackPanel({
+                        context,
+                        contentsManager: this._contentsManager
+                    });
+                    content.addWidget(jpContent);
+                    break;
+                }
+                case JupyterPackFramework.DASH: {
+                    const model = new PythonWidgetModel({
+                        context,
+                        manager: this.options.manager,
+                        contentsManager: this._contentsManager,
+                        connectionManager: this.options.connectionManager
+                    });
+                    const pythonWidget = new PythonWidget({
+                        model,
+                        id: UUID.uuid4()
+                    });
+                    content.addWidget(pythonWidget);
+                    break;
+                }
+                default: {
+                    console.error('Unsupported framework');
+                    break;
+                }
+            }
+        });
+        return new JupyterPackDocWidget({
+            context,
+            content
+        });
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (import("@jupyterlab/application").JupyterFrontEndPlugin<void> | import("@jupyterlab/application").JupyterFrontEndPlugin<import("./type").IConnectionManager>)[];
+export default _default;

package/lib/index.js

@@ -0,0 +1,3 @@
+import { spkPlugin } from './document/plugin';
+import { swPlugin } from './swConnection';
+export default [swPlugin, spkPlugin];

package/lib/pythonWidget/connectionManager.d.ts

@@ -0,0 +1,18 @@
+import { IConnectionManager, IDict, IKernelExecutor } from '../type';
+export declare class ConnectionManager implements IConnectionManager {
+    instanceId: string;
+    constructor(instanceId: string);
+    registerConnection(kernelExecutor: IKernelExecutor): Promise<{
+        instanceId: string;
+        kernelClientId: string;
+    }>;
+    generateResponse(options: {
+        kernelClientId: string;
+        urlPath: string;
+        method: string;
+        headers: IDict;
+        requestBody?: ArrayBuffer;
+        params?: string;
+    }): Promise<IDict | null>;
+    private _kernelExecutors;
+}

package/lib/pythonWidget/connectionManager.js

@@ -0,0 +1,27 @@
+import { UUID } from '@lumino/coreutils';
+export class ConnectionManager {
+    constructor(instanceId) {
+        this.instanceId = instanceId;
+        this._kernelExecutors = new Map();
+    }
+    async registerConnection(kernelExecutor) {
+        const uuid = UUID.uuid4();
+        this._kernelExecutors.set(uuid, kernelExecutor);
+        return { instanceId: this.instanceId, kernelClientId: uuid };
+    }
+    async generateResponse(options) {
+        const { urlPath, kernelClientId, method, params, requestBody, headers } = options;
+        const executor = this._kernelExecutors.get(kernelClientId);
+        if (!executor) {
+            return null;
+        }
+        const response = await executor.getResponse({
+            urlPath,
+            method,
+            params,
+            headers,
+            requestBody
+        });
+        return response;
+    }
+}

package/lib/pythonWidget/kernelExecutor.d.ts

@@ -0,0 +1,27 @@
+import { KernelMessage, Session } from '@jupyterlab/services';
+import { IDict, IKernelExecutor } from '../type';
+export declare class KernelExecutor implements IKernelExecutor {
+    constructor(options: KernelExecutor.IOptions);
+    get isDisposed(): boolean;
+    init(options: {
+        initCode?: string;
+        instanceId: string;
+        kernelClientId: string;
+    }): Promise<void>;
+    getResponse(options: {
+        method: string;
+        urlPath: string;
+        headers: IDict;
+        requestBody?: ArrayBuffer;
+        params?: string;
+    }): Promise<IDict>;
+    executeCode(code: KernelMessage.IExecuteRequestMsg['content']): Promise<string>;
+    dispose(): void;
+    private _isDisposed;
+    private _sessionConnection;
+}
+export declare namespace KernelExecutor {
+    interface IOptions {
+        sessionConnection: Session.ISessionConnection;
+    }
+}

package/lib/pythonWidget/kernelExecutor.js

@@ -0,0 +1,104 @@
+import { PageConfig, URLExt } from '@jupyterlab/coreutils';
+import { arrayBufferToBase64 } from '../tools';
+export class KernelExecutor {
+    constructor(options) {
+        this._isDisposed = false;
+        this._sessionConnection = options.sessionConnection;
+    }
+    get isDisposed() {
+        return this._isDisposed;
+    }
+    async init(options) {
+        const { initCode, instanceId, kernelClientId } = options;
+        const labBaseUrl = PageConfig.getOption('baseUrl');
+        const baseURL = URLExt.join(labBaseUrl, 'extensions/jupyterpack/static', instanceId, 'dash', kernelClientId, '/');
+        const osCode = `
+    import os
+    os.environ['DASH_URL_BASE_PATHNAME'] = '${baseURL}'
+    `;
+        await this.executeCode({ code: osCode });
+        if (initCode) {
+            await this.executeCode({ code: initCode });
+        }
+        const serverCode = `
+    import httpx, json, base64
+    __monstra_transport = httpx.WSGITransport(app=app.server)
+    def __monstra_get_response(method, url, headers, content=None, params=None):
+      decoded_content = None
+      if content is not None:
+        content = base64.b64decode(content)
+        decoded_content = content.decode()
+      with httpx.Client(transport=__monstra_transport, base_url="http://testserver") as client:
+        r = client.request(method, url, headers=headers, content=content, params=params)
+        response = {
+          "headers": dict(r.headers),
+          "content": r.text,
+          "status_code": r.status_code,
+          "original_request": {"method": method, "url": url, "content": decoded_content, "params": params, "headers": headers},
+        }
+        json_str = json.dumps(response)
+        b64_str = base64.b64encode(json_str.encode("utf-8")).decode("utf-8")
+        return b64_str
+    `;
+        await this.executeCode({ code: serverCode });
+    }
+    async getResponse(options) {
+        const { method, urlPath, requestBody, params, headers } = options;
+        const content = requestBody ? arrayBufferToBase64(requestBody) : undefined;
+        const code = `__monstra_get_response("${method}", "${urlPath}", headers=${JSON.stringify(headers)} , content=${content ? `"${content}"` : 'None'}, params=${params ? `"${params}"` : 'None'})`;
+        const raw = await this.executeCode({ code });
+        const jsonStr = atob(raw.slice(1, -1));
+        const obj = JSON.parse(jsonStr);
+        return obj;
+    }
+    async executeCode(code) {
+        var _a;
+        const kernel = (_a = this._sessionConnection) === null || _a === void 0 ? void 0 : _a.kernel;
+        if (!kernel) {
+            throw new Error('Session has no kernel.');
+        }
+        return new Promise((resolve, reject) => {
+            const future = kernel.requestExecute(code, false, undefined);
+            const parentMsgid = future.msg.header.msg_id;
+            let executeResult = '';
+            future.onIOPub = (msg) => {
+                const msgType = msg.header.msg_type;
+                switch (msgType) {
+                    case 'execute_result': {
+                        const content = msg.content
+                            .data['text/plain'];
+                        executeResult += content;
+                        break;
+                    }
+                    case 'status': {
+                        if (msg.content.execution_state ===
+                            'idle' &&
+                            msg.parent_header.msg_id === parentMsgid) {
+                            resolve(executeResult);
+                        }
+                        break;
+                    }
+                    case 'stream': {
+                        const content = msg.content.text;
+                        executeResult += content;
+                        break;
+                    }
+                    case 'error': {
+                        console.error('Kernel operation failed', msg.content);
+                        reject(msg.content);
+                        break;
+                    }
+                    default:
+                        break;
+                }
+            };
+        });
+    }
+    dispose() {
+        if (this._isDisposed) {
+            return;
+        }
+        this._isDisposed = true;
+        this._sessionConnection.dispose();
+    }
+}

package/lib/pythonWidget/pythonWidget.d.ts

@@ -0,0 +1,13 @@
+import { PythonWidgetModel } from './pythonWidgetModel';
+import { IFramePanel } from '../document/iframePanel';
+export declare class PythonWidget extends IFramePanel {
+    constructor(options: PythonWidget.IOptions);
+    get model(): PythonWidgetModel;
+    private _model;
+}
+export declare namespace PythonWidget {
+    interface IOptions {
+        id: string;
+        model: PythonWidgetModel;
+    }
+}

package/lib/pythonWidget/pythonWidget.js

@@ -0,0 +1,22 @@
+import { PageConfig } from '@jupyterlab/coreutils';
+import { IFramePanel } from '../document/iframePanel';
+export class PythonWidget extends IFramePanel {
+    constructor(options) {
+        super();
+        this._model = options.model;
+        this._model.initialize().then(connectionData => {
+            if (!connectionData) {
+                return;
+            }
+            const iframe = this._iframe;
+            const fullLabextensionsUrl = PageConfig.getOption('fullLabextensionsUrl');
+            iframe.src = `${fullLabextensionsUrl}/jupyterpack/static/${connectionData.instanceId}/dash/${connectionData.kernelClientId}/`;
+            iframe.addEventListener('load', () => {
+                this.toggleSpinner(false);
+            });
+        });
+    }
+    get model() {
+        return this._model;
+    }
+}

package/lib/pythonWidget/pythonWidgetModel.d.ts

@@ -0,0 +1,29 @@
+import { DocumentRegistry } from '@jupyterlab/docregistry';
+import { IDisposable } from '@lumino/disposable';
+import { ServiceManager, Contents } from '@jupyterlab/services';
+import { IConnectionManager } from '../type';
+export declare class PythonWidgetModel implements IDisposable {
+    constructor(options: PythonWidgetModel.IOptions);
+    get isDisposed(): boolean;
+    get connectionManager(): IConnectionManager;
+    initialize(): Promise<{
+        instanceId: string;
+        kernelClientId: string;
+    } | null>;
+    dispose(): void;
+    private _isDisposed;
+    private _kernelStarted;
+    private _sessionConnection;
+    private _manager;
+    private _context;
+    private _connectionManager;
+    private _contentsManager;
+}
+export declare namespace PythonWidgetModel {
+    interface IOptions {
+        context: DocumentRegistry.IContext<DocumentRegistry.IModel>;
+        manager: ServiceManager.IManager;
+        connectionManager: IConnectionManager;
+        contentsManager: Contents.IManager;
+    }
+}

package/lib/pythonWidget/pythonWidgetModel.js

@@ -0,0 +1,75 @@
+import { PromiseDelegate } from '@lumino/coreutils';
+import { KernelExecutor } from './kernelExecutor';
+import { PathExt } from '@jupyterlab/coreutils';
+export class PythonWidgetModel {
+    constructor(options) {
+        this._isDisposed = false;
+        this._kernelStarted = false;
+        this._context = options.context;
+        this._manager = options.manager;
+        this._connectionManager = options.connectionManager;
+        this._contentsManager = options.contentsManager;
+    }
+    get isDisposed() {
+        return this._isDisposed;
+    }
+    get connectionManager() {
+        return this._connectionManager;
+    }
+    async initialize() {
+        var _a;
+        if (this._kernelStarted) {
+            return null;
+        }
+        const filePath = this._context.localPath;
+        const spkContent = this._context.model.toJSON();
+        const entryPath = PathExt.join(PathExt.dirname(filePath), spkContent.entry);
+        const entryContent = await this._contentsManager.get(entryPath, {
+            content: true,
+            format: 'text'
+        });
+        const sessionManager = this._manager.sessions;
+        await sessionManager.ready;
+        await this._manager.kernelspecs.ready;
+        const specs = this._manager.kernelspecs.specs;
+        if (!specs) {
+            return null;
+        }
+        const { kernelspecs } = specs;
+        let kernelName = Object.keys(kernelspecs)[0];
+        if (kernelspecs[specs.default]) {
+            kernelName = specs.default;
+        }
+        this._sessionConnection = await sessionManager.startNew({
+            name: filePath,
+            path: filePath,
+            kernel: {
+                name: kernelName
+            },
+            type: 'notebook'
+        });
+        const executor = new KernelExecutor({
+            sessionConnection: this._sessionConnection
+        });
+        const data = await this._connectionManager.registerConnection(executor);
+        await executor.init({
+            initCode: entryContent.content,
+            ...data
+        });
+        const finish = new PromiseDelegate();
+        const cb = (_, status) => {
+            var _a;
+            if (status === 'idle') {
+                (_a = this._sessionConnection.kernel) === null || _a === void 0 ? void 0 : _a.statusChanged.disconnect(cb);
+                finish.resolve();
+            }
+        };
+        (_a = this._sessionConnection.kernel) === null || _a === void 0 ? void 0 : _a.statusChanged.connect(cb);
+        await finish.promise;
+        this._kernelStarted = true;
+        return data;
+    }
+    dispose() {
+        this._isDisposed = true;
+    }
+}

package/lib/sandpackWidget/sandpackFilesModel.d.ts

@@ -0,0 +1,27 @@
+import { Contents } from '@jupyterlab/services';
+import { ISignal } from '@lumino/signaling';
+import { IDict } from '../type';
+export declare class SandpackFilesModel {
+    constructor(options: {
+        contentsManager: Contents.IManager;
+        path: string;
+    });
+    getAllFiles(): Promise<IDict<{
+        code: string;
+    }>>;
+    get fileChanged(): ISignal<SandpackFilesModel, {
+        allFiles: IDict<{
+            code: string;
+        }>;
+    }>;
+    flattenDirectory(dirContent: Contents.IModel): Promise<IDict<{
+        code: string;
+    }>>;
+    private _onFileChanged;
+    private _removeRoot;
+    private _getContent;
+    private _path;
+    private _fileChanged;
+    private _contentManager;
+    private _allFiles?;
+}