프로젝트 스크립트

개요

더 복잡한 프로젝트는 주기적으로(예: 데이터 가져오기 및 준비) 또는 각 렌더링 전/후에 추가 처리가 필요할 수 있습니다. 프로젝트 스크립트는 이러한 처리를 워크플로에 통합하는 방법입니다.

주기적 스크립트

quarto run 명령으로 TypeScript, R, Python, Lua 스크립트를 실행할 수 있습니다. 예:

Terminal
quarto run import.py

quarto run에서 사용할 수 있는 스크립트 인터프리터는 다음과 같습니다.

Language Interpreter
TypeScript Deno (embedded in Quarto)
Python Python from PATH (or launcher on Windows)
R Rscript from PATH
Lua Lua 5.3 (embedded in Pandoc)

TypeScript나 Lua를 사용하면 추가 설치 없이 스크립트를 만들 수 있습니다. 반면 프로젝트에서 이미 Python이나 R을 사용하고 있다면 해당 언어의 스크립트가 더 편리할 수 있습니다.

TypeScript를 사용한다면 Deno 표준 라이브러리와 외부 스크립트 가져오기에 대한 추가 내용을 Deno 스크립트 섹션에서 확인하세요.

렌더링 전/후

pre-render와 post-render 프로젝트 옵션으로 렌더링 전/후에 하나 이상의 스크립트를 실행할 수 있습니다. 예:

project:
  type: website
  pre-render: prepare.py
  post-render: 
    - compress.ts
    - fix-links.py

pre-render와 post-render는 임의의 셸 명령도 지원합니다. 예를 들어 make로 데이터 준비를 수행할 수 있습니다.

project:
  type: website
  pre-render: make prepare

렌더링 전/후 스크립트는 기본 프로젝트 디렉터리에서 실행됩니다.

다음 환경 변수가 렌더링 전/후 스크립트에 전달됩니다(모든 경로는 기본 프로젝트 디렉터리에 대한 상대 경로입니다).

Variable Description
QUARTO_PROJECT_RENDER_ALL 프로젝트의 모든 파일을 렌더링할 경우 “1”로 설정(증분 렌더링 또는 미리보기 렌더링과 구분). 모든 파일을 렌더링하지 않으면 설정되지 않습니다.
QUARTO_PROJECT_OUTPUT_DIR 출력 디렉터리
QUARTO_PROJECT_INPUT_FILES 렌더링 중인 모든 입력 파일의 줄바꿈 구분 목록(pre-render에만 전달)
QUARTO_PROJECT_OUTPUT_FILES 렌더링된 모든 출력 파일의 줄바꿈 구분 목록(post-render에만 전달)

프로젝트 메타데이터와 렌더링 목록은 렌더링 전 스크립트 실행 후 다시 계산되므로, 스크립트가 프로젝트 데이터를 변경할 수 있습니다. 예를 들어 렌더링 전 스크립트가 렌더링해야 할 추가 qmd 또는 ipynb 파일을 생성할 수 있습니다.

렌더링 전 스크립트는 프로젝트 디렉터리, 출력 디렉터리, 프로젝트 유형을 변경할 수 없습니다. 이 값들을 변경하면 오류가 발생하고 렌더링이 실패합니다.

pre-render 단계가 무겁다면 전체 프로젝트를 렌더링할 때만 실행하고 싶을 수 있습니다. 지원되는 스크립트 언어별 방법은 다음과 같습니다.

if (!Deno.env.get("QUARTO_PROJECT_RENDER_ALL")) {
  Deno.exit();
}
import os
if not os.getenv("QUARTO_PROJECT_RENDER_ALL"):
  exit()
if (!nzchar(Sys.getenv("QUARTO_PROJECT_RENDER_ALL"))) {
  quit()
}
if not os.getenv("QUARTO_PROJECT_RENDER_ALL") then
  os.exit();
end

고급: 큰 입력/출력 파일 목록

