YETI³ SDK 0.4.3: от первого модуля до своего приложения

Начните с небольшой функции, выделите её в модуль и соберите приложение, в котором правила работы, интерфейс и оформление можно развивать отдельно. Показываем путь на Python: установка, первый сервис, запуск учебного проекта и подготовка собственного релиза.

SDK полезен, когда проект перестаёт помещаться в один скрипт. Например, у системы заявок появляются уведомления, история действий и несколько экранов. Если каждый экран напрямую меняет базу и сам отправляет уведомления, одно изменение приходится повторять в нескольких местах. Модульная сборка позволяет определить владельца каждой функции и явные связи между частями приложения.

В этой инструкции зафиксирована версия 0.4.3, доступная в официальном репозитории пакетов на дату публикации. Это практический обзор текущего SDK, а не список изменений исключительно релиза 0.4.3. На некоторых страницах документации ещё встречается 0.3.1; для воспроизводимого запуска ниже указан точный номер пакетов.

Что входит в SDK

Подключайте пакеты по необходимости. Для первого модуля достаточно ядра. Для полноценного сайта отдельно нужны HTTP-сервер, хранение данных, авторизация и эксплуатационные настройки. SDK не выбирает эти решения за разработчика.

1. Установите проверенную версию

Для всей инструкции используйте Python 3.12 или новее. Метаданные ядра 0.4.3 допускают Python 3.11, но это не означает, что такой же минимум у всех пакетов и учебных проектов.

В новой папке проекта на macOS или Linux:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --index-url https://engine.yeti3.ru/sdk/simple/ yeti3-core==0.4.3
python -m pip check
python -c "from importlib.metadata import version; print(version('yeti3-core'))"

Последняя команда должна вывести 0.4.3. На Windows окружение можно создать и использовать без изменения политики PowerShell:

py -3.12 -m venv .venv
.venv\Scripts\python.exe -m pip install --index-url https://engine.yeti3.ru/sdk/simple/ yeti3-core==0.4.3
.venv\Scripts\python.exe -m pip check

Ключ API портала для установки Python-пакета не требуется. Виртуальное окружение отделяет зависимости нового проекта от остальных программ на компьютере.

2. Напишите первый модуль

Сохраните этот самостоятельный пример в hello.py. Он предоставляет сервис расчёта стоимости: интерфейс приложения получает его по имени, а правила расчёта остаются внутри модуля.

from decimal import Decimal
from yeti3_core import Engine, Module, ModuleManifest

class Estimate(Module):
    manifest = ModuleManifest(
        id="example.estimate",
        name="Расчёт стоимости",
        version="1.0.0",
        provides=("example.estimate",),
    )

    def register(self, engine):
        engine.provide(
            "example.estimate", self,
            module_id=self.manifest.id,
        )

    def total(self, hours, rate):
        hours, rate = Decimal(str(hours)), Decimal(str(rate))
        if not hours.is_finite() or not rate.is_finite():
            raise ValueError("Нужны конечные числа")
        if hours < 0 or rate < 0:
            raise ValueError("Часы и ставка не могут быть отрицательными")
        return (hours * rate).quantize(Decimal("0.01"))

engine = Engine()
engine.register(Estimate())
engine.boot()
service = engine.capabilities.get("example.estimate")
print(service.total("2.5", "1200"))

python hello.py

Результат — 3000.00. Номер 1.0.0 внутри манифеста относится к вашему модулю, а не к версии SDK. У каждого нового модуля должен быть собственный идентификатор.

3. Определите зависимости и события

Модуль может зависеть от другого модуля: такие связи описываются в requires манифеста. Регистрируйте все компоненты до запуска engine.boot(). Получение сервиса через capabilities.get() делает зависимость видимой в коде и позволяет менять реализацию в одном месте.

События подходят для реакций на уже выполненное действие. В учебном проекте создание заявки вызывает реакцию второго модуля. Для боевых уведомлений, платежей и других действий, которые нельзя потерять при перезапуске, предусмотрите устойчивую очередь, повторы и защиту от дублирования. Сам факт вызова обработчика в памяти этого не обеспечивает.

