노트북 파일

노트북은 파이썬 파일입니다

셀은 주석이고 마크다운은 함수 호출입니다. 그래서 python file.py는 커널과 같은 코드를 실행합니다. 출력은 파일에 넣지 않고 실행 기록에 남깁니다.

예시

train.py

"""Train a small model."""
import darkpyonix                      # 프리앰블: 어떤 셀보다 먼저 한 번 실행


# %% Parameters [argparse]
LR = darkpyonix.params.get("lr", default=0.01, range=(0.001, 0.1, 0.001))
MODEL = darkpyonix.params.get("model", default=0, choices=["small", "large"])


# %% [markdown]
darkpyonix.markdown("""
## Training
The loop below prints one line per epoch.
""", silent=True)


# %% Train [code]
# @width: 1fr
for epoch in range(3):
    print(f"epoch {epoch} lr={LR} model={MODEL}")
epoch

첫 표식 앞의 줄은 프리앰블입니다. 커널은 실행할 때마다 어떤 셀보다 먼저 이것을 한 번 실행합니다. import와 docstring을 두는 자리입니다.

.pynb는 .py와 문법이 같습니다. 확장자는 편집기에게 노트북 화면으로 열지 코드로 열지를 알려 줄 뿐이고, 커널은 둘을 똑같이 다룹니다.

셀 표식

# %%로 시작하는 줄이 셀을 엽니다. 다음 표식이나 파일 끝까지가 그 셀입니다.
[type]으로 셀 타입을 정합니다. 없으면 code입니다.
타입 앞에 제목을 둘 수 있습니다: # %% 데이터 로드 [code].
경계 표기는 Jupytext 퍼센트 형식과 같습니다. 다른 점은 마크다운입니다. 여기서는 주석이 아니라 darkpyonix.markdown() 호출입니다.
파서는 Jupytext처럼 줄 단위로 동작하므로, 삼중 따옴표 문자열 안의 # %% 줄도 표식으로 봅니다.

셀 메타데이터

표식 바로 뒤의 # @key: value 줄이 그 셀의 메타데이터입니다. 값이 JSON으로 해석되면 JSON 값을, 아니면 문자열을 씁니다. 모르는 키는 보존하고 무시합니다.

키	의미	예
`width`	가로 배치에서 셀 너비(CSS grid 트랙)	`1fr`, `320px`
`layout`	이 셀부터 시작하는 배치	`horizontal`, `vertical`, `grid`
`collapsed`	처음에 접어서 표시	`true`
`auto_run`	클라이언트가 커널에 붙으면 자동 실행	`true`
`id`	클라이언트가 붙이는 안정 ID	`"c-3f2a"`

배치는 화면에만 영향을 줍니다. 가로로 놓인 셀도 차례대로 실행됩니다.

셀 타입

타입	상태	실행하면
`code`	구현	본문을 실행합니다. 마지막 식의 값은 결과로 내고 `_`에 저장합니다.
`markdown`	구현	`darkpyonix.markdown(...)` 호출을 실행합니다.
`argparse`	구현	`darkpyonix.params.get(...)` 호출을 실행합니다. 클라이언트는 폼으로 보여 줍니다.
`binding`	구현	`@darkpyonix.binding`이 붙은 정의를 `code` 셀 변수 없이 다시 평가합니다.
`shell`	구현	`darkpyonix.run_command(...)`를 실행하고 출력을 스트림으로 냅니다.
`parallel`, `concurrent`	계획 #7	받아들이고 보존합니다. 지금은 `code`처럼 실행합니다.
`cinterop`, `cppinterop`, `rustinterop`	계획 #5	받아들이고 보존합니다. API는 `NotImplementedError`를 냅니다.
`sql`, `toml`, `yaml`, `json`	계획 #5	받아들이고 보존합니다. 지금은 `code`처럼 실행합니다.
그 밖의 타입		`code`처럼 실행하고 원래 타입을 보존합니다.

파라미터

darkpyonix.params.get(name, default=..., choices=..., range=(min, max, step), type=..., help=...)로 파라미터를 읽습니다. choices가 있으면 default는 목록의 인덱스입니다. 값은 실행 요청의 params, 명령줄의 --name value, default 순서로 정해집니다. range를 벗어나거나 choices에 없는 값은 ValueError로 셀을 실패시킵니다.

그래서 같은 파일이 두 방식 모두로 돕니다. darkpyonix run train.py --param lr=0.02와 uv run train.py --lr 0.02는 같은 파라미터를 정합니다.

마크다운

darkpyonix.markdown(text, silent=False)는 커널에서 text/markdown 출력을 냅니다. silent=True이면 화면에만 보이고 실행 기록에는 남지 않습니다. python file.py에서는 아무것도 출력하지 않으므로 스크립트의 출력이 바뀌지 않습니다.

런타임 API

호출	커널 안	`python file.py`
`darkpyonix.markdown(text, silent=False)`	`text/markdown` 출력	아무것도 안 함
`darkpyonix.params.get(...)`	실행 요청의 `params` 우선	명령줄 인자
`@darkpyonix.binding`	격리 재평가	같음
`darkpyonix.run_command(cmd, check=False)`	스트림 출력	표준 출력
`darkpyonix.display(obj)`	`display_data` 출력	`print(repr(obj))`
`darkpyonix.uv.add`, `darkpyonix.uv.remove`	커널 인터프리터 환경에 설치	같음
`darkpyonix.run_parallel(*aws)`	코루틴을 모아 실행	같음

출력은 print, 파일 디스크립터 1·2에 직접 쓰는 출력(C 확장, 하위 프로세스), _repr_html_ 같은 메서드, 그리고 matplotlib 그림에서도 나옵니다. 커널 인터프리터에 matplotlib이 있으면 그림은 PNG 출력이 됩니다.