0
# Discord Objects & Models
1

2
Comprehensive models for all Discord entities like guilds, users, channels, messages, and more.
3

4
## Core Discord Objects
5

6
### Guild
7

8
Represents a Discord server/guild.
9

10
```python
11
class Guild:
12
    id: Snowflake
13
    name: str
14
    owner_id: Snowflake
15
    region: str
16
    afk_channel_id: Optional[Snowflake]
17
    afk_timeout: int
18
    verification_level: VerificationLevel
19
    default_message_notifications: DefaultNotificationLevel
20
    explicit_content_filter: ExplicitContentFilterLevel
21
    roles: List[Role]
22
    emojis: List[CustomEmoji]
23
    features: List[str]
24
    mfa_level: MFALevel
25
    system_channel_id: Optional[Snowflake]
26
    max_presences: Optional[int]
27
    max_members: Optional[int]
28
    description: Optional[str]
29
    banner: Optional[Asset]
30
    premium_tier: PremiumTier
31
    preferred_locale: str
32
    nsfw_level: NSFWLevel
33
```
34

35
**Key Methods**:
36
- `fetch_channels()` { .api } - Get all guild channels
37
- `fetch_members(limit=1000)` { .api } - Get guild members
38
- `create_text_channel(name, **kwargs)` { .api } - Create text channel
39
- `create_voice_channel(name, **kwargs)` { .api } - Create voice channel
40
- `create_role(name, **kwargs)` { .api } - Create role
41
- `fetch_ban(user_id)` { .api } - Get ban information for user
42
- `fetch_bans()` { .api } - Get all guild bans
43

44
### User
45

46
Represents a Discord user.
47

48
```python { .api }
49
class User:
50
    id: Snowflake
51
    username: str
52
    discriminator: int
53
    global_name: Optional[str]
54
    avatar: Optional[Asset]
55
    bot: bool
56
    system: bool
57
    mfa_enabled: bool
58
    banner: Optional[Asset]
59
    accent_color: Optional[int]
60
    locale: Optional[str]
61
    verified: bool
62
    email: Optional[str]
63
    flags: UserFlags
64
    premium_type: PremiumType
65
    public_flags: UserFlags
66
```
67

68
**Key Methods**:
69
- `send(content=None, **kwargs)` { .api } - Send DM to user
70
- `fetch_dm_channel()` { .api } - Get DM channel with user
71
- `mention` { .api } - Get user mention string
72

73
### Member
74

75
Represents a guild member (user in guild context).
76

77
```python
78
class Member(User):
79
    guild: Guild
80
    nick: Optional[str]
81
    avatar: Optional[Asset]
82
    roles: List[Role]
83
    joined_at: datetime
84
    premium_since: Optional[datetime]
85
    deaf: bool
86
    mute: bool
87
    flags: MemberFlags
88
    pending: Optional[bool]
89
    permissions: Optional[Permissions]
90
    communication_disabled_until: Optional[datetime]
91
```
92

93
**Key Methods**:
94
- `add_role(role, reason=None)` { .api } - Add role to member
95
- `remove_role(role, reason=None)` { .api } - Remove role from member
96
- `edit(nick=None, roles=None, **kwargs)` { .api } - Edit member
97
- `kick(reason=None)` { .api } - Kick member from guild
98
- `ban(reason=None, delete_message_days=0)` { .api } - Ban member from guild
99
- `timeout(until, reason=None)` { .api } - Timeout member
100

101
### ClientUser
102

103
Represents the bot's own user account.
104

105
```python
106
class ClientUser(User):
107
    verified: bool
108
    mfa_enabled: bool
109
```
110

111
**Key Methods**:
112
- `edit(username=None, avatar=None)` { .api } - Edit bot's profile
113

114
## Channels
115

116
### Base Channel Classes
117

118
```python
119
class BaseChannel:
120
    id: Snowflake
121
    type: ChannelType
122
    name: Optional[str]
123
    
124
class GuildChannel(BaseChannel):
125
    guild_id: Snowflake
126
    position: int
127
    permission_overwrites: List[PermissionOverwrite]
128
    parent_id: Optional[Snowflake]
129
```
130

131
### Text Channels
132

133
```python
134
class GuildText(GuildChannel, MessageableMixin):
135
    topic: Optional[str]
136
    nsfw: bool
137
    last_message_id: Optional[Snowflake]
138
    rate_limit_per_user: int
139
    default_auto_archive_duration: AutoArchiveDuration
140
    permissions: Optional[Permissions]
141
```
142

