Skip to content

Commit

Permalink
Deployed 0a4b8d5 to master with MkDocs 1.6.1 and mike 2.1.3
Browse files Browse the repository at this point in the history
  • Loading branch information
@github-actions
github-actions[bot] committed Nov 21, 2024
1 parent 5fb1b8a commit 0b83879
Show file tree
Hide file tree
Showing 4 changed files with 198 additions and 26 deletions.
Binary file modified master/objects.inv
View file
Binary file not shown.
33 changes: 33 additions & 0 deletions master/reference/attachment/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4044,6 +4044,39 @@ <h3 id="niobot.attachment.detect_mime_type" class="doc doc-heading">
</tbody>
</table>


<p><span class="doc-section-title">Raises:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code>RuntimeError</code>
</td>
<td>
<div class="doc-md-description">
<p>If the <code>magic</code> library is not installed.</p>
</div>
</td>
</tr>
<tr class="doc-section-item">
<td>
<code>TypeError</code>
</td>
<td>
<div class="doc-md-description">
<p>If the file is not a string, BytesIO, or Path object.</p>
</div>
</td>
</tr>
</tbody>
</table>

</div>

</div>
Expand Down
189 changes: 164 additions & 25 deletions master/reference/commands/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -618,15 +618,34 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>

<li class="md-nav__item">
<a href="#niobot.commands" class="md-nav__link">
<a href="#command-argument-detection" class="md-nav__link">
<span class="md-ellipsis">
commands
Command argument detection
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#reference" class="md-nav__link">
<span class="md-ellipsis">
Reference
</span>
</a>

<nav class="md-nav" aria-label="Reference">
<ul class="md-nav__list">

<li class="md-nav__item">
<a href="#niobot.commands" class="md-nav__link">
<span class="md-ellipsis">
commands
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#niobot.commands.Argument" class="md-nav__link">
<span class="md-ellipsis">
Argument
Expand All @@ -649,8 +668,8 @@
</nav>

</li>

<li class="md-nav__item">
<li class="md-nav__item">
<a href="#niobot.commands.Command" class="md-nav__link">
<span class="md-ellipsis">
Command
Expand Down Expand Up @@ -694,6 +713,15 @@
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#niobot.commands.Command.parse_args" class="md-nav__link">
<span class="md-ellipsis">
parse_args
</span>
</a>

</li>

<li class="md-nav__item">
Expand All @@ -718,8 +746,8 @@
</nav>

</li>

<li class="md-nav__item">
<li class="md-nav__item">
<a href="#niobot.commands.Module" class="md-nav__link">
<span class="md-ellipsis">
Module
Expand Down Expand Up @@ -760,32 +788,37 @@
</nav>

</li>

<li class="md-nav__item">
<li class="md-nav__item">
<a href="#niobot.commands.command" class="md-nav__link">
<span class="md-ellipsis">
command
</span>
</a>

</li>

<li class="md-nav__item">
<li class="md-nav__item">
<a href="#niobot.commands.check" class="md-nav__link">
<span class="md-ellipsis">
check
</span>
</a>

</li>

<li class="md-nav__item">
<li class="md-nav__item">
<a href="#niobot.commands.event" class="md-nav__link">
<span class="md-ellipsis">
event
</span>
</a>

</li>

</ul>
</nav>

</li>

</ul>
Expand Down Expand Up @@ -1105,15 +1138,34 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>

<li class="md-nav__item">
<a href="#niobot.commands" class="md-nav__link">
<a href="#command-argument-detection" class="md-nav__link">
<span class="md-ellipsis">
commands
Command argument detection
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#reference" class="md-nav__link">
<span class="md-ellipsis">
Reference
</span>
</a>

<nav class="md-nav" aria-label="Reference">
<ul class="md-nav__list">

<li class="md-nav__item">
<a href="#niobot.commands" class="md-nav__link">
<span class="md-ellipsis">
commands
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#niobot.commands.Argument" class="md-nav__link">
<span class="md-ellipsis">
Argument
Expand All @@ -1136,8 +1188,8 @@
</nav>

</li>

