Справочник по API

Bot

class vk_botting.bot.Bot(command_prefix, description=None, **options)

Представляет собой бота ВК. Это сабкласс Client, поэтому все, что можно делать с Client, можно делать и с ним

Так же это сабкласс GroupMixin, потому у него есть функционал для работы с командами

command_prefix

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

Префикс может быть и итератором строк, в таком случае первый подошедший префикс будет использован для вызова команды. Для избежания проблем нельзя использовать пустой итератор. Префикс можно получить с помощью Context.prefix

Примечание

Если передавать боту несколько префиксов, то учтите, что более ранний префикс не должен быть началом более позднего. Как, к примеру, префиксы не должны быть в порядке ('!', '!?'), ибо в таком случае префикс '!?' никогда не будет использован. Это особенно важно при использовании пустой строки в качестве префикса

case_insensitive

Должна ли команда быть нечуствительной к регистру. По умолчанию False

тип

bool

self_bot

Если True, бот будет слушать только команды, вызванные им же самим. Если False (по умолчанию), то бот будет себя игнорировать

тип

bool

v

Версия VK API. По умолчанию „5.131“ (последняя поддерживаемая библиотекой)

Предупреждение

Библиотека не предназначена для работы с версиями API ниже „5.131“ и выше „5.131“

тип

str

force

Должен ли бот автоматически устанавливать оптимальные настройки LongPoll

тип

bool

lang

Параметр lang для запросов к API

тип

str

add_check(func, *, call_once=False)

Добавляет боту глобальную проверку. Это способ добавить check() или check_once() без декоратора.

Параметры

• func – Функция, используемая как глобальная проверка

• call_once (bool) – Должна ли функция быть вызвана лишь раз при вызове Command.invoke()

add_cog(cog)

Добавляет боту «Cog». Cog - класс, который имеет полностью обособленные события и команды

Параметры

cog (Cog) – Cog, который надо зарегистрировать боту

Исключение

• TypeError – Cog не является наследником класса Cog.

• CommandError – Возникла ошибка во время инициализации.

add_command(command)

Добавляет команду Command или ее наследника в внутренний лист команд.

Обычно не вызывается, вместо него используется декораторы command().

Параметры

command (Command) – Команда, которую надо добавить.

Исключение

• ClientException – Если команда уже зарегистрирована.

• TypeError – Если команда не является сабклассом Command.

add_listener(func, name=None)

Алтернатива listen() без декоратора.

Параметры

• func (coroutine) – Функция, которую надо вызвать.

• name (Optional[str]) – Название события, которое надо слушать. По умолчанию название функции (func.__name__).

Пример

async def on_ready(): pass
async def my_message(message): pass
bot.add_listener(on_ready)
bot.add_listener(my_message, 'on_message_new')

await add_user_token(token)

Эта функция является корутиной. Альтернатива для Context.attach_user_token()

after_invoke(coro)

Декоратор, вызывающий корутину сразу после вызова команды. Удобно использовать для чистки подключений и еще чего-нибудь. Сама корутина должна принимать один параметр - Context

Примечание

Аналог before_invoke(), но не вызывается пока не пройдут все проверки и парсинг аргументов. Правда, вызвывается вне зависимости от наличия или отсутствия ошибок в команде

Параметры

coro (coroutine) – Корутина, которую надо зарегистрировать как привязанное после вызова

Исключение

TypeError – Переданная корутина на самом деле не корутина

await attach_user_token(token)

Эта функция является корутиной.

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

Также помещает в self.user экземпляр класса User соответствующий предоставленному токену

Параметры

token (str) – Токен пользователя, который необходимо прикрепить

before_invoke(coro)

Декоратор, который вызывает корутину прямо перед вызовом команды. Удобно чтобы подготовить подключения, например. Корутина должна принимать один параметр - Context.

Примечание

before_invoke() и after_invoke() вызываются только если все проверки прошли и команда не выдала ошибок.

Параметры

coro (coroutine) – Корутина, которую надо привязать до вызова команды

Исключение

TypeError – Переданная корутина на самом деле не корутина

exception botCommandException

with_traceback()

Тут могла быть ваша реклама

build_msg(msg)

Создает экземпляр класса Message из dict, содержащего объект сообщения.

В нормальных условиях не должна вызываться вообще

Параметры

msg (dict) – dict, представляющий объект сообщения, полученный от VK API

Результат

Экземпляр Message, представляющий изначальное сообщение

Тип результата

Message

check(func)

Декоратор, добавляющий глобальную проверку для бота. Глобальная проверка применяется ко всем командам бота.

Примечание

Эта функция может быть как обычной функцией, так и корутиной.

Similar to a command check(), this takes a single parameter of type Context and can only raise exceptions inherited from CommandError. .. rubric:: Пример

@bot.check
def check_commands(ctx):
    return ctx.command.qualified_name in allowed_commands

check_once(func)

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

Примечание

Эта функция может быть как обычной функцией, так и корутиной.

Как и функция check() команды, принимает один параметр Context и может вызывать ошибки, наследованные из CommandError

Пример

@bot.check_once
def whitelist(ctx):
    return ctx.message.author.id in my_whitelist

cogs

Связь названий cog’ов с самими cog’ами, только для чтения

тип

Mapping[str, Cog]

command(*args, **kwargs)

Декоратор, который добавляет команду в внутренний лист через add_command()

commands

Уникальный набор команд без их альтернативных имен

тип

Set[Command]

extensions

Связь названия расширений с самими расширениями, только для чтения

тип

Mapping[str, types.ModuleType]

get_cog(name)

Получает запрошенный cog. Если он не найден, возвращает None.

Параметры

name (str) – Название cog’а, который запрашивается

get_command(name)

Получает команду (Command или его сабкласс) из внутреннего списка команд

Может использоваться и чтобы получать альтернативные названия

К примеру, в случае с 'foo bar' вернет название подкоманды bar из группы команд foo. Если команда не найдена, вернет None

Параметры

name (str) – Название команды, которую надо получить

Результат

Запрошенная команда. Если не найдена, возвращает None.

Тип результата

Command или сабкласс

await get_context(message, *, cls=<class 'vk_botting.context.Context'>)

Эта функция является корутиной.

Возвращает контекст для вызова команды из сообщения. Это более низкоуровневая часть process_commands(), которая позволяет более детально управлять обработкой. Возвращенный контест не обязательно будет верным, его надо проверить с помощью Context.valid

Параметры

• message (Message) – Сообщение, из которого надо получить контекст для вызова

• cls – Класс, который будет использован для создания контекста. По умолчанию = Context. Если предоставлен собственный класс, он должен быть достаточно близок к Context.

Результат

Контекст для вызова. Тип зависит от параметра cls

Тип результата

Context

await get_group(gid)

Эта функция является корутиной.

Альтернатива для метода „groups.get“ VK API, возвращает только одну группу

Параметры

gid (int) – Id группы, которую надо запросить

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Экземпляр Group для запрошенной группы

Тип результата

Group

await get_groups(*gids)

Эта функция является корутиной.

Альтернатива для метода „groups.get“ VK API

Параметры

gids (List[int]) – Список id групп, которые надо запросить

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Список экземпляров Group для запрошенных групп

Тип результата

List[Group]

await get_own_page()

Эта функция является корутиной.

Получает страницу для текущего токена, вне зависимости от того, пользователь это или группа

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Экземпляр Group или User в зависимости от токена

Тип результата

Union[Group, User]

await get_page(pid, fields=None, name_case=None)

Эта функция является корутиной.

Получает страницу с данным id, вне зависимости от того, группа это или пользователь

Параметры

• pid (int) – Id запрашиваемой страницы

• fields (List[str]) – Опционально. Поля, которые должны быть запрошены у API. По умолчанию никакие

• name_case (str) – Опционально. Падеж имени пользователя. По умолчанию - „nom“. Можеть быть „nom“, „gen“, „dat“, „acc“, „ins“ или „abl“

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Экземпляр Group или User для запрошенного id

Тип результата

Union[Group, User]

await get_pages(*ids, fields=None, name_case=None)

Эта функция является корутиной.

Получает страницы для запрошенных id, вне зависимости от того, группа это или пользователь

Параметры

• ids (List[int]) – Список id для запроса

• fields (List[str]) – Опционально. Поля, которые должны быть запрошены у API. По умолчанию никакие

• name_case (str) – Опционально. Падеж имен пользователей. По умолчанию „nom“. Можеть быть „nom“, „gen“, „dat“, „acc“, „ins“ или „abl“

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Список экземпляров Group или User для запрошенных id

Тип результата

List[Union[Group, User]]

await get_prefix(message)

Эта функция является корутиной.

Получает префикс бота для данного сообщения

Параметры

message (Message) – Контекст сообщения, префикс для которого надо получить

Результат

Список префисков или один префикс для данного сообщения

Тип результата

Union[List[str], str]

await get_user(uid, fields=None, name_case=None)

Эта функция является корутиной.

Альтернатива методу „users.get“ VK API, возвращает только одного пользователя

Параметры

• uid (int) – Id запрашиваемого пользователя

• fields (List[str]) – Опционально. Поля, которые должны быть запрошены у API. По умолчанию никакие

• name_case (str) – Опционально. Падеж имени пользователя. По умолчанию - „nom“. Можеть быть „nom“, „gen“, „dat“, „acc“, „ins“ или „abl“

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Экземпляр класса User для запрошенного пользователя

Тип результата

User

await get_users(*uids, fields=None, name_case=None)

Эта функция является корутиной.

Альтернатива методу „users.get“ VK API

Параметры

• uids (List[int]) – Список id пользователей для запроса

• fields (List[str]) – Опционально. Поля, которые должны быть запрошены у API. По умолчанию никакие

• name_case (str) – Опционально. Падеж имен пользователей. По умолчанию „nom“. Можеть быть „nom“, „gen“, „dat“, „acc“, „ins“ или „abl“

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Список экземпляров User для запрошенных пользователей

Тип результата

List[User]

await invoke(ctx)

Эта функция является корутиной.

Вызывает команду с данным контекстом и разбирается со всеми внутренними механизмами вызова событий.

Параметры

ctx (Context) – Контекст для вызова команды.

