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

disagreement/ext/commands/core.py

@@ -70,6 +70,10 @@ class Command:
         if hasattr(callback, "__command_checks__"):
             self.checks.extend(getattr(callback, "__command_checks__"))
 
+        self.max_concurrency: Optional[Tuple[int, str]] = None
+        if hasattr(callback, "__max_concurrency__"):
+            self.max_concurrency = getattr(callback, "__max_concurrency__")
+
     def add_check(
         self, predicate: Callable[["CommandContext"], Awaitable[bool] | bool]
     ) -> None:
@@ -215,6 +219,7 @@ class CommandHandler:
         ] = prefix
         self.commands: Dict[str, Command] = {}
         self.cogs: Dict[str, "Cog"] = {}
+        self._concurrency: Dict[str, Dict[str, int]] = {}
 
         from .help import HelpCommand
 
@@ -300,6 +305,47 @@ class CommandHandler:
             logger.info("Cog '%s' removed.", cog_name)
         return cog_to_remove
 
+    def _acquire_concurrency(self, ctx: CommandContext) -> None:
+        mc = getattr(ctx.command, "max_concurrency", None)
+        if not mc:
+            return
+        limit, scope = mc
+        if scope == "user":
+            key = ctx.author.id
+        elif scope == "guild":
+            key = ctx.message.guild_id or ctx.author.id
+        else:
+            key = "global"
+        buckets = self._concurrency.setdefault(ctx.command.name, {})
+        current = buckets.get(key, 0)
+        if current >= limit:
+            from .errors import MaxConcurrencyReached
+
+            raise MaxConcurrencyReached(limit)
+        buckets[key] = current + 1
+
+    def _release_concurrency(self, ctx: CommandContext) -> None:
+        mc = getattr(ctx.command, "max_concurrency", None)
+        if not mc:
+            return
+        _, scope = mc
+        if scope == "user":
+            key = ctx.author.id
+        elif scope == "guild":
+            key = ctx.message.guild_id or ctx.author.id
+        else:
+            key = "global"
+        buckets = self._concurrency.get(ctx.command.name)
+        if not buckets:
+            return
+        current = buckets.get(key, 0)
+        if current <= 1:
+            buckets.pop(key, None)
+        else:
+            buckets[key] = current - 1
+        if not buckets:
+            self._concurrency.pop(ctx.command.name, None)
+
     async def get_prefix(self, message: "Message") -> Union[str, List[str], None]:
         if callable(self.prefix):
             if inspect.iscoroutinefunction(self.prefix):
@@ -501,7 +547,11 @@ class CommandHandler:
             parsed_args, parsed_kwargs = await self._parse_arguments(command, ctx, view)
             ctx.args = parsed_args
             ctx.kwargs = parsed_kwargs
-            await command.invoke(ctx, *parsed_args, **parsed_kwargs)
+            self._acquire_concurrency(ctx)
+            try:
+                await command.invoke(ctx, *parsed_args, **parsed_kwargs)
+            finally:
+                self._release_concurrency(ctx)
         except CommandError as e:
             logger.error("Command error for '%s': %s", command.name, e)
             if hasattr(self.client, "on_command_error"):

disagreement/ext/commands/decorators.py