143
**Key Methods**:
144
- `send(content=None, **kwargs)` { .api } - Send message to channel
145
- `fetch_message(message_id)` { .api } - Get specific message
146
- `purge(amount=50, check=None)` { .api } - Delete multiple messages
147
- `create_thread(name, **kwargs)` { .api } - Create thread
148
- `set_permissions(target, **permissions)` { .api } - Set channel permissions
149

150
### Voice Channels
151

152
```python
153
class GuildVoice(GuildChannel):
154
    bitrate: int
155
    user_limit: int
156
    rtc_region: Optional[str]
157
    video_quality_mode: VideoQualityMode
158
```
159

160
**Key Methods**:
161
- `connect()` { .api } - Connect bot to voice channel
162
- `edit(name=None, bitrate=None, user_limit=None)` { .api } - Edit voice channel
163

164
### Other Channel Types
165

166
```python
167
class GuildCategory(GuildChannel):
168
    """Channel category for organization"""
169
    
170
class GuildNews(GuildText):
171
    """News/announcement channel"""
172
    
173
class GuildStageVoice(GuildVoice):
174
    """Stage channel for events"""
175
    
176
class GuildForum(GuildChannel):
177
    """Forum channel with posts"""
178
    available_tags: List[ThreadTag]
179
    default_reaction_emoji: Optional[PartialEmoji]
180
    
181
class DMChannel(BaseChannel, MessageableMixin):
182
    """Direct message channel"""
183
    recipient: User
184
    
185
class DMGroup(BaseChannel, MessageableMixin):  
186
    """Group DM channel"""
187
    recipients: List[User]
188
    icon: Optional[Asset]
189
    owner_id: Snowflake
190
```
191

192
## Messages & Content
193

194
### Message
195

196
```python
197
class Message:
198
    id: Snowflake
199
    channel_id: Snowflake
200
    author: Union[User, Member]
201
    content: str
202
    timestamp: datetime
203
    edited_timestamp: Optional[datetime]
204
    tts: bool
205
    mention_everyone: bool
206
    mentions: List[Union[User, Member]]
207
    mention_roles: List[Role]
208
    mention_channels: List[ChannelMention]
209
    attachments: List[Attachment]
210
    embeds: List[Embed]
211
    reactions: List[Reaction]
212
    nonce: Optional[Union[int, str]]
213
    pinned: bool
214
    webhook_id: Optional[Snowflake]
215
    type: MessageType
216
    activity: Optional[MessageActivity]
217
    application: Optional[Application]
218
    message_reference: Optional[MessageReference]
219
    flags: MessageFlags
220
    referenced_message: Optional[Message]
221
    interaction: Optional[MessageInteraction]
222
    thread: Optional[ThreadChannel]
223
    components: List[ActionRow]
224
    sticker_items: List[StickerItem]
225
```
226

227
**Key Methods**:
228
- `edit(content=None, **kwargs)` { .api } - Edit message content
229
- `delete()` { .api } - Delete message
230
- `reply(content=None, **kwargs)` { .api } - Reply to message
231
- `add_reaction(emoji)` { .api } - Add emoji reaction
232
- `remove_reaction(emoji, user=None)` { .api } - Remove reaction
233
- `pin()` { .api } - Pin message
234
- `unpin()` { .api } - Unpin message
235
- `create_thread(name, **kwargs)` { .api } - Create thread from message
236

237
### Embed
238

239
```python
240
class Embed:
241
    title: Optional[str]
242
    type: str = "rich"
243
    description: Optional[str]
244
    url: Optional[str]
245
    timestamp: Optional[datetime]
246
    color: Optional[int]
247
    footer: Optional[EmbedFooter]
248
    image: Optional[EmbedAttachment]
249
    thumbnail: Optional[EmbedAttachment]
250
    video: Optional[EmbedAttachment]
251
    provider: Optional[EmbedProvider]
252
    author: Optional[EmbedAuthor]
253
    fields: List[EmbedField]
254
```
255

256
**Key Methods**:
257
- `add_field(name, value, inline=False)` { .api } - Add embed field
258
- `set_footer(text, icon_url=None)` { .api } - Set embed footer
259
- `set_author(name, url=None, icon_url=None)` { .api } - Set embed author
260
- `set_thumbnail(url)` { .api } - Set embed thumbnail
261
- `set_image(url)` { .api } - Set embed image
262

