Модерация сервера почти всегда начинается с пары команд: блокировка нарушителя и снятие блокировки. Если бан реализуют в первую очередь, то разбан нередко делают наспех, из-за чего бот падает с ошибками, не находит пользователя или не имеет прав на действие. В этой статье разберём, как создать команду unban с помощью discord.py, какие настройки нужны для её работы и с какими проблемами сталкиваются разработчики на практике.
Как работает разбан в Discord и зачем нужна отдельная команда
Когда участника банят, он исчезает из списка сервера, а его учётная запись попадает в список блокировок гильдии. Снять бан можно вручную через настройки сервера, но для активной модераторской команды это неудобно: нужно открывать интерфейс, искать пользователя, подтверждать действие. Команда в боте позволяет сделать то же самое одной строкой и сразу записать причину в журнал аудита.
Важно понимать главное отличие от бана: участника, которого уже нет на сервере, нельзя найти среди обычных участников. Поэтому для разбана используют не объект участника, а объект пользователя или просто его числовой идентификатор. Именно на этом моменте спотыкается большинство начинающих авторов ботов.
Что подготовить перед написанием команды
Прежде чем писать код, убедитесь, что выполнены базовые условия. Без них даже идеально написанная функция не заработает.
- Актуальная версия библиотеки. Пользуйтесь второй мажорной веткой discord.py: в ней есть слэш-команды, удобные интенты и асинхронные итераторы для списка банов.
- Бот с нужными правами. В настройках роли бота должно быть включено право «Банить участников». Именно оно отвечает и за блокировку, и за снятие блокировки.
- Правильная позиция роли. Роль бота должна находиться в списке ролей достаточно высоко, иначе часть действий окажется недоступной.
- Интенты. Для разбана по ID достаточно стандартных интентов. Если вы планируете префиксные команды, понадобится ещё и интент содержимого сообщений, включённый и в коде, и в панели разработчика.
- Токен и безопасное хранение. Токен бота держите в переменных окружения, а не в файле с исходным кодом.
Базовая логика команды unban
Самая надёжная схема выглядит так: команда принимает идентификатор пользователя и необязательную причину, затем вызывает метод guild.unban, передав ему объект с этим идентификатором. Для создания такого объекта достаточно использовать discord.Object с параметром id. Загружать полный профиль пользователя при этом не требуется.
Порядок действий в функции обычно следующий:
- Проверить, что команда вызвана на сервере, а не в личных сообщениях.
- Преобразовать введённое значение в целое число и обработать ошибку, если там оказались буквы.
- Отложить ответ методом defer, если операция может занять больше пары секунд.
- Вызвать guild.unban с идентификатором и причиной.
- Отправить подтверждение, желательно скрытое от остальных участников.
- Записать событие в канал журнала модерации.
Причина, которую вы передаёте в метод, попадает в журнал аудита сервера. Её длина ограничена пятьюстами двенадцатью символами, поэтому длинные комментарии лучше обрезать заранее.
Слэш-команда или префиксная: что выбрать
Сегодня разумнее делать слэш-команды. Они подсказывают пользователю параметры, проверяют типы на стороне Discord и не требуют интента содержимого сообщений. Для ограничения доступа используйте проверку has_permissions с параметром ban_members, а при желании скрывайте команду от обычных участников через настройки интеграций сервера.
Префиксные команды остаются в качестве запасного варианта для небольших проектов. У них проще синтаксис, но больше ограничений: нужен доступ к тексту сообщений, а пользователь легко ошибается в написании параметров.
Не забудьте синхронизировать дерево команд методом tree.sync. Частая ситуация: код написан правильно, а команда не появляется в списке, потому что синхронизация не выполнялась или выполнялась для другого сервера.
Как улучшить удобство: автодополнение и список банов
Вводить длинные идентификаторы вручную неудобно. Чтобы упростить работу модераторов, добавьте автодополнение. Оно получает список заблокированных пользователей через асинхронный итератор guild.bans и подставляет подходящие варианты по мере ввода.
Учтите несколько ограничений:
- Discord показывает не более двадцати пяти вариантов в подсказке, поэтому результат нужно фильтровать по введённому фрагменту.
- На крупных серверах список банов может быть большим, и запрашивать его при каждом нажатии клавиши расточительно. Кэшируйте результат на короткое время.
- Подсказка должна отвечать быстро: на автодополнение отводится всего несколько секунд.
Если пользователь вводит имя, а не число, команда должна найти запись в списке банов и взять идентификатор оттуда. Сравнивайте имена без учёта регистра и всегда обрабатывайте случай, когда найдено несколько совпадений.
Типичные проблемы и способы их решения
Ошибка Forbidden: недостаточно прав
Исключение discord.Forbidden означает, что у бота нет права банить участников либо его роль расположена ниже нужной. Проверьте права роли на сервере и на уровне канала, а также убедитесь, что бот не был приглашён по ссылке без нужных разрешений. Иногда помогает повторное добавление бота с правильным набором прав.
Ошибка NotFound: пользователь не в списке банов
Исключение discord.NotFound возникает, если указанный идентификатор не заблокирован или введён с ошибкой. Перехватывайте его и отвечайте понятным сообщением вроде «Пользователь не найден среди заблокированных». Перед разбаном можно вызвать guild.fetch_ban, чтобы заранее проверить наличие блокировки.
Команда не отвечает и показывает «приложение не отвечает»
Discord ждёт ответ на слэш-команду около трёх секунд. Если вы делаете запросы к базе данных или перебираете большой список банов, используйте defer, а итоговое сообщение отправляйте через followup.
Неверный идентификатор
Слэш-команда может принимать идентификатор как строку, потому что числа в Discord бывают слишком большими для целочисленного типа параметра. Принимайте строку, затем безопасно преобразуйте её в число внутри функции и обрабатывайте ValueError.
Команда работает на одном сервере и не работает на другом
Причина обычно в разных правах бота или в том, что команда была синхронизирована только для тестовой гильдии. Проверьте настройки интеграций и повторите синхронизацию.
Ограничения частоты запросов
При массовом разбане Discord может замедлить ответы из-за лимитов. Библиотека справляется с этим автоматически, но лучше добавлять небольшую паузу между операциями и не запускать сотни разбанов одновременно.
Практические советы по надёжности и безопасности
- Ограничьте доступ. Не полагайтесь только на скрытие команды: добавьте программную проверку прав у вызывающего.
- Ведите журнал. Фиксируйте, кто, когда и по какой причине снял блокировку. Это упрощает разбор спорных ситуаций.
- Используйте скрытые ответы. Подтверждение действия вместе с идентификаторами лучше показывать только модератору.
- Логируйте исключения. Неожиданные ошибки HTTPException сохраняйте в файл или канал отладки с трассировкой.
- Тестируйте на отдельном сервере. Создайте закрытую площадку и проверяйте на ней бан, разбан, неверные идентификаторы и отсутствие прав.
- Разделяйте код. Выносите команды модерации в отдельный модуль (cog), чтобы их было проще обновлять и отключать.
Вывод
Команда разбана в discord.py строится на простой идее: передать в guild.unban идентификатор, обработать типичные исключения и аккуратно сообщить результат модератору. Основные сложности связаны не с самим кодом, а с окружением: правами бота, иерархией ролей, синхронизацией слэш-команд и корректной обработкой ввода. Если заранее учесть эти моменты, добавить автодополнение и журналирование, команда станет удобным и надёжным инструментом модерации вашего сервера.
