Stepik Python Grader

Status: Stable  ·  🇬🇧 English quick start & generic mode

Локальный грейдер для курсов «Поколение Python» на Stepik. Скачивает данные задачи с сайта и позволяет не только проверить решение локально, но и сравнить несколько решений более честно: сначала по корректности, потом по benchmark-метрикам.

Сверх обычного прогона тестов: офлайн-глоссарий Python с переходом прямо из ошибки, пошаговый трассировщик с memory-graph, микробенчмарк timeit, OS-песочница для Linux/macOS/Windows и AI-объяснение падений (opt-in, свой ключ).

pipx install stepik-python-grader && stepik-grader   # меню; stepik-grader-gui — окно без терминала

Форк / продолжение проекта: Первоисточник грейдера

💬 Нашли баг или есть идея? Пункт 9 в меню грейдера и кнопка 💬 в веб-интерфейсе открывают форму issue уже заполненной (версия, ОС, Python подставятся сами). Вопрос, а не баг — в Discussions.

Курсы:

• Поколение Python: Курс для начинающих
• Поколение Python: Курс для продвинутых
• Поколение Python: Курс для профессионалов
• Поколение Python: ООП
• Поколение Python: Курс для самураев

Зачем это, если Stepik уже проверяет решения?

Встроенный чекер Stepik даёт «зачёт / не зачёт» — и только после сабмита. Вот чем грейдер отличается от двух реальных альтернатив:

Как проект дошёл до текущего состояния — в HISTORY.md: происхождение, одиннадцать релизов, эволюция метрик.

Основные возможности

