discord.py-self Documentation

The discord.ext.tasks extension provides asyncio.Task helpers to run background loops at specified intervals. It abstracts common concerns like handling asyncio.CancelledError, connection interruptions, and sleep intervals. You can define a loop using the @tasks.loop decorator and control its lifecycle using methods like .start() and .cancel().

from discord.ext import tasks, commands

class MyCog(commands.Cog):
    def __init__(self):
        self.index = 0
        self.printer.start()

    def cog_unload(self):
        self.printer.cancel()

    @tasks.loop(seconds=5.0)
    async def printer(self):
        print(self.index)
        self.index += 1

The library is built around the concept of events. An event is something you listen for and then respond to (e.g., receiving a message or the client becoming ready). You typically handle events by overriding methods in a class that inherits from discord.Client.

Common event methods include:

• on_ready: Triggered when the client has successfully logged on.
• on_message: Triggered when a new message is received.

import discord

class MyClient(discord.Client):
    async def on_ready(self):
        print(f'Logged on as {self.user}!')

    async def on_message(self, message):
        print(f'Message from {message.author}: {message.content}')

client = MyClient()
client.run('token')

An AuditLogChanges object represents the state of an audit log entry before and after an action occurred. It contains two primary attributes, before and after, both of which are AuditLogDiff objects. The content of these attributes depends on the AuditLogActionCategory of the entry:

• create category: before attributes are all None; after attributes contain the created values.
• delete category: before attributes contain the values before deletion; after attributes are all None.
• update category: before attributes contain the old values; after attributes contain the new values.
• None category: No attributes are set in either.

Discord Models are classes representing data received from Discord.

Important Constraints:

• Read-Only: You should not modify model instances yourself.
• Do Not Instantiate: You should not create your own instances of these classes (e.g., do not call User() to create a new user).
• Accessing Models: To obtain model instances, use the library's cache or retrieve them from attributes of objects received via Discord API events.
• Dynamic Attributes: Most model classes use __slots__, meaning you cannot add arbitrary new attributes to them at runtime.

To support 'text in voice' functionality, the following changes were implemented:

• VoiceChannel now implements abc.Messageable, allowing messages to be sent and received within voice channels.
• Message.channel can now return instances of VoiceChannel or StageChannel in addition to standard text channels.

Positional parameters are the most basic way to accept arguments. The library maps user input directly to the function's arguments.

Note on multi-word input: If a user wants to pass a single argument containing spaces, they must wrap the input in quotes (e.g., $foo "hello world"). If they omit quotes, the library will only capture the first word as the argument.

@bot.command()
async def test(ctx, arg1, arg2):
    await ctx.send(f'You passed {arg1} and {arg2}')

Several application-related state classes (ApplicationMembershipState, ApplicationVerificationState, StoreApplicationState, RPCApplicationState, ApplicationDiscoverabilityState) support comparison operations. This allows you to check the progression or equality of states using standard Python comparison operators:

• x == y: Checks if two states are equal.
• x != y: Checks if two states are not equal.
• x > y: Checks if one state is higher than another.
• x < y: Checks if one state is lower than another.
• x >= y: Checks if one state is higher or equal to another.
• x <= y: Checks if one state is lower or equal to another.

The library follows Semantic Versioning (SemVer). Major version updates are reserved for incompatible API changes.

Key Guarantees:

• Public API Scope: Breaking change guarantees apply only to publicly documented functions and classes. Attributes starting with an underscore (_) or undocumented functions are considered internal and may change without notice.
• Patch Releases: Guaranteed to not introduce breaking changes.
• Minor Releases: May introduce minor breaking changes due to the dynamic nature of Python and the Discord API.
• Major Releases: Reserved for significant breaking changes.

The library uses Abstract Base Classes (ABCs) that inherit from typing.Protocol. These classes are intended for use with isinstance() and issubclass() to verify object behavior rather than for direct instantiation.

Key ABCs include:

• Snowflake: For objects with a snowflake ID.
• User: For user objects.
• PrivateChannel: For direct message channels.
• GuildChannel: For channels within a guild.
• Messageable: For objects that can receive messages (supports async with context manager).
• Connectable: For objects that can be connected to (e.g., voice).
• ApplicationCommand: For application command objects.