Options
All
  • Public
  • Public/Protected
  • All
Menu

Package commutable

@nteract/commutable

Commutable is a package to represent a Jupyter notebook document, as well as operations on the notebook, as a series of immutable notebooks, each one with its own state at a point in time.

This package follows the principles below, based on Tom MacWright's outline for practical undo.

  • A notebook document is immutable. The notebook document's representation is never mutated in-place.
  • Changes to a notebook document are encapsulated into operations that take a previous version and return a new version of the notebook without modifying the old version.
  • History is represented as a list of states, with the past on one end, the present on the other, and an index that can back up into 'undo states'.
  • Modifying a notebook document causes any future states to be thrown away.

Installation

$ yarn add @nteract/commutable
$ npm install --save @nteract/commutable

Usage

The example below shows how we can create an empty Markdown cell in our nteract notebook application. We use the emptyMarkdownCell immutable object exported from this package to represent a new empty Markdown cell in a notebook document.

import { emptyMarkdownCell } from "@nteract/commutable";


export default () => (
  <MarkdownPreview
    id="a-random-cell-id"
    cell={emptyMarkdownCell}
    editorFocused={false}
  />
);

Documentation

You can view the reference documentation for @nteract/commutable in the package docs.

Support

If you experience an issue while using this package or have a feature request, please file an issue on the issue board and, if possible, add the pkg:commutable label.

License

BSD-3-Clause

Index

Interfaces

Type aliases

Variables

Functions

Object literals

Type aliases

Cell

Cell: CodeCell | MarkdownCell | RawCell

Cell

Cell: RawCell | MarkdownCell | HeadingCell | CodeCell

CellId

CellId: string

CellType

CellType: "raw" | "markdown" | "code"

DeepReadonly

DeepReadonly<T>: object

Type parameters

  • T

Type declaration

ExecutionCount

ExecutionCount: number | null

ImmutableCell

ImmutableCell: ImmutableMarkdownCell | ImmutableCodeCell | ImmutableRawCell

ImmutableCodeCell

ImmutableCodeCell: RecordOf<CodeCellParams>

ImmutableDisplayData

ImmutableDisplayData: RecordOf<DisplayDataParams>

ImmutableErrorOutput

ImmutableErrorOutput: RecordOf<ErrorOutputParams>

ImmutableExecuteResult

ImmutableExecuteResult: RecordOf<ExecuteResultParams>

ImmutableJSONList

ImmutableJSONList: List<any>

ImmutableJSONMap

ImmutableJSONMap: Map<string, any>

ImmutableJSONType

ImmutableJSONType: PrimitiveImmutable | ImmutableJSONMap | ImmutableJSONList

ImmutableMarkdownCell

ImmutableMarkdownCell: RecordOf<MarkdownCellParams>

ImmutableNotebook

ImmutableNotebook: Record<NotebookRecordParams> & Readonly<NotebookRecordParams>

ImmutableOutput

ImmutableOutput: ImmutableExecuteResult | ImmutableDisplayData | ImmutableStreamOutput | ImmutableErrorOutput

ImmutableRawCell

ImmutableRawCell: RecordOf<RawCellParams>

ImmutableStreamOutput

ImmutableStreamOutput: RecordOf<StreamOutputParams>

JSONType

JSONType: PrimitiveImmutable | JSONObject | JSONArray

MimePayload

MimePayload: object

Type declaration

MimeTypeKey

MimeTypeKey: keyof object

MultiLineString

MultiLineString: string | string[]

Notebook

Notebook: NotebookV4 | NotebookV3

OnDiskOutput

OnDiskOutput: OnDiskExecuteResult | OnDiskDisplayData | OnDiskStreamOutput | OnDiskErrorOutput

Output

Output: ExecuteResult | DisplayData | StreamOutput | ErrorOutput

PrimitiveImmutable

PrimitiveImmutable: string | number | boolean | null

Variables

Const IS_VEGA

IS_VEGA: RegExp = /^application\/vnd.vega(.*\+)json$/

Const createCodeCell

createCodeCell: Factory<CodeCellParams> = makeCodeCell

Const createMarkdownCell

createMarkdownCell: Factory<MarkdownCellParams> = makeMarkdownCell

Const createNotebook

createNotebook: Factory<NotebookRecordParams> = makeNotebookRecord

Const defaultNotebook

defaultNotebook: Record<NotebookRecordParams> & object = makeNotebookRecord()

Const emptyCodeCell

emptyCodeCell: Record<CodeCellParams> & object = createCodeCell()

Const emptyMarkdownCell

emptyMarkdownCell: Record<MarkdownCellParams> & object = createMarkdownCell()

Const emptyMediaBundle

emptyMediaBundle: object = Object.freeze({})

Type declaration

Const emptyNotebook

emptyNotebook: Record<NotebookRecordParams> & object = makeNotebookRecord()

Const makeCodeCell

makeCodeCell: Factory<CodeCellParams> = Record<CodeCellParams>({cell_type: "code",execution_count: null,metadata: ImmutableMap({collapsed: false,jupyter: ImmutableMap({source_hidden: false,outputs_hidden: false}),nteract: ImmutableMap({transient: ImmutableMap({deleting: false})})}),source: "",outputs: ImmutableList()})

Const makeDisplayData

makeDisplayData: Factory<DisplayDataParams> = Record<DisplayDataParams>({data: emptyMediaBundle,metadata: ImmutableMap(),output_type: "display_data"})