• ✅ Запуск решений против наборов тест-кейсов (tests/N + tests/N.clue)
• 📋 Автоматическое извлечение тест-кейсов — из HTML-таблицы задачи, из ZIP-архива по ссылке, плюс подсказка при тестах на GitHub
• 📊 Сравнение нескольких решений одной задачи в таблице
• 🚀 Subprocess-бенчмарк с замером времени и памяти (режим 3)
• ⚡ Timeit-микробенчмарк через subprocess (режим 4)
• ⚖️ Вердикты AC / WA / TLE / RE по каждому кейсу: цветной вывод через rich и diff «ожидалось / получено» при WA
• 🌐 Локальный веб-интерфейс (--serve, http://127.0.0.1:8000) и интеграция с VS Code / PyCharm
• 🖥 GUI-лаунчер веб-интерфейса без командной строки (stepik-grader-gui) — на Windows ярлык без консольного окна
• 🧩 pytest-плагин (pytest --grader-mode), кэш результатов и --watch (extra [watch]); Playwright e2e-смоук фронтенда с регрессией на XSS (extra [e2e], см. CONTRIBUTING.md § E2E-тесты)
• 📚 Локальный глоссарий (объём — в бейдже Glossary выше): функции, исключения и конструкции, детектор недостающих терминов, deep-link из error cards
• 🎓 Правила PEP 8 и раздел «Подучить» — частые ошибки из истории прогонов с затуханием (--insights / --lint)
• 📈 Локальная статистика прогонов (--stats) и SQLite-история (--history) — без сети
• 🤖 AI-объяснение падений WA/RE (--ai-hints) — opt-in, на своём ключе (BYOK: локальная ollama или облако), с заземлением на карточки глоссария; без настройки и явного согласия ничего в сеть не уходит
• 🔒 Опциональная OS-песочница исполнения решений (--sandbox)
• 🔍 Диагностика окружения и авторизация через Stepik API

Только в вебе — CLI-аналога нет. «Песочница» (запуск кода со своим stdin, не путать с OS-изоляцией --sandbox), пошаговый трейс с memory-graph, редактор решения с сохранением, «Отправить в Stepik», а также интерактивные «Глоссарий», «Правила (PEP)», «Подучить» и «Прогресс» — в терминале от них есть только сводки --insights/--lint и экспорт --export-progress. Обзор разделов — docs/use/web-interface.md.

Разбор по модулям и слоям — в docs/dev/architecture.md.

Как это выглядит (--serve)

Проверка папки решений (режим 2)	Офлайн-глоссарий Python

Быстрый старт

Установить — pipx install stepik-python-grader (см. первый экран) или другие способы. Запустить интерактивное меню:

python -m stepik_grader       # надёжный способ (работает всегда)
stepik-grader                 # если команда в PATH

Или веб-интерфейс (только localhost) — те же режимы 1–4 в браузере плюс разделы, которых в CLI нет (см. § Основные возможности):

stepik-grader --serve         # http://127.0.0.1:8000 (другой порт — --port)

Совсем без командной строки — окно-лаунчер веб-интерфейса: выбор варианта запуска («Простой сервер» / «Сервер с изоляцией --sandbox»), порта (с проверкой «занят») и рабочей папки, кнопки «Запустить»/«Остановить» и авто-открытие браузера:

stepik-grader-gui                  # на Windows — ярлык без консольного окна
python -m stepik_grader.launcher   # то же окно из терминала

Или проверить одно решение без интерактива:

stepik-grader --mode 1 --file task.py

Полная установка (из исходников, venv, Windows-заметки, настройка OAuth) — в docs/use/installation.md. Пошаговый первый пример, режимы 1–4, CLI-флаги, скачивание задач и форматы тестов — в docs/use/grader-workflow.md.

Документация

База знаний — в docs/, разложена по четырём направлениям:

Рядом с кодом: CHANGELOG.md — что изменилось в релизах, CONTRIBUTING.md — как внести вклад, CLAUDE.md — инварианты ядра для агентов.

Два правила этой документации: одна тема — один файл (остальные ссылаются, а не копируют) и в активном документе нет журнала работ (что сделано — в CHANGELOG, что предстоит — в Issues). Подробнее — docs/README.md.

Безопасность (кратко)

По умолчанию решения запускаются БЕЗ полноценного sandbox на уровне ОС. Есть таймаут выполнения (всегда) и best-effort лимит памяти на POSIX; изоляции ФС/сети по умолчанию нет. Опциональная OS-изоляция включается флагом --sandbox (core/sandbox/, три backend'а) — и в CLI (режимы 1–4), и в web (--serve --sandbox; пошаговый трейс под ней недоступен). Без --sandbox запускай только доверенные решения (свои или скачанные из Stepik as-is). Подробная threat model — в docs/use/configuration.md § Ограничения и безопасность. Как сообщить об уязвимости — SECURITY.md.

Прозрачность и доверие

• ✅ Автотесты на каждый PR (pytest), CI-матрица на 3 ОС × Python 3.12/3.13 (+3.14 экспериментально) — живые бейджи покрытия single-OS и cross-OS в шапке.
• 🧠 Строгий mypy (disallow_untyped_defs, warn_return_any, …) + ruff (lint + format) в pre-commit и CI — типы и стиль проверяются на каждый PR.
• 🔐 Приватный репорт уязвимостей (GitHub Private Vulnerability Reporting) + документированная threat model — SECURITY.md.
• 📦 Публикация на PyPI через OIDC trusted publishing — без хранимого токена в секретах; релизный dist собирается один раз в CI.
• 📜 MIT, открытая история изменений — CHANGELOG.md.

Первый вклад за 15 минут

Новичок? Возьмите issue с меткой good first issue — это задачи с понятным объёмом и ссылками на канон. Пошаговый онбординг (форк → ветка от main → локальные гейты pytest/ruff/mypy → PR по Conventional Commits) — в CONTRIBUTING.md § Первый вклад за 15 минут. Вопросы, идеи и «покажу своё» — в Discussions.

Python версия

Python 3.12+ (3.14 — экспериментальная).

Лицензия

MIT © Artem Markitanov (ArtVsMark).