Factstorm Bot

Factstorm Bot — это Telegram‑бот, который присылает пользователям интересные и порой шокирующие факты по выбранным категориям. Бот реализован на aiogram и использует несколько открытых API для получения свежей информации. Благодаря асинхронной обработке и кэшированию ответы приходят быстро, а архитектура проекта упрощает расширение и поддержку.

Особенности

• Выбор категории фактов через инлайн‑кнопки.
• Поддержка нескольких источников данных (Useless Facts, Cat Facts, исторические события и картинки Unsplash).
• Асинхронные запросы с помощью aiohttp и кэширование с помощью aiocache.
• Чистая структура проекта: отдельные модули для обработчиков, сервисов и утилит.
• Лёгкая настройка через переменные окружения (.env).
• Готовый шаблон GitHub Actions для проверки качества кода (flake8) и запуска тестов.

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

1. Склонируйте репозиторий и перейдите в директорию проекта:

   git clone https://github.com/your_username/factstorm-bot.git
   cd factstorm-bot

2. Создайте и заполните файл .env по примеру .env.example:

   BOT_TOKEN=ваш_telegram_бот_токен
   UNSPLASH_KEY=ваш_ключ_от_unsplash

3. Создайте виртуальное окружение (рекомендуется) и установите зависимости:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

4. Запустите бота:

   python bot.py

После запуска перейдите в Telegram, найдите вашего бота и отправьте команду /start. Бот предложит выбрать категорию и пришлёт интересный факт.

Пример использования

/start
👋 Привет! Выбери категорию фактов:
• Наука
• Животные
• История

После выбора «Животные» бот отправит случайный факт о животных и, если доступна картинка, прикрепит фотографию.

Структура проекта

• bot.py — точка входа приложения, инициализирует бота и регистрирует обработчики.
• handlers/ — модули с логикой обработки команд и нажатий на инлайн‑кнопки.
• services/ — работа с внешними API и кэшированием данных.
• utils/ — вспомогательные функции (например, throttle).
• .env.example — образец переменных окружения.
• requirements.txt — список зависимостей.
• .github/workflows/ — конфигурация CI для проверки кода.
• tests/ — заглушки для тестов (можно расширять).

Поддержка и развитие

Пока бот умеет присылать факты по трём категориям, но вы легко можете добавить новые источники: просто создайте новый метод в модуле services/facts_service.py и добавьте кнопку в обработчик категорий. Pull requests и предложения приветствуются!