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]",
}