1.2.1 FAQ - Xoma163/petrovich GitHub Wiki

Q: Где лежит сам бот в этом django проекте?

A: apps/bot/. Обработка запросов - classes/bots/, API - views.py, команды - commands/

Q: Куда контрибьютить свою команду?

A: В папке apps/bot/commands/ нужно добавить свою команду, унаследованную от Command. Команду следует положить в ту папку, в которую она подходит логически (пример: команда для админа в AdminCommands, простая команда с простым ответом - EasyCommands, Игра - Games, ...)

Q: Правила оформления команд

A : Любая команда должна содержать метод __init__ внутри которой происходит инициализация команды. Обязательным параметром является список names - имена, на которые будет откликаться команда.

Возможные параметры базового класса:

  • name: str - обязательное поле, имя команды.
  • names: list - необязательное поле, имена команды.
  • name_tg: str - имя команды для вызова команд в tg
  • help_text: HelpText- текст для команды /команды и для /помощь
  • enabled: bool - включена ли команда
  • suggest_for_similar: bool - предлагать команду в выдаче похожих команд
  • priority: int - приоритет обработки команды
  • hidden: bool - скрыта ли команда и будет ли отвечать пользователям без соответствующих прав доступа
  • access: Role - требуемый уровень прав для использования команды (user/student/terraria/minecraft/moderator/admin)
  • pm: bool - команда будет работать только в лс
  • conversation: bool - команда будет работать только в конфе
  • fwd: bool - требуются пересылаемые сообщения
  • args: int - требуются аргументы (количество)
  • args_or_fwd: bool- требуются аргументы или пересланные сообщения
  • int_args: list[int] - требуются int аргументы (список, указать позиции)
  • float_args: list[int] - требуются float аргументы (список, указать позиции)
  • platforms: list[Platform] - платформы, на которых будет работать команда (api,tg,vk) (по умолчанию выбраны все)
  • excluded_platforms: list[Platform] - платформы, на которых не будет работать команда
  • attachments: list[Attachment] - требуются ли вложения (список типов)
  • city: bool - требуется ли город у профиля пользователя
  • mentioned: bool - должно ли сообщение обрабатываться только с упоминанием бота
  • non_mentioned: bool - должно ли сообщение обрабатываться только без упоминания бота

Список полей может отличаться от вышеуказанного. Уточняйте в Command

Также должен быть переопределён метод start, в котором содержится тело команды.

Возможно переопределить метод accept, чтобы изменить срабатывание команды (см. VoiceRecognition)

Внутри любой команды есть две переменные - bot и event

bot

Данная переменная - экземпляр Bot со всеми методами для работы.

event

Данная переменная - экземпляр Event со всеми полями, необходимыми для работы.

  • raw - сырой евент
  • bot - экземпляр бота для работы с некоторыми методами
  • is_from_user: bool - флажок сообщение от пользователя
  • is_from_bot: bool - флажок сообщение от бота
  • is_from_chat: bool - флажок сообщение из чата
  • is_from_pm: bool - флажок сообщение из лс
  • user: Optional[User] - сущность User, информация о пользователе в конкретной поверхности (Tg, Vk, API)
  • sender: Optional[Profile] - сущность Profile, основная информация о пользователе
  • chat: Optional[Chat] - чат, откуда прислано сообщение
  • peer_id: int = peer_id - id чата, откуда прислано сообщение
  • from_id: Optional[int] - id пользователя, откуда прислано сообщение
  • platform: Platform - платформа отправителя
  • payload: dict - контент в клавиатуре
  • action - какие-либо экшены в чате (человек вышел из чата, вошёл в чат, чат переименован и т.д.)
  • message: Optional[Message] - сообщение от пользователя
  • fwd: list - пересланные сообщения
  • attachments: list - вложения
  • force_response: Optional[bool] - нужен ли ответ в любом случае
  • command: Optional[Command] - точно выбранная команда (используется для команд, у которых определён accept_extra)
  • is_fwd: bool - является ли сообщение пересланным
  • message_thread_id: Optional[int] - id для супергрупп в tg

Список полей Event может отличаться от вышеуказанного. Уточняйте в classes/events/Event.py

message

Данная переменная - экземпляр Message. В этом классе парсится сообщение пользователя

  • has_command_symbols: bool = False
  • has_mention: bool = False
  • raw: str - сырое сообщение
  • command: str - название команды
  • clear: str - очищенное сообщение от пробелов, ё и т.д.
  • clear_case: str - очищенное сообщение, только с сохранением регистра

Аргументы

  • args_str: str - аргументы пользователя в строке
  • args: list - аргументы пользователя списком
  • args_str_case: str - аргументы пользователя в строке с регистром
  • args_case: list - аргументы пользователя списком с регистром
  • kwargs: dict - мапа из клавиатуры (когда пользователь жмёт на кнопку, у неё у каждой есть какие-то данные)
  • keys:list - ключи для команд (которые передаются в виде --something)
  • id - id сообщения

Q: Как возвращать ответ команды?

A:

  • return ResponseMessage(ResponseMessageItem(...))
  • return ResponseMessage([ResponseMessageItem(...), [ResponseMessageItem(...), ...]) Если не указывается peer_id, то оно автоматически подставит peer_id из Event.

Q: Какие существуют методы для упрощения разработки команд

A: В CommonCommand есть следующие методы:

  • check_sender(role) - Проверяет роль пользователя
  • check_args(count) - Проверяет количество аргументов
  • check_number_arg_range(arg,val1,val2,banned_list) - Проверяет вхождение аргумента в диапазон [val1;val2] и также проверяет, чтобы значение не входило в banned_list
  • parse_int() - Проверяет на int выбранные позиции аргументов (параметр int_args)
  • parse_float() - Проверяет на float выбранные позиции аргументов (параметр float_args)
  • check_pm() - Проверяет на личные сообщения боту
  • check_conversation() - Проверяет на беседу
  • check_fwd() - Проверяет, есть ли пересланные сообщения
  • check_command_time(name,time) - Проверяет, не вышло ли время для повторного использования какого-либо функционала (см Start/Stop/Restart в ModeratorCommand)
  • check_platform() - Проверяет на соответствие платформы
  • check_attachments() - Проверяет, есть ли вложения
  • handle_menu(menu, arg) - Метод имитирующий меню в боте. Например: мем обновить, мем переименовать, мем добавить, и т.д. и т.д..

Q: Как работать с базой данных?

A: Вкратце - в models.py у каждого приложения есть классы - модели. (Пример VkUser, VkChat, ...). Внутри этого файла описываются поля модели. Короткий гайд по работе с сущностями:

  • Model.objects.all() - все записи
  • Model.objects.filter(fieldname = value, fieldname2 = value2) - фильтрация по полям
  • Model(**dict) или
model = Model();
model.field=value
model.save()

Создание сущности и её сохранение

Более подробно