0
# py-cord
1

2
A modern, async-ready Discord API wrapper for Python. py-cord is a comprehensive fork of discord.py that provides full access to Discord's API features through a clean, Pythonic interface, with enhanced support for application commands, UI components, and modern Discord features.
3

4
## Package Information
5

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

11
## Core Imports
12

13
Basic import for Discord functionality:
14

15
```python
16
import discord
17
```
18

19
For building bots with command frameworks:
20

21
```python
22
from discord.ext import commands
23
```
24

25
For hybrid commands (both slash and prefix):
26

27
```python
28
from discord.ext import bridge
29
```
30

31
For background tasks:
32

33
```python
34
from discord.ext import tasks
35
```
36

37
For pagination:
38

39
```python
40
from discord.ext import pages
41
```
42

43
## Basic Usage
44

45
### Simple Bot with Slash Commands
46

47
```python
48
import discord
49

50
bot = discord.Bot()
51

52
@bot.event
53
async def on_ready():
54
    print(f'{bot.user} is ready and online!')
55

56
@bot.slash_command(name="hello", description="Say hello!")
57
async def hello(ctx):
58
    await ctx.respond("Hello! I'm a bot made with py-cord!")
59

60
@bot.slash_command(name="ping", description="Check the bot's latency")
61
async def ping(ctx):
62
    await ctx.respond(f"Pong! Latency is {bot.latency}ms")
63

64
bot.run('your-bot-token')
65
```
66

67
### Prefix Commands with discord.ext.commands
68

69
```python
70
import discord
71
from discord.ext import commands
72

73
intents = discord.Intents.default()
74
intents.message_content = True
75

76
bot = commands.Bot(command_prefix='!', intents=intents)
77

78
@bot.event
79
async def on_ready():
80
    print(f'{bot.user} has landed!')
81

82
@bot.command()
83
async def hello(ctx):
84
    await ctx.send('Hello! I use prefix commands!')
85

86
@bot.command()
87
async def add(ctx, left: int, right: int):
88
    """Adds two numbers together."""
89
    await ctx.send(str(left + right))
90

91
bot.run('your-bot-token')
92
```
93

94
### Interactive UI with Buttons and Modals
95

96
```python
97
import discord
98

99
class MyView(discord.ui.View):
100
    @discord.ui.button(label="Click Me!", style=discord.ButtonStyle.primary)
101
    async def button_callback(self, button, interaction):
102
        modal = MyModal(title="Feedback Form")
103
        await interaction.response.send_modal(modal)
104

105
class MyModal(discord.ui.Modal):
106
    def __init__(self, *args, **kwargs):
107
        super().__init__(
108
            discord.ui.InputText(
109
                label="Your Name",
110
                placeholder="Enter your name here..."
111
            ),
112
            discord.ui.InputText(
113
                label="Feedback",
114
                style=discord.InputTextStyle.long,
115
                placeholder="Share your thoughts..."
116
            ),
117
            *args, **kwargs
118
        )
119
    
120
    async def callback(self, interaction):
121
        embed = discord.Embed(
122
            title="Thank you for your feedback!",
123
            description=f"Name: {self.children[0].value}\nFeedback: {self.children[1].value}",
124
            color=discord.Color.green()
125
        )
126
        await interaction.response.send_message(embed=embed)
127

128
bot = discord.Bot()
129

130
@bot.slash_command()
131
async def feedback(ctx):
132
    view = MyView()
133
    await ctx.respond("Click the button to give feedback!", view=view)
134

135
bot.run('your-bot-token')
136
```
137

138
## Architecture
139

140
py-cord follows a hierarchical object model that mirrors Discord's structure:
141

142
### Core Hierarchy
143
- **Client/Bot**: The main connection point to Discord's API
144
- **Guild**: Represents a Discord server with channels, members, and settings
145
- **Channels**: Different types of communication channels (text, voice, stage, forum)
146
- **Messages**: Content sent in channels with attachments, embeds, and components
147
- **Users/Members**: People using Discord, with different permission contexts
148
- **Roles**: Permission and organizational structures within guilds
149