@@ -107,6 +107,33 @@ def check_any(
     return check(predicate)
 
 
+def max_concurrency(
+    number: int, per: str = "user"
+) -> Callable[[Callable[..., Awaitable[None]]], Callable[..., Awaitable[None]]]:
+    """Limit how many concurrent invocations of a command are allowed.
+
+    Parameters
+    ----------
+    number:
+        The maximum number of concurrent invocations.
+    per:
+        The scope of the limiter. Can be ``"user"``, ``"guild"`` or ``"global"``.
+    """
+
+    if number < 1:
+        raise ValueError("Concurrency number must be at least 1.")
+    if per not in {"user", "guild", "global"}:
+        raise ValueError("per must be 'user', 'guild', or 'global'.")
+
+    def decorator(
+        func: Callable[..., Awaitable[None]],
+    ) -> Callable[..., Awaitable[None]]:
+        setattr(func, "__max_concurrency__", (number, per))
+        return func
+
+    return decorator
+
+
 def cooldown(
     rate: int, per: float
 ) -> Callable[[Callable[..., Awaitable[None]]], Callable[..., Awaitable[None]]]:

disagreement/ext/commands/errors.py

@@ -72,5 +72,13 @@ class CommandInvokeError(CommandError):
         super().__init__(f"Error during command invocation: {original}")
 
 
+class MaxConcurrencyReached(CommandError):
+    """Raised when a command exceeds its concurrency limit."""
+
+    def __init__(self, limit: int):
+        self.limit = limit
+        super().__init__(f"Max concurrency of {limit} reached")
+
+
 # Add more specific errors as needed, e.g., UserNotFound, ChannelNotFound, etc.
 # These might inherit from BadArgument.

disagreement/gateway.py

@@ -344,6 +344,9 @@ class GatewayClient:
                 raw_event_d_payload if isinstance(raw_event_d_payload, dict) else {}
             )
             await self._dispatcher.dispatch(event_name, event_data_to_dispatch)
+            await self._dispatcher.dispatch(
+                "SHARD_RESUME", {"shard_id": self._shard_id}
+            )
         elif event_name:
             # For other events, ensure 'd' is a dict, or pass {} if 'd' is null/missing.
             # Models/parsers in EventDispatcher will need to handle potentially empty dicts.
@@ -508,6 +511,10 @@ class GatewayClient:
                 self._receive_task.cancel()
             self._receive_task = self._loop.create_task(self._receive_loop())
 
+            await self._dispatcher.dispatch(
+                "SHARD_CONNECT", {"shard_id": self._shard_id}
+            )
+
         except aiohttp.ClientConnectorError as e:
             raise GatewayException(
                 f"Failed to connect to Gateway (Connector Error): {e}"
@@ -559,6 +566,10 @@ class GatewayClient:
             self._last_sequence = None
             self._resume_gateway_url = None  # This might be re-fetched anyway
 
+        await self._dispatcher.dispatch(
+            "SHARD_DISCONNECT", {"shard_id": self._shard_id}
+        )
+
     @property
     def latency(self) -> Optional[float]:
         """Returns the latency between heartbeat and ACK in seconds."""

disagreement/http.py

@@ -23,7 +23,7 @@ from .interactions import InteractionResponsePayload
 
 if TYPE_CHECKING:
     from .client import Client
-    from .models import Message, Webhook, File
+    from .models import Message, Webhook, File, StageInstance, Invite
     from .interactions import ApplicationCommand, Snowflake
 
 # Discord API constants
@@ -40,12 +40,27 @@ class HTTPClient:
         token: str,
         client_session: Optional[aiohttp.ClientSession] = None,
         verbose: bool = False,
+        **session_kwargs: Any,
     ):
+        """Create a new HTTP client.
+
+        Parameters
+        ----------
+        token:
+            Bot token for authentication.
+        client_session:
+            Optional existing :class:`aiohttp.ClientSession`.
+        verbose:
+            If ``True``, log HTTP requests and responses.
+        **session_kwargs:
+            Additional options forwarded to :class:`aiohttp.ClientSession`, such
+            as ``proxy`` or ``connector``.
+        """
+
         self.token = token
-        self._session: Optional[aiohttp.ClientSession] = (
-            client_session  # Can be externally managed
-        )
-        self.user_agent = f"DiscordBot (https://github.com/yourusername/disagreement, {__version__})"  # Customize URL
+        self._session: Optional[aiohttp.ClientSession] = client_session
+        self._session_kwargs: Dict[str, Any] = session_kwargs
+        self.user_agent = f"DiscordBot (https://github.com/Slipstreamm/disagreement, {__version__})"  # Customize URL
 
         self.verbose = verbose
 
@@ -53,7 +68,7 @@ class HTTPClient:
 
     async def _ensure_session(self):
         if self._session is None or self._session.closed:
-            self._session = aiohttp.ClientSession()
+            self._session = aiohttp.ClientSession(**self._session_kwargs)
 
     async def close(self):
         """Closes the underlying aiohttp.ClientSession."""
@@ -409,6 +424,30 @@ class HTTPClient:
         """Fetches a channel by ID."""
         return await self.request("GET", f"/channels/{channel_id}")
 
