| Name | pycord-rest-bot JSON |
| Version |
0.1.2
JSON |
| download |
| home_page | None |
| Summary | A lightweight wrapper for Discord's HTTP interactions and webhook events using py-cord and FastAPI |
| upload_time | 2025-07-21 17:40:36 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | ==3.12.* |
| license | None |
| keywords |
bot
discord
pycord
rest
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://pypi.org/project/pycord-rest-bot/)
[](https://pypi.org/project/pycord-rest-bot/)
[](https://pypi.org/project/pycord-rest-bot/)
[](https://pypi.org/project/pycord-rest-bot/)
[](https://github.com/Paillat-dev/pycord-rest/actions/workflows/CI.yaml)
[](https://results.pre-commit.ci/latest/github/Paillat-dev/pycord-rest/main)
---
Pycord REST enables you to build Discord applications that respond to:
- **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
## Quick Start
```python
from pycord_rest import App
import discord
app = App()
@app.slash_command(name="ping", description="Responds with pong!")
async def ping(ctx):
await ctx.respond("Pong!")
if __name__ == "__main__":
app.run(
token="YOUR_BOT_TOKEN",
public_key="YOUR_PUBLIC_KEY", # From Discord Developer Portal
uvicorn_options={
"host": "0.0.0.0",
"port": 8000
}
)
```
## Core Concepts
### How It Works
Pycord REST creates an HTTP server 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
Unlike traditional WebSocket-based Discord bots, HTTP-based applications:
- Only wake up when receiving interactions or webhook events
- Don't maintain a persistent connection to Discord's gateway
- Don't receive most real-time Discord events
### Discord Application Setup
1. Create an application on the
[Discord Developer Portal](https://discord.com/developers/applications)
2. Copy your public key to verify signatures
3. Run the Pycord REST app
4. Configure the endpoints:
- **Interactions Endpoint URL** - For slash commands and component interactions
(`https://example.com`)
- **Webhook URL** - For receiving application events (e.g.,
`https://example.com/webhook`)
<!-- prettier-ignore -->
> **IMPORTANT**:
> 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.
## Features
### Interaction Handling
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
### Type Safety
Pycord REST is fully type-annotated and type-safe. It uses `basedpyright` for type
checking.
<!-- prettier-ignore -->
> **NOTE**:
> While Pycord REST itself is fully typed, the underlying py-cord library has limited type annotations, which may affect type checking in some areas.
## Usage Examples
<!-- prettier-ignore -->
> **TIP**:
> For complete examples, check out the [examples directory](https://github.com/Paillat-dev/pycord-rest/tree/main/examples).
### Basic Commands
Commands use the familiar py-cord syntax:
```python
@app.slash_command(name="hello", description="Say hello")
async def hello(ctx, user: discord.Member = None):
user = user or ctx.author
await ctx.respond(f"Hello {user.mention}!")
@app.slash_command()
async def button(ctx):
view = discord.ui.View()
view.add_item(discord.ui.Button(label="Click me!", custom_id="my_button"))
await ctx.respond("Press the button!", view=view)
```
### Event Handling
The possible events are:
- `on_application_authorized` - When your app is added to a guild or authorized by a
user
- `on_entitlement_create` - When a user subscribes to your app's premium features
<!-- prettier-ignore -->
> **NOTE**:
> For application installation events, use `on_application_authorized` instead of `on_guild_join`.
```python
@app.listen("on_application_authorized")
async def on_application_authorized(event: ApplicationAuthorizedEvent):
# Triggers when app is added to a guild OR when a user authorizes your app
print(f"Authorization received: Guild={event.guild}, User={event.user}")
```
### Custom Routes
Add your own FastAPI routes:
```python
from fastapi import Request
@app.router.get("/custom")
async def custom_endpoint(request: Request):
return {"message": "This is a custom endpoint"}
```
## Configuration
```python
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
)
```
### 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
## Getting Help
If you encounter issues or have questions about pycord-rest:
- **GitHub Issues**:
[Submit a bug report or feature request](https://github.com/Paillat-dev/pycord-rest/issues)
- **Discord Support**:
- For py-cord related questions: Join the
[Pycord Official Server](https://discord.gg/pycord)
- For pycord-rest specific help: Join the
[Pycord Official Server](https://discord.gg/pycord) and mention `@paillat`
<!-- prettier-ignore -->
> **TIP**:
> Before asking for help, check if your question is already answered in the [examples directory](https://github.com/Paillat-dev/pycord-rest/tree/main/examples) or existing GitHub issues.
## Development
### Local Testing
Use tunneling tools to expose your local development server:
- **ngrok**:
```bash
# Install ngrok
npm install -g ngrok
# Expose your local server
ngrok http 8000
```
- **Cloudflare Tunnel** or **localtunnel** - Alternative tunneling options
These tools provide temporary URLs for testing without deploying to production.
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run linter, formatter and type checker: `ruff check .`,`ruff format .`,
`basedpyright .`
5. Submit a pull request
**Development Tools**:
- **uv**: For dependency management
- **Ruff**: For linting and formatting
- **HashiCorp Copywrite**: For managing license headers
- **basedpyright**: For type checking
<!-- prettier-ignore -->
> **NOTE**:
> This is an early-stage project and may have unexpected behaviors or bugs. Please report any issues you encounter.
## License
MIT License - Copyright (c) 2025 Paillat-dev
---
Made with ❤ by Paillat-dev
Raw data
{
"_id": null,
"home_page": null,
"name": "pycord-rest-bot",
"maintainer": null,
"docs_url": null,
"requires_python": "==3.12.*",
"maintainer_email": null,
"keywords": "bot, discord, pycord, rest",
"author": null,
"author_email": "Paillat-dev <me@paillat.dev>",
"download_url": "https://files.pythonhosted.org/packages/11/8e/4509473327c233b84a3e8220d89657046d778ab3b0ca4ea1f6d92b3e40d4/pycord_rest_bot-0.1.2.tar.gz",
"platform": null,
"description": "\n[](https://pypi.org/project/pycord-rest-bot/)\n[](https://pypi.org/project/pycord-rest-bot/)\n[](https://pypi.org/project/pycord-rest-bot/)\n[](https://pypi.org/project/pycord-rest-bot/)\n[](https://github.com/Paillat-dev/pycord-rest/actions/workflows/CI.yaml)\n[](https://results.pre-commit.ci/latest/github/Paillat-dev/pycord-rest/main)\n\n\n---\n\nPycord REST enables you to build Discord applications that respond to:\n\n- **Interactions** via HTTP endpoints (slash commands, components, modals)\n- **Webhook events** such as application authorization and entitlements\n\nBuilt on:\n\n- **FastAPI** - For handling HTTP requests\n- **py-cord** - For Discord command builders and interaction handling\n- **uvicorn** - ASGI server implementation\n\n\n## Quick Start\n\n```python\nfrom pycord_rest import App\nimport discord\n\napp = App()\n\n@app.slash_command(name=\"ping\", description=\"Responds with pong!\")\nasync def ping(ctx):\n await ctx.respond(\"Pong!\")\n\nif __name__ == \"__main__\":\n app.run(\n token=\"YOUR_BOT_TOKEN\",\n public_key=\"YOUR_PUBLIC_KEY\", # From Discord Developer Portal\n uvicorn_options={\n \"host\": \"0.0.0.0\",\n \"port\": 8000\n }\n )\n```\n\n## Core Concepts\n\n### How It Works\n\nPycord REST creates an HTTP server that:\n\n1. Listens for Discord interaction requests and webhook events\n2. Verifies request signatures using your application's public key\n3. Routes events to appropriate handlers\n4. Returns responses back to Discord\n\nUnlike traditional WebSocket-based Discord bots, HTTP-based applications:\n\n- Only wake up when receiving interactions or webhook events\n- Don't maintain a persistent connection to Discord's gateway\n- Don't receive most real-time Discord events\n\n### Discord Application Setup\n\n1. Create an application on the\n [Discord Developer Portal](https://discord.com/developers/applications)\n2. Copy your public key to verify signatures\n3. Run the Pycord REST app\n4. Configure the endpoints:\n\n- **Interactions Endpoint URL** - For slash commands and component interactions\n (`https://example.com`)\n- **Webhook URL** - For receiving application events (e.g.,\n `https://example.com/webhook`)\n\n<!-- prettier-ignore -->\n> **IMPORTANT**:\n> 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.\n\n## Features\n\n### Interaction Handling\n\nRespond to Discord interactions such as:\n\n- **Slash Commands** - Create and respond to application commands\n- **UI Components** - Buttons, select menus, and other interactive elements\n- **Modal Forms** - Pop-up forms for gathering user input\n- **Autocomplete** - Dynamic option suggestions as users type\n\n### Webhook Events\n\nHandle Discord webhook events such as:\n\n- **Application authorization** - When your app is added to a guild or authorized by a\n user\n- **Entitlement creation** - When a user subscribes to your app's premium features\n\n### Type Safety\n\nPycord REST is fully type-annotated and type-safe. It uses `basedpyright` for type\nchecking.\n\n<!-- prettier-ignore -->\n> **NOTE**:\n> While Pycord REST itself is fully typed, the underlying py-cord library has limited type annotations, which may affect type checking in some areas.\n\n## Usage Examples\n\n<!-- prettier-ignore -->\n> **TIP**:\n> For complete examples, check out the [examples directory](https://github.com/Paillat-dev/pycord-rest/tree/main/examples).\n\n### Basic Commands\n\nCommands use the familiar py-cord syntax:\n\n```python\n@app.slash_command(name=\"hello\", description=\"Say hello\")\nasync def hello(ctx, user: discord.Member = None):\n user = user or ctx.author\n await ctx.respond(f\"Hello {user.mention}!\")\n\n@app.slash_command()\nasync def button(ctx):\n view = discord.ui.View()\n view.add_item(discord.ui.Button(label=\"Click me!\", custom_id=\"my_button\"))\n await ctx.respond(\"Press the button!\", view=view)\n```\n\n### Event Handling\n\nThe possible events are:\n\n- `on_application_authorized` - When your app is added to a guild or authorized by a\n user\n- `on_entitlement_create` - When a user subscribes to your app's premium features\n\n<!-- prettier-ignore -->\n> **NOTE**:\n> For application installation events, use `on_application_authorized` instead of `on_guild_join`.\n\n```python\n@app.listen(\"on_application_authorized\")\nasync def on_application_authorized(event: ApplicationAuthorizedEvent):\n # Triggers when app is added to a guild OR when a user authorizes your app\n print(f\"Authorization received: Guild={event.guild}, User={event.user}\")\n```\n\n### Custom Routes\n\nAdd your own FastAPI routes:\n\n```python\nfrom fastapi import Request\n\n@app.router.get(\"/custom\")\nasync def custom_endpoint(request: Request):\n return {\"message\": \"This is a custom endpoint\"}\n```\n\n## Configuration\n\n```python\napp.run(\n token=\"YOUR_BOT_TOKEN\",\n public_key=\"YOUR_PUBLIC_KEY\",\n uvicorn_options={\n \"host\": \"0.0.0.0\", # Listen on all network interfaces\n \"port\": 8000, # Port to listen on\n \"log_level\": \"info\", # Uvicorn logging level\n },\n health=True # Enable /health endpoint for monitoring\n)\n```\n\n### Integration Options\n\n1. **Stand-alone HTTP Interaction Bot** - Commands and components only\n2. **Webhook Event Handler Only** - Process application events alongside a separate\n gateway bot\n3. **Full HTTP Application** - Handle both interactions and webhook events\n\n## Limitations\n\nSince Pycord REST doesn't use Discord's WebSocket gateway:\n\n- **No Cache** - No local storage of guilds, channels, or users\n- **Limited API Methods** - Functions that rely on cache won't work:\n - `app.get_channel()`, `app.get_guild()`, `app.get_user()`\n - Presence updates\n - Voice support\n - Member tracking\n- **Limited Events** - Only interaction-based and webhook events work\n\n## Getting Help\n\nIf you encounter issues or have questions about pycord-rest:\n\n- **GitHub Issues**:\n [Submit a bug report or feature request](https://github.com/Paillat-dev/pycord-rest/issues)\n- **Discord Support**:\n - For py-cord related questions: Join the\n [Pycord Official Server](https://discord.gg/pycord)\n - For pycord-rest specific help: Join the\n [Pycord Official Server](https://discord.gg/pycord) and mention `@paillat`\n\n<!-- prettier-ignore -->\n> **TIP**:\n> Before asking for help, check if your question is already answered in the [examples directory](https://github.com/Paillat-dev/pycord-rest/tree/main/examples) or existing GitHub issues.\n\n## Development\n\n### Local Testing\n\nUse tunneling tools to expose your local development server:\n\n- **ngrok**:\n\n ```bash\n # Install ngrok\n npm install -g ngrok\n\n # Expose your local server\n ngrok http 8000\n ```\n\n- **Cloudflare Tunnel** or **localtunnel** - Alternative tunneling options\n\nThese tools provide temporary URLs for testing without deploying to production.\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run linter, formatter and type checker: `ruff check .`,`ruff format .`,\n `basedpyright .`\n5. Submit a pull request\n\n**Development Tools**:\n\n- **uv**: For dependency management\n- **Ruff**: For linting and formatting\n- **HashiCorp Copywrite**: For managing license headers\n- **basedpyright**: For type checking\n\n<!-- prettier-ignore -->\n> **NOTE**:\n> This is an early-stage project and may have unexpected behaviors or bugs. Please report any issues you encounter.\n\n## License\n\nMIT License - Copyright (c) 2025 Paillat-dev\n\n---\n\nMade with \u2764 by Paillat-dev\n",
"bugtrack_url": null,
"license": null,
"summary": "A lightweight wrapper for Discord's HTTP interactions and webhook events using py-cord and FastAPI",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/Paillat-dev/pycord-rest",
"source_archive": "https://github.com/Paillat-dev/pycord-rest/archive/e886d494d926ad6cd4258315b33ebbcf5dfb6b8f.zip"
},
"split_keywords": [
"bot",
" discord",
" pycord",
" rest"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dab0ab1d956c840dc4f96e436ac84b05f24d5c71070f826eb98f476aeda16f11",
"md5": "9a72b62bece15610893cc1a10506dd2c",
"sha256": "4fe34686ef1d5cf464304c58a22d60f3bb42908944880b7fa52f32f1372e6ced"
},
"downloads": -1,
"filename": "pycord_rest_bot-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9a72b62bece15610893cc1a10506dd2c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "==3.12.*",
"size": 10563,
"upload_time": "2025-07-21T17:40:35",
"upload_time_iso_8601": "2025-07-21T17:40:35.194515Z",
"url": "https://files.pythonhosted.org/packages/da/b0/ab1d956c840dc4f96e436ac84b05f24d5c71070f826eb98f476aeda16f11/pycord_rest_bot-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "118e4509473327c233b84a3e8220d89657046d778ab3b0ca4ea1f6d92b3e40d4",
"md5": "eeb216180825c6f312816282292c62bd",
"sha256": "5b3b5eb4cadd35f0a2210ff952223234ee2b05a2e1c06811a7900a0116f4ad88"
},
"downloads": -1,
"filename": "pycord_rest_bot-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "eeb216180825c6f312816282292c62bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "==3.12.*",
"size": 10899,
"upload_time": "2025-07-21T17:40:36",
"upload_time_iso_8601": "2025-07-21T17:40:36.578887Z",
"url": "https://files.pythonhosted.org/packages/11/8e/4509473327c233b84a3e8220d89657046d778ab3b0ca4ea1f6d92b3e40d4/pycord_rest_bot-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 17:40:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Paillat-dev",
"github_project": "pycord-rest",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pycord-rest-bot"
}
