토파즈문서
인터롭

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 학습과제 {
    제목: string,
    분: int,
    완료: bool = false,
}

function 분해석(텍스트: string) -> Result<int, string> {
    match toInt(텍스트) {
        case Some(값) if 값 > 0 => Ok(값)
        case _ => Err("minutes must be a positive integer")
    }
}

export function 과제만들기(
    제목: string,
    분문자열: string,
    완료: bool = false,
) -> Result<학습과제, string> {
    let 분 = 분해석(분문자열)?
    Ok(학습과제 { 제목: 제목, 분: 분, 완료: 완료 })
}

export function 요약(과제들: Array<학습과제>) -> string {
    let mut 남음 = 0
    for 과제 in 과제들 {
        if !과제.완료 {
            남음 = 남음 + 과제.분
        }
    }
    "tasks={과제들.length}, remaining={남음} minutes"
}

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

TOPAZ
import src.plan { 학습과제, 과제만들기, 요약 }

export function main(인자: Array<string>, 표준입력: string) -> Result<int, string> {
    let 과제들: Array<학습과제> = [
        과제만들기("Run first program", "10", true)?,
        과제만들기("Build application", "25", false)?,
    ]
    print(요약(과제들))
    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 해시가 기록됩니다. 토파즈는 매니페스트를 가장 마지막에 작성합니다. 관리 파일이 변경되었거나, 충돌이 발생했거나, 동일한 출력 디렉터리에 다른 타깃의 결과물이 존재하는 경우에는 빌드가 거부됩니다. 배포할 때는 디렉터리 트리 전체를 옮기세요. program.py와 topaz_py_rt.py는 항상 함께 있어야 합니다. 고지 사항 문서, 라이선스, 매니페스트 역시 관리형 제품의 일부입니다.

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

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 소스에서 사용할 수 있도록 허용해 주는 것은 아닙니다.

리스펙스 애플리케이션 프로필은 생성 Python 기능이 아닙니다. 이 기능에 도달하는 패키지는 Python 아티팩트를 쓰기 전에 거부됩니다. 리스펙스 규칙 실행하기에서 인터프리터나 승인된 네이티브 타깃을 고르세요. 상호 운용 개요, Rust 타깃, 인터프리터와 백엔드, 아티팩트와 배포 문서를 이어서 살펴보세요.