Function and API Reference: discord.py 2.x

1. What Is It?

This is the function and API dictionary for the guide. It explains the core library APIs, interaction methods, UI builders, lifecycle hooks, and example helper functions used across the docs.

2. Why Does It Exist?

Discord bot tutorials often show code before explaining the words inside the code. This page fixes that by turning each function into a small human explanation.

3. How Discord Handles It Internally

Discord receives command registrations through REST, sends realtime events through the Gateway, and sends interactions when users run commands, click components, choose menus, or submit modals. The functions below either build those payloads, receive those payloads, route them, or respond to them.

4. Visual Explanation

5. Beginner Example

Start by reading function names as plain English. A builder builds a Discord object. A reply replies to the interaction. A guard checks whether an action is allowed.

6. Intermediate Example

Intermediate projects stop putting every decision inside the event callback. They route the interaction, parse state, validate permission, then call a small service function.

7. Production Example

Production bots treat every function as part of a workflow:

1. Builder or decorator defines what Discord shows.
2. Interaction object tells the bot what the user did.
3. Type guard or callback confirms what kind of interaction arrived.
4. Permission guard checks whether this user can act.
5. Service function performs the business operation.
6. Response method tells the user what happened.
7. Audit helper records the decision for maintainers.

Function-by-function walkthrough

8. Common Mistakes

• Calling a response method twice on the same interaction.
• Reading component state without checking the current user and guild.
• Doing slow work before defer or acknowledgement.
• Treating a helper function as magic instead of reading its input and output.

9. Best Practices

• Learn the function purpose before copying the snippet.
• Keep callbacks short and name service functions after the real action.
• Check current permissions every time a component is clicked.
• Log actions with enough metadata to debug, without storing secrets.
• Prefer explicit helpers over giant files full of unrelated interaction code.

10. Performance Notes

Fast functions can reply directly. Slow functions should defer first, then use a service and final response. Database, HTTP, AI, file, and voice operations should not block the interaction handler.

11. Security Notes

Custom IDs, option strings, modal fields, and select values are inputs. Validate them like form data. Never let a function perform moderation, economy, ticket, or dashboard actions without a permission and ownership check.

12. Challenge Section

1. Pick five functions from this page and explain them without using code.
2. Find one example module and label every function as builder, router, guard, service, or response.
3. Add one missing guard to an example callback.
4. Write a small service function and document its input, output, and failure cases.