From 9237d12a2460d90d9d26c6aa5f59a5d9ac81189b Mon Sep 17 00:00:00 2001 From: Slipstreamm Date: Sat, 14 Jun 2025 18:44:04 -0600 Subject: [PATCH] docs(imports): Update import paths in documentation examples Adjust examples to reflect the new top-level exposure of classes and enums, such as `Client`, `Permissions`, `Embed`, and `Button`, making imports simpler. --- docs/commands.md | 2 +- docs/context_menus.md | 2 +- docs/converters.md | 2 +- docs/embeds.md | 2 +- docs/events.md | 18 +++++++++--------- docs/gateway.md | 2 ++ docs/http_client.md | 2 +- docs/introduction.md | 19 ++++++++++--------- docs/mentions.md | 4 ++-- docs/permissions.md | 4 ++-- docs/presence.md | 4 ++-- docs/reactions.md | 2 +- docs/scheduled_events.md | 2 +- docs/threads.md | 2 +- docs/typing_indicator.md | 4 ++-- docs/using_components.md | 23 ++++++++++------------- docs/webhooks.md | 6 +++--- 17 files changed, 50 insertions(+), 50 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index cbd3e0a..989d37e 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -57,7 +57,7 @@ required permissions in the channel. ```python from disagreement.ext.commands import command, requires_permissions -from disagreement.permissions import Permissions +from disagreement import Permissions @command() @requires_permissions(Permissions.MANAGE_MESSAGES) diff --git a/docs/context_menus.md b/docs/context_menus.md index af10f7b..81e0cb9 100644 --- a/docs/context_menus.md +++ b/docs/context_menus.md @@ -5,8 +5,8 @@ define them. ```python +from disagreement import User, Message from disagreement.ext.app_commands import user_command, message_command, AppCommandContext -from disagreement.models import User, Message @user_command(name="User Info") async def user_info(ctx: AppCommandContext, user: User) -> None: diff --git a/docs/converters.md b/docs/converters.md index af982ee..3b8f850 100644 --- a/docs/converters.md +++ b/docs/converters.md @@ -13,8 +13,8 @@ ```python from disagreement.ext.commands import command +from disagreement import Member from disagreement.ext.commands.core import CommandContext -from disagreement.models import Member @command() async def kick(ctx: CommandContext, target: Member): diff --git a/docs/embeds.md b/docs/embeds.md index bac95c6..c2df53c 100644 --- a/docs/embeds.md +++ b/docs/embeds.md @@ -4,7 +4,7 @@ These helper methods return the embed instance so you can chain calls. ```python -from disagreement.models import Embed +from disagreement import Embed embed = ( Embed() diff --git a/docs/events.md b/docs/events.md index 810944d..e669b5b 100644 --- a/docs/events.md +++ b/docs/events.md @@ -20,7 +20,7 @@ Triggered when a user's presence changes. The callback receives a `PresenceUpdat ```python @client.event -async def on_presence_update(presence: disagreement.PresenceUpdate): +async def on_presence_update(presence: PresenceUpdate): ... ``` @@ -30,7 +30,7 @@ Dispatched when a user begins typing in a channel. The callback receives a `Typi ```python @client.event -async def on_typing_start(typing: disagreement.TypingStart): +async def on_typing_start(typing: TypingStart): ... ``` @@ -40,7 +40,7 @@ Fired when a new member joins a guild. The callback receives a `Member` model. ```python @client.event -async def on_guild_member_add(member: disagreement.Member): +async def on_guild_member_add(member: Member): ... ``` @@ -51,7 +51,7 @@ receives a `GuildMemberRemove` model. ```python @client.event -async def on_guild_member_remove(event: disagreement.GuildMemberRemove): +async def on_guild_member_remove(event: GuildMemberRemove): ... ``` @@ -62,7 +62,7 @@ Dispatched when a user is banned from a guild. The callback receives a ```python @client.event -async def on_guild_ban_add(event: disagreement.GuildBanAdd): +async def on_guild_ban_add(event: GuildBanAdd): ... ``` @@ -73,7 +73,7 @@ Dispatched when a user's ban is lifted. The callback receives a ```python @client.event -async def on_guild_ban_remove(event: disagreement.GuildBanRemove): +async def on_guild_ban_remove(event: GuildBanRemove): ... ``` @@ -84,7 +84,7 @@ Sent when a channel's settings change. The callback receives an updated ```python @client.event -async def on_channel_update(channel: disagreement.Channel): +async def on_channel_update(channel: Channel): ... ``` @@ -95,7 +95,7 @@ Emitted when a guild role is updated. The callback receives a ```python @client.event -async def on_guild_role_update(event: disagreement.GuildRoleUpdate): +async def on_guild_role_update(event: GuildRoleUpdate): ... ``` @@ -138,6 +138,6 @@ Triggered when a user's voice connection state changes, such as joining or leavi ```python @client.event -async def on_voice_state_update(state: disagreement.VoiceStateUpdate): +async def on_voice_state_update(state: VoiceStateUpdate): ... ``` diff --git a/docs/gateway.md b/docs/gateway.md index 910a0ad..fd41868 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -8,6 +8,8 @@ You can control the maximum number of retries and the backoff cap when construct These options are forwarded to `GatewayClient` as `max_retries` and `max_backoff`: ```python +from disagreement import Client + bot = Client( token="your-token", gateway_max_retries=10, diff --git a/docs/http_client.md b/docs/http_client.md index d2a45af..a9af0b3 100644 --- a/docs/http_client.md +++ b/docs/http_client.md @@ -24,7 +24,7 @@ other supported session argument. The HTTP client can list the guilds the bot user is in: ```python -from disagreement.http import HTTPClient +from disagreement import HTTPClient http = HTTPClient(token="TOKEN") guilds = await http.get_current_user_guilds() diff --git a/docs/introduction.md b/docs/introduction.md index f1e5f4e..4e4061f 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -39,14 +39,14 @@ pip install "disagreement[dev]" import asyncio import os -import disagreement +from disagreement import Client, GatewayIntent from disagreement.ext import commands from dotenv import load_dotenv load_dotenv() class Basics(commands.Cog): - def __init__(self, client: disagreement.Client) -> None: + def __init__(self, client: Client) -> None: super().__init__(client) @commands.command() @@ -58,8 +58,8 @@ token = os.getenv("DISCORD_BOT_TOKEN") if not token: raise RuntimeError("DISCORD_BOT_TOKEN environment variable not set") -intents = disagreement.GatewayIntent.default() | disagreement.GatewayIntent.MESSAGE_CONTENT -client = disagreement.Client(token=token, command_prefix="!", intents=intents, mention_replies=True) +intents = GatewayIntent.default() | GatewayIntent.MESSAGE_CONTENT +client = Client(token=token, command_prefix="!", intents=intents, mention_replies=True) async def main() -> None: client.add_cog(Basics(client)) await client.run() @@ -100,10 +100,10 @@ setup_logging(logging.DEBUG, file="bot.log") ### HTTP Session Options Pass additional keyword arguments to ``aiohttp.ClientSession`` using the -``http_options`` parameter when constructing :class:`disagreement.Client`: +``http_options`` parameter when constructing :class:`Client`: ```python -client = disagreement.Client( +client = Client( token=token, http_options={"proxy": "http://localhost:8080"}, ) @@ -119,7 +119,7 @@ Specify default mention behaviour for all outgoing messages when constructing th ```python from disagreement.models import AllowedMentions -client = disagreement.Client( +client = Client( token=token, allowed_mentions=AllowedMentions.none().to_dict(), ) @@ -173,14 +173,15 @@ To run your bot across multiple gateway shards, pass ``shard_count`` when creati the client: ```python -client = disagreement.Client(token=BOT_TOKEN, shard_count=2) +client = Client(token=BOT_TOKEN, shard_count=2) ``` If you want the library to determine the recommended shard count automatically, use ``AutoShardedClient``: ```python -client = disagreement.AutoShardedClient(token=BOT_TOKEN) +from disagreement import AutoShardedClient +client = AutoShardedClient(token=BOT_TOKEN) ``` See `examples/sharded_bot.py` for a full example. diff --git a/docs/mentions.md b/docs/mentions.md index f1a9357..eed6a4d 100644 --- a/docs/mentions.md +++ b/docs/mentions.md @@ -8,8 +8,8 @@ Use the ``allowed_mentions`` parameter of :class:`disagreement.Client` to set a default for all messages: ```python -from disagreement.models import AllowedMentions -client = disagreement.Client( +from disagreement import AllowedMentions, Client +client = Client( token="YOUR_TOKEN", allowed_mentions=AllowedMentions.none().to_dict(), ) diff --git a/docs/permissions.md b/docs/permissions.md index 7392dac..ccc6429 100644 --- a/docs/permissions.md +++ b/docs/permissions.md @@ -10,7 +10,7 @@ Each attribute of ``Permissions`` represents a single permission bit. The value is a power of two so multiple permissions can be combined using bitwise OR. ```python -from disagreement.permissions import Permissions +from disagreement import Permissions value = Permissions.SEND_MESSAGES | Permissions.MANAGE_MESSAGES ``` @@ -47,10 +47,10 @@ Return a list of permissions that ``current`` does not contain. ```python from disagreement.permissions import ( - Permissions, has_permissions, missing_permissions, ) +from disagreement import Permissions current = Permissions.SEND_MESSAGES | Permissions.MANAGE_MESSAGES diff --git a/docs/presence.md b/docs/presence.md index ac87644..ee4b086 100644 --- a/docs/presence.md +++ b/docs/presence.md @@ -26,7 +26,7 @@ An activity dictionary must include a `name` and a `type` field. The type value Example using the provided activity classes: ```python -from disagreement.models import Game +from disagreement import Game await client.change_presence(status="idle", activity=Game("with Discord")) ``` @@ -34,7 +34,7 @@ await client.change_presence(status="idle", activity=Game("with Discord")) You can also specify a streaming URL: ```python -from disagreement.models import Streaming +from disagreement import Streaming await client.change_presence(status="online", activity=Streaming("My Stream", "https://twitch.tv/someone")) ``` diff --git a/docs/reactions.md b/docs/reactions.md index dba2b43..9a1ac73 100644 --- a/docs/reactions.md +++ b/docs/reactions.md @@ -48,7 +48,7 @@ The event handlers for these events receive both a `Reaction` object and the `Us ```python import disagreement -from disagreement.models import Reaction, User, Member +from disagreement import Reaction, User, Member @client.on_event("MESSAGE_REACTION_ADD") async def on_reaction_add(reaction: Reaction, user: User | Member): diff --git a/docs/scheduled_events.md b/docs/scheduled_events.md index 12b67a0..a745729 100644 --- a/docs/scheduled_events.md +++ b/docs/scheduled_events.md @@ -3,7 +3,7 @@ The `Client` provides helpers to manage guild scheduled events. ```python -from disagreement.client import Client +from disagreement import Client client = Client(token="TOKEN") diff --git a/docs/threads.md b/docs/threads.md index 3853e9c..4b9e716 100644 --- a/docs/threads.md +++ b/docs/threads.md @@ -4,7 +4,7 @@ Use :class:`AutoArchiveDuration` to control when a thread is automatically archived. ```python -from disagreement.enums import AutoArchiveDuration +from disagreement import AutoArchiveDuration await message.create_thread( "discussion", diff --git a/docs/typing_indicator.md b/docs/typing_indicator.md index 0550047..930522f 100644 --- a/docs/typing_indicator.md +++ b/docs/typing_indicator.md @@ -4,9 +4,9 @@ The library exposes an async context manager to send the typing indicator for a ```python import asyncio -import disagreement +from disagreement import Client -client = disagreement.Client(token="YOUR_TOKEN") +client = Client(token="YOUR_TOKEN") async def indicate(channel_id: str): async with client.typing(channel_id): diff --git a/docs/using_components.md b/docs/using_components.md index a5cb942..e987217 100644 --- a/docs/using_components.md +++ b/docs/using_components.md @@ -19,8 +19,7 @@ The library exposes three broad categories of components: `ActionRow` is a layout container. It may hold up to five buttons or a single select menu. ```python -from disagreement.models import ActionRow, Button -from disagreement.enums import ButtonStyle +from disagreement import ActionRow, Button, ButtonStyle row = ActionRow(components=[ Button(style=ButtonStyle.PRIMARY, label="Click", custom_id="btn") @@ -32,8 +31,7 @@ row = ActionRow(components=[ Buttons provide a clickable UI element. ```python -from disagreement.models import Button -from disagreement.enums import ButtonStyle +from disagreement import Button, ButtonStyle button = Button( style=ButtonStyle.SUCCESS, @@ -47,8 +45,7 @@ button = Button( `SelectMenu` lets the user choose one or more options. The `type` parameter controls the menu variety (`STRING_SELECT`, `USER_SELECT`, `ROLE_SELECT`, `MENTIONABLE_SELECT`, `CHANNEL_SELECT`). ```python -from disagreement.models import SelectMenu, SelectOption -from disagreement.enums import ComponentType, ChannelType +from disagreement import SelectMenu, SelectOption, ComponentType, ChannelType menu = SelectMenu( custom_id="example", @@ -70,7 +67,7 @@ For channel selects you may pass `channel_types` with a list of allowed `Channel `Section` groups one or more `TextDisplay` components and can include an accessory `Button` or `Thumbnail`. ```python -from disagreement.models import Section, TextDisplay, Thumbnail, UnfurledMediaItem +from disagreement import Section, TextDisplay, Thumbnail, UnfurledMediaItem section = Section( components=[ @@ -86,7 +83,7 @@ section = Section( `TextDisplay` simply renders markdown text. ```python -from disagreement.models import TextDisplay +from disagreement import TextDisplay text_display = TextDisplay(content="**Bold text**") ``` @@ -96,7 +93,7 @@ text_display = TextDisplay(content="**Bold text**") `Thumbnail` shows a small image. Set `spoiler=True` to hide the image until clicked. ```python -from disagreement.models import Thumbnail, UnfurledMediaItem +from disagreement import Thumbnail, UnfurledMediaItem thumb = Thumbnail( media=UnfurledMediaItem(url="https://example.com/image.png"), @@ -110,7 +107,7 @@ thumb = Thumbnail( `MediaGallery` holds multiple `MediaGalleryItem` objects. ```python -from disagreement.models import MediaGallery, MediaGalleryItem, UnfurledMediaItem +from disagreement import MediaGallery, MediaGalleryItem, UnfurledMediaItem gallery = MediaGallery( items=[ @@ -125,7 +122,7 @@ gallery = MediaGallery( `File` displays an uploaded file. Use `spoiler=True` to mark it as a spoiler. ```python -from disagreement.models import File, UnfurledMediaItem +from disagreement import File, UnfurledMediaItem file_component = File( file=UnfurledMediaItem(url="attachment://file.zip"), @@ -138,7 +135,7 @@ file_component = File( `Separator` adds vertical spacing or an optional divider line between components. ```python -from disagreement.models import Separator +from disagreement import Separator separator = Separator(divider=True, spacing=2) ``` @@ -148,7 +145,7 @@ separator = Separator(divider=True, spacing=2) `Container` visually groups a set of components and can apply an accent colour or spoiler. ```python -from disagreement.models import Container, TextDisplay +from disagreement import Container, TextDisplay container = Container( components=[TextDisplay(content="Inside a container")], diff --git a/docs/webhooks.md b/docs/webhooks.md index 1cfbfb4..2dd4359 100644 --- a/docs/webhooks.md +++ b/docs/webhooks.md @@ -5,7 +5,7 @@ The `HTTPClient` includes helper methods for creating, editing and deleting Disc ## Create a webhook ```python -from disagreement.http import HTTPClient +from disagreement import HTTPClient http = HTTPClient(token="TOKEN") payload = {"name": "My Webhook"} @@ -27,7 +27,7 @@ await http.delete_webhook("456") The methods now return a `Webhook` object directly: ```python -from disagreement.models import Webhook +from disagreement import Webhook print(webhook.id, webhook.name) ``` @@ -37,7 +37,7 @@ print(webhook.id, webhook.name) You can construct a `Webhook` object from an existing webhook URL without any API calls: ```python -from disagreement.models import Webhook +from disagreement import Webhook webhook = Webhook.from_url("https://discord.com/api/webhooks/123/token") print(webhook.id, webhook.token)