CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-jupyterlab--nbformat

Notebook format interfaces and utilities for working with Jupyter Notebook format specifications

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

JupyterLab NBFormat

JupyterLab NBFormat provides comprehensive TypeScript interfaces and utilities for working with Jupyter Notebook format (nbformat) specifications. It defines strongly-typed interfaces for all notebook components including cells (code, markdown, raw), outputs (execute results, display data, streams, errors), metadata structures, and MIME bundles, enabling type-safe operations on notebook documents and consistent handling of notebook format versions.

Package Information

  • Package Name: @jupyterlab/nbformat
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @jupyterlab/nbformat

Core Imports

import * as nbformat from "@jupyterlab/nbformat";

Or with specific imports:

import { 
  INotebookContent, 
  ICell, 
  ICodeCell, 
  validateMimeValue, 
  isCode,
  MAJOR_VERSION 
} from "@jupyterlab/nbformat";

For CommonJS:

const nbformat = require("@jupyterlab/nbformat");
const { INotebookContent, validateMimeValue, isCode } = require("@jupyterlab/nbformat");

Basic Usage

import { 
  INotebookContent, 
  ICodeCell, 
  validateMimeValue, 
  isCode, 
  MAJOR_VERSION, 
  MINOR_VERSION 
} from "@jupyterlab/nbformat";

// Check format version compatibility
console.log(`Supporting nbformat ${MAJOR_VERSION}.${MINOR_VERSION}+`);

// Create a basic notebook structure
const notebook: INotebookContent = {
  metadata: {
    kernelspec: {
      name: "python3",
      display_name: "Python 3"
    },
    language_info: {
      name: "python",
      version: "3.8.0"
    }
  },
  nbformat: 4,
  nbformat_minor: 4,
  cells: []
};

// Type-safe cell operations
const cells = notebook.cells;
cells.forEach(cell => {
  if (isCode(cell)) {
    console.log(`Code cell with ${cell.outputs.length} outputs`);
    console.log(`Execution count: ${cell.execution_count}`);
  }
});

// Validate MIME data
const isValid = validateMimeValue("text/plain", "Hello, world!");
console.log(`MIME validation result: ${isValid}`);

Architecture

JupyterLab NBFormat is organized around several core concepts:

  • Notebook Structure: Complete notebook document format with metadata and cells
  • Cell Types: Strongly-typed interfaces for code, markdown, and raw cells
  • Output System: Type-safe representation of cell execution results
  • MIME Handling: Validation and type checking for multimedia content
  • Type Guards: Runtime type checking functions for cells and outputs
  • Version Compatibility: Constants and interfaces supporting nbformat 4.4+

Capabilities

Notebook and Metadata Interfaces

Core interfaces for notebook documents, metadata structures, and format specifications. Essential for creating and manipulating notebook files programmatically.

interface INotebookContent extends PartialJSONObject {
  metadata: INotebookMetadata;
  nbformat_minor: number;
  nbformat: number;
  cells: ICell[];
}

interface INotebookMetadata extends PartialJSONObject {
  kernelspec?: IKernelspecMetadata;
  language_info?: ILanguageInfoMetadata;
  orig_nbformat?: number;
}

const MAJOR_VERSION: number;
const MINOR_VERSION: number;

Notebook and Metadata

Cell Interfaces and Types

Comprehensive type definitions for all notebook cell types including code, markdown, and raw cells, with their associated metadata structures.

type ICell = IRawCell | IMarkdownCell | ICodeCell | IUnrecognizedCell;
type CellType = 'code' | 'markdown' | 'raw' | string;

interface ICodeCell extends IBaseCell {
  id?: string;
  cell_type: 'code';
  metadata: Partial<ICodeCellMetadata>;
  outputs: IOutput[];
  execution_count: ExecutionCount;
}

function isCode(cell: ICell): cell is ICodeCell;
function isMarkdown(cell: ICell): cell is IMarkdownCell;
function isRaw(cell: ICell): cell is IRawCell;

Cell Interfaces

Output Interfaces and Types

Type-safe interfaces for all cell output types including execution results, display data, streams, and errors, with comprehensive type guard functions.

type IOutput = IUnrecognizedOutput | IExecuteResult | IDisplayData | IStream | IError;
type OutputType = 'execute_result' | 'display_data' | 'stream' | 'error' | 'update_display_data';

interface IExecuteResult extends IBaseOutput {
  output_type: 'execute_result';
  execution_count: ExecutionCount;
  data: IMimeBundle;
  metadata: OutputMetadata;
}

function isExecuteResult(output: IOutput): output is IExecuteResult;
function isDisplayData(output: IOutput): output is IDisplayData;
function isStream(output: IOutput): output is IStream;
function isError(output: IOutput): output is IError;

Output Interfaces

MIME and Validation Utilities

MIME bundle interfaces and validation functions for handling multimedia content in notebook cells, ensuring data integrity and format compliance.

interface IMimeBundle extends PartialJSONObject {
  [key: string]: MultilineString | PartialJSONObject;
}

type MultilineString = string | string[];

function validateMimeValue(
  type: string,
  value: MultilineString | PartialJSONObject
): boolean;

MIME and Validation

Types

type ExecutionCount = number | null;
type OutputMetadata = PartialJSONObject;
type StreamType = 'stdout' | 'stderr';

interface IAttachments {
  [key: string]: IMimeBundle | undefined;
}

type ICellMetadata = IBaseCellMetadata | IRawCellMetadata | ICodeCellMetadata;

// From @lumino/coreutils - base type for JSON-compatible objects
type PartialJSONObject = { [key: string]: any };
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@jupyterlab/nbformat@4.4.x
Publish Source
CLI
Badge
tessl/npm-jupyterlab--nbformat badge