or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

commands-interactions.md core-clients.md discord-objects.md error-handling.md extensions.md index.md ui-components.md utilities-helpers.md

tile.json

tessl/pypi-py-cord

A modern, async-ready Python API wrapper for Discord with comprehensive bot development features

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:pypi/py-cord@2.6.x

To install, run

npx @tessl/cli install tessl/pypi-py-cord@2.6.0

py-cord

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.

Package Information

Package Name: py-cord
Language: Python
Installation: pip install py-cord
Voice Support: pip install py-cord[voice]

Core Imports

Basic import for Discord functionality:

import discord

For building bots with command frameworks:

from discord.ext import commands

For hybrid commands (both slash and prefix):

from discord.ext import bridge

For background tasks:

from discord.ext import tasks

For pagination:

from discord.ext import pages

Basic Usage

Simple Bot with Slash Commands

import discord

bot = discord.Bot()

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

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

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

bot.run('your-bot-token')

Prefix Commands with discord.ext.commands

import discord
from discord.ext import commands

intents = discord.Intents.default()
intents.message_content = True

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

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

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

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

bot.run('your-bot-token')

Interactive UI with Buttons and Modals

import discord

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

class MyModal(discord.ui.Modal):
    def __init__(self, *args, **kwargs):
        super().__init__(
            discord.ui.InputText(
                label="Your Name",
                placeholder="Enter your name here..."
            ),
            discord.ui.InputText(
                label="Feedback",
                style=discord.InputTextStyle.long,
                placeholder="Share your thoughts..."
            ),
            *args, **kwargs
        )
    
    async def callback(self, interaction):
        embed = discord.Embed(
            title="Thank you for your feedback!",
            description=f"Name: {self.children[0].value}\nFeedback: {self.children[1].value}",
            color=discord.Color.green()
        )
        await interaction.response.send_message(embed=embed)

bot = discord.Bot()

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

bot.run('your-bot-token')

Architecture

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

Core Hierarchy

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

Command Systems

Application Commands: Modern slash commands, user commands, and message commands
Prefix Commands: Traditional text-based commands with the commands extension
Bridge Commands: Hybrid commands that work as both slash and prefix commands

Interactive Components

Views: Containers for UI components like buttons and select menus
Modals: Dialog forms for collecting user input
Buttons: Clickable interface elements
Select Menus: Dropdown selection components

Extension System

py-cord uses a modular extension system allowing you to add functionality:

discord.ext.commands: Comprehensive command framework
discord.ext.bridge: Hybrid command support
discord.ext.tasks: Background task scheduling
discord.ext.pages: Message pagination utilities

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

Capabilities

Core Client Functionality

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

class Client:
    def __init__(self, *, intents: Intents, **options): ...
    async def start(self, token: str): ...
    async def close(self): ...
    def event(self, func): ...
    def run(self, token: str): ...

class Bot(Client):
    def __init__(self, *, command_prefix, intents: Intents, **options): ...
    def slash_command(self, **kwargs): ...
    def user_command(self, **kwargs): ...
    def message_command(self, **kwargs): ...

class AutoShardedBot(Bot): ...
class AutoShardedClient(Client): ...

Core Clients

Discord Objects and Entities

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

class Guild:
    @property
    def members(self) -> List[Member]: ...
    @property
    def channels(self) -> List[GuildChannel]: ...
    async def create_text_channel(self, name: str, **options) -> TextChannel: ...
    async def create_voice_channel(self, name: str, **options) -> VoiceChannel: ...

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

class Message:
    @property
    def author(self) -> Union[User, Member]: ...
    @property
    def content(self) -> str: ...
    async def reply(self, content=None, **kwargs) -> Message: ...
    async def edit(self, **kwargs) -> Message: ...

class User:
    @property
    def display_name(self) -> str: ...
    async def send(self, content=None, **kwargs) -> Message: ...

Discord Objects

Commands and Interactions

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

def slash_command(*, name: str = None, description: str = None, **kwargs): ...
def user_command(*, name: str = None, **kwargs): ...
def message_command(*, name: str = None, **kwargs): ...

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

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

class Interaction:
    async def response.send_message(self, content=None, **kwargs): ...
    async def response.defer(self, ephemeral: bool = False): ...

Commands & Interactions

UI Components and Views

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

class View:
    def __init__(self, *, timeout: float = 180.0): ...
    def add_item(self, item: Item): ...
    async def on_timeout(self): ...

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

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

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

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

class InputText:
    def __init__(self, *, label: str, style: InputTextStyle = InputTextStyle.short, **kwargs): ...

UI Components

Extensions and Framework

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

# discord.ext.commands
class Bot(commands.Bot):
    def __init__(self, command_prefix, **options): ...

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

# discord.ext.bridge  
def bridge_command(**kwargs): ...
class BridgeContext: ...

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

# discord.ext.pages
class Paginator:
    def __init__(self, pages: List[Union[str, discord.Embed, dict]], **kwargs): ...

Extensions

Utilities and Helpers

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

# discord.utils
def find(predicate, iterable): ...
def get(iterable, **attrs): ...
def format_dt(dt: datetime, style: str = None) -> str: ...
def oauth_url(client_id: int, *, permissions: Permissions = None, **kwargs) -> str: ...

# Colors and Assets
class Colour:
    @classmethod
    def random(cls) -> Colour: ...
    @classmethod 
    def red(cls) -> Colour: ...

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

# Enums and Flags
class Status(Enum): ...
class ChannelType(Enum): ...
class Intents: ...
class Permissions: ...

Utilities & Helpers

Error Handling and Exceptions

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

class DiscordException(Exception): ...
class HTTPException(DiscordException): ...
class Forbidden(HTTPException): ...
class NotFound(HTTPException): ...
class LoginFailure(DiscordException): ...

# Command Errors  
class CommandError(DiscordException): ...
class MissingRequiredArgument(UserInputError): ...
class BadArgument(UserInputError): ...
class CommandNotFound(CommandError): ...
class CheckFailure(CommandError): ...

# Application Command Errors
class ApplicationCommandError(DiscordException): ...
class ApplicationCommandInvokeError(ApplicationCommandError): ...

Error Handling