263
### Attachment
264

265
```python
266
class Attachment:
267
    id: Snowflake
268
    filename: str
269
    description: Optional[str]
270
    content_type: Optional[str]
271
    size: int
272
    url: str
273
    proxy_url: str
274
    height: Optional[int]
275
    width: Optional[int]
276
    ephemeral: bool
277
```
278

279
## Roles & Permissions
280

281
### Role
282

283
```python
284
class Role:
285
    id: Snowflake
286
    name: str
287
    color: int
288
    hoist: bool
289
    icon: Optional[Asset]
290
    unicode_emoji: Optional[str]
291
    position: int
292
    permissions: Permissions
293
    managed: bool
294
    mentionable: bool
295
    tags: Optional[dict]
296
```
297

298
**Key Methods**:
299
- `edit(name=None, color=None, **kwargs)` { .api } - Edit role properties
300
- `delete(reason=None)` { .api } - Delete role
301
- `mention` { .api } - Get role mention string
302

303
### Permissions
304

305
```python
306
class Permissions:
307
    # Permission flags
308
    ADMINISTRATOR: int = 1 << 3
309
    MANAGE_GUILD: int = 1 << 5
310
    MANAGE_ROLES: int = 1 << 28
311
    MANAGE_CHANNELS: int = 1 << 4
312
    SEND_MESSAGES: int = 1 << 11
313
    READ_MESSAGES: int = 1 << 10
314
    # ... many more permission flags
315
```
316

317
**Key Methods**:
318
- `has(*permissions)` { .api } - Check if has permissions
319
- `add(*permissions)` { .api } - Add permissions
320
- `remove(*permissions)` { .api } - Remove permissions
321

322
### Permission Overwrite
323

324
```python
325
class PermissionOverwrite:
326
    id: Snowflake
327
    type: OverwriteType
328
    allow: Permissions
329
    deny: Permissions
330
```
331

332
## Emojis & Reactions
333

334
### Custom Emoji
335

336
```python
337
class CustomEmoji:
338
    id: Snowflake
339
    name: str
340
    roles: List[Role]
341
    user: Optional[User]
342
    require_colons: bool
343
    managed: bool
344
    animated: bool
345
    available: bool
346
```
347

348
### Reaction
349

350
```python
351
class Reaction:
352
    count: int
353
    me: bool
354
    emoji: Union[CustomEmoji, PartialEmoji]
355
```
356

357
**Key Methods**:
358
- `users()` { .api } - Get users who reacted
359
- `remove(user=None)` { .api } - Remove reaction
360

361
## Files & Assets
362

363
### File
364

365
```python
366
class File:
367
    file: Union[str, bytes, io.IOBase]
368
    filename: Optional[str]
369
    description: Optional[str]
370
    spoiler: bool = False
371
```
372

373
**Utility Functions**:
374
- `open_file(path, filename=None, description=None)` { .api } - Open file for upload
375

376
### Asset
377

378
```python
379
class Asset:
380
    url: str
381
    key: str
382
    animated: bool
383
```
384

385
**Key Methods**:
386
- `url` { .api } - Get asset URL
387
- `read()` { .api } - Download asset data
388
- `save(path)` { .api } - Save asset to file
389

390
## Colors
391

392
### Color Classes
393

394
```python
395
class Color:
396
    """Color representation for embeds, roles"""
397
    
398
class BrandColors:
399
    """Discord brand colors"""
400
    BLURPLE = 0x5865F2
401
    GREEN = 0x57F287
402
    YELLOW = 0xFEE75C
403
    FUCHSIA = 0xEB459E
404
    RED = 0xED4245
405
    
406
class MaterialColors:
407
    """Material Design colors"""
408
    RED_50 = 0xFFEBEE
409
    # ... many more colors
410
    
411
class FlatUIColors:
412
    """Flat UI color palette"""
413
    TURQUOISE = 0x1ABC9C
414
    # ... many more colors
415
    
416
class RoleColors:
417
    """Default Discord role colors"""  
418
    DEFAULT = 0x000000
419
    # ... many more colors
420
```
421

422
## Utility Types & Functions
423

424
### Snowflake Handling
425

