从discord.py v0.9.0迁移到v0.10.0的全面指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01048/article/details/148377405

从discord.py v0.9.0迁移到v0.10.0的全面指南

discord.py An API wrapper for Discord written in Python. 项目地址: https://gitcode.com/gh_mirrors/di/discord.py

前言

discord.py v0.10.0版本是该库历史上最重要的更新之一，它引入了异步编程模型，彻底改变了库的工作方式。本文将详细介绍从v0.9.0迁移到v0.10.0需要注意的所有关键变化，帮助开发者顺利完成过渡。

Python版本要求变更

v0.10.0版本放弃了Python 2.7和3.3的支持，最低要求提升至Python 3.4.2。这一变更是为了全面支持asyncio异步编程框架。如果你仍在使用旧版本Python，升级Python环境是使用新版本库的前提条件。

事件处理机制的改变

事件注册方式

在v0.9.0中，事件处理函数可以直接使用@client.event装饰器注册。但在v0.10.0中，所有事件处理函数必须声明为协程：

旧方式:

@client.event
def on_message(message):
    pass

新方式:

@client.event
@asyncio.coroutine
def on_message(message):
    pass

Python 3.5+可以使用更简洁的语法:

@client.event
async def on_message(message):
    pass

为了简化代码，库提供了@client.async_event装饰器，它会自动将函数转换为协程:

@client.async_event
def on_message(message):
    pass

事件参数变化

多个事件的处理方式进行了优化，特别是那些原本只提供单一状态的事件：

on_channel_update、on_member_update等事件现在接收before和after两个参数，分别表示变更前后的状态
on_status事件被移除，其功能由on_member_update替代
移除了几个底层socket事件：on_socket_closed、on_socket_receive和on_socket_opened

全面转向协程

v0.10.0最重大的变化是几乎所有Client类的方法都变成了协程。这意味着调用这些方法时需要使用yield from(Python 3.4)或await(Python 3.5+)语法。

旧方式:

client.send_message(message.channel, 'Hello')

新方式:

yield from client.send_message(message.channel, 'Hello')
# 或Python 3.5+
await client.send_message(message.channel, 'Hello')

注意：调用协程的函数本身也必须是协程，需要使用@asyncio.coroutine或async def装饰。

数据结构优化

为了提高性能，许多内部数据结构从列表改为字典，这影响了部分API属性：

Client.servers
Client.private_channels
Server.channels
Server.members

这些属性现在返回的是可迭代对象而非列表，因此不再支持索引操作：

不再有效:

if client.servers[0].name == "test":
    # 操作

正确方式:

servers = list(client.servers)
# 现在可以像列表一样操作

注意：迭代顺序不再保证固定，这是性能优化的副作用。

枚举类型的引入

得益于Python 3.4.2+的支持，库现在使用标准库enum替代字符串常量：

旧方式:

server.region == 'us-west'
member.status == 'online'
channel.type == 'text'

新方式:

server.region == discord.ServerRegion.us_west
member.status = discord.Status.online
channel.type == discord.ChannelType.text

这种改变提高了代码的可靠性和可维护性，避免了拼写错误等问题。

方法到属性的转换

许多返回常量值的函数被改为属性，使代码更简洁，特别是在格式化字符串时：

| 旧方法 | 新属性 | |--------|--------| | User.avatar_url() | User.avatar_url | | User.mention() | User.mention | | Channel.mention() | Channel.mention | | Server.get_default_role() | Server.default_role |

成员管理API变更

封禁和踢出成员的API变得更直观：

旧方式:

client.ban(server, user)
client.kick(server, user)

新方式:

client.ban(member)
client.kick(member)

方法重命名

部分方法进行了重命名以提高一致性：

Client.set_channel_permissions → Client.edit_channel_permissions
权限相关属性移除了can_前缀，如can_manage_messages → manage_messages

强制关键字参数

为了减少参数顺序导致的错误，部分方法的关键参数变为强制关键字参数：

# 必须明确指定参数名
client.send_message(channel, "Hello", tts=True)
client.logs_from(channel, before=some_time)

客户端运行方式变更

client.run()方法现在集成了登录功能，并自动处理事件循环：

旧方式:

client.login('token')
client.run()

新方式:

client.run('token')

如果需要更精细的控制，可以手动管理事件循环：

import discord
import asyncio

client = discord.Client()

@asyncio.coroutine
def main_task():
    yield from client.login('token')
    yield from client.connect()

loop = asyncio.get_event_loop()
try:
    loop.run_until_complete(main_task())
except:
    loop.run_until_complete(client.logout())
finally:
    loop.close()