Python 사용하기

개요

Quarto는 마크다운 안에서 실행 가능한 Python 코드 블록을 지원합니다. 이를 통해 완전한 재현 가능 문서와 보고서를 만들 수 있습니다. 출력에 필요한 Python 코드는 문서 자체의 일부이며, 문서를 렌더링할 때마다 자동으로 다시 실행됩니다.

Python과 jupyter 패키지가 설치되어 있다면 임베디드 Python 코드를 포함한 문서를 렌더링하는 데 필요한 모든 것이 준비된 것입니다(아직 없다면 아래 설치 섹션에서 다룹니다). 이제 Python 코드 블록을 포함한 문서를 만들고 렌더링하는 기본을 살펴보겠습니다.

코드 블록

언어 이름을 중괄호로 감싼 코드 블록(예: ```{python})은 실행 가능하며, 렌더링 시 Quarto가 실행합니다. 아래는 간단한 예시입니다.

---
title: "matplotlib demo"
format:
  html:
    code-fold: true
jupyter: python3
---

For a demonstration of a line plot on a polar axis, see @fig-polar.

```{python}
#| label: fig-polar
#| fig-cap: "A line plot on a polar axis"

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
  subplot_kw = {'projection': 'polar'} 
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```

코드 블록 상단에는 특수 주석이 있는데, 이는 그림을 상호 참조할 수 있게 하는 셀 수준 옵션입니다.

이 문서는 다음과 같은 렌더링 결과를 생성합니다.

출력 예시: 제목은 matplotlib demo이며 본문에는 '극좌표 축의 선 플롯 데모는 Figure 1을 참고하세요.'라고 표시된다. 코드 접기 영역과 Figure 1 이미지가 있으며 캡션은 'Figure 1: A line plot on a polar axis.'이다.

실행 가능한 코드 블록으로 플롯, 데이터 프레임의 표 출력, 일반 텍스트 출력(예: 통계 요약 결과 출력) 등 다양한 유형의 출력을 생성할 수 있습니다.

코드 실행과 출력 동작을 제어하는 다양한 옵션이 있으며, 자세한 내용은 실행 옵션 문서에서 확인할 수 있습니다.

마크다운 흐름을 끊는 코드 블록 외에도 인라인 코드를 포함할 수 있습니다. 인라인 코드에 대한 자세한 내용은 인라인 코드 문서를 참고하세요.

렌더링

Quarto는 실행 가능한 코드 블록이 포함된 모든 마크다운 문서에서 계산을 자동으로 실행합니다. 예를 들어 앞서 보인 예제는 다음과 같이 다양한 포맷으로 렌더링할 수 있습니다.

Terminal
quarto render document.qmd # all formats
quarto render document.qmd --to pdf
quarto render document.qmd --to docx

render 명령은 문서 YAML에 나열된 모든 포맷을 렌더링합니다. 포맷이 지정되지 않았다면 HTML로 렌더링합니다. --to 인수로 특정 포맷만 지정할 수도 있습니다.

Quarto는 어떤 Jupyter 노트북(.ipynb)도 렌더링할 수 있습니다.

Terminal
quarto render document.ipynb

대상 파일(이 경우 document.qmd)은 항상 명령줄의 첫 번째 인수여야 합니다.

.ipynb를 렌더링할 때 Quarto는 기본적으로 노트북 셀을 실행하지 않습니다(노트북을 편집하면서 이미 실행했을 것으로 가정). 셀을 실행하려면 렌더링 시 --execute 플래그를 추가하세요.

Terminal
quarto render notebook.ipynb --execute

설치

환경에 Python 3와 Jupyter가 이미 설치되어 있다면 Python 커널이 포함된 Jupyter 노트북을 렌더링하는 데 필요한 모든 것이 준비된 것입니다.

시스템에 아직 Python 3가 없다면, https://www.python.org/downloads/의 표준 설치 프로그램으로 설치하는 것을 권장합니다.

새 Python 3 환경이라면 jupyter 패키지를 설치하면 Quarto에서 Jupyter 커널을 실행하는 데 필요한 모든 구성 요소가 제공됩니다.

패키지 관리자 | 명령 |
Pip
(Mac/Linux)		 
Terminal
python3 -m pip install jupyter
Pip
(Windows)		 
Terminal
py -m pip install jupyter
Conda 
Terminal
conda install jupyter

다음 명령으로 Quarto의 Jupyter 구성이 올바른지 확인할 수 있습니다.

Terminal
quarto check jupyter

Quarto는 Windows에서 Python Launcher를, macOS와 Linux에서는 시스템 PATH를 사용해 Python 버전을 선택합니다. Quarto가 사용하는 Python 버전은 QUARTO_PYTHON 환경 변수를 설정해 변경할 수 있습니다.

가상 환경을 사용 중이라면 가상 환경을 참고하세요.

워크플로

Python 코드를 포함한 Quarto 문서는 어떤 텍스트 편집기나 노트북 편집기에서도 작성할 수 있습니다. 어떤 편집 도구를 사용하든, 먼저 quarto preview로 문서 변경 사항을 실시간 미리보기 하는 것이 일반적입니다. 실시간 미리보기는 HTML과 PDF 출력 모두에서 사용할 수 있습니다. 예:

Terminal
# html로 미리보기
quarto preview document.qmd

# pdf로 미리보기
quarto preview document.qmd --to pdf

# jupyter 노트북 미리보기
quarto preview document.ipynb

.ipynb를 렌더링할 때 Quarto는 기본적으로 노트북 셀을 실행하지 않습니다(노트북을 편집하면서 이미 실행했을 것으로 가정합니다). 셀을 실행하려면 렌더링 시 --execute 플래그를 추가하세요.

Terminal
quarto render notebook.ipynb --execute

노트북 YAML front matter에서 이 동작을 지정할 수도 있습니다.

notebook.ipynb
---
title: "My Notebook"
execute: 
  enabled: true
---

노트북 임베딩

Quarto 문서에 실행 가능한 Python 코드 청크를 포함하는 것 외에도, 외부 Jupyter Notebook(.ipynb)의 셀을 임베드할 수 있습니다. 자세한 내용은 Jupyter Notebook 셀 임베딩을 참고하세요.

Positron

Quarto 확장은 Positron에 포함되어 있으며, .qmd 파일 작업을 위한 다양한 도구를 제공합니다. 이 확장은 Positron의 기본 Python 지원과 직접 통합되어 코드 완성, 셀 실행, Quarto 문서의 나란히 미리보기를 제공합니다.

편집기 패널에 소스 마크다운이 표시되고, 뷰어 패널에 렌더링된 문서가 표시된 Positron의 qmd 파일 스크린샷.편집기 패널에 소스 마크다운이 표시되고, 뷰어 패널에 렌더링된 문서가 표시된 Positron의 qmd 파일 스크린샷.

이 확장은 명령 팔레트, 단축키 , 또는 편집기 툴바의 Preview 버튼(Preview iconPreview icon)을 통해 사용할 수 있는 Quarto: Preview 명령을 제공합니다. 렌더링 후 미리보기는 Positron의 Viewer 패널에 표시됩니다.

Positron 사용법에 대한 자세한 내용은 도구: Positron에서 확인하세요.

Positron 노트북 편집기를 사용해 .ipynb 노트북을 만든 뒤 Quarto로 렌더링할 수도 있습니다. Jupyter Lab 섹션에서는 Jupyter Lab에서 Quarto와 노트북을 사용하는 방법을 설명하지만, 동일한 개념이 Positron에도 적용됩니다.

VS Code

VS Code용 Quarto 확장은 .qmd 파일 작업을 위한 다양한 도구를 제공합니다. 이 확장은 Python Extension과 직접 통합되어 다음과 같은 Python 전용 기능을 제공합니다.

  1. 코드 완성
  2. 셀 실행
  3. 문맥 기반 도움말

VS Code 편집기의 스크린샷. 왼쪽에는 파일 탐색기와 Quarto 도움말, 가운데에는 Python 코드가 포함된 quarto 파일 소스, 오른쪽에는 Python이 실행되며 코드 셀 출력이 표시되는 패널이 있다.

VS Code 확장은 확장 패널에서 ’quarto’를 검색하거나 확장 마켓플레이스에서 설치할 수 있습니다.

VS Code 노트북 편집기를 사용해 Python 노트북을 만든 뒤 Quarto로 렌더링할 수도 있습니다. 다음 섹션에서는 Jupyter Lab에서 Quarto로 노트북을 사용하는 방법을 설명하지만, 동일한 개념이 VS Code에도 적용됩니다.

Jupyter Lab

위에서 예로 사용한 간단한 document.qmd를 quarto convert 명령으로 Jupyter 노트북으로 변환할 수 있습니다. 예:

Terminal
quarto convert document.qmd

이 노트북을 Jupyter Lab에서 열고 셀을 실행하면 다음과 같이 보입니다.

Quarto Basics라는 제목의 Jupyter 노트북으로, 텍스트와 코드 셀, 그리고 코드 셀 결과인 극좌표 선 그래프가 포함된 스크린샷.

여기에는 세 가지 유형의 셀이 있습니다.

  1. 맨 위의 YAML 문서 옵션은 Raw 셀에 있습니다.
  2. 제목과 설명은 Markdown 셀에 있습니다.
  3. Python 코드와 그 출력은 Code 셀에 있습니다.

Jupyter 노트북에서 작업할 때는 quarto preview로 렌더링된 문서의 실시간 미리보기를 제공할 수 있습니다.

Terminal
quarto preview document.ipynb

Jupyter Lab에서 노트북을 저장할 때마다 미리보기가 갱신됩니다.

캐싱

Jupyter Cache는 노트북의 모든 셀 출력을 캐시할 수 있게 해줍니다. 노트북의 어떤 셀이든 변경되면 모든 셀이 다시 실행됩니다.

Jupyter Cache를 사용하려면 먼저 jupyter-cache 패키지를 설치해야 합니다.

플랫폼 명령
Mac/Linux 
Terminal
python3 -m pip install jupyter-cache
Windows 
Terminal
py -m pip install jupyter-cache

문서에 캐시를 활성화하려면 cache 옵션을 추가합니다. 예:

---
title: "My Document"
format: html
execute: 
  cache: true
---

프로젝트 수준에서도 캐싱을 지정할 수 있습니다. 예:

project:
  type: website
  
format:
  html:
    theme: united
    
execute:
  cache: true

코드 셀 밖의 변경(예: 마크다운 서술)은 문서 캐시를 무효화하지 않습니다. 그래서 문서의 글쓰기 부분만 작업할 때 캐싱은 매우 편리합니다.

Jupyter Cache에는 노트북 캐시를 분석하고 관리할 수 있는 jcache 명령줄 유틸리티가 포함되어 있습니다. 자세한 내용은 Jupyter Cache 문서를 참고하세요.

렌더링

quarto render 명령줄 옵션으로 문서 코드를 변경하지 않고 캐싱 동작을 제어할 수 있습니다. 모든 청크에 캐시를 강제로 사용하거나, 옵션에 지정되어 있더라도 캐시를 비활성화하거나, 캐시가 무효화되지 않았더라도 강제로 새로고침할 수 있습니다.

Terminal
# 캐시 사용(옵션에 활성화되어 있지 않아도)
quarto render example.qmd --cache 

# 캐시 사용 안 함(옵션에 활성화되어 있어도)
quarto render example.qmd --no-cache 

# 캐시 사용 + 강제 새로고침 
quarto render example.qmd --cache-refresh

대안

렌더링 시간이 길어 캐싱을 고려한다면, 캐싱 외에도 아래 대안을 함께 고려할 수 있습니다.

실행 비활성화

서술/마크다운 작업만 하고 있다면 실행을 완전히 비활성화하는 것이 좋습니다. enabled: false 실행 옵션으로 설정합니다. 예:

---
title: "My Document"
format: html
execute: 
  enabled: false
---

Jupyter .ipynb 노트북으로 작성하는 경우(일반 텍스트 .qmd가 아닌), 이는 이미 기본 동작입니다. 즉, quarto render를 호출해도 실행은 되지 않고, 노트북에서 작업할 때 실행이 이루어집니다.

실행 고정

프로젝트에서 여러 문서를 한꺼번에 렌더링할 때 누적 비용이 걱정된다면 freeze 옵션을 고려하세요.

freeze 옵션을 사용하면 전체 프로젝트 렌더링 중 계산 문서를 다시 렌더링하지 않도록 하거나, 소스 파일이 변경될 때만 다시 렌더링하도록 지정할 수 있습니다.

execute:
  freeze: true  # 프로젝트 렌더링 중 다시 렌더링하지 않음
execute:
  freeze: auto  # 소스가 변경될 때만 다시 렌더링

freeze는 전체 프로젝트 렌더링 중 실행 여부를 제어합니다. 단일 문서나 프로젝트 하위 디렉터리를 증분 렌더링하면 코드는 항상 실행됩니다. 예:

Terminal
# 단일 문서 렌더링(항상 코드 실행)
quarto render document.qmd

# 프로젝트 하위 디렉터리 렌더링(항상 코드 실행)
quarto render articles

프로젝트에서 freeze를 사용하는 방법은 프로젝트 실행 관리 문서를 참고하세요.

커널 선택

Quarto가 사용하는 Jupyter 커널은 jupyter 메타데이터 옵션으로 결정됩니다. 예를 들어 Xeus Python 커널을 사용하려면 다음과 같이 지정합니다.

---
title: "My Document"
jupyter: xpython
---

전체 kernelspec을 제공할 수도 있습니다.

---
title: "My Document"
jupyter: 
  kernelspec:
    name: "xpython"
    language: "python"
    display_name: "Python 3.7 (XPython)"
---

Jupyter 커널이 지정되지 않으면, Quarto는 파일에서 처음 발견된 실행 코드 블록의 언어를 지원하는 커널을 찾아 사용합니다(예: ```{python}).