listen(name=None)

Декоратор, который привязывает функцию к событию. По сути позволяет слушать множество событий из разных мест, таких, как, к примеру on_ready(). Привязанная функция должна быть корутиной.

Пример

@bot.listen()
async def on_message_new(message):
    print('one')
# in some other file...
@bot.listen('on_message_new')
async def my_message(message):
    print('two')

Выведет „one“ и „two“ в неопределенном порядке.

Исключение

TypeError – Привязанная функция - не корутина.

load_extension(name)

Загружает расширение. Расширения - модуль python который содержит команды, cog’и и события. Любое расширение должно иметь глобальную функцию setup, определяющую, что расширение должно делать, когда загружено. Эта функция должна принимать 1 аргумент - bot.

Параметры

name (str) – Название расширения, которое надо загрузить. Должно иметь в себе точку, повторяя синтаксис импорта в обычном Python (к примеру foo.test для файла foo/test.py).

Исключение

• ExtensionNotFound – Расширение не может быть импортировано.

• ExtensionAlreadyLoaded – Расширение уже загружено.

• NoEntryPointError – У расширения нет функции setup.

• ExtensionFailed – В расширении или его setup возникла ошибка.

await on_command_error(context, exception)

Эта функция является корутиной. Обработчик ошибок, предоставляемый ботом. По умолчанию выводит информацию о ошибке в sys.stderr, но может быть переобъявлен, чтобы делать что-то другое. Вызывается только если в боте нет функций, привязанных к ошибкам.

await on_error(event_method, *args, **kwargs)

Эта функция является корутиной.

Обработчик ошибок, предоставляемый ботом.

По умолчанию выводит информацию о ошибке в sys.stderr, но может быть переобъявлен, чтобы делать что-то другое.

Посмотрите vk_botting.on_error() для более детального объяснения

await process_commands(message)

Эта функция является корутиной.

Функция, обрабатывающая команды, зарегистрированные в боте и прочих источниках. Без этой корутины никакие команды вызваны не будут.

По умолчанию, эта корутина вызывается внутри on_message_new(). Если вы переобъявляете on_message_new(), не забудьте вызывать эту корутину.

Состоит из более низкоуровневых функций и представляет собой последовательный вызов get_context() и invoke().

Так же проверяет, является ли автор сообщения ботом и не вызывает get_context() и invoke() в таком случае.

Параметры

message (Message) – Сообщение, команды из которого надо обрабатывать

reload_extension(name)

Автоматически перезагружает расширение. Заменяет расширение перезагруженной версией самого себя. Представляет собой последовательный вызов unload_extension() и load_extension(), но рассчитанный на возможные ошибки, в случае которых бот возвращается к предыдущей, рабочей версии расширения.

Параметры

name (str) – Имя расширения, которое надо перезагрузить. Должно иметь в себе точку, повторяя синтаксис импорта в обычном Python (к примеру foo.test для файла foo/test.py).

Исключение

• ExtensionNotLoaded – Расширение не было загружено.

• ExtensionNotFound – Расширение не может быть импортировано.

• NoEntryPointError – У расширения нет функции setup.

• ExtensionFailed – В функции setup расширения произошла ошибка.

remove_check(func, *, call_once=False)

Удаляет глобальную проверку из бота. Эта функция не вызывает ошибку даже если такой глобальной проверки не было.

Параметры

• func – Функция, которую надо удалить из глобальных проверок.

• call_once (bool) – Была ли функция была добавлена с параметром call_once=True

remove_cog(name)

Удаляет cog из бота. Все связаные с ним команды и события тоже будут удалены. Если cog не найден, ничего не делает.

Параметры

name (str) – Название cog’а для удаления.

remove_command(name)

Удаляет команду (Command или сабкласс) из внутреннего списка команд.

Может быть использован и для удаления альтернативных названий.

Параметры

name (str) – Названия команды для удаления.

Результат

Удаленная команда. Если имя было неверным, то None

Тип результата

Command или сабкласс

remove_listener(func, name=None)

Удаляет событие из списка событий.

Параметры

• func – Функция, которая была привязана к событию.

• name (str) – Название события, которое надо удалить. По умолчанию - имя функции

run(token, owner_id=None)

Блокирующий вызов, который позволяет не инициализировать цикл самостоятельно.

Предупреждение

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

Параметры

• token (str) – Токен бота. Должен быть токеном группы или токеном пользователя с доступом к группе.

• owner_id (int) – Должен отправляться только вместе с токеном пользователя. Id группы, к которой надо подключиться

await send_message(peer_id=None, message=None, attachment=None, sticker_id=None, keyboard=None, reply_to=None, forward_messages=None, forward=None, **kwargs)

Эта функция является корутиной.

Отправляет сообщение данному получателю с данным текстом

Текст должен быть типом, который можно преобразовать в строку с помощью str(message).

Если сообщение - None (по умолчанию), то должен быть предоставлен параметр attachment или sticker_id.

Если есть параметр attachment, он должен быть str, List[str], Attachment или List[Attachment]

Если есть параметр keyboard, он должен быть str или Keyboard (предпочтительно)

Параметры

• peer_id (int) – Id получателя сообщения

• message (str) – Текст сообщения

• attachment (Union[List[str], str, List[Attachment], Attachment]) – Приложение к сообщению

• sticker_id (Union[str, int]) – Id стикера, который надо отправить

• keyboard (Keyboard) – Клавиатура, которую надо отправить вместе с сообщением

• reply_to (Union[str, int]) – Id сообщения, на которое надо ответить

• forward_messages (Union[List[int], List[str]]) – Id сообщений, которые надо переслать.

• forward (dict) – Для дополнительной информации смотрите документацию.

• as_user (bool) – Должно ли сообщение быть отправлено от имени пользователя (с использованием присоединенного токена)

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Сообщение, которое было отправлено

Тип результата

Message

unload_extension(name)

Выгружает расширение. Когда расширение выгружено, все команды, события и cog’и, связанные с ним, тоже удаляются. У расширения так же может быть функция teardown для чистки всего, что осталось, если это необходимо. Она, аналогично setup, должна принимать один параметр - bot

Параметры

name (str) – Название расширения для выгрузки. Должно иметь в себе точку, повторяя синтаксис импорта в обычном Python (к примеру foo.test для файла foo/test.py).

Исключение

ExtensionNotLoaded – Расширение не было загружено.

await upload_document(peer_id, file, type=<DocType.DOCUMENT: 'doc'>, title=None)

Эта функция является корутиной.

Загружает документ в диалог с данным peer_id

Возвращает attachment, готовый к использованию в send_message

Параметры

• peer_id (int) – Peer_id назначения. Загруженный документ нельзя использовать вне данного диалога.

• file (str) – Путь к документу, который надо загрузить. Может быть относительным.

• type (str) – Тип загруженного документа. Может быть значением из DocType

• title (str) – Название для загруженного документа. По умолчанию имя файла.

Результат

Экземпляр Attachment, представляющий загруженный документ

Тип результата

Attachment

await upload_image_to_server(server, filename=None, url=None, raw=None, format=None)

Эта функция является корутиной.

Загружает изображение на какой-то сервер ВК.

Возвращает dict, представляющий собой ответ сервера.

Параметры

• server (str) – Url сервера для загрузки. Может быть получен от API с помощью методов подобных photos.getUploadServer.

• filename (str) – Путь к изображению, которое надо загрузить. Может быть относительным.

• url (str) – Ссылка на изображение, которое надо загрузить. Это должна быть прямая ссылка на поддерживаемый формат изображений, иначе не сработает.

• raw (bytes) – Сырые байты изображения, которое надо загрузить. Если используется, надо передать параметр format.

• format (str) – Расширение загружаемого изображения. Должно быть использовано только вместе с сырыми байтами.

Результат

dict, представляющий собой ответ сервера.

Тип результата

dict

await upload_photo(peer_id, filename=None, url=None, raw=None, format=None)

Эта функция является корутиной.

Загружает изображение в диалог с данным peer_id

Возвращает attachment, готовый к использованию в send_message

Параметры

• peer_id (int) – Peer_id назначения. Загруженное изображение нельзя использовать вне данного диалога

• filename (str) – Путь к изображению, которое надо загрузить. Может быть относительным.

• url (str) – Ссылка на изображение, которое надо загрузить. Это должна быть прямая ссылка на поддерживаемый формат изображений, иначе не сработает.

• raw (bytes) – Сырые байты изображения, которое надо загрузить. Если используется, надо передать параметр format.

• format (str) – Расширение загружаемого изображения. Должно быть использовано только вместе с сырыми байтами.

Результат

Экземпляр Attachment, представляющий загруженное фото.

Тип результата

Attachment

await user_vk_request(method, post=True, **kwargs)

Эта функция является корутиной.

Реализует абстрактный запрос к методам VK Api с помощью прикрепленного токена пользователя.

Параметры

• method (str) – Название метода в виде строки (к примеру „users.get“)

• post (bool) – Должен ли запрос быть POST. По умолчанию True. Не рекомендуется менять этот параметр.

• kwargs (Any) – Аргументы для отправки вместе с запросом. .. note:: access_token и v отправлять не надо, они автоматически добавляются из настроек текущего бота

Результат

Ответ от сервера, представленный в виде dict

Тип результата

dict

await vk_request(method, post=True, **kwargs)

Эта функция является корутиной.

Реализует абстрактный запрос к методам VK Api

Параметры

• method (str) – Название метода в виде строки (к примеру „users.get“)

• post (bool) – Должен ли запрос быть POST. По умолчанию True. Не рекомендуется менять этот параметр.

• kwargs (Any) – Аргументы для отправки вместе с запросом. .. note:: access_token и v отправлять не надо, они автоматически добавляются из настроек текущего бота

Результат

Ответ от сервера, представленный в виде dict

Тип результата

dict

wait_for(event, *, check=None, timeout=None)

Эта функция является корутиной.

Ожидает определенное событие.

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

Параметр timeout передается напрямую в asyncio.wait_for(). По умолчанию, ждет неопределенно долго. Учтите, что в случае истечения времени вызывается asyncio.TimeoutError.

