Notebook 파일 형식

1 개요

The Notebook file format
Notebook 파일 형식

https://nbformat.readthedocs.io/en/latest/format_description.html

공식 Jupyter Notebook 형식은 이 JSON 스키마로 정의되며, Jupyter 도구는 이를 사용해 노트북을 검증합니다.

이 페이지에는 노트북 형식에 대한 사람이 읽을 수 있는 설명이 포함되어 있습니다.

Note

모든 메타데이터 필드는 선택사항입니다. 일부 메타데이터 필드의 타입과 값은 정의되어 있지만, 어떤 메타데이터 필드도 정의할 필요가 없습니다. 또한, 모든 메타데이터 필드는 무시될 수도 있습니다.

2 최상위 구조

최상위 수준에서, Jupyter 노트북은 몇 가지 키를 가진 딕셔너리입니다:

metadata (dict)
nbformat (int)
nbformat_minor (int)
cells (list)

{
    "metadata": {
        "kernel_info": {
            # if kernel_info is defined, its name field is required.
            "name": "the name of the kernel"
        },
        "language_info": {
            # if language_info is defined, its name field is required.
            "name": "the programming language of the kernel",
            "version": "the version of the language",
            "codemirror_mode": "The name of the codemirror mode to use [optional]",
        },
    },
    "nbformat": 4,
    "nbformat_minor": 0,
    "cells": [
        # list of cell dictionaries, see below
    ],
}

코드 입력 및 텍스트 출력과 같은 일부 필드는 특성상 여러 줄로 된 문자열입니다. 이러한 필드가 디스크에 기록될 때는 문자열 목록으로 기록될 수 있으며, 메모리에 다시 읽을 때는 ''로 결합(join)해야 합니다. 노트북 파일을 직접 다루려면, 여러 줄로 된 문자열 필드가 문자열이거나 문자열 목록일 수 있도록 허용해야 합니다. 프로그램 API(Python, Javascript)를 사용하여 노트북을 다룰 때는 항상 원래의 여러 줄 문자열로 다시 결합됩니다.

3 셀 타입

코드와 텍스트를 캡슐화하는 기본 셀 타입이 몇 가지 있습니다. 모든 셀은 다음과 같은 기본 구조를 갖습니다:

{
    "cell_type": "type",
    "metadata": {},
    "source": "single string or [list, of, strings]"
}

Note

디스크 상에서, 여러 줄 문자열은 리스트로 나눌 수 있습니다. nbformat Python API로 읽을 때, 이러한 여러 줄 문자열은 항상 하나의 문자열이 됩니다.

3.1 마크다운 셀

마크다운 셀은 본문 텍스트에 사용되며, GitHub향 마크다운으로 정의되고 marked에서 구현된 마크다운을 포함합니다.

{
    "cell_type": "markdown",
    "metadata": {},
    "source": "[multi-line *markdown*]"
}

Warning

nbformat 버전 4.0에서 변경됨
헤딩 셀은 마크다운의 간단한 헤딩으로 대체되었습니다.

3.2 코드 셀

코드 셀은 Jupyter 노트북의 주요 콘텐츠입니다. 이 셀은 문서와 연결된 커널의 언어로 작성된 소스코드를 포함하며, 그 코드 실행과 연관된 출력 목록을 가지고 있습니다. 코드 셀은, 정수 또는 null이어야 하는 execution_count도 포함합니다.

{
    "cell_type": "code",
    "execution_count": 1,  # integer or null
    "metadata": {
        "collapsed": True,  # whether the output of the cell is collapsed
        "scrolled": False,  # any of true, false or "auto"
    },
    "source": "[some multi-line code]",
    "outputs": [
        {
            # list of output dicts (described below)
            "output_type": "stream",
            # ...
        }
    ],
}

Warning

nbformat 버전 4.0에서 변경됨
셀 타입 간의 일관성을 위해 input이 source로 이름이 변경되었습니다.

Warning

nbformat 버전 4.0에서 변경됨
prompt_number가 execution_count로 이름이 변경되었습니다.

3.3 코드 셀 출력

코드 셀은 다양한 출력(스트림 데이터 또는 리치 mime-타입 출력)을 가질 수 있습니다. 이러한 출력은 셀을 실행한 결과로 생성된 메시지에 해당합니다.

