Перейти к содержанию

Python — внешний исполнитель для смарт-скриптов

Python-скриптинг в 1Форме реализован через внешний HTTP-сервис Python Executor, на который платформа отправляет код смарт-скрипта. Ниже описаны протокол обмена, настройки подключения, состав передаваемого контекста и отличия Python от остальных языков смарт-скриптов (Lua, JavaScript, OneScript, C#).

Статус и обзор

Реализовано. Python-скриптинг доступен в продакшене с версии 2.268.35. Frontend-редактор поддерживает выбор Python в v2.268.38.

Платформа поддерживает четыре языка смарт-скриптов:

Язык Движок ScriptLanguage (enum) LanguageId (БД) Модель исполнения
Lua NLua Lua = 0 0 Внутри платформы
JavaScript Jint 4.6.0 JavaScript = 1 1 Внутри платформы
Python Python Executor (HTTP) Python = 2 2 Внешний сервис
OneScript OneScript OneScript = 3 3 Внутри платформы
C# Roslyn Scripting 4.12 CSharp = 4 4 Внутри платформы

Ключевое отличие Python от Lua и JavaScript: скрипт исполняется не внутри платформы, а отправляется HTTP-запросом на внешний сервис Python Executor.

Версионирование Python SmartScript — обязательно

Каждый Python SmartScript обязан содержать комментарий с версией и датой в начале скрипта. Правило версионирования критично для отладки и отката: без явной версии невозможно определить, какой код выполнялся на момент инцидента.

# v1 | 2026-03-08 15:30 | Начальная версия
# v2 | 2026-03-08 16:45 | Добавлена проверка прав

Версия увеличивается при каждом изменении. Соглашение о версионировании единое для всех языков смарт-скриптов — подробнее в разделе Паттерны JS-скриптов.

Как платформа выполняет Python-скрипт

Когда смарт-действие запускает скрипт с языком Python, платформа определяет язык скрипта, собирает контекст и отправляет код на внешний сервис Python Executor по HTTP. Результат выполнения возвращается обратно и используется в смарт-действии. Скрипты на остальных языках (Lua, JavaScript, OneScript, C#) платформа выполняет сама, без обращения к внешнему сервису.

Протокол обмена с Python Executor

Запрос к Python Executor:

POST {PythonExecutor.ApiUrl}/execute/code
Headers:
  Content-Type: application/json
  X-Api-Key: {ApiKey}   (если настроен)

Body:
{
  "ScriptCode": "def execute(ctx):\n    return ctx['task_id']",
  "Context": { ... },
  "Timeout": 30
}

Ответ при успешном выполнении:

{
  "Status": "ok",
  "Result": 12345,
  "Output": "debug output...",
  "DurationMs": 42
}

Ответ при ошибке:

{
  "Status": "error",
  "Error": "NameError: name 'foo' is not defined",
  "Output": "",
  "DurationMs": 5
}

Обработка ошибок. Платформа прерывает смарт-действие с ошибкой в следующих случаях: сетевая ошибка или таймаут при обращении к сервису; ответ со статусом error (текст ошибки берётся из поля Error); не задан адрес сервиса (ApiUrl).

Контекст скрипта

Python-скрипт получает данные только через объект ctx. Платформа собирает контекст и передаёт его в скрипт, отфильтровывая значения по типу:

Тип значения Что передаётся
Объекты платформы (задача, пользователь и т.п.) Только идентификатор (Id)
Примитивы (строка, число, логическое значение, дата) Передаются как есть
Коллекции (списки, словари) Только если содержат значения, пригодные для передачи в JSON
Сложные объекты Пропускаются

Дополнительно в контекст автоматически добавляется session_user_id — идентификатор текущего пользователя.

Шаблон по умолчанию для нового скрипта:

def execute(ctx):
    pass

Конфигурация и Frontend (AdminSPA)

Настройки подключения к Python Executor хранятся в настройках сервиса:

Параметр Описание
ApiUrl URL Python Executor (например, http://python-executor:8000)
ApiKey API-ключ для авторизации (опционально)

Timeout запроса: 30 секунд (фиксированный).

Редактор скриптов (AdminSPA). С версии 2.268.38 в редакторе смарт-скриптов можно выбрать Python из списка языков (Lua, JavaScript, Python, OneScript, C#). При выборе Python редактор включает подсветку синтаксиса Python и подставляет шаблон по умолчанию def execute(ctx):.

Редактор смарт-скрипта в AdminSPA: выбор языка, кнопки «Выполнить» и «Библиотека», поле кода и история версий

Сравнение с Lua/JS

Ключевые отличия Python от языков, выполняемых внутри платформы:

Аспект Lua (NLua) JavaScript (Jint) Python (Executor)
Модель Внутри платформы Внутри платформы Внешний HTTP-сервис
Sandbox Ограниченный Строгий Полная изоляция (отдельный процесс)
Таймаут 5 мин 5 мин 30 сек
API-объекты (SQL, HTTP, SMART и т.д.) Доступны Доступны Недоступны — только ctx
Библиотеки (include) Да Да Нет
Возврат результата RESULT = value RESULT = value return value из execute(ctx)
Зависимости NLua + Lua DLL Нет (pure .NET) Python Executor (Docker)

Ограничения Python: нет прямого доступа к SQL, HTTP, SMART, CACHE, REGISTRY, FILES API. Скрипт может оперировать только данными из контекста. Для полноценной автоматизации (обращения к БД, HTTP-вызовы) рекомендуются Lua или JavaScript.

Связанные документы домена Smart Actions

Документация по другим языкам смарт-скриптов: