ryg/royalnet
ryg/royalnet
1
Fork 0
mirror of https://github.com/RYGhub/royalnet.git synced 2024-11-23 19:44:20 +00:00
Code Activity

Update docs

Browse source
This commit is contained in:
Steffo 2019-08-29 22:13:53 +02:00
parent 76000491db
commit addff10e63
7 changed files with 100 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
docs/doctrees/creatingacommand.doctree
View file

Binary file not shown.

BIN
docs/doctrees/environment.pickle
View file

Binary file not shown.

37
docs/html/_sources/creatingacommand.rst.txt
View file

@ -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.

35
docs/html/creatingacommand.html
View file

@ -84,6 +84,7 @@
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Royalnet Commands</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#creating-a-new-command">Creating a new Command</a></li>
<li class="toctree-l2"><a class="reference internal" href="#coroutines-and-slow-operations">Coroutines and slow operations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="apireference.html">API Reference</a></li>
@ -178,7 +179,7 @@ It’s the name your command will be called with: for example, the “spaghetti
Try to keep the name as short as possible, while staying specific enough so no other command will have the same name.</p>
<p>Next, create a new Python file with the <code class="docutils literal notranslate"><span class="pre">name</span></code> you have thought of.
The previously mentioned “spaghetti” command should have a file called <code class="docutils literal notranslate"><span class="pre">spaghetti.py</span></code>.</p>
<p>Then, in the first row of the file, import the <a class="reference internal" href="apireference.html#royalnet.commands.Command" title="royalnet.commands.Command"><code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code></a> class from <code class="xref py py-mod docutils literal notranslate"><span class="pre">royalnet</span></code>, and create a new class inheriting from it:</p>
<p>Then, in the first row of the file, import the <a class="reference internal" href="apireference.html#royalnet.commands.Command" title="royalnet.commands.Command"><code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code></a> class from royalnet, and create a new class inheriting from it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">royalnet.commands</span> <span class="k">import</span> <span class="n">Command</span>
<span class="k">class</span> <span class="nc">SpaghettiCommand</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
@ -204,10 +205,38 @@ The previously mentioned “spaghetti” command should have a file called <code
<span class="n">description</span> <span class="o">=</span> <span class="s2">&quot;Send a spaghetti emoji in the chat.&quot;</span>
<span class="k">async</span> <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
<span class="n">data</span><span class="o">.</span><span class="n">reply</span><span class="p">(</span><span class="s2">&quot;🍝&quot;</span><span class="p">)</span>
<span class="k">await</span> <span class="n">data</span><span class="o">.</span><span class="n">reply</span><span class="p">(</span><span class="s2">&quot;🍝&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>And it’s done! The command is now ready to be used in a bot!</p>
<p>And… it’s done! The command is ready to be added to a bot!</p>
</div>
<div class="section" id="coroutines-and-slow-operations">
<h2>Coroutines and slow operations<a class="headerlink" href="#coroutines-and-slow-operations" title="Permalink to this headline"></a></h2>
<p>You may have noticed that in the previous example I wrote <code class="docutils literal notranslate"><span class="pre">await</span> <span class="pre">data.reply(&quot;🍝&quot;)</span></code> instead of just <code class="docutils literal notranslate"><span class="pre">data.reply(&quot;🍝&quot;)</span></code>.</p>
<dl>
<dt>This is because <a class="reference internal" href="apireference.html#royalnet.commands.CommandData.reply" title="royalnet.commands.CommandData.reply"><code class="xref py py-meth docutils literal notranslate"><span class="pre">CommandData.reply()</span></code></a> isn’t a simple method: it is a coroutine, a special kind of function that</dt><dd><p>can be executed separately from the rest of the code, allowing the bot to do other things in the meantime.</p>
</dd>
<dt>By adding the <code class="docutils literal notranslate"><span class="pre">await</span></code> keyword before the <code class="docutils literal notranslate"><span class="pre">data.reply(&quot;🍝&quot;)</span></code>, we tell the bot that it can do other things, like</dt><dd><p>receiving new messages, while the message is being sent.</p>
</dd>
<dt>You should avoid running slow normal functions inside bot commands, as they will stop the bot from working until they</dt><dd><p>are finished and may cause bugs in other parts of the code!</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
<span class="c1"># Don&#39;t do this!</span>
<span class="n">image</span> <span class="o">=</span> <span class="n">download_1_terabyte_of_spaghetti</span><span class="p">(</span><span class="s2">&quot;right_now&quot;</span><span class="p">,</span> <span class="n">from</span><span class="o">=</span><span class="s2">&quot;italy&quot;</span><span class="p">)</span>
<span class="o">...</span>
</pre></div>
</div>
</dd>
<dt>If the slow function you want does not cause any side effect, you can wrap it with the <span class="xref std std-ref">royalnet.utils.asyncify</span></dt><dd><p>function:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
<span class="c1"># If the called function has no side effect, you can do this!</span>
<span class="n">image</span> <span class="o">=</span> <span class="k">await</span> <span class="n">asyncify</span><span class="p">(</span><span class="n">download_1_terabyte_of_spaghetti</span><span class="p">,</span> <span class="s2">&quot;right_now&quot;</span><span class="p">,</span> <span class="n">from</span><span class="o">=</span><span class="s2">&quot;italy&quot;</span><span class="p">)</span>
<span class="o">...</span>
</pre></div>
</div>
</dd>
<dt>Avoid using <a class="reference external" href="https://docs.python.org/3.7/library/time.html#time.sleep" title="(in Python v3.7)"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.sleep()</span></code></a> function, as it is considered a slow operation: use instead <a class="reference external" href="https://docs.python.org/3.7/library/asyncio-task.html#asyncio.sleep" title="(in Python v3.7)"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.sleep()</span></code></a>,</dt><dd><p>a coroutine that does the same exact thing.</p>
</dd>
</dl>
</div>
</div>

1
docs/html/index.html
View file

@ -154,6 +154,7 @@
<ul>
<li class="toctree-l1"><a class="reference internal" href="creatingacommand.html">Royalnet Commands</a><ul>
<li class="toctree-l2"><a class="reference internal" href="creatingacommand.html#creating-a-new-command">Creating a new Command</a></li>
<li class="toctree-l2"><a class="reference internal" href="creatingacommand.html#coroutines-and-slow-operations">Coroutines and slow operations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="apireference.html">API Reference</a><ul>

2
docs/html/searchindex.js
View file

File diff suppressed because one or more lines are too long

37
docs_source/creatingacommand.rst
View file

@ -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.