Notebook 파일 형식 편집하기

==개요==
[[분류: jupyter]]
;The Notebook file format
;Notebook 파일 형식
https://nbformat.readthedocs.io/en/latest/format_description.html
----
공식 Jupyter Notebook 형식은 [https://github.com/jupyter/nbformat/blob/main/nbformat/v4/nbformat.v4.schema.json 이 JSON 스키마]로 정의되며, Jupyter 도구는 이를 사용해 노트북을 검증합니다.

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

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

==최상위 구조==
최상위 수준에서, Jupyter 노트북은 몇 가지 키를 가진 딕셔너리입니다:
* metadata (dict)
* nbformat (int)
* nbformat_minor (int)
* cells (list)

<syntaxhighlight lang='json'>
{
    "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
    ],
}
</syntaxhighlight>

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

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

<syntaxhighlight lang='json'>
{
    "cell_type": "type",
    "metadata": {},
    "source": "single string or [list, of, strings]"
}
</syntaxhighlight>

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

===마크다운 셀===
마크다운 셀은 본문 텍스트에 사용되며, [https://github.github.com/gfm/ GitHub향 마크다운]으로 정의되고 [https://github.com/markedjs/marked marked]에서 구현된 마크다운을 포함합니다.

<syntaxhighlight lang='json'>
{
    "cell_type": "markdown",
    "metadata": {},
    "source": "[multi-line *markdown*]"
}
</syntaxhighlight>

{{WARNING}}
nbformat 버전 4.0에서 변경됨

헤딩 셀은 마크다운의 간단한 헤딩으로 대체되었습니다.
{{/WARNING}}

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

<syntaxhighlight lang='json'>
{
    "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",
            # ...
        }
    ],
}
</syntaxhighlight>

{{WARNING}}
nbformat 버전 4.0에서 변경됨

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

<code>prompt_number</code>가 <code>execution_count</code>로 이름이 변경되었습니다.
{{/WARNING}}

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

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

====스트림 출력====
<syntaxhighlight lang='json'>
{
    "output_type": "stream",
    "name": "stdout",  # or stderr
    "text": "[multiline stream text]",
}
</syntaxhighlight>

{{WARNING}}
nbformat 버전 4.0에서 변경됨

<code>stream</code> 키가 스트림 메시지와 일치하도록 <code>name</code>으로 변경되었습니다.
{{/WARNING}}

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

<syntaxhighlight lang='json'>
{
    "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,
        },
    },
}
</syntaxhighlight>

{{WARNING}}
nbformat 버전 4.0에서 변경됨

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

mime-types는 짧은 이름(<code>text</code>)과 mime-types의 조합 대신 키로 사용되며, 최상위 레벨이 아닌 <code>data</code> 키에 저장됩니다. 예를 들어, <code>output.png</code> 대신 <code>output.data['image/png']</code>입니다.
{{/WARNING}}

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

<syntaxhighlight lang='json'>
{
    "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,
        },
    },
}
</syntaxhighlight>

{{WARNING}}
nbformat 버전 4.0에서 변경됨

<code>pyout</code>이 <code>execute_result</code>로 이름 변경됨
{{/WARNING}}
{{WARNING}}
nbformat 버전 4.0에서 변경됨

<code>prompt_number</code>가 <code>execution_count</code>로 이름 변경됨
{{/WARNING}}

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

<syntaxhighlight lang='json'>
{
    '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,
}
</syntaxhighlight>

{{WARNING}}
nbformat 버전 4.0에서 변경됨

<code>pyerr</code>가 <code>error</code>로 이름이 변경됨
{{/WARNING}}

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

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

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

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

