⬆️ Update py-cord dependency to paillcord version 2.7.0a3 (#28)

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: Paillat <paillat@pycord.dev>

.github/workflows/publish.yaml

@@ -12,7 +12,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: "Install uv"
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v6
         with:
           enable-cache: true
 

.github/workflows/quality.yaml

@@ -11,7 +11,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
       - name: Setup Copywrite
-        uses: hashicorp/setup-copywrite@5e3e8a26d7b9f8a508848ad0a069dfd2f7aa5339
+        uses: hashicorp/setup-copywrite@32f9f1c86f661b8a51100768976a06f1b281a035
       - name: Check Header Compliance
         run: copywrite headers --plan --config .copywrite.hcl
 
@@ -38,7 +38,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: "Install uv"
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v6
         with:
           enable-cache: true
 

.pre-commit-config.yaml

@@ -21,7 +21,7 @@ repos:
         exclude: \.(po|pot|yml|yaml)$
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.9.10
+    rev: v0.11.11
     hooks:
       # Run the linter.
       - id: ruff
@@ -31,4 +31,4 @@ repos:
   - repo: https://github.com/bhundven/copywrite # waiting for https://github.com/hashicorp/copywrite/pull/120 to be merged
     rev: 937f17f09c46992447dfa8977bb96eda512588c4
     hooks:
-      - id: add-headers
+      - id: add-headers

README.md

@@ -1,8 +1,28 @@
-# Pycord REST
+<div align="center">
+  <h1>Pycord REST</h1>
+
+<!-- badges -->
+
+[![PyPI - Version](https://img.shields.io/pypi/v/pycord-rest-bot)](https://pypi.org/project/pycord-rest-bot/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pycord-rest-bot)](https://pypi.org/project/pycord-rest-bot/)
+[![PyPI - Types](https://img.shields.io/pypi/types/pycord-rest-bot)](https://pypi.org/project/pycord-rest-bot/)
+[![PyPI - License](https://img.shields.io/pypi/l/pycord-rest-bot)](https://pypi.org/project/pycord-rest-bot/)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Paillat-dev/pycord-rest/CI.yaml)](https://github.com/Paillat-dev/pycord-rest/actions/workflows/CI.yaml)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Paillat-dev/pycord-rest/main.svg)](https://results.pre-commit.ci/latest/github/Paillat-dev/pycord-rest/main)
+
+<!-- end badges -->
+
+<!-- short description -->
 
 A lightweight wrapper for Discord's HTTP interactions and webhook events using py-cord
 and FastAPI.
 
+<!-- end short description -->
+
+</div>
+
+<!-- toc -->
+
 ## Table of Contents
 
 - [Overview](#overview)
@@ -14,12 +34,14 @@ and FastAPI.
 - [Features](#features)
   - [Interaction Handling](#interaction-handling)
   - [Webhook Events](#webhook-events)
+  - [Type Safety](#type-safety)
 - [Usage Examples](#usage-examples)
   - [Basic Commands](#basic-commands)
   - [Event Handling](#event-handling)
   - [Custom Routes](#custom-routes)
 - [Configuration](#configuration)
 - [Limitations](#limitations)
+- [Getting Help](#getting-help)
 - [Development](#development)
   - [Local Testing](#local-testing)
   - [Contributing](#contributing)
@@ -41,12 +63,10 @@ Built on:
 ## Installation
 
 ```bash
-pip install pycord-rest-bot --prerelease=allow
+pip install pycord-rest-bot
 ```
 
-<!-- prettier-ignore -->
-> [!NOTE]
-> The package is currently in pre-release.
+<!-- quick-start -->
 
 ## Quick Start
 
@@ -93,7 +113,7 @@ Unlike traditional WebSocket-based Discord bots, HTTP-based applications:
 1. Create an application on the
    [Discord Developer Portal](https://discord.com/developers/applications)
 2. Copy your public key to verify signatures
-3. Run your FastAPI server
+3. Run the Pycord REST app
 4. Configure the endpoints:
 
 - **Interactions Endpoint URL** - For slash commands and component interactions
@@ -124,6 +144,15 @@ Handle Discord webhook events such as:
   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 -->
@@ -212,6 +241,22 @@ Since Pycord REST doesn't use Discord's WebSocket gateway:
   - 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](/examples) or existing GitHub issues.
+
 ## Development
 
 ### Local Testing
@@ -243,6 +288,7 @@ These tools provide temporary URLs for testing without deploying to production.
 
 **Development Tools**:
 
+- **uv**: For dependency management
 - **Ruff**: For linting and formatting
 - **HashiCorp Copywrite**: For managing license headers
 - **basedpyright**: For type checking

examples/button_example.py

@@ -21,7 +21,7 @@ class MyView(discord.ui.View):
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
         self.add_item(
-            discord.ui.Button(
+            discord.ui.Button(  # pyright: ignore[reportUnknownArgumentType]
                 style=discord.ButtonStyle.link, label="GitHub", url="https://github.com/Paillat-dev/pycord-rest"
             )
         )

examples/webhook_events.py

@@ -1,12 +1,8 @@
 # Copyright (c) Paillat-dev
 # SPDX-License-Identifier: MIT
 
-"""Basic Discord bot example using Pycord REST.
+"""Example showing how to work with webhook events in Pycord REST."""
 
-This is a minimal example showing how to create slash commands.
-"""
-
-import logging
 import os
 
 from dotenv import load_dotenv
@@ -16,10 +12,6 @@ from pycord_rest import App, ApplicationAuthorizedEvent
 # Load environment variables from .env file
 load_dotenv()
 
-
-# Set up logging
-logging.basicConfig(level=logging.DEBUG)
-
 app = App()
 
 
@@ -31,7 +23,7 @@ async def on_application_authorized(event: ApplicationAuthorizedEvent) -> None:
 
     else:
         print(
-            f"Bot {event.user.display_name} ({event.user.id}) installed the application"  # noqa: ISC003
+            f"Bot {event.user.display_name} ({event.user.id}) installed the application"
             + f" to guild {event.guild.name} ({event.guild.id})."
         )
 

pyproject.toml

@@ -1,12 +1,11 @@
 [build-system]
-requires = ["hatchling", "hatch-vcs"]
+requires = ["hatchling", "hatch-vcs", "hatch-fancy-pypi-readme"]
 build-backend = "hatchling.build"
 
 [project]
 name = "pycord-rest-bot"
-dynamic = ["version", "urls"]
-description = "A discord rest-bot wrapper for pycord"
-readme = "README.md"
+dynamic = ["version", "urls", "readme"]
+description = "A lightweight wrapper for Discord's HTTP interactions and webhook events using py-cord and FastAPI"
 authors = [
     { name = "Paillat-dev", email = "me@paillat.dev" }
 ]
@@ -17,13 +16,15 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.12"
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+    "Operating System :: OS Independent",
 ]
 keywords = ["discord", "bot", "rest", "pycord"]
 dependencies = [
     "fastapi>=0.115.11",
     "orjson>=3.10.15",
-    "py-cord==2.6.1",
+    "paillcord>=2.7.0a3",
     "pynacl>=1.5.0",
     "uvicorn>=0.34.0",
 ]
@@ -45,6 +46,34 @@ version-file = "src/pycord_rest/_version.py"
 Homepage = "https://github.com/Paillat-dev/pycord-rest"
 source_archive = "https://github.com/Paillat-dev/pycord-rest/archive/{commit_hash}.zip"
 
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+start-after = "<!-- badges -->\n"
+end-before = "\n<!-- end badges -->"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+text = "\n\n---\n"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+start-after = "## Overview\n"
+end-before = "\n## Installation"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+start-after = "<!-- quick-start -->"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '\[(.+?)\]\(((?!https?://)\S+?)\)'
+replacement = '[\1](https://github.com/Paillat-dev/pycord-rest/tree/main\g<2>)'
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]'
+replacement = '**\1**:'
+
 [tool.hatchling]
 name = "pycord-rest-bot"
 
@@ -116,5 +145,6 @@ extend-ignore = [
     "FBT002",
     "PLR2004",
     "PLR0913",
-    "C901"
+    "C901",
+    "ISC003" # conflicts with basedpyright reportImplicitStringConcatenation
 ]

renovate.json

@@ -8,12 +8,12 @@
   "commitMessageAction": "Upgrade",
   "packageRules": [
     {
-      "updateTypes": ["pin"],
+      "matchUpdateTypes": ["pin"],
       "commitMessagePrefix": "📌",
       "commitMessageAction": "Pin"
     },
     {
-      "updateTypes": ["rollback"],
+      "matchUpdateTypes": ["rollback"],
       "commitMessagePrefix": "⬇️",
       "commitMessageAction": "Downgrade"
     },

src/pycord_rest/app.py

@@ -1,7 +1,9 @@
 # Copyright (c) Paillat-dev
 # SPDX-License-Identifier: MIT
 
+import functools
 import logging
+import warnings
 from collections.abc import Callable, Coroutine
 from functools import cached_property
 from typing import Any, Never, override
@@ -11,10 +13,10 @@ import discord
 import uvicorn
 from discord import Entitlement, Interaction, InteractionType
 from fastapi import APIRouter, Depends, FastAPI, HTTPException, Request, Response
-from fastapi.exceptions import FastAPIError
 from nacl.exceptions import BadSignatureError
 from nacl.signing import VerifyKey
 
+from .errors import InvalidCredentialsError
 from .models import EventType, WebhookEventPayload, WebhookType
 
 logger = logging.getLogger("pycord.rest")
@@ -35,31 +37,56 @@ class ApplicationAuthorizedEvent:
         )
 
 
+def not_supported[T, U](func: Callable[[T], U]) -> Callable[[T], U]:
+    @functools.wraps(func)
+    def inner(*args: T, **kwargs: T) -> U:
+        logger.warning(f"{func.__qualname__} is not supported by REST apps.")
+        warnings.warn(
+            f"{func.__qualname__} is not supported by REST apps.",
+            SyntaxWarning,
+            stacklevel=2,
+        )
+        return func(*args, **kwargs)
+
+    return inner
+
+
 class App(discord.Bot):
-    def __init__(self, *args: Any, **options: Any) -> None:  # pyright: ignore [reportExplicitAny]
+    _UvicornConfig: type[uvicorn.Config] = uvicorn.Config
+    _UvicornServer: type[uvicorn.Server] = uvicorn.Server
+    _FastAPI: type[FastAPI] = FastAPI
+    _APIRouter: type[APIRouter] = APIRouter
+
+    def __init__(self, *args: Any, path_prefix: str = "", **options: Any) -> None:  # pyright: ignore [reportExplicitAny]
         super().__init__(*args, **options)  # pyright: ignore [reportUnknownMemberType]
-        self.app: FastAPI = FastAPI(openapi_url=None, docs_url=None, redoc_url=None)
-        self.router: APIRouter = APIRouter()
-        self.public_key: str | None = None
+        self._app: FastAPI = self._FastAPI(openapi_url=None, docs_url=None, redoc_url=None)
+        self.router: APIRouter = self._APIRouter(prefix=path_prefix)
+        self._public_key: str | None = None
+
+    @property
+    @override
+    @not_supported
+    def latency(self) -> float:
+        return 0.0
 
     @cached_property
     def _verify_key(self) -> VerifyKey:
-        if self.public_key is None:
-            raise FastAPIError("No public key provided")
-        return VerifyKey(bytes.fromhex(self.public_key))
+        if self._public_key is None:
+            raise InvalidCredentialsError("No public key provided")
+        return VerifyKey(bytes.fromhex(self._public_key))
 
     async def _dispatch_view(self, component_type: int, custom_id: str, interaction: Interaction) -> None:
         # Code taken from ViewStore.dispatch
         self._connection._view_store._ViewStore__verify_integrity()  # noqa: SLF001  # pyright: ignore [reportUnknownMemberType, reportAttributeAccessIssue, reportPrivateUsage]
         message_id: int | None = interaction.message and interaction.message.id
         key = (component_type, message_id, custom_id)
-        value = self._connection._view_store._views.get(key) or self._connection._view_store._views.get(  # pyright: ignore [reportUnknownVariableType, reportUnknownMemberType, reportPrivateUsage]  # noqa: SLF001
+        value = self._connection._view_store._views.get(key) or self._connection._view_store._views.get(  # pyright: ignore [reportPrivateUsage]  # noqa: SLF001
             (component_type, None, custom_id)
         )
         if value is None:
             return
 
-        view, item = value  # pyright: ignore [reportUnknownVariableType]
+        view, item = value
         item.refresh_state(interaction)
 
         # Code taken from View._dispatch_item
@@ -69,7 +96,7 @@ class App(discord.Bot):
         if interaction.message:
             view.message = interaction.message
 
-        await view._scheduled_task(item, interaction)  # noqa: SLF001  # pyright: ignore [reportPrivateUsage, reportUnknownMemberType]
+        await view._scheduled_task(item, interaction)  # noqa: SLF001 # pyright: ignore [reportPrivateUsage]
 
     async def _verify_request(self, request: Request) -> None:
         signature = request.headers["X-Signature-Ed25519"]
@@ -110,6 +137,7 @@ class App(discord.Bot):
     async def process_application_commands(  # noqa: PLR0912
         self, interaction: Interaction, auto_sync: bool | None = None
     ) -> None:
+        # Code taken from super().process_application_commands
         if auto_sync is None:
             auto_sync = self._bot.auto_sync_commands  # pyright: ignore [reportUnknownVariableType, reportUnknownMemberType]
         # TODO: find out why the isinstance check below doesn't stop the type errors below  # noqa: FIX002, TD002, TD003
@@ -231,16 +259,17 @@ class App(discord.Bot):
         uvicorn_options: dict[str, Any] | None = None,  # pyright: ignore [reportExplicitAny]
         health: bool = True,
     ) -> None:
-        self.public_key = public_key
+        self._public_key = public_key
         _ = self._process_interaction_factory()
         _ = self._webhook_event_factory()
         if health:
             _ = self._health_factory()
-        self.app.include_router(self.router)
+        self._app.include_router(self.router)
         uvicorn_options = uvicorn_options or {}
         uvicorn_options["log_level"] = uvicorn_options.get("log_level", logging.root.level)
-        config = uvicorn.Config(self.app, **uvicorn_options)
-        server = uvicorn.Server(config)
+        uvicorn_options["server_header"] = uvicorn_options.get("server_header", False)
+        config = self._UvicornConfig(self._app, **uvicorn_options)
+        server = self._UvicornServer(config)
         try:
             self.dispatch("connect")
             await server.serve()
@@ -250,7 +279,10 @@ class App(discord.Bot):
 
     @override
     async def close(self) -> None:
-        pass
+        self._closed: bool = True
+
+        await self.http.close()
+        self._ready.clear()
 
     @override
     async def start(  # pyright: ignore [reportIncompatibleMethodOverride]
@@ -260,6 +292,10 @@ class App(discord.Bot):
         uvicorn_options: dict[str, Any] | None = None,  # pyright: ignore [reportExplicitAny]
         health: bool = True,
     ) -> None:
+        if not token:
+            raise InvalidCredentialsError("No token provided")
+        if not public_key:
+            raise InvalidCredentialsError("No public key provided")
         await self.login(token)
         await self.connect(
             token=token,

src/pycord_rest/errors.py

@@ -0,0 +1,12 @@
+# Copyright (c) Paillat-dev
+# SPDX-License-Identifier: MIT
+
+import discord
+
+
+class PycordRestError(discord.DiscordException):
+    pass
+
+
+class InvalidCredentialsError(PycordRestError):
+    pass

uv.lock

@@ -260,6 +260,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ed/eb/a85317ee1732d1034b92d56f89f1de4d7bf7904f5c8fb9dcdd5b1c83917f/orjson-3.10.15-cp312-cp312-win_amd64.whl", hash = "sha256:ef5b87e7aa9545ddadd2309efe6824bd3dd64ac101c15dae0f2f597911d46eaa", size = 133732 },
 ]
 
+[[package]]
+name = "paillcord"
+version = "2.7.0a3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "aiohttp" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5f/23/ae29cedaa6822d85b553407f7287fb355cb85ad9fefa10454aee11b6c256/paillcord-2.7.0a3.tar.gz", hash = "sha256:32e46935a72ef4df1619f551b1464ba21c59db9b524dfe87177c8003510caec1", size = 974819 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c4/da/da5f56051c68e4b749d7b54a6b27aa27b7968a6a4787ff9b49184a88f717/paillcord-2.7.0a3-py3-none-any.whl", hash = "sha256:76f553b48075ff633b7f6182e6238ff374bb7c55e512c9384dfea7bd546dd609", size = 1117883 },
+]
+
 [[package]]
 name = "propcache"
 version = "0.3.0"
@@ -285,25 +298,13 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b5/35/6c4c6fc8774a9e3629cd750dc24a7a4fb090a25ccd5c3246d127b70f9e22/propcache-0.3.0-py3-none-any.whl", hash = "sha256:67dda3c7325691c2081510e92c561f465ba61b975f481735aefdfc845d2cd043", size = 12101 },
 ]
 
-[[package]]
-name = "py-cord"
-version = "2.6.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "aiohttp" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/27/c7/c539d69d5cfa1ea5891d596212f73d619e40c7fc9f02ae906f4147993b94/py_cord-2.6.1.tar.gz", hash = "sha256:36064f225f2c7bbddfe542d5ed581f2a5744f618e039093cf7cd2659a58bc79b", size = 965087 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/e7/90/2690ded84e34b15ca2619932a358c1b7dc6d28fe845dfbd01929fc33c9da/py_cord-2.6.1-py3-none-any.whl", hash = "sha256:e3d3b528c5e37b0e0825f5b884cbb9267860976c1e4878e28b55da8fd3af834b", size = 1089154 },
-]
-
 [[package]]
 name = "pycord-rest-bot"
 source = { editable = "." }
 dependencies = [
     { name = "fastapi" },
     { name = "orjson" },
-    { name = "py-cord" },
+    { name = "paillcord" },
     { name = "pynacl" },
     { name = "uvicorn" },
 ]
@@ -319,7 +320,7 @@ dev = [
 requires-dist = [
     { name = "fastapi", specifier = ">=0.115.11" },
     { name = "orjson", specifier = ">=3.10.15" },
-    { name = "py-cord", specifier = "==2.6.1" },
+    { name = "paillcord", specifier = ">=2.7.0a3" },
     { name = "pynacl", specifier = ">=1.5.0" },
     { name = "uvicorn", specifier = ">=0.34.0" },
 ]