Const makeErrorOutput

makeErrorOutput: Factory<ErrorOutputParams> = Record<ErrorOutputParams>({ename: "",evalue: "",output_type: "error",traceback: ImmutableList()})

Const makeExecuteResult

makeExecuteResult: Factory<ExecuteResultParams> = Record<ExecuteResultParams>({data: emptyMediaBundle,execution_count: null,metadata: ImmutableMap(),output_type: "execute_result"})

Const makeMarkdownCell

makeMarkdownCell: Factory<MarkdownCellParams> = Record<MarkdownCellParams>({cell_type: "markdown",metadata: ImmutableMap({nteract: ImmutableMap({transient: ImmutableMap({deleting: false})})}),source: ""})

Const makeNotebookRecord

makeNotebookRecord: Factory<NotebookRecordParams> = Record<NotebookRecordParams>({cellOrder: ImmutableList(),cellMap: ImmutableMap(),nbformat_minor: 0,nbformat: 4,metadata: ImmutableMap()})

Const makeRawCell

makeRawCell: Factory<RawCellParams> = Record<RawCellParams>({cell_type: "raw",metadata: ImmutableMap({nteract: ImmutableMap({transient: ImmutableMap({deleting: false})})}),source: ""})

Const makeStreamOutput

makeStreamOutput: Factory<StreamOutputParams> = Record<StreamOutputParams>({name: "stdout",output_type: "stream",text: ""})

Const monocellNotebook

monocellNotebook: Record<NotebookRecordParams> & object = appendCellToNotebook(emptyNotebook,emptyCodeCell)

A new 'monocell' notebook with a single empty code cell. This function is useful if you are looking to initialize a fresh, new notebook.

Functions

appendCell

  • A function that appends a new cell to a CellStructure object.

    Parameters

    • cellStructure: CellStructure

      The cellOrder and cellMap of the current notebook

    • immutableCell: ImmutableCell

      The cell that will be inserted into the cellStructure

    • Default value id: CellId = createCellId()

      The id of the new cell, defaults to a new UUID

    Returns CellStructure

    Cell structure with the new cell appended at the end

appendCellToNotebook

cellToJS

codeCellToJS

createCellId

createFrozenMediaBundle

createImmutableCell

  • Converts a JSON representation of a cell of any type to the correct immutable representation, per the v4 nbformat specification.

    Parameters

    • cell: Cell

      A JSON representation of a cell.

    Returns ImmutableCell

    An immutable representation of the same cell.

createImmutableCell

  • createImmutableCell(cell: Cell): any

createImmutableCodeCell

createImmutableCodeCell

createImmutableHeadingCell

createImmutableMarkdownCell

createImmutableMarkdownCell

createImmutableMediaBundle

createImmutableMetadata

  • createImmutableMetadata(metadata: JSONObject): ImmutableMap<any, any>

  • Converts a mutable representation of metadata to an immutable representation.

    Parameters

    • metadata: JSONObject

      A JSON representation of notebook metadata.

    Returns ImmutableMap<any, any>

    ImmutableMetadata An immutable representation of the metadata.

createImmutableOutput

createImmutableOutput

createImmutableRawCell

createImmutableRawCell

createOnDiskMediaBundle

deepFreeze

deleteCell

demultiline

  • demultiline(s: string | string[]): string

freezeReviver

  • freezeReviver<T>(_k: string, v: T): Readonly<T>

fromJS

fromJS

fromJS

insertCellAfter

insertCellAt

isJSONKey

  • isJSONKey(key: string): boolean

isNotebookV3

  • isNotebookV3(value: any): value is NotebookV3

isNotebookV4

  • isNotebookV4(value: any): value is NotebookV4

markCellDeleting

markCellNotDeleting

markdownCellToJS

metadataToJS

  • metadataToJS(immMetadata: ImmutableMap<string, any>): JSONObject

outputToJS

parseNotebook

  • parseNotebook(notebookString: string): Notebook

  • Converts a string representation of a notebook into a JSON representation.

    Parameters

    • notebookString: string

      A string representation of a notebook.

    Returns Notebook

    A JSON representation of the same notebook.

rawCellToJS

removeCell

remultiline

  • remultiline(s: string | string[]): string[]

  • Split string into a list of strings delimited by newlines; useful for on-disk git comparisons; and is the expectation for jupyter notebooks on disk

    Parameters

    • s: string | string[]

    Returns string[]

stringifyNotebook

  • stringifyNotebook(notebook: Notebook): string

  • Converts a JSON representation of a notebook into a string representation.

    Parameters

    • notebook: Notebook

      The JSON representation of a notebook.

    Returns string

    A string containing the notebook data.

toJS

toJS

  • Converts an immutable representation of a notebook to a JSON representation of the notebook using the v4 of the nbformat specification.

    Parameters

    Returns NotebookV4

    The JSON representation of a notebook.

Object literals

Const VALID_MIMETYPES

VALID_MIMETYPES: object

html

html: string = "text/html"

javascript

javascript: string = "application/x-javascript"

jpeg

jpeg: string = "image/jpeg"

json

json: string = "application/javascript"

latex

latex: string = "text/latex"

pdf

pdf: string = "application/pdf"

png

png: string = "image/png"

svg

svg: string = "image/svg+xml"

text

text: string = "text/plain"

Generated using TypeDoc