This is a discord library that provides a low-level interface to the discord API. You'll need discord's API documentation open for which parameters a function accepts to use this.
They key defining point of this library is that it's the only one that doesn't use asyncio (as far as I have been able to find). No asyncio means we no longer are relient on every library we use to support asyncio, we can do whatever we want! It also means easy integration with libraries like cherrypy (for which this library includes a plugin under utils.cherrypy).
The organisation of the library is as follows:
- The discord api reference is used as basis
- In the left sidebar of the api reference, under HTTP API Resources, there is a whole list of resources. Expect to find the stuff described in the page for said resource to be in a submodule with the same name (for example all methods from the Message resource is under discord.message).
- The library adds a few new methods to control the library itself:
- The discord module itself contains 3 methods, see below
- discord.gateway allows access to the gateway, see below
Apart from the many submodules equivaling discord resources, the discord module houses 3 functions:
set_debug(state:bool=True) { #set_debug}
This can be used to enable debug logging in the library. Note this adds a lot of extra messages, but can be usefull for figuring out whether the library receives a discord event or not, is being ratelimited, etc.set_name(note:str) { #set_name}
This function sets the appendix of the useragent to your note. Please use this to add a way of identifying your bot (eg adding your website or an email address, maybe a version number)set_log_fn(log:callable=None) { #set_log_fn}
Set the function called to log. The function you provide must accept an arbitrary amount of arguments, of any type (similar to how print() does, except without the extra kwargs print() has). Note this is automatically set when using discord.utils.cherrypy.
Take a look at an example pingbot for a full example with explanations about what I'm doing.
Minimal example without comments:
from discord import gateway, message
def run():
i=gateway.intents
intents=i.GUILD_MESSAGES | i.DIRECT_MESSAGES | i.MESSAGE_CONTENT
def on_ready(client:gateway.DiscordWsConnection, data, payload):
@client.event()
def on_message_create(data, payload):
content=data["content"]
channel=data["channel_id"]
if 'ping' in content:
message.message_send(channel_id=channel, content="pong")
gw=gateway.GatewayClient(connect_callback=on_ready, intents=intents)
gw.start()
# note keeping the program running is up to you. here's a premade idea:
from time import sleep
try:
while True: sleep(3600) # sleep for an hour infinitely
except KeyboardInterrupt:
pass
gw.stop()
if __name__=="__main__":
run()
Things to keep in mind while using the gateway:
- GatewayClient.start() is not blocking, it is up to you to keep the program running as long as wanted. Above example shows a way to block until KeyboardInterrupts.
- Make sure the pass the right intents. Using gateway.intents.ALL is possible, but will use unnecessary resources of both discord's servers and your bot, so I recommend only passing the intents you need. Especially if your bot is in a few active servers, the amount of network traffic can can climb fast.
