Paillat-dev/pycord-rest
1
0
Fork 0
mirror of https://github.com/Paillat-dev/pycord-rest.git synced 2026-01-02 00:56:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 Update README.md to enhance documentation on webhook events and core concepts

Browse Source
This commit is contained in:
Paillat-dev
2025-03-09 16:52:18 +01:00
parent a133ca87cf
commit 3bce16b3e7
1 changed files with 148 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

255
README.md
View File

@@ -1,21 +1,41 @@
# Pycord REST # Pycord REST
A lightweight wrapper for Discord's HTTP interactions using py-cord and FastAPI. This A lightweight wrapper for Discord's HTTP interactions and webhook events using py-cord
library enables you to build Discord bots that work exclusively through Discord's HTTP and FastAPI.
interactions, without requiring a WebSocket gateway connection.
## About ## Table of Contents
Pycord REST allows you to build Discord bots that respond to interactions via HTTP - [Overview](#overview)
endpoints as described in - [Installation](#installation)
[Discord's interaction documentation](https://discord.com/developers/docs/interactions/receiving-and-responding) - [Quick Start](#quick-start)
and - [Core Concepts](#core-concepts)
[interaction overview](https://discord.com/developers/docs/interactions/overview#preparing-for-interactions). - [How It Works](#how-it-works)
- [Discord Application Setup](#discord-application-setup)
- [Features](#features)
- [Interaction Handling](#interaction-handling)
- [Webhook Events](#webhook-events)
- [Usage Examples](#usage-examples)
- [Basic Commands](#basic-commands)
- [Event Handling](#event-handling)
- [Custom Routes](#custom-routes)
- [Configuration](#configuration)
- [Limitations](#limitations)
- [Development](#development)
- [Local Testing](#local-testing)
- [Contributing](#contributing)
- [License](#license)
This project is built on: ## Overview
- **FastAPI** - For handling the HTTP server Pycord REST enables you to build Discord applications that respond to:
- **py-cord** - Leveraging Discord command builders and interaction handling
- **Interactions** via HTTP endpoints (slash commands, components, modals)
- **Webhook events** such as application authorization and entitlements
Built on:
- **FastAPI** - For handling HTTP requests
- **py-cord** - For Discord command builders and interaction handling
- **uvicorn** - ASGI server implementation - **uvicorn** - ASGI server implementation
## Installation ## Installation
@@ -24,8 +44,9 @@ This project is built on:
pip install pycord-rest-bot --prerelease=allow pip install pycord-rest-bot --prerelease=allow
``` ```
Currently, the package is in pre-release, so you need to use the `--prerelease=allow` <!-- prettier-ignore -->
flag to install it. > [!NOTE]
> The package is currently in pre-release.
## Quick Start ## Quick Start
@@ -50,48 +71,68 @@ if __name__ == "__main__":
) )
``` ```
For more examples, check out the [examples directory](/examples) which includes: ## Core Concepts
- Basic slash command setup ### How It Works
- Button interactions
- Modal forms
## How It Works Pycord REST creates an HTTP server that:
Under the hood, Pycord REST creates an HTTP server using FastAPI and Uvicorn that: 1. Listens for Discord interaction requests and webhook events
2. Verifies request signatures using your application's public key
3. Routes events to appropriate handlers
4. Returns responses back to Discord
1. Listens for incoming Discord interaction requests on your specified endpoint Unlike traditional WebSocket-based Discord bots, HTTP-based applications:
2. Verifies the request signature using your application's public key
3. Routes the interaction to the appropriate command handler
4. Returns the response back to Discord
Unlike traditional Discord bots that maintain a persistent WebSocket connection to - Only wake up when receiving interactions or webhook events
Discord's gateway, HTTP-based bots: - Don't maintain a persistent connection to Discord's gateway
- Don't receive most real-time Discord events
- Only wake up when an interaction is received ### Discord Application Setup
- Don't receive real-time events from Discord
## Usage 1. Create an application on the
### Setting up your bot on Discord
1. Create a bot on the
[Discord Developer Portal](https://discord.com/developers/applications) [Discord Developer Portal](https://discord.com/developers/applications)
2. Enable the "Interactions Endpoint URL" for your application 2. Copy your public key to verify signatures
3. Set the URL to your public endpoint where your bot will receive interactions 3. Run your FastAPI server
4. Copy your public key from the Developer Portal to verify signatures 4. Configure the endpoints:
### Features - **Interactions Endpoint URL** - For slash commands and component interactions
(`https://example.com`)
- **Webhook URL** - For receiving application events (e.g.,
`https://example.com/webhook`)
- Slash Commands <!-- prettier-ignore -->
- UI Components (buttons, select menus) > [!IMPORTANT]
- Modal interactions > Don't forget to run your FastAPI server **before** setting up the application on Discord, or else Discord won't be able to verify the endpoints.
- Autocomplete for commands
### Similarities to py-cord ## Features
Syntax is equivalent to py-cord, as it is what is being used under the hood, making it ### Interaction Handling
easy to adapt existing bots:
Respond to Discord interactions such as:
- **Slash Commands** - Create and respond to application commands
- **UI Components** - Buttons, select menus, and other interactive elements
- **Modal Forms** - Pop-up forms for gathering user input
- **Autocomplete** - Dynamic option suggestions as users type
### Webhook Events
Handle Discord webhook events such as:
- **Application authorization** - When your app is added to a guild or authorized by a
user
- **Entitlement creation** - When a user subscribes to your app's premium features
## Usage Examples
<!-- prettier-ignore -->
> [!TIP]
> For complete examples, check out the [examples directory](/examples).
### Basic Commands
Commands use the familiar py-cord syntax:
```python ```python
@app.slash_command(name="hello", description="Say hello") @app.slash_command(name="hello", description="Say hello")
@@ -106,57 +147,28 @@ async def button(ctx):
await ctx.respond("Press the button!", view=view) await ctx.respond("Press the button!", view=view)
``` ```
## Limitations ### Event Handling
This library works differently than traditional bots because it does not use Discord's The possible events are:
WebSocket gateway:
- **No Cache**: Since there's no gateway connection, there's no cache of guilds, - `on_application_authorized` - When your app is added to a guild or authorized by a
channels, users, etc. user
- **Limited API Methods**: Many standard py-cord methods that rely on cache won't work - `on_entitlement_create` - When a user subscribes to your app's premium features
properly:
- `app.get_channel()`, `app.get_guild()`, `app.get_user()`, etc.
- Presence updates
- Voice support
- Member tracking
- **Event-Based Functions**: Only interaction-based events work; message events, etc.
don't work
Remember that this is an HTTP-only bot that responds exclusively to interactions <!-- prettier-ignore -->
triggered by users. > [!NOTE]
> For application installation events, use `on_application_authorized` instead of `on_guild_join`.
## Configuration Options
```python ```python
app.run( @app.listen("on_application_authorized")
token="YOUR_BOT_TOKEN", async def on_application_authorized(event: ApplicationAuthorizedEvent):
public_key="YOUR_PUBLIC_KEY", # Triggers when app is added to a guild OR when a user authorizes your app
uvicorn_options={ print(f"Authorization received: Guild={event.guild}, User={event.user}")
"host": "0.0.0.0", # Listen on all network interfaces
"port": 8000, # Port to listen on
"log_level": "info", # Uvicorn logging level
# Any valid uvicorn server options
},
health=True # Enable /health endpoint
)
``` ```
### Server Configuration ### Custom Routes
For Discord to reach your bot, you need a publicly accessible HTTPS URL. Options Add your own FastAPI routes:
include:
- Using a VPS with a domain and SSL certificate
- Deploying to a cloud service like Heroku, Railway, or Fly.io
### Health Check
By default, Pycord REST includes a `/health` endpoint that returns a 200 status code.
This endpoint is useful for monitoring services like UptimeRobot or health checks.
## Advanced Usage
### Adding Custom FastAPI Routes
```python ```python
from fastapi import Request from fastapi import Request
@@ -166,12 +178,47 @@ async def custom_endpoint(request: Request):
return {"message": "This is a custom endpoint"} return {"message": "This is a custom endpoint"}
``` ```
## Development Workflow ## Configuration
For faster development and testing, you can use tunneling tools to expose your local ```python
development server: app.run(
token="YOUR_BOT_TOKEN",
public_key="YOUR_PUBLIC_KEY",
uvicorn_options={
"host": "0.0.0.0", # Listen on all network interfaces
"port": 8000, # Port to listen on
"log_level": "info", # Uvicorn logging level
},
health=True # Enable /health endpoint for monitoring
)
```
- **ngrok** - Creates a secure tunnel to your localhost ### Integration Options
1. **Stand-alone HTTP Interaction Bot** - Commands and components only
2. **Webhook Event Handler Only** - Process application events alongside a separate
gateway bot
3. **Full HTTP Application** - Handle both interactions and webhook events
## Limitations
Since Pycord REST doesn't use Discord's WebSocket gateway:
- **No Cache** - No local storage of guilds, channels, or users
- **Limited API Methods** - Functions that rely on cache won't work:
- `app.get_channel()`, `app.get_guild()`, `app.get_user()`
- Presence updates
- Voice support
- Member tracking
- **Limited Events** - Only interaction-based and webhook events work
## Development
### Local Testing
Use tunneling tools to expose your local development server:
- **ngrok**:
```bash ```bash
# Install ngrok # Install ngrok
@@ -181,34 +228,28 @@ development server:
ngrok http 8000 ngrok http 8000
``` ```
- **Cloudflare Tunnel** - Provides a secure connection to your local server - **Cloudflare Tunnel** or **localtunnel** - Alternative tunneling options
- **localtunnel** - Simple tunnel service for exposing local endpoints
These tools provide temporary URLs that you can use in the Discord Developer Portal These tools provide temporary URLs for testing without deploying to production.
during development, allowing you to test changes quickly without deploying to
production.
## Contributing ### Contributing
Contributions are welcome! This project is in early development, so there might be bugs
or unexpected behaviors.
1. Fork the repository 1. Fork the repository
2. Create a feature branch 2. Create a feature branch
3. Make your changes 3. Make your changes
4. Run tests and linting: `ruff check` and `ruff format` 4. Run linter, formatter and type checker: `ruff check .`,`ruff format .`,
`basedpyright .`
5. Submit a pull request 5. Submit a pull request
### Development Tools **Development Tools**:
- **Ruff**: For linting and formatting - **Ruff**: For linting and formatting
- **HashiCorp Copywrite**: For managing license headers - **HashiCorp Copywrite**: For managing license headers
- **basedpyright**: For type checking - **basedpyright**: For type checking
## Disclaimer <!-- prettier-ignore -->
> [!NOTE]
This is an early-stage project and may have unexpected behaviors or bugs. Please report > This is an early-stage project and may have unexpected behaviors or bugs. Please report any issues you encounter.
any issues you encounter.
## License ## License
@@ -216,4 +257,4 @@ MIT License - Copyright (c) 2025 Paillat-dev
--- ---
Made with ❤️ by Paillat-dev Made with :red_heart: by Paillat-dev