shablbot 2.0.4

Бот написанный на Python для социальной сети Вконтакте, работающий через VkBotLongPull

---

🤖 Бот написанный на Python для социальной сети Вконтакте, работающий через VkBotLongPull.

💭 О проекте

Данный проект разрабатывался с целью облегчить создание ботов для людей, которые мало/плохо знакомы с программированием. Бот устроен таким образом, что Вам нужно написать минимальное количество кода, чтобы добавить новый функционал. В последствии бот будет дорабатываться и развиваться.

🎈 Установка

Можете воспользоваться командой pip:

 pip install shablbot

Или же использовать poetry:

 poetry add shablbot

:dizzy: Инициализация

Чтобы начать работу с ботом необходимо выполнить инициализацию компонентов бота:

Для этого нужно выполнить команду:

windows

 C:\shablbot> py -m shablbot --init

linux

 blackgard@bar:~/shablbot$ python3 -m shablbot --init

После чего будет в папке, откуда был вызван скрипт будет созданы каталоги с следующей структурой:

📦*yourfolder*
 ┣ 📂commands
 ┃  ┣ 📂private
 ┃  ┃  ┗ 🐍 show_id_active_chats.py
 ┃  ┣ 📂public
 ┃  ┃  ┣ 🐍 chat_bot_off.py
 ┃  ┃  ┣ 🐍 chat_bot_on.py
 ┃  ┃  ┗ 🐍 chat_show_statistics.py
 ┣ 📂keyboards
 ┃  ┣ 📜 clear.json
 ┃  ┗ 📜 default.json
 ┣ 📂modules
 ┃ ┗ 📂games
 ┃    ┗ 🐍 flip_and_roll.py
 ┣ 📂phrases
 ┃  ┣ 📜 _default.json
 ┃  ┣ 📜 bye.json
 ┃  ┗ 📜 hello.json
 ┣ 📂settings
 ┃  ┣ 🐍 settings_model.py
 ┃  ┗ 🐍 settings.py
 ┗ 🐍 manager.py

Более подробно про каждый из каталогов будет рассказано далее

После этого можно перейти к настройке бота.

⏳ Стартовая настройка

Настройка бота производится с помощью редактирования файла settings.py, находящегося в папке settings, созданной на шаге выше.

Обязательные поля для работы бота:

1. TOKEN - ключ доступа к сообществу вконтакте, ключ должен быть с правами к сообщениям сообщества. Как получить токен для бота?

  TOKEN = os.getenv("TOKEN") # "1234566789908798689764867293876243987" (str)

2. BOT_CHAT_ID - id страницы вконтакте сообщества, от лица которого будет работать бот.

  BOT_CHAT_ID = os.getenv("BOT_CHAT_ID") # 123456789 (int)

3. DEFAULT_REACTION_TEMPLATES - слова на которые бот будет всегда как-либо реагировать.

  DEFAULT_REACTION_TEMPLATES = (r"бот",) # (tuple)

4. ADMIN_ID - id страницы вконтакте человека, от лица которого будет происходить администрирование бота.

  ADMIN_ID = os.getenv("ADMIN_ID") # 123456789 (int)

Остальные параметры для начального запуска бота менять не нужно.

🔔 Советую для хранения токена и id-ов использовать .env файл. К примеру используйте python-dotenv.

🚀 Запуск бота

Для запуска бота мы используем файл manager.py, созданный на первом шаге.

windows

  C:\shablbot> py manager.py --run

linux

  blackgard@bar:~/shablbot$ python3 manager.py --run

Если вы все правильно сделали, то в консоли увидите следующее сообщение:

  2099-99-99 at -1:99:99 | INFO | ------- Бот запущен / Bot is runing -------

:card_file_box: Модульность бота

1. Модуль команды
2. Модуль клавиатуры
3. Модуль пользовательских модулей
4. Модуль фраз
5. Модуль настроек

То, как бот обрабатывает команды и сообщения от Вас спрятано. По этому Вам доступны 5 типов модулей, для расширения и настройки бота:

commands

Модуль отвечающий за команды управления ботом. Нужен для администрирования. Делятся на два типа:

1. private - доступные только администратору бота
2. public - доступные всем пользователям

:bell: Команды нужно подключать в настройках бота. Переменная ACTIVE_COMMANDS.

Для добавления новой команды вам нужно создай файл в папке private/public с *название_команды*.py.

В созданном файле нужно создать переменную command_settings с следующей структурой:

command_settings = {
    # Код команды. Должен быть уникальным.
    "code": "bot_off",
    # Название команды. Публичная переменная.
    "name": "Выключить бота",
    # Слова, на которые бот будет реагировать.
    # Может быть регулярным выражением.
    "templates": ["выкл бот", "бот выкл"],
    # Ответ бота, на результат выполненной команды.
    "answer": "Теперь бот не читает сообщения в чате",
    # Описание команды. Публичная переменная.
    "description": "Команда для выключения бота в чате (Внутри чата)",
    # Метод обработки templates. Если normal, то сравнивает как слова.
    # Если regular, то сравнивает как регулярные выражения.
    "method": "normal",
    # Какие переменные нужны для выполнения команды.
    # Доступные значения = processed_chat, chats, commands;
    "need": ["processed_chat",],
    # Входная точка для выполнения команды.
    # Может быть любой функцией.
    "entry_point": command
}

Функция выключения бота в чате:

def command(processed_chat: Chat) -> None:
    processed_chat.turn_off()

keyboards

Модуль отвечающий за варианты клавиатуры бота. Нужен для настройки сообщений, если вы хотите использовать клавиатуру в сообщениях бота.

Про клавиатуру Vk подробнее читать тут

