0
# Disnake
1

2
A modern, easy-to-use, feature-rich, and async-ready API wrapper for Discord written in Python. Disnake enables developers to create Discord bots and applications with proper rate limit handling, type-safety measures, and FastAPI-like slash command syntax while preserving the syntax and structure of discord.py 2.0.
3

4
## Package Information
5

6
- **Package Name**: disnake
7
- **Language**: Python
8
- **Installation**: `pip install disnake`
9
- **Voice Support**: `pip install disnake[voice]`
10

11
## Core Imports
12

13
```python
14
import disnake
15
```
16

17
Common imports for bot development:
18

19
```python
20
from disnake.ext import commands
21
import disnake
22
```
23

24
## Basic Usage
25

26
```python
27
import disnake
28
from disnake.ext import commands
29

30
# Create a bot with message commands
31
bot = commands.Bot(command_prefix='!')
32

33
@bot.event
34
async def on_ready():
35
    print(f'Bot is ready! Logged in as {bot.user}')
36

37
@bot.slash_command(description="Say hello")
38
async def hello(inter: disnake.ApplicationCommandInteraction):
39
    await inter.response.send_message("Hello!")
40

41
@bot.command()
42
async def ping(ctx):
43
    await ctx.send('Pong!')
44

45
# Run the bot
46
bot.run('YOUR_BOT_TOKEN')
47
```
48

49
## Architecture
50

51
Disnake follows a hierarchical event-driven architecture:
52

53
- **Client/Bot**: Central connection handler managing Discord API communication
54
- **Gateway**: WebSocket connection for real-time events and command handling
55
- **Commands**: Both traditional message-based and modern application commands (slash commands, context menus)
56
- **Interactions**: User input handling through buttons, select menus, modals, and application commands
57
- **Entities**: Discord objects (guilds, channels, users, messages) with full API integration
58
- **Extensions**: Modular command framework with cogs and extensions for organized bot structure
59

60
This design provides both backward compatibility with discord.py and modern Discord API features including interactions, UI components, and comprehensive bot development tools.
61

62
## Capabilities
63

64
### Client and Bot Classes
65

66
Core client and bot classes for establishing Discord connections and managing bot functionality. Includes both basic clients and specialized bot classes for different use cases.
67

68
```python { .api }
69
class Client:
70
    def __init__(self, **options): ...
71
    async def login(self, token: str): ...
72
    async def connect(self, *, reconnect: bool = True): ...
73
    def run(self, token: str, **kwargs): ...
74
    async def close(): ...
75

76
class Bot(commands.BotBase, Client):
77
    def __init__(self, command_prefix, **options): ...
78
```
79

80
[Client and Bot Classes](./client-bot.md)
81

82
### Channels and Messaging
83

84
Comprehensive channel types and messaging functionality supporting text channels, voice channels, threads, forums, and direct messages. Includes message creation, editing, deletion, and rich content support.
85

86
```python { .api }
87
class TextChannel:
88
    async def send(self, content=None, **kwargs) -> Message: ...
89
    async def fetch_message(self, id: int) -> Message: ...
90

91
class Message:
92
    content: str
93
    author: Union[User, Member]
94
    channel: Messageable
95
    async def edit(self, **kwargs): ...
96
    async def delete(): ...
97
```
98

99
[Channels and Messaging](./channels-messaging.md)
100

101
### Application Commands
102

103
Modern Discord application commands including slash commands, user context menu commands, and message context menu commands with parameter validation and autocomplete support.
104

105
```python { .api }
106
def slash_command(name=None, description=None, **kwargs):
107
    """Decorator for slash commands"""
108

109
def user_command(name=None, **kwargs):
110
    """Decorator for user context menu commands"""
111

112
def message_command(name=None, **kwargs):
113
    """Decorator for message context menu commands"""
114
```
115

116
[Application Commands](./application-commands.md)
117

118
### Interactions and UI Components
119

120
Interactive Discord UI elements including buttons, select menus, modals, and views for creating rich user interfaces with persistent component handling.
121

122
```python { .api }
123
class View:
124
    def __init__(self, **kwargs): ...
125
    async def interaction_check(self, interaction: Interaction) -> bool: ...
126

127
class Button(Item):
128
    def __init__(self, style=ButtonStyle.secondary, label=None, **kwargs): ...
129
    async def callback(self, interaction: Interaction): ...
130

131
class Modal:
132
    def __init__(self, title: str, **kwargs): ...
133
    async def on_submit(self, interaction: ModalInteraction): ...
134
```
135

136
[Interactions and UI Components](./interactions-ui.md)
137

138
### Guild Management
139

140
Comprehensive guild (server) management including member management, role management, channel organization, permissions, and guild-specific features like scheduled events and moderation.
141

142
```python { .api }
143
class Guild:
144
    name: str
145
    members: List[Member]
146
    channels: List[GuildChannel]
147
    roles: List[Role]
148
    async def create_text_channel(self, name: str, **kwargs) -> TextChannel: ...
149
    async def ban(self, user, **kwargs): ...
150
```
151