===셀 첨부파일===
마크다운과 원시 셀은 일반적으로 셀의 마크다운 내용에서 참조할 수 있는 인라인 이미지와 같은 여러 첨부파일을 가질 수 있습니다. 셀의 <code>attachments</code> 딕셔너리는 파일 이름으로 키가 설정된 mime-번들([https://jupyter-client.readthedocs.io/en/stable/messaging.html#display-data display_data 참조])을 포함하며, 이는 셀에 첨부된 파일을 나타냅니다.

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

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

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

셀 ID 사용에 대한 전체 규칙과 지침은 해당 [https://github.com/jupyter/enhancement-proposals/blob/master/62-cell-id/cell-id.md JEP 제안]에 담겨 있습니다.

다른 노트북 사양을 지원하는 언어에 유사한 지원을 추가하려는 경우, 이 [https://github.com/jupyter/nbformat/pull/189 예제 PR]을 참조로 사용할 수 있습니다.

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

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

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

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

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

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

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

==메타데이터==
===노트북 메타데이터===
===셀 메타데이터===
===출력 메타데이터===
@@ 270번째 줄: / 270번째 줄: @@
 ==하위호환가능 변경사항==
-노트북 형식은 진화하는 형식입니다. 하위 호환 변경이 이루어질 때마다 노트북 형식의 마이너 버전이 증가합니다. 하위 호환이 불가능한 변경이 이루어질 때는 메이저 버전이 증가합니다.
+노트북 포맷은 진화하는 포맷입니다. 하위 호환 변경이 이루어질 때마다 노트북 포맷의 마이너 버전이 증가합니다. 하위 호환이 불가능한 변경이 이루어질 때는 메이저 버전이 증가합니다.
 nbformat 4.x 기준으로, 하위 호환 변경에는 다음이 포함됩니다:
@@ 288번째 줄: / 288번째 줄: @@
 ==메타데이터==
-메타데이터는 노트북, 셀, 출력에 대해 임의의 JSON 형태의 정보를 저장할 수 있는 공간입니다. 공유되는 네임스페이스이기 때문에, 커스텀 메타데이터는 충분히 고유한 네임스페이스를 사용해야 합니다. 예를 들어, <code>metadata.kaylees_md.foo = "bar"</code>와 같이 사용할 수 있습니다.
-Jupyter 노트북에 공식적으로 정의된 메타데이터 필드는 다음에 나열되어 있습니다:
 ===노트북 메타데이터===
-다음 메타데이터 키는 노트북 수준에서 정의됩니다:
-{| class='wikitable'
-! 키 !! 값 !! 설명
-|-
-| kernelspec || dict || 커널 사양
-|-
-| authors || list of dicts || 문서 작성자 목록
-|}
-노트북의 작성자는 노트북의 각 작성자에 대한 정보를 포함하는 사전들의 목록입니다. 현재는 이름만 필요합니다. 추가 필드가 추가될 수 있습니다.
-<syntaxhighlight lang='python'>
-nb.metadata.authors = [
-    {
-        "name": "Fernando Perez",
-    },
-    {
-        "name": "Brian Granger",
-    },
-]
-</syntaxhighlight>
 ===셀 메타데이터===
-Jupyter 프론트엔드에서 사용하는 공식 Jupyter 메타데이터는 <code>metadata.jupyter</code> 네임스페이스에 배치되어야 합니다. 예를 들어 <code>metadata.jupyter.foo = "bar"</code>와 같이 설정할 수 있습니다.
-다음의 메타데이터 키는 셀 레벨에서 정의됩니다:
-{| class='wikitable'
-! 키 !! 값 !! 설명
-|-
-| collapsed || bool || 셀의 출력 컨테이너가 접혀 있어야 하는지 여부
-|-
-| scrolled || bool 또는 ‘auto’ || 셀의 출력이 스크롤되는지, 스크롤되지 않는지 또는 자동 스크롤되는지 여부
-|-
-| deletable || bool || False인 경우, 셀 삭제를 방지
-|-
-| editable || bool || False인 경우, 셀 편집을 방지 (삭제도 방지됨)
-|-
-| format || ‘mime/type’ || [[#원시 NBConvert 셀|원시 NBConvert 셀]]의 MIME 타입
-|-
-| name || str || 셀의 이름. 노트북 내에서 고유해야 함. 고유성은 json 스키마 외부에서 확인되어야 함
-|-
-| tags || str 리스트 || 셀에 대한 문자열 태그 리스트. 태그에 쉼표는 허용되지 않음
-|-
-| jupyter || dict || Jupyter 특정 필드를 보유한 네임스페이스. 자세한 내용은 아래 문서 참조
-|-
-| execution || dict || 실행 관련 필드를 보유한 네임스페이스. 자세한 내용은 아래 문서 참조
-|}
-다음의 메타데이터 키는 <code>jupyter</code> 네임스페이스 내에서 셀 레벨에서 정의됩니다:
-{| class='wikitable'
-! 키 !! 값 !! 설명
-|-
-| source_hidden || bool || 셀의 소스가 표시될지 여부
-|-
-| outputs_hidden || bool || 셀의 출력이 표시될지 여부
-|}
-다음의 메타데이터 키는 <code>execution</code> 네임스페이스 내에서 셀 레벨에서 정의됩니다. 이러한 필드는 대부분의 사용자가 직접 보지 않는 낮은 수준의 필드로, 애플리케이션에서 필요할 경우 커널 메시지 타임스탬프를 더 잘 볼 수 있도록 캡처합니다.
-{| class='wikitable'
-! 키 !! 값 !! 설명
-|-
-| iopub.execute_input || ISO 8601 형식 || 커널이 execute_input 메시지를 방송한 시간. 이는 커널이 작업 요청을 받은 시간을 나타냄
-|-
-| iopub.status.busy || ISO 8601 형식 || iopub 채널의 커널 상태 메시지가 ‘busy’인 시간. 이는 커널이 작업을 시작한 시간을 나타냄
-|-
-| shell.execute_reply || ISO 8601 형식 || shell 채널의 execute_reply 상태 메시지가 생성된 시간. 이는 커널이 작업을 완료한 시간을 나타냄
-|-
-| iopub.status.idle || ISO 8601 형식 || iopub 채널의 커널 상태 메시지가 ‘idle’인 시간. 이는 커널이 새로운 작업을 받을 준비가 된 시간을 나타냄
-|}
 ===출력 메타데이터===
-다음 메타데이터 키는 코드 셀 출력에 대해 정의됩니다:
-{| class='wikitable'
-! 키 !! 값 !! 설명
-|-
-| isolated || bool || 출력이 IFrame으로 격리되어야 하는지 여부
-|}