msra-app-func-input.md

[app.func..input.]

Таблица [app.func.<id>.input.<name>] описывает один аргумент метода. Из неё client строит сигнатуру функции, runtime-валидацию и более узкие Python-типы.

Ключ	Что делает	Как влияет на поведение
type	Тип аргумента	Формирует аннотацию метода и runtime-валидацию. Поддерживаются примитивы, списки и объединения через массивы типов.
description	Описание аргумента	Используется в docstring-ах и подсказках.
@Required	Делает аргумент обязательным	Убирает None из сигнатуры и заставляет client проверять наличие аргумента.
default	Значение по умолчанию	Подставляется, если caller не передал аргумент. Если default задан, сигнатура использует это значение как fallback.
values	Набор допустимых значений	Ограничивает аргумент по enum-like списку. В сочетании без match может сузить Python-тип до Literal[...].
from	Связующий источник значения	Служит для downstream-связок и tooling; сам по себе не меняет сигнатуру, но может участвовать в контрактных преобразованиях.
match	Дополнительная проверка	Ограничивает аргумент диапазоном чисел, regex-ссылкой или whitelist-значениями.

type

Поддерживаемые формы:

• string
• integer
• boolean
• array
• object
• null
• list[string], list[integer] и т.п.
• объединения через массив типов, например [string, null]

Что меняется

• type определяет Python-аннотацию параметра.
• list[...] включает проверку каждого элемента списка.
• null делает значение nullable в generated type.

default

default определяет значение, которое method-argument получит, если caller не передал его явно.

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

• argument становится удобнее вызывать;
• в сигнатуре появляется default-value;
• runtime не требует None, если default уже подставлен.

values и match

Эти ключи решают разные задачи:

• values задаёт перечислимый набор допустимых значений;
• match задаёт общую проверку формата или диапазона.

Правила

• values и match не должны сосуществовать в одном input-табле.
• Если values есть и match нет, тип может сузиться до Literal[...].
• Для списочных input-ов тип может стать list[Literal[...]], если whitelist задан без match.

from

from полезен, когда input участвует в более сложной контрактной связке:

• его можно переиспользовать в url.params, body и других вычисляемых местах;
• tooling может использовать его как связующую подсказку;
• сам метод не меняет поведение только из-за from, но контрактная модель становится богаче и точнее.