Skip to content

Latest commit

 

History

History
306 lines (258 loc) · 26.3 KB

result-contract.md

File metadata and controls

306 lines (258 loc) · 26.3 KB

Контракт результата проверки (CLI / Web / API)

Документ-контракт. Фиксирует форму данных, которую ядро отдаёт про один тест-кейс и про решение целиком, чтобы CLI, веб-оболочка (--serve) и будущий API/сервер (см. server-mode.md) опирались на один стабильный набор полей, а не переизобретали его.

Это контракт, не описание реализации: имена полей и семантика вердиктов здесь канонические. Продуктовые ViewModel'и веб-слоя (ResultViewModel, ErrorCard) — надстройки над этим контрактом, канонично описаны в web-contracts.md § Контракты данных и здесь не дублируются. Форматы тест-кейсов и таблица вердиктов — в configuration.md.

Уровни контракта

Проверка возвращает данные на трёх уровнях. Каждый последующий агрегирует предыдущий:

Уровень Что описывает Кто строит Форма сегодня
Case result Один тест-кейс на одном решении core.grader_core.run_single_test CaseResult (TypedDict)
Solution result Одно решение на всех кейсах (агрегат) run_tests / run_benchmark SolutionResult / BenchResult (TypedDict)
Run result Прогон пути (файл/папка) — набор решений адаптер (cli.py, web.grade_path) dict / ResultViewModel

Case- и solution-уровни формализованы как TypedDict'ы в core.result (CaseResult, SolutionResult, BenchResult): mypy проверяет ключи и типы полей во всей цепочке CLI→web→pytest-плагин, но runtime-представление остаётся обычным dict — это по-прежнему та же форма на границе JSON-вывода. Два типа на агрегат, а не один: корректность (run_tests) и замер (run_benchmark/run_microbench_mode) отдают разные наборы полей, и общий тип пришлось бы сделать почти целиком NotRequired — то есть не проверяющим ничего. Run-уровень остаётся адаптерным: Web маппит его в JSON ViewModel. Контракт описывает имена и смысл полей, а не конкретный Python-тип: типизированная модель, попадающая на границу JSON, обязана сохранить эти имена.

TestResult (core/result.py) — намеренное исключение: это усечённый носитель для печати (reporter.print_case_verbose строит его через from_dict), а не сериализуемая модель. Он не несёт exit_code/stdin, и его to_dict() для вывода наружу использовать нельзя — JSON-граница идёт по CaseResult/dict, где поля на месте.

Case result — поля

Возврат run_single_test (режимы 1–3). Источник истины полей — docstring функции; здесь — их семантика и стабильность.

Поле Тип Всегда Описание
passed bool ✓ Прошёл ли кейс (вывод совпал с ожидаемым)
verdict "AC"|"WA"|"OLE"|"TLE"|"RE"|"CANCELLED"|"SANDBOX_VIOLATION" ✓ Вердикт кейса (см. ниже); при ошибке до запуска — "RE"
output list[str] ✓ Фактический вывод решения (строки)
expected list[str] ✓ Ожидаемый вывод кейса (строки)
diff str ✓ Unified-diff при несовпадении; пустой при AC
time float ✓ Время выполнения, секунды
memory float ✓ Пик памяти, МБ (0.0, если замер выключен)
error str ✓ Сообщение об ошибке; пустая строка = ошибки нет
timed_out bool ✓ Истёк ли таймаут
exit_code int | None ✓ Код возврата процесса решения; None, если процесс не завершился нормально (ошибка запуска/таймаут)
stdin str — NotRequired: stdin кейса, если он был подан на вход решению; ключ отсутствует, когда входа не было