В случае если событие возвращает множество аргументов, возвращается tuple, содержащий их. Пожалуйста, обращайтесь к documentation для справки о событиях и их параметрах

Функция возвращает первое событие, удовлетворяющее условиям

Примеры

Ожидание ответа пользователя:

@bot.command()
async def greet(ctx):
    await ctx.send('Say hello!')
    def check(m):
        return m.text == 'hello' and m.from_id == ctx.from_id
    msg = await bot.wait_for('message_new', check=check)
    await ctx.send('Hello {.from_id}!'.format(msg))

Параметры

• event (str) – Название события, как и в event reference, но без префикса on_.

• check (Optional[Callable[…, bool]]) – Проверка для события, которое надо ожидать. Аргументы должны соответствовать параметрам события, который ожидается.

• timeout (Optional[float]) – Количество секунд для ожидания. По истечении вызывает asyncio.TimeoutError.

Исключение

asyncio.TimeoutError – Если время ожидание было предоставлено и достигнуто

Результат

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

Тип результата

Any

for ... in walk_commands()

Итератор, который рекурсивно проходит по всем командам и подкомандам.

vk_botting.bot.when_mentioned(bot, msg)

Функция, которая реализует префикс команды, аналогичный обращению к боту. Должна передаваться как атрибут Bot.command_prefix

vk_botting.bot.when_mentioned_or(*prefixes)

Функция, которая реализует префикс команды, аналогичный обращению к боту, а также все предоставленные префиксы. Должна передаваться как атрибут Bot.command_prefix

Пример

bot = Bot(command_prefix=commands.when_mentioned_or('!'))

Примечание

Эта функция возвращает другую функцию, так что если она используется внутри собственной функции, то должна возвращать возвращенную функцию. К примеру:

async def get_prefix(bot, message):
    extras = await prefixes_for(message.peer_id) # returns a list
    return commands.when_mentioned_or(*extras)(bot, message)

См.также

when_mentioned(), when_mentioned_or_pm(), when_mentioned_or_pm_or()

vk_botting.bot.when_mentioned_or_pm()

Функция, которая реализует префикс команды, аналогичный обращению к боту, а также принимает любое сообщение за команду, в случае если боту пишут в ЛС. Должна передаваться как атрибут Bot.command_prefix

Пример

bot = commands.Bot(command_prefix=commands.when_mentioned_or_pm())

См.также

when_mentioned(), when_mentioned_or(), when_mentioned_or_pm_or()

vk_botting.bot.when_mentioned_or_pm_or(*prefixes)

Функция, которая реализует префикс команды, аналогичный обращению к боту, принимает любое сообщение за команду, в случае если боту пишут в ЛС, а также реализует все предоставленные префиксы. Должна передаваться как атрибут Bot.command_prefix

Пример

bot = commands.Bot(command_prefix=commands.when_mentioned_or_pm_or('!'))

Примечание

Эта функция возвращает другую функцию, так что если она используется внутри собственной функции, то должна возвращать возвращенную функцию. К примеру:

async def get_prefix(bot, message):
    extras = await prefixes_for(message.peer_id) # returns a list
    return commands.when_mentioned_or(*extras)(bot, message)

См.также

when_mentioned(), when_mentioned_or(), when_mentioned_or_pm()

Context

class vk_botting.context.Context(**attrs)

Представляет собой контекст с которым должна вызываться команда.

Этот класс содержит кучу информации, которая поможет вам понять контекст вызова команды. Класс не должен создаваться вручную и вместо этого должен передаваться командам как первый параметр.

Класс является экземпляром абстрактного класса Messageable

message

Сообщение, которое вызвало команду.

тип

Message

bot

Бот, у которого зарегистрирована вызываемая команда.

тип

Bot

args

Список преобразованных аргументов, переданных команде. Если используется в событии on_command_error(), то может быть неполным

тип

list

kwargs

Словарь преобразованных аргументов, переданных команде. Аналогично args, если используется в событии on_command_error(), то может быть неполным

тип

dict

prefix

Префикс, использованный для вызова команды

тип

str

command

Команда (Command или сабкласс), которую контекст вызывает

invoked_with

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

тип

str

invoked_subcommand

Подкоманда (Command или сабкласс), которая была вызвана. None если подкоманды не были использованы

subcommand_passed

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

тип

Опциональный[str]

command_failed

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

тип

bool

await invoke(*args, **kwargs)

Эта функция является корутиной.

Вызывает команду с данными аргументами.

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

Примечание

Не вызывает преобразователи, проверки, задержки или связанные события. Просто вызывает связанную функцию.

В эту функцию очень важно передавать верные аргументы.

Предупреждение

Первым параметром должна быть вызываемая команда.

Параметры

• command (Command) – Команда или ее сабкласс, которую необходимо вызвать

• *args – Аргументы для вызова

• **kwargs – Аргументы с ключевыми словами для вызова

await reinvoke(*, call_hooks=False, restart=True)

Эта функция является корутиной.

Заново вызывает команду

Аналог invoke(), но пропускает проверки, задержки и обработчики ошибок

Примечание

Если необходимо избежать ArgumentError или ее наследников, то стоит использовать обычный invoke(), так как иначе будут использованы те же аргументы и возвращена та же ошибка

Параметры

• call_hooks (bool) – Вызывать ли связанные события

• restart (bool) – Начинать ли вызов команды с начала или с момента, где бот остановился (к примеру команда, вызвавшая ошибку). По умолчанию - с места остановки

await reply(message=None, *, attachment=None, sticker_id=None, keyboard=None)

Эта функция является корутиной. Сокращение для Message.reply()

await get_user(fields=None, name_case=None)

Эта функция является корутиной. Возвращает автора сообщения как экземпляр User class

await get_author(*args, **kwargs)

Эта функция является корутиной. Альтернатива для Context.get_user()

await fetch_user(*args, **kwargs)

Эта функция является корутиной. Альтернатива для Context.get_user()

await fetch_author(*args, **kwargs)

Эта функция является корутиной. Альтернатива для Context.get_user()

cog

Возвращает cog, связанный с командой или None, если такого не существует

valid

Проверяет, верен ли контекст для вызова

author

Сокращение для Message.from_id

from_id

Сокращение для Message.from_id

peer_id

Сокращение для Message.peer_id

text

Сокращение для Message.text

me

Возвращает экземпляр Group или User, в зависимости от используемого токена.

await send(message=None, *, attachment=None, sticker_id=None, keyboard=None, reply_to=None, forward_messages=None)

Эта функция является корутиной.

Отправляет сообщение в ответ с данным текстом.

Текст должен быть типом, который можно преобразовать в строку с помощью str(message).

Если сообщение - None (по умолчанию), то должен быть предоставлен параметр attachment или sticker_id.

Если есть параметр attachment, он должен быть str, List[str], Attachment или List[Attachment]

Если есть параметр keyboard, он должен быть str или Keyboard (предпочтительно)

Параметры

• message (str) – Текст сообщения

• attachment (Union[List[str], str, List[Attachment], Attachment]) – Приложение к сообщению

• sticker_id (Union[str, int]) – Id стикера, который надо отправить

• keyboard (Keyboard) – Клавиатура, которую надо отправить вместе с сообщением

• reply_to (Union[str, int]) – Id сообщения, на которое надо ответить

• forward_messages (Union[List[int], List[str]]) – Id сообщений, которые надо переслать.

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Сообщение, которое было отправлено

Тип результата

Message

await trigger_typing()

Эта функция является корутиной.

Включает боту состояние „печатает“

Может быть использовано вместо typing() в некоторых случаях

Состояние „печатает“ выключается через 10 секунд или при отправке ответа

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Результат вызова к VK Api

Тип результата

dict

typing()

Возвращает контекстный менеджер, который позволяет поддерживать состояние „печатает“ неопределенное количество времени

Может быть использовано для долгих операций бота в командах

Примечание

Может использоваться и как синхронный контекстный менеджер, и как асинхроный. То есть и with и async with будут работать

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

async with ctx.typing():
    # do expensive stuff here
    await ctx.send('done!')

Справка по событиям

Эта страница описывает различные события, которые слушает Bot

Есть два способа зарегистрировать события: через Bot.listen() или создать сабкласс Bot и перезаписать события. К примеру:

import vk_botting

class MyBot(vk_botting.Bot):
    async def on_message_new(self, message):
        if message.from_id == self.group.id:
            return

        if message.text.startswith('$hello'):
            await message.send('Hello World!')

Если обработчик события вызывает ошибку, то вызывается функция on_error() для ее обработки. По умолчанию она выводит ошибку и игнорирует ее

Предупреждение

Все события должны быть корутинами(корутиной). Если они таковыми не являются, то можно получить неожиданные ошибки. Чтобы функция стала корутиной, ее надо объявлять через async def

on_ready()

Вызывается, когда бот закончил подготовку информации, полученной от VK Api. Обычно - после успешного входа и когда подготовлены атрибуты Bot.group и прочие

on_error(event, \*args, \*\*kwargs)

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

Информация о ошибке и сама ошибка получаются стандартным вызовом sys.exc_info()

Если необходимо, чтобы ошибка выходила за пределы бота, то можно просто вызывать ошибку внутри on_error (The raise statement). Если внутри on_error вызвана ошибка, то бот никак не будет ее обрабатывать.

Параметры

• event (str) – Названия события, вызвавшего ошибку

• args – Позиционные аргументы для события, вызвавшего ошибку

• kwargs – Аргументы с ключевыми словами для события, вызвавшего ошибку

on_command_error(ctx, error)

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

По умолчанию - Bot.on_command_error()

Параметры

• ctx (Context) – Контекст вызова команды

• error (CommandError derived) – Вызванная ошибка

on_command(ctx)

Событие, которое вызывается когда команда найдена и будет вызвана

Это событие вызывается вне зависимости от возможных ошибок в команде

Параметры

ctx (Context) – Контекст вызова команды

on_command_completion(ctx)

Событие, которое вызывается, когда команда успешно вызвана

Вызывается только после успешного вызова команды

Параметры

ctx (Context) – Контекст вызова команды

on_message_new(message)

Вызывается, когда бот получает сообщение

Параметры

message (message.Message) – Полученное сообщение

on_message_event(event)