150
### Command Systems
151
- **Application Commands**: Modern slash commands, user commands, and message commands
152
- **Prefix Commands**: Traditional text-based commands with the commands extension
153
- **Bridge Commands**: Hybrid commands that work as both slash and prefix commands
154

155
### Interactive Components
156
- **Views**: Containers for UI components like buttons and select menus
157
- **Modals**: Dialog forms for collecting user input
158
- **Buttons**: Clickable interface elements
159
- **Select Menus**: Dropdown selection components
160

161
### Extension System
162
py-cord uses a modular extension system allowing you to add functionality:
163
- `discord.ext.commands`: Comprehensive command framework
164
- `discord.ext.bridge`: Hybrid command support
165
- `discord.ext.tasks`: Background task scheduling
166
- `discord.ext.pages`: Message pagination utilities
167

168
This architecture enables building everything from simple bots to complex applications with rich user interfaces and comprehensive Discord integration.
169

170
## Capabilities
171

172
### Core Client Functionality
173

174
Essential client and bot classes for connecting to Discord, managing connections, and handling events. Includes auto-sharding support for large bots.
175

176
```python { .api }
177
class Client:
178
    def __init__(self, *, intents: Intents, **options): ...
179
    async def start(self, token: str): ...
180
    async def close(self): ...
181
    def event(self, func): ...
182
    def run(self, token: str): ...
183

184
class Bot(Client):
185
    def __init__(self, *, command_prefix, intents: Intents, **options): ...
186
    def slash_command(self, **kwargs): ...
187
    def user_command(self, **kwargs): ...
188
    def message_command(self, **kwargs): ...
189

190
class AutoShardedBot(Bot): ...
191
class AutoShardedClient(Client): ...
192
```
193

194
[Core Clients](./core-clients.md)
195

196
### Discord Objects and Entities
197

198
Comprehensive representation of Discord's object model including guilds, channels, messages, users, and all their associated properties and methods.
199

200
```python { .api }
201
class Guild:
202
    @property
203
    def members(self) -> List[Member]: ...
204
    @property
205
    def channels(self) -> List[GuildChannel]: ...
206
    async def create_text_channel(self, name: str, **options) -> TextChannel: ...
207
    async def create_voice_channel(self, name: str, **options) -> VoiceChannel: ...
208

209
class TextChannel:
210
    async def send(self, content=None, *, embed=None, view=None, **kwargs) -> Message: ...
211
    async def create_thread(self, name: str, **kwargs) -> Thread: ...
212

213
class Message:
214
    @property
215
    def author(self) -> Union[User, Member]: ...
216
    @property
217
    def content(self) -> str: ...
218
    async def reply(self, content=None, **kwargs) -> Message: ...
219
    async def edit(self, **kwargs) -> Message: ...
220

221
class User:
222
    @property
223
    def display_name(self) -> str: ...
224
    async def send(self, content=None, **kwargs) -> Message: ...
225
```
226

227
[Discord Objects](./discord-objects.md)
228

229
### Commands and Interactions
230

231
Modern application commands (slash commands, user commands, message commands) and interaction handling, plus traditional prefix command support.
232

233
```python { .api }
234
def slash_command(*, name: str = None, description: str = None, **kwargs): ...
235
def user_command(*, name: str = None, **kwargs): ...
236
def message_command(*, name: str = None, **kwargs): ...
237

238
class Option:
239
    def __init__(self, input_type: SlashCommandOptionType, description: str, **kwargs): ...
240

241
class ApplicationContext:
242
    async def respond(self, content=None, *, embed=None, view=None, **kwargs): ...
243
    async def followup(self, content=None, **kwargs): ...
244
    async def send_modal(self, modal: Modal): ...
245

246
class Interaction:
247
    async def response.send_message(self, content=None, **kwargs): ...
248
    async def response.defer(self, ephemeral: bool = False): ...
249
```
250