ImportantConda의 커널

외부 conda 환경에 있는 커널을 사용하는 경우, Quarto가 이를 인식하도록 추가 설정이 필요합니다. conda로 관리되는 커널을 사용할 수 있도록 아래 안내를 따르세요.

https://github.com/Anaconda-Platform/nb_conda_kernels#use-with-nbconvert-voila-papermill

이 단계는 conda를 Quarto와 함께 사용하는 경우에 필요한 것은 아닙니다. conda 환경에 설치된 기본 Python 커널이 아닌 다른 커널을 사용할 때만 적용됩니다.

커널 데몬

Jupyter 커널의 시작 시간을 줄이기 위해 Quarto는 각 문서에 대해 실행 중인 Jupyter 커널을 유지하는 데몬을 사용합니다. 이를 통해 이후 렌더링이 커널 시작을 기다리지 않고 즉시 진행됩니다.

데몬은 대화형 세션에서 렌더링 반응성을 높이기 위한 것입니다. 따라서 활성 tty 없이 렌더링하거나 배치 렌더링(예: Quarto 프로젝트)의 일부일 때는 데몬이 생성되지 않습니다.

Quarto는 Windows에서 기본적으로 데몬을 사용하지 않습니다(일부 Windows 시스템은 데몬에 필요한 소켓 연결을 허용하지 않기 때문입니다).

