From 0539c047517e6352906963f5fd1252046e85a065 Mon Sep 17 00:00:00 2001 From: DLCHAMP <36091350+dlchamp@users.noreply.github.com> Date: Wed, 16 Aug 2023 10:48:27 -0500 Subject: [PATCH 1/3] feat: update popular-topics/webhooks --- guide/docs/popular-topics/webhooks.mdx | 98 +++++++++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) diff --git a/guide/docs/popular-topics/webhooks.mdx b/guide/docs/popular-topics/webhooks.mdx index b312f481..a9d926c8 100644 --- a/guide/docs/popular-topics/webhooks.mdx +++ b/guide/docs/popular-topics/webhooks.mdx @@ -4,5 +4,101 @@ hide_table_of_contents: true --- # Webhooks +Webhooks provide a way to send messages to guild channels without a bot user or authentication. - +## Creating or Fetching webhooks +There are two main ways of using webhooks in disnake. + + +1. The first method involves fetching existing Webhooks from a Guild or Channel, or creating a new webhook. + - `await Guild.webhooks()` - Fetches a list of webhooks available in the guild. + - `await Channel.webhooks()` - Fetches a list of webhooks available in the channel. + - `await Channel.create_webhook()` - Creates and returns the created Webhook for the Channel. (Requires manage_webhooks) + - Supported Channels for `.webhooks()` and `.create_webhook()`: + - TextChannel + - ForumChannel + - VoiceChannel + - StageChannel + +:::note +Webhooks fetched or created using these methods are automatically bound to the bot's internal HTTP session. +::: + + +2. The second way involves creating partial webhooks using the following methods: + - Webhook.from_url() - Create a Webhook from a channel's webhook URL. + - Webhook.partial() - Create a Webhook with an `id`, webhook `token`, and optional `bot_token` + +:::note +Webhooks created using these methods require that you create and manage a separate HTTP session. +An [example of this](#creating-a-webhook-from-a-url) is available further down this page. +::: + + +### Other Webhook methods +- Webhook.fetch - Useful for fetching the full webhook from a partial webhook. +- Webhook.delete - Deletes the webhook. (Requires manage_webhooks) +- Webhook.edit - Edits the webhook (Requires manage_webhooks) +- Webhook.fetch_message - Fetches a WebhookMessage owned by the webhook using the messages's ID. +- Webhook.send - Sends a message using the Webhook. + + +### Creating a Webhook from a URL +```python title="webhook_from_url.py" +import disnake +import asyncio +import aiohttp + +URL = "https://discord.com/api/webhooks/808030843078836254/H82Ba5B958KkeAG4u4A3otcQvl64XPFNqmlP2aMmpJbCHntrEfxgoqE7_OZAzqP9Z2Dr" + +async def main(): + + # Create the HTTP session using aiohttp.ClientSession + async with aiohttp.ClientSession() as session: + # Construct the Webhook from the URL using the HTTP session. + webhook = disnake.Webhook.from_url(URL, session=session) + # Send a message using the webhook with a custom username. + # Webhook `username` and `avatar` can be changed for each message that is sent. + # Doing this in the `.send` method will not alter the Webhook as it appears in the + # Guild or Channel integrations. + await webhook.send('I sent my first webhook!.', username='Webhook!') + +if __name__ == '__main__': + asyncio.run(main()) +``` + +## SyncWebhook +When working with Webhooks in the context of a bot, it's advisable to utilize disnake.Webhook to maintain an asynchronous approach. +Nevertheless, disnake does offer an alternative synchronous variant of Webhooks known as disnake.SyncWebhook, designed for scenarios +outside the realm of asynchronous projects. + +It's important to note that this version of the `Webhook` should be avoided in asynchronous projects, as its HTTP requests rely on the synchronous and blocking +[Requests](https://requests.readthedocs.io/en/latest/) library. + +Usage of this object remains largely consistent; the primary distinction is the utilization of [Requests](https://requests.readthedocs.io/en/latest/) for managing the HTTP session. + +### SyncWebhook example +```python title='sync_webhook.py' +import requests +import disnake + + +URL = "https://discord.com/api/webhooks/808030843078836254/H82Ba5B958KkeAG4u4A3otcQvl64XPFNqmlP2aMmpJbCHntrEfxgoqE7_OZAzqP9Z2Dr" + +def main(): + + # This time we create a requests.Session + with requests.Session() as session: + + # We are still passing the session to the Webhook, however + # it should be noted that if a session is not provided, the + # webhook will create it's own `requests.Session` and use that instead. + webhook = disnake.SyncWebhook.from_url(URL, session=session) + + # Notice we do not `await` the `webhook.send` method this time. + webhook.send('My first synchronous webhook!', username='SyncWebhook!') + +if __name__ == "__main__": + main() + +``` \ No newline at end of file From 5f15d57a0aad5c33324af02f8b7a00a412aefda8 Mon Sep 17 00:00:00 2001 From: DLCHAMP <36091350+dlchamp@users.noreply.github.com> Date: Wed, 16 Aug 2023 10:49:06 -0500 Subject: [PATCH 2/3] run pre-commit task --- guide/docs/popular-topics/webhooks.mdx | 56 +++++++++++++++++--------- 1 file changed, 36 insertions(+), 20 deletions(-) diff --git a/guide/docs/popular-topics/webhooks.mdx b/guide/docs/popular-topics/webhooks.mdx index a9d926c8..3ab73a39 100644 --- a/guide/docs/popular-topics/webhooks.mdx +++ b/guide/docs/popular-topics/webhooks.mdx @@ -4,13 +4,14 @@ hide_table_of_contents: true --- # Webhooks + Webhooks provide a way to send messages to guild channels without a bot user or authentication. ## Creating or Fetching webhooks -There are two main ways of using webhooks in disnake. +There are two main ways of using webhooks in disnake. -1. The first method involves fetching existing Webhooks from a Guild or Channel, or creating a new webhook. +1. The first method involves fetching existing Webhooks from a Guild or Channel, or creating a new webhook. - `await Guild.webhooks()` - Fetches a list of webhooks available in the guild. - `await Channel.webhooks()` - Fetches a list of webhooks available in the channel. - `await Channel.create_webhook()` - Creates and returns the created Webhook for the Channel. (Requires manage_webhooks) @@ -18,32 +19,42 @@ There are two main ways of using webhooks in disnake. - TextChannel - ForumChannel - VoiceChannel - - StageChannel + - StageChannel{' '} :::note Webhooks fetched or created using these methods are automatically bound to the bot's internal HTTP session. ::: - 2. The second way involves creating partial webhooks using the following methods: - - Webhook.from_url() - Create a Webhook from a channel's webhook URL. - - Webhook.partial() - Create a Webhook with an `id`, webhook `token`, and optional `bot_token` + - Webhook.from_url() - Create a Webhook from a channel's webhook + URL. + - Webhook.partial() - Create a Webhook with an `id`, webhook + `token`, and optional `bot_token` :::note -Webhooks created using these methods require that you create and manage a separate HTTP session. +Webhooks created using these methods require that you create and manage a separate HTTP session. An [example of this](#creating-a-webhook-from-a-url) is available further down this page. ::: - ### Other Webhook methods -- Webhook.fetch - Useful for fetching the full webhook from a partial webhook. -- Webhook.delete - Deletes the webhook. (Requires manage_webhooks) -- Webhook.edit - Edits the webhook (Requires manage_webhooks) -- Webhook.fetch_message - Fetches a WebhookMessage owned by the webhook using the messages's ID. -- Webhook.send - Sends a message using the Webhook. +- Webhook.fetch - Useful for fetching the full webhook from a partial + webhook. +- Webhook.delete - Deletes the webhook. (Requires + manage_webhooks + + ) +- Webhook.edit - Edits the webhook (Requires + manage_webhooks + + ) +- Webhook.fetch_message - Fetches a + WebhookMessage + owned by the webhook using the messages's ID. +- Webhook.send - Sends a message using the Webhook. ### Creating a Webhook from a URL + ```python title="webhook_from_url.py" import disnake import asyncio @@ -51,6 +62,7 @@ import aiohttp URL = "https://discord.com/api/webhooks/808030843078836254/H82Ba5B958KkeAG4u4A3otcQvl64XPFNqmlP2aMmpJbCHntrEfxgoqE7_OZAzqP9Z2Dr" + async def main(): # Create the HTTP session using aiohttp.ClientSession @@ -61,13 +73,15 @@ async def main(): # Webhook `username` and `avatar` can be changed for each message that is sent. # Doing this in the `.send` method will not alter the Webhook as it appears in the # Guild or Channel integrations. - await webhook.send('I sent my first webhook!.', username='Webhook!') + await webhook.send("I sent my first webhook!.", username="Webhook!") -if __name__ == '__main__': + +if __name__ == "__main__": asyncio.run(main()) ``` ## SyncWebhook + When working with Webhooks in the context of a bot, it's advisable to utilize disnake.Webhook to maintain an asynchronous approach. Nevertheless, disnake does offer an alternative synchronous variant of Webhooks known as disnake.SyncWebhook, designed for scenarios outside the realm of asynchronous projects. @@ -78,6 +92,7 @@ It's important to note that this version of the `Webhook` should be avoided in a Usage of this object remains largely consistent; the primary distinction is the utilization of [Requests](https://requests.readthedocs.io/en/latest/) for managing the HTTP session. ### SyncWebhook example + ```python title='sync_webhook.py' import requests import disnake @@ -85,8 +100,9 @@ import disnake URL = "https://discord.com/api/webhooks/808030843078836254/H82Ba5B958KkeAG4u4A3otcQvl64XPFNqmlP2aMmpJbCHntrEfxgoqE7_OZAzqP9Z2Dr" + def main(): - + # This time we create a requests.Session with requests.Session() as session: @@ -94,11 +110,11 @@ def main(): # it should be noted that if a session is not provided, the # webhook will create it's own `requests.Session` and use that instead. webhook = disnake.SyncWebhook.from_url(URL, session=session) - + # Notice we do not `await` the `webhook.send` method this time. - webhook.send('My first synchronous webhook!', username='SyncWebhook!') + webhook.send("My first synchronous webhook!", username="SyncWebhook!") + if __name__ == "__main__": main() - -``` \ No newline at end of file +``` From 5f245e38893a77dd8ac7c32fc2d1d8637f237d98 Mon Sep 17 00:00:00 2001 From: DLCHAMP <36091350+dlchamp@users.noreply.github.com> Date: Wed, 16 Aug 2023 13:21:35 -0500 Subject: [PATCH 3/3] spelling and stuff Remove a somehow randomly added "{' '}" on line 22 Reworded short descriptions for Webhook.from_url and .partial. Expanded on the usage of session within the note for the section that needed it. --- guide/docs/popular-topics/webhooks.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/guide/docs/popular-topics/webhooks.mdx b/guide/docs/popular-topics/webhooks.mdx index 3ab73a39..b8be41e3 100644 --- a/guide/docs/popular-topics/webhooks.mdx +++ b/guide/docs/popular-topics/webhooks.mdx @@ -19,20 +19,20 @@ There are two main ways of using webhooks in disnake. - TextChannel - ForumChannel - VoiceChannel - - StageChannel{' '} + - StageChannel :::note Webhooks fetched or created using these methods are automatically bound to the bot's internal HTTP session. ::: 2. The second way involves creating partial webhooks using the following methods: - - Webhook.from_url() - Create a Webhook from a channel's webhook + - Webhook.from_url() - Create a Webhook from only a webhook URL. - - Webhook.partial() - Create a Webhook with an `id`, webhook - `token`, and optional `bot_token` + - Webhook.partial() - Create a Webhook with only a webhook ID, + and token. :::note -Webhooks created using these methods require that you create and manage a separate HTTP session. +Webhooks created using these methods require that you create and manage a separate HTTP session that is provided to the method used. An [example of this](#creating-a-webhook-from-a-url) is available further down this page. :::