토파즈문서
인터롭

Python 백엔드

검사를 마친 토파즈 패키지 하나를 관리형 Python 제품으로 만듭니다. 토파즈 소스 트리가 없어도 실행됩니다.

배포 환경에 Python 3.11 이상이 있고, 사람이 읽을 수 있는 생성 제품이 쓸모 있다면 Python 경로를 고릅니다. Python은 빌드 대상일 뿐입니다. Python 문법이 토파즈 문법이 되지는 않습니다.

준비 사항

  • 첫 애플리케이션의 study-plan 패키지를 완성합니다.
  • topaz.toml, topaz.lock, src/plan.tpz, src/main.tpz와 선택 테스트를 한곳에 둡니다.
  • 배포할 컴퓨터에 Python 3.11 이상을 설치합니다.
  • 다음 명령은 study-plan 디렉터리에서 실행합니다.

제품을 실행할 때 토파즈 컴파일러와 .tpz 파일은 필요하지 않습니다. 다만 생성된 Python 소스와 지원 모듈이 들어 있는 묶음이라서 네이티브 실행 파일은 아닙니다.

공유하는 검사 대상 패키지

Rust 페이지도 같은 두 토파즈 모듈을 사용합니다. 먼저 src/plan.tpz입니다.

TOPAZ
export record StudyTask {
    title: string,
    minutes: int,
    done: bool = false,
}

function parseMinutes(text: string) -> Result<int, string> {
    match toInt(text) {
        case Some(value) if value > 0 => Ok(value)
        case _ => Err("minutes must be a positive integer")
    }
}

export function makeTask(
    title: string,
    minuteText: string,
    done: bool = false,
) -> Result<StudyTask, string> {
    let minutes = parseMinutes(minuteText)?
    Ok(StudyTask { title: title, minutes: minutes, done: done })
}

export function summarize(tasks: Array<StudyTask>) -> string {
    let mut remaining = 0
    for task in tasks {
        if !task.done {
            remaining = remaining + task.minutes
        }
    }
    "tasks={tasks.length}, remaining={remaining} minutes"
}

패키지 진입점 src/main.tpz입니다.

TOPAZ
import src.plan { StudyTask, makeTask, summarize }

export function main(args: Array<string>, stdin: string) -> Result<int, string> {
    let tasks: Array<StudyTask> = [
        makeTask("Run first program", "10", true)?,
        makeTask("Build application", "25", false)?,
    ]
    print(summarize(tasks))
    Ok(0)
}

토파즈 소스 검증하기

먼저 패키지를 검사합니다. 이어서 선택 테스트를 실행합니다. 마지막으로 기준 출력을 확인합니다.

BASH
topaz check --root . --locked
topaz test tests/plan.tpz --root . --locked
topaz run --root . --locked

테스트는 tests/plan.tpz: test-ok를 보고합니다. 실행 결과는 다음과 같습니다.

출력
tasks=2, remaining=25 minutes

검토에는 emit, 배포에는 build

생성된 Python 소스를 직접 읽어 보거나 다른 코드에 통합해야 할 때만 emit을 사용합니다.

BASH
topaz emit --target python --root . --locked --out-dir ../dist/python-source

완전한 관리형 Python 제품은 build로 만듭니다.

BASH
topaz build --target python --root . --locked --out-dir ../dist/python

빌드한 뒤에는 program.py를 직접 실행합니다. Python 빌드는 --run과 --release를 거부합니다. 둘 다 Python 제품에 쓰는 옵션이 아닙니다. Rust용 --backend 옵션도 Python 빌드에서는 쓸 수 없습니다.

관리형 제품 확인하기

제품에는 다음 파일이 있습니다.

출력
dist/python/
├── GENERATED-OUTPUT-NOTICE.txt
├── LICENSE
├── NOTICE
├── program.py
├── topaz-artifact.json
└── topaz_py_rt.py

topaz-artifact.json에는 python 대상, Python 3.11 이상이라는 실행 요구 사항, 실행 명령, 모든 관리 파일의 크기와 SHA-256이 기록됩니다. 토파즈는 manifest를 맨 마지막에 씁니다. 관리 파일이 바뀐 경우, 안전하지 않은 충돌이 생긴 경우, 같은 출력 디렉터리에 다른 대상이 있는 경우에는 거부합니다. 배포할 때는 트리 전체를 옮기세요. program.py와 topaz_py_rt.py는 늘 함께 있어야 합니다. 고지와 라이선스, manifest도 관리형 제품의 일부입니다.

토파즈 소스를 사용할 수 없는 곳에서 실행하기

dist는 패키지 바깥에 있습니다. 원본 패키지를 다른 이름으로 옮긴 다음 제품만 실행합니다.

BASH
cd ..
mv study-plan source-unavailable
python3 dist/python/program.py

Windows에서는 Rename-Item study-plan source-unavailable을 먼저 실행합니다. 그다음 python dist\python\program.py를 실행합니다. 제품은 위와 같은 결과를 출력합니다. 종료 코드는 0입니다.

대상별 복구

Python 백엔드는 지원하지 않는 표준 라이브러리 연산을 미리 알려 줍니다. 산출물을 쓰기 전에 소스 위치와 함께 보고합니다. 이 대상에서는 Codec.deflateFixedCompress, Codec.zlibFixedCompress, Codec.reedSolomon255223Protect를 사용할 수 없습니다. 해당 연산을 지원하는 대상을 그대로 쓰거나, 다른 구현을 골라서 다시 빌드하세요.

program.py가 topaz_py_rt.py를 불러오지 못할 때가 있습니다. 이때는 생성 파일 하나만 복사하지 말고 관리형 트리 전체를 되돌려 놓습니다. Python 버전이 낮다면 배포 환경에 Python 3.11 이상을 설치합니다.

정확한 경계

생성된 Python 코드는 언제든 교체할 수 있는 배포 산출물입니다. 손으로 확장해 쓰는 안정 API나 네이티브 실행 파일이 아닙니다. 실행에 성공했다면 선택한 Python 환경에서 이 프로그램의 출력과 종료 코드만 확인한 것입니다. 아무 Python 라이브러리나 예외, 데코레이터, 패키지 API를 .tpz 소스에서 쓸 수 있게 열어 주지는 않습니다.

상호 운용 개요, Rust 백엔드, 인터프리터와 백엔드, 산출물과 배포로 이어서 살펴보세요.