426
```python
427
Snowflake = int  # Discord snowflake ID type
428
Snowflake_Type = Union[Snowflake, SnowflakeObject, int, str]
429

430
# Conversion functions
431
to_snowflake(data) -> int  # Convert to snowflake
432
to_optional_snowflake(data) -> Optional[int]  # Convert to optional snowflake  
433
to_snowflake_list(data) -> List[int]  # Convert to snowflake list
434
```
435

436
### Processing Functions
437

438
```python
439
# Message processing
440
process_message_payload(content, **kwargs) -> dict
441
process_allowed_mentions(mentions) -> dict
442
process_message_reference(reference) -> dict
443

444
# Component processing  
445
process_components(components) -> List[dict]
446
get_components_ids(components) -> List[str]
447
spread_to_rows(components, max_in_row=5) -> List[ActionRow]
448

449
# Embed processing
450
process_embeds(embeds) -> List[dict]
451

452
# Color processing
453
process_color(color) -> int
454
process_colour(color) -> int  # Alias
455

456
# Emoji processing
457
process_emoji(emoji) -> dict
458
process_emoji_req_format(emoji) -> str
459

460
# Permission processing
461
process_permission_overwrites(overwrites) -> List[dict]
462
```
463

464
## Type Mappings & Constants
465

466
### Channel Type Mappings
467

468
```python
469
TYPE_ALL_CHANNEL = Union[GuildText, GuildVoice, GuildCategory, ...]
470
TYPE_GUILD_CHANNEL = Union[GuildText, GuildVoice, GuildCategory, ...]
471
TYPE_DM_CHANNEL = Union[DMChannel, DMGroup]
472
TYPE_THREAD_CHANNEL = Union[GuildPublicThread, GuildPrivateThread, ...]
473
TYPE_VOICE_CHANNEL = Union[GuildVoice, GuildStageVoice]
474
TYPE_MESSAGEABLE_CHANNEL = Union[GuildText, DMChannel, ...]
475

476
TYPE_CHANNEL_MAPPING = {
477
    ChannelType.GUILD_TEXT: GuildText,
478
    ChannelType.DM: DMChannel,
479
    # ... mapping of channel types to classes
480
}
481
```
482

483
### Component Type Mappings
484

485
```python
486
TYPE_COMPONENT_MAPPING = {
487
    ComponentType.ACTION_ROW: ActionRow,
488
    ComponentType.BUTTON: Button,
489
    ComponentType.STRING_SELECT: StringSelectMenu,
490
    # ... mapping of component types to classes
491
}
492
```
493

494
### File Type Constants
495

496
```python
497
UPLOADABLE_TYPE = Union[str, bytes, io.IOBase, File]
498
COLOR_TYPES = Union[int, Color, BrandColors, MaterialColors, ...]
499
```
500

501
## Mixins
502

503
### MessageableMixin
504

505
```python
506
class MessageableMixin:
507
    """Mixin for objects that can receive messages"""
508
    
509
    async def send(self, content=None, **kwargs) -> Message:
510
        """Send message to this channel"""
511
        
512
    async def fetch_message(self, message_id: Snowflake) -> Message:
513
        """Fetch specific message"""
514
        
515
    def history(self, limit=100, **kwargs) -> ChannelHistory:
516
        """Get message history"""
517
```
518

519
### InvitableMixin
520

521
```python  
522
class InvitableMixin:
523
    """Mixin for channels that support invites"""
524
    
525
    async def create_invite(self, **kwargs) -> Invite:
526
        """Create invite for this channel"""
527
        
528
    async def fetch_invites(self) -> List[Invite]:
529
        """Get all invites for this channel"""
530
```
531

532
### ThreadableMixin
533

534
```python
535
class ThreadableMixin:
536
    """Mixin for channels that support threads"""
537
    
538
    async def create_thread(self, name: str, **kwargs) -> ThreadChannel:
539
        """Create thread in this channel"""
540
        
541
    async def fetch_active_threads(self) -> ThreadList:
542
        """Get active threads"""
543
```
544

545
### WebhookMixin
546

547
```python
548
class WebhookMixin:
549
    """Mixin for webhook functionality"""
550
    
551
    async def create_webhook(self, name: str, **kwargs) -> Webhook:
552
        """Create webhook for this channel"""
553
        
554
    async def fetch_webhooks(self) -> List[Webhook]:
555
        """Get all webhooks for this channel"""
556
```