일부 실행 환경에서는 환경 변수 크기 제한이 있을 수 있습니다. 이 경우 Quarto가 적절한 환경 변수를 구성하려고 할 때 렌더링 전/후 스크립트 호출이 실패할 수 있습니다.

이런 상황에서는 QUARTO_USE_FILE_FOR_PROJECT_INPUT_FILES(또는 QUARTO_USE_FILE_FOR_PROJECT_OUTPUT_FILES) 환경 변수를 선언해, QUARTO_PROJECT_INPUT_FILES(또는 QUARTO_PROJECT_OUTPUT_FILES)에 기록될 파일 목록을 지정한 파일로 쓰도록 Quarto에 지시할 수 있습니다.

Deno 스크립트

TypeScript로 프로젝트 스크립트를 만들고 싶다면 quarto run으로 Quarto에 포함된 Deno TypeScript 인터프리터를 사용할 수 있습니다. 이 인터프리터는 Deno의 표준 라이브러리 대부분도 포함합니다. 예를 들어 Deno YAML 파서를 사용하려면 다음과 같이 합니다.

Quarto 1.6 호환성 깨짐 변경

Warning

Quarto 1.6은 Deno와 Deno 표준 라이브러리 업데이트를 포함하면서 import 문법에 호환성 깨짐 변경이 필요했습니다. 불편을 끼쳐 드려 죄송합니다.

import { parse } from "stdlib/yaml"; // Quarto 1.6 syntax
import { parse } from "https://deno.land/std/yaml/mod.ts"; // Quarto 1.5 and earlier syntax

const config = parse(Deno.readTextFileSync("_quarto.yml"));

Deno는 표준 라이브러리를 온라인에서 호스팅하지만, Quarto 1.5에서는 라이브러리를 원격 서버에서 다운로드하지 않습니다(실제로 Quarto Deno 인터프리터에서는 원격 서버에서의 import가 완전히 비활성화됨). Quarto 1.6은 표준 라이브러리와 원격 서버 다운로드 비활성화 기능 간에 바람직하지 않은 상호작용이 있는 Deno 버전을 포함합니다. 그 결과 Quarto 1.6에서는 표준 라이브러리를 호출할 때 일부 파일을 다운로드(한 번만, 이후 캐시)할 수 있습니다. 향후 Quarto 버전은 이 문제가 없는 Deno 2를 포함할 예정입니다.

Quarto 1.5의 동작을 강제하고 싶다면 환경 변수 QUARTO_RUN_NO_NETWORK를 true로 설정할 수 있습니다. 이 경우 stdlib/에서의 import는 일반적으로 동작하지 않습니다.

Deno 라이브러리 import에 버전을 직접 포함한 예제 코드를 볼 수 있습니다. 예:

import { format } from "https://deno.land/std@0.119.0/datetime/mod.ts";
import { format } from "jsr:@std/datetime@^0.224.0"

이러한 버전 고정 import는 Quarto에서 동작하지 않습니다(로컬 표준 라이브러리 캐시에 버전 없는 URL이 저장되어 있기 때문). 올바른 import 형식은 다음과 같습니다.

import { format } from "stdlib/datetime";

또한 URL에서 직접 3rd party 라이브러리를 import하는 Deno 코드 예시가 있을 수 있습니다. 앞서 언급했듯이 이 기능은 Quarto Deno 스크립트에서는 일반적으로 사용할 수 없습니다. 대신 사용할 외부 라이브러리를 다운로드해 프로젝트 소스 코드에 포함하고, 상대 경로로 import해야 합니다.

여러 Quarto 버전에서 .ts 스크립트 이식성 유지

프로젝트나 확장이 TypeScript 프로젝트 스크립트를 포함하면서 Quarto 1.5와 1.6 모두에서 동작해야 한다면 다음 기법을 사용하세요.

const multiImport = async (...sources: string[]) => {
    for (const source of sources) {
        try {
            return await import(source);
        } catch (e) {}
    }
}
const { readLines } = await multiImport(
  "stdlib/io", // Quarto 1.6 syntax
  "https://deno.land/std/io/mod.ts", // Quarto 1.5 syntax
);