모든 출력에는 출력 타입을 정의하는 문자열인 output_type 필드가 있습니다.

3.3.1 스트림 출력

{
    "output_type": "stream",
    "name": "stdout",  # or stderr
    "text": "[multiline stream text]",
}

Warning

nbformat 버전 4.0에서 변경됨
stream 키가 스트림 메시지와 일치하도록 name으로 변경되었습니다.

3.3.2 display_data

display_data 메시지로 생성된 리치 디스플레이 출력은 MIME 타입으로 키가 지정된 데이터를 포함합니다. 이는 종종 MIME 번들(mime-bundle)이라고 불리며, 노트북 형식 및 메시지 사양의 다양한 위치에 나타납니다. 이러한 메시지의 메타데이터도 MIME 타입으로 키가 지정될 수 있습니다.

{
    "output_type": "display_data",
    "data": {
        "text/plain": "[multiline text data]",
        "image/png": "[base64-encoded-multiline-png-data]",
        "application/json": {
            # JSON data is included as-is
            "key1": "data",
            "key2": ["some", "values"],
            "key3": {"more": "data"},
        },
        "application/vnd.exampleorg.type+json": {
            # JSON data, included as-is, when the mime-type key ends in +json
            "key1": "data",
            "key2": ["some", "values"],
            "key3": {"more": "data"},
        },
    },
    "metadata": {
        "image/png": {
            "width": 640,
            "height": 480,
        },
    },
}

Warning

nbformat 버전 4.0에서 변경됨
application/json 출력은 더 이상 문자열로 이중 직렬화되지 않습니다.

Warning

nbformat 버전 4.0에서 변경됨
mime-types는 짧은 이름(text)과 mime-types의 조합 대신 키로 사용되며, 최상위 레벨이 아닌 data 키에 저장됩니다. 예를 들어, output.png 대신 output.data['image/png']입니다.

3.3.3 execute_result

셀을 실행한 결과(파이썬에서 displayhook에 의해 생성됨)는 execute_result 출력에 저장됩니다. execute_result 출력은 display_data와 동일하며, 정수여야 하는 execution_count 필드만 추가됩니다.

{
    "output_type": "execute_result",
    "execution_count": 42,
    "data": {
        "text/plain": "[multiline text data]",
        "image/png": "[base64-encoded-multiline-png-data]",
        "application/json": {
            # JSON data is included as-is
            "json": "data",
        },
    },
    "metadata": {
        "image/png": {
            "width": 640,
            "height": 480,
        },
    },
}

Warning

nbformat 버전 4.0에서 변경됨
pyout이 execute_result로 이름 변경됨

Warning

nbformat 버전 4.0에서 변경됨
prompt_number가 execution_count로 이름 변경됨

3.3.4 오류

실행 실패 시 다음과 같은 오류가 나타날 수 있습니다:

{
    'output_type': 'error',
    'ename' : str,   # Exception name, as a string
    'evalue' : str,  # Exception value, as a string

    # The traceback will contain a list of frames,
    # represented each as a string.
    'traceback' : list,
}

Warning

nbformat 버전 4.0에서 변경됨
pyerr가 error로 이름이 변경됨

3.4 원시 NBConvert 셀

원시 셀은 nbconvert 출력에 수정되지 않은 상태로 포함되어야 하는 콘텐츠로 정의됩니다. 예를 들어, 이 셀은 latex을 통해 pdf로 변환하기 위한 원시 LaTeX 또는 Sphinx 문서에 사용하기 위한 구조화된 텍스트를 포함할 수 있습니다.

노트북 작성 환경에서는 원시 셀을 렌더링하지 않습니다.

원시 셀의 유일한 로직은 format 메타데이터 필드입니다. 정의된 경우, 이는 원시 셀의 내용이 대상으로 하는 nbconvert 출력 형식을 지정합니다. 다른 형식으로 출력할 때는 원시 셀의 내용이 제외됩니다. 이 값이 정의되지 않은 기본인 경우, 원시 셀의 내용은 형식에 관계없이 모든 nbconvert 출력에 포함됩니다.

