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로 이름이 변경됨