Вызывается, когда пользователь нажимает на callback-кнопку

Параметры

event – Полученное событие

on_message_reply(message)

Вызывается, когда бот отвечает на сообщение

Параметры

message (message.Message) – Отправленное сообщение

on_message_edit(message)

Вызывается, когда сообщение изменено

Параметры

message (message.Message) – Измененное сообщение

on_message_typing_state(state)

Вызывается, когда изменяется состояние „печатает“ (к примеру кто-то начал печатать)

Параметры

state (states.State) – Новое состояние

on_conversation_start(message)

Вызывается, когда пользователь использует кнопку „Начать“ в диалоге с ботом

Параметры

message (message.Message) – Сообщение, отправленное когда пользователь начал диалог

on_chat_kick_user(message)

Вызывается при удалении пользователя из чата

Параметры

message (message.Message) – Сообщение, отправленное, когда пользователь был удален

on_chat_invite_user(message)

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

Параметры

message (message.Message) – Сообщение, отправленное при приглашении пользователя

on_chat_invite_user_by_link(message)

Вызывается при добавлении пользователя к чату посредством ссылки-приглашения

Параметры

message (message.Message) – Сообщение, отправленное при приглашении пользователя

on_chat_photo_update(message)

Вызывается при обновлении фото чата

Параметры

message (message.Message) – Сообщение, отправленное при смене фото

on_chat_photo_remove(message)

Вызывается при удалении фото чата

Параметры

message (message.Message) – Сообщение, отправленное при удалении фото

on_chat_create(message)

Вызывается при создании чата

Параметры

message (message.Message) – Сообщение, отправленное при создании чата

on_chat_title_update(message)

Вызывается при обновлении названия чата

Параметры

message (message.Message) – Сообщение, отправленное при смене названия чата

on_chat_pin_message(message)

Вызывается при закреплении сообщения в чате

Параметры

message (message.Message) – Сообщение, отправленное при закреплении сообщения в чате

on_chat_unpin_message(message)

Вызывается при откреплении сообщения в чате

Параметры

message (message.Message) – Сообщение, отправленное при откреплении сообщения в чате

on_message_allow(user)

Вызывается, когда пользователь разрешает получение сообщений от бота

Параметры

user (user.User) – Пользователь, разрешивший получение сообщений

on_message_deny(user)

Вызывается, когда пользователь запрещает получение сообщения от бота

Параметры

user (user.User) – Пользователь, запретивший получение сообщений

on_photo_new(photo)

Вызывается, когда в группу бота загружено фото

Параметры

photo (attachments.Photo) – Загруженное фото

on_audio_new(audio)

Вызывается, когда в группу бота загружено аудио

Параметры

audio (attachments.Audio) – Загруженное аудио

on_video_new(video)

Вызывается, когда в группу бота загружено видео

Параметры

video (attachments.Video) – Загруженное видео

on_photo_comment_new(comment)

Вызывается, когда к фото добавляется новый комментарий

Параметры

comment (group.PhotoComment) – Добавленный комментарий

on_photo_comment_edit(comment)

Вызывается, когда под фото изменяется комментарий

Параметры

comment (group.PhotoComment) – Измененный комментарий

on_photo_comment_restore(comment)

Вызывается, когда под фото восстанавливается комментарий

Параметры

comment (group.PhotoComment) – Восстановленный комментарий

on_photo_comment_delete(comment)

Вызывается, когда под фото удаляется комментарий

Параметры

comment (group.DeletedPhotoComment) – Удаленный комментарий

on_video_comment_new(comment)

Вызывается, когда к видео добавляется новый комментарий

Параметры

comment (group.VideoComment) – Добавленный комментарий

on_video_comment_edit(comment)

Вызывается, когда под видео изменяется комментарий

Параметры

comment (group.VideoComment) – Измененный комментарий

on_video_comment_restore(comment)

Вызывается, когда под видео восстанавливается комментарий

Параметры

comment (group.VideoComment) – Восстановленный комментарий

on_video_comment_delete(comment)

Вызывается, когда под видео удаляется комментарий

Параметры

comment (group.DeletedVideoComment) – Удаленный комментарий

on_market_comment_new(comment)

Вызывается, когда к товару добавляется новый комментарий

Параметры

comment (group.MarketComment) – Добавленный комментарий

on_market_comment_edit(comment)

Вызывается, когда под товаром изменяется комментарий

Параметры

comment (group.MarketComment) – Измененный комментарий

on_market_comment_restore(comment)

Вызывается, когда под товаром восстанавливается комментарий

Параметры

comment (group.MarketComment) – Восстановленный комментарий

on_market_comment_delete(comment)

Вызывается, когда под товаром удаляется комментарий

Параметры

comment (group.DeletedMarketComment) – Удаленный комментарий

on_board_post_new(comment)

Вызывается, когда к обсуждению добавляется новый комментарий

Параметры

comment (group.BoardComment) – Комментарий, добавленный к обсуждению

on_board_post_edit(comment)

Вызывается, когда в обсуждении изменяется комментарий

Параметры

comment (group.BoardComment) – Измененный комментарий

on_board_post_restore(comment)

Вызывается, когда в обсуждении восстанавливается комментарий

Параметры

comment (group.BoardComment) – Восстановленный комментарий

on_board_post_delete(comment)

Вызывается, когда в обсуждении удаляется комментарий

Параметры

comment (group.DeletedBoardComment) – Удаленный комментарий

on_wall_post_new(post)

Вызывается, когда на стену добавляется пост

Параметры

post (group.Post) – Добавленный пост

on_wall_repost(post)

Вызывается, когда пост со стены репостится

Параметры

post (group.Post) – Репостнутый пост

on_wall_reply_new(comment)

Вызывается, когда на стену добавляется новый комментарий

Параметры

comment (group.WallComment) – Добавленный комментарий

on_wall_reply_edit(comment)

Вызывается, когда комментарий на стене изменяется

Параметры

comment (group.WallComment) – Измененный комментарий

on_wall_reply_restore(comment)

Вызывается, когда комментарий на стене восстанавливается

Параметры

comment (group.WallComment) – Восстановленный комментарий

on_wall_reply_delete(comment)

Вызывается, когда комментарий на стене удаляется

Параметры

comment (group.DeletedWallComment) – Удаленный комментарий

on_group_join(user, join_type)

Вызывается, когда пользователь присоединяется к группе

Параметры

• user (user.User) – Пользователь, присоединившийся к группе

• join_type (str) – Тип присоединения. Может быть „join“ если пользователь просто присоединился, „unsure“ для событий, „accepted“ если пользователя приглашали, „approved“ если пользователя приняли или „request“ если пользователь запросил доступ в сообщество

on_group_leave(user, self)

Вызывается, когда пользователь покидает группу

Параметры

• user (user.User) – Пользователь, покинувший группу

• self (bool) – Покинул ли пользователь сам (True) или был исключен (False)

on_user_block(user)

Вызывается, когда пользователя блокируют в группе

Параметры

user (user.BlockedUser) – Пользователь, которого заблокировали

on_user_unblock(user)

Вызывается, когда пользователя разблокируют в группе

Параметры

user (user.UnblockedUser) – Пользователь, которого разблокировали

on_poll_vote_new(vote)

Вызывается, когда в опросе появляется новый голос

Параметры

vote (group.PollVote) – Новый голос

on_group_officers_edit(edit)

Вызывается, когда изменяются полномочия в группе

Параметры

edit (group.OfficersEdit) – Изменение

on_unknown(payload)

Вызывается, когда получено неизвестное событие

Параметры

payload (dict) – Json события

Cog’и

Cog

class vk_botting.cog.Cog

Базовый класс который должны наследовать все cog’и.

Cog - собрание команд, событий и переменных состояний, помогающий объединять команды в группы. Больше информации о них можно найти на странице Cogs.

При наследовании этого класса, можно также указывать параметры, доступные в CogMeta.

qualified_name

Возвращает название cog’а, а не название класса.

тип

str

description

Возвращает описание cog’а, обычно это очищенный docstring.

тип

str

for ... in walk_commands()

Итератор, который рекурсивно проходит по всем командам и подкомандам.

get_listeners()

Возвращает list вида (имя, функция), содержащий все события объявленные в этом cog’е.

classmethod listener(name=None)

Декоратор, который регистрирует функцию как обработчик события.

Это то же самое, что Bot.listen(), только для cog’а.

Параметры

name (str) – Название события, которое надо слушать. По умолчанию название функции (func.__name__).

Исключение

TypeError – Функция не является корутиной или же переданное название не является строкой.

cog_unload()

Особый метод, который вызывается когда cog удаляется.

Эта функция не может быть корутиной. Это должна быть обычная функция.

Сабклассы должны заменить эту функцию для изменения поведения при удалении cog’а.

bot_check_once(ctx)

Особый метод который регистрирует проверку аналогично Bot.check_once().

Эта функция может быть корутиной и должна принимать один параметр - ctx, который представляет собой Context.

bot_check(ctx)

Особый метод который регистрирует проверку аналогично Bot.check_once().

Эта функция может быть корутиной и должна принимать один параметр - ctx, который представляет собой Context.

cog_check(ctx)

Особый метод, который добавляет commands.check() к каждой команде и подкоманде в этом cog’е.

Эта функция может быть корутиной и должна принимать один параметр - ctx, который представляет собой Context.

cog_command_error(ctx, error)

Особый метод, который вызывается когда внутри cog’а происходит ошибка.

Он похож на on_command_error(), за исключением того что применяется он только к командам внутри cog’а.

Эта функция может быть корутиной.

Параметры

• ctx (Context) – Контекст вызова, при котором произошла ошибка.

• error (CommandError) – Вызванная ошибка.

await cog_before_invoke(ctx)

Особый метод, который выступает как локальный, действующий только на cog аналог Command.before_invoke().

Эта функция должна быть корутиной.

Параметры

ctx (Context) – Контекст вызова команды

await cog_after_invoke(ctx)

Особый метод, который выступает как локальный, действующий только на cog аналог Command.after_invoke().

Эта функция должна быть корутиной.

Параметры

ctx (Context) – Контекст вызова команды

CogMeta

class vk_botting.cog.CogMeta(*args, **kwargs)

