Канонический справочник по разделам «Правила/PEP» и «Подучить» (дизайн — audit-2026-07.md § 9). Здесь — форматы данных и контракты; продуктовый замысел и wireframes — в аудите.
Строится по образцу глоссария (модель + JSON-провайдер + bundled-данные), но без обобщения в единый «RefCard»-слой — у правил своя специфика (severity, PEP-ссылка, bad/good примеры), преждевременная абстракция дороже (решение § 11 аудита, правило трёх).
Локальная база карточек правил стиля, на которые ссылаются найденные в коде нарушения. Каждая карточка учит духу PEP 8 — объясняет «почему», а не только «что нельзя».
rules/models.py— модельRuleCard(Domain, leaf).rules/json_provider.py—JsonRulesProvider(from_file/from_directory/load),RulesError,bundled_rules()(кеш по mtime черезmtime_cache).rules/data/pep8_ru.json— комплектная база (≥30 частых кодов pycodestyle/pyflakes: E1xx–E7xx, W2xx/W3xx, W605, F401/F811/F821/F841), попадает в wheel через package-data.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
id |
str |
✓ | Код правила: E501, F401 |
title |
str |
✓ | Краткое название (RU) |
summary |
str |
Однострочник: что нарушено (RU) | |
body |
str |
Markdown: «почему» + «как исправить» | |
pep_url |
str |
Ссылка на раздел peps.python.org | |
docs_url |
str |
Доп. ссылка (ruff/pycodestyle) | |
severity |
"convention"|"warning"|"error" |
Тяжесть (на вердикт НЕ влияет) | |
status |
"draft"|"ready" |
Жизненный цикл карточки | |
tags |
list[str] |
Метки для поиска/фильтров | |
example_bad |
str |
Фрагмент-нарушение | |
example_good |
str |
Исправленный фрагмент |
from_dict/to_dict симметричны, с валидацией обязательных полей и
severity/status (как GlossaryCard). JSON-корень — список карточек или
объект {"rules": [...]}.
Тонкая обёртка над ruff check --output-format json --select <коды> --preview:
возвращает list[Violation] (rule_code, line_no, message, column). Свой
AST/tokenize-чекер не пишем — не дублируем pycodestyle (§ 11 аудита).
Набор правил = карточки базы. --select строится из самой
rules/data/pep8_ru.json (rules.lint_select()), а не задаётся широким
E,W,F, и вызывается с --preview. Причина — двустороннее расхождение,
которое накопилось при широком наборе:
| Что | Было | Почему |
|---|---|---|
| Кодов, которые ruff мог выдать без карточки | 74 | E,W,F — это ~110 правил, а карточек 36; объяснить такой код нечем |
| Карточек, недостижимых на практике | 17 из 36 | Их правила у ruff в preview (E1xx/E2xx/E3xx, W391) и без --preview не срабатывают вовсе |
Молчали ровно «школьные» замечания — пробелы вокруг оператора, пробел после запятой, пробелы в скобках, пустые строки между определениями. На типовом файле ученика набор давал 5 замечаний вместо 18.
Набор строится в rules/ (там же, где карточки), а core/lint.py принимает его
параметром — иначе core пришлось бы импортировать rules, а rules уже
зависит от mtime_cache. Прикладной слой (cli/commands._collect_lint,
web/viewmodels._web_lint_records) передаёт один и тот же набор, поэтому CLI и
web не могут разойтись. Пустая база (битый источник) → пустой select → ruff не
запускается.
Guard'ы в tests/test_lint.py: каждый код базы известен текущему ruff (ловит
опечатку в id и правило, удалённое в новой версии), --preview реально
включает whitespace-правила, и ни один показанный код не остаётся без карточки.
Границы (дизайн § 5/§ 9.4):
- Opt-in extra
[lint](pip install stepik-python-grader[lint]) — ruff НЕ runtime-зависимость. Без негоrun_lintбросаетLintUnavailable, а UI/CLI скрывают блок «Стиль» с подсказкой про установку. - Не влияет на вердикт проверки — информационный канал.
- Best-effort: ruff упал / вернул мусор / аварийный код возврата → пустой
список (принцип
cache/stats);code=null(синтаксические ошибки) — пропускается (нет карточки правила, RE и так виден в проверке).
ruff_available() — дешёвая проба для решения, показывать ли блок.
Опциональное поле lint в контракте результата — см.
result-contract.md.
core/history.py (SQLite .grader_history.db) хранит runs/case_results/
lint_violations — фундамент, на котором считаются карточки «Подучить». Опции:
--history/record_history (см. configuration.md).
Данные не покидают машину: канал обратной связи и так не отправляет код
(core/feedback.py), а эти записи вообще не уходят в сеть. Тумблер один на весь
журнал — новые данные не заводят второго согласия (ADR-0002).
| Таблица | Что в ней | Появилась |
|---|---|---|
runs |
прогон: режим, источник (cli/web), ключ и имя задачи, файл решения и его хеш, длительность, признак изоляции |
v1, isolation — v4 |
case_results |
по кейсу: вердикт, время, класс исключения, failure_kind |
v1 |
lint_violations |
по прогону: код правила, строка, сообщение | v1 |
task_progress |
агрегат «попыток/времени до первого зачёта» на задачу | v2 |
stepik_submissions |
вердикт платформы по отправке: шаг, id сабмишна, подсказка Stepik, наш вердикт и флаг расхождения | v4 |
glossary_hits |
переход в карточку глоссария из ошибки: ключ ошибки и id карточки | v4 |
Три решения в v4, которые иначе выглядят произволом:
runs.isolation:NULL≠"none".NULL— «неизвестно» (записи до появления колонки),"none"— «точно без ОС-изоляции», остальное — имя backend'а (bwrap/sandbox-exec/job-objects). Backend назван, а не свёрнут в булев признак: гарантии у трёх реализаций разные (SECURITY.md).- Расхождение вердиктов считается при записи. Наш вердикт изменчив
(следующий прогон перепишет
runs, retention вытеснит старые записи), а вопрос задаётся про момент отправки. Посчитанный при чтении, флаг отвечал бы про сегодняшнее состояние базы, а не про то, что случилось. - Связь с прогоном рвётся, факт остаётся. У
stepik_submissions.run_idнамеренноON DELETE SET NULL: вердикт платформы невосстановим, а наш прогон воспроизводится запуском.
Пишется только переход из ошибки, а не любое открытие раздела «Глоссарий»:
метрика отвечает на вопрос «работает ли связка упал → понял», а не «сколько
карточек полистали». У события нет задачи, поэтому точечное
--purge-history <задача> его не трогает — оно уходит при удалении базы
целиком; вердикты платформы, наоборот, удаляются по задаче вместе с прогонами.
Статус
lint_violations. Контур наполнения замкнут:LintRecordконструируется вcore/history_recording.py(lint_records_from_violations),record_run(lint=...)вызывается из CLI (cli/commands.py, режимы 1/2 при--lint --history) и web-грейдинга (web/viewmodels.py), нарушения пишутся вlint_violations(core/history.py). Категория «lint» ниже достижима — карточки «Подучить» строятся поrule_codeиз истории (core/insights.py). Формат поля — секция «Опциональное полеlint» в result-contract.md.
Ключ карточки «Подучить» — failure_kind (падение) или rule_code
(lint-нарушение, наполняется при --lint --history / web-грейдинге).
failure_kind — чистая классификация исхода кейса (заполняется при записи в
историю):
| kind | Когда |
|---|---|
timeout |
TLE |
runtime-error:<Класс> |
RE (имя исключения из stderr тем же lookup_from_error; runtime-error без класса) |
output-format |
WA, где вывод совпал с точностью до пробелов/пустых строк/регистра |
wrong-answer |
прочие WA |
slow |
SLOWER/MUCH_SLOWER режимов 3/4 |
Статус карточки — чистая функция classify_status(flags) от истории её
ключа в последних N прогонах (True = встречался), по номерам прогонов, а
не по календарю (тестируемо без часов/freezegun):
| status | Правило |
|---|---|
active |
≥T попаданий в окне и последний прогон «грязный» |
fading |
был активен, 1..K-1 последних прогонов чистые |
archived |
≥K чистых прогонов подряд → исчезает из «Подучить», остаётся в «архиве побед» |
watch |
появлялся, но ниже порога активности (первое появление / «мигающая» ошибка) |
Пороги N/T/K (default 10/2/3) настраиваются в [tool.stepik-grader]
(insights_window_n/insights_active_threshold_t/insights_clean_streak_k).
learning_cards(db_path) агрегирует карточки из истории на лету — без
хранимого состояния; archived по умолчанию скрыты (include_archived=True
для «архива побед»), а runtime-error:<Класс> несёт glossary_id — ссылку на
карточку исключения в глоссарии.