Source code for redbot.core.commands.context

from __future__ import annotations

import asyncio
import contextlib
import os
import re
from typing import Iterable, List, Union, Optional, TYPE_CHECKING
import discord
from discord.ext.commands import Context as DPYContext

from .requires import PermState
from ..utils.chat_formatting import box
from ..utils.predicates import MessagePredicate
from ..utils import common_filters

if TYPE_CHECKING:
    from .commands import Command
    from ..bot import Red

TICK = "\N{WHITE HEAVY CHECK MARK}"

__all__ = ["Context", "GuildContext", "DMContext"]


[docs]class Context(DPYContext): """Command invocation context for Red. All context passed into commands will be of this type. This class inherits from `discord.ext.commands.Context`. Attributes ---------- assume_yes: bool Whether or not interactive checks should be skipped and assumed to be confirmed. This is intended for allowing automation of tasks. An example of this would be scheduled commands not requiring interaction if the cog developer checks this value prior to confirming something interactively. Depending on the potential impact of a command, it may still be appropriate not to use this setting. permission_state: PermState The permission state the current context is in. """ command: "Command" invoked_subcommand: "Optional[Command]" bot: "Red" def __init__(self, **attrs): self.assume_yes = attrs.pop("assume_yes", False) super().__init__(**attrs) self.permission_state: PermState = PermState.NORMAL
[docs] async def send(self, content=None, **kwargs): """Sends a message to the destination with the content given. This acts the same as `discord.ext.commands.Context.send`, with one added keyword argument as detailed below in *Other Parameters*. Parameters ---------- content : str The content of the message to send. Other Parameters ---------------- filter : Callable[`str`] -> `str` A function which is used to sanitize the ``content`` before it is sent. Defaults to :func:`~redbot.core.utils.common_filters.filter_mass_mentions`. This must take a single `str` as an argument, and return the sanitized `str`. **kwargs See `discord.ext.commands.Context.send`. Returns ------- discord.Message The message that was sent. """ _filter = kwargs.pop("filter", common_filters.filter_mass_mentions) if _filter and content: content = _filter(str(content)) return await super().send(content=content, **kwargs)
[docs] async def send_help(self, command=None): """ Send the command help message. """ # This allows people to manually use this similarly # to the upstream d.py version, while retaining our use. command = command or self.command await self.bot.send_help_for(self, command)
[docs] async def tick(self) -> bool: """Add a tick reaction to the command message. Returns ------- bool :code:`True` if adding the reaction succeeded. """ try: await self.message.add_reaction(TICK) except discord.HTTPException: return False else: return True
[docs] async def react_quietly( self, reaction: Union[discord.Emoji, discord.Reaction, discord.PartialEmoji, str] ) -> bool: """Adds a reaction to to the command message. Returns ------- bool :code:`True` if adding the reaction succeeded. """ try: await self.message.add_reaction(reaction) except discord.HTTPException: return False else: return True
[docs] async def send_interactive( self, messages: Iterable[str], box_lang: str = None, timeout: int = 15 ) -> List[discord.Message]: """Send multiple messages interactively. The user will be prompted for whether or not they would like to view the next message, one at a time. They will also be notified of how many messages are remaining on each prompt. Parameters ---------- messages : `iterable` of `str` The messages to send. box_lang : str If specified, each message will be contained within a codeblock of this language. timeout : int How long the user has to respond to the prompt before it times out. After timing out, the bot deletes its prompt message. """ messages = tuple(messages) ret = [] for idx, page in enumerate(messages, 1): if box_lang is None: msg = await self.send(page) else: msg = await self.send(box(page, lang=box_lang)) ret.append(msg) n_remaining = len(messages) - idx if n_remaining > 0: if n_remaining == 1: plural = "" is_are = "is" else: plural = "s" is_are = "are" query = await self.send( "There {} still {} message{} remaining. " "Type `more` to continue." "".format(is_are, n_remaining, plural) ) try: resp = await self.bot.wait_for( "message", check=MessagePredicate.lower_equal_to("more", self), timeout=timeout, ) except asyncio.TimeoutError: with contextlib.suppress(discord.HTTPException): await query.delete() break else: try: await self.channel.delete_messages((query, resp)) except (discord.HTTPException, AttributeError): # In case the bot can't delete other users' messages, # or is not a bot account # or channel is a DM with contextlib.suppress(discord.HTTPException): await query.delete() return ret
[docs] async def embed_colour(self): """ Helper function to get the colour for an embed. Returns ------- discord.Colour: The colour to be used """ return await self.bot.get_embed_color(self)
@property def embed_color(self): # Rather than double awaiting. return self.embed_colour
[docs] async def embed_requested(self): """ Simple helper to call bot.embed_requested with logic around if embed permissions are available Returns ------- bool: :code:`True` if an embed is requested """ if self.guild and not self.channel.permissions_for(self.guild.me).embed_links: return False return await self.bot.embed_requested(self.channel, self.author, command=self.command)
[docs] async def maybe_send_embed(self, message: str) -> discord.Message: """ Simple helper to send a simple message to context without manually checking ctx.embed_requested This should only be used for simple messages. Parameters ---------- message: `str` The string to send Returns ------- discord.Message: the message which was sent Raises ------ discord.Forbidden see `discord.abc.Messageable.send` discord.HTTPException see `discord.abc.Messageable.send` """ if await self.embed_requested(): return await self.send( embed=discord.Embed(description=message, color=(await self.embed_colour())) ) else: return await self.send(message)
@property def clean_prefix(self) -> str: """str: The command prefix, but a mention prefix is displayed nicer.""" me = self.me pattern = re.compile(rf"<@!?{me.id}>") return pattern.sub(f"@{me.display_name}", self.prefix) @property def me(self) -> Union[discord.ClientUser, discord.Member]: """discord.abc.User: The bot member or user object. If the context is DM, this will be a `discord.User` object. """ if self.guild is not None: return self.guild.me else: return self.bot.user
if TYPE_CHECKING or os.getenv("BUILDING_DOCS", False):
[docs] class DMContext(Context): """ At runtime, this will still be a normal context object. This lies about some type narrowing for type analysis in commands using a dm_only decorator. It is only correct to use when those types are already narrowed """ @property def author(self) -> discord.User: ... @property def channel(self) -> discord.DMChannel: ... @property def guild(self) -> None: ... @property def me(self) -> discord.ClientUser: ...
[docs] class GuildContext(Context): """ At runtime, this will still be a normal context object. This lies about some type narrowing for type analysis in commands using a guild_only decorator. It is only correct to use when those types are already narrowed """ @property def author(self) -> discord.Member: ... @property def channel(self) -> discord.TextChannel: ... @property def guild(self) -> discord.Guild: ... @property def me(self) -> discord.Member: ...
else: GuildContext = Context DMContext = Context