Инвариант согласованности: verdict — производное от остальных полей и должно с ними согласоваться:

  • AC ⟺ passed is True;

  • TLE ⟹ timed_out is True, passed is False;

  • RE ⟹ error != "" (и/или ненулевой код возврата процесса), passed is False;

  • WA ⟹ passed is False and not timed_out and error == "" — вывод получен, но не совпал; diff непустой.

  • CANCELLED ⟹ passed is False, timed_out is False, error != "" — кейс прерван через cancel_event (async job-модель), не таймаутом и не ошибкой решения; UI не должен показывать его как провал решения.

  • OLE ⟹ passed is False, timed_out is False, error != "" — вывод решения перерос потолок max_output_bytes и был обрезан. Отдельный вердикт, а не WA, по тому же основанию, что и TLE: превышен лимит, а не «ответ неверный». Разница не косметическая — после обрезки сравнивать нечего: известно лишь, что уцелевшие байты дошли, а что решение печатало дальше, не знает никто. Пока признак обрезки не доезжал до маппинга, это молча превращало WA в AC: болтливое неверное решение теряло лишнее вместе с несовпадением и проходило проверку. SandboxRunner для того же случая даёт SANDBOX_VIOLATION (output_size) — он обрывает процесс, а не урезает результат.

  • SANDBOX_VIOLATION ⟹ passed is False, timed_out is False, error != "" — только у SandboxRunner (--sandbox): решение превысило sandbox-квоту (память/процессы/сеть/ФС/размер вывода), LocalRunner никогда не даёт этот verdict. В отличие от CANCELLED — это провал решения (реально сделало что-то запрещённое), UI может стилизовать как ошибку (см. core/reporter._STATUS_COLORS).

Потребитель может доверять verdict как единственному полю для ветвления UI, не пересобирая логику из passed/timed_out/error.

Вердикты (семантика)

Канонический список — configuration.md § Вердикты. Контрактно закреплено:

Вердикт Значение Терминальность
AC Accepted — вывод совпал успех
WA Wrong Answer — вывод не совпал провал (детерминированный)
TLE Time Limit Exceeded — превышен таймаут провал (недетерминированный по времени)
RE Runtime Error — процесс упал / ошибка до запуска провал (крэш)
OLE Output Limit Exceeded — вывод перерос max_output_bytes и обрезан провал (проверить нечем: сравнивать можно лишь то, что доехало)
CANCELLED Cancelled — прерван пользователем через async job-модель не провал; терминально, но не оценивает решение
SANDBOX_VIOLATION Sandbox Violation — превышена квота изоляции (только --sandbox) провал (решение нарушило sandbox)

Бенчмарк-режимы (3/4) добавляют перформанс-вердикты решения (не кейса): SIMILAR / SLOWER / MUCH SLOWER относительно быстрейшего решения — пороги similar_threshold/much_slower_threshold (configuration.md). Они живут на уровне solution result и не смешиваются с корректностными вердиктами кейса.

Там же возможен SKIPPED — решение не допущено к замеру: пре-флайт (один прогон тестов перед бенчмарком) показал, что оно не проходит тесты. Строка приходит без метрик (runs: 0, нет median), с человекочитаемой причиной в error вида «не прошёл проверку: 2 из 3 (первый провал: WA)», и не участвует в ранжировании. Сравнивать по времени решения с разным результатом бессмысленно: run_benchmark меряет время, не сверяя вывод, поэтому без пре-флайта решение с неверным ответом получало бы медиану и место в рейтинге наравне с корректными. Отсутствие тест-кейсов — не SKIPPED: там нечего сверять, и режим сообщает об этом своим обычным «нет тест-кейсов».

Форма ошибки и таймаута

  • RE. error содержит человекочитаемое сообщение; для реального крэша процесса — фрагмент stderr/трейсбека. Ошибки до запуска (не найдено имя функции, битый wrapper) тоже дают verdict="RE" с заполненным error и time=0.0 — потребитель не должен различать «упал в рантайме» и «не удалось собрать запуск» по форме результата, только по тексту error.
  • TLE. timed_out=True, verdict="TLE", time ≈ лимиту (CONFIG.timeout_seconds). Частичный output может присутствовать.
  • Микро-бенчмарк (режим 4). Локального per-call таймаута нет — зависание упирается в общий subprocess.run(timeout=60); сообщение об ошибке содержит number=<N> (см. configuration.md § Ограничения).
  • Секреты. error/diff/output — это вывод пользовательского решения; токены и содержимое secrets.json в них попадать не должны (см. SECURITY.md). Для будущего логирования — правила редакции в logging.md.

