190 lines
7.4 KiB
Markdown
190 lines
7.4 KiB
Markdown
# Discord Bot
|
||
|
||
Discord-бот для Магнитогорска. Команды погоды, новостей, котиков и утреннего дайджеста.
|
||
|
||
## Установка
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
## Запуск
|
||
|
||
```bash
|
||
python bot.py
|
||
```
|
||
|
||
Введите номер команды в терминале или `!команда` в Discord.
|
||
|
||
## Настройка
|
||
|
||
1. Скопируйте `.env.example` в `.env`:
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
2. Вставьте токен бота в `.env`:
|
||
```env
|
||
DISCORD_TOKEN=ваш_токен
|
||
```
|
||
|
||
Токен получите на [Discord Developer Portal](https://discord.com/developers/applications).
|
||
|
||
## Команды Discord
|
||
|
||
| Команда | Описание |
|
||
|---------|----------|
|
||
| `!pogoda` | Прогноз погоды для Магнитогорска |
|
||
| `!news` | Топ-5 свежих статей по AI с Habr |
|
||
| `!morning` | Погода + топ-5 статей + топ-5 новостей + котик (утренний дайджест) |
|
||
| `!cat` | Случайный котик |
|
||
| `!msg <текст>` | Повторить текст в чате |
|
||
|
||
## Команды терминала
|
||
|
||
| Номер | Команда | Описание |
|
||
|-------|---------|----------|
|
||
| 1 | `news` | Топ-5 статей + топ-5 новостей с Habr |
|
||
| 2 | `pogoda` | Прогноз погоды для Магнитогорска |
|
||
| 3 | `morning` | Погода + топ-5 статей + топ-5 новостей + котик |
|
||
| 4 | `cat` | Вывести URL случайного котика |
|
||
| 0 | `stop` | Остановка бота |
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
bot.py # Точка входа, инициализация бота, console_input()
|
||
commands/ # Discord команды (cogs)
|
||
__init__.py # ALL_COMMANDS — явные импорты
|
||
pogoda.py # !pogoda — погода с retry + fallback
|
||
news.py # !news — новости с Habr
|
||
cat.py # !cat — случайный котик
|
||
morning.py # !morning — утренний дайджест
|
||
console_commands/ # Консольные команды
|
||
__init__.py # ALL_CONSOLE_COMMANDS — явные импорты
|
||
stop.py # stop — остановка бота
|
||
news.py # news — новости с Habr
|
||
pogoda.py # pogoda — погода в терминале
|
||
morning.py # morning — утренний дайджест в терминале
|
||
cat.py # cat — вывод URL котика
|
||
utils/ # Утилиты (API-клиенты, конвертации)
|
||
pogoda.py # fetch_weather(), fetch_open_meteo(), wmo_to_russian(), translate_weather(), pressure_to_mmhg()
|
||
news.py # fetch_rss(), format_articles(), truncate_title(), parse_date()
|
||
cat.py # fetch_cat()
|
||
tests/ # pytest-тесты
|
||
test_pogoda.py # translate_weather, pressure_to_mmhg, wmo_to_russian
|
||
test_fetch_cat.py # fetch_cat
|
||
test_fetch_rss.py # fetch_rss
|
||
test_fetch_weather.py # fetch_weather, fetch_open_meteo
|
||
test_format_articles.py # truncate_title, parse_date, format_articles
|
||
test_commands_pogoda.py # Pogoda cog
|
||
ISSUES.md # Задачи и баг-трекер проекта
|
||
pytest.ini # Конфигурация pytest
|
||
```
|
||
|
||
### Добавление Discord команды
|
||
|
||
1. Создать файл `commands/имя.py` с классом, наследующим `commands.Cog`
|
||
2. Добавить импорт в `commands/__init__.py`
|
||
3. Добавить класс в `ALL_COMMANDS`
|
||
|
||
### Добавление консольной команды
|
||
|
||
1. Создать файл `console_commands/имя.py` с функцией `func(stop_event, bot)`
|
||
2. Добавить импорт в `console_commands/__init__.py`
|
||
3. Добавить функцию в `ALL_CONSOLE_COMMANDS`
|
||
|
||
## Запуск тестов
|
||
|
||
```bash
|
||
python -m pytest tests/ -v
|
||
```
|
||
|
||
### Структура тестов
|
||
|
||
| Файл | Что тестирует | Кол-во |
|
||
|------|---------------|--------|
|
||
| `test_pogoda.py` | `translate_weather()`, `pressure_to_mmhg()`, `wmo_to_russian()` | 93 |
|
||
| `test_fetch_cat.py` | `fetch_cat()` | 10 |
|
||
| `test_fetch_rss.py` | `fetch_rss()` | 20 |
|
||
| `test_fetch_weather.py` | `fetch_weather()`, `fetch_open_meteo()` | 20 |
|
||
| `test_format_articles.py` | `truncate_title()`, `parse_date()`, `format_articles()` | 24 |
|
||
| `test_commands_pogoda.py` | `Pogoda` cog, команда `!pogoda` | 13 |
|
||
|
||
**Итого: 180 тестов.**
|
||
|
||
## API и внешние сервисы
|
||
|
||
### Погода (!pogoda, !morning)
|
||
- **Основной**: `wttr.in/Magnitogorsk` (бесплатный, без ключа)
|
||
- **Fallback**: `api.open-meteo.com` (бесплатный, без ключа)
|
||
- Retry: 3 попытки с экспоненциальной задержкой при SSL/Connection/Timeout ошибках
|
||
- Fallback срабатывает автоматически при неуспешных попытках
|
||
- WMO weather codes → русский перевод в `wmo_to_russian()`
|
||
|
||
### Конвертации
|
||
- Давление: hPa → мм рт. ст. (`* 0.750062`)
|
||
- Ветер: км/ч → м/с (`/ 3.6`)
|
||
- Погодные описания: английский → русский (`translate_weather()`)
|
||
|
||
### Новости (!news, !morning)
|
||
- **Articles**: `https://habr.com/ru/rss/hubs/artificial_intelligence/articles/top/daily/?fl=ru`
|
||
- **News**: `https://habr.com/ru/rss/hubs/artificial_intelligence/news/top/daily/?fl=ru`
|
||
- Парсинг RSS 2.0 и Atom форматов
|
||
- Извлечение ссылок из `<guid isPermaLink="true">` и авторов из `<dc:creator>`
|
||
- Формат вывода: заголовок → дата → ссылка
|
||
|
||
### Котики (!cat, !morning)
|
||
- **API**: `https://api.thecatapi.com/v1/images/search`
|
||
- Картинка встраивается в Discord Embed
|
||
|
||
## Структура данных погоды
|
||
|
||
Команда `!pogoda` возвращает:
|
||
|
||
```
|
||
Температура: X°C (ощущается как Y°C)
|
||
Описание: Z
|
||
Влажность: X%
|
||
Ветер: X м/с
|
||
Давление: X мм рт. ст.
|
||
```
|
||
|
||
## Формат дат
|
||
|
||
Даты форматируются как `дд.мм.гггг` через `datetime.strptime` с форматом `%a, %d %b %Y %H:%M:%S %z`.
|
||
|
||
## Конфигурация
|
||
|
||
| Переменная | Описание | Где взять |
|
||
|------------|----------|-----------|
|
||
| `DISCORD_TOKEN` | Токен бота | [Discord Developer Portal](https://discord.com/developers/applications) |
|
||
|
||
## Зависимости
|
||
|
||
```txt
|
||
discord.py>=2.3.2
|
||
python-dotenv>=1.0.0
|
||
requests>=2.31.0
|
||
pytest>=7.4.0
|
||
pytest-asyncio>=0.21.0
|
||
```
|
||
|
||
## Безопасность
|
||
|
||
- `.env` в `.gitignore` — токен никогда не должен попадать в репозиторий
|
||
- Используйте `.env.example` как шаблон
|
||
|
||
## Формат новостей
|
||
|
||
Каждая новость выводится в формате:
|
||
|
||
```
|
||
Заголовок статьи
|
||
дд.мм.гггг https://habr.com/ru/articles/...
|
||
```
|
||
|
||
Заголовки обрезаются до 60 символов с суффиксом `...`.
|
||
|
||
Ссылки отображаются без `<>` и `https://` префикса для предотвращения embed-превью в Discord.
|