:bell: Клавиатуры нужно подключать в настройках бота. Переменная KEYBOARDS.

:warning: Обязательно для работы бота нужны, "clear.json" и "default.json"

modules

Модуль отвечающий за пользовательские модули для бота. К таким модулям можно отнести:

• Игры
• Утилиты (Погода, время, конвертирование валюты)

:bell: Модули нужно подключать в настройках бота. Переменная ACTIVE_MODULES.

:warning: Данный блок еще не совершенен, т.к. всегда требует возврата строки как ответа, в будущем будет как ответ отправлять все типы данных

Для создания модуля Вам необходимо создать файл с названием модуля и добавить туда переменную settings с следующей структурой:

settings = {
    # Название модуля.
    "name": "Flip and roll game",
    # Версия модуля.
    "version": "1.0.0",
    # Автор модуля.
    "author": "Narteno",
    # Дата создания модуля.
    "date_created": "12.11.2019",
    # Входная точка обработки модуля.
    "entry_point": activate_module,
    # Обрабатывающие запросы функции модуля.
    # В себя включают название функции, описание
    # и входную точку. Нужен для более гибкой настройки.
    "func": {
        "roll": {"name": "roll", "description": "", "entry_point": roll},
        "flip": {"name": "flip", "description": "", "entry_point": flip},
    },
    # Фразы для реакции. Разделяются по функциям модуля.
    "templates": {"flip": [r"флип"], "roll": [r"ролл"]},
}

Входная точка модуля должна иметь такую структуру, но не ограничена этим:

def activate_module(func) -> str:
    """Входная точка модуля"""
    active_func = settings["func"].get(func)["entry_point"]

    # Если переменная ответа будет в значении None.
    # То бот не отправит сообщение пользователю.
    answer_module = None
    if active_func:
        answer_module = active_func()

    return answer_module

Подробнее о структуре кастомных модулей смотрите тут flip_and_roll.py

phrases

Модуль отвечающий за фразы, на которые бот реагирует. Содержит в себе файлы .json формата.

:bell: Все фразы из папки подгружаются автоматически. Вы можете исключить ненужные фразы используя в настройках переменную EXCLUDED_PHRASES.

json файл должен содержать следующую структуру:

:warning: Значения с пометкой "_comment" в реальном файле не должны пристутствовать.

{
    "#group_comment#":"Стандартная группа. нельзя удалять"
    "group": "default",

    "#words_comment#":"Список слов входящих в группу"
    "words": {
        "#main_comment#":"Название слова, на которое бот реагирует. Может содержать любые символы. Для файла _default.json 'main' обязательное системное значение"
        "main": {
            "#templates_comment#":"Фразы для реакции"
            "templates": [ "бот" ],
            "#answer_comment#":"Варианты ответа разбитые по редкости"
            "answer": {
                "common": ["Я бот"],
                "uncommon": ["Я почти бот"],
                "rare": ["Я точно бот"],
                "legendary": ["А может быть это ты бот?"]
            },
            "#templates_comment#":"Ключ клавиатуры, которую нужно отправить для данного слова."
            "keyboard": "default"
        },
    }
}

settings

Модуль отвечающий за настройки бота. Все настройки производятся в файле settings.py. В файле для каждой переменной имеются комментарии, поясняющие, что в них хранится.

💻 Пример работы

Бот по имени "Ходор" - клик-клик (вк)

🧰 CLI Shablbot

Для бота разработано CLI. Доступные методы:

(env) C:\Users\user\Desktop\shablbot>py manager.py --help
usage: python manage.py  [-h] [-r] [-i] [-c]

🤖 Бот написанный на Python для социальной сети Вконтакте, работающий через VkBotLongPull

optional arguments:
  -h, --help       show this help message and exit
  -r, --run-bot    Запустить сервер для работы бота
  -i, --init       Инициировать каталоги для работы бота [ "commands", "keyboards", "modules", "phrases", "settings", "manager.py" ]
  -c, --check-bot  Проверить работоспособность бота без запуска сервера

(c) Alex Drachenin

Для старта работы с ботом вы можете воспользоваться методом "--init" таким образом:

(env) C:\Users\user\Desktop\shablbot>py -m shablbot --init

Каталог 'commands' инициирован!
Каталог 'keyboards' инициирован!
Каталог 'modules' инициирован!
Каталог 'phrases' инициирован!
Каталог 'settings' инициирован!
Файл manager.py инициирован!

❔ Как получить токен для работы бота?

Для начала нам нужно создать сообщество. Для этого переходим в вк в вкладку "Сообщества" и нажимаем кнопку "Создать сообщество".

Там вы заполняете всю необходимую вам информацию, со всем соглашаетесь и попадаете на страницу группы. Там нам нужно найти вкладку "Управление". В меню справа найдите "Настройки"->"Работа с API".

На той странице будет 3 вкладки. Из них нам нужны только 1 и 3:

1. Нажимаем кнопку "Создать ключ", выбираем все необходимые нам доступы (желательно все) и нажимаем "Создать". Данный ключ нужен для переменной TOKEN в настройках бота.
2. Не нужна, пропускаем ее.
3. На данной вкладке вам нужно выбрать версию API, бот тестировался на самом последней версии в момент написания (5.131), советую выбирать самую свежую. Так же вам нужно установить "Long Poll API" в значение "Включено". После этого переходим на вкладку "Тип событий" и выбираем нужные вам значения. Минимальные для работы бота:
   1. Входящее сообщение
   2. Исходящее сообщение

После этого ваш бот готов к работе, можете начинать его тестировать, удачи!

✍️ Автор

• @alex_blackgard - создатель бота и человек, который будет рад любой помощи в доработке бота 🐙💭🌎