Solution result и Run result

  • Solution result (run_tests, тип SolutionResult) агрегирует кейсы: passed (int), total (int), cases (список case result), суммарное/среднее time, memory. Решение считается OK, когда total > 0 and passed == total; NO TESTS — когда тестов не найдено (total == 0). Есть опциональное warnings (list[str]) — предупреждения загрузки набора: рассогласование блоков формата 3, непарные input_N/expected_N, смешение форматов в одной папке. Пустой список означает, что набор загружен целиком. Поле нужно потому, что «OK N/N» на урезанном наборе и «OK N/N» на полном выглядели одинаково: предупреждение уходило только в stderr, и машинный потребитель не отличал полный прогон от частичного. Ключ NotRequired: словари результата собирают ещё кэш и web-адаптеры, и обязательное поле сломало бы их молча.

    Отдельно: error в case result не пуст и при WA, если вердикт объясняется обрезкой вывода по max_output_bytes. Раньше это поле в ветке AC/WA было захардкожено пустым, и WA от лимита грейдера был неотличим от обычного несовпадения — студент искал ошибку в своём коде.

  • Bench result (run_benchmark, run_microbench_mode; тип BenchResult) — агрегат замера: runs (сколько замеров реально получилось) плюс min/max/mean/median/stdev/peak_memory_mb/relative/verdict. Обязателен только runs: у записи-ошибки (error заполнен) он равен 0, а статистики нет — потребитель обязан читать error до цифр. Оба режима замера дают одинаковую форму ошибки: раньше режим 3 клал runs: 0, а режим 4 — только error, и общий потребитель падал KeyError на микробенче.

  • Run result — обёртка над набором решений с полями kind ("file"|"dir"|"error"), mode ("tests"|"bench"), base (база для относительных имён), rows (по решению), message/message_id/ message_params (только при kind="error", см. § Локализация сообщений (message_id) ниже). Это уже адаптерный слой; Web отдаёт его как ResultViewModel — см. web-contracts.md.

status в машинном выводе CLI

--output json и табличные форматы CLI несут поле status — "ok" | "fail" | "no_tests". Оно кодирует то же, что код возврата процесса, и разойтись с ним не может: оба считаются из одного ExitCode.

Поле появилось потому, что «ни одного кейса не загружено» выглядело в машинном выводе как прогон без провалов: total: 0, failed: 0, cases: []. Текстовая таблица честно печатала NO TESTS, а потребитель JSON видел успех — самый тихий способ пропустить неверное решение, когда тесты не скачались.

  • режим 1: {"file": ..., "status": ..., ...};
  • режим 2: status у пачки и у каждого решения внутри results;
  • csv/markdown режима 1 на пустом наборе печатают одну строку со статусом вместо нуля строк — пустая таблица читалась как «всё хорошо».

Потребителю: проверять status, а не failed == 0.

Режимы замера (3/4) и ранние выходы («папка не найдена», «решений нет») несут status на тех же правилах: пустой замер — no_tests, потому что сравнивать было нечего.

schema, mode и isolation в машинном выводе CLI

Рядом со status едут ещё три пометки — аддитивно, существующие ключи не тронуты, потребитель волен их игнорировать:

Поле Значения Зачем
schema 1 версия формы машинного вывода CLI; растёт при ломающем изменении
mode grade · batch · benchmark · microbench четыре режима дают четыре разные формы результата, а признака, по которому их различить, не было — парсер угадывал по набору ключей
isolation none · имя backend'а песочницы под --sandbox вердикты другие, а по артефакту прогона это было недоказуемо

Ранний выход несёт schema/status/isolation и пару error/reason, но без mode: режим до отказа не начинался.

Полный конверт {"schema", "mode", "results"} вместо плоского объекта был бы сменой корня, то есть ломающим изменением (см. § Ожидания стабильности, п. 2) — поэтому пометки едут рядом с существующими ключами, а не оборачивают их.

Те же сведения об изоляции пишутся в строку .grader_stats.jsonl полем isolation; у записей, сделанных раньше, поля нет — потребитель обязан считать его отсутствие как «неизвестно», а не как none.

Опциональное поле lint

Поле lint продюсится: core/lint.py (run_lint) даёт нарушения стиля, которые core/history_recording.py (lint_records_from_violations) превращает в LintRecord, а record_run(lint=...) пишет в таблицу lint_violations (core/history.py) — из CLI (cli/commands.py, --lint --history, режимы 1/2) и из web-грейдинга (web/viewmodels.py). Категория «lint» в разделе «Подучить» достижима (core/insights.py). Ниже — формат поля.

Формат (при включённой PEP-проверке, extra [lint]): результат решения может нести дополнительное поле lint — список нарушений стиля от core/lint.py:

