601 lines
68 KiB
HTML
601 lines
68 KiB
HTML
<!DOCTYPE html>
|
||
<html>
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>Frequently Asked Questions</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" />
|
||
</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="#" 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="#" selected>discord</option>
|
||
<option value="ext/commands/index.html" >discord.ext.commands</option>
|
||
<option value="ext/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="#">Frequently Asked Questions</a><ul>
|
||
<li><a class="reference internal" href="#coroutines">Coroutines</a><ul>
|
||
<li><a class="reference internal" href="#what-is-a-coroutine">What is a coroutine?</a></li>
|
||
<li><a class="reference internal" href="#where-can-i-use-await">Where can I use <code class="docutils literal notranslate"><span class="pre">await</span></code>?</a></li>
|
||
<li><a class="reference internal" href="#what-does-blocking-mean">What does “blocking” mean?</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#general">General</a><ul>
|
||
<li><a class="reference internal" href="#where-can-i-find-usage-examples">Where can I find usage examples?</a></li>
|
||
<li><a class="reference internal" href="#how-do-i-set-the-playing-status">How do I set the “Playing” status?</a></li>
|
||
<li><a class="reference internal" href="#how-do-i-send-a-message-to-a-specific-channel">How do I send a message to a specific channel?</a></li>
|
||
<li><a class="reference internal" href="#how-do-i-send-a-dm">How do I send a DM?</a></li>
|
||
<li><a class="reference internal" href="#how-do-i-get-the-id-of-a-sent-message">How do I get the ID of a sent message?</a></li>
|
||
<li><a class="reference internal" href="#how-do-i-upload-an-image">How do I upload an image?</a></li>
|
||
<li><a class="reference internal" href="#how-can-i-add-a-reaction-to-a-message">How can I add a reaction to a message?</a></li>
|
||
<li><a class="reference internal" href="#how-do-i-pass-a-coroutine-to-the-player-s-after-function">How do I pass a coroutine to the player’s “after” function?</a></li>
|
||
<li><a class="reference internal" href="#how-do-i-run-something-in-the-background">How do I run something in the background?</a></li>
|
||
<li><a class="reference internal" href="#how-do-i-get-a-specific-model">How do I get a specific model?</a></li>
|
||
<li><a class="reference internal" href="#how-do-i-make-a-web-request">How do I make a web request?</a></li>
|
||
<li><a class="reference internal" href="#how-do-i-use-a-local-image-file-for-an-embed-image">How do I use a local image file for an embed image?</a></li>
|
||
<li><a class="reference internal" href="#is-there-an-event-for-audit-log-entries-being-created">Is there an event for audit log entries being created?</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#commands-extension">Commands Extension</a><ul>
|
||
<li><a class="reference internal" href="#why-does-on-message-make-my-commands-stop-working">Why does <code class="docutils literal notranslate"><span class="pre">on_message</span></code> make my commands stop working?</a></li>
|
||
<li><a class="reference internal" href="#why-do-my-arguments-require-quotes">Why do my arguments require quotes?</a></li>
|
||
<li><a class="reference internal" href="#how-do-i-get-the-original-message">How do I get the original <code class="docutils literal notranslate"><span class="pre">message</span></code>?</a></li>
|
||
<li><a class="reference internal" href="#how-do-i-make-a-subcommand">How do I make a subcommand?</a></li>
|
||
<li><a class="reference internal" href="#how-do-i-make-slash-commands">How do I make slash commands?</a></li>
|
||
<li><a class="reference internal" href="#my-slash-commands-aren-t-showing-up">My slash commands aren’t showing up!</a></li>
|
||
<li><a class="reference internal" href="#my-bot-won-t-start-after-enabling-slash-commands">My bot won’t start after enabling slash commands!</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
</aside>
|
||
<main class="grid-item" role="main">
|
||
|
||
<section id="frequently-asked-questions">
|
||
<span id="faq"></span><h1>Frequently Asked Questions<a class="headerlink" href="#frequently-asked-questions" title="Permalink to this headline">¶</a></h1>
|
||
<p>This is a list of Frequently Asked Questions regarding using <code class="docutils literal notranslate"><span class="pre">discord.py</span></code> and its extension modules. Feel free to suggest a
|
||
new question or submit one via pull requests.</p>
|
||
<div class="contents local topic" id="questions">
|
||
<p class="topic-title">Questions</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="#coroutines" id="id1">Coroutines</a></p>
|
||
<ul>
|
||
<li><p><a class="reference internal" href="#what-is-a-coroutine" id="id2">What is a coroutine?</a></p></li>
|
||
<li><p><a class="reference internal" href="#where-can-i-use-await" id="id3">Where can I use <code class="docutils literal notranslate"><span class="pre">await</span></code>?</a></p></li>
|
||
<li><p><a class="reference internal" href="#what-does-blocking-mean" id="id4">What does “blocking” mean?</a></p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference internal" href="#general" id="id5">General</a></p>
|
||
<ul>
|
||
<li><p><a class="reference internal" href="#where-can-i-find-usage-examples" id="id6">Where can I find usage examples?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-do-i-set-the-playing-status" id="id7">How do I set the “Playing” status?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-do-i-send-a-message-to-a-specific-channel" id="id8">How do I send a message to a specific channel?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-do-i-send-a-dm" id="id9">How do I send a DM?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-do-i-get-the-id-of-a-sent-message" id="id10">How do I get the ID of a sent message?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-do-i-upload-an-image" id="id11">How do I upload an image?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-can-i-add-a-reaction-to-a-message" id="id12">How can I add a reaction to a message?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-do-i-pass-a-coroutine-to-the-player-s-after-function" id="id13">How do I pass a coroutine to the player’s “after” function?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-do-i-run-something-in-the-background" id="id14">How do I run something in the background?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-do-i-get-a-specific-model" id="id15">How do I get a specific model?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-do-i-make-a-web-request" id="id16">How do I make a web request?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-do-i-use-a-local-image-file-for-an-embed-image" id="id17">How do I use a local image file for an embed image?</a></p></li>
|
||
<li><p><a class="reference internal" href="#is-there-an-event-for-audit-log-entries-being-created" id="id18">Is there an event for audit log entries being created?</a></p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference internal" href="#commands-extension" id="id19">Commands Extension</a></p>
|
||
<ul>
|
||
<li><p><a class="reference internal" href="#why-does-on-message-make-my-commands-stop-working" id="id20">Why does <code class="docutils literal notranslate"><span class="pre">on_message</span></code> make my commands stop working?</a></p></li>
|
||
<li><p><a class="reference internal" href="#why-do-my-arguments-require-quotes" id="id21">Why do my arguments require quotes?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-do-i-get-the-original-message" id="id22">How do I get the original <code class="docutils literal notranslate"><span class="pre">message</span></code>?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-do-i-make-a-subcommand" id="id23">How do I make a subcommand?</a></p></li>
|
||
<li><p><a class="reference internal" href="#how-do-i-make-slash-commands" id="id24">How do I make slash commands?</a></p></li>
|
||
<li><p><a class="reference internal" href="#my-slash-commands-aren-t-showing-up" id="id25">My slash commands aren’t showing up!</a></p></li>
|
||
<li><p><a class="reference internal" href="#my-bot-won-t-start-after-enabling-slash-commands" id="id26">My bot won’t start after enabling slash commands!</a></p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<section id="coroutines">
|
||
<h2><a class="toc-backref" href="#id1">Coroutines</a><a class="headerlink" href="#coroutines" title="Permalink to this headline">¶</a></h2>
|
||
<p>Questions regarding coroutines and asyncio belong here.</p>
|
||
<section id="what-is-a-coroutine">
|
||
<h3><a class="toc-backref" href="#id2">What is a coroutine?</a><a class="headerlink" href="#what-is-a-coroutine" title="Permalink to this headline">¶</a></h3>
|
||
<p>A <a class="reference external" href="https://docs.python.org/3/library/asyncio-task.html#coroutine"><em>coroutine</em></a> is a function that must be invoked with <code class="docutils literal notranslate"><span class="pre">await</span></code> or <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">from</span></code>. When Python encounters an <code class="docutils literal notranslate"><span class="pre">await</span></code> it stops
|
||
the function’s execution at that point and works on other things until it comes back to that point and finishes off its work.
|
||
This allows for your program to be doing multiple things at the same time without using threads or complicated
|
||
multiprocessing.</p>
|
||
<p><strong>If you forget to await a coroutine then the coroutine will not run. Never forget to await a coroutine.</strong></p>
|
||
</section>
|
||
<section id="where-can-i-use-await">
|
||
<h3><a class="toc-backref" href="#id3">Where can I use <code class="docutils literal notranslate"><span class="pre">await</span></code>?</a><a class="headerlink" href="#where-can-i-use-await" title="Permalink to this headline">¶</a></h3>
|
||
<p>You can only use <code class="docutils literal notranslate"><span class="pre">await</span></code> inside <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code> functions and nowhere else.</p>
|
||
</section>
|
||
<section id="what-does-blocking-mean">
|
||
<h3><a class="toc-backref" href="#id4">What does “blocking” mean?</a><a class="headerlink" href="#what-does-blocking-mean" title="Permalink to this headline">¶</a></h3>
|
||
<p>In asynchronous programming a blocking call is essentially all the parts of the function that are not <code class="docutils literal notranslate"><span class="pre">await</span></code>. Do not
|
||
despair however, because not all forms of blocking are bad! Using blocking calls is inevitable, but you must work to make
|
||
sure that you don’t excessively block functions. Remember, if you block for too long then your bot will freeze since it has
|
||
not stopped the function’s execution at that point to do other things.</p>
|
||
<p>If logging is enabled, this library will attempt to warn you that blocking is occurring with the message:
|
||
<code class="docutils literal notranslate"><span class="pre">Heartbeat</span> <span class="pre">blocked</span> <span class="pre">for</span> <span class="pre">more</span> <span class="pre">than</span> <span class="pre">N</span> <span class="pre">seconds.</span></code>
|
||
See <a class="reference internal" href="logging.html#logging-setup"><span class="std std-ref">Setting Up Logging</span></a> for details on enabling logging.</p>
|
||
<p>A common source of blocking for too long is something like <a class="reference external" href="https://docs.python.org/3/library/time.html#time.sleep" title="(in Python v3.9)"><code class="xref py py-func docutils literal notranslate"><span class="pre">time.sleep()</span></code></a>. Don’t do that. Use <a class="reference external" href="https://docs.python.org/3/library/asyncio-task.html#asyncio.sleep" title="(in Python v3.9)"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.sleep()</span></code></a>
|
||
instead. Similar to this example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># bad</span>
|
||
<span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
|
||
|
||
<span class="c1"># good</span>
|
||
<span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Another common source of blocking for too long is using HTTP requests with the famous module <a class="reference external" href="https://docs.python-requests.org/en/latest/" title="(in Requests v2.26.0)"><span>Requests: HTTP for Humans™</span></a>.
|
||
While <a class="reference external" href="https://docs.python-requests.org/en/latest/" title="(in Requests v2.26.0)"><span>Requests: HTTP for Humans™</span></a> is an amazing module for non-asynchronous programming, it is not a good choice for
|
||
<a class="reference external" href="https://docs.python.org/3/library/asyncio.html#module-asyncio" title="(in Python v3.9)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> because certain requests can block the event loop too long. Instead, use the <a class="reference external" href="https://docs.aiohttp.org/en/stable/index.html" title="(in aiohttp v3.7)"><span class="xref std std-doc">aiohttp</span></a> library which
|
||
is installed on the side with this library.</p>
|
||
<p>Consider the following example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># bad</span>
|
||
<span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'http://aws.random.cat/meow'</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">200</span><span class="p">:</span>
|
||
<span class="n">js</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
|
||
<span class="k">await</span> <span class="n">channel</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">js</span><span class="p">[</span><span class="s1">'file'</span><span class="p">])</span>
|
||
|
||
<span class="c1"># good</span>
|
||
<span class="k">async</span> <span class="k">with</span> <span class="n">aiohttp</span><span class="o">.</span><span class="n">ClientSession</span><span class="p">()</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
||
<span class="k">async</span> <span class="k">with</span> <span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'http://aws.random.cat/meow'</span><span class="p">)</span> <span class="k">as</span> <span class="n">r</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="n">r</span><span class="o">.</span><span class="n">status</span> <span class="o">==</span> <span class="mi">200</span><span class="p">:</span>
|
||
<span class="n">js</span> <span class="o">=</span> <span class="k">await</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
|
||
<span class="k">await</span> <span class="n">channel</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">js</span><span class="p">[</span><span class="s1">'file'</span><span class="p">])</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="general">
|
||
<h2><a class="toc-backref" href="#id5">General</a><a class="headerlink" href="#general" title="Permalink to this headline">¶</a></h2>
|
||
<p>General questions regarding library usage belong here.</p>
|
||
<section id="where-can-i-find-usage-examples">
|
||
<h3><a class="toc-backref" href="#id6">Where can I find usage examples?</a><a class="headerlink" href="#where-can-i-find-usage-examples" title="Permalink to this headline">¶</a></h3>
|
||
<p>Example code can be found in the <a class="reference external" href="https://github.com/Rapptz/discord.py/tree/master/examples">examples folder</a>
|
||
in the repository.</p>
|
||
</section>
|
||
<section id="how-do-i-set-the-playing-status">
|
||
<h3><a class="toc-backref" href="#id7">How do I set the “Playing” status?</a><a class="headerlink" href="#how-do-i-set-the-playing-status" title="Permalink to this headline">¶</a></h3>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">activity</span></code> keyword argument may be passed in the <a class="reference internal" href="api.html#discord.Client" title="discord.Client"><code class="xref py py-class docutils literal notranslate"><span class="pre">Client</span></code></a> constructor or <a class="reference internal" href="api.html#discord.Client.change_presence" title="discord.Client.change_presence"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.change_presence()</span></code></a>, given an <a class="reference internal" href="api.html#discord.Activity" title="discord.Activity"><code class="xref py py-class docutils literal notranslate"><span class="pre">Activity</span></code></a> object.</p>
|
||
<p>The constructor may be used for static activities, while <a class="reference internal" href="api.html#discord.Client.change_presence" title="discord.Client.change_presence"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.change_presence()</span></code></a> may be used to update the activity at runtime.</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>It is highly discouraged to use <a class="reference internal" href="api.html#discord.Client.change_presence" title="discord.Client.change_presence"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.change_presence()</span></code></a> or API calls in <a class="reference internal" href="api.html#discord.on_ready" title="discord.on_ready"><code class="xref py py-func docutils literal notranslate"><span class="pre">on_ready()</span></code></a> as this event may be called many times while running, not just once.</p>
|
||
<p>There is a high chance of disconnecting if presences are changed right after connecting.</p>
|
||
</div>
|
||
<p>The status type (playing, listening, streaming, watching) can be set using the <a class="reference internal" href="api.html#discord.ActivityType" title="discord.ActivityType"><code class="xref py py-class docutils literal notranslate"><span class="pre">ActivityType</span></code></a> enum.
|
||
For memory optimisation purposes, some activities are offered in slimmed-down versions:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="api.html#discord.Game" title="discord.Game"><code class="xref py py-class docutils literal notranslate"><span class="pre">Game</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="api.html#discord.Streaming" title="discord.Streaming"><code class="xref py py-class docutils literal notranslate"><span class="pre">Streaming</span></code></a></p></li>
|
||
</ul>
|
||
<p>Putting both of these pieces of info together, you get the following:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">client</span> <span class="o">=</span> <span class="n">discord</span><span class="o">.</span><span class="n">Client</span><span class="p">(</span><span class="n">activity</span><span class="o">=</span><span class="n">discord</span><span class="o">.</span><span class="n">Game</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'my game'</span><span class="p">))</span>
|
||
|
||
<span class="c1"># or, for watching:</span>
|
||
<span class="n">activity</span> <span class="o">=</span> <span class="n">discord</span><span class="o">.</span><span class="n">Activity</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'my activity'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">discord</span><span class="o">.</span><span class="n">ActivityType</span><span class="o">.</span><span class="n">watching</span><span class="p">)</span>
|
||
<span class="n">client</span> <span class="o">=</span> <span class="n">discord</span><span class="o">.</span><span class="n">Client</span><span class="p">(</span><span class="n">activity</span><span class="o">=</span><span class="n">activity</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="how-do-i-send-a-message-to-a-specific-channel">
|
||
<h3><a class="toc-backref" href="#id8">How do I send a message to a specific channel?</a><a class="headerlink" href="#how-do-i-send-a-message-to-a-specific-channel" title="Permalink to this headline">¶</a></h3>
|
||
<p>You must fetch the channel directly and then call the appropriate method. Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">channel</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">get_channel</span><span class="p">(</span><span class="mi">12324234183172</span><span class="p">)</span>
|
||
<span class="k">await</span> <span class="n">channel</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="s1">'hello'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="how-do-i-send-a-dm">
|
||
<h3><a class="toc-backref" href="#id9">How do I send a DM?</a><a class="headerlink" href="#how-do-i-send-a-dm" title="Permalink to this headline">¶</a></h3>
|
||
<p>Get the <a class="reference internal" href="api.html#discord.User" title="discord.User"><code class="xref py py-class docutils literal notranslate"><span class="pre">User</span></code></a> or <a class="reference internal" href="api.html#discord.Member" title="discord.Member"><code class="xref py py-class docutils literal notranslate"><span class="pre">Member</span></code></a> object and call <a class="reference internal" href="api.html#discord.abc.Messageable.send" title="discord.abc.Messageable.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">abc.Messageable.send()</span></code></a>. For example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">user</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">get_user</span><span class="p">(</span><span class="mi">381870129706958858</span><span class="p">)</span>
|
||
<span class="k">await</span> <span class="n">user</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="s1">'👀'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If you are responding to an event, such as <a class="reference internal" href="api.html#discord.on_message" title="discord.on_message"><code class="xref py py-func docutils literal notranslate"><span class="pre">on_message()</span></code></a>, you already have the <a class="reference internal" href="api.html#discord.User" title="discord.User"><code class="xref py py-class docutils literal notranslate"><span class="pre">User</span></code></a> object via <a class="reference internal" href="api.html#discord.Message.author" title="discord.Message.author"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Message.author</span></code></a>:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">await</span> <span class="n">message</span><span class="o">.</span><span class="n">author</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="s1">'👋'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="how-do-i-get-the-id-of-a-sent-message">
|
||
<h3><a class="toc-backref" href="#id10">How do I get the ID of a sent message?</a><a class="headerlink" href="#how-do-i-get-the-id-of-a-sent-message" title="Permalink to this headline">¶</a></h3>
|
||
<p><a class="reference internal" href="api.html#discord.abc.Messageable.send" title="discord.abc.Messageable.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">abc.Messageable.send()</span></code></a> returns the <a class="reference internal" href="api.html#discord.Message" title="discord.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> that was sent.
|
||
The ID of a message can be accessed via <a class="reference internal" href="api.html#discord.Message.id" title="discord.Message.id"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Message.id</span></code></a>:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">message</span> <span class="o">=</span> <span class="k">await</span> <span class="n">channel</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="s1">'hmm…'</span><span class="p">)</span>
|
||
<span class="n">message_id</span> <span class="o">=</span> <span class="n">message</span><span class="o">.</span><span class="n">id</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="how-do-i-upload-an-image">
|
||
<h3><a class="toc-backref" href="#id11">How do I upload an image?</a><a class="headerlink" href="#how-do-i-upload-an-image" title="Permalink to this headline">¶</a></h3>
|
||
<p>To upload something to Discord you have to use the <a class="reference internal" href="api.html#discord.File" title="discord.File"><code class="xref py py-class docutils literal notranslate"><span class="pre">File</span></code></a> object.</p>
|
||
<p>A <a class="reference internal" href="api.html#discord.File" title="discord.File"><code class="xref py py-class docutils literal notranslate"><span class="pre">File</span></code></a> accepts two parameters, the file-like object (or file path) and the filename
|
||
to pass to Discord when uploading.</p>
|
||
<p>If you want to upload an image it’s as simple as:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">await</span> <span class="n">channel</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">file</span><span class="o">=</span><span class="n">discord</span><span class="o">.</span><span class="n">File</span><span class="p">(</span><span class="s1">'my_file.png'</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If you have a file-like object you can do as follows:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'my_file.png'</span><span class="p">,</span> <span class="s1">'rb'</span><span class="p">)</span> <span class="k">as</span> <span class="n">fp</span><span class="p">:</span>
|
||
<span class="k">await</span> <span class="n">channel</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">file</span><span class="o">=</span><span class="n">discord</span><span class="o">.</span><span class="n">File</span><span class="p">(</span><span class="n">fp</span><span class="p">,</span> <span class="s1">'new_filename.png'</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>To upload multiple files, you can use the <code class="docutils literal notranslate"><span class="pre">files</span></code> keyword argument instead of <code class="docutils literal notranslate"><span class="pre">file</span></code>:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">my_files</span> <span class="o">=</span> <span class="p">[</span>
|
||
<span class="n">discord</span><span class="o">.</span><span class="n">File</span><span class="p">(</span><span class="s1">'result.zip'</span><span class="p">),</span>
|
||
<span class="n">discord</span><span class="o">.</span><span class="n">File</span><span class="p">(</span><span class="s1">'teaser_graph.png'</span><span class="p">),</span>
|
||
<span class="p">]</span>
|
||
<span class="k">await</span> <span class="n">channel</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">files</span><span class="o">=</span><span class="n">my_files</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If you want to upload something from a URL, you will have to use an HTTP request using <a class="reference external" href="https://docs.aiohttp.org/en/stable/index.html" title="(in aiohttp v3.7)"><span class="xref std std-doc">aiohttp</span></a>
|
||
and then pass an <a class="reference external" href="https://docs.python.org/3/library/io.html#io.BytesIO" title="(in Python v3.9)"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.BytesIO</span></code></a> instance to <a class="reference internal" href="api.html#discord.File" title="discord.File"><code class="xref py py-class docutils literal notranslate"><span class="pre">File</span></code></a> like so:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">io</span>
|
||
<span class="kn">import</span> <span class="nn">aiohttp</span>
|
||
|
||
<span class="k">async</span> <span class="k">with</span> <span class="n">aiohttp</span><span class="o">.</span><span class="n">ClientSession</span><span class="p">()</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
||
<span class="k">async</span> <span class="k">with</span> <span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">my_url</span><span class="p">)</span> <span class="k">as</span> <span class="n">resp</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="n">resp</span><span class="o">.</span><span class="n">status</span> <span class="o">!=</span> <span class="mi">200</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="k">await</span> <span class="n">channel</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="s1">'Could not download file...'</span><span class="p">)</span>
|
||
<span class="n">data</span> <span class="o">=</span> <span class="n">io</span><span class="o">.</span><span class="n">BytesIO</span><span class="p">(</span><span class="k">await</span> <span class="n">resp</span><span class="o">.</span><span class="n">read</span><span class="p">())</span>
|
||
<span class="k">await</span> <span class="n">channel</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">file</span><span class="o">=</span><span class="n">discord</span><span class="o">.</span><span class="n">File</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="s1">'cool_image.png'</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="how-can-i-add-a-reaction-to-a-message">
|
||
<h3><a class="toc-backref" href="#id12">How can I add a reaction to a message?</a><a class="headerlink" href="#how-can-i-add-a-reaction-to-a-message" title="Permalink to this headline">¶</a></h3>
|
||
<p>You use the <a class="reference internal" href="api.html#discord.Message.add_reaction" title="discord.Message.add_reaction"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Message.add_reaction()</span></code></a> method.</p>
|
||
<p>If you want to use unicode emoji, you must pass a valid unicode code point in a string. In your code, you can write this in a few different ways:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'👍'</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'\U0001F44D'</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">'\N{THUMBS</span> <span class="pre">UP</span> <span class="pre">SIGN}'</span></code></p></li>
|
||
</ul>
|
||
<p>Quick example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">emoji</span> <span class="o">=</span> <span class="s1">'</span><span class="se">\N{THUMBS UP SIGN}</span><span class="s1">'</span>
|
||
<span class="c1"># or '\U0001f44d' or '👍'</span>
|
||
<span class="k">await</span> <span class="n">message</span><span class="o">.</span><span class="n">add_reaction</span><span class="p">(</span><span class="n">emoji</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In case you want to use emoji that come from a message, you already get their code points in the content without needing
|
||
to do anything special. You <strong>cannot</strong> send <code class="docutils literal notranslate"><span class="pre">':thumbsup:'</span></code> style shorthands.</p>
|
||
<p>For custom emoji, you should pass an instance of <a class="reference internal" href="api.html#discord.Emoji" title="discord.Emoji"><code class="xref py py-class docutils literal notranslate"><span class="pre">Emoji</span></code></a>. You can also pass a <code class="docutils literal notranslate"><span class="pre">'<:name:id>'</span></code> string, but if you
|
||
can use said emoji, you should be able to use <a class="reference internal" href="api.html#discord.Client.get_emoji" title="discord.Client.get_emoji"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.get_emoji()</span></code></a> to get an emoji via ID or use <a class="reference internal" href="api.html#discord.utils.find" title="discord.utils.find"><code class="xref py py-func docutils literal notranslate"><span class="pre">utils.find()</span></code></a>/
|
||
<a class="reference internal" href="api.html#discord.utils.get" title="discord.utils.get"><code class="xref py py-func docutils literal notranslate"><span class="pre">utils.get()</span></code></a> on <a class="reference internal" href="api.html#discord.Client.emojis" title="discord.Client.emojis"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Client.emojis</span></code></a> or <a class="reference internal" href="api.html#discord.Guild.emojis" title="discord.Guild.emojis"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Guild.emojis</span></code></a> collections.</p>
|
||
<p>The name and ID of a custom emoji can be found with the client by prefixing <code class="docutils literal notranslate"><span class="pre">:custom_emoji:</span></code> with a backslash.
|
||
For example, sending the message <code class="docutils literal notranslate"><span class="pre">\:python3:</span></code> with the client will result in <code class="docutils literal notranslate"><span class="pre"><:python3:232720527448342530></span></code>.</p>
|
||
<p>Quick example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># if you have the ID already</span>
|
||
<span class="n">emoji</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">get_emoji</span><span class="p">(</span><span class="mi">310177266011340803</span><span class="p">)</span>
|
||
<span class="k">await</span> <span class="n">message</span><span class="o">.</span><span class="n">add_reaction</span><span class="p">(</span><span class="n">emoji</span><span class="p">)</span>
|
||
|
||
<span class="c1"># no ID, do a lookup</span>
|
||
<span class="n">emoji</span> <span class="o">=</span> <span class="n">discord</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">guild</span><span class="o">.</span><span class="n">emojis</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">'LUL'</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">emoji</span><span class="p">:</span>
|
||
<span class="k">await</span> <span class="n">message</span><span class="o">.</span><span class="n">add_reaction</span><span class="p">(</span><span class="n">emoji</span><span class="p">)</span>
|
||
|
||
<span class="c1"># if you have the name and ID of a custom emoji:</span>
|
||
<span class="n">emoji</span> <span class="o">=</span> <span class="s1">'<:python3:232720527448342530>'</span>
|
||
<span class="k">await</span> <span class="n">message</span><span class="o">.</span><span class="n">add_reaction</span><span class="p">(</span><span class="n">emoji</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="how-do-i-pass-a-coroutine-to-the-player-s-after-function">
|
||
<h3><a class="toc-backref" href="#id13">How do I pass a coroutine to the player’s “after” function?</a><a class="headerlink" href="#how-do-i-pass-a-coroutine-to-the-player-s-after-function" title="Permalink to this headline">¶</a></h3>
|
||
<p>The library’s music player launches on a separate thread, ergo it does not execute inside a coroutine.
|
||
This does not mean that it is not possible to call a coroutine in the <code class="docutils literal notranslate"><span class="pre">after</span></code> parameter. To do so you must pass a callable
|
||
that wraps up a couple of aspects.</p>
|
||
<p>The first gotcha that you must be aware of is that calling a coroutine is not a thread-safe operation. Since we are
|
||
technically in another thread, we must take caution in calling thread-safe operations so things do not bug out. Luckily for
|
||
us, <a class="reference external" href="https://docs.python.org/3/library/asyncio.html#module-asyncio" title="(in Python v3.9)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> comes with a <a class="reference external" href="https://docs.python.org/3/library/asyncio-task.html#asyncio.run_coroutine_threadsafe" title="(in Python v3.9)"><code class="xref py py-func docutils literal notranslate"><span class="pre">asyncio.run_coroutine_threadsafe()</span></code></a> function that allows us to call
|
||
a coroutine from another thread.</p>
|
||
<p>However, this function returns a <a class="reference external" href="https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future" title="(in Python v3.9)"><code class="xref py py-class docutils literal notranslate"><span class="pre">Future</span></code></a> and to actually call it we have to fetch its result. Putting all of
|
||
this together we can do the following:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">my_after</span><span class="p">(</span><span class="n">error</span><span class="p">):</span>
|
||
<span class="n">coro</span> <span class="o">=</span> <span class="n">some_channel</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="s1">'Song is done!'</span><span class="p">)</span>
|
||
<span class="n">fut</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">run_coroutine_threadsafe</span><span class="p">(</span><span class="n">coro</span><span class="p">,</span> <span class="n">client</span><span class="o">.</span><span class="n">loop</span><span class="p">)</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="n">fut</span><span class="o">.</span><span class="n">result</span><span class="p">()</span>
|
||
<span class="k">except</span><span class="p">:</span>
|
||
<span class="c1"># an error happened sending the message</span>
|
||
<span class="k">pass</span>
|
||
|
||
<span class="n">voice</span><span class="o">.</span><span class="n">play</span><span class="p">(</span><span class="n">discord</span><span class="o">.</span><span class="n">FFmpegPCMAudio</span><span class="p">(</span><span class="n">url</span><span class="p">),</span> <span class="n">after</span><span class="o">=</span><span class="n">my_after</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="how-do-i-run-something-in-the-background">
|
||
<h3><a class="toc-backref" href="#id14">How do I run something in the background?</a><a class="headerlink" href="#how-do-i-run-something-in-the-background" title="Permalink to this headline">¶</a></h3>
|
||
<p><a class="reference external" href="https://github.com/Rapptz/discord.py/blob/master/examples/background_task.py">Check the background_task.py example.</a></p>
|
||
</section>
|
||
<section id="how-do-i-get-a-specific-model">
|
||
<h3><a class="toc-backref" href="#id15">How do I get a specific model?</a><a class="headerlink" href="#how-do-i-get-a-specific-model" title="Permalink to this headline">¶</a></h3>
|
||
<p>There are multiple ways of doing this. If you have a specific model’s ID then you can use
|
||
one of the following functions:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="api.html#discord.Client.get_channel" title="discord.Client.get_channel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.get_channel()</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="api.html#discord.Client.get_guild" title="discord.Client.get_guild"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.get_guild()</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="api.html#discord.Client.get_user" title="discord.Client.get_user"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.get_user()</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="api.html#discord.Client.get_emoji" title="discord.Client.get_emoji"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.get_emoji()</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="api.html#discord.Guild.get_member" title="discord.Guild.get_member"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Guild.get_member()</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="api.html#discord.Guild.get_channel" title="discord.Guild.get_channel"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Guild.get_channel()</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="api.html#discord.Guild.get_role" title="discord.Guild.get_role"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Guild.get_role()</span></code></a></p></li>
|
||
</ul>
|
||
<p>The following use an HTTP request:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="api.html#discord.abc.Messageable.fetch_message" title="discord.abc.Messageable.fetch_message"><code class="xref py py-meth docutils literal notranslate"><span class="pre">abc.Messageable.fetch_message()</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="api.html#discord.Client.fetch_user" title="discord.Client.fetch_user"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.fetch_user()</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="api.html#discord.Client.fetch_guilds" title="discord.Client.fetch_guilds"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.fetch_guilds()</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="api.html#discord.Client.fetch_guild" title="discord.Client.fetch_guild"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.fetch_guild()</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="api.html#discord.Guild.fetch_emoji" title="discord.Guild.fetch_emoji"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Guild.fetch_emoji()</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="api.html#discord.Guild.fetch_emojis" title="discord.Guild.fetch_emojis"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Guild.fetch_emojis()</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="api.html#discord.Guild.fetch_member" title="discord.Guild.fetch_member"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Guild.fetch_member()</span></code></a></p></li>
|
||
</ul>
|
||
<p>If the functions above do not help you, then use of <a class="reference internal" href="api.html#discord.utils.find" title="discord.utils.find"><code class="xref py py-func docutils literal notranslate"><span class="pre">utils.find()</span></code></a> or <a class="reference internal" href="api.html#discord.utils.get" title="discord.utils.get"><code class="xref py py-func docutils literal notranslate"><span class="pre">utils.get()</span></code></a> would serve some use in finding
|
||
specific models.</p>
|
||
<p>Quick example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># find a guild by name</span>
|
||
<span class="n">guild</span> <span class="o">=</span> <span class="n">discord</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">client</span><span class="o">.</span><span class="n">guilds</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">'My Server'</span><span class="p">)</span>
|
||
|
||
<span class="c1"># make sure to check if it's found</span>
|
||
<span class="k">if</span> <span class="n">guild</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
|
||
<span class="c1"># find a channel by name</span>
|
||
<span class="n">channel</span> <span class="o">=</span> <span class="n">discord</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">guild</span><span class="o">.</span><span class="n">text_channels</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">'cool-channel'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="how-do-i-make-a-web-request">
|
||
<h3><a class="toc-backref" href="#id16">How do I make a web request?</a><a class="headerlink" href="#how-do-i-make-a-web-request" title="Permalink to this headline">¶</a></h3>
|
||
<p>To make a request, you should use a non-blocking library.
|
||
This library already uses and requires a 3rd party library for making requests, <a class="reference external" href="https://docs.aiohttp.org/en/stable/index.html" title="(in aiohttp v3.7)"><span class="xref std std-doc">aiohttp</span></a>.</p>
|
||
<p>Quick example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">with</span> <span class="n">aiohttp</span><span class="o">.</span><span class="n">ClientSession</span><span class="p">()</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
||
<span class="k">async</span> <span class="k">with</span> <span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'http://aws.random.cat/meow'</span><span class="p">)</span> <span class="k">as</span> <span class="n">r</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="n">r</span><span class="o">.</span><span class="n">status</span> <span class="o">==</span> <span class="mi">200</span><span class="p">:</span>
|
||
<span class="n">js</span> <span class="o">=</span> <span class="k">await</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>See <a class="reference external" href="http://aiohttp.readthedocs.io/en/stable/">aiohttp’s full documentation</a> for more information.</p>
|
||
</section>
|
||
<section id="how-do-i-use-a-local-image-file-for-an-embed-image">
|
||
<h3><a class="toc-backref" href="#id17">How do I use a local image file for an embed image?</a><a class="headerlink" href="#how-do-i-use-a-local-image-file-for-an-embed-image" title="Permalink to this headline">¶</a></h3>
|
||
<p>Discord special-cases uploading an image attachment and using it within an embed so that it will not
|
||
display separately, but instead in the embed’s thumbnail, image, footer or author icon.</p>
|
||
<p>To do so, upload the image normally with <a class="reference internal" href="api.html#discord.abc.Messageable.send" title="discord.abc.Messageable.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">abc.Messageable.send()</span></code></a>,
|
||
and set the embed’s image URL to <code class="docutils literal notranslate"><span class="pre">attachment://image.png</span></code>,
|
||
where <code class="docutils literal notranslate"><span class="pre">image.png</span></code> is the filename of the image you will send.</p>
|
||
<p>Quick example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">file</span> <span class="o">=</span> <span class="n">discord</span><span class="o">.</span><span class="n">File</span><span class="p">(</span><span class="s2">"path/to/my/image.png"</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="s2">"image.png"</span><span class="p">)</span>
|
||
<span class="n">embed</span> <span class="o">=</span> <span class="n">discord</span><span class="o">.</span><span class="n">Embed</span><span class="p">()</span>
|
||
<span class="n">embed</span><span class="o">.</span><span class="n">set_image</span><span class="p">(</span><span class="n">url</span><span class="o">=</span><span class="s2">"attachment://image.png"</span><span class="p">)</span>
|
||
<span class="k">await</span> <span class="n">channel</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">file</span><span class="o">=</span><span class="n">file</span><span class="p">,</span> <span class="n">embed</span><span class="o">=</span><span class="n">embed</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Due to a Discord limitation, filenames may not include underscores.</p>
|
||
</div>
|
||
</section>
|
||
<section id="is-there-an-event-for-audit-log-entries-being-created">
|
||
<h3><a class="toc-backref" href="#id18">Is there an event for audit log entries being created?</a><a class="headerlink" href="#is-there-an-event-for-audit-log-entries-being-created" title="Permalink to this headline">¶</a></h3>
|
||
<p>Since Discord does not dispatch this information in the gateway, the library cannot provide this information.
|
||
This is currently a Discord limitation.</p>
|
||
</section>
|
||
</section>
|
||
<section id="commands-extension">
|
||
<h2><a class="toc-backref" href="#id19">Commands Extension</a><a class="headerlink" href="#commands-extension" title="Permalink to this headline">¶</a></h2>
|
||
<p>Questions regarding <code class="docutils literal notranslate"><span class="pre">discord.ext.commands</span></code> belong here.</p>
|
||
<section id="why-does-on-message-make-my-commands-stop-working">
|
||
<h3><a class="toc-backref" href="#id20">Why does <code class="docutils literal notranslate"><span class="pre">on_message</span></code> make my commands stop working?</a><a class="headerlink" href="#why-does-on-message-make-my-commands-stop-working" title="Permalink to this headline">¶</a></h3>
|
||
<p>Overriding the default provided <code class="docutils literal notranslate"><span class="pre">on_message</span></code> forbids any extra commands from running. To fix this, add a
|
||
<code class="docutils literal notranslate"><span class="pre">bot.process_commands(message)</span></code> line at the end of your <code class="docutils literal notranslate"><span class="pre">on_message</span></code>. For example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@bot</span><span class="o">.</span><span class="n">event</span>
|
||
<span class="k">async</span> <span class="k">def</span> <span class="nf">on_message</span><span class="p">(</span><span class="n">message</span><span class="p">):</span>
|
||
<span class="c1"># do some extra stuff here</span>
|
||
|
||
<span class="k">await</span> <span class="n">bot</span><span class="o">.</span><span class="n">process_commands</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Alternatively, you can place your <code class="docutils literal notranslate"><span class="pre">on_message</span></code> logic into a <strong>listener</strong>. In this setup, you should not
|
||
manually call <code class="docutils literal notranslate"><span class="pre">bot.process_commands()</span></code>. This also allows you to do multiple things asynchronously in response
|
||
to a message. Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@bot</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="s1">'on_message'</span><span class="p">)</span>
|
||
<span class="k">async</span> <span class="k">def</span> <span class="nf">whatever_you_want_to_call_it</span><span class="p">(</span><span class="n">message</span><span class="p">):</span>
|
||
<span class="c1"># do stuff here</span>
|
||
<span class="c1"># do not process commands here</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="why-do-my-arguments-require-quotes">
|
||
<h3><a class="toc-backref" href="#id21">Why do my arguments require quotes?</a><a class="headerlink" href="#why-do-my-arguments-require-quotes" title="Permalink to this headline">¶</a></h3>
|
||
<p>In a simple command defined as:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@bot</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">echo</span><span class="p">(</span><span class="n">ctx</span><span class="p">,</span> <span class="n">message</span><span class="p">:</span> <span class="nb">str</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="n">message</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Calling it via <code class="docutils literal notranslate"><span class="pre">?echo</span> <span class="pre">a</span> <span class="pre">b</span> <span class="pre">c</span></code> will only fetch the first argument and disregard the rest. To fix this you should either call
|
||
it via <code class="docutils literal notranslate"><span class="pre">?echo</span> <span class="pre">"a</span> <span class="pre">b</span> <span class="pre">c"</span></code> or change the signature to have “consume rest” behaviour. Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@bot</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">echo</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">message</span><span class="p">:</span> <span class="nb">str</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="n">message</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This will allow you to use <code class="docutils literal notranslate"><span class="pre">?echo</span> <span class="pre">a</span> <span class="pre">b</span> <span class="pre">c</span></code> without needing the quotes.</p>
|
||
</section>
|
||
<section id="how-do-i-get-the-original-message">
|
||
<h3><a class="toc-backref" href="#id22">How do I get the original <code class="docutils literal notranslate"><span class="pre">message</span></code>?</a><a class="headerlink" href="#how-do-i-get-the-original-message" title="Permalink to this headline">¶</a></h3>
|
||
<p>The <a class="reference internal" href="ext/commands/api.html#discord.ext.commands.Context" title="discord.ext.commands.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> contains an attribute, <a class="reference internal" href="ext/commands/api.html#discord.ext.commands.Context.message" title="discord.ext.commands.Context.message"><code class="xref py py-attr docutils literal notranslate"><span class="pre">message</span></code></a> to get the original
|
||
message.</p>
|
||
<p>Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@bot</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">length</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">'Your message is </span><span class="si">{</span><span class="nb">len</span><span class="p">(</span><span class="n">ctx</span><span class="o">.</span><span class="n">message</span><span class="o">.</span><span class="n">content</span><span class="p">)</span><span class="si">}</span><span class="s1"> characters long.'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="how-do-i-make-a-subcommand">
|
||
<h3><a class="toc-backref" href="#id23">How do I make a subcommand?</a><a class="headerlink" href="#how-do-i-make-a-subcommand" title="Permalink to this headline">¶</a></h3>
|
||
<p>Use the <a class="reference internal" href="ext/commands/api.html#discord.ext.commands.group" title="discord.ext.commands.group"><code class="xref py py-func docutils literal notranslate"><span class="pre">group()</span></code></a> decorator. This will transform the callback into a <a class="reference internal" href="ext/commands/api.html#discord.ext.commands.Group" title="discord.ext.commands.Group"><code class="xref py py-class docutils literal notranslate"><span class="pre">Group</span></code></a> which will allow you to add commands into
|
||
the group operating as “subcommands”. These groups can be arbitrarily nested as well.</p>
|
||
<p>Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@bot</span><span class="o">.</span><span class="n">group</span><span class="p">()</span>
|
||
<span class="k">async</span> <span class="k">def</span> <span class="nf">git</span><span class="p">(</span><span class="n">ctx</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="n">ctx</span><span class="o">.</span><span class="n">invoked_subcommand</span> <span class="ow">is</span> <span class="kc">None</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="s1">'Invalid git command passed...'</span><span class="p">)</span>
|
||
|
||
<span class="nd">@git</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">push</span><span class="p">(</span><span class="n">ctx</span><span class="p">,</span> <span class="n">remote</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">branch</span><span class="p">:</span> <span class="nb">str</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">'Pushing to </span><span class="si">{</span><span class="n">remote</span><span class="si">}</span><span class="s1"> </span><span class="si">{</span><span class="n">branch</span><span class="si">}</span><span class="s1">'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This could then be used as <code class="docutils literal notranslate"><span class="pre">?git</span> <span class="pre">push</span> <span class="pre">origin</span> <span class="pre">master</span></code>.</p>
|
||
</section>
|
||
<section id="how-do-i-make-slash-commands">
|
||
<h3><a class="toc-backref" href="#id24">How do I make slash commands?</a><a class="headerlink" href="#how-do-i-make-slash-commands" title="Permalink to this headline">¶</a></h3>
|
||
<p>See <a class="reference internal" href="ext/commands/slash-commands.html"><span class="doc">Slash Commands</span></a></p>
|
||
</section>
|
||
<section id="my-slash-commands-aren-t-showing-up">
|
||
<h3><a class="toc-backref" href="#id25">My slash commands aren’t showing up!</a><a class="headerlink" href="#my-slash-commands-aren-t-showing-up" title="Permalink to this headline">¶</a></h3>
|
||
<p id="ext-commands-slash-command-troubleshooting">You need to invite your bot with the <code class="docutils literal notranslate"><span class="pre">application.commands</span></code> scope on each guild and
|
||
you need the <a class="reference internal" href="api.html#discord.Permissions.use_slash_commands" title="discord.Permissions.use_slash_commands"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Permissions.use_slash_commands</span></code></a> permission in order to see slash commands.</p>
|
||
<img alt="The scopes checkbox with "bot" and "applications.commands" ticked." src="images/discord_oauth2_slash_scope.png" />
|
||
<p>Global slash commands (created by not specifying <a class="reference internal" href="ext/commands/api.html#discord.ext.commands.Bot.slash_command_guilds" title="discord.ext.commands.Bot.slash_command_guilds"><code class="xref py py-attr docutils literal notranslate"><span class="pre">slash_command_guilds</span></code></a>) will also take up an
|
||
hour to refresh on discord’s end, so it is recommended to set <a class="reference internal" href="ext/commands/api.html#discord.ext.commands.Bot.slash_command_guilds" title="discord.ext.commands.Bot.slash_command_guilds"><code class="xref py py-attr docutils literal notranslate"><span class="pre">slash_command_guilds</span></code></a> for development.</p>
|
||
<p>If none of this works, make sure you are actually running enhanced-discord.py by doing <code class="docutils literal notranslate"><span class="pre">print(bot.slash_commands)</span></code></p>
|
||
</section>
|
||
<section id="my-bot-won-t-start-after-enabling-slash-commands">
|
||
<h3><a class="toc-backref" href="#id26">My bot won’t start after enabling slash commands!</a><a class="headerlink" href="#my-bot-won-t-start-after-enabling-slash-commands" title="Permalink to this headline">¶</a></h3>
|
||
<p>This means some of your command metadata is invalid for slash commands.
|
||
Make sure your command names and option names are lowercase, and they have to match the regex <code class="docutils literal notranslate"><span class="pre">^[\w-]{1,32}$</span></code></p>
|
||
<p>If you cannot figure out the problem, you should disable slash commands globally (<a class="reference internal" href="ext/commands/api.html#discord.ext.commands.Bot.slash_commands" title="discord.ext.commands.Bot.slash_commands"><code class="xref py py-attr docutils literal notranslate"><span class="pre">slash_commands</span></code></a>=False)
|
||
then go through commands, enabling them specifically with <a class="reference internal" href="ext/commands/api.html#discord.ext.commands.Command.slash_command" title="discord.ext.commands.Command.slash_command"><code class="xref py py-attr docutils literal notranslate"><span class="pre">slash_command</span></code></a>=True until it
|
||
errors, then you can debug the problem with that command specifically.</p>
|
||
</section>
|
||
</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> |