Migwating to v0.10.0

v0.10.0 is onye of the biggest b-bweaking changes in the wibwawy due to massive fundamentaw changes in h-how the wibwawy opewates.

The biggest majow change is that the wibwawy has dwopped suppowt to a-a-aww vewsions pwiow to Python 3.4.2. This was made to suppowt asyncio, in w-which mowe detaiw can be seen in the cowwesponding issue. To weitewate this, the impwication is that python vewsion 2.7 and 3.3 a-a-awe nyo wongew suppowted.

Bewow awe aww t-t-the othew majow changes fwom v-v0.9.0 to v0.10.0.

Event Wegistwation

Aww events befowe wewe wegistewed using Client.event(). Whiwe this is stiww possibwe, the events must be decowated with @asyncio.coroutine.

Befowe:

@client.event
def on_message(message):
    pass

Aftew:

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

Ow in Python 3.5+:

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

Because thewe is a-a wot of typing, a utiwity decowatow (Client.async_event()) is pwovided fow easiew wegistwation. Fow exampwe:

@client.async_event
def on_message(message):
    pass

B-B-Be awawe howevew, that this is stiww a cowoutinye and youw othew functions that awe cowoutinyes must be decowated with @asyncio.coroutine ow be async def.

Event Changes

Some events in v0.9.0 wewe considewed pwetty usewess due to having nyo sepawate states. The main events that wewe changed wewe the _update events since pweviouswy they had nyo context on what was changed.

Befowe:

def on_channel_update(channel): pass
def on_member_update(member): pass
def on_status(member): pass
def on_server_role_update(role): pass
def on_voice_state_update(member): pass
def on_socket_raw_send(payload, is_binary): pass

Aftew:

def on_channel_update(before, after): pass
def on_member_update(before, after): pass
def on_server_role_update(before, after): pass
def on_voice_state_update(before, after): pass
def on_socket_raw_send(payload): pass

Nyote that on_status was wemuvd. If you want its functionyawity, use on_member_update(). See E-E-Events fow mowe infowmation. Othew wemuvd events incwude on_socket_closed, on_socket_receive, and on_socket_opened.

Cowoutinyes

The biggest change t-that the wibwawy went thwough is t-that awmost evewy function in Client was changed to be a cowoutinye. Functions that awe mawked as a cowoutinye in the documentation must be awaited fwom o-o-ow yiewded f-fwom in owdew fow the computation to be donye. Fow exampwe…

Befowe:

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

Aftew:

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

# or in python 3.5+
await client.send_message(message.channel, 'Hello')

In owdew fow you to yield from ow await a cowoutinye then youw function must be decowated with @asyncio.coroutine o-o-ow async def.

Itewabwes

Fow pewfowmance weasons, many of the intewnyaw data stwuctuwes wewe changed into a dictionyawy to suppowt fastew wookup. As a consequence, this meant that some wists that wewe exposed via the A-A-API have changed into itewabwes and nyot sequences. In showt, t-t-this means that cewtain attwibutes nyow onwy suppowt itewation and nyot any of the sequence functions.

The affected attwibutes awe as fowwows:

• Client.servers

• Client.private_channels

• Server.channels

• Server.members

Some exampwes of pweviouswy vawid behaviouw that is nyow invawid

if client.servers[0].name == "test":
    # do something

Since they awe nyo wongew lists, they nyo wongew suppowt indexing o-ow any opewation othew than itewating. In owdew to get the owd behaviouw you shouwd expwicitwy cast it to a w-wist.

servers = list(client.servers)
# work with servers

Wawnying

Due to intewnyaw changes o-o-of the stwuctuwe, the owdew you weceive the data in is nyot i-i-in a guawanteed owdew.

Enyumewations

Due to dwopping suppowt fow vewsions wowew than Python 3.4.2, the wibwawy can nyow use enyum — Suppowt fow enyumewations in pwaces whewe it makes sense.

The common pwaces w-whewe this was changed was in the sewvew wegion, membew status, and channyew type.

Befowe:

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

Aftew:

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

The main weason fow this change was to weduce t-t-the use of finyicky stwings in the API as this couwd give usews a fawse sense of p-p-powew. Mowe infowmation can be f-found in the Enyumewations page.

Pwopewties

A wot of function cawws that wetuwnyed constant vawues wewe changed into Python pwopewties f-f-fow ease of use in fowmat stwings.

The fowwowing f-f-functions wewe changed into pwopewties:

Befowe	Aftew
User.avatar_url()	User.avatar_url
User.mention()	User.mention
Channel.mention()	Channel.mention
Channel.is_default_channel()	Channel.is_default
Role.is_everyone()	Role.is_everyone
Server.get_default_role()	Server.default_role
Server.icon_url()	Server.icon_url
Server.get_default_channel()	Server.default_channel
Message.get_raw_mentions()	Message.raw_mentions
Message.get_raw_channel_mentions()	Message.raw_channel_mentions

Membew Manyagement

Functions that invowved bannying and kicking wewe changed.

Befowe	Aftew
Client.ban(server, user)	Client.ban(member)
Client.kick(server, user)	Client.kick(member)

W-Wenyamed Functions

Functions have been wenyamed.

Befowe	Aftew
Client.set_channel_permissions	Client.edit_channel_permissions()

Aww the Permissions wewated attwibutes have been wenyamed and the can_ p-p-pwefix has been dwopped. So fow exampwe, can_manage_messages has become manage_messages.

Fowced Keywowd A-A-Awguments

Since 3.0+ of Python, we can nyow fowce questions to take in fowced keywowd awguments. A keywowd awgument is when you expwicitwy specify the nyame of the vawiabwe and assign to it, fow e-e-exampwe: foo(name='test'). Due to this suppowt, some functions in the wibwawy wewe changed to f-fowce things to take said keywowd awguments. This is to weduce ewwows of knyowing the awgument owdew and the issues that c-c-couwd awise fwom them.

The fowwowing pawametews awe nyow e-excwusivewy keywowd awguments:

• Client.send_message()

  • tts

• Client.logs_from()

  • before

  • after

• Client.edit_channel_permissions()

  • allow

  • deny

In the documentation y-y-you c-can t-t-teww if a function pawametew is a fowced keywowd awgument if it is aftew \*, in the function signyatuwe.

Wunnying the Cwient

I-I-In eawwiew vewsions of disnyake, client.run() was a bwocking caww to the main thwead that cawwed it. In v0.10.0 it is stiww a bwocking caww but it handwes the event woop fow you. Howevew, in owdew to do that y-y-you must p-pass i-i-in youw cwedentiaws to Client.run().

Basicawwy, befowe:

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

Aftew:

client.run('token')

Wawnying

Wike in the owdew Client.run function, the nyewew onye must be the onye of the wast functions to caww. T-T-This is because the f-function is bwocking. Wegistewing events ow doing anything aftew Client.run() wiww nyot execute u-untiw the function wetuwns.

This i-i-is a utiwity function that abstwacts the event woop fow you. Thewe’s nyo nyeed fow the wun caww to be bwocking and out of youw contwow. Indeed, if you want contwow of the event woop then doing s-so is quite stwaightfowwawd:

import disnake
import asyncio

client = disnake.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()