diff --git a/docs/doctrees/creatingacommand.doctree b/docs/doctrees/creatingacommand.doctree index bdc5f93c..0898c66f 100644 Binary files a/docs/doctrees/creatingacommand.doctree and b/docs/doctrees/creatingacommand.doctree differ diff --git a/docs/doctrees/environment.pickle b/docs/doctrees/environment.pickle index f695f38c..4e9f7c4f 100644 Binary files a/docs/doctrees/environment.pickle and b/docs/doctrees/environment.pickle differ diff --git a/docs/html/_sources/creatingacommand.rst.txt b/docs/html/_sources/creatingacommand.rst.txt index 341e2437..e617e69f 100644 --- a/docs/html/_sources/creatingacommand.rst.txt +++ b/docs/html/_sources/creatingacommand.rst.txt @@ -22,7 +22,6 @@ A Command code looks like this: :: # This code is run every time the command is called await data.reply("Pong!") - Creating a new Command ------------------------------------ @@ -33,7 +32,7 @@ Try to keep the name as short as possible, while staying specific enough so no o Next, create a new Python file with the ``name`` you have thought of. The previously mentioned "spaghetti" command should have a file called ``spaghetti.py``. -Then, in the first row of the file, import the :py:class:`Command` class from :py:mod:`royalnet`, and create a new class inheriting from it: :: +Then, in the first row of the file, import the :py:class:`Command` class from royalnet, and create a new class inheriting from it: :: from royalnet.commands import Command @@ -61,6 +60,36 @@ To send a message in the chat the command was called in, you can use the :py:met description = "Send a spaghetti emoji in the chat." async def run(self, args, data): - data.reply("๐Ÿ") + await data.reply("๐Ÿ") -And it's done! The command is now ready to be used in a bot! +And... it's done! The command is ready to be added to a bot! + +Coroutines and slow operations +------------------------------------ + +You may have noticed that in the previous example I wrote ``await data.reply("๐Ÿ")`` instead of just ``data.reply("๐Ÿ")``. + +This is because :py:meth:`CommandData.reply` isn't a simple method: it is a coroutine, a special kind of function that + can be executed separately from the rest of the code, allowing the bot to do other things in the meantime. + +By adding the ``await`` keyword before the ``data.reply("๐Ÿ")``, we tell the bot that it can do other things, like + receiving new messages, while the message is being sent. + +You should avoid running slow normal functions inside bot commands, as they will stop the bot from working until they + are finished and may cause bugs in other parts of the code! :: + + async def run(self, args, data): + # Don't do this! + image = download_1_terabyte_of_spaghetti("right_now", from="italy") + ... + +If the slow function you want does not cause any side effect, you can wrap it with the :ref:`royalnet.utils.asyncify` + function: :: + + async def run(self, args, data): + # If the called function has no side effect, you can do this! + image = await asyncify(download_1_terabyte_of_spaghetti, "right_now", from="italy") + ... + +Avoid using :py:func:`time.sleep` function, as it is considered a slow operation: use instead :py:func:`asyncio.sleep`, + a coroutine that does the same exact thing. diff --git a/docs/html/creatingacommand.html b/docs/html/creatingacommand.html index e8fbdd6c..d2dc83fb 100644 --- a/docs/html/creatingacommand.html +++ b/docs/html/creatingacommand.html @@ -84,6 +84,7 @@