Метакласс для объявления cog’а.

Важно заметить, что этот класс не предназначен для использования напрямую. Он представлен тут исключительно для полноты документации. В случае необходимости есть возможность создания собственных метаклассов для смеси этого с другими метаклассами, к примеру abc.ABCMeta.

К примеру, для создания своего абстрактного класса, смешивающего cog с чем-то еще,можно сделать следующее.

import abc
class CogABCMeta(CogMeta, abc.ABCMeta):
    pass
class SomeMixin(metaclass=abc.ABCMeta):
    pass
class SomeCogMixin(SomeMixin, Cog, metaclass=CogABCMeta):
    pass

Примечание

При передаче аттрибута метакласса, задокументированного ниже, важно заметить необходимость передачи его именно как аргумент с ключевым словом при создании класса, например:

class MyCog(Cog, name='My Cog'):
    pass

name

Название cog’а. По умолчанию - название класса без изменений.

тип

str

command_attrs

Список свойств, которые передаются каждой команде внутри этого cog’а. Словарь передается в __init__ класса Command (или его сабкласса). Если указать свойства при объявлении команды внутри класса, то они перезапишутсвойства, указанные в данном параметре. Например:

class MyCog(Cog, command_attrs=dict(hidden=True)):
    @command()
    async def foo(self, ctx):
        pass # hidden -> True

    @command(hidden=False)
    async def bar(self, ctx):
        pass # hidden -> False

тип

dict

Абстрактные классы

abstract base class, известные как abc - классы, которые определяют базовые модели, которые могут наследовать другие классы (abc). Нельзя создавать экземпляры этих классов. Они существуют в основном для использования с isinstance() и issubclass()

Эта библиотека содержит раздел, посвященный абстрактным классам

class vk_botting.abstract.Messageable

ABC, который определяет основные операции с моделями, способными получать сообщения

Этот ABC используется для:

• User

• Message

• UserMessage

• Context

async with typing()

Возвращает контекстный менеджер, который позволяет поддерживать состояние „печатает“ неопределенное количество времени

Может быть использовано для долгих операций бота в командах

Примечание

Может использоваться и как синхронный контекстный менеджер, и как асинхроный. То есть и with и async with будут работать

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

async with ctx.typing():
    # do expensive stuff here
    await ctx.send('done!')

await send(message=None, *, attachment=None, sticker_id=None, keyboard=None, reply_to=None, forward_messages=None)

Эта функция является корутиной.

Отправляет сообщение в ответ с данным текстом.

Текст должен быть типом, который можно преобразовать в строку с помощью str(message).

Если сообщение - None (по умолчанию), то должен быть предоставлен параметр attachment или sticker_id.

Если есть параметр attachment, он должен быть str, List[str], Attachment или List[Attachment]

Если есть параметр keyboard, он должен быть str или Keyboard (предпочтительно)

Параметры

• message (str) – Текст сообщения

• attachment (Union[List[str], str, List[Attachment], Attachment]) – Приложение к сообщению

• sticker_id (Union[str, int]) – Id стикера, который надо отправить

• keyboard (Keyboard) – Клавиатура, которую надо отправить вместе с сообщением

• reply_to (Union[str, int]) – Id сообщения, на которое надо ответить

• forward_messages (Union[List[int], List[str]]) – Id сообщений, которые надо переслать.

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Сообщение, которое было отправлено

Тип результата

Message

await trigger_typing()

Эта функция является корутиной.

Включает боту состояние „печатает“

Может быть использовано вместо typing() в некоторых случаях

Состояние „печатает“ выключается через 10 секунд или при отправке ответа

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Результат вызова к VK Api

Тип результата

dict

Дополнительные классы

Attachment

class vk_botting.attachments.AttachmentType

Определяет тип приложения

PHOTO = 'photo'

Фото

VIDEO = 'video'

Видео

AUDIO = 'audio'

Аудио

DOCUMENT = 'doc'

Документ

WALL = 'wall'

Пост со стены

MARKET = 'market'

Товар

POLL = 'poll'

Опрос

class vk_botting.attachments.Attachment(owner_id, _id, type)

Представляет собой приложение к сообщению

Для получения строкового представления можно использовать str(Attachment) или просто передавать это как аргумент в Bot.send_message()

owner_id

Id владельца приложения. Положительное целое для пользователей, отрицательное для групп

тип

int

id

Id самого приложения. Положительное целое

тип

int

type

Тип приложения. Может быть значением из AttachmentType

тип

str

Keyboard

class vk_botting.keyboard.KeyboardColor

Определяет цвета клавиатуры

PRIMARY = 'primary'

Основной цвет (синий)

SECONDARY = 'secondary'

Вторичный цвет (серый)

NEGATIVE = 'negative'

Отрицательный цвет (красный)

POSITIVE = 'positive'

Положительный цвет (зеленый)

class vk_botting.keyboard.Keyboard(one_time=False, inline=False)

Класс для удобного создания и изменения клавиатур ботов

Может использоваться в Bot.send_message() как есть

one_time

Должна ли клавиатура быть одноразовой (исчезать после одного использования)

тип

bool

inline

Должна ли клавиатура быть прикреплена к сообщению. Ограничивает клавиатуру до 6x5

тип

bool

classmethod get_empty_keyboard()

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

add_button(label, color=<KeyboardColor.PRIMARY: 'primary'>, payload=None)

Добавляет кнопку на текущую строку

Параметры

• label (str) – Название кнопки

• color (:class:Union[str, KeyboardColor]) – Цвет кнопки. Может быть значением из KeyboardColor

• payload (dict) – Опционально. Используется для некоторых кнопок

Исключение

vk_botting.VKApiError – Когда на строке уже слишком много кнопок

add_callback_button(label, color=<KeyboardColor.PRIMARY: 'primary'>, payload=None)

