diff --git a/.github/labeler.yml b/.github/labeler.yml index 00924a702..f31fc49d5 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -73,7 +73,10 @@ - docs/cog_customcom.rst - docs/cog_guides/customcommands.rst "Category: Dev Cog": + # Source - redbot/core/dev_commands.py + # Docs + - docs/cog_guides/dev.rst "Category: Docs": - docs/**/* "Category: Downloader": diff --git a/docs/cog_guides/dev.rst b/docs/cog_guides/dev.rst new file mode 100644 index 000000000..6b5cc3164 --- /dev/null +++ b/docs/cog_guides/dev.rst @@ -0,0 +1,254 @@ +.. _dev: + +=== +Dev +=== + +This is the cog guide for the dev cog. You will +find detailed docs about usage and commands. + +``[p]`` is considered as your prefix. + +.. note:: To use this cog, load it by typing this:: + + [p]load dev + +.. _dev-usage: + +----- +Usage +----- + +Various development focused utilities. All commands in this cog are +restricted to the bot owners. + +.. note:: + + Unlike other cogs, the Dev cog is only loaded if the bot is + started with the ``--dev`` flag. + + .. warning:: + + It is not suggested that you run Dev in production. Many + of these cog's commands may cause down-the-line complications if + not used appropriately. + +.. _dev-commands: + +-------- +Commands +-------- + +.. _dev-command-bypasscooldowns: + +^^^^^^^^^^^^^^^ +bypasscooldowns +^^^^^^^^^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]bypasscooldowns [toggle] + +**Description** + +Give bot owners the ability to bypass cooldowns. Note that this bypass +does not persist through restarts/shutdowns. + +**Arguments** + +* ``[toggle]``: |bool-input| Otherwise, defaults to the inverse of the current setting. + +.. _dev-command-debug: + +^^^^^ +debug +^^^^^ + +**Syntax** + +.. code-block:: none + + [p]debug + +**Description** + +Evaluate a statement of python code. + +The bot will always respond with the return value of the code. +If the return value of the code is a coroutine, it will be awaited, +and the result of that will be the bot's response. + +Note: Only one statement may be evaluated. Using certain restricted +keywords, e.g. yield, will result in a syntax error. For multiple +lines or asynchronous code, see [p]repl or [p]eval. + +**Environment Variables** + +* ``ctx``: Command invocation context +* ``bot``: The bot object +* ``channel``: The current channel object +* ``author``: The current author's member object +* ``guild``: The current guild object +* ``message``: The command's message object +* ``aiohttp``: The aiohttp library +* ``asyncio``: The asyncio library +* ``discord``: The discord.py library +* ``commands``: The redbot.core.commands module +* ``cf``: The redbot.core.utils.chat_formatting module +* ``_``: The result from the last dev command + +**Arguments** + +* ````: The statement to run. + +.. _dev-command-eval: + +^^^^ +eval +^^^^ + +**Syntax** + +.. code-block:: none + + [p]eval + +**Description** + +Execute asynchronous code. + +This command wraps code into the body of an async function and then +calls and awaits it. The bot will respond with anything printed to +stdout, as well as the return value of the function. + +The code can be within a codeblock, inline code or neither, as long +as they are not mixed and they are formatted correctly. + +**Environment Variables** + +* ``ctx``: Command invocation context +* ``bot``: The bot object +* ``channel``: The current channel object +* ``author``: The current author's member object +* ``guild``: The current guild object +* ``message``: The command's message object +* ``aiohttp``: The aiohttp library +* ``asyncio``: The asyncio library +* ``discord``: The discord.py library +* ``commands``: The redbot.core.commands module +* ``cf``: The redbot.core.utils.chat_formatting module +* ``_``: The result from the last dev command + +**Arguments** + +* ````: The code to evaluate. + +.. _dev-command-mock: + +^^^^ +mock +^^^^ + +**Syntax** + +.. code-block:: none + + [p]mock + +**Description** + +Mock another user invoking a command. The prefix must not be entered. + +**Arguments** + +* ````: The user to mock. |user-input-quotes| +* ````: The command to invoke. + +.. _dev-command-mockmsg: + +^^^^^^^ +mockmsg +^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]mockmsg + +**Description** + +Dispatch a message event as if it were sent by a different user. + +Current message is used as a base (including attachments, embeds, etc.), +the content and author of the message are replaced with the given arguments. + +**Arguments** + +* ````: The member to mock. |user-input-quotes| +* ````: The content used for the message. + +.. note:: + + If ``content`` isn't passed, the message needs to contain embeds, attachments, + or anything else that makes the message non-empty. + +.. _dev-command-repl: + +^^^^ +repl +^^^^ + +**Syntax** + +.. code-block:: none + + [p]repl + +**Description** + +Open an interactive REPL. + +The REPL will only recognise code as messages which start with a +backtick. This includes codeblocks, and as such multiple lines can be +evaluated. + +Use ``exit()`` or ``quit`` to exit the REPL session, prefixed with +a backtick so they may be interpreted. + +**Environment Variables** + +* ``ctx``: Command invocation context +* ``bot``: The bot object +* ``channel``: The current channel object +* ``author``: The current author's member object +* ``guild``: The current guild object +* ``message``: The command's message object +* ``aiohttp``: The aiohttp library +* ``asyncio``: The asyncio library +* ``discord``: The discord.py library +* ``commands``: The redbot.core.commands module +* ``cf``: The redbot.core.utils.chat_formatting module +* ``_``: The result from the last dev command + +.. _dev-command-repl-pause: + +"""""""""" +repl pause +"""""""""" + +**Syntax** + +.. code-block:: none + + [p]repl pause [toggle] + +**Description** + +Pauses/resumes the REPL running in the current channel. + +**Arguments** + +* ``[toggle]``: |bool-input| Otherwise, defaults to the inverse of the current setting. diff --git a/docs/index.rst b/docs/index.rst index 4cb337b0a..eebef1d5b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,6 +39,7 @@ Welcome to Red - Discord Bot's documentation! cog_guides/cog_manager_ui cog_guides/core cog_guides/customcommands + cog_guides/dev cog_guides/downloader cog_guides/economy cog_guides/filter diff --git a/redbot/core/dev_commands.py b/redbot/core/dev_commands.py index b5c5a7033..27db6af4e 100644 --- a/redbot/core/dev_commands.py +++ b/redbot/core/dev_commands.py @@ -27,6 +27,7 @@ import discord from . import checks, commands from .commands import NoParseOptional as Optional from .i18n import Translator, cog_i18n +from .utils import chat_formatting from .utils.chat_formatting import pagify from .utils.predicates import MessagePredicate @@ -110,6 +111,7 @@ class Dev(commands.Cog): "aiohttp": aiohttp, "discord": discord, "commands": commands, + "cf": chat_formatting, "_": self._last_result, "__name__": "__main__", } @@ -135,14 +137,18 @@ class Dev(commands.Cog): lines or asynchronous code, see [p]repl or [p]eval. Environment Variables: - ctx - command invocation context - bot - bot object - channel - the current channel object - author - command author's member object - message - the command's message object - discord - discord.py library - commands - redbot.core.commands - _ - The result of the last dev command. + `ctx` - the command invocation context + `bot` - the bot object + `channel` - the current channel object + `author` - the command author's member object + `guild` - the current guild object + `message` - the command's message object + `_` - the result of the last dev command + `aiohttp` - the aiohttp library + `asyncio` - the asyncio library + `discord` - the discord.py library + `commands` - the redbot.core.commands module + `cf` - the redbot.core.utils.chat_formatting module """ env = self.get_environment(ctx) code = self.cleanup_code(code) @@ -178,14 +184,18 @@ class Dev(commands.Cog): as they are not mixed and they are formatted correctly. Environment Variables: - ctx - command invocation context - bot - bot object - channel - the current channel object - author - command author's member object - message - the command's message object - discord - discord.py library - commands - redbot.core.commands - _ - The result of the last dev command. + `ctx` - the command invocation context + `bot` - the bot object + `channel` - the current channel object + `author` - the command author's member object + `guild` - the current guild object + `message` - the command's message object + `_` - the result of the last dev command + `aiohttp` - the aiohttp library + `asyncio` - the asyncio library + `discord` - the discord.py library + `commands` - the redbot.core.commands module + `cf` - the redbot.core.utils.chat_formatting module """ env = self.get_environment(ctx) body = self.cleanup_code(body) @@ -227,6 +237,23 @@ class Dev(commands.Cog): The REPL will only recognise code as messages which start with a backtick. This includes codeblocks, and as such multiple lines can be evaluated. + + Use `exit()` or `quit` to exit the REPL session, prefixed with + a backtick so they may be interpreted. + + Environment Variables: + `ctx` - the command invocation context + `bot` - the bot object + `channel` - the current channel object + `author` - the command author's member object + `guild` - the current guild object + `message` - the command's message object + `_` - the result of the last dev command + `aiohttp` - the aiohttp library + `asyncio` - the asyncio library + `discord` - the discord.py library + `commands` - the redbot.core.commands module + `cf` - the redbot.core.utils.chat_formatting module """ if ctx.channel.id in self.sessions: if self.sessions[ctx.channel.id]: @@ -318,7 +345,7 @@ class Dev(commands.Cog): @repl.command(aliases=["resume"]) async def pause(self, ctx, toggle: Optional[bool] = None): - """Pauses/resumes the REPL running in the current channel""" + """Pauses/resumes the REPL running in the current channel.""" if ctx.channel.id not in self.sessions: await ctx.send(_("There is no currently running REPL session in this channel.")) return @@ -334,7 +361,7 @@ class Dev(commands.Cog): @commands.command() @checks.is_owner() - async def mock(self, ctx, user: discord.Member, *, command): + async def mock(self, ctx, user: discord.User, *, command): """Mock another user invoking a command. The prefix must not be entered. @@ -347,7 +374,7 @@ class Dev(commands.Cog): @commands.command(name="mockmsg") @checks.is_owner() - async def mock_msg(self, ctx, user: discord.Member, *, content: str = ""): + async def mock_msg(self, ctx, user: discord.User, *, content: str = ""): """Dispatch a message event as if it were sent by a different user. Current message is used as a base (including attachments, embeds, etc.),