disagreement 0.1.0rc3__py3-none-any.whl → 0.2.0rc1__py3-none-any.whl

disagreement/__init__.py

@@ -14,10 +14,10 @@ __title__ = "disagreement"
 __author__ = "Slipstream"
 __license__ = "BSD 3-Clause License"
 __copyright__ = "Copyright 2025 Slipstream"
-__version__ = "0.1.0rc3"
+__version__ = "0.2.0rc1"
 
 from .client import Client, AutoShardedClient
-from .models import Message, User, Reaction
+from .models import Message, User, Reaction, AuditLogEntry
 from .voice_client import VoiceClient
 from .audio import AudioSource, FFmpegAudioSource
 from .typing import Typing

disagreement/client.py

@@ -12,6 +12,7 @@ from typing import (
     Any,
     TYPE_CHECKING,
     Awaitable,
+    AsyncIterator,
     Union,
     List,
     Dict,
@@ -22,7 +23,7 @@ from .http import HTTPClient
 from .gateway import GatewayClient
 from .shard_manager import ShardManager
 from .event_dispatcher import EventDispatcher
-from .enums import GatewayIntent, InteractionType, GatewayOpcode
+from .enums import GatewayIntent, InteractionType, GatewayOpcode, VoiceRegion
 from .errors import DisagreementException, AuthenticationError
 from .typing import Typing
 from .ext.commands.core import CommandHandler
@@ -50,6 +51,10 @@ if TYPE_CHECKING:
         Thread,
         DMChannel,
         Webhook,
+        GuildTemplate,
+        ScheduledEvent,
+        AuditLogEntry,
+        Invite,
     )
     from .ui.view import View
     from .enums import ChannelType as EnumChannelType
@@ -72,6 +77,9 @@ class Client:
         command_prefix (Union[str, List[str], Callable[['Client', Message], Union[str, List[str]]]]):
             The prefix(es) for commands. Defaults to '!'.
         verbose (bool): If True, print raw HTTP and Gateway traffic for debugging.
+        http_options (Optional[Dict[str, Any]]): Extra options passed to
+            :class:`HTTPClient` for creating the internal
+            :class:`aiohttp.ClientSession`.
     """
 
     def __init__(
@@ -88,6 +96,7 @@ class Client:
         shard_count: Optional[int] = None,
         gateway_max_retries: int = 5,
         gateway_max_backoff: float = 60.0,
+        http_options: Optional[Dict[str, Any]] = None,
     ):
         if not token:
             raise ValueError("A bot token must be provided.")
@@ -101,7 +110,11 @@ class Client:
         setup_global_error_handler(self.loop)
 
         self.verbose: bool = verbose
-        self._http: HTTPClient = HTTPClient(token=self.token, verbose=verbose)
+        self._http: HTTPClient = HTTPClient(
+            token=self.token,
+            verbose=verbose,
+            **(http_options or {}),
+        )
         self._event_dispatcher: EventDispatcher = EventDispatcher(client_instance=self)
         self._gateway: Optional[GatewayClient] = (
             None  # Initialized in run() or connect()
@@ -698,6 +711,40 @@ class Client:
         self._webhooks[webhook.id] = webhook
         return webhook
 
+    def parse_template(self, data: Dict[str, Any]) -> "GuildTemplate":
+        """Parses template data into a GuildTemplate object."""
+
+        from .models import GuildTemplate
+
+        return GuildTemplate(data, client_instance=self)
+
+    def parse_scheduled_event(self, data: Dict[str, Any]) -> "ScheduledEvent":
+        """Parses scheduled event data and updates cache."""
+
+        from .models import ScheduledEvent
+
+        event = ScheduledEvent(data, client_instance=self)
+        # Cache by ID under guild if guild cache exists
+        guild = self._guilds.get(event.guild_id)
+        if guild is not None:
+            events = getattr(guild, "_scheduled_events", {})
+            events[event.id] = event
+            setattr(guild, "_scheduled_events", events)
+        return event
+
+    def parse_audit_log_entry(self, data: Dict[str, Any]) -> "AuditLogEntry":
+        """Parses audit log entry data."""
+        from .models import AuditLogEntry
+
+        return AuditLogEntry(data, client_instance=self)
+
+    def parse_invite(self, data: Dict[str, Any]) -> "Invite":
+        """Parses invite data into an :class:`Invite`."""
+
+        from .models import Invite
+
+        return Invite.from_dict(data)
+
     async def fetch_user(self, user_id: Snowflake) -> Optional["User"]:
         """Fetches a user by ID from Discord."""
         if self._closed:
@@ -1219,6 +1266,31 @@ class Client:
             print(f"Failed to fetch channel {channel_id}: {e}")
             return None
 
+    async def fetch_audit_logs(
+        self, guild_id: Snowflake, **filters: Any
+    ) -> AsyncIterator["AuditLogEntry"]:
+        """Fetch audit log entries for a guild."""
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        data = await self._http.get_audit_logs(guild_id, **filters)
+        for entry in data.get("audit_log_entries", []):
+            yield self.parse_audit_log_entry(entry)
+
+    async def fetch_voice_regions(self) -> List[VoiceRegion]:
+        """Fetches available voice regions."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        data = await self._http.get_voice_regions()
+        regions = []
+        for region in data:
+            region_id = region.get("id")
+            if region_id:
+                regions.append(VoiceRegion(region_id))
+        return regions
+
     async def create_webhook(
         self, channel_id: Snowflake, payload: Dict[str, Any]
     ) -> "Webhook":
@@ -1249,6 +1321,130 @@ class Client:
 
         await self._http.delete_webhook(webhook_id)
 
+    async def fetch_templates(self, guild_id: Snowflake) -> List["GuildTemplate"]:
+        """|coro| Fetch all templates for a guild."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        data = await self._http.get_guild_templates(guild_id)
+        return [self.parse_template(t) for t in data]
+
+    async def create_template(
+        self, guild_id: Snowflake, payload: Dict[str, Any]
+    ) -> "GuildTemplate":
+        """|coro| Create a template for a guild."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        data = await self._http.create_guild_template(guild_id, payload)
+        return self.parse_template(data)
+
+    async def sync_template(
+        self, guild_id: Snowflake, template_code: str
+    ) -> "GuildTemplate":
+        """|coro| Sync a template to the guild's current state."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        data = await self._http.sync_guild_template(guild_id, template_code)
+        return self.parse_template(data)
+
+    async def delete_template(self, guild_id: Snowflake, template_code: str) -> None:
+        """|coro| Delete a guild template."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        await self._http.delete_guild_template(guild_id, template_code)
+
+    async def fetch_scheduled_events(
+        self, guild_id: Snowflake
+    ) -> List["ScheduledEvent"]:
+        """|coro| Fetch all scheduled events for a guild."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        data = await self._http.get_guild_scheduled_events(guild_id)
+        return [self.parse_scheduled_event(ev) for ev in data]
+
+    async def fetch_scheduled_event(
+        self, guild_id: Snowflake, event_id: Snowflake
+    ) -> Optional["ScheduledEvent"]:
+        """|coro| Fetch a single scheduled event."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        try:
+            data = await self._http.get_guild_scheduled_event(guild_id, event_id)
+            return self.parse_scheduled_event(data)
+        except DisagreementException as e:
+            print(f"Failed to fetch scheduled event {event_id}: {e}")
+            return None
+
+    async def create_scheduled_event(
+        self, guild_id: Snowflake, payload: Dict[str, Any]
+    ) -> "ScheduledEvent":
+        """|coro| Create a scheduled event in a guild."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        data = await self._http.create_guild_scheduled_event(guild_id, payload)
+        return self.parse_scheduled_event(data)
+
+    async def edit_scheduled_event(
+        self, guild_id: Snowflake, event_id: Snowflake, payload: Dict[str, Any]
+    ) -> "ScheduledEvent":
+        """|coro| Edit an existing scheduled event."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        data = await self._http.edit_guild_scheduled_event(guild_id, event_id, payload)
+        return self.parse_scheduled_event(data)
+
+    async def delete_scheduled_event(
+        self, guild_id: Snowflake, event_id: Snowflake
+    ) -> None:
+        """|coro| Delete a scheduled event."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        await self._http.delete_guild_scheduled_event(guild_id, event_id)
+
+    async def create_invite(
+        self, channel_id: Snowflake, payload: Dict[str, Any]
+    ) -> "Invite":
+        """|coro| Create an invite for the given channel."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        return await self._http.create_invite(channel_id, payload)
+
+    async def delete_invite(self, code: str) -> None:
+        """|coro| Delete an invite by code."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        await self._http.delete_invite(code)
+
+    async def fetch_invites(self, channel_id: Snowflake) -> List["Invite"]:
+        """|coro| Fetch all invites for a channel."""
+
+        if self._closed:
+            raise DisagreementException("Client is closed.")
+
+        data = await self._http.get_channel_invites(channel_id)
+        return [self.parse_invite(inv) for inv in data]
+
     # --- Application Command Methods ---
     async def process_interaction(self, interaction: Interaction) -> None:
         """Internal method to process an interaction from the gateway."""

disagreement/color.py

@@ -46,11 +46,110 @@ class Color:
     def blue(cls) -> "Color":
         return cls(0x0000FF)
 
+    # Discord brand colors
+    @classmethod
+    def blurple(cls) -> "Color":
+        """Discord brand blurple (#5865F2)."""
+        return cls(0x5865F2)
+
+    @classmethod
+    def light_blurple(cls) -> "Color":
+        """Light blurple used by Discord (#E0E3FF)."""
+        return cls(0xE0E3FF)
+
+    @classmethod
+    def legacy_blurple(cls) -> "Color":
+        """Legacy Discord blurple (#7289DA)."""
+        return cls(0x7289DA)
+
+    # Additional assorted colors
+    @classmethod
+    def teal(cls) -> "Color":
+        return cls(0x1ABC9C)
+
+    @classmethod
+    def dark_teal(cls) -> "Color":
+        return cls(0x11806A)
+
+    @classmethod
+    def brand_green(cls) -> "Color":
+        return cls(0x57F287)
+
+    @classmethod
+    def dark_green(cls) -> "Color":
+        return cls(0x206694)
+
+    @classmethod
+    def orange(cls) -> "Color":
+        return cls(0xE67E22)
+
+    @classmethod
+    def dark_orange(cls) -> "Color":
+        return cls(0xA84300)
+
+    @classmethod
+    def brand_red(cls) -> "Color":
+        return cls(0xED4245)
+
+    @classmethod
+    def dark_red(cls) -> "Color":
+        return cls(0x992D22)
+
+    @classmethod
+    def magenta(cls) -> "Color":
+        return cls(0xE91E63)
+
+    @classmethod
+    def dark_magenta(cls) -> "Color":
+        return cls(0xAD1457)
+
+    @classmethod
+    def purple(cls) -> "Color":
+        return cls(0x9B59B6)
+
+    @classmethod
+    def dark_purple(cls) -> "Color":
+        return cls(0x71368A)
+
+    @classmethod
+    def yellow(cls) -> "Color":
+        return cls(0xF1C40F)
+
+    @classmethod
+    def dark_gold(cls) -> "Color":
+        return cls(0xC27C0E)
+
+    @classmethod
+    def light_gray(cls) -> "Color":
+        return cls(0x99AAB5)
+
+    @classmethod
+    def dark_gray(cls) -> "Color":
+        return cls(0x2C2F33)
+
+    @classmethod
+    def lighter_gray(cls) -> "Color":
+        return cls(0xBFBFBF)
+
+    @classmethod
+    def darker_gray(cls) -> "Color":
+        return cls(0x23272A)
+
+    @classmethod
+    def black(cls) -> "Color":
+        return cls(0x000000)
+
+    @classmethod
+    def white(cls) -> "Color":
+        return cls(0xFFFFFF)
+
     def to_rgb(self) -> tuple[int, int, int]:
         return ((self.value >> 16) & 0xFF, (self.value >> 8) & 0xFF, self.value & 0xFF)
 
     @classmethod
-    def parse(cls, value: "Color | int | str | tuple[int, int, int] | None") -> "Color | None":
+    def parse(
+        cls, value: "Color | int | str | tuple[int, int, int] | None"
+    ) -> "Color | None":
         """Convert ``value`` to a :class:`Color` instance.
 
         Parameters

disagreement/enums.py

@@ -278,6 +278,62 @@ class GuildFeature(str, Enum):  # Changed from IntEnum to Enum
         return str(value)
 
 
+# --- Guild Scheduled Event Enums ---
+
+
+class GuildScheduledEventPrivacyLevel(IntEnum):
+    """Privacy level for a scheduled event."""
+
+    GUILD_ONLY = 2
+
+
+class GuildScheduledEventStatus(IntEnum):
+    """Status of a scheduled event."""
+
+    SCHEDULED = 1
+    ACTIVE = 2
+    COMPLETED = 3
+    CANCELED = 4
+
+
+class GuildScheduledEventEntityType(IntEnum):
+    """Entity type for a scheduled event."""
+
+    STAGE_INSTANCE = 1
+    VOICE = 2
+    EXTERNAL = 3
+
+
+class VoiceRegion(str, Enum):
+    """Voice region identifier."""
+
+    AMSTERDAM = "amsterdam"
+    BRAZIL = "brazil"
+    DUBAI = "dubai"
+    EU_CENTRAL = "eu-central"
+    EU_WEST = "eu-west"
+    EUROPE = "europe"
+    FRANKFURT = "frankfurt"
+    HONGKONG = "hongkong"
+    INDIA = "india"
+    JAPAN = "japan"
+    RUSSIA = "russia"
+    SINGAPORE = "singapore"
+    SOUTHAFRICA = "southafrica"
+    SOUTH_KOREA = "south-korea"
+    SYDNEY = "sydney"
+    US_CENTRAL = "us-central"
+    US_EAST = "us-east"
+    US_SOUTH = "us-south"
+    US_WEST = "us-west"
+    VIP_US_EAST = "vip-us-east"
+    VIP_US_WEST = "vip-us-west"
+
+    @classmethod
+    def _missing_(cls, value):  # type: ignore
+        return str(value)
+
+
 # --- Channel Enums ---
 
 
@@ -305,6 +361,13 @@ class ChannelType(IntEnum):
     GUILD_MEDIA = 16  # (Still in development) a channel that can only contain media
 
 
+class StageInstancePrivacyLevel(IntEnum):
+    """Privacy level of a stage instance."""
+
+    PUBLIC = 1
+    GUILD_ONLY = 2
+
+
 class OverwriteType(IntEnum):
     """Type of target for a permission overwrite."""
 

disagreement/ext/app_commands/commands.py

@@ -202,8 +202,6 @@ class MessageCommand(AppCommand):
         super().__init__(callback, type=ApplicationCommandType.MESSAGE, **kwargs)
 
 
-
-
 class AppCommandGroup:
     """
     Represents a group of application commands (subcommands or subcommand groups).

disagreement/ext/app_commands/handler.py

@@ -1,7 +1,9 @@
 # disagreement/ext/app_commands/handler.py
 
 import inspect
+import json
 import logging
+import os
 from typing import (
     TYPE_CHECKING,
     Dict,
@@ -67,6 +69,8 @@ if not TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+COMMANDS_CACHE_FILE = ".disagreement_commands.json"
+
 
 class AppCommandHandler:
     """
@@ -84,6 +88,33 @@ class AppCommandHandler:
         self._app_command_groups: Dict[str, AppCommandGroup] = {}
         self._converter_registry: Dict[type, type] = {}
 
+    def _load_cached_ids(self) -> Dict[str, Dict[str, str]]:
+        try:
+            with open(COMMANDS_CACHE_FILE, "r", encoding="utf-8") as fp:
+                return json.load(fp)
+        except FileNotFoundError:
+            return {}
+        except json.JSONDecodeError:
+            logger.warning("Invalid command cache file. Ignoring.")
+            return {}
+
+    def _save_cached_ids(self, data: Dict[str, Dict[str, str]]) -> None:
+        try:
+            with open(COMMANDS_CACHE_FILE, "w", encoding="utf-8") as fp:
+                json.dump(data, fp, indent=2)
+        except Exception as e:  # pragma: no cover - logging only
+            logger.error("Failed to write command cache: %s", e)
+
+    def clear_stored_registrations(self) -> None:
+        """Remove persisted command registration data."""
+        if os.path.exists(COMMANDS_CACHE_FILE):
+            os.remove(COMMANDS_CACHE_FILE)
+
+    def migrate_stored_registrations(self, new_path: str) -> None:
+        """Move stored registrations to ``new_path``."""
+        if os.path.exists(COMMANDS_CACHE_FILE):
+            os.replace(COMMANDS_CACHE_FILE, new_path)
+
     def add_command(self, command: Union["AppCommand", "AppCommandGroup"]) -> None:
         """Adds an application command or a command group to the handler."""
         if isinstance(command, AppCommandGroup):
@@ -564,11 +595,13 @@ class AppCommandHandler:
         Synchronizes (registers/updates) all application commands with Discord.
         If guild_id is provided, syncs commands for that guild. Otherwise, syncs global commands.
         """
-        commands_to_sync: List[Dict[str, Any]] = []
+        cache = self._load_cached_ids()
+        scope_key = str(guild_id) if guild_id else "global"
+        stored = cache.get(scope_key, {})
 
-        # Collect commands based on scope (global or specific guild)
-        # This needs to be more sophisticated to handle guild_ids on commands/groups
+        current_payloads: Dict[str, Dict[str, Any]] = {}
 
+        # Collect commands based on scope (global or specific guild)
         source_commands = (
             list(self._slash_commands.values())
             + list(self._user_commands.values())
@@ -577,26 +610,22 @@ class AppCommandHandler:
         )
 
         for cmd_or_group in source_commands:
-            # Determine if this command/group should be synced for the current scope
             is_guild_specific_command = (
                 cmd_or_group.guild_ids is not None and len(cmd_or_group.guild_ids) > 0
             )
 
-            if guild_id:  # Syncing for a specific guild
-                # Skip if not a guild-specific command OR if it's for a different guild
+            if guild_id:
                 if not is_guild_specific_command or (
                     cmd_or_group.guild_ids is not None
                     and guild_id not in cmd_or_group.guild_ids
                 ):
                     continue
-            else:  # Syncing global commands
+            else:
                 if is_guild_specific_command:
-                    continue  # Skip guild-specific commands when syncing global
+                    continue
 
-            # Use the to_dict() method from AppCommand or AppCommandGroup
             try:
-                payload = cmd_or_group.to_dict()
-                commands_to_sync.append(payload)
+                current_payloads[cmd_or_group.name] = cmd_or_group.to_dict()
             except AttributeError:
                 logger.warning(
                     "Command or group '%s' does not have a to_dict() method. Skipping.",
@@ -609,32 +638,74 @@ class AppCommandHandler:
                     e,
                 )
 
-        if not commands_to_sync:
+        if not current_payloads:
             logger.info(
                 "No commands to sync for %s scope.",
                 f"guild {guild_id}" if guild_id else "global",
             )
             return
 
+        names_current = set(current_payloads)
+        names_stored = set(stored)
+
+        to_delete = names_stored - names_current
+        to_create = names_current - names_stored
+        to_update = names_current & names_stored
+
+        if not to_delete and not to_create and not to_update:
+            logger.info(
+                "Application commands already up to date for %s scope.", scope_key
+            )
+            return
+
         try:
-            if guild_id:
-                logger.info(
-                    "Syncing %s commands for guild %s...",
-                    len(commands_to_sync),
-                    guild_id,
-                )
-                await self.client._http.bulk_overwrite_guild_application_commands(
-                    application_id, guild_id, commands_to_sync
-                )
-            else:
-                logger.info(
-                    "Syncing %s global commands...",
-                    len(commands_to_sync),
-                )
-                await self.client._http.bulk_overwrite_global_application_commands(
-                    application_id, commands_to_sync
-                )
+            for name in to_delete:
+                cmd_id = stored[name]
+                if guild_id:
+                    await self.client._http.delete_guild_application_command(
+                        application_id, guild_id, cmd_id
+                    )
+                else:
+                    await self.client._http.delete_global_application_command(
+                        application_id, cmd_id
+                    )
+
+            new_ids: Dict[str, str] = {}
+            for name in to_create:
+                payload = current_payloads[name]
+                if guild_id:
+                    result = await self.client._http.create_guild_application_command(
+                        application_id, guild_id, payload
+                    )
+                else:
+                    result = await self.client._http.create_global_application_command(
+                        application_id, payload
+                    )
+                if result.id:
+                    new_ids[name] = str(result.id)
+
+            for name in to_update:
+                payload = current_payloads[name]
+                cmd_id = stored[name]
+                if guild_id:
+                    await self.client._http.edit_guild_application_command(
+                        application_id, guild_id, cmd_id, payload
+                    )
+                else:
+                    await self.client._http.edit_global_application_command(
+                        application_id, cmd_id, payload
+                    )
+                new_ids[name] = cmd_id
+
+            final_ids: Dict[str, str] = {}
+            for name in names_current:
+                if name in new_ids:
+                    final_ids[name] = new_ids[name]
+                else:
+                    final_ids[name] = stored[name]
+
+            cache[scope_key] = final_ids
+            self._save_cached_ids(cache)
             logger.info("Command sync successful.")
         except Exception as e:
             logger.error("Error syncing application commands: %s", e)
-            # Consider re-raising or specific error handling

disagreement/ext/commands/__init__.py

@@ -16,6 +16,7 @@ from .decorators import (
     check,
     check_any,
     cooldown,
+    max_concurrency,
     requires_permissions,
 )
 from .errors import (
@@ -28,6 +29,7 @@ from .errors import (
     CheckAnyFailure,
     CommandOnCooldown,
     CommandInvokeError,
+    MaxConcurrencyReached,
 )
 
 __all__ = [
@@ -43,6 +45,7 @@ __all__ = [
     "check",
     "check_any",
     "cooldown",
+    "max_concurrency",
     "requires_permissions",
     # Errors
     "CommandError",
@@ -54,4 +57,5 @@ __all__ = [
     "CheckAnyFailure",
     "CommandOnCooldown",
     "CommandInvokeError",
+    "MaxConcurrencyReached",
 ]