diff --git a/docs/README.md b/docs/README.md index 89124d5e8..6e218f1c2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -34,7 +34,7 @@ The docs folder has a few moving components, here's a brief description of each: - `conf.py`: Configuration for Sphinx. This includes things such as the project name, version, plugins and their configuration. - `utils.py`: Helpful function used by `conf.py` to properly create the docs. -- `netliy_build.py`: Script which downloads the build output in netlify. Refer to [Static Netlify Build](#static-builds) +- `netlify_build.py`: Script which downloads the build output in netlify. Refer to [Static Netlify Build](#static-builds) ## Versions diff --git a/pydis_core/utils/checks.py b/pydis_core/utils/checks.py index 809e98de3..23dfe487a 100644 --- a/pydis_core/utils/checks.py +++ b/pydis_core/utils/checks.py @@ -46,17 +46,21 @@ def in_whitelist_check( fail_silently: bool = False, ) -> bool: """ - Check if a command was issued in a whitelisted context. + Check if a command was issued in a context that is whitelisted by channel, category, or roles. - The whitelists that can be provided are: + Args: + ctx (Context): The context in which the command is being invoked. + redirect (int | None): The channel ID to redirect the user to, if any. + channels (Container[int], optional): Whitelisted channel IDs. Defaults to (). + categories (Container[int], optional): Whitelisted category IDs. Defaults to (). + roles (Container[int], optional): Whitelisted role IDs. Defaults to (). + fail_silently (bool, optional): Whether to fail silently without raising an exception. Defaults to False. - - `channels`: a container with channel ids for whitelisted channels - - `categories`: a container with category ids for whitelisted categories - - `roles`: a container with with role ids for whitelisted roles + Returns: + bool: True if the command is used in a whitelisted context; False otherwise. - If the command was invoked in a context that was not whitelisted, the member is either - redirected to the `redirect` channel that was passed (default: #bot-commands) or simply - told that they're not allowed to use this particular command (if `None` was passed). + Raises: + InWhitelistCheckFailure: If the context is not whitelisted and `fail_silently` is False. """ if redirect not in channels: # It does not make sense for the channel whitelist to not contain the redirection @@ -92,12 +96,28 @@ def in_whitelist_check( return False -def cooldown_with_role_bypass(rate: int, per: float, type: BucketType = BucketType.default, *, - bypass_roles: Iterable[int]) -> Callable: +def cooldown_with_role_bypass( + rate: int, + per: float, + type: BucketType = BucketType.default, + *, + bypass_roles: Iterable[int]) -> Callable: """ - Applies a cooldown to a command, but allows members with certain roles to be ignored. + Decorate a command to have a cooldown, which can be bypassed by users with specified roles. - NOTE: this replaces the `Command.before_invoke` callback, which *might* introduce problems in the future. + Note: This replaces the `Command.before_invoke` callback, which *might* introduce problems in the future. + + Args: + rate (int): Number of times a command can be used before triggering a cooldown. + per (float): The duration (in seconds) for how long the cooldown lasts. + type: The type of cooldown (per user, per channel, per guild, etc.). + bypass_roles (Iterable[int]): An iterable of role IDs that bypass the cooldown. + + Returns: + Callable: A decorator that adds the described cooldown behavior to the command. + + Raises: + TypeError: If the decorator is not applied to an instance of `Command`. """ # Make it a set so lookup is hash based. bypass = set(bypass_roles) @@ -140,10 +160,16 @@ def wrapper(command: Command) -> Command: async def has_any_role_check(ctx: Context, *roles: str | int) -> bool: """ - Returns True if the context's author has any of the specified roles. + Verify if the context's author has any of the specified roles. + + This check will always fail if the context is a DM, since DMs don't have roles. - `roles` are the names or IDs of the roles for which to check. - False is always returns if the context is outside a guild. + Args: + ctx (Context): The context where the command is being invoked. + roles (Union[str, int], ...): A collection of role IDs. + + Returns: + bool: True if the context's author has at least one of the specified roles; False otherwise. """ if not ctx.guild: # Return False in a DM log.trace( @@ -166,10 +192,16 @@ async def has_any_role_check(ctx: Context, *roles: str | int) -> bool: async def has_no_roles_check(ctx: Context, *roles: str | int) -> bool: """ - Returns True if the context's author doesn't have any of the specified roles. + Verify if the context's author doesn't have any of the specified roles. + + This check will always fail if the context is a DM, since DMs don't have roles. + + Args: + ctx (Context): The context where the command is being invoked. + roles (Union[str, int], ...): A collection of role IDs. - `roles` are the names or IDs of the roles for which to check. - False is always returns if the context is outside a guild. + Returns: + bool: True if the context's author doesn't have any of the specified roles; False otherwise. """ if not ctx.guild: # Return False in a DM log.trace(