<li class="md-nav__item">
<li class="md-nav__item">
<a href="#niobot.commands.Command" class="md-nav__link">
<span class="md-ellipsis">
Command
Expand Down Expand Up @@ -1181,6 +1233,15 @@
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#niobot.commands.Command.parse_args" class="md-nav__link">
<span class="md-ellipsis">
parse_args
</span>
</a>

</li>

<li class="md-nav__item">
Expand All @@ -1205,8 +1266,8 @@
</nav>

</li>

<li class="md-nav__item">
<li class="md-nav__item">
<a href="#niobot.commands.Module" class="md-nav__link">
<span class="md-ellipsis">
Module
Expand Down Expand Up @@ -1247,32 +1308,37 @@
</nav>

</li>

<li class="md-nav__item">
<li class="md-nav__item">
<a href="#niobot.commands.command" class="md-nav__link">
<span class="md-ellipsis">
command
</span>
</a>

</li>

<li class="md-nav__item">
<li class="md-nav__item">
<a href="#niobot.commands.check" class="md-nav__link">
<span class="md-ellipsis">
check
</span>
</a>

</li>

<li class="md-nav__item">
<li class="md-nav__item">
<a href="#niobot.commands.event" class="md-nav__link">
<span class="md-ellipsis">
event
</span>
</a>

</li>

</ul>
</nav>

</li>

</ul>
Expand Down Expand Up @@ -1300,6 +1366,54 @@