4. Запустите приложение «Мастерская»

Следующий шаг — официальный практикум с полным архивом исходников. Скачайте и распакуйте архив, затем откройте терминал в папке workshop.

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --index-url https://engine.yeti3.ru/sdk/simple/ yeti3-core==0.4.3 yeti3-assets==0.4.3
python -m pip check
python app.py

Откройте http://127.0.0.1:8088. Создайте заявку, завершите её и верните в работу. Остановите приложение и запустите снова: этот простой опыт проверяет, что данные действительно сохраняются.

Для повторения именно этой проверки используйте зафиксированные команды выше. Скачанный архив на дату проверки также содержит собственный requirements.txt с установкой пакета yeti3-engine из канала latest; такой запуск может получить более свежий релиз позднее.

5. Развивайте приложение по частям

Начните с одного изменения, результат которого легко проверить. Например, добавьте правило для названия заявки и тест для него. Затем поменяйте подпись поля в шаблоне. Только после этого добавляйте новый сценарий или таблицу.

• Правила: проверка входных данных должна оставаться на серверной стороне, даже если у поля HTML уже есть ограничения.
• Интерфейс: пользовательский текст нужно экранировать перед выводом. Проверяйте не только обычные фразы, но и кавычки, угловые скобки, длинные строки.
• Оформление: CSS и изображения можно менять независимо от хранения заявок и событий.
• Данные: добавление нового поля к существующей базе требует миграции. Команда создания таблицы сама по себе не обновит её структуру.

6. Установите ассеты и выполните тесты

python install_assets.py
python -m unittest discover -s tests -v

Установка ассетов должна создавать отдельный результат, не затирая исходный проект. Повторную установку в занятую папку следует рассматривать как проверку защиты от перезаписи; для нового опыта выбирайте другую пустую папку.

7. Подготовьте собственный релиз

Отделите исходники модуля от локальных данных, ключей и временных файлов. Зафиксируйте версии зависимостей и требования к Python. Приложите инструкцию с ожидаемым результатом запуска и автоматические проверки. Если пакет изменяет схему хранения, опишите обновление и восстановление из резервной копии.

Перед передачей пакета другому разработчику повторите установку в новом окружении. Проверяйте именно архив релиза: рабочая папка может незаметно предоставлять файлы, которые забыли включить в поставку.

Для распространения через GoChain изучите текущий процесс в кабинете разработчика. Исходный модуль, проверенный установочный релиз и установленный на целевом сайте пакет — разные состояния. Совместимость и условия установки должны быть подтверждены до изменения рабочего сайта.

API портала: отдельный способ интеграции

Python SDK работает внутри вашего приложения. API портала нужен для взаимодействия с возможностями самого портала. Доступ оформляется через кабинет разработчика; ключ передаётся сервером и не должен попадать в клиентский JavaScript или Git.

Начните с страницы разработчиков и справочника API, на который она ссылается. Проверяйте разрешения конкретного ключа. Наличие доступа к каталогу не предоставляет доступ к данным и операциям других проектов.

Если запуск не удался

• Модуль не найден: проверьте активное окружение и устанавливайте зависимости через python -m pip тем же интерпретатором, которым запускаете проект.
• Порт занят: запустите python app.py --port 8090 и откройте новый адрес.
• Форма перестала отправляться после перезапуска: обновите страницу перед повторной отправкой.
• Версии отличаются от статьи: проверьте установленные пакеты через python -m pip list. Не смешивайте проверку конкретного релиза с автоматическим обновлением из latest.

Учебный HTTP-сервер предназначен для локального запуска. Для публичного приложения подготовьте HTTPS, вход пользователей, разграничение доступа, резервные копии и журналирование. Подключение SDK не заменяет эти части системы.

• SDK, кабинет разработчика и API YETI³
• Практикум «Мастерская»
• Инструкция к исходному проекту
• Опубликованные версии ядра