matthew/enhanced-discord.py
1
0
Fork 0
Code Issues 4 Pull Requests 21 Projects Releases Wiki Activity
enhanced-discord.py/docs/Python/html/migrating_to_async.html
Chiggy-Playz 16b7cdc488 Sort event references by categories
2021-10-03 16:18:46 +05:30

457 lines
32 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Migrating to v0.10.0</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="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="#" 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="#">Migrating to v0.10.0</a><ul>
<li><a class="reference internal" href="#event-registration">Event Registration</a></li>
<li><a class="reference internal" href="#event-changes">Event Changes</a></li>
<li><a class="reference internal" href="#coroutines">Coroutines</a></li>
<li><a class="reference internal" href="#iterables">Iterables</a></li>
<li><a class="reference internal" href="#enumerations">Enumerations</a></li>
<li><a class="reference internal" href="#properties">Properties</a></li>
<li><a class="reference internal" href="#member-management">Member Management</a></li>
<li><a class="reference internal" href="#renamed-functions">Renamed Functions</a></li>
<li><a class="reference internal" href="#forced-keyword-arguments">Forced Keyword Arguments</a></li>
<li><a class="reference internal" href="#running-the-client">Running the Client</a></li>
</ul>
</li>
</ul>
</div>
</aside>
<main class="grid-item" role="main">
<section id="migrating-to-v0-10-0">
<span id="migrating-to-async"></span><h1>Migrating to v0.10.0<a class="headerlink" href="#migrating-to-v0-10-0" title="Permalink to this headline"></a></h1>
<p>v0.10.0 is one of the biggest breaking changes in the library due to massive
fundamental changes in how the library operates.</p>
<p>The biggest major change is that the library has dropped support to all versions prior to
Python 3.4.2. This was made to support <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>, in which more detail can be seen
<a class="reference external" href="https://github.com/Rapptz/discord.py/issues/50">in the corresponding issue</a>. To reiterate this, the implication is that
<strong>python version 2.7 and 3.3 are no longer supported</strong>.</p>
<p>Below are all the other major changes from v0.9.0 to v0.10.0.</p>
<section id="event-registration">
<h2>Event Registration<a class="headerlink" href="#event-registration" title="Permalink to this headline"></a></h2>
<p>All events before were registered using <a class="reference internal" href="api.html#discord.Client.event" title="discord.Client.event"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.event()</span></code></a>. While this is still
possible, the events must be decorated with <code class="docutils literal notranslate"><span class="pre">&#64;asyncio.coroutine</span></code>.</p>
<p>Before:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@client</span><span class="o">.</span><span class="n">event</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="k">pass</span>
</pre></div>
</div>
<p>After:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@client</span><span class="o">.</span><span class="n">event</span>
<span class="nd">@asyncio</span><span class="o">.</span><span class="n">coroutine</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="k">pass</span>
</pre></div>
</div>
<p>Or in Python 3.5+:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@client</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="k">pass</span>
</pre></div>
</div>
<p>Because there is a lot of typing, a utility decorator (<code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.async_event()</span></code>) is provided
for easier registration. For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@client</span><span class="o">.</span><span class="n">async_event</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="k">pass</span>
</pre></div>
</div>
<p>Be aware however, that this is still a coroutine and your other functions that are coroutines must
be decorated with <code class="docutils literal notranslate"><span class="pre">&#64;asyncio.coroutine</span></code> or be <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code>.</p>
</section>
<section id="event-changes">
<h2>Event Changes<a class="headerlink" href="#event-changes" title="Permalink to this headline"></a></h2>
<p>Some events in v0.9.0 were considered pretty useless due to having no separate states. The main
events that were changed were the <code class="docutils literal notranslate"><span class="pre">_update</span></code> events since previously they had no context on what
was changed.</p>
<p>Before:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">on_channel_update</span><span class="p">(</span><span class="n">channel</span><span class="p">):</span> <span class="k">pass</span>
<span class="k">def</span> <span class="nf">on_member_update</span><span class="p">(</span><span class="n">member</span><span class="p">):</span> <span class="k">pass</span>
<span class="k">def</span> <span class="nf">on_status</span><span class="p">(</span><span class="n">member</span><span class="p">):</span> <span class="k">pass</span>
<span class="k">def</span> <span class="nf">on_server_role_update</span><span class="p">(</span><span class="n">role</span><span class="p">):</span> <span class="k">pass</span>
<span class="k">def</span> <span class="nf">on_voice_state_update</span><span class="p">(</span><span class="n">member</span><span class="p">):</span> <span class="k">pass</span>
<span class="k">def</span> <span class="nf">on_socket_raw_send</span><span class="p">(</span><span class="n">payload</span><span class="p">,</span> <span class="n">is_binary</span><span class="p">):</span> <span class="k">pass</span>
</pre></div>
</div>
<p>After:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">on_channel_update</span><span class="p">(</span><span class="n">before</span><span class="p">,</span> <span class="n">after</span><span class="p">):</span> <span class="k">pass</span>
<span class="k">def</span> <span class="nf">on_member_update</span><span class="p">(</span><span class="n">before</span><span class="p">,</span> <span class="n">after</span><span class="p">):</span> <span class="k">pass</span>
<span class="k">def</span> <span class="nf">on_server_role_update</span><span class="p">(</span><span class="n">before</span><span class="p">,</span> <span class="n">after</span><span class="p">):</span> <span class="k">pass</span>
<span class="k">def</span> <span class="nf">on_voice_state_update</span><span class="p">(</span><span class="n">before</span><span class="p">,</span> <span class="n">after</span><span class="p">):</span> <span class="k">pass</span>
<span class="k">def</span> <span class="nf">on_socket_raw_send</span><span class="p">(</span><span class="n">payload</span><span class="p">):</span> <span class="k">pass</span>
</pre></div>
</div>
<p>Note that <code class="docutils literal notranslate"><span class="pre">on_status</span></code> was removed. If you want its functionality, use <a class="reference internal" href="api.html#discord.on_member_update" title="discord.on_member_update"><code class="xref py py-func docutils literal notranslate"><span class="pre">on_member_update()</span></code></a>.
See <a class="reference internal" href="api.html#discord-api-events"><span class="std std-ref">Event Reference</span></a> for more information. Other removed events include <code class="docutils literal notranslate"><span class="pre">on_socket_closed</span></code>, <code class="docutils literal notranslate"><span class="pre">on_socket_receive</span></code>, and <code class="docutils literal notranslate"><span class="pre">on_socket_opened</span></code>.</p>
</section>
<section id="coroutines">
<h2>Coroutines<a class="headerlink" href="#coroutines" title="Permalink to this headline"></a></h2>
<p>The biggest change that the library went through is that almost every function in <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>
was changed to be a <a class="reference external" href="py:library/asyncio-task.html">coroutine</a>. Functions
that are marked as a coroutine in the documentation must be awaited from or yielded from in order
for the computation to be done. For example…</p>
<p>Before:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">client</span><span class="o">.</span><span class="n">send_message</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">channel</span><span class="p">,</span> <span class="s1">&#39;Hello&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>After:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">yield from</span> <span class="n">client</span><span class="o">.</span><span class="n">send_message</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">channel</span><span class="p">,</span> <span class="s1">&#39;Hello&#39;</span><span class="p">)</span>
<span class="c1"># or in python 3.5+</span>
<span class="k">await</span> <span class="n">client</span><span class="o">.</span><span class="n">send_message</span><span class="p">(</span><span class="n">message</span><span class="o">.</span><span class="n">channel</span><span class="p">,</span> <span class="s1">&#39;Hello&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>In order for you to <code class="docutils literal notranslate"><span class="pre">yield</span> <span class="pre">from</span></code> or <code class="docutils literal notranslate"><span class="pre">await</span></code> a coroutine then your function must be decorated
with <code class="docutils literal notranslate"><span class="pre">&#64;asyncio.coroutine</span></code> or <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">def</span></code>.</p>
</section>
<section id="iterables">
<h2>Iterables<a class="headerlink" href="#iterables" title="Permalink to this headline"></a></h2>
<p>For performance reasons, many of the internal data structures were changed into a dictionary to support faster
lookup. As a consequence, this meant that some lists that were exposed via the API have changed into iterables
and not sequences. In short, this means that certain attributes now only support iteration and not any of the
sequence functions.</p>
<p>The affected attributes are as follows:</p>
<ul class="simple">
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">Client.servers</span></code></p></li>
<li><p><a class="reference internal" href="api.html#discord.Client.private_channels" title="discord.Client.private_channels"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Client.private_channels</span></code></a></p></li>
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">Server.channels</span></code></p></li>
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">Server.members</span></code></p></li>
</ul>
<p>Some examples of previously valid behaviour that is now invalid</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">client</span><span class="o">.</span><span class="n">servers</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s2">&quot;test&quot;</span><span class="p">:</span>
<span class="c1"># do something</span>
</pre></div>
</div>
<p>Since they are no longer <a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.9)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">list</span></code></a>s, they no longer support indexing or any operation other than iterating.
In order to get the old behaviour you should explicitly cast it to a list.</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">servers</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">client</span><span class="o">.</span><span class="n">servers</span><span class="p">)</span>
<span class="c1"># work with servers</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Due to internal changes of the structure, the order you receive the data in
is not in a guaranteed order.</p>
</div>
</section>
<section id="enumerations">
<h2>Enumerations<a class="headerlink" href="#enumerations" title="Permalink to this headline"></a></h2>
<p>Due to dropping support for versions lower than Python 3.4.2, the library can now use
<a class="reference external" href="https://docs.python.org/3/library/enum.html" title="(in Python v3.9)"><span>enum — Support for enumerations</span></a> in places where it makes sense.</p>
<p>The common places where this was changed was in the server region, member status, and channel type.</p>
<p>Before:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">server</span><span class="o">.</span><span class="n">region</span> <span class="o">==</span> <span class="s1">&#39;us-west&#39;</span>
<span class="n">member</span><span class="o">.</span><span class="n">status</span> <span class="o">==</span> <span class="s1">&#39;online&#39;</span>
<span class="n">channel</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="s1">&#39;text&#39;</span>
</pre></div>
</div>
<p>After:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">server</span><span class="o">.</span><span class="n">region</span> <span class="o">==</span> <span class="n">discord</span><span class="o">.</span><span class="n">ServerRegion</span><span class="o">.</span><span class="n">us_west</span>
<span class="n">member</span><span class="o">.</span><span class="n">status</span> <span class="o">=</span> <span class="n">discord</span><span class="o">.</span><span class="n">Status</span><span class="o">.</span><span class="n">online</span>
<span class="n">channel</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="n">discord</span><span class="o">.</span><span class="n">ChannelType</span><span class="o">.</span><span class="n">text</span>
</pre></div>
</div>
<p>The main reason for this change was to reduce the use of finicky strings in the API as this
could give users a false sense of power. More information can be found in the <a class="reference internal" href="api.html#discord-api-enums"><span class="std std-ref">Enumerations</span></a> page.</p>
</section>
<section id="properties">
<h2>Properties<a class="headerlink" href="#properties" title="Permalink to this headline"></a></h2>
<p>A lot of function calls that returned constant values were changed into Python properties for ease of use
in format strings.</p>
<p>The following functions were changed into properties:</p>
<div class="table-wrapper"><table class="docutils align-default">
<colgroup>
<col style="width: 51%" />
<col style="width: 49%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p>Before</p></td>
<td><p>After</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">User.avatar_url()</span></code></p></td>
<td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">User.avatar_url</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">User.mention()</span></code></p></td>
<td><p><a class="reference internal" href="api.html#discord.User.mention" title="discord.User.mention"><code class="xref py py-attr docutils literal notranslate"><span class="pre">User.mention</span></code></a></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Channel.mention()</span></code></p></td>
<td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">Channel.mention</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">Channel.is_default_channel()</span></code></p></td>
<td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">Channel.is_default</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Role.is_everyone()</span></code></p></td>
<td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">Role.is_everyone</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">Server.get_default_role()</span></code></p></td>
<td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">Server.default_role</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Server.icon_url()</span></code></p></td>
<td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">Server.icon_url</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">Server.get_default_channel()</span></code></p></td>
<td><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">Server.default_channel</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Message.get_raw_mentions()</span></code></p></td>
<td><p><a class="reference internal" href="api.html#discord.Message.raw_mentions" title="discord.Message.raw_mentions"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Message.raw_mentions</span></code></a></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">Message.get_raw_channel_mentions()</span></code></p></td>
<td><p><a class="reference internal" href="api.html#discord.Message.raw_channel_mentions" title="discord.Message.raw_channel_mentions"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Message.raw_channel_mentions</span></code></a></p></td>
</tr>
</tbody>
</table>
</div></section>
<section id="member-management">
<h2>Member Management<a class="headerlink" href="#member-management" title="Permalink to this headline"></a></h2>
<p>Functions that involved banning and kicking were changed.</p>
<div class="table-wrapper"><table class="docutils align-default">
<colgroup>
<col style="width: 55%" />
<col style="width: 45%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p>Before</p></td>
<td><p>After</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Client.ban(server,</span> <span class="pre">user)</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Client.ban(member)</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">Client.kick(server,</span> <span class="pre">user)</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Client.kick(member)</span></code></p></td>
</tr>
</tbody>
</table>
</div></section>
<section id="renamed-functions">
<h2>Renamed Functions<a class="headerlink" href="#renamed-functions" title="Permalink to this headline"></a></h2>
<p>Functions have been renamed.</p>
<div class="table-wrapper"><table class="docutils align-default">
<colgroup>
<col style="width: 46%" />
<col style="width: 54%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p>Before</p></td>
<td><p>After</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Client.set_channel_permissions</span></code></p></td>
<td><p><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.edit_channel_permissions()</span></code></p></td>
</tr>
</tbody>
</table>
</div><p>All the <a class="reference internal" href="api.html#discord.Permissions" title="discord.Permissions"><code class="xref py py-class docutils literal notranslate"><span class="pre">Permissions</span></code></a> related attributes have been renamed and the <cite>can_</cite> prefix has been
dropped. So for example, <code class="docutils literal notranslate"><span class="pre">can_manage_messages</span></code> has become <code class="docutils literal notranslate"><span class="pre">manage_messages</span></code>.</p>
</section>
<section id="forced-keyword-arguments">
<h2>Forced Keyword Arguments<a class="headerlink" href="#forced-keyword-arguments" title="Permalink to this headline"></a></h2>
<p>Since 3.0+ of Python, we can now force questions to take in forced keyword arguments. A keyword argument is when you
explicitly specify the name of the variable and assign to it, for example: <code class="docutils literal notranslate"><span class="pre">foo(name='test')</span></code>. Due to this support,
some functions in the library were changed to force things to take said keyword arguments. This is to reduce errors of
knowing the argument order and the issues that could arise from them.</p>
<p>The following parameters are now exclusively keyword arguments:</p>
<ul class="simple">
<li><dl class="simple">
<dt><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.send_message()</span></code></dt><dd><ul>
<li><p><code class="docutils literal notranslate"><span class="pre">tts</span></code></p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.logs_from()</span></code></dt><dd><ul>
<li><p><code class="docutils literal notranslate"><span class="pre">before</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">after</span></code></p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.edit_channel_permissions()</span></code></dt><dd><ul>
<li><p><code class="docutils literal notranslate"><span class="pre">allow</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">deny</span></code></p></li>
</ul>
</dd>
</dl>
</li>
</ul>
<p>In the documentation you can tell if a function parameter is a forced keyword argument if it is after <code class="docutils literal notranslate"><span class="pre">\*,</span></code>
in the function signature.</p>
</section>
<section id="running-the-client">
<span id="migrating-running"></span><h2>Running the Client<a class="headerlink" href="#running-the-client" title="Permalink to this headline"></a></h2>
<p>In earlier versions of discord.py, <code class="docutils literal notranslate"><span class="pre">client.run()</span></code> was a blocking call to the main thread
that called it. In v0.10.0 it is still a blocking call but it handles the event loop for you.
However, in order to do that you must pass in your credentials to <a class="reference internal" href="api.html#discord.Client.run" title="discord.Client.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.run()</span></code></a>.</p>
<p>Basically, before:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">client</span><span class="o">.</span><span class="n">login</span><span class="p">(</span><span class="s1">&#39;token&#39;</span><span class="p">)</span>
<span class="n">client</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
</pre></div>
</div>
<p>After:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">client</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s1">&#39;token&#39;</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Like in the older <code class="docutils literal notranslate"><span class="pre">Client.run</span></code> function, the newer one must be the one of
the last functions to call. This is because the function is <strong>blocking</strong>. Registering
events or doing anything after <a class="reference internal" href="api.html#discord.Client.run" title="discord.Client.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Client.run()</span></code></a> will not execute until the function
returns.</p>
</div>
<p>This is a utility function that abstracts the event loop for you. There’s no need for
the run call to be blocking and out of your control. Indeed, if you want control of the
event loop then doing so is quite straightforward:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">discord</span>
<span class="kn">import</span> <span class="nn">asyncio</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="nd">@asyncio</span><span class="o">.</span><span class="n">coroutine</span>
<span class="k">def</span> <span class="nf">main_task</span><span class="p">():</span>
<span class="k">yield from</span> <span class="n">client</span><span class="o">.</span><span class="n">login</span><span class="p">(</span><span class="s1">&#39;token&#39;</span><span class="p">)</span>
<span class="k">yield from</span> <span class="n">client</span><span class="o">.</span><span class="n">connect</span><span class="p">()</span>
<span class="n">loop</span> <span class="o">=</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">get_event_loop</span><span class="p">()</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">loop</span><span class="o">.</span><span class="n">run_until_complete</span><span class="p">(</span><span class="n">main_task</span><span class="p">())</span>
<span class="k">except</span><span class="p">:</span>
<span class="n">loop</span><span class="o">.</span><span class="n">run_until_complete</span><span class="p">(</span><span class="n">client</span><span class="o">.</span><span class="n">logout</span><span class="p">())</span>
<span class="k">finally</span><span class="p">:</span>
<span class="n">loop</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
</section>
</section>
</main>
<footer class="grid-item">
&#169; 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>
Reference in New Issue View Git Blame Copy Permalink