이 동작은 daemon 실행 옵션으로 사용자 정의할 수 있습니다. false로 설정하면 데몬을 사용하지 않으며, 초 단위 값을 지정하면 해당 시간이 지나면 데몬이 타임아웃됩니다(기본값은 300초). 예:

execute:
  daemon: false
execute:
  daemon: 60

Windows에서 데몬을 사용하려면 명시적으로 활성화해야 합니다.

execute:
  daemon: true

명령줄

다음 명령줄 옵션으로 Jupyter 데몬 사용을 제어할 수도 있습니다.

Terminal
# 기본 타임아웃(300초)으로 데몬 사용
quarto render document.qmd --execute-daemon

# 명시적 타임아웃으로 데몬 사용
quarto render document.qmd --execute-daemon 60

# 데몬 사용하지 않기
quarto render document.qmd --no-execute-daemon

--execute-daemon-restart 플래그로 기존 데몬을 강제로 재시작할 수도 있습니다.

Terminal
quarto render document.qmd --execute-daemon-restart

노트북 세션 재사용이 오류를 일으킨다고 의심될 때 유용합니다.

마지막으로 --execute-debug 플래그로 데몬 사용에 대한 상세한 디버깅 정보(시작/종료/연결 등)를 출력할 수 있습니다.

Terminal
quarto render document.qmd --execute-debug