msra-app-variables.md

[app.variables.]

Таблица [app.variables.<name>] описывает переменную, которую runtime извлекает из окружения, сетевых заголовков, cookies или storage и затем делает доступной как обычное значение клиента.

Ключ	Что делает	Как влияет на поведение
types	Список допустимых type-веток	Определяет, как runtime будет коэрцировать и типизировать значение. Поддерживаются string, integer, boolean, array, object, а также null.
description	Документация переменной	Используется в hover, generated docs и docstring-ах.
@ReadOnly	Делает переменную только для чтения	Generated package не создаёт setter для этой переменной. Значение может только захватываться runtime-ом.
@Nullable	Разрешает None/null	Generated client начинает считать переменную nullable в типах и в runtime-проверках.
from	Источник значения	Указывает, откуда runtime должен захватить значение: заголовок, cookie, localStorage, sessionStorage или другой допустимый reference-источник.

types

Каждый элемент в types описывает одну допустимую форму значения.

Ключ	Что делает
type	Базовый тип ветки: string, integer, boolean, array, object или null
match	Дополнительная валидация: диапазон, regex-ссылка или whitelist значений

Что меняется

• types влияет на coercion в generated client.
• Если значение не совпадает с ожидаемым типом, runtime выбрасывает ValueError или TypeError в зависимости от места проверки.
• match сужает допустимые значения после type coercion.
• Если match задан literal-array значений, generated property annotation сужается до Literal[...], а setter проверяет membership по этому списку.
• Если null присутствует в types, generated type тоже становится nullable.

from

from связывает переменную с живым источником данных.

Практически это означает:

• runtime берёт raw value из указанного источника;
• затем приводит его к одному из типов из types;
• после этого проверяет match, @Nullable и остальные ограничения;
• итоговое значение кладётся в backing field клиента и доступно как VARIABLES.<name>.