Skip to content

Latest commit

 

History

History
181 lines (143 loc) · 13 KB

rules-insights.md

File metadata and controls

181 lines (143 loc) · 13 KB

Правила PEP 8 и учебные инсайты

Канонический справочник по разделам «Правила/PEP» и «Подучить» (дизайн — audit-2026-07.md § 9). Здесь — форматы данных и контракты; продуктовый замысел и wireframes — в аудите.

Строится по образцу глоссария (модель + JSON-провайдер + bundled-данные), но без обобщения в единый «RefCard»-слой — у правил своя специфика (severity, PEP-ссылка, bad/good примеры), преждевременная абстракция дороже (решение § 11 аудита, правило трёх).


Пакет rules/ — карточки правил

Локальная база карточек правил стиля, на которые ссылаются найденные в коде нарушения. Каждая карточка учит духу 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.

Формат карточки RuleCard

Поле Тип Обяз. Описание
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": [...]}.


core/lint.py — PEP-проверка через ruff

Тонкая обёртка над 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).

Что именно пишется (схема v4)

Данные не покидают машину: канал обратной связи и так не отправляет код (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.


Таксономия падений и затухание (core/insights.py)

Ключ карточки «Подучить» — 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 — ссылку на карточку исключения в глоссарии.