vk-maria 1.0.1

vk bot api wrapper

vk_maria

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

• Установка
• Ваш первый бот
  • Предисловие
  • Простейший эхо бот
• Общая документация по библиотеке
  • Vk
  • LongPoll
  • Обработчики событий
  • EventType
  • Upload
  • Клавиатуры
    • Keyboards
    • Model
    • Button
• Постскриптум

Установка

• Установка с помощью pip:

$ pip install vk_maria

• Установка с github:

$ git clone https://github.com/lxstvayne/vk_maria
$ cd vk_maria
$ python setup.py install

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

Хотя библиотека и готова к использованию, она всё ещё находится на стадии разработки, поэтому не забывайте регулярно её обновлять pip install vk_maria --upgrade

Ваш первый бот

Предисловие

В примерах token предполагает ключ доступа вашего сообщества.

Простейший эхо бот

Класс Vk инкапсулирует все методы работы с токеном сообщества. Класс LongPoll предоставляет возможность работы с событиями сообщества.

Создайте файл echo_bot.py. Откройте его и создайте экземпляр класса Vk:

from vk_maria import Vk, LongPoll


vk = Vk(access_token='token')

Примечание: Обязательно замените token ключом доступа вашего сообщества.

Затем создайте экземпляр класса LongPoll передав ему в качестве аргумента vk:

longpoll = LongPoll(vk)

После этого нам необходимо зарегистрировать обработчик событий. Обработчики событий определяют фильтры, которые должно пройти событие. Если событие проходит фильтры, вызывается декорированная функция и входящее событие передаётся в качестве аргумента.

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

@longpoll.event_handler(commands=['Начать'])
def send_welcome(event):
    vk.messages_send(user_id=event.message.from_id, message='Добро пожаловать!')

Добавим ещё один обработчик:

@longpoll.event_handler()
def echo(event):
    vk.messages_send(user_id=event.message.from_id, message=event.message.text)

Декорированная функция может иметь произвольное имя, однако она должна принимать только 1 параметр (event).

Примечание: все обработчики тестируются в том порядке, в котором они были объявлены.

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

longpoll.polling()

Вот и всё! Наш исходный файл теперь выглядит так:

from vk_maria import Vk, LongPoll


vk = Vk(access_token='token')
longpoll = LongPoll(vk)

@longpoll.event_handler(commands=['Начать'])
def send_welcome(event):
    vk.messages_send(user_id=event.message.from_id, message='Добро пожаловать!')

@longpoll.event_handler()
def echo(event):
    vk.messages_send(user_id=event.message.from_id, message=event.message.text)


longpoll.polling()

Чтобы запустить бота, просто откройте терминал, введите python echo_bot.py и протестируйте его.

Общая документация по библиотеке

Все инструменты импортируются исключительно из пакета vk_maria.

Доступные инструменты:

• Vk
• LongPoll
• EventType
• Upload
• Keyboards
• Model
• Button

---

Vk

Vk, как говорилось раннее, инкапсулирует все методы для работы при помощи ключа доступа сообщества.

---

LongPoll

Экземпляр класса LongPoll позволяет обрабатывает события в сообществе. Он предоставляет обработку как через цикл:

for event in longpoll.listen():
    ...

Так и через удобный декоратор event_handler:

@longpoll.event_handler()
def do_smth(event):
    ...

longpoll.polling()

---

Обработчики событий

Обработчик событий это функция с декоратором event_handler(). Он определяет фильтры для обрабатываемых событий.

@longpoll.event_handler(**filters)
def do_smth(event):
    ...

Фильтр объявляется следующим образом name=argument.

Доступные фильтры:

Название	Аргументы	Условие
type	Тип события из EventType по умолчанию MESSAGE_NEW.	True, если типы событий совпадают.
regexp	Регулярное выражение или подстрока.	True, если подстрока находится в сообщении или строка проходит проверку на наличие шаблона регулярного выражения (Подробнее Python Regular Expressions).
commands	Список с командами.	True, если текст сообщения совпадает с одной из команд.
frm	От кого обрабатывать события ('user', 'chat', 'group') по умолчанию 'user'.	True, если поле from_(user, chat, group) соответсвенно True.

Чтобы начать обрабатывать события, необходимо запустить polling(). Для удобства разработки можно передать параметр debug=True. Тогда все происходящие события будут красиво выводиться в консоль.

---

EventType

EventType представляет из себя перечисление всех возможных событий. К примеру MESSAGE_NEW, MESSAGE_TYPING_STATE, MESSAGE_REPLY...

---

Upload

Класс Upload реализует готовые функции для загрузки файлов на сервера Вконтакте.

Доступные методы:

• photo(photo)
• set_chat_photo(file, chat_id, **kwargs)
• set_group_cover_photo(photo)
• document(document, peer_id, **kwargs)

Параметры photo и document могут быть как строкой относительного пути к файлу, так и файлом открытым с помощью open() на бинарное чтение rb стандартной библиотеки Python.

---

Клавиатуры

Вы можете использовать ассоциации для отправки клавиатур.

Keyboards

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

kbs = Keyboards(folder='keyboards', models='models')

• folder - папка с файлами клавиатур в формате json;
• models - файл с расширением .py, хранящий модели клавиатур.

Теперь вы можете получать клавиатуру вызвав kbs(keyboard), где keyboard - название вашей клавиатуры.

Model

С помощью класса Model можно удобно создавать свои клавиатуры на Python.

Пример:

Создадим файл keyboards.py, где будут храниться наши модели. Импортируем Model и Button:

from vk_maria import Model, Button

Теперь необходимо определить свои модели. Для этого необходимо создать классы, родителями которых будет Model:

class TestKeyboard(Model):

    one_time = True

    row1 = [
        Button.Text(color='primary', label='Кнопка 1'), Button.Text(color='primary', label='Кнопка 2')
    ]
    row2 = [
        Button.Text(color='primary', label='Кнопка 3'), Button.Text(color='primary', label='Кнопка 4')
    ]


class Calculator(Model):

    row1 = [
        Button.Text(color='primary', label='1'),
        Button.Text(color='primary', label='2'),
        Button.Text(color='primary', label='3')
    ]

    row2 = [
        Button.Text(color='primary', label='4'),
        Button.Text(color='primary', label='5'),
        Button.Text(color='primary', label='6')
    ]

    row3 = [
        Button.Text(color='primary', label='7'),
        Button.Text(color='primary', label='8'),
        Button.Text(color='primary', label='9')
    ]

    row4 = [
        Button.Text(color='primary', label='0')
    ]


class Empty(Model):
    pass

Теперь необходимо создать объект типа Keyboards и указать в нём название файла с нашими моделями:

kbs = Keyboards(models='keyboards')

Готово! Мы можем обращаться к нашим объектам клавиатур через kbs:

vk.messages_send(user_id='yourid', message='Разовая клавиатура', keyboard=kbs('TestKeyboard')
vk.messages_send(user_id='yourid', message='Инлайн клавиатура', keyboard=kbs('Calculator')

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

vk.messages_send(user_id='yourid', message='Скрываю клавиатуру', keyboard=kbs('Empty')

Button

Содержит объекты кнопок:

• Text
• OpenLink
• Location
• VKPay
• VKApps
• Callback

Подробнее о них вы можете прочитать в официальной документации

Постскриптум

Я старался написать простую и удобную библиотеку. Если у вас есть идеи по её улучшению, вы можете отправить письмо мне на почту [e-mail].