200 lines
12 KiB
HTML
200 lines
12 KiB
HTML
<!DOCTYPE html>
|
||
<html>
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>Extensions</title>
|
||
<!-- end extra head -->
|
||
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
|
||
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
|
||
<link rel="stylesheet" type="text/css" href="../../_static/basic.css" />
|
||
<link rel="stylesheet" href="../../_static/style.css" type="text/css" />
|
||
<link rel="stylesheet" href="../../_static/codeblocks.css" type="text/css" />
|
||
<link rel="stylesheet" href="../../_static/icons.css" type="text/css" />
|
||
<script id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
|
||
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
|
||
<script src="../../_static/jquery.js"></script>
|
||
<script src="../../_static/underscore.js"></script>
|
||
<script src="../../_static/doctools.js"></script>
|
||
<script src="../../_static/custom.js"></script>
|
||
<script src="../../_static/settings.js"></script>
|
||
<script src="../../_static/copy.js"></script>
|
||
<script src="../../_static/sidebar.js"></script>
|
||
<link rel="shortcut icon" href="../../_static/discord_py_logo.ico"/>
|
||
<link rel="index" title="Index" href="../../genindex.html" />
|
||
<link rel="search" title="Search" href="../../search.html" />
|
||
<link rel="next" title="Slash Commands" href="slash-commands.html" />
|
||
<link rel="prev" title="Cogs" href="cogs.html" />
|
||
</head>
|
||
<body>
|
||
<div class="main-grid">
|
||
<header class="grid-item">
|
||
<nav>
|
||
<a href="../../index.html" class="main-heading">discord.py</a>
|
||
<a href="https://github.com/Rapptz/discord.py" title="GitHub"><span class="material-icons custom-icons">github</span></a>
|
||
<a href="https://discord.gg/TvqYBrGXEm" title="Discord"><span class="material-icons custom-icons">discord</span></a>
|
||
<a href="../../faq.html" title="FAQ"><span class="material-icons">help_center</span></a>
|
||
<a onclick="mobileSearch.open();" title="Search" id="open-search" class="mobile-only"><span class="material-icons">search</span></a>
|
||
<a onclick="mobileSearch.close();" title="Close" id="close-search" class="mobile-only" hidden><span class="material-icons">close</span></a>
|
||
</nav>
|
||
<nav class="mobile-only">
|
||
<form role="search" class="search" action="../../search.html" method="get">
|
||
<div class="search-wrapper">
|
||
<input type="search" name="q" placeholder="Search documentation" />
|
||
<button type="submit">
|
||
<span class="material-icons">search</span>
|
||
</button>
|
||
</div>
|
||
</form>
|
||
</nav>
|
||
</header>
|
||
<div class="sub-header grid-item">
|
||
<label for="documentation_select">View Documentation For</label>
|
||
<select id="documentation_select" onchange="window.location = this.value;">
|
||
<option value="../../index.html">discord</option>
|
||
<option value="index.html" selected>discord.ext.commands</option>
|
||
<option value="../tasks/index.html" >discord.ext.tasks</option>
|
||
</select>
|
||
<form role="search" class="search" action="../../search.html" method="get">
|
||
<div class="search-wrapper">
|
||
<input type="search" name="q" placeholder="Search documentation" />
|
||
<button type="submit">
|
||
<span class="material-icons">search</span>
|
||
</button>
|
||
</div>
|
||
</form>
|
||
<a accesskey="S" class="settings" onclick="settingsModal.open();"><span class="material-icons">settings</span></a>
|
||
</div>
|
||
<aside class="grid-item">
|
||
<span id="hamburger-toggle">
|
||
<span class="material-icons">menu</span>
|
||
</span>
|
||
<span id="settings-toggle" class="settings" onclick="settingsModal.open();">
|
||
<span class="material-icons">settings</span>
|
||
</span>
|
||
<div id="sidebar">
|
||
<h3><a href="../../index.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Extensions</a><ul>
|
||
<li><a class="reference internal" href="#primer">Primer</a></li>
|
||
<li><a class="reference internal" href="#reloading">Reloading</a></li>
|
||
<li><a class="reference internal" href="#cleaning-up">Cleaning Up</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
</aside>
|
||
<main class="grid-item" role="main">
|
||
|
||
<section id="extensions">
|
||
<span id="ext-commands-extensions"></span><h1>Extensions<a class="headerlink" href="#extensions" title="Permalink to this headline">¶</a></h1>
|
||
<p>There comes a time in the bot development when you want to extend the bot functionality at run-time and quickly unload and reload code (also called hot-reloading). The command framework comes with this ability built-in, with a concept called <strong>extensions</strong>.</p>
|
||
<section id="primer">
|
||
<h2>Primer<a class="headerlink" href="#primer" title="Permalink to this headline">¶</a></h2>
|
||
<p>An extension at its core is a python file with an entry point called <code class="docutils literal notranslate"><span class="pre">setup</span></code>. This setup must be a plain Python function (not a coroutine). It takes a single parameter – the <a class="reference internal" href="api.html#discord.ext.commands.Bot" title="discord.ext.commands.Bot"><code class="xref py py-class docutils literal notranslate"><span class="pre">Bot</span></code></a> that loads the extension.</p>
|
||
<p>An example extension looks like this:</p>
|
||
<div class="literal-block-wrapper docutils container" id="id1">
|
||
<div class="code-block-caption"><span class="caption-text">hello.py</span><a class="headerlink" href="#id1" title="Permalink to this code">¶</a></div>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">discord.ext</span> <span class="kn">import</span> <span class="n">commands</span>
|
||
|
||
<span class="nd">@commands</span><span class="o">.</span><span class="n">command</span><span class="p">()</span>
|
||
<span class="k">async</span> <span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="n">ctx</span><span class="p">):</span>
|
||
<span class="k">await</span> <span class="n">ctx</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="sa">f</span><span class="s1">'Hello </span><span class="si">{</span><span class="n">ctx</span><span class="o">.</span><span class="n">author</span><span class="o">.</span><span class="n">display_name</span><span class="si">}</span><span class="s1">.'</span><span class="p">)</span>
|
||
|
||
<span class="hll"><span class="k">def</span> <span class="nf">setup</span><span class="p">(</span><span class="n">bot</span><span class="p">):</span>
|
||
</span><span class="hll"> <span class="n">bot</span><span class="o">.</span><span class="n">add_command</span><span class="p">(</span><span class="n">hello</span><span class="p">)</span>
|
||
</span></pre></div>
|
||
</div>
|
||
</div>
|
||
<p>In this example we define a simple command, and when the extension is loaded this command is added to the bot. Now the final step to this is loading the extension, which we do by calling <a class="reference internal" href="api.html#discord.ext.commands.Bot.load_extension" title="discord.ext.commands.Bot.load_extension"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Bot.load_extension()</span></code></a>. To load this extension we call <code class="docutils literal notranslate"><span class="pre">bot.load_extension('hello')</span></code>.</p>
|
||
<div class="helpful admonition">
|
||
<p class="admonition-title">Cogs</p>
|
||
<p>Extensions are usually used in conjunction with cogs. To read more about them, check out the documentation, <a class="reference internal" href="cogs.html#ext-commands-cogs"><span class="std std-ref">Cogs</span></a>.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Extension paths are ultimately similar to the import mechanism. What this means is that if there is a folder, then it must be dot-qualified. For example to load an extension in <code class="docutils literal notranslate"><span class="pre">plugins/hello.py</span></code> then we use the string <code class="docutils literal notranslate"><span class="pre">plugins.hello</span></code>.</p>
|
||
</div>
|
||
</section>
|
||
<section id="reloading">
|
||
<h2>Reloading<a class="headerlink" href="#reloading" title="Permalink to this headline">¶</a></h2>
|
||
<p>When you make a change to the extension and want to reload the references, the library comes with a function to do this for you, <a class="reference internal" href="api.html#discord.ext.commands.Bot.reload_extension" title="discord.ext.commands.Bot.reload_extension"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Bot.reload_extension()</span></code></a>.</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">bot</span><span class="o">.</span><span class="n">reload_extension</span><span class="p">(</span><span class="s1">'hello'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Once the extension reloads, any changes that we did will be applied. This is useful if we want to add or remove functionality without restarting our bot. If an error occurred during the reloading process, the bot will pretend as if the reload never happened.</p>
|
||
</section>
|
||
<section id="cleaning-up">
|
||
<h2>Cleaning Up<a class="headerlink" href="#cleaning-up" title="Permalink to this headline">¶</a></h2>
|
||
<p>Although rare, sometimes an extension needs to clean-up or know when it’s being unloaded. For cases like these, there is another entry point named <code class="docutils literal notranslate"><span class="pre">teardown</span></code> which is similar to <code class="docutils literal notranslate"><span class="pre">setup</span></code> except called when the extension is unloaded.</p>
|
||
<div class="literal-block-wrapper docutils container" id="id2">
|
||
<div class="code-block-caption"><span class="caption-text">basic_ext.py</span><a class="headerlink" href="#id2" title="Permalink to this code">¶</a></div>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">setup</span><span class="p">(</span><span class="n">bot</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'I am being loaded!'</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span> <span class="nf">teardown</span><span class="p">(</span><span class="n">bot</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'I am being unloaded!'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</main>
|
||
<footer class="grid-item">
|
||
© Copyright 2015-present, Rapptz.
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.2.0.
|
||
</footer>
|
||
</div>
|
||
|
||
<div id="settings" class="modal" onclick="if (event.target == this){ settingsModal.close(); }" hidden>
|
||
<div class="modal-content">
|
||
<span class="close" onclick="settingsModal.close();" title="Close">
|
||
<span class="material-icons">close</span>
|
||
</span>
|
||
<h1>Settings</h1>
|
||
|
||
<h2>Font</h2>
|
||
<div class="setting">
|
||
<h3>Use a serif font:
|
||
<label class="toggle"
|
||
title="Use a serif font? Your system font will be used, falling back to serif.">
|
||
<input type="checkbox" name="useSerifFont" onclick="updateSetting(this);">
|
||
<span class="toggle-slider"></span>
|
||
</label>
|
||
</h3>
|
||
</div>
|
||
|
||
<h2>Theme</h2>
|
||
<div class="setting">
|
||
<h3>
|
||
<label class="toggle" title="Set your theme based on your system preferences">
|
||
<input type="radio" name="setTheme" onclick="updateSetting(this);" value="automatic" checked>
|
||
</label>
|
||
Automatic
|
||
</h3>
|
||
<h3>
|
||
<label class="toggle" title="Set your theme to light theme">
|
||
<input type="radio" name="setTheme" onclick="updateSetting(this);" value="light">
|
||
</label>
|
||
Light
|
||
</h3>
|
||
<h3>
|
||
<label class="toggle" title="Set your theme to dark theme">
|
||
<input type="radio" name="setTheme" onclick="updateSetting(this);" value="dark">
|
||
</label>
|
||
Dark
|
||
</h3>
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<div id="to-top" onclick="scrollToTop()" hidden>
|
||
<span><span class="material-icons">arrow_upward</span> to top</span>
|
||
</div>
|
||
|
||
</body>
|
||
</html> |