schema

Documentation

Overview

Package schema defines the common data format for elements of a Jupyter notebook.

It is based on the v4.4 definition, as it is stable and encompasses all the data necessary for accurate rendering. Note, that schema validation is not a goal of this package, and so, interfaces defined here will often omit the non-essential data, e.g. metadata or fields specific to JupyterLab environment.

Index

• type Attachments
• type Cell
• type CellType
  • func (t CellType) String() string
• type CodeCell
• type ExecutionCounter
• type HasAttachments
• type MimeBundle
• type Notebook
• type NotebookMetadata
• type Outputter
• type Version
  • func (v Version) String() string

Types

type Attachments

type Attachments interface {
	// MimeBundle returns a mime-bundle associated with the filename.
	// If no data is present for the file, implementations should return nil.
	MimeBundle(filename string) MimeBundle
}

Attachments are data for inline images stored as a mime-bundle keyed by filename.

type Cell

type Cell interface {
	Type() CellType
	MimeType() string
	Text() []byte
}

Cell encapsulates the raw content of each notebook cell and its designated mime-type.

type CellType

type CellType int

CellType reports the intended cell type to the components that work with notebook cells through the Cell interface.

"markdown", "raw", "code", and "unrecognized" are official cell types, as defined in the nbformat JSON schema. Only "true" cells should use these to report their type.

"execute_result", "display_data", "stream", and "error" are, on the other hand, output types and only appear within the code cells. Although they aren't "true" cells with respect to the Jupyter's schema, functionally they are quite similar (output structs will, in fact, implement the Cell interface). They should use the predefined values to report their .CellType().

const (
	Unrecognized CellType = iota
	Markdown
	Raw
	Code

	ExecuteResult
	DisplayData
	Stream
	Error
)

func (CellType) String

func (t CellType) String() string

String returns the official enum values for cell and output types as defined in the JSON schema v4.5.

These values should not be depended on, as their representation may change in the future. They are only provided to make logs and test output more readable.

type CodeCell

type CodeCell interface {
	Cell
	Outputter
	ExecutionCounter

	Language() string
}

CodeCell contains the source code in the language of the document's associated kernel, and a list of outputs associated with executing that code.

type ExecutionCounter

type ExecutionCounter interface {
	ExecutionCount() int
}

type HasAttachments

type HasAttachments interface {
	// Attachments are only defined for v4.0 and above for markdown and raw cells
	// and may be omitted in the JSON. Cells without attachments should return nil.
	Attachments() Attachments
}

HasAttachments is implemented by cells which include cell attachments.

type MimeBundle

type MimeBundle interface {
	MimeType() string
	Text() []byte

	// PlainText returns the value associated with "text/plain" mime-type if present and a nil slice otherwise.
	// A renderer may want to fallback to this option if it is not able to render the richer mime-type.
	PlainText() []byte
}

MimeBundle holds rich display outputs, such as images, JSON, HTML, etc. A single output will often have 2 representations:

1. raw data, e.g. a base64-encoded image or JSON string/bytes, and
2. plain text representation of the original object (in Python it's the output of the __repr__() method).

MimeBundle partially implements Cell interface, hiding the above complexity from the caller. When reporting MimeType implementations should prefer "text/html", "image/png", and any other type to "text/plain", and only return the latter if it is the only available option.

Similarly, Text returns the value associated with the richer of the available mime-types.

type Notebook

type Notebook interface {
	Version() Version
	Cells() []Cell
}

Notebook is a common interface of the Jupyter Notebooks' different formats.

type NotebookMetadata

type NotebookMetadata interface {
	// Language reports the language of the document's associated kernel.
	Language() string
}

type Outputter

type Outputter interface {
	Outputs() []Cell
}

type Version

type Version struct {
	Major int
	Minor int
}

Version specifies an nbformat version.

func (Version) String

func (v Version) String() string