Janettora

Простой телеграм бот для тренировки словарного запаса английского языка, написанный на фреймворке Aiogram. Проект использует реляционную СУБД PostgreSQL в качестве основной базы данных, нереляционную СУБД Redis для кэширования, библиотечку loguru для логирования. Программа Docker'изирована. Используемый линтер и форматер кода - ruff.

К боту Janettora встроены парсер сайта worderdict.ru и некоторые маленькие CLI утилиты для управления базами данных.

Documentation in English

Карта контента

• Janettora
  • Карта контента
  • Быстрый старт
    • Установка
    • Запуск в режиме локальной разработки
    • Запуск в продакшен режиме через Docker
  • Функционал бота
  • Скриншоты
  • Описание настроек
    • Runtime настройки
    • Основная PostgreSQL база данных
    • Основная Redis база данных
    • Исходная PostgreSQL база данных для Docker
    • Исходная SQLite база данных для Docker
  • Лицензия

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

Установка

git clone https://github.com/waflawe/Janettora.git  
cd Janettora/

После успешной установки вам нужно определиться с используемой базой данных слов. Она указывается программе по-разному в зависимости от режима запуска.

Запуск в режиме локальной разработки

1. Установка зависимостей:

pip install -r requirements/dev.txt

2. Создаем файл .env и заполняем его по примеру файла .env.template. Описание настроек тут.
3. Для работы бота ему нужна база данных со словами, содержащая данные об их англоязычной, русскоязычной версиях и частях речи. Чтобы ее собрать для режима локальной разработки, у вас есть два предоставляемых программой пути:
   • Быстрый путь: вы можете воспользоваться небольшой, однако уже готовой базой в репозитории с именем test_words.db. Она используется по умолчанию, если вы не переопределили в настройках (.env) переменную SQLITE_WORDS_DB_TO_DOCKER_NAME. Для ее инициализации, введите команду python database/cli/migrate_words.py в папке проекта.
   • Долгий алтернативный путь: вы можете воспользоваться прикрепленным к боту парсером сайта worderdict.ru, который соберет актуальные данные (пока его, конечно, не забанят на вашем IP) о словах в базу. Для этого запустите команду python parser/parser.py из папки проекта.
4. Если Redis используется локальный, то запускаем отдельно два окна терминала. Иначе пропустите этот пункт. В первом запускаем Redis:

redis-server

5. Во втором запускаем проект:

python bot/bot.py

6. После продолжительного ожидания, заходим в бота, чей токен мы использовали в файле .env.
7. Наслаждаемся.

Запуск в продакшен-режиме через Docker

1. Создаем файл .env.docker и заполняем его по примеру файла .env.docker.template. Описание настроек тут.
2. Для работы бота ему нужна база данных со словами, содержащая данные об их англоязычной, русскоязычной версиях и частях речи. Чтобы ее собрать для продакшен-режима через Docker, у вас есть два предоставляемых программой пути:
   • Быстрейший путь: ничего не делать. Тогда вы воспользуетесь автоматически небольшой, однако уже готовой базой в репозитории с именем test_words.db. Она используется по умолчанию, если вы не переопределили в настройках (файл .env.docker) переменную SQLITE_WORDS_DB_TO_DOCKER_NAME.
   • Долгий путь: вы можете воспользоваться своей PostgreSQL базой слов, если в ней табличка со словами в правильном формате (это, например, может быть ранее используемая ботом база в режиме Запуск в режиме локальной разработки, тогда для вас настройки секции Исходная PostgreSQL база данных для Docker будут соответственно совпадать с настройками секции Основная PostgreSQL база. Это, впринципе, самый частый случай). Если у вас есть такая база, вы можете создать файл .env, если у вас еще он не создан, настроить по примеру .env.template (описание настроек тут) и, после установления правильных значений секции настроек Исходная PostgreSQL база данных для Docker, запустить команду python database/cli/collect_words.py. Команда сгенерирует SQLite базу с именем типа collect_words_{GENERATION_DATE}.db в корне проекта. Затем впишите имя сгенерированной базы в переменную SQLITE_WORDS_DB_TO_DOCKER_NAME в файле .env.docker.
3. Поднимаем Docker-compose:

docker-compose up

4. После продолжительного ожидания, заходим в бота, чей токен мы использовали в файле .env.docker.
5. Наслаждаемся.

Функционал бота

В Janettora вы можете генерировать telegram-викторины, предлагающие угадать перевод английского слова на русский язык. При этом, настройка этих викторин довольно гибкая.

Janettora позволяет менять настройки своего аккаунта, такие как количество вариантов ответа в викторинах (quiz_answers_count) и части речи генерируемых в викторинах слов (words_part_of_speech). При изменении настройки quiz_answers_count дополнительно меняется время, дающееся на выполнение викторины. При использовании слов конретной части речи в настройке words_part_of_speech не только генерируемое слово на английском имеет установленную часть речи, но и все варианты ответа в викторине.

Так же Janettora умеет вести статистику пользователей, такую как общее число пройденных викторин, данные об успешности их прохождения (число верных/неверных ответов, их отношение), статистику о частоте генераций викторин с определенными настройками (например, сколько раз были сгенерированы викторины, с quiz_answers_count равном 3 и words_part_of_speech равном Фразы).

Последней функцией бота Janettora является топ всех пользователей. По умолчанию, топ состоит из 10 лучших пользователей по отношению правильных ответов к неправильным. Минимальное количество пройденных викторин для попадания в топ - 100 (все эти цифры можно менять в файле config.py).

Скриншоты

1. 
2. 
3. 
4. 
5. 
6. 

Описание настроек

Runtime-настройки

• TELEGRAM_BOT_TOKEN
  Обязательная для изменения настройка с телеграм токеном бота. Как его получить описано здесь.

• DEBUG
  Необязательная для изменения настройка, сигнализирующая важность ведения DEBUG логов (которые, кстати, ведутся в папке .logs/). 1 - True, 0 - False.

Основная PostgreSQL база данных

• DB_NAME
  Не требующая изменения настройка, обозначающая имя основной PostgreSQL базы данных для бота.

• DB_USER
  Имя пользователя базы.

• DB_PASSWORD
  Пароль пользователя базы.

• DB_HOST
  IP Адрес базы.

• DB_PORT
  Порт на DB_HOST с базой.

Основная Redis база данных

• REDIS_HOST
  IP Адрес базы.

• REDIS_PORT
  Порт на REDIS_HOST с базой.

• REDIS_DB_NUMBER
  Номер базы. 0+

Исходная PostgreSQL база данных для Docker

Настройки для CLI утилиты database/cli/collect_words.py. Чаще всего совпадают соответственно с настройками раздела Основная PostgreSQL база данных, но не всегда.

• COLLECT_WORDS_DB_NAME
  Имя базы.

• COLLECT_WORDS_DB_USER
  Имя пользователя базы.

• COLLECT_WORDS_DB_PASSWORD
  Пароль пользователя базы.

• COLLECT_WORDS_DB_HOST
  IP Адрес базы.

• COLLECT_WORDS_DB_PORT
  Порт на DB_HOST с базой.

Исходная SQLite база данных для Docker

• SQLITE_WORDS_DB_TO_DOCKER_NAME
  Имя SQLite базы данных в папке проекта с табличкой слов для Docker контейнера. По умолчанию используется база test_words.db, предоставляемая самим проектом.

Лицензия

Этот проект лицензирован MIT лицензией.