or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cell-interfaces.mdindex.mdmime-validation.mdnotebook-metadata.mdoutput-interfaces.md
tile.json

tessl/npm-jupyterlab--nbformat

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@jupyterlab/nbformat@4.4.x

To install, run

npx @tessl/cli install tessl/npm-jupyterlab--nbformat@4.4.0

index.mddocs/

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 };