Поле Тип Описание
rule_code str Код правила ruff/pycodestyle (E501, F401) — ключ карточки в rules/
line_no int 1-based номер строки (0, если ruff не сообщил)
message str Текст нарушения от ruff
column int 1-based колонка (0, если не сообщена)

Инвариант: lint не влияет на verdict/passed/OK — это информационный канал. Поле отсутствует, когда ruff недоступен (LintUnavailable) или проверка стиля не запрашивалась; потребитель обязан работать без него (обратная совместимость). Формат Violation и границы — rules-insights.md.

Локализация сообщений (message_id)

Ответы веб-API с человекочитаемым message (не только Run result — та же пара полей стоит рядом с message в error-конвертах /api/*, включая обе существующие формы — {"kind": "error", ...} и {"ok": False, ...}; сам конверт собирает хелпер _json в web/http_guards.py, а наполняют его хендлеры web/api_routes.py и web/viewmodels.py) дополнены двумя полями:

Поле Тип Описание
message str Человекочитаемый текст, отрендеренный сервером из каталога сообщений (см. ниже). Сохранён для обратной совместимости — потребители, не знающие про message_id, продолжают работать без изменений.
message_id str Машиночитаемый ключ каталога (core/locales/<lang>.json), например "path_not_found". Позволяет клиенту локализовать/кастомизировать текст самостоятельно, не парся message.
message_params dict[str, Any] Значения, подставленные в шаблон message_id при рендере (например {"path": "..."}); пустой dict, если подстановок не было.

Локаль. Выбирается query-параметром ?lang= на GET/POST /api/* эндпойнтах (ru/en; любое другое значение или отсутствие параметра — ru, поведение по умолчанию не меняется). Рендерит и выбирает локаль stepik_grader.web.i18n (render_message()/message_fields()) — надстройка веб-слоя над core.i18n.load_locale_messages(): core/i18n.py остаётся leaf-модулем (только stdlib), сам каталог и интерполяция message_params — забота web/i18n.py, не ядра. Guardrail scripts/check_locale_guardrails.py (CI) следит, чтобы все message_id, на которые ссылается web/*.py, существовали в ru.json, а ru.json/ en.json имели одинаковый набор ключей.

Ожидания стабильности (для будущих потребителей)

Контракт задаёт правила эволюции, чтобы CLI/Web/API не расходились:

  1. Имена и семантика перечисленных полей стабильны. Переименование или смена смысла passed/verdict/error/timed_out/diff/time/memory — ломающее изменение; допускается только вместе с миграцией всех потребителей (CLI, web.py-мэпперы) и записью в CHANGELOG.md.
  2. Расширение — аддитивно. Новые поля добавляются как опциональные; потребитель обязан игнорировать незнакомые ключи (как GraderConfig игнорирует незнакомые ключи pyproject.toml).
  3. verdict — единственная точка ветвления UI. Новый вердикт (напр. отдельный для перформанса или sandbox-нарушения будущего server mode) добавляется в перечисление, а не переопределяет существующие.
  4. Адаптеры, не ядро, знают про транспорт. JSON-сериализация, HTTP-коды, версия API — забота адаптеров (web.py, будущий API — см. server-mode.md § Контракт API удалённого исполнения). Ядро отдаёт данные, а не транспорт.
  5. Версионирование API. Когда появится сетевой API (server-mode.md), он версионирует именно этот контракт (/api/v1/...); поля case/solution result — его семантическое ядро.

Типизированный TestResult. stepik_grader.core.result.TestResult — frozen dataclass с полями case result выше + Verdict = Literal["AC", "WA", "TLE", "RE", "CANCELLED", "SANDBOX_VIOLATION"]. Рядом живёт CaseResult (TypedDict) — статический тип того же словаря: run_single_test() теперь аннотирован -> CaseResult, а from_dict() принимает любой Mapping[str, Any] (в т.ч. CaseResult). Runtime-форма при этом не менялась — обычный dict на границе CLI JSON-вывода, run_tests()/run_benchmark() и /api/grade. TestResult используется там, где нужна типобезопасность поверх словаря — сейчас: core/reporter.print_case_verbose конвертирует dict в TestResult на входе вместо чтения произвольных dict-ключей. Источник истины формы по-прежнему — этот документ + docstring run_single_test.