How pycord-development/pycord works
Pycord is an async Python library for building Discord bots and clients. A bot developer’s application initiates the principal workflow by constructing/configuring a bot and calling run; Discord then emits gateway events (messages, interactions, voice state) that Pycord dispatches to the developer’s handlers, whose contexts issue Discord responses or other API operations.
Components
Application lifecycle and Discord transport
• Bot Developer Application and Callbacks — path: null: Consumer-owned code registers commands and event handlers, as shown by the README’s slash-command and prefix-command examples.
• Discord Platform — path: null: The external Discord gateway and HTTP APIs deliver events and receive bot actions.
• Bot API Facade — discord/bot.py: Provides the documented discord.Bot application-facing entry point for declaring application commands and running a bot.
• Async Client and Dispatcher — discord/client.py: Owns the asyncio loop, listener/task tracking, Discord websocket handle, HTTP client, login lifecycle, and asynchronous event-dispatch machinery.
• Gateway WebSocket Protocol — discord/gateway.py: Contains the dedicated Discord gateway protocol implementation; receive-loop details were not sampled.
• REST HTTP Transport — discord/http.py: Implements the HTTP client created by the client runtime for Discord API operations.
• Connection State and Cache — discord/state.py: Supplies the ConnectionState referenced by client-owned channels, interactions, and voice sessions, including access to the loop and HTTP transport.
Commands, contexts, and interaction responses
• Application Command Definitions — discord/commands/core.py: Defines slash, user, and other application-command execution abstractions used by the bot-facing API.
• Application Interaction Context — discord/commands/context.py: Wraps an Interaction, invokes application commands, and delegates respond, defer, edit, and original-response operations to it.
• Prefix Command Definitions — discord/ext/commands/core.py: Provides traditional prefix-command abstractions, including command invocation and help behavior.
• Prefix Command Context — discord/ext/commands/context.py: Holds parsed command/message state and invokes, reinvokes, replies to, forwards, and renders help for prefix commands.
• Bridge Command Context — discord/ext/bridge/context.py: Normalizes response, defer, and edit operations across application-interaction and prefix-message command modes.
• Interaction Resource API — discord/interactions.py: Represents Discord interaction state and response operations consumed by application command contexts.
• Message Resource API — discord/message.py: Represents Discord messages and supplies reply/forward operations used by prefix command contexts.
• Async Webhook Interface — discord/webhook/async_.py: Provides webhook and webhook-message interfaces returned or used by interaction-response flows.
• Interactive UI Kit — discord/ui: Exports views, buttons, selects, modals, layouts, and other Discord message-component helpers.
• Typing Indicator Context — discord/context_managers.py: Repeatedly calls the channel HTTP typing endpoint every five seconds while its synchronous or async context is active.
Voice receive and media handling
• Voice Client Session — discord/voice/client.py: Validates optional voice dependencies, maintains voice connection/session state and SSRC mappings, handles voice-state updates, and dispatches received voice events to listeners, sinks, and the parent client.
• Voice Connection State Machine — discord/voice/state.py: Encapsulates voice connection lifecycle state used by the voice client.
• Voice Packet and Sink Event Routers — discord/voice/receive/router.py: Runs daemon threads that route RTP packets into per-SSRC decoders and queue/register sink event listeners, including child sinks.
• Opus Packet Decoder — discord/opus.py: Supplies PacketDecoder instances used by the receive router to accept RTP packets.
• Voice Sink Collection — discord/sinks/__init__.py: Exposes official recording/output sinks for PCM and multiple container/audio formats.
Relationships
• Bot Developer Application and Callbacks -> Bot API Facade: constructs, decorates, and starts a bot; evidence: README examples call discord.Bot(), register commands, and call run.
• Bot API Facade -> Async Client and Dispatcher: starts/configures the underlying client lifecycle; evidence: the documented Bot.run flow, though its implementation was not sampled.
• Discord Platform -> Gateway WebSocket Protocol: delivers gateway payloads that drive bot events; evidence: the repository contains a dedicated gateway protocol layer and the client owns a DiscordWebSocket.
• Gateway WebSocket Protocol -> Async Client and Dispatcher: supplies the client’s websocket transport; evidence: the client stores self.ws and exposes event dispatch, while the receive-loop call site was not sampled.
• Async Client and Dispatcher -> REST HTTP Transport: constructs and owns an HTTPClient; evidence: client initialization instantiates it with connector, proxy, clock, and loop settings.
• Async Client and Dispatcher -> Bot Developer Application and Callbacks: schedules dispatched event coroutines as tracked asyncio tasks; evidence: dispatch and _schedule_event manage callback tasks.
• Bot API Facade -> Application Command Definitions: registers application-command callbacks; evidence: README slash and user command decorators.
• Bot API Facade -> Prefix Command Definitions: registers prefix-command callbacks; evidence: README commands.Bot and @bot.command() usage.
• Application Interaction Context -> Application Command Definitions: invokes a command callback with itself and supplied arguments; evidence: invoke calls command(self, *args, **kwargs).
• Application Interaction Context -> Interaction Resource API: delegates response operations; evidence: respond calls interaction.respond and related methods use the interaction response state.
• Interaction Resource API -> Discord Platform: submits interaction responses and follow-up-capable results; evidence: context-facing response methods are defined around the interaction API, though transport internals were not sampled.
• Prefix Command Context -> Message Resource API: replies to or forwards the triggering message; evidence: it calls message.reply and message.forward_to.
• Bridge Command Context -> Application Interaction Context: uses inherited application-context response, defer, and edit behavior for interaction commands.
• Bridge Command Context -> Prefix Command Context: uses inherited message reply/typing/edit behavior for prefix commands; this is an alternative execution mode, not a sequential stage.
• Typing Indicator Context -> REST HTTP Transport: invokes channel._state.http.send_typing repeatedly until cancelled.
• Voice Client Session -> Connection State and Cache: reads the client connection state and loop and forwards raw voice-state updates into its voice connection state machine.
• Voice Client Session -> Async Client and Dispatcher: forwards voice receive events to the parent client after its own listeners and sink dispatch.
• Voice Packet and Sink Event Routers -> Opus Packet Decoder: obtains per-SSRC decoders and pushes RTP packets into them.
• Voice Packet and Sink Event Routers -> Voice Sink Collection: holds sinks and registers listeners on each sink and its child sinks.
Coverage limits
The sampled excerpts omit the concrete gateway receive loop, HTTP request implementation, command parsing/registration internals, interaction serialization, UI dispatch lifecycle, voice connection handshake, audio decoding output flow, and sink file-writing behavior. Therefore, those components are mapped by documented behavior, dedicated source locations, and visible interfaces rather than asserted as fully traced runtime call chains.
Main entry points: client.py Async Client and Dispatcher · bot.py Bot API Facade · commands/context.py Application Interaction Context · bridge/context.py Bridge Command Context
Components 20
Application Lifecycle
- Bot Developer Application · Consumer-owned bot code and callbacks.
- Discord Platform · Discord gateway and HTTP APIs.
- Bot API Facade
discord/bot.py - Async Client and Dispatcher
discord/client.py - Gateway WebSocket Protocol
discord/gateway.py - REST HTTP Transport
discord/http.py - Connection State and Cache
discord/state.py
Commands and Responses
- Application Command Definitions
discord/commands/core.py - Application Interaction Context
discord/commands/context.py - Prefix Command Definitions
discord/ext/commands/core.py - Prefix Command Context
discord/ext/commands/context.py - Bridge Command Context
discord/ext/bridge/context.py - Interaction Resource API
discord/interactions.py - Message Resource API
discord/message.py - Typing Indicator Context
discord/context_managers.py
Voice and Media
- Voice Client Session
discord/voice/client.py - Voice Connection State Machine
discord/voice/state.py - Voice Packet and Sink Event Routers
discord/voice/receive/router.py - Opus Packet Decoder
discord/opus.py - Voice Sink Collection
discord/sinks/__init__.py
Connections 19
- Bot Developer Application → Bot API Facade: constructs and runs
- Bot API Facade → Async Client and Dispatcher: starts lifecycle
- Discord Platform → Gateway WebSocket Protocol: delivers payloads
- Gateway WebSocket Protocol → Async Client and Dispatcher: supplies websocket
- Async Client and Dispatcher → REST HTTP Transport: owns HTTP client
- Async Client and Dispatcher → Bot Developer Application: schedules callbacks
- Bot API Facade → Application Command Definitions: registers callbacks
- Bot API Facade → Prefix Command Definitions: registers callbacks
- Application Interaction Context → Application Command Definitions: invokes command
- Application Interaction Context → Interaction Resource API: delegates responses
- Interaction Resource API → Discord Platform: submits responses
- Prefix Command Context → Message Resource API: replies and forwards
- Bridge Command Context → Application Interaction Context: uses interaction mode · Alternative execution mode.
- Bridge Command Context → Prefix Command Context: uses prefix mode · Alternative execution mode.
- Typing Indicator Context → REST HTTP Transport: sends typing
- Voice Client Session → Connection State and Cache: forwards voice state
- Voice Client Session → Async Client and Dispatcher: forwards voice events
- Voice Packet and Sink Event Routers → Opus Packet Decoder: routes RTP packets
- Voice Packet and Sink Event Routers → Voice Sink Collection: registers sink listeners