152
[Guild Management](./guild-management.md)
153

154
### Users and Members
155

156
User and member objects representing Discord users and guild members with profile information, permissions, voice states, and user-specific operations.
157

158
```python { .api }
159
class User:
160
    id: int
161
    name: str
162
    discriminator: str
163
    avatar: Optional[Asset]
164

165
class Member(User):
166
    guild: Guild
167
    roles: List[Role]
168
    joined_at: Optional[datetime]
169
    async def add_roles(*roles): ...
170
```
171

172
[Users and Members](./users-members.md)
173

174
### Events and Gateway
175

176
Discord gateway events and event handling system for real-time bot functionality including message events, member events, guild events, and custom event dispatching.
177

178
```python { .api }
179
@bot.event
180
async def on_ready(): ...
181

182
@bot.event
183
async def on_message(message: Message): ...
184

185
@bot.event
186
async def on_member_join(member: Member): ...
187
```
188

189
[Events and Gateway](./events-gateway.md)
190

191
### Command Framework
192

193
Traditional message-based command framework with command groups, argument parsing, permission checks, cooldowns, and error handling for text-based bot commands.
194

195
```python { .api }
196
@commands.command()
197
async def my_command(ctx: commands.Context): ...
198

199
@commands.group()
200
async def my_group(ctx: commands.Context): ...
201

202
@commands.check(lambda ctx: ctx.author.id == 123456789)
203
async def owner_only(ctx): ...
204
```
205

206
[Command Framework](./command-framework.md)
207

208
### Permissions and Security
209

210
Discord permissions system, role management, and security features including permission overrides, role hierarchy, and access control for commands and features.
211

212
```python { .api }
213
class Permissions:
214
    def __init__(self, **kwargs): ...
215
    @classmethod
216
    def all(cls): ...
217
    @classmethod
218
    def none(cls): ...
219

220
class PermissionOverwrite:
221
    def __init__(self, **kwargs): ...
222
```
223

224
[Permissions and Security](./permissions-security.md)
225

226
### Error Handling
227

228
Comprehensive error handling system covering Discord API errors, command framework errors, interaction errors, and custom exception types with proper error recovery patterns.
229

230
```python { .api }
231
class DiscordException(Exception): ...
232
class HTTPException(DiscordException): ...
233
class CommandError(DiscordException): ...
234
class InteractionException(DiscordException): ...
235

236
@bot.event
237
async def on_command_error(ctx, error): ...
238
```
239

240
[Error Handling](./error-handling.md)
241

242
### Voice and Audio
243

244
Voice channel connection, audio streaming, and voice-related functionality for music bots and voice applications with proper audio handling and connection management.
245

246
```python { .api }
247
class VoiceChannel:
248
    async def connect(self, **kwargs) -> VoiceClient: ...
249

250
class VoiceClient:
251
    async def disconnect(): ...
252
    def play(self, source, **kwargs): ...
253
```
254

255
[Voice and Audio](./voice-audio.md)
256

257
### Localization and Internationalization
258

259
Comprehensive i18n system for application commands with support for Discord's native localization features, file-based translation stores, and custom localization providers.
260

261
```python { .api }
262
class Localized:
263
    def __init__(self, string, *, key=None, **localizations): ...
264
    def set(self, locale, value): ...
265

266
class LocalizationStore(LocalizationProtocol):
267
    def __init__(self, files, *, strict=False, fallback=None): ...
268
    async def get(self, key, locale, **kwargs): ...
269
```
270

271
[Localization and Internationalization](./localization-i18n.md)
272

273
### AutoMod System
274

275
Discord's automated content moderation system with configurable rules, triggers, and actions for filtering messages, managing spam, and enforcing community guidelines.
276

277
```python { .api }
278
class AutoModRule:
279
    @property
280
    def name(self) -> str: ...
281
    @property
282
    def trigger_type(self) -> AutoModTriggerType: ...
283
    async def edit(self, **kwargs) -> AutoModRule: ...
284
    async def delete(self) -> None: ...
285

286
class AutoModAction:
287
    @property
288
    def type(self) -> AutoModActionType: ...
289
```
290

291
[AutoMod System](./automod.md)
292

293
### Poll System
294

295
Discord's native poll system with multi-choice answers, emoji support, vote tracking, and automatic result counting for interactive community engagement.
296

297
```python { .api }
298
class Poll:
299
    @property
300
    def question(self) -> PollMedia: ...
301
    @property
302
    def answers(self) -> List[PollAnswer]: ...
303
    async def end(self) -> Message: ...
304
    
305
    @classmethod
306
    def create(cls, question, *answers, duration=None, allow_multiselect=False): ...
307

308
class PollAnswer:
309
    @property
310
    def vote_count(self) -> int: ...
311
    def get_voters(self) -> PollAnswerIterator: ...
312
```
313

314
[Poll System](./polls.md)