<h1 id="commands">Commands<a class="headerlink" href="#commands" title="Permanent link">&para;</a></h1>
<p>Using commands and events is the main way to interact with the bot.</p>
<h2 id="command-argument-detection">Command argument detection<a class="headerlink" href="#command-argument-detection" title="Permanent link">&para;</a></h2>
<p>One of the most powerful features of NioBot is the command argument interpretation system.
When you create a niobot command, the arguments are automatically detected, and their desired
type is inferred from the type hints in the function signature.</p>
<p>This means that <code>foo: str</code> will always give you a string, <code>bar: int</code> will try to give you an integer,
or throw an error if it cannot convert the user-given argument.</p>
<p>As of v1.2.0, you can take advantage of the keyword-only and positional args in Python.
Normally, when you specify a function like <code>async def mycommand(ctx, x: str)</code>, niobot will see
that you want an argument, x, and will do just that. It will take the user's input, and give you
the value for x. However, if the user specifies multiple words for <code>x</code>, it will only give the first one
to the function, unless the user warps the argument in "quotes".</p>
<p><div class="language-python highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">import</span> <span class="nn">niobot</span>
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="n">bot</span> <span class="o">=</span> <span class="n">niobot</span><span class="o">.</span><span class="n">NioBot</span><span class="p">()</span>
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="nd">@bot</span><span class="o">.</span><span class="n">command</span><span class="p">()</span>
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="k">async</span> <span class="k">def</span> <span class="nf">mycommand</span><span class="p">(</span><span class="n">ctx</span><span class="p">,</span> <span class="n">x</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
</span><span id="__span-0-6"><a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a> <span class="k">await</span> <span class="n">ctx</span><span class="o">.</span><span class="n">respond</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Your argument was: </span><span class="si">{</span><span class="n">x</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
</span></code></pre></div>
If you ran <code>!mycommand hello world</code>, the bot would respond with <code>Your argument was: hello</code>.</p>
<p>With keyword-only arguments, you can make use of "greedy" arguments.
While you could previously do this by <em>manually</em> constructing the <a class="autorefs autorefs-internal" href="#niobot.commands.Argument">niobot.Argument</a> type,
you can now do this with the <code>*</code> syntax in Python.</p>
<p><div class="language-python highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="kn">import</span> <span class="nn">niobot</span>
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="n">bot</span> <span class="o">=</span> <span class="n">niobot</span><span class="o">.</span><span class="n">NioBot</span><span class="p">()</span>
</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>
</span><span id="__span-1-4"><a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a><span class="nd">@bot</span><span class="o">.</span><span class="n">command</span><span class="p">()</span>
</span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a><span class="k">async</span> <span class="k">def</span> <span class="nf">mycommand</span><span class="p">(</span><span class="n">ctx</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">x</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a> <span class="k">await</span> <span class="n">ctx</span><span class="o">.</span><span class="n">respond</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Your argument was: </span><span class="si">{</span><span class="n">x</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
</span></code></pre></div>
If you ran <code>!mycommand hello world</code>, the bot would respond with <code>Your argument was: hello world</code>.</p>
<p>And, as for positional args, if you want to fetch a set of arguments, you can do so by specifying
<code>*args</code>. This will give you a tuple containing every whitespace-delimited argument after the command.</p>
<p><div class="language-python highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="kn">import</span> <span class="nn">niobot</span>
</span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="n">bot</span> <span class="o">=</span> <span class="n">niobot</span><span class="o">.</span><span class="n">NioBot</span><span class="p">()</span>
</span><span id="__span-2-3"><a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a>
</span><span id="__span-2-4"><a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="nd">@bot</span><span class="o">.</span><span class="n">command</span><span class="p">()</span>
</span><span id="__span-2-5"><a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a><span class="k">async</span> <span class="k">def</span> <span class="nf">mycommand</span><span class="p">(</span><span class="n">ctx</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
</span><span id="__span-2-6"><a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a> <span class="k">await</span> <span class="n">ctx</span><span class="o">.</span><span class="n">respond</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Your arguments were: </span><span class="si">{</span><span class="n">args</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
</span></code></pre></div>
If you ran <code>!mycommand hello world</code>, the bot would respond with <code>Your arguments were: ('hello', 'world')</code>.</p>
<div class="admonition danger">
<p class="admonition-title">Position &amp; KW-Only args are final and strings!</p>
<p>If you specify a keyword or positional argument, you cannot have any arguments afterwards.
Furthermore, (currently) both of these arguments are always strings. Trying to specify
another type will throw an error.</p>
</div>
<hr />
<h2 id="reference">Reference<a class="headerlink" href="#reference" title="Permanent link">&para;</a></h2>


<div class="doc doc-object doc-module">
Expand Down Expand Up @@ -1893,6 +2007,31 @@ <h4 id="niobot.commands.Command.can_run" class="doc doc-heading">
<div class="doc doc-object doc-function">


<h4 id="niobot.commands.Command.parse_args" class="doc doc-heading">
<span class="doc doc-object-name doc-function-name">parse_args</span>


<span class="doc doc-labels">
<small class="doc doc-label doc-label-async"><code>async</code></small>
</span>

<a href="#niobot.commands.Command.parse_args" class="headerlink" title="Permanent link">&para;</a></h4>
<div class="language-python doc-signature highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">parse_args</span><span class="p">(</span>
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a> <span class="n">ctx</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="niobot.context.Context" href="../context/#niobot.context.Context">Context</a></span><span class="p">,</span>
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" title="typing.Dict" href="https://docs.python.org/3/library/typing.html#typing.Dict">Dict</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-internal" title="niobot.commands.Argument" href="#niobot.commands.Argument">Argument</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-external" title="typing.Union" href="https://docs.python.org/3/library/typing.html#typing.Union">Union</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" title="typing.Any" href="https://docs.python.org/3/library/typing.html#typing.Any">Any</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-external" title="typing.List" href="https://docs.python.org/3/library/typing.html#typing.List">List</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" title="typing.Any" href="https://docs.python.org/3/library/typing.html#typing.Any">Any</a></span><span class="p">]]]</span>
</span></code></pre></div>

<div class="doc doc-contents ">

<p>Parses the arguments for the current command.</p>

</div>

</div>

<div class="doc doc-object doc-function">


<h4 id="niobot.commands.Command.invoke" class="doc doc-heading">
<span class="doc doc-object-name doc-function-name">invoke</span>

Expand Down Expand Up @@ -2553,7 +2692,7 @@ <h3 id="niobot.commands.event" class="doc doc-heading">
<span class="md-icon" title="Last update">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg>
</span>
<span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime">October 9, 2023 20:31:51</span>
<span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime">November 21, 2024 17:01:40</span>
</span>


Expand Down
2 changes: 1 addition & 1 deletion master/search/search_index.json
View file

Large diffs are not rendered by default.

0 comments on commit 0b83879

Please sign in to comment.