251
[Commands & Interactions](./commands-interactions.md)
252

253
### UI Components and Views
254

255
Interactive user interface elements including buttons, select menus, modals, and the view system for creating rich bot interfaces.
256

257
```python { .api }
258
class View:
259
    def __init__(self, *, timeout: float = 180.0): ...
260
    def add_item(self, item: Item): ...
261
    async def on_timeout(self): ...
262

263
class Button:
264
    def __init__(self, *, style: ButtonStyle = ButtonStyle.secondary, label: str = None, **kwargs): ...
265

266
def button(*, label: str = None, style: ButtonStyle = ButtonStyle.secondary, **kwargs): ...
267

268
class Select:
269
    def __init__(self, *, placeholder: str = None, min_values: int = 1, max_values: int = 1, **kwargs): ...
270

271
class Modal:
272
    def __init__(self, *children, title: str, **kwargs): ...
273
    async def callback(self, interaction: Interaction): ...
274

275
class InputText:
276
    def __init__(self, *, label: str, style: InputTextStyle = InputTextStyle.short, **kwargs): ...
277
```
278

279
[UI Components](./ui-components.md)
280

281
### Extensions and Framework
282

283
Extension modules providing command frameworks, hybrid commands, background tasks, and pagination utilities for building sophisticated bots.
284

285
```python { .api }
286
# discord.ext.commands
287
class Bot(commands.Bot):
288
    def __init__(self, command_prefix, **options): ...
289

290
def command(name: str = None, **kwargs): ...
291
def group(name: str = None, **kwargs): ...
292
class Context:
293
    async def send(self, content=None, **kwargs) -> Message: ...
294

295
# discord.ext.bridge  
296
def bridge_command(**kwargs): ...
297
class BridgeContext: ...
298

299
# discord.ext.tasks
300
def loop(*, seconds: float = None, minutes: float = None, hours: float = None): ...
301

302
# discord.ext.pages
303
class Paginator:
304
    def __init__(self, pages: List[Union[str, discord.Embed, dict]], **kwargs): ...
305
```
306

307
[Extensions](./extensions.md)
308

309
### Utilities and Helpers
310

311
Utility functions, enumerations, flags, audio support, color handling, and various helper functions for Discord bot development.
312

313
```python { .api }
314
# discord.utils
315
def find(predicate, iterable): ...
316
def get(iterable, **attrs): ...
317
def format_dt(dt: datetime, style: str = None) -> str: ...
318
def oauth_url(client_id: int, *, permissions: Permissions = None, **kwargs) -> str: ...
319

320
# Colors and Assets
321
class Colour:
322
    @classmethod
323
    def random(cls) -> Colour: ...
324
    @classmethod 
325
    def red(cls) -> Colour: ...
326

327
class Embed:
328
    def __init__(self, *, title: str = None, description: str = None, color: Colour = None): ...
329
    def add_field(self, *, name: str, value: str, inline: bool = True): ...
330

331
# Enums and Flags
332
class Status(Enum): ...
333
class ChannelType(Enum): ...
334
class Intents: ...
335
class Permissions: ...
336
```
337

338
[Utilities & Helpers](./utilities-helpers.md)
339

340
### Error Handling and Exceptions
341

342
Comprehensive exception hierarchy for handling Discord API errors, connection issues, command errors, and other failure scenarios.
343

344
```python { .api }
345
class DiscordException(Exception): ...
346
class HTTPException(DiscordException): ...
347
class Forbidden(HTTPException): ...
348
class NotFound(HTTPException): ...
349
class LoginFailure(DiscordException): ...
350

351
# Command Errors  
352
class CommandError(DiscordException): ...
353
class MissingRequiredArgument(UserInputError): ...
354
class BadArgument(UserInputError): ...
355
class CommandNotFound(CommandError): ...
356
class CheckFailure(CommandError): ...
357

358
# Application Command Errors
359
class ApplicationCommandError(DiscordException): ...
360
class ApplicationCommandInvokeError(ApplicationCommandError): ...
361
```
362

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