Документ-контракт. Фиксирует форму данных, которую ядро отдаёт про один тест-кейс и про решение целиком, чтобы 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, где поля на месте.
Возврат 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_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.
--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, потому что сравнивать
было нечего.
Рядом со 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продюсится: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.
Ответы веб-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 не расходились:
- Имена и семантика перечисленных полей стабильны. Переименование или
смена смысла
passed/verdict/error/timed_out/diff/time/memory— ломающее изменение; допускается только вместе с миграцией всех потребителей (CLI,web.py-мэпперы) и записью в CHANGELOG.md. - Расширение — аддитивно. Новые поля добавляются как опциональные;
потребитель обязан игнорировать незнакомые ключи (как
GraderConfigигнорирует незнакомые ключиpyproject.toml). verdict— единственная точка ветвления UI. Новый вердикт (напр. отдельный для перформанса или sandbox-нарушения будущего server mode) добавляется в перечисление, а не переопределяет существующие.- Адаптеры, не ядро, знают про транспорт. JSON-сериализация, HTTP-коды,
версия API — забота адаптеров (
web.py, будущий API — см. server-mode.md § Контракт API удалённого исполнения). Ядро отдаёт данные, а не транспорт. - Версионирование 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-ключей. Источник истины формы по-прежнему — этот документ + docstringrun_single_test.