Добавляет callback-кнопку (https://vk.com/dev/bots_docs_5) на текущую строку

Параметры

• label (str) – Название кнопки

• color (:class:Union[str, KeyboardColor]) – Цвет кнопки. Может быть значением из KeyboardColor

• payload (dict) – Опционально. Используется для некоторых кнопок

Исключение

vk_botting.VKApiError – Когда на строке уже слишком много кнопок

add_location_button(payload=None)

Добавляет кнопку местоположения на текущую строку

Параметры

payload (dict) – Информация для кнопки местоположения

Исключение

vk_botting.VKApiError – Когда на строке уже слишком много кнопок

add_vkpay_button(_hash, payload=None)

Добавляет кнопку на текущую строку

Параметры

• _hash (str) – Хэш для кнопки VKPay

• payload (dict) – Информация для кнопки VKPay

Исключение

vk_botting.VKApiError – Когда на строке уже слишком много кнопок

add_vkapps_button(app_id, owner_id, label, _hash, payload=None)

Добавляет кнопку на текущую строку

Параметры

• app_id (int) – Id приложения ВК

• owner_id (int) – Id владельца приложения ВК

• label (str) – Название кнопки

• _hash (str) – Хэш для кнопки VKApp

• payload (dict) – Опционально. Используется для некоторых кнопок

Исключение

vk_botting.VKApiError – Когда на строке уже слишком много кнопок

add_line()

Добавляет новую строку на клавиатуру

Исключение

vk_botting.VKApiError – Когда на клавиатуре уже слишком много кнопок

Кулдаун

vk_botting.commands.cooldown(rate, per, type=<BucketType.default: 0>)

Декоратор который добавляет кулдаун к экземпляру класса Command или его сабкласса.

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

Третий аргумент - тип, который должен быть значением BucketType, то есть может быть одним из:

• BucketType.default чтобы кулдаун считался на глобальной основе.

• BucketType.user - на основе пользователя.

• BucketType.conversation - на основе диалога.

• BucketType.member - на основе участника диалога.

Если кто-то пытается использовать команду при достигнутом кулдауне, то вызывается ошибка CommandOnCooldown, которую можно поймать в on_command_error() или локальном обработчике ошибок.

У команды может быть только один кулдаун

Параметры

• rate (int) – Количество раз, которое команда может быть использована до достижения кулдауна.

• per (float) – Количество секунд, которое необходимо ждать до следующего использования команды.

• type (BucketType) – Тип необходимого кулдауна.

class vk_botting.cooldowns.BucketType

Представляет собой тип бакета для кулдауна.

default = 0

По умолчанию. Работает на глобальной основе. По сути, считает использование команды любым пользователем где угодно в один бакет.

user = 1

Работает на основе пользователя. Считает использование команд конкретными пользователями вне зависимости от того, где эти пользователи использовали команду.

conversation = 2

Работает на основе беседы. Считает использование команд в конкретных беседах, вне зависимости от того, кто использовал команду и является ли эта беседа личным или групповым чатом.

member = 3

Работает на основе участника диалога. Участник тут - это пользователь в диалоге. Тот же пользователь сможет использовать команду в другом диалоге, и это будет считаться в другой бакет.

Модели VK

Модели - классы, которые получаются от VK и не должны быть созданы пользователем

Опасно

Классы ниже только для чтения

К примеру, это значит, что не стоит создавать или менять экземпляры класса User

User

class vk_botting.user.User(bot, data)

Представляет собой пользователя ВК

Класс имеет в себе много неиспользуемых атрибутов, которые основаны вокруг полей пользователя в VK API, так что можно посмотреть их в документации VK API

Все атрибуты могут быть None при недостатке информации

id

Id пользователя, положительное целое

тип

int

first_name

Имя пользователя

тип

str

last_name

Фамилия пользователя

тип

str

is_closed

True если страница пользователя закрыта

тип

bool

can_access_closed

True если у бота есть доступ к закрытой странице пользователя

тип

bool

sex

1 - женский, 2 - мужской, 0 - не определен

тип

int

async with typing()

Возвращает контекстный менеджер, который позволяет поддерживать состояние „печатает“ неопределенное количество времени

Может быть использовано для долгих операций бота в командах

Примечание

Может использоваться и как синхронный контекстный менеджер, и как асинхроный. То есть и with и async with будут работать

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

async with ctx.typing():
    # do expensive stuff here
    await ctx.send('done!')

await send(message=None, *, attachment=None, sticker_id=None, keyboard=None, reply_to=None, forward_messages=None)

Эта функция является корутиной.

Отправляет сообщение в ответ с данным текстом.

Текст должен быть типом, который можно преобразовать в строку с помощью str(message).

Если сообщение - None (по умолчанию), то должен быть предоставлен параметр attachment или sticker_id.

Если есть параметр attachment, он должен быть str, List[str], Attachment или List[Attachment]

Если есть параметр keyboard, он должен быть str или Keyboard (предпочтительно)

Параметры

• message (str) – Текст сообщения

• attachment (Union[List[str], str, List[Attachment], Attachment]) – Приложение к сообщению

• sticker_id (Union[str, int]) – Id стикера, который надо отправить

• keyboard (Keyboard) – Клавиатура, которую надо отправить вместе с сообщением

• reply_to (Union[str, int]) – Id сообщения, на которое надо ответить

• forward_messages (Union[List[int], List[str]]) – Id сообщений, которые надо переслать.

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Сообщение, которое было отправлено

Тип результата

Message

await trigger_typing()

Эта функция является корутиной.

Включает боту состояние „печатает“

Может быть использовано вместо typing() в некоторых случаях

Состояние „печатает“ выключается через 10 секунд или при отправке ответа

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Результат вызова к VK Api

Тип результата

dict

Group

class vk_botting.group.Group(data)

Представляет собой сообщество ВК

id

Id группы, положительное целое

тип

int

name

Название группы

тип

str

screen_name

Короткая ссылка на группу

тип

str

is_closed

True, если группа закрыта

тип

bool

type

Может быть`event`, group или page в зависимости от типа группы

тип

str

photo

Разные размеры фото группы

тип

dict

Message

class vk_botting.message.Message(data)

Представляет собой любое сообщение, отправленное или полученное ботом

Должно создаваться только через Bot.build_msg()

id

Id сообщения в диалоге

Предупреждение

Не пытайтесь использовать этот параметр в групповых чатах, так как он всегда будет 0 и будет вызывать ошибки

тип

int

date

Дата/время отправки сообщения

тип

datetime.datetime

update_time

Дата/время изменения сообщения

тип

datetime.datetime

peer_id

Id диалога, где отправлено сообщение

тип

int

from_id

Id автора сообщения

тип

int

text

Текст сообщения. Может быть пустым

тип

str

attachments

Список приложений к сообщению

тип

List[Attachment]

fwd_messages

Список пересланных сообщений

тип

List[Message]

reply_message

Сообщение, в ответ на которое было отправлено данное

тип

Message

action

Информация о действии

тип

Union[MessageAction, NoneType]

async with typing()

Возвращает контекстный менеджер, который позволяет поддерживать состояние „печатает“ неопределенное количество времени

Может быть использовано для долгих операций бота в командах

Примечание

Может использоваться и как синхронный контекстный менеджер, и как асинхроный. То есть и with и async with будут работать

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

async with ctx.typing():
    # do expensive stuff here
    await ctx.send('done!')

await edit(message=None, *, attachment=None, keep_forward_messages=1, keep_snippets=1)

Эта функция является корутиной.

Корутина для изменения сообщения

Параметры

• message (str) – Новый текст сообщения

• attachment (Union[List[str], str, List[Attachment], Attachment]) – Новые приложения к сообщению

• keep_forward_messages (bool) – True если стоит сохранить пересланные сообщения. По умолчанию True

• keep_snippets (bool) – True если стоит сохранить сниппеты. По умолчанию True

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Сообщение, которое было отправлено

Тип результата

Message

await delete(delete_for_all=1)

Эта функция является корутиной.

Корутина для удаления сообщения

Параметры

delete_for_all (bool) – True если стоит удалить сообщение для всех пользователей. По умолчанию True

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

await reply(message=None, **kwargs)

Эта функция является корутиной.

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

Текст должен быть типом, который можно преобразовать в строку с помощью str(message).

Если сообщение - None (по умолчанию), то должен быть предоставлен параметр attachment или sticker_id.

Если есть параметр attachment, он должен быть str, List[str], Attachment или List[Attachment]

Если есть параметр keyboard, он должен быть str или Keyboard (предпочтительно)

Параметры

• message (str) – Текст сообщения

• attachment (Union[List[str], str, List[Attachment], Attachment]) – Приложение к сообщению

• sticker_id (Union[str, int]) – Id стикера, который надо отправить

• keyboard (Keyboard) – Клавиатура, которую надо отправить вместе с сообщением

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Сообщение, которое было отправлено

Тип результата

Message

await get_user()

Эта функция является корутиной. Возвращает автора сообщения как экземпляр User class

await get_author()

Эта функция является корутиной. Альтернатива для Message.get_user()

await fetch_user()

Эта функция является корутиной. Альтернатива для Message.get_user()

await fetch_author()

Эта функция является корутиной. Альтернатива для Message.get_user()

await send(message=None, *, attachment=None, sticker_id=None, keyboard=None, reply_to=None, forward_messages=None)

Эта функция является корутиной.

Отправляет сообщение в ответ с данным текстом.

Текст должен быть типом, который можно преобразовать в строку с помощью str(message).

Если сообщение - None (по умолчанию), то должен быть предоставлен параметр attachment или sticker_id.

Если есть параметр attachment, он должен быть str, List[str], Attachment или List[Attachment]

Если есть параметр keyboard, он должен быть str или Keyboard (предпочтительно)

Параметры

• message (str) – Текст сообщения

• attachment (Union[List[str], str, List[Attachment], Attachment]) – Приложение к сообщению

• sticker_id (Union[str, int]) – Id стикера, который надо отправить

• keyboard (Keyboard) – Клавиатура, которую надо отправить вместе с сообщением

• reply_to (Union[str, int]) – Id сообщения, на которое надо ответить

• forward_messages (Union[List[int], List[str]]) – Id сообщений, которые надо переслать.

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Сообщение, которое было отправлено

Тип результата

Message

await trigger_typing()

Эта функция является корутиной.

Включает боту состояние „печатает“

Может быть использовано вместо typing() в некоторых случаях

Состояние „печатает“ выключается через 10 секунд или при отправке ответа

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Результат вызова к VK Api

Тип результата

dict

MessageEvent

class vk_botting.message.MessageEvent(data)

Представляет собой событие сообщения (https://vk.com/dev/bots_docs_5)

conversation_message_id

Id сообщения в диалоге

тип

int

user_id

Id пользователя, вызвавшего событие

тип

int

peer_id

Id диалога, где отправлено сообщение

тип

int

event_id

Уникальное id события (может быть использовано только один раз и только в течении следующей минуты)

тип

str

payload

Payload, отправленный вместе с кнопкой. Может быть None

тип

dict

await blank_answer()

Эта функция является корутиной.

Корутина, которая отправляет пустой ответ на событие (чтобы убрать анимацию загрузки на кнопке)

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Ответ сервера

Тип результата

dict

await show_snackbar(text)

Эта функция является корутиной.

Корутина для отправки ответа типа show_snackbar (показывает пользователю всплывающее уведомление)

Параметры

text (str) – Текст, который отобразится в уведомлении

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Ответ сервера

Тип результата

dict

await open_link(link)

Эта функция является корутиной.

Корутина для отправки ответа типа open_link (открывает у пользователя ссылку)

Параметры

link (str) – Ссылка, которую необходимо открыть

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Ответ сервера

Тип результата

dict

await open_app(app_id, owner_id, _hash)

Эта функция является корутиной.

Корутина для отправки ответа типа open_app (открывает у пользователя мини-приложение ВК)

Параметры

• app_id (int) – Id нужного приложения

• owner_id (Optional[int]) – owner_id этого приложения

• _hash (str) – Если честно, я не знаю для чего этот параметр (читайте доки вк)

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Ответ сервера

Тип результата

dict

Ошибки

class vk_botting.exceptions.VKException

Базовый класс ошибки для vk_botting

В идеале, он может быть использован для обработки всех ошибок, вызываемых библиотекой

class vk_botting.exceptions.VKApiError

Ошибка для большинства ошибок, возвращаемых VK Api в своих ответах

class vk_botting.exceptions.CommandError(message=None, *args)

Базовая ошибка для всех ошибок, связанных с командами

Является наследником VKException

Эта ошибка и ее наследники обрабатываются особым образом в специальном событии on_command_error()

class vk_botting.exceptions.CommandNotFound

Ошибка, вызываемая когда не найдена команда с подходящим именем

Не вызывается при неверных подкомандах

Является наследником CommandError

class vk_botting.exceptions.DisabledCommand(message=None, *args)

Ошибка, вызываемая, когда вызыванная команда выключена

Является наследником CommandError

class vk_botting.exceptions.CommandOnCooldown(cooldown, retry_after)

Ошибка, вызываемая когда вызыванная команда на кулдауне. Является наследником CommandError

cooldown

Класс с атрибутами rate, per и type, аналогичный декоратору cooldown()

тип

Кулдаун

retry_after

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

тип

float

class vk_botting.exceptions.CheckFailure(message=None, *args)

Ошибка, вызываемая при провале проверок из Command.checks

Является наследником CommandError

class vk_botting.exceptions.ClientException

Ошибка, вызываемая когда возникает проблема с Client

Обычно возникает из-за кривого ввода пользователя

class vk_botting.exceptions.CommandInvokeError(e)

Ошибка, вызываемая при возникновении ошибки при вызове команды. Наследник CommandError

original

Изначальная ошибка. Может быть получена с помощью атрибута __cause__

class vk_botting.exceptions.ArgumentError(message=None, *args)

Базовая ошибка для ошибок, связанных с аргументами команд

Является наследником CommandError

class vk_botting.exceptions.BadArgument(message=None, *args)

Ошибка, возникающая при ошибке парсинга или преобразования аргументов

Наследник ArgumentError

class vk_botting.exceptions.BadUnionArgument(param, converters, errors)

Ошибка, возникающая при ошибке преобразования к всем типам typing.Union. Наследник ArgumentError

param

Параметр, который не удалось преобразовать

тип

inspect.Parameter

converters

Кортеж использованных преобразователей

тип

Tuple[Type, ..]

errors

Список ошибок, вызванных проблемой при преобразовании

тип

List[CommandError]

class vk_botting.exceptions.MissingRequiredArgument(param)

Ошибка, возникшая при нехватке пропаршенных аргументов для команды

Наследник ArgumentError

param

Отсутствующий аргумент

тип

inspect.Parameter

class vk_botting.exceptions.TooManyArguments(message=None, *args)

Ошибка, возникающая когда команде было передано слишком много аргументов и атрибут Command.ignore_extra был на True

Наследник ArgumentError

class vk_botting.exceptions.ConversionError(converter, original)

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

converter

Преобразователь, который вызвал ошибку

тип

conversions.Converter

original

Изначальная ошибка. Может быть получена с помощью атрибута __cause__

class vk_botting.exceptions.ExtensionError(message=None, *args, name)

Базовая ошибка для ошибок, связанных с расширениями

Является наследником VKException

name

Расширение, вызвавшее ошибку

тип

str

class vk_botting.exceptions.ExtensionAlreadyLoaded(name)

Ошибка, вызванная когда расширение уже было загружено

Наследник ExtensionError

class vk_botting.exceptions.ExtensionNotLoaded(name)

Ошибка, вызываемая, когда расширение не загружено

Наследник ExtensionError

class vk_botting.exceptions.NoEntryPointError(name)

Ошибка, вызываемая, когда в расширении нет функции setup

Наследник ExtensionError

class vk_botting.exceptions.ExtensionFailed(name, original)

Ошибка, вызываемая когда расширение провалилось при выполнении или в функции setup

Наследник ExtensionError

name

Расширение, вызвавшее ошибку

тип

str

original

Изначальная ошибка. Может быть получена с помощью атрибута __cause__

тип

Exception

class vk_botting.exceptions.ExtensionNotFound(name, original)

Ошибка, вызываемая когда расширение не найдено

Наследник ExtensionError

name

Расширение, вызвавшее ошибку

тип

str

original

Тут могла быть ваша реклама ver.2

тип

NoneType

class vk_botting.exceptions.UnexpectedQuoteError(quote)

Ошибка, вызываемая когда парсер находит кавычку внутри строки, не ограниченной кавычками

Наследник ArgumentError

quote

Кавычка, найденная внутри строки, не ограниченной кавычками

тип

str

class vk_botting.exceptions.InvalidEndOfQuotedStringError(char)

Ошибка, вызываемая когда пробел должен быть после закрывающей кавычки, но найден другой символ

Наследник ArgumentError

char

Символ, найденный вместо пробела

тип

str

class vk_botting.exceptions.ExpectedClosingQuoteError(close_quote)

Ошибка, вызываемая когда ожидается кавычка, но ее нет

Наследник ArgumentError

close_quote

Ожидаемая кавычка

тип

str

class vk_botting.exceptions.LoginError

Ошибка, вызываемая когда боту не удается зайти с предоставленным токеном по какой-то причине

Дополнительные классы

class vk_botting.commands.GroupMixin(*args, **kwargs)

Mixin, который определяет часто используемый функционал для классов, которые могут регистрировать команды

all_commands

Связь названий команд с экземплярами Command или сабклассов

тип

dict

case_insensitive

Должны ли команды быть невосприимчивыми к регистру. По умолчанию False

тип

bool

commands

Уникальный набор команд без их альтернативных имен

тип

Set[Command]

add_command(command)

Добавляет команду Command или ее наследника в внутренний лист команд.

Обычно не вызывается, вместо него используется декораторы command().

Параметры

command (Command) – Команда, которую надо добавить.

Исключение

• ClientException – Если команда уже зарегистрирована.

• TypeError – Если команда не является сабклассом Command.

remove_command(name)

Удаляет команду (Command или сабкласс) из внутреннего списка команд.

Может быть использован и для удаления альтернативных названий.

Параметры

name (str) – Названия команды для удаления.

Результат

Удаленная команда. Если имя было неверным, то None

Тип результата

Command или сабкласс

for ... in walk_commands()

Итератор, который рекурсивно проходит по всем командам и подкомандам.

get_command(name)

Получает команду (Command или его сабкласс) из внутреннего списка команд

Может использоваться и чтобы получать альтернативные названия

К примеру, в случае с 'foo bar' вернет название подкоманды bar из группы команд foo. Если команда не найдена, вернет None

Параметры

name (str) – Название команды, которую надо получить

Результат

Запрошенная команда. Если не найдена, возвращает None.

Тип результата

Command или сабкласс

command(*args, **kwargs)

Декоратор, который добавляет команду в внутренний лист через add_command()

class vk_botting.commands.Command(func, **kwargs)

Класс, определяющий текстовую команду бота

Не создаются вручную, вместо этого они создаются с помощью декоратора

name

Название команды

тип

str

callback

Корутина, вызываемая, когда вызвана команда

тип

coroutine

aliases

Список альтернативных названий для команды

тип

list

enabled

Логическая переменная, обозначающая что команда включена. По умолчанию True

тип

bool

parent

Родительская команда для данной. None если таковой нет

тип

Optional[Command]

cog

Cog, к которому принадлежит команда. None если такого нет

тип

Optional[Cog]

checks

Список проверок, которые подтверждают, что команда должна быть вызвана, принимающих на вход Context как единственный параметр. Если команда не проходит проверки, то в on_command_error() подается CheckFailure

тип

List[Callable[…, bool]]

rest_is_raw

Если False и есть аргумент с ключевым словом, то он обрабатывается как обычный аргумент, который обрабатывает MissingRequiredArgument и значения по умолчанию как обычно вместо того, чтобы передавать аргумент как сырую строку

тип

bool

invoked_subcommand

Подкоманда, которая была вызвана, если такая есть

тип

Optional[Command]

ignore_extra

Если True, игнорирует лишние аргументы, переданные команде. Иначе вызывается TooManyArguments

тип

bool

cooldown_after_parsing

Если True, то обработка перезарядки происходит после парсинга аргументов, иначе до

тип

bool

add_check(func)

Добавляет проверку к команде. Это check(), только без декоратора

Параметры

func – Функция, которая будет использоваться для проверки

remove_check(func)

Удаляет проверку с команды. Если такой проверки нет, не вызовет ошибку

Параметры

func – Функция, которую необходимо удалить из проверок

update(**kwargs)

Обновляет экземпляр Command с новыми атрибутами

Работает аналогично декоратору command() в плане параметров

copy()

Создает копию команды

clean_params

Получает параметр OrderedDict без параметров контекста и self

Удобно для исследования подписей

full_parent_name

Получает имя команды

Базовое имя команды, которое необходимо для ее выполнения

тип

str

parents

Получает родительские команды для данной

Если у команды нет родительских команд, то возвращает пустой list

К примеру для команды ?a b c test родительские команды - [c, b, a]

тип

Command

root_parent

Получает коренные родительские команды данной

Если у команды нет родительских команд, возвращает None

К примеру в команде ?a b c test вернет a

qualified_name

Получает имя команды

Это полное имя родительских команд и самой команды

тип

str

is_on_cooldown(ctx)

Проверяет на перезарядке ли команда

Параметры

ctx (Context) – Контекст вызова команды для проверки на перезарядку

Результат

Логическая переменная, показывающая на перезарядке ли команда

Тип результата

bool

reset_cooldown(ctx)

Обнуляет перезарядку команды

Параметры

ctx (Context) – Контест команды, перезарядку которой надо обнулить

error(coro)

Декоратор, который регистрирует корутину как локальный обработчик ошибок

Локальный обработчик ошибок это on_command_error(), работающий только на одну команду

Параметры

coro (coroutine) – Корутина, регистрируемая как локальный обработчик ошибок

Исключение

TypeError – Переданная корутина на самом деле не корутина

before_invoke(coro)

Декоратор, который вызывает корутину прямо перед вызовом команды

Удобно чтобы подготовить подключения, например

Корутина должна принимать один параметр - Context

См. Bot.before_invoke() для дополнительной информации

Параметры

coro (coroutine) – Корутина, которую надо привязать до вызова команды

Исключение

TypeError – Переданная корутина на самом деле не корутина

after_invoke(coro)

Декоратор, вызывающий корутину сразу после вызова команды

Удобно использовать для чистки подключений и еще чего-нибудь

Сама корутина должна принимать один параметр - Context

См. Bot.after_invoke() для дополнительной информации

Параметры

coro (coroutine) – Корутина, которую надо зарегистрировать как привязанное после вызова

Исключение

TypeError – Переданная корутина на самом деле не корутина

cog_name

Имя cog’а, к которому принадлежит команда. Если такого нет, то None

тип

str

await can_run(ctx)

Эта функция является корутиной.

Проверяет, может ли команда быть вызвана засчет проверки всех проверок внутри атрибута checks. Еще проверяет, выключена ли команда

Параметры

ctx (Context) – Параметр ctx вызванной команды

Исключение

CommandError – Любая ошибка, возникшая во время выполнения функции будет обработана этой функцией

Результат

Логическая переменная, обозначающая может ли команда быть вызвана

Тип результата

bool

class vk_botting.client.Client(**kwargs)

Класс, представляющий собой Клиент для взаимодействий с VK Api

Предупреждение

Не должен использоваться вне класса Bot, так как не будет работать

exception botCommandException

wait_for(event, *, check=None, timeout=None)

Эта функция является корутиной.

Ожидает определенное событие.

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

Параметр timeout передается напрямую в asyncio.wait_for(). По умолчанию, ждет неопределенно долго. Учтите, что в случае истечения времени вызывается asyncio.TimeoutError.

В случае если событие возвращает множество аргументов, возвращается tuple, содержащий их. Пожалуйста, обращайтесь к documentation для справки о событиях и их параметрах

Функция возвращает первое событие, удовлетворяющее условиям

Примеры

Ожидание ответа пользователя:

@bot.command()
async def greet(ctx):
    await ctx.send('Say hello!')
    def check(m):
        return m.text == 'hello' and m.from_id == ctx.from_id
    msg = await bot.wait_for('message_new', check=check)
    await ctx.send('Hello {.from_id}!'.format(msg))

Параметры

• event (str) – Название события, как и в event reference, но без префикса on_.

• check (Optional[Callable[…, bool]]) – Проверка для события, которое надо ожидать. Аргументы должны соответствовать параметрам события, который ожидается.

• timeout (Optional[float]) – Количество секунд для ожидания. По истечении вызывает asyncio.TimeoutError.

Исключение

asyncio.TimeoutError – Если время ожидание было предоставлено и достигнуто

Результат

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

Тип результата

Any

await vk_request(method, post=True, **kwargs)

Эта функция является корутиной.

Реализует абстрактный запрос к методам VK Api

Параметры

• method (str) – Название метода в виде строки (к примеру „users.get“)

• post (bool) – Должен ли запрос быть POST. По умолчанию True. Не рекомендуется менять этот параметр.

• kwargs (Any) – Аргументы для отправки вместе с запросом. .. note:: access_token и v отправлять не надо, они автоматически добавляются из настроек текущего бота

Результат

Ответ от сервера, представленный в виде dict

Тип результата

dict

await user_vk_request(method, post=True, **kwargs)

Эта функция является корутиной.

Реализует абстрактный запрос к методам VK Api с помощью прикрепленного токена пользователя.

Параметры

• method (str) – Название метода в виде строки (к примеру „users.get“)

• post (bool) – Должен ли запрос быть POST. По умолчанию True. Не рекомендуется менять этот параметр.

• kwargs (Any) – Аргументы для отправки вместе с запросом. .. note:: access_token и v отправлять не надо, они автоматически добавляются из настроек текущего бота

Результат

Ответ от сервера, представленный в виде dict

Тип результата

dict

await get_users(*uids, fields=None, name_case=None)

Эта функция является корутиной.

Альтернатива методу „users.get“ VK API

Параметры

• uids (List[int]) – Список id пользователей для запроса

• fields (List[str]) – Опционально. Поля, которые должны быть запрошены у API. По умолчанию никакие

• name_case (str) – Опционально. Падеж имен пользователей. По умолчанию „nom“. Можеть быть „nom“, „gen“, „dat“, „acc“, „ins“ или „abl“

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Список экземпляров User для запрошенных пользователей

Тип результата

List[User]

await get_groups(*gids)

Эта функция является корутиной.

Альтернатива для метода „groups.get“ VK API

Параметры

gids (List[int]) – Список id групп, которые надо запросить

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Список экземпляров Group для запрошенных групп

Тип результата

List[Group]

await get_pages(*ids, fields=None, name_case=None)

Эта функция является корутиной.

Получает страницы для запрошенных id, вне зависимости от того, группа это или пользователь

Параметры

• ids (List[int]) – Список id для запроса

• fields (List[str]) – Опционально. Поля, которые должны быть запрошены у API. По умолчанию никакие

• name_case (str) – Опционально. Падеж имен пользователей. По умолчанию „nom“. Можеть быть „nom“, „gen“, „dat“, „acc“, „ins“ или „abl“

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Список экземпляров Group или User для запрошенных id

Тип результата

List[Union[Group, User]]

await get_user(uid, fields=None, name_case=None)

Эта функция является корутиной.

Альтернатива методу „users.get“ VK API, возвращает только одного пользователя

Параметры

• uid (int) – Id запрашиваемого пользователя

• fields (List[str]) – Опционально. Поля, которые должны быть запрошены у API. По умолчанию никакие

• name_case (str) – Опционально. Падеж имени пользователя. По умолчанию - „nom“. Можеть быть „nom“, „gen“, „dat“, „acc“, „ins“ или „abl“

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Экземпляр класса User для запрошенного пользователя

Тип результата

User

await get_group(gid)

Эта функция является корутиной.

Альтернатива для метода „groups.get“ VK API, возвращает только одну группу

Параметры

gid (int) – Id группы, которую надо запросить

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Экземпляр Group для запрошенной группы

Тип результата

Group

await get_page(pid, fields=None, name_case=None)

Эта функция является корутиной.

Получает страницу с данным id, вне зависимости от того, группа это или пользователь

Параметры

• pid (int) – Id запрашиваемой страницы

• fields (List[str]) – Опционально. Поля, которые должны быть запрошены у API. По умолчанию никакие

• name_case (str) – Опционально. Падеж имени пользователя. По умолчанию - „nom“. Можеть быть „nom“, „gen“, „dat“, „acc“, „ins“ или „abl“

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Экземпляр Group или User для запрошенного id

Тип результата

Union[Group, User]

await get_own_page()

Эта функция является корутиной.

Получает страницу для текущего токена, вне зависимости от того, пользователь это или группа

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Экземпляр Group или User в зависимости от токена

Тип результата

Union[Group, User]

await upload_image_to_server(server, filename=None, url=None, raw=None, format=None)

Эта функция является корутиной.

Загружает изображение на какой-то сервер ВК.

Возвращает dict, представляющий собой ответ сервера.

Параметры

• server (str) – Url сервера для загрузки. Может быть получен от API с помощью методов подобных photos.getUploadServer.

• filename (str) – Путь к изображению, которое надо загрузить. Может быть относительным.

• url (str) – Ссылка на изображение, которое надо загрузить. Это должна быть прямая ссылка на поддерживаемый формат изображений, иначе не сработает.

• raw (bytes) – Сырые байты изображения, которое надо загрузить. Если используется, надо передать параметр format.

• format (str) – Расширение загружаемого изображения. Должно быть использовано только вместе с сырыми байтами.

Результат

dict, представляющий собой ответ сервера.

Тип результата

dict

await upload_document(peer_id, file, type=<DocType.DOCUMENT: 'doc'>, title=None)

Эта функция является корутиной.

Загружает документ в диалог с данным peer_id

Возвращает attachment, готовый к использованию в send_message

Параметры

• peer_id (int) – Peer_id назначения. Загруженный документ нельзя использовать вне данного диалога.

• file (str) – Путь к документу, который надо загрузить. Может быть относительным.

• type (str) – Тип загруженного документа. Может быть значением из DocType

• title (str) – Название для загруженного документа. По умолчанию имя файла.

Результат

Экземпляр Attachment, представляющий загруженный документ

Тип результата

Attachment

await upload_photo(peer_id, filename=None, url=None, raw=None, format=None)

Эта функция является корутиной.

Загружает изображение в диалог с данным peer_id

Возвращает attachment, готовый к использованию в send_message

Параметры

• peer_id (int) – Peer_id назначения. Загруженное изображение нельзя использовать вне данного диалога

• filename (str) – Путь к изображению, которое надо загрузить. Может быть относительным.

• url (str) – Ссылка на изображение, которое надо загрузить. Это должна быть прямая ссылка на поддерживаемый формат изображений, иначе не сработает.

• raw (bytes) – Сырые байты изображения, которое надо загрузить. Если используется, надо передать параметр format.

• format (str) – Расширение загружаемого изображения. Должно быть использовано только вместе с сырыми байтами.

Результат

Экземпляр Attachment, представляющий загруженное фото.

Тип результата

Attachment

build_msg(msg)

Создает экземпляр класса Message из dict, содержащего объект сообщения.

В нормальных условиях не должна вызываться вообще

Параметры

msg (dict) – dict, представляющий объект сообщения, полученный от VK API

Результат

Экземпляр Message, представляющий изначальное сообщение

Тип результата

Message

await on_error(event_method, *args, **kwargs)

Эта функция является корутиной.

Обработчик ошибок, предоставляемый ботом.

По умолчанию выводит информацию о ошибке в sys.stderr, но может быть переобъявлен, чтобы делать что-то другое.

Посмотрите vk_botting.on_error() для более детального объяснения

await send_message(peer_id=None, message=None, attachment=None, sticker_id=None, keyboard=None, reply_to=None, forward_messages=None, forward=None, **kwargs)

Эта функция является корутиной.

Отправляет сообщение данному получателю с данным текстом

Текст должен быть типом, который можно преобразовать в строку с помощью str(message).

Если сообщение - None (по умолчанию), то должен быть предоставлен параметр attachment или sticker_id.

Если есть параметр attachment, он должен быть str, List[str], Attachment или List[Attachment]

Если есть параметр keyboard, он должен быть str или Keyboard (предпочтительно)

Параметры

• peer_id (int) – Id получателя сообщения

• message (str) – Текст сообщения

• attachment (Union[List[str], str, List[Attachment], Attachment]) – Приложение к сообщению

• sticker_id (Union[str, int]) – Id стикера, который надо отправить

• keyboard (Keyboard) – Клавиатура, которую надо отправить вместе с сообщением

• reply_to (Union[str, int]) – Id сообщения, на которое надо ответить

• forward_messages (Union[List[int], List[str]]) – Id сообщений, которые надо переслать.

• forward (dict) – Для дополнительной информации смотрите документацию.

• as_user (bool) – Должно ли сообщение быть отправлено от имени пользователя (с использованием присоединенного токена)

Исключение

vk_botting.VKApiError – Если VK API возвращает ошибку

Результат

Сообщение, которое было отправлено

Тип результата

Message

await add_user_token(token)

Эта функция является корутиной. Альтернатива для Context.attach_user_token()

await attach_user_token(token)

Эта функция является корутиной.

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

Также помещает в self.user экземпляр класса User соответствующий предоставленному токену

Параметры

token (str) – Токен пользователя, который необходимо прикрепить

run(token, owner_id=None)

Блокирующий вызов, который позволяет не инициализировать цикл самостоятельно.

Предупреждение

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

Параметры

• token (str) – Токен бота. Должен быть токеном группы или токеном пользователя с доступом к группе.

• owner_id (int) – Должен отправляться только вместе с токеном пользователя. Id группы, к которой надо подключиться

vk_botting.commands.command(name=None, cls=None, **attrs)

Декоратор который преобразует функцию в класс Command.

Все проверки, добавленные с помощью check() и подобных, привязываются к функции. Через сам этот декоратор нельзя передать проверки.

Параметры

• name (str) – Название, с которым надо создать команду. По умолчанию - название функции без изменений.

• cls – Класс, с помощью которого надо создать команду. По умолчанию - класс Command. Обычно этот параметр менять не стоит.

• attrs – Аргументы с ключевыми словами, которые передаются при создании класса, указанного в cls.

Исключение

TypeError – Если функция не является корутиной или уже является командой.