Cluster · разработчикам

Drawing

Передача ресурсов и растеризация сцены через установленный модуль Image Generator.

Получение объекта

drawing = app.images("image-generator-id")

drawing выбирает установленный Image Generator; image_bytes содержит настоящее изображение, canvas является допустимой сценой.

init

Создаёт Drawing. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

def __init__(app: App, module: Module) -> None: ...

Аргументы

app: App, обязательный. Переданный ядром объект app. Второй App в модуле создавать не нужно.
module: Module, обязательный. Объект зависимости Image Generator, не строковый ID.

Результат

None. Создаёт Drawing. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

Права

Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.

Ошибки

Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.

Пример

# Обычный способ получения объекта:
drawing = app.images("image-generator-id")

canvas

Создаёт локальную сцену без обращения к зависимости.

def canvas(width: float = 1200, height: float = 700, background: str | None = None) -> Canvas: ...

Аргументы

width: float, по умолчанию 1200. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
height: float, по умолчанию 700. Размер в пикселях, конечное число. Canvas требует целые размеры 1..2048; полная геометрия проверяется build().
background: str | None, по умолчанию None. Цвет #RRGGBB или #RRGGBBAA; None допускается только для необязательного цвета.

Результат

Canvas. Создаёт локальную сцену без обращения к зависимости.

Права

Ошибки

Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.

Пример

result = drawing.canvas()

call

Вызывает функцию генератора и проверяет форму результата и вложенную ошибку.

async def call(function: str, **values: JSON) -> dict[str, JSON] | bool: ...

Аргументы

function: str, обязательный. Имя функции, сигнала либо поля в выбранном объекте.
values: JSON, произвольные именованные аргументы. Данные выбранной операции. Форма и ограничения описаны ниже; передаваемые JSON-значения копируются.

Результат

dict[str, JSON] | bool. Вызывает функцию генератора и проверяет форму результата и вложенную ошибку.

Права

Нужны modules.call.

Ошибки

ValueError('Invalid image generator response'): условие проверяется до продолжения операции.
error(result['error']): условие проверяется до продолжения операции.
Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await drawing.call("status", count=1)

upload

Принимает bytes, bytearray или готовый File размером 1..2097152 байт. Проверяет доступ к File, ищет фон в кэше генератора по SHA-256 и размеру, при промахе загружает частями. Возвращает новый Asset вызывающего экземпляра; старый генератор поддерживается без кэширования.

async def upload(source: bytes | bytearray | File) -> Asset: ...

Аргументы

source: bytes | bytearray | File, обязательный. Содержимое изображения либо объект готового файла Cluster. Размер 1..2097152 байт.

Результат

Asset. Новый временный Asset. При попадании в кэш исходные байты повторно не передаются.

Права

Нужны modules.call; files.read при источнике File. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение.

Ошибки

ValueError для превышения размера, незавершённой загрузки исходного файла, неверных метаданных кэша, ответа или позиции передачи.
Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

asset = await drawing.upload(image_bytes)

measure

Запрашивает размеры текста с выбранными параметрами стиля.

async def measure(text: str | Text, **style: JSON) -> dict[str, JSON]: ...

Аргументы

text: str | Text, обязательный. Текст или собранный Text там, где поддерживается преобразование. В короткие методы клиента передавай str(Text).
style: JSON, произвольные именованные аргументы. Именованные свойства выбранного слоя: допустимые поля и пределы приведены в IMAGE_GENERATOR.md. Свойства другого типа слоя отклоняются при build().

Результат

dict[str, JSON]. Запрашивает размеры текста с выбранными параметрами стиля.

Права

Нужны modules.call.

Ошибки

Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

metrics = await drawing.measure("Cluster", size=24)

render

Проверяет сцену, получает PNG частями, проверяет метаданные и SHA256, записывает файл Cluster со сроком 120 секунд и освобождает ресурс генератора. Полученные части собираются в блоки до 64 KiB перед записью файла; метаданные, границы частей и итоговая SHA-256 проверяются.

async def render(canvas: Canvas | dict[str, JSON], filename: str = 'image.png') -> File: ...

Аргументы

canvas: Canvas | dict[str, JSON], обязательный. Сцена с width, height, background и layers. Описание проверяется и копируется.
filename: str, по умолчанию 'image.png'. Подпись файла до 255 байт UTF-8 без управляющих символов. None сохраняет исходное имя только у File.copy().

Результат

File. Проверяет сцену, получает PNG частями, проверяет метаданные и SHA256, записывает файл Cluster со сроком 120 секунд и освобождает ресурс генератора.

Права

Нужны modules.call + files.write. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение.

Ошибки

ValueError('Invalid generated image'): условие проверяется до продолжения операции.
ValueError('Invalid generated image metadata'): условие проверяется до продолжения операции.
ValueError('Invalid generated image dimensions'): условие проверяется до продолжения операции.
ValueError('Invalid generated image chunk'): условие проверяется до продолжения операции.
Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

file = await drawing.render(canvas, "card.png")

release

Пытается освободить ресурс генератора. RuntimeError и TimeoutError при очистке подавляются.

async def release(id: str) -> None: ...

Аргументы

id: str, обязательный. Идентификатор объекта, полученный при его создании. Не путь сервера.

Результат

None. Пытается освободить ресурс генератора. RuntimeError и TimeoutError при очистке подавляются.

Права

Нужны modules.call.

Ошибки

Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await drawing.release("object-id")