+    async def get_channel_invites(
+        self, channel_id: "Snowflake"
+    ) -> List[Dict[str, Any]]:
+        """Fetches the invites for a channel."""
+
+        return await self.request("GET", f"/channels/{channel_id}/invites")
+
+    async def create_invite(
+        self, channel_id: "Snowflake", payload: Dict[str, Any]
+    ) -> "Invite":
+        """Creates an invite for a channel."""
+
+        data = await self.request(
+            "POST", f"/channels/{channel_id}/invites", payload=payload
+        )
+        from .models import Invite
+
+        return Invite.from_dict(data)
+
+    async def delete_invite(self, code: str) -> None:
+        """Deletes an invite by code."""
+
+        await self.request("DELETE", f"/invites/{code}")
+
     async def create_webhook(
         self, channel_id: "Snowflake", payload: Dict[str, Any]
     ) -> "Webhook":
@@ -589,6 +628,87 @@ class HTTPClient:
         """Fetches a guild object for a given guild ID."""
         return await self.request("GET", f"/guilds/{guild_id}")
 
+    async def get_guild_templates(self, guild_id: "Snowflake") -> List[Dict[str, Any]]:
+        """Fetches all templates for the given guild."""
+        return await self.request("GET", f"/guilds/{guild_id}/templates")
+
+    async def create_guild_template(
+        self, guild_id: "Snowflake", payload: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Creates a guild template."""
+        return await self.request(
+            "POST", f"/guilds/{guild_id}/templates", payload=payload
+        )
+
+    async def sync_guild_template(
+        self, guild_id: "Snowflake", template_code: str
+    ) -> Dict[str, Any]:
+        """Syncs a guild template to the guild's current state."""
+        return await self.request(
+            "PUT",
+            f"/guilds/{guild_id}/templates/{template_code}",
+        )
+
+    async def delete_guild_template(
+        self, guild_id: "Snowflake", template_code: str
+    ) -> None:
+        """Deletes a guild template."""
+        await self.request("DELETE", f"/guilds/{guild_id}/templates/{template_code}")
+
+    async def get_guild_scheduled_events(
+        self, guild_id: "Snowflake"
+    ) -> List[Dict[str, Any]]:
+        """Returns a list of scheduled events for the guild."""
+
+        return await self.request("GET", f"/guilds/{guild_id}/scheduled-events")
+
+    async def get_guild_scheduled_event(
+        self, guild_id: "Snowflake", event_id: "Snowflake"
+    ) -> Dict[str, Any]:
+        """Returns a guild scheduled event."""
+
+        return await self.request(
+            "GET", f"/guilds/{guild_id}/scheduled-events/{event_id}"
+        )
+
+    async def create_guild_scheduled_event(
+        self, guild_id: "Snowflake", payload: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Creates a guild scheduled event."""
+
+        return await self.request(
+            "POST", f"/guilds/{guild_id}/scheduled-events", payload=payload
+        )
+
+    async def edit_guild_scheduled_event(
+        self, guild_id: "Snowflake", event_id: "Snowflake", payload: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Edits a guild scheduled event."""
+
+        return await self.request(
+            "PATCH",
+            f"/guilds/{guild_id}/scheduled-events/{event_id}",
+            payload=payload,
+        )
+
+    async def delete_guild_scheduled_event(
+        self, guild_id: "Snowflake", event_id: "Snowflake"
+    ) -> None:
+        """Deletes a guild scheduled event."""
+
+        await self.request("DELETE", f"/guilds/{guild_id}/scheduled-events/{event_id}")
+
+    async def get_audit_logs(
+        self, guild_id: "Snowflake", **filters: Any
+    ) -> Dict[str, Any]:
+        """Fetches audit log entries for a guild."""
+        params = {k: v for k, v in filters.items() if v is not None}
+        return await self.request(
+            "GET",
+            f"/guilds/{guild_id}/audit-logs",
+            params=params if params else None,
+        )
+
     # Add other methods like:
     # async def get_guild(self, guild_id: str) -> Dict[str, Any]: ...
     # async def create_reaction(self, channel_id: str, message_id: str, emoji: str) -> None: ...
@@ -873,3 +993,49 @@ class HTTPClient:
     async def trigger_typing(self, channel_id: str) -> None:
         """Sends a typing indicator to the specified channel."""
         await self.request("POST", f"/channels/{channel_id}/typing")
+
+    async def start_stage_instance(
+        self, payload: Dict[str, Any], reason: Optional[str] = None
+    ) -> "StageInstance":
+        """Starts a stage instance."""
+
+        headers = {"X-Audit-Log-Reason": reason} if reason else None
+        data = await self.request(
+            "POST", "/stage-instances", payload=payload, custom_headers=headers
+        )
+        from .models import StageInstance
+
+        return StageInstance(data)
+
+    async def edit_stage_instance(
+        self,
+        channel_id: "Snowflake",
+        payload: Dict[str, Any],
+        reason: Optional[str] = None,
+    ) -> "StageInstance":
+        """Edits an existing stage instance."""
+
+        headers = {"X-Audit-Log-Reason": reason} if reason else None
+        data = await self.request(
+            "PATCH",
+            f"/stage-instances/{channel_id}",
+            payload=payload,
+            custom_headers=headers,
+        )
+        from .models import StageInstance
+
+        return StageInstance(data)
+
+    async def end_stage_instance(
+        self, channel_id: "Snowflake", reason: Optional[str] = None
+    ) -> None:
+        """Ends a stage instance."""
+
+        headers = {"X-Audit-Log-Reason": reason} if reason else None
+        await self.request(
+            "DELETE", f"/stage-instances/{channel_id}", custom_headers=headers
+        )
+
+    async def get_voice_regions(self) -> List[Dict[str, Any]]:
+        """Returns available voice regions."""
+        return await self.request("GET", "/voice/regions")

disagreement/models.py

@@ -6,6 +6,7 @@ Data models for Discord objects.
 
 import asyncio
 import json
+from dataclasses import dataclass
 from typing import Any, AsyncIterator, Dict, List, Optional, TYPE_CHECKING, Union
 
 import aiohttp  # pylint: disable=import-error
@@ -22,6 +23,9 @@ from .enums import (  # These enums will need to be defined in disagreement/enum
     ChannelType,
     ComponentType,
     ButtonStyle,  # Added for Button
+    GuildScheduledEventPrivacyLevel,
+    GuildScheduledEventStatus,
+    GuildScheduledEventEntityType,
     # SelectMenuType will be part of ComponentType or a new enum if needed
 )
 from .permissions import Permissions
@@ -1159,6 +1163,85 @@ class VoiceChannel(Channel):
         return f"<VoiceChannel id='{self.id}' name='{self.name}' guild_id='{self.guild_id}'>"
 
 
+class StageChannel(VoiceChannel):
+    """Represents a guild stage channel."""
+
+    def __repr__(self) -> str:
+        return f"<StageChannel id='{self.id}' name='{self.name}' guild_id='{self.guild_id}'>"
+
+    async def start_stage_instance(
+        self,
+        topic: str,
+        *,
+        privacy_level: int = 2,
+        reason: Optional[str] = None,
+        guild_scheduled_event_id: Optional[str] = None,
+    ) -> "StageInstance":
+        if not hasattr(self._client, "_http"):
+            raise DisagreementException("Client missing HTTP for stage instance")
+
+        payload: Dict[str, Any] = {
+            "channel_id": self.id,
+            "topic": topic,
+            "privacy_level": privacy_level,
+        }
+        if guild_scheduled_event_id is not None:
+            payload["guild_scheduled_event_id"] = guild_scheduled_event_id
+
+        instance = await self._client._http.start_stage_instance(payload, reason=reason)
+        instance._client = self._client
+        return instance
+
+    async def edit_stage_instance(
+        self,
+        *,
+        topic: Optional[str] = None,
+        privacy_level: Optional[int] = None,
+        reason: Optional[str] = None,
+    ) -> "StageInstance":
+        if not hasattr(self._client, "_http"):
+            raise DisagreementException("Client missing HTTP for stage instance")
+
+        payload: Dict[str, Any] = {}
+        if topic is not None:
+            payload["topic"] = topic
+        if privacy_level is not None:
+            payload["privacy_level"] = privacy_level
+
+        instance = await self._client._http.edit_stage_instance(
+            self.id, payload, reason=reason
+        )
+        instance._client = self._client
+        return instance
+
+    async def end_stage_instance(self, *, reason: Optional[str] = None) -> None:
+        if not hasattr(self._client, "_http"):
+            raise DisagreementException("Client missing HTTP for stage instance")
+
+        await self._client._http.end_stage_instance(self.id, reason=reason)
+
+
+class StageInstance:
+    """Represents a stage instance."""
+
+    def __init__(
+        self, data: Dict[str, Any], client_instance: Optional["Client"] = None
+    ) -> None:
+        self._client = client_instance
+        self.id: str = data["id"]
+        self.guild_id: Optional[str] = data.get("guild_id")
+        self.channel_id: str = data["channel_id"]
+        self.topic: str = data["topic"]
+        self.privacy_level: int = data.get("privacy_level", 2)
+        self.discoverable_disabled: bool = data.get("discoverable_disabled", False)
+        self.guild_scheduled_event_id: Optional[str] = data.get(
+            "guild_scheduled_event_id"
+        )
+
+    def __repr__(self) -> str:
+        return f"<StageInstance id='{self.id}' channel_id='{self.channel_id}'>"
+
+
 class CategoryChannel(Channel):
     """Represents a guild category channel."""
 
@@ -1433,6 +1516,33 @@ class Webhook:
         return self._client.parse_message(message_data)
 
 
+class GuildTemplate:
+    """Represents a guild template."""
+
+    def __init__(
+        self, data: Dict[str, Any], client_instance: Optional["Client"] = None
+    ):
+        self._client = client_instance
+        self.code: str = data["code"]
+        self.name: str = data["name"]
+        self.description: Optional[str] = data.get("description")
+        self.usage_count: int = data.get("usage_count", 0)
+        self.creator_id: str = data.get("creator_id", "")
+        self.creator: Optional[User] = (
+            User(data["creator"]) if data.get("creator") else None
+        )
+        self.created_at: Optional[str] = data.get("created_at")
+        self.updated_at: Optional[str] = data.get("updated_at")
+        self.source_guild_id: Optional[str] = data.get("source_guild_id")
+        self.serialized_source_guild: Dict[str, Any] = data.get(
+            "serialized_source_guild", {}
+        )
+        self.is_dirty: Optional[bool] = data.get("is_dirty")
+
+    def __repr__(self) -> str:
+        return f"<GuildTemplate code='{self.code}' name='{self.name}'>"
+
+
 # --- Message Components ---
 
 
@@ -1978,6 +2088,77 @@ class Reaction:
         return f"<Reaction message_id='{self.message_id}' user_id='{self.user_id}' emoji='{emoji_value}'>"
 
 
+class ScheduledEvent:
+    """Represents a guild scheduled event."""
+
+    def __init__(
+        self, data: Dict[str, Any], client_instance: Optional["Client"] = None
+    ):
+        self._client = client_instance
+        self.id: str = data["id"]
+        self.guild_id: str = data["guild_id"]
+        self.channel_id: Optional[str] = data.get("channel_id")
+        self.creator_id: Optional[str] = data.get("creator_id")
+        self.name: str = data["name"]
+        self.description: Optional[str] = data.get("description")
+        self.scheduled_start_time: str = data["scheduled_start_time"]
+        self.scheduled_end_time: Optional[str] = data.get("scheduled_end_time")
+        self.privacy_level: GuildScheduledEventPrivacyLevel = (
+            GuildScheduledEventPrivacyLevel(data["privacy_level"])
+        )
+        self.status: GuildScheduledEventStatus = GuildScheduledEventStatus(
+            data["status"]
+        )
+        self.entity_type: GuildScheduledEventEntityType = GuildScheduledEventEntityType(
+            data["entity_type"]
+        )
+        self.entity_id: Optional[str] = data.get("entity_id")
+        self.entity_metadata: Optional[Dict[str, Any]] = data.get("entity_metadata")
+        self.creator: Optional[User] = (
+            User(data["creator"]) if data.get("creator") else None
+        )
+        self.user_count: Optional[int] = data.get("user_count")
+        self.image: Optional[str] = data.get("image")
+
+    def __repr__(self) -> str:
+        return f"<ScheduledEvent id='{self.id}' name='{self.name}'>"
+
+
+@dataclass
+class Invite:
+    """Represents a Discord invite."""
+
+    code: str
+    channel_id: Optional[str]
+    guild_id: Optional[str]
+    inviter_id: Optional[str]
+    uses: Optional[int]
+    max_uses: Optional[int]
+    max_age: Optional[int]
+    temporary: Optional[bool]
+    created_at: Optional[str]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Invite":
+        channel = data.get("channel")
+        guild = data.get("guild")
+        inviter = data.get("inviter")
+        return cls(
+            code=data["code"],
+            channel_id=(channel or {}).get("id") if channel else data.get("channel_id"),
+            guild_id=(guild or {}).get("id") if guild else data.get("guild_id"),
+            inviter_id=(inviter or {}).get("id"),
+            uses=data.get("uses"),
+            max_uses=data.get("max_uses"),
+            max_age=data.get("max_age"),
+            temporary=data.get("temporary"),
+            created_at=data.get("created_at"),
+        )
+
+    def __repr__(self) -> str:
+        return f"<Invite code='{self.code}' guild_id='{self.guild_id}' channel_id='{self.channel_id}'>"
+
+
 class GuildMemberRemove:
     """Represents a GUILD_MEMBER_REMOVE event."""
 
@@ -2036,6 +2217,25 @@ class GuildRoleUpdate:
         return f"<GuildRoleUpdate guild_id='{self.guild_id}' role_id='{self.role.id}'>"
 
 
+class AuditLogEntry:
+    """Represents a single entry in a guild's audit log."""
+
+    def __init__(
+        self, data: Dict[str, Any], client_instance: Optional["Client"] = None
+    ) -> None:
+        self._client = client_instance
+        self.id: str = data["id"]
+        self.user_id: Optional[str] = data.get("user_id")
+        self.target_id: Optional[str] = data.get("target_id")
+        self.action_type: int = data["action_type"]
+        self.reason: Optional[str] = data.get("reason")
+        self.changes: List[Dict[str, Any]] = data.get("changes", [])
+        self.options: Optional[Dict[str, Any]] = data.get("options")
+
+    def __repr__(self) -> str:
+        return f"<AuditLogEntry id='{self.id}' action_type={self.action_type} user_id='{self.user_id}'>"
+
+
 def channel_factory(data: Dict[str, Any], client: "Client") -> Channel:
     """Create a channel object from raw API data."""
     channel_type = data.get("type")
@@ -2045,11 +2245,10 @@ def channel_factory(data: Dict[str, Any], client: "Client") -> Channel:
         ChannelType.GUILD_ANNOUNCEMENT.value,
     ):
         return TextChannel(data, client)
-    if channel_type in (
-        ChannelType.GUILD_VOICE.value,
-        ChannelType.GUILD_STAGE_VOICE.value,
-    ):
+    if channel_type == ChannelType.GUILD_VOICE.value:
         return VoiceChannel(data, client)
+    if channel_type == ChannelType.GUILD_STAGE_VOICE.value:
+        return StageChannel(data, client)
     if channel_type == ChannelType.GUILD_CATEGORY.value:
         return CategoryChannel(data, client)
     if channel_type in (

{disagreement-0.1.0rc3.dist-info → disagreement-0.2.0rc1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: disagreement
-Version: 0.1.0rc3
+Version: 0.2.0rc1
 Summary: A Python library for the Discord API.
 Author-email: Slipstream <me@slipstreamm.dev>
 License: BSD 3-Clause
@@ -119,6 +119,22 @@ setup_logging(logging.INFO)
 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`:
+
+```python
+client = disagreement.Client(
+    token=token,
+    http_options={"proxy": "http://localhost:8080"},
+)
+```
+
+These options are forwarded to ``HTTPClient`` when it creates the underlying
+``aiohttp.ClientSession``. You can specify a custom ``connector`` or any other
+session parameter supported by ``aiohttp``.
+
 ### Defining Subcommands with `AppCommandGroup`
 
 ```python