Skip to content

msra-app-func-examples.md

Latest commit

 

History

History
44 lines (32 loc) · 5.98 KB

msra-app-func-examples.md

File metadata and controls

44 lines (32 loc) · 5.98 KB
Raw

[app.func..examples]

Таблица [app.func.<id>.examples] хранит именованные примеры вызова функции. Это namespace-контейнер: сам блок может быть пустым, а реальные примеры живут в [app.func.<id>.examples.<name>].

[app.func.<id>.examples.<name>]

Ключ Что делает Как влияет на поведение
inputs Значения входов для примера Опциональное поле. Если его не указать, оно считается равным inputs={} и пример всё равно остаётся валидным.
type Формат результата примера Опциональное поле. Значения: json по умолчанию, text для текстовых ответов и image для image-стримов.
@Test Помечает пример как тестовый контракт Делает пример источником generated contract tests: codegen помечает endpoint-методы @autotest, пишет tests/api_test.py и поддерживает fixtures/hooks/params для canonical JSON примеров.
@Docs Помечает пример как документируемый сценарий Делает пример пригодным для показа в документации и как пользовательский sample. Может принимать print=..., чтобы сгенерировать дополнительные print(...) в mini-guide.
description Краткое описание примера Используется генератором для README и mini-docs только если явно задано; без него комментарий не пишется.

inputs

inputs должен быть inline table с ключами, которые совпадают с именами объявленных input-ов функции. Если inputs не указан, анализатор трактует пример как inputs={}.

Что меняется

  • анализатор проверяет, что каждый inputs.<key> действительно существует в функции;
  • анализатор проверяет типы и допустимые значения;
  • @Test examples используются генератором для contract tests: JSON-примеры становятся canonical fixtures, а text/image примеры превращаются в ручные проверки;
  • FUNCRESULT можно использовать внутри inputs.<key>.value и внутри @Docs(print=...), чтобы связать один пример с результатом другой функции; ссылка должна указывать имя source example перед result-kind, например <FUNCRESULT.<function>.<example>.JSON[@Key(0)]["id"]>;
  • @Docs может принимать необязательный аргумент print=...; значение может быть одним выражением или списком выражений, и генератор превратит их в print(...) подряд в generated mini-guide;
  • если текущий пример помечен @Docs или @Test, то referenced example с FUNCRESULT должен иметь те же флаги; если у текущего примера флага нет, проверку для него не выполняем;
  • type управляет тем, как генератор покажет пример в README: json по умолчанию, text для строкового ответа, image для image-stream;
  • description можно использовать как короткую статическую подпись для документации и generated README; если поле отсутствует, комментарий в mini-guide не пишется;
  • generated README/example.py/quick_start.rst включают все примеры, помеченные @Docs; @Test остаётся независимым флагом для тестового контракта;
  • если @Docs пример ссылается на не-@Docs пример через FUNCRESULT, LSP сообщает об этом, а codegen падает во время генерации вместо того, чтобы скрывать проблему в output;
  • если inputs отсутствует, это эквивалентно inputs={} и не считается ошибкой.
  • имя примера становится именем переменной в generated README/example.py/quick_start.rst; если два выбранных примера сводятся к одному имени переменной, LSP покажет ошибку до генерации.

@Test и @Docs

Семантика

  • @Test помечает пример для contract testing.
  • @Docs помечает пример для отображения в документации.

Правила

  • FUNCRESULT допускается внутри example inputs и внутри @Docs(print=...); он должен указывать source example по имени, например <FUNCRESULT.<function>.<example>.JSON>. После JSON можно применять @Key(id) для выбора ключа или элемента: id должен быть целым числом >= -1; id=0 означает next(iter(data)), id=-1 означает next(reversed(data)), другие значения используют list(data)[id].
  • Если пример ссылается на несуществующий input или даёт значение неподходящего типа, analyzer выдаёт диагностику.