jupyterlab_tabular_data_viewer_extension 1.1.20

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Stellars Henson
+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,145 @@
+# jupyterlab_tabular_data_viewer_extension
+
+![GitHub Actions](https://github.com/stellarshenson/jupyterlab_tabular_data_viewer_extension/actions/workflows/build.yml/badge.svg)
+[![npm version](https://badge.fury.io/js/jupyterlab_tabular_data_viewer_extension.svg)](https://www.npmjs.com/package/jupyterlab_tabular_data_viewer_extension)
+[![PyPI version](https://badge.fury.io/py/jupyterlab-tabular-data-viewer-extension.svg)](https://pypi.org/project/jupyterlab-tabular-data-viewer-extension/)
+[![Total PyPI downloads](https://static.pepy.tech/badge/jupyterlab-tabular-data-viewer-extension)](https://pepy.tech/project/jupyterlab-tabular-data-viewer-extension)
+![JL4 Ready](https://img.shields.io/badge/Jupyterlab%204-ready-blue)
+
+View and browse Parquet, Excel, CSV, and TSV files directly in JupyterLab. Double-click any .parquet, .xlsx, .csv, or .tsv file to open it in a simple, spreadsheet-like table view - no code required. Navigate through your data, inspect values, and explore the structure of your tabular data files with interactive column resizing and advanced filtering capabilities.
+
+![Parquet Viewer](.resources/screenshot.png)
+
+## Features
+
+**Supported File Formats:**
+- **Parquet files** (.parquet) - Full support with efficient columnar data reading
+- **Excel files** (.xlsx) - Reads first worksheet only. Excel files must be simple tabular data without merged cells, complex formulas, or advanced formatting. Files with these features may not display correctly or fail to load
+- **CSV files** (.csv) - Comma-separated values with UTF-8 encoding (fallback to latin1)
+- **TSV files** (.tsv) - Tab-separated values with UTF-8 encoding (fallback to latin1)
+
+**Core viewing and navigation:**
+- Simple table display showing your data in familiar spreadsheet format
+- Column headers with field names and simplified datatype indicators
+- Interactive column resizing - drag column borders to adjust width independently
+- Progressive loading - starts with 500 rows, automatically loads more as you scroll
+- File statistics (column count, row count, file size) at a glance
+- Fixed status bar remains visible during horizontal scrolling
+- Handles large files efficiently with server-side processing
+
+**Advanced filtering and sorting:**
+- Column sorting with three-state toggle (ascending, descending, off)
+- Per-column filtering with substring or regex pattern matching
+- Case-insensitive search option
+- Numerical filters supporting comparison operators (`>`, `<`, `>=`, `<=`, `=`)
+- Clear filters functionality to reset all active filters
+- Multiple filters work together to narrow down results
+
+**Additional features:**
+- Right-click context menu on rows to copy data as JSON
+- Configurable file type support via Settings - Enable/disable Parquet, Excel, or CSV/TSV handling
+- All features work seamlessly across all supported file formats
+
+## Installation
+
+Requires JupyterLab 4.0.0 or higher.
+
+```bash
+pip install jupyterlab_tabular_data_viewer_extension
+```
+
+Uninstall:
+```bash
+pip uninstall jupyterlab_tabular_data_viewer_extension
+```
+
+## Configuration
+
+Configure file type support through JupyterLab Settings:
+
+1. Open **Settings → Settings Editor**
+2. Search for "Parquet Viewer Extension"
+3. Configure options:
+   - **Enable Parquet files** - Default: enabled
+   - **Enable Excel files** - Default: disabled (enable to view .xlsx files)
+
+When a file type is disabled, files open with JupyterLab's default handler instead.
+
+## Troubleshooting
+
+Verify both extension components are enabled if the extension doesn't work:
+
+```bash
+# Check server extension
+jupyter server extension list
+
+# Check frontend extension
+jupyter labextension list
+```
+
+Both commands should show `jupyterlab_tabular_data_viewer_extension` as enabled. Reinstall if either is missing or disabled.
+
+## Development Setup
+
+Requires NodeJS for building TypeScript frontend. Uses `jlpm` (JupyterLab's pinned yarn version) for consistency.
+
+**Initial setup:**
+
+```bash
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate
+
+# Install in editable mode
+pip install --editable ".[dev,test]"
+
+# Link frontend and enable server extension
+jupyter labextension develop . --overwrite
+jupyter server extension enable jupyterlab_tabular_data_viewer_extension
+```
+
+**Development workflow:**
+
+Use two terminals for efficient development:
+- Terminal 1: `jlpm watch` (auto-rebuild on file changes)
+- Terminal 2: `jupyter lab` (run development instance)
+
+Refresh browser after changes to see updates. Build generates source maps for debugging.
+
+Enable deeper debugging with unminimized JupyterLab build:
+```bash
+jupyter lab build --minimize=False
+```
+
+**Removing development installation:**
+
+```bash
+jupyter server extension disable jupyterlab_tabular_data_viewer_extension
+pip uninstall jupyterlab_tabular_data_viewer_extension
+```
+
+Then delete the `jupyterlab_tabular_data_viewer_extension` symlink from your `labextensions` directory (find with `jupyter labextension list`).
+
+## Testing
+
+Three-tier testing strategy: Python backend, TypeScript frontend, and integration tests.
+
+**Python tests** (pytest with coverage):
+```bash
+pip install -e ".[test]"
+jupyter labextension develop . --overwrite
+pytest -vv -r ap --cov jupyterlab_tabular_data_viewer_extension
+```
+
+**TypeScript tests** (Jest):
+```bash
+jlpm
+jlpm test
+```
+
+**Integration tests** (Playwright + Galata):
+Simulates real user interactions to validate complete workflows. See [ui-tests README](./ui-tests/README.md) for detailed instructions.
+
+## Packaging and Release
+
+See [RELEASE.md](RELEASE.md) for instructions on building distributable packages and publishing releases.

package/lib/document.d.ts

@@ -0,0 +1,8 @@
+import { DocumentWidget } from '@jupyterlab/docregistry';
+import { TabularDataViewer } from './widget';
+/**
+ * A document widget for tabular data files (Parquet, Excel)
+ */
+export declare class TabularDataDocument extends DocumentWidget<TabularDataViewer> {
+    constructor(options: DocumentWidget.IOptions<TabularDataViewer>);
+}

package/lib/document.js

@@ -0,0 +1,9 @@
+import { DocumentWidget } from '@jupyterlab/docregistry';
+/**
+ * A document widget for tabular data files (Parquet, Excel)
+ */
+export class TabularDataDocument extends DocumentWidget {
+    constructor(options) {
+        super(options);
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * Initialization data for the jupyterlab_tabular_data_viewer_extension extension.
+ */
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;

package/lib/index.js

@@ -0,0 +1,214 @@
+import { ABCWidgetFactory } from '@jupyterlab/docregistry';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { TabularDataViewer } from './widget';
+import { TabularDataDocument } from './document';
+/**
+ * A widget factory for Parquet files
+ */
+class TabularDataWidgetFactory extends ABCWidgetFactory {
+    constructor(options, setLastContextMenuRow, setActiveWidget) {
+        super(options);
+        this._setLastContextMenuRow = setLastContextMenuRow;
+        this._setActiveWidget = setActiveWidget;
+    }
+    /**
+     * Create a new widget given a context
+     */
+    createNewWidget(context) {
+        // console.log(`[Tabular Data Viewer] Creating widget for file: ${context.path}`);
+        // console.log(`[Tabular Data Viewer] File type: ${context.contentsModel?.type}, Format: ${context.contentsModel?.format}`);
+        const content = new TabularDataViewer(context.path, this._setLastContextMenuRow);
+        const widget = new TabularDataDocument({ content, context });
+        widget.title.label = context.path.split('/').pop() || 'Tabular Data File';
+        // Track this as the active widget when context menu is used
+        this._setActiveWidget(content);
+        return widget;
+    }
+}
+/**
+ * Initialization data for the jupyterlab_tabular_data_viewer_extension extension.
+ */
+const plugin = {
+    id: 'jupyterlab_tabular_data_viewer_extension:plugin',
+    description: 'Jupyterlab extension to allow simple browsing of tabular data files (Parquet, Excel) with filtering and sorting capabilities',
+    autoStart: true,
+    requires: [ISettingRegistry],
+    activate: async (app, settingRegistry) => {
+        // console.log(
+        //   'JupyterLab extension jupyterlab_tabular_data_viewer_extension is activated!'
+        // );
+        const { docRegistry, commands, contextMenu } = app;
+        // Track last right-clicked row for context menu
+        let lastContextMenuRow = null;
+        let activeWidget = null;
+        // Load settings
+        let settings = {
+            enableParquet: true,
+            enableExcel: true,
+            enableCSV: true,
+            enableTSV: true
+        };
+        // console.log('[Tabular Data Viewer] Default settings:', settings);
+        try {
+            // console.log('[Tabular Data Viewer] Loading settings from registry with id:', plugin.id);
+            const pluginSettings = await settingRegistry.load(plugin.id);
+            settings = pluginSettings.composite;
+            // console.log('[Tabular Data Viewer] Loaded settings:', settings);
+            // console.log('[Tabular Data Viewer] Settings detail - enableParquet:', settings.enableParquet, 'enableExcel:', settings.enableExcel);
+            // Watch for settings changes
+            pluginSettings.changed.connect(() => {
+                settings = pluginSettings.composite;
+                // console.log('[Tabular Data Viewer] Settings changed:', settings);
+            });
+        }
+        catch (error) {
+            console.error('[Tabular Data Viewer] Failed to load settings:', error);
+            // console.log('[Tabular Data Viewer] Using default settings:', settings);
+        }
+        // Command to copy row as JSON
+        const copyRowCommand = 'tabular-data-viewer:copy-row-json';
+        commands.addCommand(copyRowCommand, {
+            label: 'Copy Row as JSON',
+            caption: 'Copy the row data as JSON to clipboard',
+            isEnabled: () => {
+                return lastContextMenuRow !== null;
+            },
+            execute: async () => {
+                if (lastContextMenuRow) {
+                    const jsonString = JSON.stringify(lastContextMenuRow, null, 2);
+                    await navigator.clipboard.writeText(jsonString);
+                    // console.log('Row copied to clipboard as JSON');
+                    // Clean up highlight after copy
+                    if (activeWidget) {
+                        activeWidget.getCleanupHighlight()();
+                    }
+                }
+            }
+        });
+        // Add to context menu for tabular data viewer rows
+        contextMenu.addItem({
+            command: copyRowCommand,
+            selector: '.jp-TabularDataViewer-row',
+            rank: 10
+        });
+        // Register file types based on settings
+        // console.log('[Tabular Data Viewer] Starting file type registration...');
+        // console.log('[Tabular Data Viewer] Current settings state:', settings);
+        const binaryFileTypes = [];
+        const textFileTypes = [];
+        // Register Parquet file type if enabled
+        if (settings.enableParquet) {
+            try {
+                docRegistry.addFileType({
+                    name: 'parquet',
+                    displayName: 'Parquet',
+                    extensions: ['.parquet'],
+                    mimeTypes: ['application/x-parquet'],
+                    iconClass: 'jp-MaterialIcon jp-SpreadsheetIcon',
+                    contentType: 'file',
+                    fileFormat: 'base64'
+                });
+                binaryFileTypes.push('parquet');
+                // console.log('[Tabular Data Viewer] Parquet file type registered');
+            }
+            catch (e) {
+                console.warn('[Tabular Data Viewer] Parquet file type already registered', e);
+            }
+        }
+        // Register Excel file type if enabled
+        if (settings.enableExcel) {
+            try {
+                docRegistry.addFileType({
+                    name: 'xlsx-parquet-viewer',
+                    displayName: 'Excel (Parquet Viewer)',
+                    extensions: ['.xlsx'],
+                    mimeTypes: ['application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
+                    iconClass: 'jp-MaterialIcon jp-SpreadsheetIcon',
+                    contentType: 'file',
+                    fileFormat: 'base64'
+                });
+                binaryFileTypes.push('xlsx-parquet-viewer');
+                // console.log('[Tabular Data Viewer] Excel file type registered');
+            }
+            catch (e) {
+                console.warn('[Tabular Data Viewer] Excel file type already registered', e);
+            }
+        }
+        // Register CSV file type if enabled
+        if (settings.enableCSV) {
+            try {
+                docRegistry.addFileType({
+                    name: 'csv-tabular-viewer',
+                    displayName: 'CSV (Tabular Viewer)',
+                    extensions: ['.csv'],
+                    mimeTypes: ['text/csv'],
+                    iconClass: 'jp-MaterialIcon jp-SpreadsheetIcon',
+                    contentType: 'file',
+                    fileFormat: 'text'
+                });
+                textFileTypes.push('csv-tabular-viewer');
+                // console.log('[Tabular Data Viewer] CSV file type registered');
+            }
+            catch (e) {
+                console.warn('[Tabular Data Viewer] CSV file type already registered', e);
+            }
+        }
+        // Register TSV file type if enabled
+        if (settings.enableTSV) {
+            try {
+                docRegistry.addFileType({
+                    name: 'tsv-tabular-viewer',
+                    displayName: 'TSV (Tabular Viewer)',
+                    extensions: ['.tsv'],
+                    mimeTypes: ['text/tab-separated-values'],
+                    iconClass: 'jp-MaterialIcon jp-SpreadsheetIcon',
+                    contentType: 'file',
+                    fileFormat: 'text'
+                });
+                textFileTypes.push('tsv-tabular-viewer');
+                // console.log('[Tabular Data Viewer] TSV file type registered');
+            }
+            catch (e) {
+                console.warn('[Tabular Data Viewer] TSV file type already registered', e);
+            }
+        }
+        // Create binary factory for Parquet and Excel files
+        if (binaryFileTypes.length > 0) {
+            const binaryFactory = new TabularDataWidgetFactory({
+                name: 'Tabular Data Viewer (Binary)',
+                modelName: 'base64',
+                fileTypes: binaryFileTypes,
+                defaultFor: binaryFileTypes,
+                defaultRendered: binaryFileTypes,
+                readOnly: true
+            }, (row) => {
+                lastContextMenuRow = row;
+            }, (widget) => {
+                activeWidget = widget;
+            });
+            docRegistry.addWidgetFactory(binaryFactory);
+            // console.log(`[Tabular Data Viewer] Binary factory registered for: ${binaryFileTypes.join(', ')}`);
+        }
+        // Create text factory for CSV and TSV files
+        if (textFileTypes.length > 0) {
+            const textFactory = new TabularDataWidgetFactory({
+                name: 'Tabular Data Viewer (Text)',
+                modelName: 'text',
+                fileTypes: textFileTypes,
+                defaultFor: textFileTypes,
+                defaultRendered: textFileTypes,
+                readOnly: true
+            }, (row) => {
+                lastContextMenuRow = row;
+            }, (widget) => {
+                activeWidget = widget;
+            });
+            docRegistry.addWidgetFactory(textFactory);
+            // console.log(`[Tabular Data Viewer] Text factory registered for: ${textFileTypes.join(', ')}`);
+        }
+        if (binaryFileTypes.length === 0 && textFileTypes.length === 0) {
+            console.warn('[Tabular Data Viewer] No file types enabled in settings');
+        }
+    }
+};
+export default plugin;

package/lib/request.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Call the server extension
+ *
+ * @param endPoint API REST end point for the extension
+ * @param init Initial values for the request
+ * @returns The response body interpreted as JSON
+ */
+export declare function requestAPI<T>(endPoint?: string, init?: RequestInit): Promise<T>;

package/lib/request.js

@@ -0,0 +1,35 @@
+import { URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
+/**
+ * Call the server extension
+ *
+ * @param endPoint API REST end point for the extension
+ * @param init Initial values for the request
+ * @returns The response body interpreted as JSON
+ */
+export async function requestAPI(endPoint = '', init = {}) {
+    // Make request to Jupyter API
+    const settings = ServerConnection.makeSettings();
+    const requestUrl = URLExt.join(settings.baseUrl, 'jupyterlab-tabular-data-viewer-extension', // our server extension's API namespace
+    endPoint);
+    let response;
+    try {
+        response = await ServerConnection.makeRequest(requestUrl, init, settings);
+    }
+    catch (error) {
+        throw new ServerConnection.NetworkError(error);
+    }
+    let data = await response.text();
+    if (data.length > 0) {
+        try {
+            data = JSON.parse(data);
+        }
+        catch (error) {
+            console.log('Not a JSON response body.', response);
+        }
+    }
+    if (!response.ok) {
+        throw new ServerConnection.ResponseError(response, data.message || data);
+    }
+    return data;
+}

package/lib/widget.d.ts

@@ -0,0 +1,127 @@
+import { Widget } from '@lumino/widgets';
+/**
+ * Parquet viewer widget
+ */
+export declare class TabularDataViewer extends Widget {
+    private _filePath;
+    private _columns;
+    private _data;
+    private _totalRows;
+    private _unfilteredTotalRows;
+    private _currentOffset;
+    private _limit;
+    private _loading;
+    private _hasMore;
+    private _filters;
+    private _sortBy;
+    private _sortOrder;
+    private _fileSize;
+    private _caseInsensitive;
+    private _useRegex;
+    private _contextMenuOpen;
+    private _columnWidths;
+    private _resizing;
+    private _tableContainer;
+    private _table;
+    private _thead;
+    private _tbody;
+    private _filterRow;
+    private _headerRow;
+    private _statusBar;
+    private _statusLeft;
+    private _statusRight;
+    private _caseInsensitiveCheckbox;
+    private _regexCheckbox;
+    private _setLastContextMenuRow;
+    private _cleanupHighlight;
+    private _menuObserver;
+    constructor(filePath: string, setLastContextMenuRow: (row: any) => void);
+    /**
+     * Start observing for menu removal when context menu opens
+     */
+    private _startMenuObserver;
+    /**
+     * Get cleanup function to clear highlight (for external use)
+     */
+    getCleanupHighlight(): () => void;
+    /**
+     * Initialize the viewer by loading metadata and initial data
+     */
+    private _initialize;
+    /**
+     * Load file metadata (columns, types, row count)
+     */
+    private _loadMetadata;
+    /**
+     * Load data from server
+     */
+    private _loadData;
+    /**
+     * Render table headers with filter inputs
+     */
+    private _renderHeaders;
+    /**
+     * Render data rows
+     */
+    private _renderData;
+    /**
+     * Start column resize
+     */
+    private _startResize;
+    /**
+     * Handle column resize drag
+     */
+    private _doResize;
+    /**
+     * Stop column resize
+     */
+    private _stopResize;
+    /**
+     * Apply filter to a column
+     */
+    private _applyFilter;
+    /**
+     * Simplify type names for display
+     */
+    private _simplifyType;
+    /**
+     * Check if column type is numeric
+     */
+    private _isNumericType;
+    /**
+     * Get filter placeholder based on column type
+     */
+    private _getFilterPlaceholder;
+    /**
+     * Handle scroll event for progressive loading
+     */
+    private _onScroll;
+    /**
+     * Toggle sort on a column
+     */
+    private _toggleSort;
+    /**
+     * Update sort indicators in column headers
+     */
+    private _updateSortIndicators;
+    /**
+     * Clear all filters
+     */
+    private _clearFilters;
+    /**
+     * Format file size to human-readable string
+     */
+    private _formatFileSize;
+    /**
+     * Update status bar
+     */
+    private _updateStatusBar;
+    /**
+     * Show error message
+     */
+    private _showError;
+    /**
+     * Dispose of the widget
+     */
+    dispose(): void;
+}