- Python 99.6%
- Nix 0.4%
| nhm21bot | ||
| tests | ||
| .env.example | ||
| .envrc | ||
| .gitignore | ||
| .python-version | ||
| flake.lock | ||
| flake.nix | ||
| LICENSE | ||
| pyproject.toml | ||
| README.md | ||
| uv.lock | ||
nhmt21bot
Telegram-бот для автоматического парсинга и рассылки изменений в расписании (замен) с официального сайта НХМТ. Бот парсит страницы замен СПО и НПО, нормализует номера аудиторий и распределяет их по корпусам колледжа (ЦОПП, Кванториум, Главный корпус и т.д.).
Стек технологий
- Python 3.13+
- aiogram 3.x для работы с Telegram Bot API
- BeautifulSoup4 / lxml для парсинга HTML
- uv для быстрого управления зависимостями
- Nix для воспроизводимого окружения (опционально)
Установка и локальный запуск
-
Склонируйте репозиторий:
git clone https://github.com/rus07tam/nhmt21bot.git cd nhmt21bot -
Настройте конфигурацию:
cp .env.example .envЗатем откройте файл
.envи укажитеBOT_TOKEN— токен, полученный от @BotFather. -
Установите зависимости проекта с помощью uv:
uv sync -
Запустите бота:
uv run python -m nhm21bot
Альтернативный запуск через Nix
Проект поддерживает работу через Nix Flakes. Для входа в настроенное окружение со всеми зависимостями выполните:
nix develop
Либо используйте direnv (конфигурация .envrc уже есть в репозитории).
Конфигурация (.env)
| Переменная | Описание | Значение по умолчанию |
|---|---|---|
BOT_TOKEN |
Токен Telegram-бота | (обязательно) |
BASE_URL |
Базовый URL страницы замен | https://zamena.nhmt.ru/zamena |
SUFFIX_SPO |
Относительный путь для замен СПО | /spo.php?a=0 |
SUFFIX_NPO |
Относительный путь для замен НПО | /npo.php?a=0 |
ADMIN_ID |
Telegram ID администратора | None |
SYNC_CRON |
Интервал проверки сайта в секундах | 300 |
CHATS_DB_FILE |
Путь к SQLite-базе чатов | data/chats.sqlite3 |
Практика
Бот разбирает раздел практики из таблицы замен: УП (учебная практика) и ПП (производственная практика). Для каждой записи сохраняются группа, период, преподаватели и кабинет. Практика показывается в карточках групп, inline и уведомлениях об изменениях; для преподавателей и кабинетов она выводится в подписи к изображению. Для практики также рассчитывается, через сколько дней она закончится.
Если в таблице замен указано короткое имя группы (31 ИС), бот восстанавливает
полный код (24-ИО-028) из nhm21bot/group_directory.json. Это важно для
подписок и уведомлений, которые хранятся по полному коду группы.
Хранилище чатов и миграция
Настройки чатов (подписки, напоминания, закрепление) хранятся в SQLite:
data/chats.sqlite3. Легаси-файл data/chats.json при первом запуске
автоматически мигрируется в SQLite и больше не изменяется.
Миграция безопасная: сначала создаётся временная БД, проверяются
PRAGMA integrity_check, PRAGMA foreign_key_check, количество строк и
контрольный хэш содержимого, и только потом файл атомарно заменяется.
Перед миграцией создаётся копия JSON в data/backups/. При любой ошибке
исходный JSON и существующая БД не изменяются.
# Проверить данные и показать отчёт, ничего не записывая
python -m nhm21bot.cli chats migrate --dry-run
# Выполнить миграцию (бот должен быть остановлен)
python -m nhm21bot.cli chats migrate
# Сверить JSON и SQLite (сразу после миграции)
python -m nhm21bot.cli chats verify
# Экспортировать SQLite обратно в старый формат (для отката)
python -m nhm21bot.cli chats export-json --output data/chats.rollback.json
После запуска бота SQLite начнёт принимать новые изменения, поэтому verify
будет ожидаемо показывать расхождения с замороженным chats.json.
Для отката на старую версию: остановить бота, при необходимости выполнить
export-json, заменить data/chats.json результатом экспорта и запустить
старую версию. Перед откатом всегда сохраняйте копию текущей SQLite-базы.
Отчёты об ошибках
Если задан ADMIN_ID, бот отправляет администратору в ЛС отчёты о runtime-ошибках:
- необработанные исключения aiogram-хендлеров;
- ошибки фоновых циклов синхронизации и напоминаний;
- необработанные исключения
asyncio-задач; - записи уровня
ERROR/CRITICALиз логов бота.
Длинные traceback автоматически делятся на несколько сообщений с учётом лимита
Telegram в 4096 символов. Если текст слишком большой, полный отчёт
отправляется файлом bot-error.txt. Одинаковые ошибки в пределах
ERROR_REPORT_COOLDOWN секунд не дублируются.
Настройки:
| Переменная | Описание | По умолчанию |
|---|---|---|
ERROR_REPORTING_ENABLED |
Включить отправку ошибок админу | true |
ERROR_REPORT_COOLDOWN |
Подавление повторов, секунды | 60 |
ERROR_REPORT_MAX_CHUNKS |
Максимум текстовых частей до отправки файла | 8 |
Для работы отчётов должен быть указан ADMIN_ID. Если админ заблокировал бота,
отправка отключается до перезапуска.
Структура проекта
nhm21bot/— исходный код бота.bot/— хэндлеры и роутеры aiogram.db/— SQLite-слой, схема и миграция чатов из JSON.cabinets.py— группировка кабинетов с учётом корпуса.practice.py— модель практики, привязка к группам и расчёт оставшихся дней.error_reporting.py— отправка runtime-ошибок администратору.parser/— логика сбора данных с сайта НХМТ.render/— генерация изображений или PDF-файлов с расписанием.settings.py— настройки приложения (pydantic-settings).sync.py— фоновая синхронизация и проверка обновлений.cli.py— команды миграции, проверки и экспорта чатов.
tests/— автотесты (pytest).data/— директория для сохранения временных файлов (создается автоматически).
Лицензия
Проект распространяется под лицензией The Unlicense.