{
    "cell_type": "raw",
    "metadata": {
        # 대상 nbconvert 형식의 MIME 타입.
        # 이 외의 형식으로 nbconvert할 경우 이 셀은 제외됩니다.
        "format": "mime/type"
    },
    "source": "[some nbformat output text]",
}

3.5 셀 첨부파일

마크다운과 원시 셀은 일반적으로 셀의 마크다운 내용에서 참조할 수 있는 인라인 이미지와 같은 여러 첨부파일을 가질 수 있습니다. 셀의 attachments 딕셔너리는 파일 이름으로 키가 설정된 mime-번들(display_data 참조)을 포함하며, 이는 셀에 첨부된 파일을 나타냅니다.

Note

attachments 딕셔너리는 선택 필드이며, 셀이 첨부파일을 가지고 있지 않은 경우 정의되지 않거나 비어 있을 수 있습니다.

{
    "cell_type": "markdown",
    "metadata": {},
    "source": ["Here is an *inline* image ![inline image](attachment:test.png)"],
    "attachments": {"test.png": {"image/png": "base64-encoded-png-data"}}
}

3.6 셀 ID

4.5 스키마 릴리스 이후, 모든 셀에는 id 필드가 있으며, 이는 길이가 1~64인 문자열이어야 하며, 알파벳, 숫자, -, _를 사용할 수 있습니다. 이러한 ID는 nbformat 스펙을 따르는 모든 노트북에서 고유해야 합니다.

셀 ID 사용에 대한 전체 규칙과 지침은 해당 JEP 제안에 담겨 있습니다.

다른 노트북 사양을 지원하는 언어에 유사한 지원을 추가하려는 경우, 이 예제 PR을 참조로 사용할 수 있습니다.

4 하위호환가능 변경사항

노트북 형식은 진화하는 형식입니다. 하위 호환 변경이 이루어질 때마다 노트북 형식의 마이너 버전이 증가합니다. 하위 호환이 불가능한 변경이 이루어질 때는 메이저 버전이 증가합니다.

nbformat 4.x 기준으로, 하위 호환 변경에는 다음이 포함됩니다:

모든 딕셔너리(노트북, 셀, 출력, 메타데이터 등)에 새로운 필드 추가
새로운 셀 타입 추가
새로운 출력 타입 추가

새로운 셀 또는 출력 타입은 이를 인식하지 못하는 버전에서는 렌더링되지 않지만, 보존됩니다.

nbformat 파이썬 패키지가 노트북 파일 유효성 검증을 덜 엄격하게 하던 시절이 있었기 때문에, 두 가지 기능이 nbformat 4.x에서 nbformat 4.0으로 백포트되었습니다. 이 기능들은 다음과 같습니다:

마크다운과 원시 셀 타입의 attachment 최상위 키 (nbformat 4.1에서 백포트됨)
Mime-bundle 속성은 mime-type 키가 +json으로 끝나는 경우 JSON 데이터임 (nbformat 4.2에서 백포트됨)

이러한 백포트는 모든 유효한 nbformat 4.4 파일이 유효한 nbformat 4.0 파일이 되도록 보장합니다.

5 메타데이터

메타데이터는 노트북, 셀, 출력에 대해 임의의 JSON 형태의 정보를 저장할 수 있는 공간입니다. 공유되는 네임스페이스이기 때문에, 커스텀 메타데이터는 충분히 고유한 네임스페이스를 사용해야 합니다. 예를 들어, metadata.kaylees_md.foo = "bar"와 같이 사용할 수 있습니다.

Jupyter 노트북에 공식적으로 정의된 메타데이터 필드는 다음에 나열되어 있습니다:

5.1 노트북 메타데이터

다음 메타데이터 키는 노트북 수준에서 정의됩니다:

키	값	설명
kernelspec	dict	커널 사양
authors	list of dicts	문서 작성자 목록

노트북의 작성자는 노트북의 각 작성자에 대한 정보를 포함하는 사전들의 목록입니다. 현재는 이름만 필요합니다. 추가 필드가 추가될 수 있습니다.

nb.metadata.authors = [
    {
        "name": "Fernando Perez",
    },
    {
        "name": "Brian Granger",
    },
]

5.2 셀 메타데이터

5.3 출력 메타데이터