Топаздокументация
Интеграция

Бэкенд Python

Соберите проверенный пакет Топаза в управляемый продукт Python и запустите его без дерева исходного кода Топаза.

Выбирайте целевую платформу Python, если в целевом окружении установлен Python 3.11 или новее и требуется получить читаемый сгенерированный продукт. 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 для поставки

Используйте команду emit только при необходимости изучить или интегрировать сгенерированный исходный код Python:

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. Он не предоставляет доступ к произвольным библиотекам, исключениям, декораторам или API пакетов Python из файлов .tpz.

Профиль приложения Лиспекса не поддерживается в сгенерированном Python. Пакет, задействующий эту возможность, отклоняется до записи артефакта Python. Выберите интерпретатор или допустимую нативную целевую платформу в разделе Запуск правил Лиспекса. Перейдите к разделам границы интеграции, бэкенд Rust, интерпретатор и бэкенды или артефакты и развёртывание.