Bump version to 3.0.2

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

.github/CODEOWNERS

@@ -25,6 +25,7 @@ redbot/core/utils/data_converter.py      @mikeshardmind
 redbot/core/utils/antispam.py            @mikeshardmind
 redbot/core/utils/tunnel.py              @mikeshardmind
 redbot/core/utils/caching.py             @mikeshardmind
+redbot/core/utils/common_filters.py      @mikeshardmind
 
 # Cogs
 redbot/cogs/admin/*                 @tekulvw

.github/CONTRIBUTING.md

@@ -53,7 +53,7 @@ Red's repository is configured to follow a particular development workflow, usin
 
 ### 4.1 Setting up your development environment
 The following requirements must be installed prior to setting up:
- - Python 3.6
+ - Python 3.6.2 or greater (3.6.6 or greater on Windows)
  - git
  - pip
  - pipenv
@@ -79,7 +79,7 @@ Note: If you haven't used `pipenv` before but are comfortable with virtualenvs,
 We've recently started using [tox](https://github.com/tox-dev/tox) to run all of our tests. It's extremely simple to use, and if you followed the previous section correctly, it is already installed to your virtual environment.
 
 Currently, tox does the following, creating its own virtual environments for each stage:
-- Runs all of our unit tests with [pytest](https://github.com/pytest-dev/pytest) on python 3.6 (test environment `py36`)
+- Runs all of our unit tests with [pytest](https://github.com/pytest-dev/pytest) on python 3.6 and 3.7 (test environments `py36` and `py37`)
 - Ensures documentation builds without warnings, and all hyperlinks have a valid destination (test environment `docs`)
 - Ensures that the code meets our style guide with [black](https://github.com/ambv/black) (test environment `style`)
 
@@ -92,7 +92,7 @@ Your PR will not be merged until all of these tests pass.
 ### 4.3 Style
 Our style checker of choice, [black](https://github.com/ambv/black), actually happens to be an auto-formatter. The checking functionality simply detects whether or not it would try to reformat something in your code, should you run the formatter on it. For this reason, we recommend using this tool as a formatter, regardless of any disagreements you might have with the style it enforces.
 
-Use the command `black --help` to see how to use this tool. The full style guide is explained in detail on [black's GitHub repository](https://github.com/ambv/black). **There is one exception to this**, however, which is that we set the line length to 99, instead of black's default 88. When using `black` on the command line, simply use it like so: `black -l 99 <src>`.
+Use the command `black --help` to see how to use this tool. The full style guide is explained in detail on [black's GitHub repository](https://github.com/ambv/black). **There is one exception to this**, however, which is that we set the line length to 99, instead of black's default 88. When using `black` on the command line, simply use it like so: `black -l 99 -N <src>`.
 
 ### 4.4 Make
 You may have noticed we have a `Makefile` and a `make.bat` in the top-level directory. For now, you can do two things with them:

.gitignore

@@ -1,6 +1,7 @@
 *.json
 *.exe
 *.dll
+*.pot
 .data
 !/tests/cogs/dataconverter/data/**/*.json
 

.readthedocs.yml

@@ -4,10 +4,9 @@ formats:
 build:
   image: latest
 
-requirements_file: docs/requirements.txt
-
 python:
   version: 3.6
   pip_install: true
   extra_requirements:
+    - docs
     - mongo

.travis.yml

@@ -1,35 +1,40 @@
-dist: trusty
+dist: xenial
 language: python
 cache: pip
 notifications:
   email: false
+sudo: true
 
 python:
-- 3.6.5
+- 3.6.6
+- 3.7
 env:
   global:
     PIPENV_IGNORE_VIRTUALENVS=1
   matrix:
-    - TOXENV=py
-    - TOXENV=docs
-    - TOXENV=style
+    TOXENV=py
 
 install:
-- pip install --upgrade pip pipenv
-- pipenv install --dev
+- pip install --upgrade pip tox
 
 script:
-- pipenv run tox
+- tox
 
 jobs:
   include:
 
-    # These jobs only occur on tag creation for V3/develop if the prior ones succeed
+    - python: 3.6.6
+      env: TOXENV=docs
+    - python: 3.6.6
+      env: TOXENV=style
+
+    # These jobs only occur on tag creation if the prior ones succeed
     - stage: PyPi Deployment
       if: tag IS present
-      python: 3.6.5
+      python: 3.6.6
       env:
         - DEPLOYING=true
+        - TOXENV=py36
       deploy:
         - provider: pypi
           user: Red-DiscordBot
@@ -38,25 +43,25 @@ jobs:
           skip_cleanup: true
           on:
             repo: Cog-Creators/Red-DiscordBot
-            branch: V3/develop
-            python: 3.6.5
+            python: 3.6.6
             tags: true
     - stage: Crowdin Deployment
       if: tag IS present
-      python: 3.6.5
+      python: 3.6.6
       env:
         - DEPLOYING=true
+        - TOXENV=py36
       before_deploy:
       - curl https://artifacts.crowdin.com/repo/GPG-KEY-crowdin | sudo apt-key add -
       - echo "deb https://artifacts.crowdin.com/repo/deb/ /" | sudo tee -a /etc/apt/sources.list
       - sudo apt-get update -qq
       - sudo apt-get install -y crowdin
+      - pip install redgettext==2.2
       deploy:
       - provider: script
-        script: python3 ./generate_strings.py
+        script: make gettext
         skip_cleanup: true
         on:
           repo: Cog-Creators/Red-DiscordBot
-          branch: V3/develop
-          python: 3.6.5
+          python: 3.6.6
           tags: true

LICENSE

@@ -632,7 +632,7 @@ state the exclusion of warranty; and each file should have at least
 the "copyright" line and a pointer to where the full notice is found.
 
     Red - A fully customizable Discord bot
-    Copyright (C) 2015-2018  Twentysix
+    Copyright (C) 2015-2019  Twentysix
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -652,7 +652,7 @@ Also add information on how to contact you by electronic and paper mail.
   If the program does terminal interaction, make it output a short
 notice like this when it starts in an interactive mode:
 
-    Red-DiscordBot  Copyright (C) 2015-2018  Twentysix
+    Red-DiscordBot  Copyright (C) 2015-2019  Twentysix
     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

MANIFEST.in

@@ -1,5 +0,0 @@
-include README.rst
-include LICENSE
-include requirements.txt
-include discord/bin/*.dll
-include redbot/cogs/audio/application.yml

Makefile

@@ -1,4 +1,13 @@
 reformat:
-	black -l 99 `git ls-files "*.py"`
+	black -l 99 -N `git ls-files "*.py"`
 stylecheck:
-	black --check -l 99 `git ls-files "*.py"`
+	black --check -l 99 -N `git ls-files "*.py"`
+gettext:
+	redgettext --command-docstrings --verbose --recursive redbot --exclude-files "redbot/pytest/**/*"
+	crowdin upload
+
+REF?=rewrite
+update_vendor:
+	pip install --upgrade --no-deps -t . https://github.com/Rapptz/discord.py/archive/$(REF).tar.gz#egg=discord.py
+	rm -r discord.py*-info
+	$(MAKE) reformat

Pipfile

@@ -4,17 +4,8 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
-"discord.py" = { git = 'git://github.com/Rapptz/discord.py', ref = '7eb918b19e3e60b56eb9039eb267f8f3477c5e17', editable = true}
-"e1839a8" = {path = ".", editable = true}
+red-discordbot = {path = ".",editable = true,extras = ['mongo', 'voice']}
 
 [dev-packages]
 tox = "*"
-pytest = "*"
-pytest-asyncio = "*"
-sphinx = ">1.7"
-sphinxcontrib-asyncio = "*"
-sphinx-rtd-theme = "*"
-black = "*"
-
-[pipenv]
-allow_prereleases = true
+red-discordbot = {path = ".",editable = true,extras = ['docs', 'test', 'style']}

README.md

@@ -0,0 +1,140 @@
+<h1 align="center">
+  <br>
+  <a href="https://github.com/Cog-Creators/Red-DiscordBot/tree/V3/develop"><img src="https://imgur.com/pY1WUFX.png" alt="Red - Discord Bot"></a>
+  <br>
+  Red Discord Bot
+  <br>
+</h1>
+
+<h4 align="center">Music, Moderation, Trivia, Stream Alerts and Fully Modular.</h4>
+
+<p align="center">
+  <a href="https://discord.gg/red">
+    <img src="https://discordapp.com/api/guilds/133049272517001216/widget.png?style=shield" alt="Discord Server">
+  </a>
+  <a href="https://www.patreon.com/Red_Devs">
+    <img src="https://img.shields.io/badge/Support-Red!-yellow.svg" alt="Support Red on Patreon!">
+  </a>
+  <a href="https://www.python.org/downloads/">
+    <img src="https://img.shields.io/badge/Made%20With-Python%203-blue.svg?style=for-the-badge" alt="Made with Python 3">
+  </a>
+  <a href="https://crowdin.com/project/red-discordbot">
+    <img src="https://d322cqt584bo4o.cloudfront.net/red-discordbot/localized.svg" alt="Localized with Crowdin">
+  </a>
+  <a href="https://github.com/Rapptz/discord.py/tree/rewrite">
+      <img src="https://img.shields.io/badge/discord-py-blue.svg" alt="discord.py">
+  </a>
+</p>
+<p align="center">
+  <a href="https://travis-ci.org/Cog-Creators/Red-DiscordBot">
+    <img src="https://api.travis-ci.org/Cog-Creators/Red-DiscordBot.svg?branch=V3/develop" alt="Travis CI">
+  </a>
+  <a href="http://red-discordbot.readthedocs.io/en/v3-develop/?badge=v3-develop">
+    <img src="https://readthedocs.org/projects/red-discordbot/badge/?version=v3-develop" alt="Red on readthedocs.org">
+  </a>
+  <a href="https://github.com/ambv/black">
+    <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code Style: Black">
+  </a>
+  <a href="http://makeapullrequest.com">
+    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg">
+  </a>
+</p>
+
+<p align="center">
+  <a href="#overview">Overview</a>
+  •
+  <a href="#installation">Installation</a>
+  •
+  <a href="http://red-discordbot.readthedocs.io/en/v3-develop/index.html">Documentation</a>
+  •
+  <a href="#plugins">Plugins</a>
+  •
+  <a href="#join-the-community">Community</a>
+  •
+  <a href="#license">License</a>
+</p>
+
+# Overview
+
+Red is a fully modular bot – meaning all features and commands can be enabled/disabled to your
+liking, making it completely customizable. This is also a *self-hosted bot* – meaning you will need
+to host and maintain your own instance. You can turn Red into an admin bot, music bot, trivia bot,
+new best friend or all of these together!  
+
+[Installation](#installation) is easy, and you do **NOT** need to know anything about coding! Aside
+from installation and updating, every part of the bot can be controlled from within Discord.
+
+**The default set of modules includes and is not limited to:**
+
+- Moderation features (kick/ban/softban/hackban, mod-log, filter, chat cleanup)
+- Trivia (lists are included and can be easily added)
+- Music features (YouTube, SoundCloud, local files, playlists, queues)
+- Stream alerts (Twitch, Youtube, Mixer, Hitbox, Picarto)
+- Bank (slot machine, user credits)
+- Custom commands
+- Imgur/gif search
+- Admin automation (self-role assignment, cross-server announcements, mod-mail reports)
+- Customisable command permissions
+
+**Additionally, other [plugins](#plugins) (cogs) can be easily found and added from our growing
+community of cog repositories.**
+
+# Installation
+
+**The following platforms are officially supported:** 
+
+- [Windows](https://red-discordbot.readthedocs.io/en/v3-develop/install_windows.html)
+- [MacOS](https://red-discordbot.readthedocs.io/en/v3-develop/install_linux_mac.html)
+- [Ubuntu](https://red-discordbot.readthedocs.io/en/v3-develop/install_linux_mac.html)
+- [Debian Stretch](https://red-discordbot.readthedocs.io/en/v3-develop/install_linux_mac.html)
+- [CentOS 7](https://red-discordbot.readthedocs.io/en/v3-develop/install_linux_mac.html)
+- [Arch Linux](https://red-discordbot.readthedocs.io/en/v3-develop/install_linux_mac.html)
+- [Raspbian Stretch](https://red-discordbot.readthedocs.io/en/v3-develop/install_linux_mac.html)
+
+Already using **Red** V2? Take a look at the [Data Converter](https://red-discordbot.readthedocs.io/en/v3-develop/cog_dataconverter.html)
+to import your data to V3.
+
+If after reading the guide you are still experiencing issues, feel free to join the
+[Official Discord Server](https://discord.gg/red) and ask in the **#v3-support** channel for help.
+
+# Plugins
+
+Red is fully modular, allowing you to load and unload plugins of your choice, and install 3rd party
+plugins directly from Discord! A few examples are:
+
+- Cleverbot integration (talk to Red and she talks back)
+- Ban sync
+- Welcome messages
+- Casino
+- Reaction roles
+- Slow Mode
+- Anilist
+- And much, much more!
+
+Feel free to take a [peek](https://github.com/Cog-Creators/Red-DiscordBot/issues/1398) at a list of
+available 3rd party cogs!
+
+# Join the community!
+
+**Red** is in continuous development, and it’s supported by an active community which produces new
+content (cogs/plugins) for everyone to enjoy. New features are constantly added. If you can’t
+[find](https://github.com/Cog-Creators/Red-DiscordBot/issues/1398) the cog you’re looking for,
+consult our [guide](https://red-discordbot.readthedocs.io/en/v3-develop/guide_cog_creation.html) on
+building your own cogs!
+
+Join us on our [Official Discord Server](https://discord.gg/red)!
+
+# License
+
+Released under the [GNU GPL v3](https://www.gnu.org/licenses/gpl-3.0.en.html) license.
+
+This project vendors the
+[discord.py library by Rapptz](https://github.com/Rapptz/discord.py/tree/rewrite), which is
+licensed under the [MIT License](https://opensource.org/licenses/MIT). This amounts to everything
+within the *discord* folder of this repository.
+
+Red is named after the main character of "Transistor", a video game by
+[Super Giant Games](https://www.supergiantgames.com/games/transistor/).
+
+Artwork created by [Sinlaire](https://sinlaire.deviantart.com/) on Deviant Art for the Red Discord
+Bot Project.

README.rst

@@ -1,113 +0,0 @@
-.. class:: center
-
-  .. image:: https://imgur.com/pY1WUFX.png
-    :target: https://github.com/Cog-Creators/Red-DiscordBot/tree/V3/develop
-    :alt: Red Discord Bot
-  
-  
-.. class:: center
-  
-  Music, Moderation, Trivia, Stream Alerts and fully customizable.
-
-.. class:: center
-
-  .. image:: https://discordapp.com/api/guilds/133049272517001216/embed.png
-    :target: https://discord.gg/red
-    :alt: Discord server
-    
-  .. image:: https://api.travis-ci.org/Cog-Creators/Red-DiscordBot.svg?branch=V3/develop
-    :target: https://travis-ci.org/Cog-Creators/Red-DiscordBot
-    :alt: Travis CI status
-
-  .. image:: https://readthedocs.org/projects/red-discordbot/badge/?version=v3-develop
-    :target: http://red-discordbot.readthedocs.io/en/v3-develop/?badge=v3-develop
-    :alt: Documentation Status
-    
-  .. image:: https://img.shields.io/badge/discord-py-blue.svg
-    :target: https://github.com/Rapptz/discord.py
-    :alt: discord.py
-
-  .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-    :target: https://github.com/ambv/black
-    :alt: Code style: black
-
-  .. image:: https://d322cqt584bo4o.cloudfront.net/red-discordbot/localized.svg
-    :target: https://crowdin.com/project/red-discordbot
-    :alt: Crowdin
-
-  .. image:: https://img.shields.io/badge/Support-Red!-orange.svg
-    :target: https://www.patreon.com/Red_Devs
-    :alt: Patreon
-    
-  .. image:: https://img.shields.io/badge/PRs-welcome-brightgreen.svg
-    :target: http://makeapullrequest.com
-    :alt: PRs open
-
-==========
-Overview
-==========
-
-Red is a fully modular bot – meaning all features and commands can be enabled/disabled to your liking, making it completely customizable.  
-This is also a *self-hosted bot* – meaning you will need to host and maintain your own instance. You can turn Red into an admin bot, music bot, trivia bot, new best friend or all of these together!  
-
-`Installation <#installation>`_ is easy, and you do **NOT** need to know anything about coding! Aside from installation and updating, every part of the bot can be controlled from within Discord.
-
-**The default set of modules includes and is not limited to:**
-
-- Moderation features (kick/ban/softban/hackban, mod-log, filter, chat cleanup)
-- Trivia (lists are included and can be easily added)
-- Music features (YouTube, SoundCloud, local files, playlists, queues)
-- Stream alerts (Twitch, Youtube, Mixer, Hitbox, Picarto)
-- Slot machine
-- Custom commands
-- Imgur/gif search
-
-
-**Additionally, other plugins (cogs) can be easily found and added from our growing community of cog repositories.**
-
-- Cleverbot integration (talk to Red and she talks back)
-- Ban sync
-- Welcome messages
-- Casino
-- Reaction roles
-- Slow Mode
-- Anilist
-- And much, much more!
-
-Feel free to take a `peek <https://github.com/Cog-Creators/Red-DiscordBot/issues/1398>`_!
-
-==============
-Installation
-==============
-
-**The following platforms are officially supported:** 
-
-- `Windows <https://red-discordbot.readthedocs.io/en/v3-develop/install_windows.html>`_
-- `MacOS <https://red-discordbot.readthedocs.io/en/v3-develop/install_mac.html>`_
-- `Ubuntu <https://red-discordbot.readthedocs.io/en/v3-develop/install_ubuntu.html>`_
-- `Debian Stretch <https://red-discordbot.readthedocs.io/en/v3-develop/install_debian.html>`_
-- `CentOS 7 <https://red-discordbot.readthedocs.io/en/v3-develop/install_centos.html>`_
-- `Arch Linux <https://red-discordbot.readthedocs.io/en/v3-develop/install_arch.html>`_
-- `Raspbian Stretch <https://red-discordbot.readthedocs.io/en/v3-develop/install_raspbian.html>`_
-
-Already using **Red** V2? Take a look at the `Data Converter <https://red-discordbot.readthedocs.io/en/v3-develop/cog_dataconverter.html>`_ to import your data to V3.
-
-If `after reading the guides <https://red-discordbot.readthedocs.io/en/v3-develop/>`_ you are still experiencing issues, feel free to join the `Official Server <https://discord.gg/red>`_ and ask in the **#support** channel for help. 
-
-=====================
-Join the community!
-=====================
-
-**Red** is in continuous development, and it’s supported by an active community which produces new content (cogs/plugins) for everyone to enjoy. New features are constantly added. If you can’t `find <https://github.com/Cog-Creators/Red-DiscordBot/issues/1398>`_ what you’re looking for, consult our `guide <https://red-discordbot.readthedocs.io/en/v3-develop/guide_cog_creation.html>`_ on building your own cogs! 
-
-Join us on our `Official Discord Server <https://discord.gg/red>`_!
-
-=========
-License
-=========
-
-Released under the `GNU GPL v3 <#License>`_.
-
-Red is named after the main character of "Transistor", a videogame by `Super Giant Games <https://www.supergiantgames.com/games/transistor/>`_
-
-Artwork created by `Sinlaire <https://sinlaire.deviantart.com/>`_ on Deviant Art for the Red Bot Project.

crowdin.yml

@@ -1,5 +1,5 @@
 api_key_env: CROWDIN_API_KEY
 project_identifier_env: CROWDIN_PROJECT_ID
 files:
-  - source: /**/*.pot
+  - source: /redbot/**/*.pot
     translation: /%original_path%/%locale%.po

discord/__init__.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+
+"""
+Discord API Wrapper
+~~~~~~~~~~~~~~~~~~~
+
+A basic wrapper for the Discord API.
+
+:copyright: (c) 2015-2019 Rapptz
+:license: MIT, see LICENSE for more details.
+
+"""
+
+__title__ = "discord"
+__author__ = "Rapptz"
+__license__ = "MIT"
+__copyright__ = "Copyright 2015-2019 Rapptz"
+__version__ = "1.0.0a"
+
+from collections import namedtuple
+import logging
+
+from .client import Client, AppInfo
+from .user import User, ClientUser, Profile
+from .emoji import Emoji, PartialEmoji
+from .activity import *
+from .channel import *
+from .guild import Guild
+from .relationship import Relationship
+from .member import Member, VoiceState
+from .message import Message, Attachment
+from .errors import *
+from .calls import CallMessage, GroupCall
+from .permissions import Permissions, PermissionOverwrite
+from .role import Role
+from .file import File
+from .colour import Color, Colour
+from .invite import Invite
+from .object import Object
+from .reaction import Reaction
+from . import utils, opus, abc
+from .enums import *
+from .embeds import Embed
+from .shard import AutoShardedClient
+from .player import *
+from .webhook import *
+from .voice_client import VoiceClient
+from .audit_logs import AuditLogChanges, AuditLogEntry, AuditLogDiff
+from .raw_models import *
+
+VersionInfo = namedtuple("VersionInfo", "major minor micro releaselevel serial")
+
+version_info = VersionInfo(major=1, minor=0, micro=0, releaselevel="alpha", serial=0)
+
+try:
+    from logging import NullHandler
+except ImportError:
+
+    class NullHandler(logging.Handler):
+        def emit(self, record):
+            pass
+
+
+logging.getLogger(__name__).addHandler(NullHandler())

discord/__main__.py

@@ -0,0 +1,337 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+import discord
+
+
+def core(parser, args):
+    pass
+
+
+bot_template = """#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from discord.ext import commands
+import discord
+import config
+
+class Bot(commands.{base}):
+    def __init__(self, **kwargs):
+        super().__init__(command_prefix=commands.when_mentioned_or('{prefix}'), **kwargs)
+        for cog in config.cogs:
+            try:
+                self.load_extension(cog)
+            except Exception as exc:
+                print('Could not load extension {{0}} due to {{1.__class__.__name__}}: {{1}}'.format(cog, exc))
+
+    async def on_ready(self):
+        print('Logged on as {{0}} (ID: {{0.id}})'.format(self.user))
+
+
+bot = Bot()
+
+# write general commands here
+
+bot.run(config.token)
+"""
+
+gitignore_template = """# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Our configuration files
+config.py
+"""
+
+cog_template = '''# -*- coding: utf-8 -*-
+
+from discord.ext import commands
+import discord
+
+class {name}:
+    """The description for {name} goes here."""
+
+    def __init__(self, bot):
+        self.bot = bot
+{extra}
+def setup(bot):
+    bot.add_cog({name}(bot))
+'''
+
+cog_extras = """
+    def __unload(self):
+        # clean up logic goes here
+        pass
+
+    async def __local_check(self, ctx):
+        # checks that apply to every command in here
+        return True
+
+    async def __global_check(self, ctx):
+        # checks that apply to every command to the bot
+        return True
+
+    async def __global_check_once(self, ctx):
+        # check that apply to every command but is guaranteed to be called only once
+        return True
+
+    async def __error(self, ctx, error):
+        # error handling to every command in here
+        pass
+
+    async def __before_invoke(self, ctx):
+        # called before a command is called here
+        pass
+
+    async def __after_invoke(self, ctx):
+        # called after a command is called here
+        pass
+
+"""
+
+
+# certain file names and directory names are forbidden
+# see: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247%28v=vs.85%29.aspx
+# although some of this doesn't apply to Linux, we might as well be consistent
+_base_table = {
+    "<": "-",
+    ">": "-",
+    ":": "-",
+    '"': "-",
+    # '/': '-', these are fine
+    # '\\': '-',
+    "|": "-",
+    "?": "-",
+    "*": "-",
+}
+
+#
+_base_table.update((chr(i), None) for i in range(32))
+
+translation_table = str.maketrans(_base_table)
+
+
+def to_path(parser, name, *, replace_spaces=False):
+    if isinstance(name, Path):
+        return name
+
+    if sys.platform == "win32":
+        forbidden = (
+            "CON",
+            "PRN",
+            "AUX",
+            "NUL",
+            "COM1",
+            "COM2",
+            "COM3",
+            "COM4",
+            "COM5",
+            "COM6",
+            "COM7",
+            "COM8",
+            "COM9",
+            "LPT1",
+            "LPT2",
+            "LPT3",
+            "LPT4",
+            "LPT5",
+            "LPT6",
+            "LPT7",
+            "LPT8",
+            "LPT9",
+        )
+        if len(name) <= 4 and name.upper() in forbidden:
+            parser.error("invalid directory name given, use a different one")
+
+    name = name.translate(translation_table)
+    if replace_spaces:
+        name = name.replace(" ", "-")
+    return Path(name)
+
+
+def newbot(parser, args):
+    if sys.version_info < (3, 5):
+        parser.error("python version is older than 3.5, consider upgrading.")
+
+    new_directory = to_path(parser, args.directory) / to_path(parser, args.name)
+
+    # as a note exist_ok for Path is a 3.5+ only feature
+    # since we already checked above that we're >3.5
+    try:
+        new_directory.mkdir(exist_ok=True, parents=True)
+    except OSError as exc:
+        parser.error("could not create our bot directory ({})".format(exc))
+
+    cogs = new_directory / "cogs"
+
+    try:
+        cogs.mkdir(exist_ok=True)
+        init = cogs / "__init__.py"
+        init.touch()
+    except OSError as exc:
+        print("warning: could not create cogs directory ({})".format(exc))
+
+    try:
+        with open(str(new_directory / "config.py"), "w", encoding="utf-8") as fp:
+            fp.write('token = "place your token here"\ncogs = []\n')
+    except OSError as exc:
+        parser.error("could not create config file ({})".format(exc))
+
+    try:
+        with open(str(new_directory / "bot.py"), "w", encoding="utf-8") as fp:
+            base = "Bot" if not args.sharded else "AutoShardedBot"
+            fp.write(bot_template.format(base=base, prefix=args.prefix))
+    except OSError as exc:
+        parser.error("could not create bot file ({})".format(exc))
+
+    if not args.no_git:
+        try:
+            with open(str(new_directory / ".gitignore"), "w", encoding="utf-8") as fp:
+                fp.write(gitignore_template)
+        except OSError as exc:
+            print("warning: could not create .gitignore file ({})".format(exc))
+
+    print("successfully made bot at", new_directory)
+
+
+def newcog(parser, args):
+    if sys.version_info < (3, 5):
+        parser.error("python version is older than 3.5, consider upgrading.")
+
+    cog_dir = to_path(parser, args.directory)
+    try:
+        cog_dir.mkdir(exist_ok=True)
+    except OSError as exc:
+        print("warning: could not create cogs directory ({})".format(exc))
+
+    directory = cog_dir / to_path(parser, args.name)
+    directory = directory.with_suffix(".py")
+    try:
+        with open(str(directory), "w", encoding="utf-8") as fp:
+            extra = cog_extras if args.full else ""
+            if args.class_name:
+                name = args.class_name
+            else:
+                name = str(directory.stem)
+                if "-" in name:
+                    name = name.replace("-", " ").title().replace(" ", "")
+                else:
+                    name = name.title()
+            fp.write(cog_template.format(name=name, extra=extra))
+    except OSError as exc:
+        parser.error("could not create cog file ({})".format(exc))
+    else:
+        print("successfully made cog at", directory)
+
+
+def add_newbot_args(subparser):
+    parser = subparser.add_parser("newbot", help="creates a command bot project quickly")
+    parser.set_defaults(func=newbot)
+
+    parser.add_argument("name", help="the bot project name")
+    parser.add_argument(
+        "directory",
+        help="the directory to place it in (default: .)",
+        nargs="?",
+        default=Path.cwd(),
+    )
+    parser.add_argument(
+        "--prefix", help="the bot prefix (default: $)", default="$", metavar="<prefix>"
+    )
+    parser.add_argument("--sharded", help="whether to use AutoShardedBot", action="store_true")
+    parser.add_argument(
+        "--no-git", help="do not create a .gitignore file", action="store_true", dest="no_git"
+    )
+
+
+def add_newcog_args(subparser):
+    parser = subparser.add_parser("newcog", help="creates a new cog template quickly")
+    parser.set_defaults(func=newcog)
+
+    parser.add_argument("name", help="the cog name")
+    parser.add_argument(
+        "directory",
+        help="the directory to place it in (default: cogs)",
+        nargs="?",
+        default=Path("cogs"),
+    )
+    parser.add_argument(
+        "--class-name", help="the class name of the cog (default: <name>)", dest="class_name"
+    )
+    parser.add_argument("--full", help="add all special methods as well", action="store_true")
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        prog="discord", description="Tools for helping with discord.py"
+    )
+
+    version = "discord.py v{0.__version__} for Python {1[0]}.{1[1]}.{1[2]}".format(
+        discord, sys.version_info
+    )
+    parser.add_argument(
+        "-v", "--version", action="version", version=version, help="shows the library version"
+    )
+    parser.set_defaults(func=core)
+
+    subparser = parser.add_subparsers(dest="subcommand", title="subcommands")
+    add_newbot_args(subparser)
+    add_newcog_args(subparser)
+    return parser, parser.parse_args()
+
+
+def main():
+    parser, args = parse_args()
+    args.func(parser, args)
+
+
+main()

discord/activity.py

@@ -0,0 +1,613 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import datetime
+
+from .enums import ActivityType, try_enum
+from .colour import Colour
+
+__all__ = ["Activity", "Streaming", "Game", "Spotify"]
+
+"""If curious, this is the current schema for an activity.
+
+It's fairly long so I will document it here:
+
+All keys are optional.
+
+state: str (max: 128),
+details: str (max: 128)
+timestamps: dict
+    start: int (min: 1)
+    end: int (min: 1)
+assets: dict
+    large_image: str (max: 32)
+    large_text: str (max: 128)
+    small_image: str (max: 32)
+    small_text: str (max: 128)
+party: dict
+    id: str (max: 128),
+    size: List[int] (max-length: 2)
+        elem: int (min: 1)
+secrets: dict
+    match: str (max: 128)
+    join: str (max: 128)
+    spectate: str (max: 128)
+instance: bool
+application_id: str
+name: str (max: 128)
+url: str
+type: int
+sync_id: str
+session_id: str
+flags: int
+
+There are also activity flags which are mostly uninteresting for the library atm.
+
+t.ActivityFlags = {
+    INSTANCE: 1,
+    JOIN: 2,
+    SPECTATE: 4,
+    JOIN_REQUEST: 8,
+    SYNC: 16,
+    PLAY: 32
+}
+"""
+
+
+class _ActivityTag:
+    __slots__ = ()
+
+
+class Activity(_ActivityTag):
+    """Represents an activity in Discord.
+
+    This could be an activity such as streaming, playing, listening
+    or watching.
+
+    For memory optimisation purposes, some activities are offered in slimmed
+    down versions:
+
+    - :class:`Game`
+    - :class:`Streaming`
+
+    Attributes
+    ------------
+    application_id: :class:`str`
+        The application ID of the game.
+    name: :class:`str`
+        The name of the activity.
+    url: :class:`str`
+        A stream URL that the activity could be doing.
+    type: :class:`ActivityType`
+        The type of activity currently being done.
+    state: :class:`str`
+        The user's current state. For example, "In Game".
+    details: :class:`str`
+        The detail of the user's current activity.
+    timestamps: :class:`dict`
+        A dictionary of timestamps. It contains the following optional keys:
+
+        - ``start``: Corresponds to when the user started doing the
+          activity in milliseconds since Unix epoch.
+        - ``end``: Corresponds to when the user will finish doing the
+          activity in milliseconds since Unix epoch.
+
+    assets: :class:`dict`
+        A dictionary representing the images and their hover text of an activity.
+        It contains the following optional keys:
+
+        - ``large_image``: A string representing the ID for the large image asset.
+        - ``large_text``: A string representing the text when hovering over the large image asset.
+        - ``small_image``: A string representing the ID for the small image asset.
+        - ``small_text``: A string representing the text when hovering over the small image asset.
+
+    party: :class:`dict`
+        A dictionary representing the activity party. It contains the following optional keys:
+
+        - ``id``: A string representing the party ID.
+        - ``size``: A list of up to two integer elements denoting (current_size, maximum_size).
+    """
+
+    __slots__ = (
+        "state",
+        "details",
+        "timestamps",
+        "assets",
+        "party",
+        "flags",
+        "sync_id",
+        "session_id",
+        "type",
+        "name",
+        "url",
+        "application_id",
+    )
+
+    def __init__(self, **kwargs):
+        self.state = kwargs.pop("state", None)
+        self.details = kwargs.pop("details", None)
+        self.timestamps = kwargs.pop("timestamps", {})
+        self.assets = kwargs.pop("assets", {})
+        self.party = kwargs.pop("party", {})
+        self.application_id = kwargs.pop("application_id", None)
+        self.name = kwargs.pop("name", None)
+        self.url = kwargs.pop("url", None)
+        self.flags = kwargs.pop("flags", 0)
+        self.sync_id = kwargs.pop("sync_id", None)
+        self.session_id = kwargs.pop("session_id", None)
+        self.type = try_enum(ActivityType, kwargs.pop("type", -1))
+
+    def to_dict(self):
+        ret = {}
+        for attr in self.__slots__:
+            value = getattr(self, attr, None)
+            if value is None:
+                continue
+
+            if isinstance(value, dict) and len(value) == 0:
+                continue
+
+            ret[attr] = value
+        ret["type"] = int(self.type)
+        return ret
+
+    @property
+    def start(self):
+        """Optional[:class:`datetime.datetime`]: When the user started doing this activity in UTC, if applicable."""
+        try:
+            return datetime.datetime.utcfromtimestamp(self.timestamps["start"] / 1000)
+        except KeyError:
+            return None
+
+    @property
+    def end(self):
+        """Optional[:class:`datetime.datetime`]: When the user will stop doing this activity in UTC, if applicable."""
+        try:
+            return datetime.datetime.utcfromtimestamp(self.timestamps["end"] / 1000)
+        except KeyError:
+            return None
+
+    @property
+    def large_image_url(self):
+        """Optional[:class:`str`]: Returns a URL pointing to the large image asset of this activity if applicable."""
+        if self.application_id is None:
+            return None
+
+        try:
+            large_image = self.assets["large_image"]
+        except KeyError:
+            return None
+        else:
+            return "https://cdn.discordapp.com/app-assets/{0}/{1}.png".format(
+                self.application_id, large_image
+            )
+
+    @property
+    def small_image_url(self):
+        """Optional[:class:`str`]: Returns a URL pointing to the small image asset of this activity if applicable."""
+        if self.application_id is None:
+            return None
+
+        try:
+            small_image = self.assets["small_image"]
+        except KeyError:
+            return None
+        else:
+            return "https://cdn.discordapp.com/app-assets/{0}/{1}.png".format(
+                self.application_id, small_image
+            )
+
+    @property
+    def large_image_text(self):
+        """Optional[:class:`str`]: Returns the large image asset hover text of this activity if applicable."""
+        return self.assets.get("large_text", None)
+
+    @property
+    def small_image_text(self):
+        """Optional[:class:`str`]: Returns the small image asset hover text of this activity if applicable."""
+        return self.assets.get("small_text", None)
+
+
+class Game(_ActivityTag):
+    """A slimmed down version of :class:`Activity` that represents a Discord game.
+
+    This is typically displayed via **Playing** on the official Discord client.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two games are equal.
+
+        .. describe:: x != y
+
+            Checks if two games are not equal.
+
+        .. describe:: hash(x)
+
+            Returns the game's hash.
+
+        .. describe:: str(x)
+
+            Returns the game's name.
+
+    Parameters
+    -----------
+    name: :class:`str`
+        The game's name.
+    start: Optional[:class:`datetime.datetime`]
+        A naive UTC timestamp representing when the game started. Keyword-only parameter. Ignored for bots.
+    end: Optional[:class:`datetime.datetime`]
+        A naive UTC timestamp representing when the game ends. Keyword-only parameter. Ignored for bots.
+
+    Attributes
+    -----------
+    name: :class:`str`
+        The game's name.
+    """
+
+    __slots__ = ("name", "_end", "_start")
+
+    def __init__(self, name, **extra):
+        self.name = name
+
+        try:
+            timestamps = extra["timestamps"]
+        except KeyError:
+            self._extract_timestamp(extra, "start")
+            self._extract_timestamp(extra, "end")
+        else:
+            self._start = timestamps.get("start", 0)
+            self._end = timestamps.get("end", 0)
+
+    def _extract_timestamp(self, data, key):
+        try:
+            dt = data[key]
+        except KeyError:
+            setattr(self, "_" + key, 0)
+        else:
+            setattr(self, "_" + key, dt.timestamp() * 1000.0)
+
+    @property
+    def type(self):
+        """Returns the game's type. This is for compatibility with :class:`Activity`.
+
+        It always returns :attr:`ActivityType.playing`.
+        """
+        return ActivityType.playing
+
+    @property
+    def start(self):
+        """Optional[:class:`datetime.datetime`]: When the user started playing this game in UTC, if applicable."""
+        if self._start:
+            return datetime.datetime.utcfromtimestamp(self._start / 1000)
+        return None
+
+    @property
+    def end(self):
+        """Optional[:class:`datetime.datetime`]: When the user will stop playing this game in UTC, if applicable."""
+        if self._end:
+            return datetime.datetime.utcfromtimestamp(self._end / 1000)
+        return None
+
+    def __str__(self):
+        return str(self.name)
+
+    def __repr__(self):
+        return "<Game name={0.name!r}>".format(self)
+
+    def to_dict(self):
+        timestamps = {}
+        if self._start:
+            timestamps["start"] = self._start
+
+        if self._end:
+            timestamps["end"] = self._end
+
+        return {
+            "type": ActivityType.playing.value,
+            "name": str(self.name),
+            "timestamps": timestamps,
+        }
+
+    def __eq__(self, other):
+        return isinstance(other, Game) and other.name == self.name
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def __hash__(self):
+        return hash(self.name)
+
+
+class Streaming(_ActivityTag):
+    """A slimmed down version of :class:`Activity` that represents a Discord streaming status.
+
+    This is typically displayed via **Streaming** on the official Discord client.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two streams are equal.
+
+        .. describe:: x != y
+
+            Checks if two streams are not equal.
+
+        .. describe:: hash(x)
+
+            Returns the stream's hash.
+
+        .. describe:: str(x)
+
+            Returns the stream's name.
+
+    Attributes
+    -----------
+    name: :class:`str`
+        The stream's name.
+    url: :class:`str`
+        The stream's URL. Currently only twitch.tv URLs are supported. Anything else is silently
+        discarded.
+    details: Optional[:class:`str`]
+        If provided, typically the game the streamer is playing.
+    assets: :class:`dict`
+        A dictionary comprising of similar keys than those in :attr:`Activity.assets`.
+    """
+
+    __slots__ = ("name", "url", "details", "assets")
+
+    def __init__(self, *, name, url, **extra):
+        self.name = name
+        self.url = url
+        self.details = extra.pop("details", None)
+        self.assets = extra.pop("assets", {})
+
+    @property
+    def type(self):
+        """Returns the game's type. This is for compatibility with :class:`Activity`.
+
+        It always returns :attr:`ActivityType.streaming`.
+        """
+        return ActivityType.streaming
+
+    def __str__(self):
+        return str(self.name)
+
+    def __repr__(self):
+        return "<Streaming name={0.name!r}>".format(self)
+
+    @property
+    def twitch_name(self):
+        """Optional[:class:`str`]: If provided, the twitch name of the user streaming.
+
+        This corresponds to the ``large_image`` key of the :attr:`Streaming.assets`
+        dictionary if it starts with ``twitch:``. Typically set by the Discord client.
+        """
+
+        try:
+            name = self.assets["large_image"]
+        except KeyError:
+            return None
+        else:
+            return name[7:] if name[:7] == "twitch:" else None
+
+    def to_dict(self):
+        ret = {
+            "type": ActivityType.streaming.value,
+            "name": str(self.name),
+            "url": str(self.url),
+            "assets": self.assets,
+        }
+        if self.details:
+            ret["details"] = self.details
+        return ret
+
+    def __eq__(self, other):
+        return isinstance(other, Streaming) and other.name == self.name and other.url == self.url
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def __hash__(self):
+        return hash(self.name)
+
+
+class Spotify:
+    """Represents a Spotify listening activity from Discord. This is a special case of
+    :class:`Activity` that makes it easier to work with the Spotify integration.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two activities are equal.
+
+        .. describe:: x != y
+
+            Checks if two activities are not equal.
+
+        .. describe:: hash(x)
+
+            Returns the activity's hash.
+
+        .. describe:: str(x)
+
+            Returns the string 'Spotify'.
+    """
+
+    __slots__ = (
+        "_state",
+        "_details",
+        "_timestamps",
+        "_assets",
+        "_party",
+        "_sync_id",
+        "_session_id",
+    )
+
+    def __init__(self, **data):
+        self._state = data.pop("state", None)
+        self._details = data.pop("details", None)
+        self._timestamps = data.pop("timestamps", {})
+        self._assets = data.pop("assets", {})
+        self._party = data.pop("party", {})
+        self._sync_id = data.pop("sync_id")
+        self._session_id = data.pop("session_id")
+
+    @property
+    def type(self):
+        """Returns the activity's type. This is for compatibility with :class:`Activity`.
+
+        It always returns :attr:`ActivityType.listening`.
+        """
+        return ActivityType.listening
+
+    @property
+    def colour(self):
+        """Returns the Spotify integration colour, as a :class:`Colour`.
+
+        There is an alias for this named :meth:`color`"""
+        return Colour(0x1DB954)
+
+    @property
+    def color(self):
+        """Returns the Spotify integration colour, as a :class:`Colour`.
+
+        There is an alias for this named :meth:`colour`"""
+        return self.colour
+
+    def to_dict(self):
+        return {
+            "flags": 48,  # SYNC | PLAY
+            "name": "Spotify",
+            "assets": self._assets,
+            "party": self._party,
+            "sync_id": self._sync_id,
+            "session_id": self._session_id,
+            "timestamps": self._timestamps,
+            "details": self._details,
+            "state": self._state,
+        }
+
+    @property
+    def name(self):
+        """:class:`str`: The activity's name. This will always return "Spotify"."""
+        return "Spotify"
+
+    def __eq__(self, other):
+        return isinstance(other, Spotify) and other._session_id == self._session_id
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def __hash__(self):
+        return hash(self._session_id)
+
+    def __str__(self):
+        return "Spotify"
+
+    def __repr__(self):
+        return "<Spotify title={0.title!r} artist={0.artist!r} track_id={0.track_id!r}>".format(
+            self
+        )
+
+    @property
+    def title(self):
+        """:class:`str`: The title of the song being played."""
+        return self._details
+
+    @property
+    def artists(self):
+        """List[:class:`str`]: The artists of the song being played."""
+        return self._state.split("; ")
+
+    @property
+    def artist(self):
+        """:class:`str`: The artist of the song being played.
+
+        This does not attempt to split the artist information into
+        multiple artists. Useful if there's only a single artist.
+        """
+        return self._state
+
+    @property
+    def album(self):
+        """:class:`str`: The album that the song being played belongs to."""
+        return self._assets.get("large_text", "")
+
+    @property
+    def album_cover_url(self):
+        """:class:`str`: The album cover image URL from Spotify's CDN."""
+        large_image = self._assets.get("large_image", "")
+        if large_image[:8] != "spotify:":
+            return ""
+        album_image_id = large_image[8:]
+        return "https://i.scdn.co/image/" + album_image_id
+
+    @property
+    def track_id(self):
+        """:class:`str`: The track ID used by Spotify to identify this song."""
+        return self._sync_id
+
+    @property
+    def start(self):
+        """:class:`datetime.datetime`: When the user started playing this song in UTC."""
+        return datetime.datetime.utcfromtimestamp(self._timestamps["start"] / 1000)
+
+    @property
+    def end(self):
+        """:class:`datetime.datetime`: When the user will stop playing this song in UTC."""
+        return datetime.datetime.utcfromtimestamp(self._timestamps["end"] / 1000)
+
+    @property
+    def duration(self):
+        """:class:`datetime.timedelta`: The duration of the song being played."""
+        return self.end - self.start
+
+    @property
+    def party_id(self):
+        """:class:`str`: The party ID of the listening party."""
+        return self._party.get("id", "")
+
+
+def create_activity(data):
+    if not data:
+        return None
+
+    game_type = try_enum(ActivityType, data.get("type", -1))
+    if game_type is ActivityType.playing:
+        if "application_id" in data or "session_id" in data:
+            return Activity(**data)
+        return Game(**data)
+    elif game_type is ActivityType.streaming:
+        if "url" in data:
+            return Streaming(**data)
+        return Activity(**data)
+    elif game_type is ActivityType.listening and "sync_id" in data and "session_id" in data:
+        return Spotify(**data)
+    return Activity(**data)

discord/audit_logs.py

@@ -0,0 +1,366 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from . import utils, enums
+from .object import Object
+from .permissions import PermissionOverwrite, Permissions
+from .colour import Colour
+from .invite import Invite
+
+
+def _transform_verification_level(entry, data):
+    return enums.try_enum(enums.VerificationLevel, data)
+
+
+def _transform_default_notifications(entry, data):
+    return enums.try_enum(enums.NotificationLevel, data)
+
+
+def _transform_explicit_content_filter(entry, data):
+    return enums.try_enum(enums.ContentFilter, data)
+
+
+def _transform_permissions(entry, data):
+    return Permissions(data)
+
+
+def _transform_color(entry, data):
+    return Colour(data)
+
+
+def _transform_snowflake(entry, data):
+    return int(data)
+
+
+def _transform_channel(entry, data):
+    if data is None:
+        return None
+    channel = entry.guild.get_channel(int(data)) or Object(id=data)
+    return channel
+
+
+def _transform_owner_id(entry, data):
+    if data is None:
+        return None
+    return entry._get_member(int(data))
+
+
+def _transform_inviter_id(entry, data):
+    if data is None:
+        return None
+    return entry._get_member(int(data))
+
+
+def _transform_overwrites(entry, data):
+    overwrites = []
+    for elem in data:
+        allow = Permissions(elem["allow"])
+        deny = Permissions(elem["deny"])
+        ow = PermissionOverwrite.from_pair(allow, deny)
+
+        ow_type = elem["type"]
+        ow_id = int(elem["id"])
+        if ow_type == "role":
+            target = entry.guild.get_role(ow_id)
+        else:
+            target = entry._get_member(ow_id)
+
+        if target is None:
+            target = Object(id=ow_id)
+
+        overwrites.append((target, ow))
+
+    return overwrites
+
+
+class AuditLogDiff:
+    def __len__(self):
+        return len(self.__dict__)
+
+    def __iter__(self):
+        return iter(self.__dict__.items())
+
+    def __repr__(self):
+        return "<AuditLogDiff attrs={0!r}>".format(tuple(self.__dict__))
+
+
+class AuditLogChanges:
+    TRANSFORMERS = {
+        "verification_level": (None, _transform_verification_level),
+        "explicit_content_filter": (None, _transform_explicit_content_filter),
+        "allow": (None, _transform_permissions),
+        "deny": (None, _transform_permissions),
+        "permissions": (None, _transform_permissions),
+        "id": (None, _transform_snowflake),
+        "color": ("colour", _transform_color),
+        "owner_id": ("owner", _transform_owner_id),
+        "inviter_id": ("inviter", _transform_inviter_id),
+        "channel_id": ("channel", _transform_channel),
+        "afk_channel_id": ("afk_channel", _transform_channel),
+        "system_channel_id": ("system_channel", _transform_channel),
+        "widget_channel_id": ("widget_channel", _transform_channel),
+        "permission_overwrites": ("overwrites", _transform_overwrites),
+        "splash_hash": ("splash", None),
+        "icon_hash": ("icon", None),
+        "avatar_hash": ("avatar", None),
+        "rate_limit_per_user": ("slowmode_delay", None),
+        "default_message_notifications": (
+            "default_notifications",
+            _transform_default_notifications,
+        ),
+    }
+
+    def __init__(self, entry, data):
+        self.before = AuditLogDiff()
+        self.after = AuditLogDiff()
+
+        for elem in data:
+            attr = elem["key"]
+
+            # special cases for role add/remove
+            if attr == "$add":
+                self._handle_role(self.before, self.after, entry, elem["new_value"])
+                continue
+            elif attr == "$remove":
+                self._handle_role(self.after, self.before, entry, elem["new_value"])
+                continue
+
+            transformer = self.TRANSFORMERS.get(attr)
+            if transformer:
+                key, transformer = transformer
+                if key:
+                    attr = key
+
+            try:
+                before = elem["old_value"]
+            except KeyError:
+                before = None
+            else:
+                if transformer:
+                    before = transformer(entry, before)
+
+            setattr(self.before, attr, before)
+
+            try:
+                after = elem["new_value"]
+            except KeyError:
+                after = None
+            else:
+                if transformer:
+                    after = transformer(entry, after)
+
+            setattr(self.after, attr, after)
+
+        # add an alias
+        if hasattr(self.after, "colour"):
+            self.after.color = self.after.colour
+            self.before.color = self.before.colour
+
+    def _handle_role(self, first, second, entry, elem):
+        if not hasattr(first, "roles"):
+            setattr(first, "roles", [])
+
+        data = []
+        g = entry.guild
+
+        for e in elem:
+            role_id = int(e["id"])
+            role = g.get_role(role_id)
+
+            if role is None:
+                role = Object(id=role_id)
+                role.name = e["name"]
+
+            data.append(role)
+
+        setattr(second, "roles", data)
+
+
+class AuditLogEntry:
+    r"""Represents an Audit Log entry.
+
+    You retrieve these via :meth:`Guild.audit_logs`.
+
+    Attributes
+    -----------
+    action: :class:`AuditLogAction`
+        The action that was done.
+    user: :class:`abc.User`
+        The user who initiated this action. Usually a :class:`Member`\, unless gone
+        then it's a :class:`User`.
+    id: :class:`int`
+        The entry ID.
+    target: Any
+        The target that got changed. The exact type of this depends on
+        the action being done.
+    reason: Optional[:class:`str`]
+        The reason this action was done.
+    extra: Any
+        Extra information that this entry has that might be useful.
+        For most actions, this is ``None``. However in some cases it
+        contains extra information. See :class:`AuditLogAction` for
+        which actions have this field filled out.
+    """
+
+    def __init__(self, *, users, data, guild):
+        self._state = guild._state
+        self.guild = guild
+        self._users = users
+        self._from_data(data)
+
+    def _from_data(self, data):
+        self.action = enums.AuditLogAction(data["action_type"])
+        self.id = int(data["id"])
+
+        # this key is technically not usually present
+        self.reason = data.get("reason")
+        self.extra = data.get("options")
+
+        if self.extra:
+            if self.action is enums.AuditLogAction.member_prune:
+                # member prune has two keys with useful information
+                self.extra = type(
+                    "_AuditLogProxy", (), {k: int(v) for k, v in self.extra.items()}
+                )()
+            elif self.action is enums.AuditLogAction.message_delete:
+                channel_id = int(self.extra["channel_id"])
+                elems = {
+                    "count": int(self.extra["count"]),
+                    "channel": self.guild.get_channel(channel_id) or Object(id=channel_id),
+                }
+                self.extra = type("_AuditLogProxy", (), elems)()
+            elif self.action.name.startswith("overwrite_"):
+                # the overwrite_ actions have a dict with some information
+                instance_id = int(self.extra["id"])
+                the_type = self.extra.get("type")
+                if the_type == "member":
+                    self.extra = self._get_member(instance_id)
+                else:
+                    role = self.guild.get_role(instance_id)
+                    if role is None:
+                        role = Object(id=instance_id)
+                        role.name = self.extra.get("role_name")
+                    self.extra = role
+
+        # this key is not present when the above is present, typically.
+        # It's a list of { new_value: a, old_value: b, key: c }
+        # where new_value and old_value are not guaranteed to be there depending
+        # on the action type, so let's just fetch it for now and only turn it
+        # into meaningful data when requested
+        self._changes = data.get("changes", [])
+
+        self.user = self._get_member(utils._get_as_snowflake(data, "user_id"))
+        self._target_id = utils._get_as_snowflake(data, "target_id")
+
+    def _get_member(self, user_id):
+        return self.guild.get_member(user_id) or self._users.get(user_id)
+
+    def __repr__(self):
+        return "<AuditLogEntry id={0.id} action={0.action} user={0.user!r}>".format(self)
+
+    @utils.cached_property
+    def created_at(self):
+        """Returns the entry's creation time in UTC."""
+        return utils.snowflake_time(self.id)
+
+    @utils.cached_property
+    def target(self):
+        try:
+            converter = getattr(self, "_convert_target_" + self.action.target_type)
+        except AttributeError:
+            return Object(id=self._target_id)
+        else:
+            return converter(self._target_id)
+
+    @utils.cached_property
+    def category(self):
+        """Optional[:class:`AuditLogActionCategory`]: The category of the action, if applicable."""
+        return self.action.category
+
+    @utils.cached_property
+    def changes(self):
+        """:class:`AuditLogChanges`: The list of changes this entry has."""
+        obj = AuditLogChanges(self, self._changes)
+        del self._changes
+        return obj
+
+    @utils.cached_property
+    def before(self):
+        """:class:`AuditLogDiff`: The target's prior state."""
+        return self.changes.before
+
+    @utils.cached_property
+    def after(self):
+        """:class:`AuditLogDiff`: The target's subsequent state."""
+        return self.changes.after
+
+    def _convert_target_guild(self, target_id):
+        return self.guild
+
+    def _convert_target_channel(self, target_id):
+        ch = self.guild.get_channel(target_id)
+        if ch is None:
+            return Object(id=target_id)
+        return ch
+
+    def _convert_target_user(self, target_id):
+        return self._get_member(target_id)
+
+    def _convert_target_role(self, target_id):
+        role = self.guild.get_role(target_id)
+        if role is None:
+            return Object(id=target_id)
+        return role
+
+    def _convert_target_invite(self, target_id):
+        # invites have target_id set to null
+        # so figure out which change has the full invite data
+        changeset = (
+            self.before if self.action is enums.AuditLogAction.invite_delete else self.after
+        )
+
+        fake_payload = {
+            "max_age": changeset.max_age,
+            "max_uses": changeset.max_uses,
+            "code": changeset.code,
+            "temporary": changeset.temporary,
+            "channel": changeset.channel,
+            "uses": changeset.uses,
+            "guild": self.guild,
+        }
+
+        obj = Invite(state=self._state, data=fake_payload)
+        try:
+            obj.inviter = changeset.inviter
+        except AttributeError:
+            pass
+        return obj
+
+    def _convert_target_emoji(self, target_id):
+        return self._state.get_emoji(target_id) or Object(id=target_id)
+
+    def _convert_target_message(self, target_id):
+        return self._get_member(target_id)

discord/backoff.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import time
+import random
+
+
+class ExponentialBackoff:
+    """An implementation of the exponential backoff algorithm
+
+    Provides a convenient interface to implement an exponential backoff
+    for reconnecting or retrying transmissions in a distributed network.
+
+    Once instantiated, the delay method will return the next interval to
+    wait for when retrying a connection or transmission.  The maximum
+    delay increases exponentially with each retry up to a maximum of
+    2^10 * base, and is reset if no more attempts are needed in a period
+    of 2^11 * base seconds.
+
+    Parameters
+    ----------
+    base: int
+        The base delay in seconds.  The first retry-delay will be up to
+        this many seconds.
+    integral: bool
+        Set to True if whole periods of base is desirable, otherwise any
+        number in between may be returned.
+    """
+
+    def __init__(self, base=1, *, integral=False):
+        self._base = base
+
+        self._exp = 0
+        self._max = 10
+        self._reset_time = base * 2 ** 11
+        self._last_invocation = time.monotonic()
+
+        # Use our own random instance to avoid messing with global one
+        rand = random.Random()
+        rand.seed()
+
+        self._randfunc = rand.randrange if integral else rand.uniform
+
+    def delay(self):
+        """Compute the next delay
+
+        Returns the next delay to wait according to the exponential
+        backoff algorithm.  This is a value between 0 and base * 2^exp
+        where exponent starts off at 1 and is incremented at every
+        invocation of this method up to a maximum of 10.
+
+        If a period of more than base * 2^11 has passed since the last
+        retry, the exponent is reset to 1.
+        """
+        invocation = time.monotonic()
+        interval = invocation - self._last_invocation
+        self._last_invocation = invocation
+
+        if interval > self._reset_time:
+            self._exp = 0
+
+        self._exp = min(self._exp + 1, self._max)
+        return self._randfunc(0, self._base * 2 ** self._exp)

discord/calls.py

@@ -0,0 +1,157 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import datetime
+
+from . import utils
+from .enums import VoiceRegion, try_enum
+from .member import VoiceState
+
+
+class CallMessage:
+    """Represents a group call message from Discord.
+
+    This is only received in cases where the message type is equivalent to
+    :attr:`MessageType.call`.
+
+    Attributes
+    -----------
+    ended_timestamp: Optional[datetime.datetime]
+        A naive UTC datetime object that represents the time that the call has ended.
+    participants: List[:class:`User`]
+        The list of users that are participating in this call.
+    message: :class:`Message`
+        The message associated with this call message.
+    """
+
+    def __init__(self, message, **kwargs):
+        self.message = message
+        self.ended_timestamp = utils.parse_time(kwargs.get("ended_timestamp"))
+        self.participants = kwargs.get("participants")
+
+    @property
+    def call_ended(self):
+        """:obj:`bool`: Indicates if the call has ended."""
+        return self.ended_timestamp is not None
+
+    @property
+    def channel(self):
+        r""":class:`GroupChannel`\: The private channel associated with this message."""
+        return self.message.channel
+
+    @property
+    def duration(self):
+        """Queries the duration of the call.
+
+        If the call has not ended then the current duration will
+        be returned.
+
+        Returns
+        ---------
+        datetime.timedelta
+            The timedelta object representing the duration.
+        """
+        if self.ended_timestamp is None:
+            return datetime.datetime.utcnow() - self.message.created_at
+        else:
+            return self.ended_timestamp - self.message.created_at
+
+
+class GroupCall:
+    """Represents the actual group call from Discord.
+
+    This is accompanied with a :class:`CallMessage` denoting the information.
+
+    Attributes
+    -----------
+    call: :class:`CallMessage`
+        The call message associated with this group call.
+    unavailable: :obj:`bool`
+        Denotes if this group call is unavailable.
+    ringing: List[:class:`User`]
+        A list of users that are currently being rung to join the call.
+    region: :class:`VoiceRegion`
+        The guild region the group call is being hosted on.
+    """
+
+    def __init__(self, **kwargs):
+        self.call = kwargs.get("call")
+        self.unavailable = kwargs.get("unavailable")
+        self._voice_states = {}
+
+        for state in kwargs.get("voice_states", []):
+            self._update_voice_state(state)
+
+        self._update(**kwargs)
+
+    def _update(self, **kwargs):
+        self.region = try_enum(VoiceRegion, kwargs.get("region"))
+        lookup = {u.id: u for u in self.call.channel.recipients}
+        me = self.call.channel.me
+        lookup[me.id] = me
+        self.ringing = list(filter(None, map(lookup.get, kwargs.get("ringing", []))))
+
+    def _update_voice_state(self, data):
+        user_id = int(data["user_id"])
+        # left the voice channel?
+        if data["channel_id"] is None:
+            self._voice_states.pop(user_id, None)
+        else:
+            self._voice_states[user_id] = VoiceState(data=data, channel=self.channel)
+
+    @property
+    def connected(self):
+        """A property that returns the :obj:`list` of :class:`User` that are currently in this call."""
+        ret = [u for u in self.channel.recipients if self.voice_state_for(u) is not None]
+        me = self.channel.me
+        if self.voice_state_for(me) is not None:
+            ret.append(me)
+
+        return ret
+
+    @property
+    def channel(self):
+        r""":class:`GroupChannel`\: Returns the channel the group call is in."""
+        return self.call.channel
+
+    def voice_state_for(self, user):
+        """Retrieves the :class:`VoiceState` for a specified :class:`User`.
+
+        If the :class:`User` has no voice state then this function returns
+        ``None``.
+
+        Parameters
+        ------------
+        user: :class:`User`
+            The user to retrieve the voice state for.
+
+        Returns
+        --------
+        Optional[:class:`VoiceState`]
+            The voice state associated with this user.
+        """
+
+        return self._voice_states.get(user.id)

discord/colour.py

@@ -0,0 +1,234 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import colorsys
+
+
+class Colour:
+    """Represents a Discord role colour. This class is similar
+    to an (red, green, blue) :class:`tuple`.
+
+    There is an alias for this called Color.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+             Checks if two colours are equal.
+
+        .. describe:: x != y
+
+             Checks if two colours are not equal.
+
+        .. describe:: hash(x)
+
+             Return the colour's hash.
+
+        .. describe:: str(x)
+
+             Returns the hex format for the colour.
+
+    Attributes
+    ------------
+    value: :class:`int`
+        The raw integer colour value.
+    """
+
+    __slots__ = ("value",)
+
+    def __init__(self, value):
+        if not isinstance(value, int):
+            raise TypeError(
+                "Expected int parameter, received %s instead." % value.__class__.__name__
+            )
+
+        self.value = value
+
+    def _get_byte(self, byte):
+        return (self.value >> (8 * byte)) & 0xFF
+
+    def __eq__(self, other):
+        return isinstance(other, Colour) and self.value == other.value
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def __str__(self):
+        return "#{:0>6x}".format(self.value)
+
+    def __repr__(self):
+        return "<Colour value=%s>" % self.value
+
+    def __hash__(self):
+        return hash(self.value)
+
+    @property
+    def r(self):
+        """Returns the red component of the colour."""
+        return self._get_byte(2)
+
+    @property
+    def g(self):
+        """Returns the green component of the colour."""
+        return self._get_byte(1)
+
+    @property
+    def b(self):
+        """Returns the blue component of the colour."""
+        return self._get_byte(0)
+
+    def to_rgb(self):
+        """Returns an (r, g, b) tuple representing the colour."""
+        return (self.r, self.g, self.b)
+
+    @classmethod
+    def from_rgb(cls, r, g, b):
+        """Constructs a :class:`Colour` from an RGB tuple."""
+        return cls((r << 16) + (g << 8) + b)
+
+    @classmethod
+    def from_hsv(cls, h, s, v):
+        """Constructs a :class:`Colour` from an HSV tuple."""
+        rgb = colorsys.hsv_to_rgb(h, s, v)
+        return cls.from_rgb(*(int(x * 255) for x in rgb))
+
+    @classmethod
+    def default(cls):
+        """A factory method that returns a :class:`Colour` with a value of 0."""
+        return cls(0)
+
+    @classmethod
+    def teal(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x1abc9c``."""
+        return cls(0x1ABC9C)
+
+    @classmethod
+    def dark_teal(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x11806a``."""
+        return cls(0x11806A)
+
+    @classmethod
+    def green(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x2ecc71``."""
+        return cls(0x2ECC71)
+
+    @classmethod
+    def dark_green(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x1f8b4c``."""
+        return cls(0x1F8B4C)
+
+    @classmethod
+    def blue(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x3498db``."""
+        return cls(0x3498DB)
+
+    @classmethod
+    def dark_blue(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x206694``."""
+        return cls(0x206694)
+
+    @classmethod
+    def purple(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x9b59b6``."""
+        return cls(0x9B59B6)
+
+    @classmethod
+    def dark_purple(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x71368a``."""
+        return cls(0x71368A)
+
+    @classmethod
+    def magenta(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0xe91e63``."""
+        return cls(0xE91E63)
+
+    @classmethod
+    def dark_magenta(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0xad1457``."""
+        return cls(0xAD1457)
+
+    @classmethod
+    def gold(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0xf1c40f``."""
+        return cls(0xF1C40F)
+
+    @classmethod
+    def dark_gold(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0xc27c0e``."""
+        return cls(0xC27C0E)
+
+    @classmethod
+    def orange(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0xe67e22``."""
+        return cls(0xE67E22)
+
+    @classmethod
+    def dark_orange(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0xa84300``."""
+        return cls(0xA84300)
+
+    @classmethod
+    def red(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0xe74c3c``."""
+        return cls(0xE74C3C)
+
+    @classmethod
+    def dark_red(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x992d22``."""
+        return cls(0x992D22)
+
+    @classmethod
+    def lighter_grey(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x95a5a6``."""
+        return cls(0x95A5A6)
+
+    @classmethod
+    def dark_grey(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x607d8b``."""
+        return cls(0x607D8B)
+
+    @classmethod
+    def light_grey(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x979c9f``."""
+        return cls(0x979C9F)
+
+    @classmethod
+    def darker_grey(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x546e7a``."""
+        return cls(0x546E7A)
+
+    @classmethod
+    def blurple(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x7289da``."""
+        return cls(0x7289DA)
+
+    @classmethod
+    def greyple(cls):
+        """A factory method that returns a :class:`Colour` with a value of ``0x99aab5``."""
+        return cls(0x99AAB5)
+
+
+Color = Colour

discord/context_managers.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import asyncio
+
+
+def _typing_done_callback(fut):
+    # just retrieve any exception and call it a day
+    try:
+        fut.exception()
+    except Exception:
+        pass
+
+
+class Typing:
+    def __init__(self, messageable):
+        self.loop = messageable._state.loop
+        self.messageable = messageable
+
+    async def do_typing(self):
+        try:
+            channel = self._channel
+        except AttributeError:
+            channel = await self.messageable._get_channel()
+
+        typing = channel._state.http.send_typing
+
+        while True:
+            await typing(channel.id)
+            await asyncio.sleep(5)
+
+    def __enter__(self):
+        self.task = asyncio.ensure_future(self.do_typing(), loop=self.loop)
+        self.task.add_done_callback(_typing_done_callback)
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.task.cancel()
+
+    async def __aenter__(self):
+        self._channel = channel = await self.messageable._get_channel()
+        await channel._state.http.send_typing(channel.id)
+        return self.__enter__()
+
+    async def __aexit__(self, exc_type, exc, tb):
+        self.task.cancel()

discord/embeds.py

@@ -0,0 +1,492 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import datetime
+
+from . import utils
+from .colour import Colour
+
+
+class _EmptyEmbed:
+    def __bool__(self):
+        return False
+
+    def __repr__(self):
+        return "Embed.Empty"
+
+
+EmptyEmbed = _EmptyEmbed()
+
+
+class EmbedProxy:
+    def __init__(self, layer):
+        self.__dict__.update(layer)
+
+    def __len__(self):
+        return len(self.__dict__)
+
+    def __repr__(self):
+        return "EmbedProxy(%s)" % ", ".join(
+            ("%s=%r" % (k, v) for k, v in self.__dict__.items() if not k.startswith("_"))
+        )
+
+    def __getattr__(self, attr):
+        return EmptyEmbed
+
+
+class Embed:
+    """Represents a Discord embed.
+
+    The following attributes can be set during creation
+    of the object:
+
+    Certain properties return an ``EmbedProxy``. Which is a type
+    that acts similar to a regular :class:`dict` except access the attributes
+    via dotted access, e.g. ``embed.author.icon_url``. If the attribute
+    is invalid or empty, then a special sentinel value is returned,
+    :attr:`Embed.Empty`.
+
+    For ease of use, all parameters that expect a :class:`str` are implicitly
+    casted to :class:`str` for you.
+
+    Attributes
+    -----------
+    title: :class:`str`
+        The title of the embed.
+    type: :class:`str`
+        The type of embed. Usually "rich".
+    description: :class:`str`
+        The description of the embed.
+    url: :class:`str`
+        The URL of the embed.
+    timestamp: `datetime.datetime`
+        The timestamp of the embed content. This could be a naive or aware datetime.
+    colour: :class:`Colour` or :class:`int`
+        The colour code of the embed. Aliased to ``color`` as well.
+    Empty
+        A special sentinel value used by ``EmbedProxy`` and this class
+        to denote that the value or attribute is empty.
+    """
+
+    __slots__ = (
+        "title",
+        "url",
+        "type",
+        "_timestamp",
+        "_colour",
+        "_footer",
+        "_image",
+        "_thumbnail",
+        "_video",
+        "_provider",
+        "_author",
+        "_fields",
+        "description",
+    )
+
+    Empty = EmptyEmbed
+
+    def __init__(self, **kwargs):
+        # swap the colour/color aliases
+        try:
+            colour = kwargs["colour"]
+        except KeyError:
+            colour = kwargs.get("color", EmptyEmbed)
+
+        self.colour = colour
+        self.title = kwargs.get("title", EmptyEmbed)
+        self.type = kwargs.get("type", "rich")
+        self.url = kwargs.get("url", EmptyEmbed)
+        self.description = kwargs.get("description", EmptyEmbed)
+
+        try:
+            timestamp = kwargs["timestamp"]
+        except KeyError:
+            pass
+        else:
+            self.timestamp = timestamp
+
+    @classmethod
+    def from_data(cls, data):
+        # we are bypassing __init__ here since it doesn't apply here
+        self = cls.__new__(cls)
+
+        # fill in the basic fields
+
+        self.title = data.get("title", EmptyEmbed)
+        self.type = data.get("type", EmptyEmbed)
+        self.description = data.get("description", EmptyEmbed)
+        self.url = data.get("url", EmptyEmbed)
+
+        # try to fill in the more rich fields
+
+        try:
+            self._colour = Colour(value=data["color"])
+        except KeyError:
+            pass
+
+        try:
+            self._timestamp = utils.parse_time(data["timestamp"])
+        except KeyError:
+            pass
+
+        for attr in ("thumbnail", "video", "provider", "author", "fields", "image", "footer"):
+            try:
+                value = data[attr]
+            except KeyError:
+                continue
+            else:
+                setattr(self, "_" + attr, value)
+
+        return self
+
+    @property
+    def colour(self):
+        return getattr(self, "_colour", EmptyEmbed)
+
+    @colour.setter
+    def colour(self, value):
+        if isinstance(value, (Colour, _EmptyEmbed)):
+            self._colour = value
+        elif isinstance(value, int):
+            self._colour = Colour(value=value)
+        else:
+            raise TypeError(
+                "Expected discord.Colour, int, or Embed.Empty but received %s instead."
+                % value.__class__.__name__
+            )
+
+    color = colour
+
+    @property
+    def timestamp(self):
+        return getattr(self, "_timestamp", EmptyEmbed)
+
+    @timestamp.setter
+    def timestamp(self, value):
+        if isinstance(value, (datetime.datetime, _EmptyEmbed)):
+            self._timestamp = value
+        else:
+            raise TypeError(
+                "Expected datetime.datetime or Embed.Empty received %s instead"
+                % value.__class__.__name__
+            )
+
+    @property
+    def footer(self):
+        """Returns an ``EmbedProxy`` denoting the footer contents.
+
+        See :meth:`set_footer` for possible values you can access.
+
+        If the attribute has no value then :attr:`Empty` is returned.
+        """
+        return EmbedProxy(getattr(self, "_footer", {}))
+
+    def set_footer(self, *, text=EmptyEmbed, icon_url=EmptyEmbed):
+        """Sets the footer for the embed content.
+
+        This function returns the class instance to allow for fluent-style
+        chaining.
+
+        Parameters
+        -----------
+        text: str
+            The footer text.
+        icon_url: str
+            The URL of the footer icon. Only HTTP(S) is supported.
+        """
+
+        self._footer = {}
+        if text is not EmptyEmbed:
+            self._footer["text"] = str(text)
+
+        if icon_url is not EmptyEmbed:
+            self._footer["icon_url"] = str(icon_url)
+
+        return self
+
+    @property
+    def image(self):
+        """Returns an ``EmbedProxy`` denoting the image contents.
+
+        Possible attributes you can access are:
+
+        - ``url``
+        - ``proxy_url``
+        - ``width``
+        - ``height``
+
+        If the attribute has no value then :attr:`Empty` is returned.
+        """
+        return EmbedProxy(getattr(self, "_image", {}))
+
+    def set_image(self, *, url):
+        """Sets the image for the embed content.
+
+        This function returns the class instance to allow for fluent-style
+        chaining.
+
+        Parameters
+        -----------
+        url: str
+            The source URL for the image. Only HTTP(S) is supported.
+        """
+
+        self._image = {"url": str(url)}
+
+        return self
+
+    @property
+    def thumbnail(self):
+        """Returns an ``EmbedProxy`` denoting the thumbnail contents.
+
+        Possible attributes you can access are:
+
+        - ``url``
+        - ``proxy_url``
+        - ``width``
+        - ``height``
+
+        If the attribute has no value then :attr:`Empty` is returned.
+        """
+        return EmbedProxy(getattr(self, "_thumbnail", {}))
+
+    def set_thumbnail(self, *, url):
+        """Sets the thumbnail for the embed content.
+
+        This function returns the class instance to allow for fluent-style
+        chaining.
+
+        Parameters
+        -----------
+        url: str
+            The source URL for the thumbnail. Only HTTP(S) is supported.
+        """
+
+        self._thumbnail = {"url": str(url)}
+
+        return self
+
+    @property
+    def video(self):
+        """Returns an ``EmbedProxy`` denoting the video contents.
+
+        Possible attributes include:
+
+        - ``url`` for the video URL.
+        - ``height`` for the video height.
+        - ``width`` for the video width.
+
+        If the attribute has no value then :attr:`Empty` is returned.
+        """
+        return EmbedProxy(getattr(self, "_video", {}))
+
+    @property
+    def provider(self):
+        """Returns an ``EmbedProxy`` denoting the provider contents.
+
+        The only attributes that might be accessed are ``name`` and ``url``.
+
+        If the attribute has no value then :attr:`Empty` is returned.
+        """
+        return EmbedProxy(getattr(self, "_provider", {}))
+
+    @property
+    def author(self):
+        """Returns an ``EmbedProxy`` denoting the author contents.
+
+        See :meth:`set_author` for possible values you can access.
+
+        If the attribute has no value then :attr:`Empty` is returned.
+        """
+        return EmbedProxy(getattr(self, "_author", {}))
+
+    def set_author(self, *, name, url=EmptyEmbed, icon_url=EmptyEmbed):
+        """Sets the author for the embed content.
+
+        This function returns the class instance to allow for fluent-style
+        chaining.
+
+        Parameters
+        -----------
+        name: str
+            The name of the author.
+        url: str
+            The URL for the author.
+        icon_url: str
+            The URL of the author icon. Only HTTP(S) is supported.
+        """
+
+        self._author = {"name": str(name)}
+
+        if url is not EmptyEmbed:
+            self._author["url"] = str(url)
+
+        if icon_url is not EmptyEmbed:
+            self._author["icon_url"] = str(icon_url)
+
+        return self
+
+    @property
+    def fields(self):
+        """Returns a :class:`list` of ``EmbedProxy`` denoting the field contents.
+
+        See :meth:`add_field` for possible values you can access.
+
+        If the attribute has no value then :attr:`Empty` is returned.
+        """
+        return [EmbedProxy(d) for d in getattr(self, "_fields", [])]
+
+    def add_field(self, *, name, value, inline=True):
+        """Adds a field to the embed object.
+
+        This function returns the class instance to allow for fluent-style
+        chaining.
+
+        Parameters
+        -----------
+        name: str
+            The name of the field.
+        value: str
+            The value of the field.
+        inline: bool
+            Whether the field should be displayed inline.
+        """
+
+        field = {"inline": inline, "name": str(name), "value": str(value)}
+
+        try:
+            self._fields.append(field)
+        except AttributeError:
+            self._fields = [field]
+
+        return self
+
+    def clear_fields(self):
+        """Removes all fields from this embed."""
+        try:
+            self._fields.clear()
+        except AttributeError:
+            self._fields = []
+
+    def remove_field(self, index):
+        """Removes a field at a specified index.
+
+        If the index is invalid or out of bounds then the error is
+        silently swallowed.
+
+        .. note::
+
+            When deleting a field by index, the index of the other fields
+            shift to fill the gap just like a regular list.
+
+        Parameters
+        -----------
+        index: int
+            The index of the field to remove.
+        """
+        try:
+            del self._fields[index]
+        except (AttributeError, IndexError):
+            pass
+
+    def set_field_at(self, index, *, name, value, inline=True):
+        """Modifies a field to the embed object.
+
+        The index must point to a valid pre-existing field.
+
+        This function returns the class instance to allow for fluent-style
+        chaining.
+
+        Parameters
+        -----------
+        index: int
+            The index of the field to modify.
+        name: str
+            The name of the field.
+        value: str
+            The value of the field.
+        inline: bool
+            Whether the field should be displayed inline.
+
+        Raises
+        -------
+        IndexError
+            An invalid index was provided.
+        """
+
+        try:
+            field = self._fields[index]
+        except (TypeError, IndexError, AttributeError):
+            raise IndexError("field index out of range")
+
+        field["name"] = str(name)
+        field["value"] = str(value)
+        field["inline"] = inline
+        return self
+
+    def to_dict(self):
+        """Converts this embed object into a dict."""
+
+        # add in the raw data into the dict
+        result = {
+            key[1:]: getattr(self, key)
+            for key in self.__slots__
+            if key[0] == "_" and hasattr(self, key)
+        }
+
+        # deal with basic convenience wrappers
+
+        try:
+            colour = result.pop("colour")
+        except KeyError:
+            pass
+        else:
+            if colour:
+                result["color"] = colour.value
+
+        try:
+            timestamp = result.pop("timestamp")
+        except KeyError:
+            pass
+        else:
+            if timestamp:
+                result["timestamp"] = timestamp.isoformat()
+
+        # add in the non raw attribute ones
+        if self.type:
+            result["type"] = self.type
+
+        if self.description:
+            result["description"] = self.description
+
+        if self.url:
+            result["url"] = self.url
+
+        if self.title:
+            result["title"] = self.title
+
+        return result

discord/emoji.py

@@ -0,0 +1,279 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from collections import namedtuple
+
+from . import utils
+from .mixins import Hashable
+
+
+class PartialEmoji(namedtuple("PartialEmoji", "animated name id")):
+    """Represents a "partial" emoji.
+
+    This model will be given in two scenarios:
+
+    - "Raw" data events such as :func:`on_raw_reaction_add`
+    - Custom emoji that the bot cannot see from e.g. :attr:`Message.reactions`
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two emoji are the same.
+
+        .. describe:: x != y
+
+            Checks if two emoji are not the same.
+
+        .. describe:: hash(x)
+
+            Return the emoji's hash.
+
+        .. describe:: str(x)
+
+            Returns the emoji rendered for discord.
+
+    Attributes
+    -----------
+    name: :class:`str`
+        The custom emoji name, if applicable, or the unicode codepoint
+        of the non-custom emoji.
+    animated: :class:`bool`
+        Whether the emoji is animated or not.
+    id: Optional[:class:`int`]
+        The ID of the custom emoji, if applicable.
+    """
+
+    __slots__ = ()
+
+    def __str__(self):
+        if self.id is None:
+            return self.name
+        if self.animated:
+            return "<a:%s:%s>" % (self.name, self.id)
+        return "<:%s:%s>" % (self.name, self.id)
+
+    def __eq__(self, other):
+        if self.is_unicode_emoji():
+            return isinstance(other, PartialEmoji) and self.name == other.name
+
+        if isinstance(other, (PartialEmoji, Emoji)):
+            return self.id == other.id
+
+    def is_custom_emoji(self):
+        """Checks if this is a custom non-Unicode emoji."""
+        return self.id is not None
+
+    def is_unicode_emoji(self):
+        """Checks if this is a Unicode emoji."""
+        return self.id is None
+
+    def _as_reaction(self):
+        if self.id is None:
+            return self.name
+        return "%s:%s" % (self.name, self.id)
+
+    @property
+    def url(self):
+        """Returns a URL version of the emoji, if it is custom."""
+        if self.is_unicode_emoji():
+            return None
+
+        _format = "gif" if self.animated else "png"
+        return "https://cdn.discordapp.com/emojis/{0.id}.{1}".format(self, _format)
+
+
+class Emoji(Hashable):
+    """Represents a custom emoji.
+
+    Depending on the way this object was created, some of the attributes can
+    have a value of ``None``.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two emoji are the same.
+
+        .. describe:: x != y
+
+            Checks if two emoji are not the same.
+
+        .. describe:: hash(x)
+
+            Return the emoji's hash.
+
+        .. describe:: iter(x)
+
+            Returns an iterator of ``(field, value)`` pairs. This allows this class
+            to be used as an iterable in list/dict/etc constructions.
+
+        .. describe:: str(x)
+
+            Returns the emoji rendered for discord.
+
+    Attributes
+    -----------
+    name: :class:`str`
+        The name of the emoji.
+    id: :class:`int`
+        The emoji's ID.
+    require_colons: :class:`bool`
+        If colons are required to use this emoji in the client (:PJSalt: vs PJSalt).
+    animated: :class:`bool`
+        Whether an emoji is animated or not.
+    managed: :class:`bool`
+        If this emoji is managed by a Twitch integration.
+    guild_id: :class:`int`
+        The guild ID the emoji belongs to.
+    """
+
+    __slots__ = (
+        "require_colons",
+        "animated",
+        "managed",
+        "id",
+        "name",
+        "_roles",
+        "guild_id",
+        "_state",
+    )
+
+    def __init__(self, *, guild, state, data):
+        self.guild_id = guild.id
+        self._state = state
+        self._from_data(data)
+
+    def _from_data(self, emoji):
+        self.require_colons = emoji["require_colons"]
+        self.managed = emoji["managed"]
+        self.id = int(emoji["id"])
+        self.name = emoji["name"]
+        self.animated = emoji.get("animated", False)
+        self._roles = utils.SnowflakeList(map(int, emoji.get("roles", [])))
+
+    def _iterator(self):
+        for attr in self.__slots__:
+            if attr[0] != "_":
+                value = getattr(self, attr, None)
+                if value is not None:
+                    yield (attr, value)
+
+    def __iter__(self):
+        return self._iterator()
+
+    def __str__(self):
+        if self.animated:
+            return "<a:{0.name}:{0.id}>".format(self)
+        return "<:{0.name}:{0.id}>".format(self)
+
+    def __repr__(self):
+        return "<Emoji id={0.id} name={0.name!r}>".format(self)
+
+    def __eq__(self, other):
+        return isinstance(other, (PartialEmoji, Emoji)) and self.id == other.id
+
+    @property
+    def created_at(self):
+        """Returns the emoji's creation time in UTC."""
+        return utils.snowflake_time(self.id)
+
+    @property
+    def url(self):
+        """Returns a URL version of the emoji."""
+        _format = "gif" if self.animated else "png"
+        return "https://cdn.discordapp.com/emojis/{0.id}.{1}".format(self, _format)
+
+    @property
+    def roles(self):
+        """List[:class:`Role`]: A :class:`list` of roles that is allowed to use this emoji.
+
+        If roles is empty, the emoji is unrestricted.
+        """
+        guild = self.guild
+        if guild is None:
+            return []
+
+        return [role for role in guild.roles if self._roles.has(role.id)]
+
+    @property
+    def guild(self):
+        """:class:`Guild`: The guild this emoji belongs to."""
+        return self._state._get_guild(self.guild_id)
+
+    async def delete(self, *, reason=None):
+        """|coro|
+
+        Deletes the custom emoji.
+
+        You must have :attr:`~Permissions.manage_emojis` permission to
+        do this.
+
+        Parameters
+        -----------
+        reason: Optional[str]
+            The reason for deleting this emoji. Shows up on the audit log.
+
+        Raises
+        -------
+        Forbidden
+            You are not allowed to delete emojis.
+        HTTPException
+            An error occurred deleting the emoji.
+        """
+
+        await self._state.http.delete_custom_emoji(self.guild.id, self.id, reason=reason)
+
+    async def edit(self, *, name, roles=None, reason=None):
+        r"""|coro|
+
+        Edits the custom emoji.
+
+        You must have :attr:`~Permissions.manage_emojis` permission to
+        do this.
+
+        Parameters
+        -----------
+        name: str
+            The new emoji name.
+        roles: Optional[list[:class:`Role`]]
+            A :class:`list` of :class:`Role`\s that can use this emoji. Leave empty to make it available to everyone.
+        reason: Optional[str]
+            The reason for editing this emoji. Shows up on the audit log.
+
+        Raises
+        -------
+        Forbidden
+            You are not allowed to edit emojis.
+        HTTPException
+            An error occurred editing the emoji.
+        """
+
+        if roles:
+            roles = [role.id for role in roles]
+        await self._state.http.edit_custom_emoji(
+            self.guild.id, self.id, name=name, roles=roles, reason=reason
+        )

discord/enums.py

@@ -0,0 +1,285 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from enum import Enum, IntEnum
+
+__all__ = [
+    "ChannelType",
+    "MessageType",
+    "VoiceRegion",
+    "SpeakingState",
+    "VerificationLevel",
+    "ContentFilter",
+    "Status",
+    "DefaultAvatar",
+    "RelationshipType",
+    "AuditLogAction",
+    "AuditLogActionCategory",
+    "UserFlags",
+    "ActivityType",
+    "HypeSquadHouse",
+    "NotificationLevel",
+]
+
+
+class ChannelType(Enum):
+    text = 0
+    private = 1
+    voice = 2
+    group = 3
+    category = 4
+
+    def __str__(self):
+        return self.name
+
+
+class MessageType(Enum):
+    default = 0
+    recipient_add = 1
+    recipient_remove = 2
+    call = 3
+    channel_name_change = 4
+    channel_icon_change = 5
+    pins_add = 6
+    new_member = 7
+
+
+class VoiceRegion(Enum):
+    us_west = "us-west"
+    us_east = "us-east"
+    us_south = "us-south"
+    us_central = "us-central"
+    eu_west = "eu-west"
+    eu_central = "eu-central"
+    singapore = "singapore"
+    london = "london"
+    sydney = "sydney"
+    amsterdam = "amsterdam"
+    frankfurt = "frankfurt"
+    brazil = "brazil"
+    hongkong = "hongkong"
+    russia = "russia"
+    japan = "japan"
+    southafrica = "southafrica"
+    vip_us_east = "vip-us-east"
+    vip_us_west = "vip-us-west"
+    vip_amsterdam = "vip-amsterdam"
+
+    def __str__(self):
+        return self.value
+
+
+class SpeakingState(IntEnum):
+    none = 0
+    voice = 1
+    soundshare = 2
+    priority = 4
+
+    def __str__(self):
+        return self.name
+
+
+class VerificationLevel(IntEnum):
+    none = 0
+    low = 1
+    medium = 2
+    high = 3
+    table_flip = 3
+    extreme = 4
+    double_table_flip = 4
+
+    def __str__(self):
+        return self.name
+
+
+class ContentFilter(IntEnum):
+    disabled = 0
+    no_role = 1
+    all_members = 2
+
+    def __str__(self):
+        return self.name
+
+
+class Status(Enum):
+    online = "online"
+    offline = "offline"
+    idle = "idle"
+    dnd = "dnd"
+    do_not_disturb = "dnd"
+    invisible = "invisible"
+
+    def __str__(self):
+        return self.value
+
+
+class DefaultAvatar(Enum):
+    blurple = 0
+    grey = 1
+    gray = 1
+    green = 2
+    orange = 3
+    red = 4
+
+    def __str__(self):
+        return self.name
+
+
+class RelationshipType(Enum):
+    friend = 1
+    blocked = 2
+    incoming_request = 3
+    outgoing_request = 4
+
+
+class NotificationLevel(IntEnum):
+    all_messages = 0
+    only_mentions = 1
+
+
+class AuditLogActionCategory(Enum):
+    create = 1
+    delete = 2
+    update = 3
+
+
+class AuditLogAction(Enum):
+    guild_update = 1
+    channel_create = 10
+    channel_update = 11
+    channel_delete = 12
+    overwrite_create = 13
+    overwrite_update = 14
+    overwrite_delete = 15
+    kick = 20
+    member_prune = 21
+    ban = 22
+    unban = 23
+    member_update = 24
+    member_role_update = 25
+    role_create = 30
+    role_update = 31
+    role_delete = 32
+    invite_create = 40
+    invite_update = 41
+    invite_delete = 42
+    webhook_create = 50
+    webhook_update = 51
+    webhook_delete = 52
+    emoji_create = 60
+    emoji_update = 61
+    emoji_delete = 62
+    message_delete = 72
+
+    @property
+    def category(self):
+        lookup = {
+            AuditLogAction.guild_update: AuditLogActionCategory.update,
+            AuditLogAction.channel_create: AuditLogActionCategory.create,
+            AuditLogAction.channel_update: AuditLogActionCategory.update,
+            AuditLogAction.channel_delete: AuditLogActionCategory.delete,
+            AuditLogAction.overwrite_create: AuditLogActionCategory.create,
+            AuditLogAction.overwrite_update: AuditLogActionCategory.update,
+            AuditLogAction.overwrite_delete: AuditLogActionCategory.delete,
+            AuditLogAction.kick: None,
+            AuditLogAction.member_prune: None,
+            AuditLogAction.ban: None,
+            AuditLogAction.unban: None,
+            AuditLogAction.member_update: AuditLogActionCategory.update,
+            AuditLogAction.member_role_update: AuditLogActionCategory.update,
+            AuditLogAction.role_create: AuditLogActionCategory.create,
+            AuditLogAction.role_update: AuditLogActionCategory.update,
+            AuditLogAction.role_delete: AuditLogActionCategory.delete,
+            AuditLogAction.invite_create: AuditLogActionCategory.create,
+            AuditLogAction.invite_update: AuditLogActionCategory.update,
+            AuditLogAction.invite_delete: AuditLogActionCategory.delete,
+            AuditLogAction.webhook_create: AuditLogActionCategory.create,
+            AuditLogAction.webhook_update: AuditLogActionCategory.update,
+            AuditLogAction.webhook_delete: AuditLogActionCategory.delete,
+            AuditLogAction.emoji_create: AuditLogActionCategory.create,
+            AuditLogAction.emoji_update: AuditLogActionCategory.update,
+            AuditLogAction.emoji_delete: AuditLogActionCategory.delete,
+            AuditLogAction.message_delete: AuditLogActionCategory.delete,
+        }
+        return lookup[self]
+
+    @property
+    def target_type(self):
+        v = self.value
+        if v == -1:
+            return "all"
+        elif v < 10:
+            return "guild"
+        elif v < 20:
+            return "channel"
+        elif v < 30:
+            return "user"
+        elif v < 40:
+            return "role"
+        elif v < 50:
+            return "invite"
+        elif v < 60:
+            return "webhook"
+        elif v < 70:
+            return "emoji"
+        elif v < 80:
+            return "message"
+
+
+class UserFlags(Enum):
+    staff = 1
+    partner = 2
+    hypesquad = 4
+    bug_hunter = 8
+    hypesquad_bravery = 64
+    hypesquad_brilliance = 128
+    hypesquad_balance = 256
+    early_supporter = 512
+
+
+class ActivityType(IntEnum):
+    unknown = -1
+    playing = 0
+    streaming = 1
+    listening = 2
+    watching = 3
+
+
+class HypeSquadHouse(Enum):
+    bravery = 1
+    brilliance = 2
+    balance = 3
+
+
+def try_enum(cls, val):
+    """A function that tries to turn the value into enum ``cls``.
+
+    If it fails it returns the value instead.
+    """
+    try:
+        return cls(val)
+    except ValueError:
+        return val

discord/errors.py

@@ -0,0 +1,183 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+
+class DiscordException(Exception):
+    """Base exception class for discord.py
+
+    Ideally speaking, this could be caught to handle any exceptions thrown from this library.
+    """
+
+    pass
+
+
+class ClientException(DiscordException):
+    """Exception that's thrown when an operation in the :class:`Client` fails.
+
+    These are usually for exceptions that happened due to user input.
+    """
+
+    pass
+
+
+class NoMoreItems(DiscordException):
+    """Exception that is thrown when an async iteration operation has no more
+    items."""
+
+    pass
+
+
+class GatewayNotFound(DiscordException):
+    """An exception that is usually thrown when the gateway hub
+    for the :class:`Client` websocket is not found."""
+
+    def __init__(self):
+        message = "The gateway to connect to discord was not found."
+        super(GatewayNotFound, self).__init__(message)
+
+
+def flatten_error_dict(d, key=""):
+    items = []
+    for k, v in d.items():
+        new_key = key + "." + k if key else k
+
+        if isinstance(v, dict):
+            try:
+                _errors = v["_errors"]
+            except KeyError:
+                items.extend(flatten_error_dict(v, new_key).items())
+            else:
+                items.append((new_key, " ".join(x.get("message", "") for x in _errors)))
+        else:
+            items.append((new_key, v))
+
+    return dict(items)
+
+
+class HTTPException(DiscordException):
+    """Exception that's thrown when an HTTP request operation fails.
+
+    Attributes
+    ------------
+    response: aiohttp.ClientResponse
+        The response of the failed HTTP request. This is an
+        instance of `aiohttp.ClientResponse`__. In some cases
+        this could also be a ``requests.Response``.
+
+        __ http://aiohttp.readthedocs.org/en/stable/client_reference.html#aiohttp.ClientResponse
+
+    text: :class:`str`
+        The text of the error. Could be an empty string.
+    status: :class:`int`
+        The status code of the HTTP request.
+    code: :class:`int`
+        The Discord specific error code for the failure.
+    """
+
+    def __init__(self, response, message):
+        self.response = response
+        self.status = response.status
+        if isinstance(message, dict):
+            self.code = message.get("code", 0)
+            base = message.get("message", "")
+            errors = message.get("errors")
+            if errors:
+                errors = flatten_error_dict(errors)
+                helpful = "\n".join("In %s: %s" % t for t in errors.items())
+                self.text = base + "\n" + helpful
+            else:
+                self.text = base
+        else:
+            self.text = message
+            self.code = 0
+
+        fmt = "{0.reason} (status code: {0.status})"
+        if len(self.text):
+            fmt = fmt + ": {1}"
+
+        super().__init__(fmt.format(self.response, self.text))
+
+
+class Forbidden(HTTPException):
+    """Exception that's thrown for when status code 403 occurs.
+
+    Subclass of :exc:`HTTPException`
+    """
+
+    pass
+
+
+class NotFound(HTTPException):
+    """Exception that's thrown for when status code 404 occurs.
+
+    Subclass of :exc:`HTTPException`
+    """
+
+    pass
+
+
+class InvalidArgument(ClientException):
+    """Exception that's thrown when an argument to a function
+    is invalid some way (e.g. wrong value or wrong type).
+
+    This could be considered the analogous of ``ValueError`` and
+    ``TypeError`` except derived from :exc:`ClientException` and thus
+    :exc:`DiscordException`.
+    """
+
+    pass
+
+
+class LoginFailure(ClientException):
+    """Exception that's thrown when the :meth:`Client.login` function
+    fails to log you in from improper credentials or some other misc.
+    failure.
+    """
+
+    pass
+
+
+class ConnectionClosed(ClientException):
+    """Exception that's thrown when the gateway connection is
+    closed for reasons that could not be handled internally.
+
+    Attributes
+    -----------
+    code: :class:`int`
+        The close code of the websocket.
+    reason: :class:`str`
+        The reason provided for the closure.
+    shard_id: Optional[:class:`int`]
+        The shard ID that got closed if applicable.
+    """
+
+    def __init__(self, original, *, shard_id):
+        # This exception is just the same exception except
+        # reconfigured to subclass ClientException for users
+        self.code = original.code
+        self.reason = original.reason
+        self.shard_id = shard_id
+        super().__init__(str(original))

discord/ext/commands/__init__.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+
+"""
+discord.ext.commands
+~~~~~~~~~~~~~~~~~~~~~
+
+An extension module to facilitate creation of bot commands.
+
+:copyright: (c) 2019 Rapptz
+:license: MIT, see LICENSE for more details.
+"""
+
+from .bot import Bot, AutoShardedBot, when_mentioned, when_mentioned_or
+from .context import Context
+from .core import *
+from .errors import *
+from .formatter import HelpFormatter, Paginator
+from .converter import *
+from .cooldowns import *

discord/ext/commands/context.py

@@ -0,0 +1,225 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import discord.abc
+import discord.utils
+
+
+class Context(discord.abc.Messageable):
+    r"""Represents the context in which a command is being invoked under.
+
+    This class contains a lot of meta data to help you understand more about
+    the invocation context. This class is not created manually and is instead
+    passed around to commands as the first parameter.
+
+    This class implements the :class:`abc.Messageable` ABC.
+
+    Attributes
+    -----------
+    message: :class:`discord.Message`
+        The message that triggered the command being executed.
+    bot: :class:`.Bot`
+        The bot that contains the command being executed.
+    args: :class:`list`
+        The list of transformed arguments that were passed into the command.
+        If this is accessed during the :func:`on_command_error` event
+        then this list could be incomplete.
+    kwargs: :class:`dict`
+        A dictionary of transformed arguments that were passed into the command.
+        Similar to :attr:`args`\, if this is accessed in the
+        :func:`on_command_error` event then this dict could be incomplete.
+    prefix: :class:`str`
+        The prefix that was used to invoke the command.
+    command
+        The command (i.e. :class:`.Command` or its superclasses) that is being
+        invoked currently.
+    invoked_with: :class:`str`
+        The command name that triggered this invocation. Useful for finding out
+        which alias called the command.
+    invoked_subcommand
+        The subcommand (i.e. :class:`.Command` or its superclasses) that was
+        invoked. If no valid subcommand was invoked then this is equal to
+        `None`.
+    subcommand_passed: Optional[:class:`str`]
+        The string that was attempted to call a subcommand. This does not have
+        to point to a valid registered subcommand and could just point to a
+        nonsense string. If nothing was passed to attempt a call to a
+        subcommand then this is set to `None`.
+    command_failed: :class:`bool`
+        A boolean that indicates if the command failed to be parsed, checked,
+        or invoked.
+    """
+
+    def __init__(self, **attrs):
+        self.message = attrs.pop("message", None)
+        self.bot = attrs.pop("bot", None)
+        self.args = attrs.pop("args", [])
+        self.kwargs = attrs.pop("kwargs", {})
+        self.prefix = attrs.pop("prefix")
+        self.command = attrs.pop("command", None)
+        self.view = attrs.pop("view", None)
+        self.invoked_with = attrs.pop("invoked_with", None)
+        self.invoked_subcommand = attrs.pop("invoked_subcommand", None)
+        self.subcommand_passed = attrs.pop("subcommand_passed", None)
+        self.command_failed = attrs.pop("command_failed", False)
+        self._state = self.message._state
+
+    async def invoke(self, *args, **kwargs):
+        r"""|coro|
+
+        Calls a command with the arguments given.
+
+        This is useful if you want to just call the callback that a
+        :class:`.Command` holds internally.
+
+        Note
+        ------
+        You do not pass in the context as it is done for you.
+
+        Warning
+        ---------
+        The first parameter passed **must** be the command being invoked.
+
+        Parameters
+        -----------
+        command: :class:`.Command`
+            A command or superclass of a command that is going to be called.
+        \*args
+            The arguments to to use.
+        \*\*kwargs
+            The keyword arguments to use.
+        """
+
+        try:
+            command = args[0]
+        except IndexError:
+            raise TypeError("Missing command to invoke.") from None
+
+        arguments = []
+        if command.instance is not None:
+            arguments.append(command.instance)
+
+        arguments.append(self)
+        arguments.extend(args[1:])
+
+        ret = await command.callback(*arguments, **kwargs)
+        return ret
+
+    async def reinvoke(self, *, call_hooks=False, restart=True):
+        """|coro|
+
+        Calls the command again.
+
+        This is similar to :meth:`~.Context.invoke` except that it bypasses
+        checks, cooldowns, and error handlers.
+
+        .. note::
+
+            If you want to bypass :exc:`.UserInputError` derived exceptions,
+            it is recommended to use the regular :meth:`~.Context.invoke`
+            as it will work more naturally. After all, this will end up
+            using the old arguments the user has used and will thus just
+            fail again.
+
+        Parameters
+        ------------
+        call_hooks: bool
+            Whether to call the before and after invoke hooks.
+        restart: bool
+            Whether to start the call chain from the very beginning
+            or where we left off (i.e. the command that caused the error).
+            The default is to start where we left off.
+        """
+        cmd = self.command
+        view = self.view
+        if cmd is None:
+            raise ValueError("This context is not valid.")
+
+        # some state to revert to when we're done
+        index, previous = view.index, view.previous
+        invoked_with = self.invoked_with
+        invoked_subcommand = self.invoked_subcommand
+        subcommand_passed = self.subcommand_passed
+
+        if restart:
+            to_call = cmd.root_parent or cmd
+            view.index = len(self.prefix)
+            view.previous = 0
+            view.get_word()  # advance to get the root command
+        else:
+            to_call = cmd
+
+        try:
+            await to_call.reinvoke(self, call_hooks=call_hooks)
+        finally:
+            self.command = cmd
+            view.index = index
+            view.previous = previous
+            self.invoked_with = invoked_with
+            self.invoked_subcommand = invoked_subcommand
+            self.subcommand_passed = subcommand_passed
+
+    @property
+    def valid(self):
+        """Checks if the invocation context is valid to be invoked with."""
+        return self.prefix is not None and self.command is not None
+
+    async def _get_channel(self):
+        return self.channel
+
+    @property
+    def cog(self):
+        """Returns the cog associated with this context's command. None if it does not exist."""
+
+        if self.command is None:
+            return None
+        return self.command.instance
+
+    @discord.utils.cached_property
+    def guild(self):
+        """Returns the guild associated with this context's command. None if not available."""
+        return self.message.guild
+
+    @discord.utils.cached_property
+    def channel(self):
+        """Returns the channel associated with this context's command. Shorthand for :attr:`Message.channel`."""
+        return self.message.channel
+
+    @discord.utils.cached_property
+    def author(self):
+        """Returns the author associated with this context's command. Shorthand for :attr:`Message.author`"""
+        return self.message.author
+
+    @discord.utils.cached_property
+    def me(self):
+        """Similar to :attr:`Guild.me` except it may return the :class:`ClientUser` in private message contexts."""
+        return self.guild.me if self.guild is not None else self.bot.user
+
+    @property
+    def voice_client(self):
+        r"""Optional[:class:`VoiceClient`]: A shortcut to :attr:`Guild.voice_client`\, if applicable."""
+        g = self.guild
+        return g.voice_client if g else None

discord/ext/commands/converter.py

@@ -0,0 +1,560 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import re
+import inspect
+
+import discord
+
+from .errors import BadArgument, NoPrivateMessage
+
+__all__ = [
+    "Converter",
+    "MemberConverter",
+    "UserConverter",
+    "TextChannelConverter",
+    "InviteConverter",
+    "RoleConverter",
+    "GameConverter",
+    "ColourConverter",
+    "VoiceChannelConverter",
+    "EmojiConverter",
+    "PartialEmojiConverter",
+    "CategoryChannelConverter",
+    "IDConverter",
+    "clean_content",
+    "Greedy",
+]
+
+
+def _get_from_guilds(bot, getter, argument):
+    result = None
+    for guild in bot.guilds:
+        result = getattr(guild, getter)(argument)
+        if result:
+            return result
+    return result
+
+
+class Converter:
+    """The base class of custom converters that require the :class:`.Context`
+    to be passed to be useful.
+
+    This allows you to implement converters that function similar to the
+    special cased ``discord`` classes.
+
+    Classes that derive from this should override the :meth:`~.Converter.convert`
+    method to do its conversion logic. This method must be a coroutine.
+    """
+
+    async def convert(self, ctx, argument):
+        """|coro|
+
+        The method to override to do conversion logic.
+
+        If an error is found while converting, it is recommended to
+        raise a :exc:`.CommandError` derived exception as it will
+        properly propagate to the error handlers.
+
+        Parameters
+        -----------
+        ctx: :class:`.Context`
+            The invocation context that the argument is being used in.
+        argument: str
+            The argument that is being converted.
+        """
+        raise NotImplementedError("Derived classes need to implement this.")
+
+
+class IDConverter(Converter):
+    def __init__(self):
+        self._id_regex = re.compile(r"([0-9]{15,21})$")
+        super().__init__()
+
+    def _get_id_match(self, argument):
+        return self._id_regex.match(argument)
+
+
+class MemberConverter(IDConverter):
+    """Converts to a :class:`Member`.
+
+    All lookups are via the local guild. If in a DM context, then the lookup
+    is done by the global cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by mention.
+    3. Lookup by name#discrim
+    4. Lookup by name
+    5. Lookup by nickname
+    """
+
+    async def convert(self, ctx, argument):
+        bot = ctx.bot
+        match = self._get_id_match(argument) or re.match(r"<@!?([0-9]+)>$", argument)
+        guild = ctx.guild
+        result = None
+        if match is None:
+            # not a mention...
+            if guild:
+                result = guild.get_member_named(argument)
+            else:
+                result = _get_from_guilds(bot, "get_member_named", argument)
+        else:
+            user_id = int(match.group(1))
+            if guild:
+                result = guild.get_member(user_id)
+            else:
+                result = _get_from_guilds(bot, "get_member", user_id)
+
+        if result is None:
+            raise BadArgument('Member "{}" not found'.format(argument))
+
+        return result
+
+
+class UserConverter(IDConverter):
+    """Converts to a :class:`User`.
+
+    All lookups are via the global user cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by mention.
+    3. Lookup by name#discrim
+    4. Lookup by name
+    """
+
+    async def convert(self, ctx, argument):
+        match = self._get_id_match(argument) or re.match(r"<@!?([0-9]+)>$", argument)
+        result = None
+        state = ctx._state
+
+        if match is not None:
+            user_id = int(match.group(1))
+            result = ctx.bot.get_user(user_id)
+        else:
+            arg = argument
+            # check for discriminator if it exists
+            if len(arg) > 5 and arg[-5] == "#":
+                discrim = arg[-4:]
+                name = arg[:-5]
+                predicate = lambda u: u.name == name and u.discriminator == discrim
+                result = discord.utils.find(predicate, state._users.values())
+                if result is not None:
+                    return result
+
+            predicate = lambda u: u.name == arg
+            result = discord.utils.find(predicate, state._users.values())
+
+        if result is None:
+            raise BadArgument('User "{}" not found'.format(argument))
+
+        return result
+
+
+class TextChannelConverter(IDConverter):
+    """Converts to a :class:`TextChannel`.
+
+    All lookups are via the local guild. If in a DM context, then the lookup
+    is done by the global cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by mention.
+    3. Lookup by name
+    """
+
+    async def convert(self, ctx, argument):
+        bot = ctx.bot
+
+        match = self._get_id_match(argument) or re.match(r"<#([0-9]+)>$", argument)
+        result = None
+        guild = ctx.guild
+
+        if match is None:
+            # not a mention
+            if guild:
+                result = discord.utils.get(guild.text_channels, name=argument)
+            else:
+
+                def check(c):
+                    return isinstance(c, discord.TextChannel) and c.name == argument
+
+                result = discord.utils.find(check, bot.get_all_channels())
+        else:
+            channel_id = int(match.group(1))
+            if guild:
+                result = guild.get_channel(channel_id)
+            else:
+                result = _get_from_guilds(bot, "get_channel", channel_id)
+
+        if not isinstance(result, discord.TextChannel):
+            raise BadArgument('Channel "{}" not found.'.format(argument))
+
+        return result
+
+
+class VoiceChannelConverter(IDConverter):
+    """Converts to a :class:`VoiceChannel`.
+
+    All lookups are via the local guild. If in a DM context, then the lookup
+    is done by the global cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by mention.
+    3. Lookup by name
+    """
+
+    async def convert(self, ctx, argument):
+        bot = ctx.bot
+        match = self._get_id_match(argument) or re.match(r"<#([0-9]+)>$", argument)
+        result = None
+        guild = ctx.guild
+
+        if match is None:
+            # not a mention
+            if guild:
+                result = discord.utils.get(guild.voice_channels, name=argument)
+            else:
+
+                def check(c):
+                    return isinstance(c, discord.VoiceChannel) and c.name == argument
+
+                result = discord.utils.find(check, bot.get_all_channels())
+        else:
+            channel_id = int(match.group(1))
+            if guild:
+                result = guild.get_channel(channel_id)
+            else:
+                result = _get_from_guilds(bot, "get_channel", channel_id)
+
+        if not isinstance(result, discord.VoiceChannel):
+            raise BadArgument('Channel "{}" not found.'.format(argument))
+
+        return result
+
+
+class CategoryChannelConverter(IDConverter):
+    """Converts to a :class:`CategoryChannel`.
+
+    All lookups are via the local guild. If in a DM context, then the lookup
+    is done by the global cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by mention.
+    3. Lookup by name
+    """
+
+    async def convert(self, ctx, argument):
+        bot = ctx.bot
+
+        match = self._get_id_match(argument) or re.match(r"<#([0-9]+)>$", argument)
+        result = None
+        guild = ctx.guild
+
+        if match is None:
+            # not a mention
+            if guild:
+                result = discord.utils.get(guild.categories, name=argument)
+            else:
+
+                def check(c):
+                    return isinstance(c, discord.CategoryChannel) and c.name == argument
+
+                result = discord.utils.find(check, bot.get_all_channels())
+        else:
+            channel_id = int(match.group(1))
+            if guild:
+                result = guild.get_channel(channel_id)
+            else:
+                result = _get_from_guilds(bot, "get_channel", channel_id)
+
+        if not isinstance(result, discord.CategoryChannel):
+            raise BadArgument('Channel "{}" not found.'.format(argument))
+
+        return result
+
+
+class ColourConverter(Converter):
+    """Converts to a :class:`Colour`.
+
+    The following formats are accepted:
+
+    - ``0x<hex>``
+    - ``#<hex>``
+    - ``0x#<hex>``
+    - Any of the ``classmethod`` in :class:`Colour`
+
+        - The ``_`` in the name can be optionally replaced with spaces.
+    """
+
+    async def convert(self, ctx, argument):
+        arg = argument.replace("0x", "").lower()
+
+        if arg[0] == "#":
+            arg = arg[1:]
+        try:
+            value = int(arg, base=16)
+            return discord.Colour(value=value)
+        except ValueError:
+            method = getattr(discord.Colour, arg.replace(" ", "_"), None)
+            if method is None or not inspect.ismethod(method):
+                raise BadArgument('Colour "{}" is invalid.'.format(arg))
+            return method()
+
+
+class RoleConverter(IDConverter):
+    """Converts to a :class:`Role`.
+
+
+    All lookups are via the local guild. If in a DM context, then the lookup
+    is done by the global cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by mention.
+    3. Lookup by name
+    """
+
+    async def convert(self, ctx, argument):
+        guild = ctx.guild
+        if not guild:
+            raise NoPrivateMessage()
+
+        match = self._get_id_match(argument) or re.match(r"<@&([0-9]+)>$", argument)
+        if match:
+            result = guild.get_role(int(match.group(1)))
+        else:
+            result = discord.utils.get(guild._roles.values(), name=argument)
+
+        if result is None:
+            raise BadArgument('Role "{}" not found.'.format(argument))
+        return result
+
+
+class GameConverter(Converter):
+    """Converts to :class:`Game`."""
+
+    async def convert(self, ctx, argument):
+        return discord.Game(name=argument)
+
+
+class InviteConverter(Converter):
+    """Converts to a :class:`Invite`.
+
+    This is done via an HTTP request using :meth:`.Bot.get_invite`.
+    """
+
+    async def convert(self, ctx, argument):
+        try:
+            invite = await ctx.bot.get_invite(argument)
+            return invite
+        except Exception as exc:
+            raise BadArgument("Invite is invalid or expired") from exc
+
+
+class EmojiConverter(IDConverter):
+    """Converts to a :class:`Emoji`.
+
+
+    All lookups are done for the local guild first, if available. If that lookup
+    fails, then it checks the client's global cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by extracting ID from the emoji.
+    3. Lookup by name
+    """
+
+    async def convert(self, ctx, argument):
+        match = self._get_id_match(argument) or re.match(
+            r"<a?:[a-zA-Z0-9\_]+:([0-9]+)>$", argument
+        )
+        result = None
+        bot = ctx.bot
+        guild = ctx.guild
+
+        if match is None:
+            # Try to get the emoji by name. Try local guild first.
+            if guild:
+                result = discord.utils.get(guild.emojis, name=argument)
+
+            if result is None:
+                result = discord.utils.get(bot.emojis, name=argument)
+        else:
+            emoji_id = int(match.group(1))
+
+            # Try to look up emoji by id.
+            if guild:
+                result = discord.utils.get(guild.emojis, id=emoji_id)
+
+            if result is None:
+                result = discord.utils.get(bot.emojis, id=emoji_id)
+
+        if result is None:
+            raise BadArgument('Emoji "{}" not found.'.format(argument))
+
+        return result
+
+
+class PartialEmojiConverter(Converter):
+    """Converts to a :class:`PartialEmoji`.
+
+
+    This is done by extracting the animated flag, name and ID from the emoji.
+    """
+
+    async def convert(self, ctx, argument):
+        match = re.match(r"<(a?):([a-zA-Z0-9\_]+):([0-9]+)>$", argument)
+
+        if match:
+            emoji_animated = bool(match.group(1))
+            emoji_name = match.group(2)
+            emoji_id = int(match.group(3))
+
+            return discord.PartialEmoji(animated=emoji_animated, name=emoji_name, id=emoji_id)
+
+        raise BadArgument('Couldn\'t convert "{}" to PartialEmoji.'.format(argument))
+
+
+class clean_content(Converter):
+    """Converts the argument to mention scrubbed version of
+    said content.
+
+    This behaves similarly to :attr:`.Message.clean_content`.
+
+    Attributes
+    ------------
+    fix_channel_mentions: :obj:`bool`
+        Whether to clean channel mentions.
+    use_nicknames: :obj:`bool`
+        Whether to use nicknames when transforming mentions.
+    escape_markdown: :obj:`bool`
+        Whether to also escape special markdown characters.
+    """
+
+    def __init__(self, *, fix_channel_mentions=False, use_nicknames=True, escape_markdown=False):
+        self.fix_channel_mentions = fix_channel_mentions
+        self.use_nicknames = use_nicknames
+        self.escape_markdown = escape_markdown
+
+    async def convert(self, ctx, argument):
+        message = ctx.message
+        transformations = {}
+
+        if self.fix_channel_mentions and ctx.guild:
+
+            def resolve_channel(id, *, _get=ctx.guild.get_channel):
+                ch = _get(id)
+                return ("<#%s>" % id), ("#" + ch.name if ch else "#deleted-channel")
+
+            transformations.update(
+                resolve_channel(channel) for channel in message.raw_channel_mentions
+            )
+
+        if self.use_nicknames and ctx.guild:
+
+            def resolve_member(id, *, _get=ctx.guild.get_member):
+                m = _get(id)
+                return "@" + m.display_name if m else "@deleted-user"
+
+        else:
+
+            def resolve_member(id, *, _get=ctx.bot.get_user):
+                m = _get(id)
+                return "@" + m.name if m else "@deleted-user"
+
+        transformations.update(
+            ("<@%s>" % member_id, resolve_member(member_id)) for member_id in message.raw_mentions
+        )
+
+        transformations.update(
+            ("<@!%s>" % member_id, resolve_member(member_id)) for member_id in message.raw_mentions
+        )
+
+        if ctx.guild:
+
+            def resolve_role(_id, *, _find=ctx.guild.get_role):
+                r = _find(_id)
+                return "@" + r.name if r else "@deleted-role"
+
+            transformations.update(
+                ("<@&%s>" % role_id, resolve_role(role_id))
+                for role_id in message.raw_role_mentions
+            )
+
+        def repl(obj):
+            return transformations.get(obj.group(0), "")
+
+        pattern = re.compile("|".join(transformations.keys()))
+        result = pattern.sub(repl, argument)
+
+        if self.escape_markdown:
+            transformations = {re.escape(c): "\\" + c for c in ("*", "`", "_", "~", "\\", "||")}
+
+            def replace(obj):
+                return transformations.get(re.escape(obj.group(0)), "")
+
+            pattern = re.compile("|".join(transformations.keys()))
+            result = pattern.sub(replace, result)
+
+        # Completely ensure no mentions escape:
+        return re.sub(r"@(everyone|here|[!&]?[0-9]{17,21})", "@\u200b\\1", result)
+
+
+class _Greedy:
+    __slots__ = ("converter",)
+
+    def __init__(self, *, converter=None):
+        self.converter = converter
+
+    def __getitem__(self, params):
+        if not isinstance(params, tuple):
+            params = (params,)
+        if len(params) != 1:
+            raise TypeError("Greedy[...] only takes a single argument")
+        converter = params[0]
+
+        if not inspect.isclass(converter):
+            raise TypeError("Greedy[...] expects a type.")
+
+        if converter is str or converter is type(None) or converter is _Greedy:
+            raise TypeError("Greedy[%s] is invalid." % converter.__name__)
+
+        return self.__class__(converter=converter)
+
+
+Greedy = _Greedy()

discord/ext/commands/cooldowns.py

@@ -0,0 +1,148 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import enum
+import time
+
+__all__ = ["BucketType", "Cooldown", "CooldownMapping"]
+
+
+class BucketType(enum.Enum):
+    default = 0
+    user = 1
+    guild = 2
+    channel = 3
+    member = 4
+    category = 5
+
+
+class Cooldown:
+    __slots__ = ("rate", "per", "type", "_window", "_tokens", "_last")
+
+    def __init__(self, rate, per, type):
+        self.rate = int(rate)
+        self.per = float(per)
+        self.type = type
+        self._window = 0.0
+        self._tokens = self.rate
+        self._last = 0.0
+
+        if not isinstance(self.type, BucketType):
+            raise TypeError("Cooldown type must be a BucketType")
+
+    def get_tokens(self, current=None):
+        if not current:
+            current = time.time()
+
+        tokens = self._tokens
+
+        if current > self._window + self.per:
+            tokens = self.rate
+        return tokens
+
+    def update_rate_limit(self):
+        current = time.time()
+        self._last = current
+
+        self._tokens = self.get_tokens(current)
+
+        # first token used means that we start a new rate limit window
+        if self._tokens == self.rate:
+            self._window = current
+
+        # check if we are rate limited
+        if self._tokens == 0:
+            return self.per - (current - self._window)
+
+        # we're not so decrement our tokens
+        self._tokens -= 1
+
+        # see if we got rate limited due to this token change, and if
+        # so update the window to point to our current time frame
+        if self._tokens == 0:
+            self._window = current
+
+    def reset(self):
+        self._tokens = self.rate
+        self._last = 0.0
+
+    def copy(self):
+        return Cooldown(self.rate, self.per, self.type)
+
+    def __repr__(self):
+        return "<Cooldown rate: {0.rate} per: {0.per} window: {0._window} tokens: {0._tokens}>".format(
+            self
+        )
+
+
+class CooldownMapping:
+    def __init__(self, original):
+        self._cache = {}
+        self._cooldown = original
+
+    @property
+    def valid(self):
+        return self._cooldown is not None
+
+    @classmethod
+    def from_cooldown(cls, rate, per, type):
+        return cls(Cooldown(rate, per, type))
+
+    def _bucket_key(self, msg):
+        bucket_type = self._cooldown.type
+        if bucket_type is BucketType.user:
+            return msg.author.id
+        elif bucket_type is BucketType.guild:
+            return (msg.guild or msg.author).id
+        elif bucket_type is BucketType.channel:
+            return msg.channel.id
+        elif bucket_type is BucketType.member:
+            return ((msg.guild and msg.guild.id), msg.author.id)
+        elif bucket_type is BucketType.category:
+            return (msg.channel.category or msg.channel).id
+
+    def _verify_cache_integrity(self):
+        # we want to delete all cache objects that haven't been used
+        # in a cooldown window. e.g. if we have a  command that has a
+        # cooldown of 60s and it has not been used in 60s then that key should be deleted
+        current = time.time()
+        dead_keys = [k for k, v in self._cache.items() if current > v._last + v.per]
+        for k in dead_keys:
+            del self._cache[k]
+
+    def get_bucket(self, message):
+        if self._cooldown.type is BucketType.default:
+            return self._cooldown
+
+        self._verify_cache_integrity()
+        key = self._bucket_key(message)
+        if key not in self._cache:
+            bucket = self._cooldown.copy()
+            self._cache[key] = bucket
+        else:
+            bucket = self._cache[key]
+
+        return bucket

discord/ext/commands/errors.py

@@ -0,0 +1,279 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from discord.errors import DiscordException
+
+
+__all__ = [
+    "CommandError",
+    "MissingRequiredArgument",
+    "BadArgument",
+    "NoPrivateMessage",
+    "CheckFailure",
+    "CommandNotFound",
+    "DisabledCommand",
+    "CommandInvokeError",
+    "TooManyArguments",
+    "UserInputError",
+    "CommandOnCooldown",
+    "NotOwner",
+    "MissingPermissions",
+    "BotMissingPermissions",
+    "ConversionError",
+    "BadUnionArgument",
+]
+
+
+class CommandError(DiscordException):
+    r"""The base exception type for all command related errors.
+
+    This inherits from :exc:`discord.DiscordException`.
+
+    This exception and exceptions derived from it are handled
+    in a special way as they are caught and passed into a special event
+    from :class:`.Bot`\, :func:`on_command_error`.
+    """
+
+    def __init__(self, message=None, *args):
+        if message is not None:
+            # clean-up @everyone and @here mentions
+            m = message.replace("@everyone", "@\u200beveryone").replace("@here", "@\u200bhere")
+            super().__init__(m, *args)
+        else:
+            super().__init__(*args)
+
+
+class ConversionError(CommandError):
+    """Exception raised when a Converter class raises non-CommandError.
+
+    This inherits from :exc:`.CommandError`.
+
+    Attributes
+    ----------
+    converter: :class:`discord.ext.commands.Converter`
+        The converter that failed.
+    original
+        The original exception that was raised. You can also get this via
+        the ``__cause__`` attribute.
+    """
+
+    def __init__(self, converter, original):
+        self.converter = converter
+        self.original = original
+
+
+class UserInputError(CommandError):
+    """The base exception type for errors that involve errors
+    regarding user input.
+
+    This inherits from :exc:`.CommandError`.
+    """
+
+    pass
+
+
+class CommandNotFound(CommandError):
+    """Exception raised when a command is attempted to be invoked
+    but no command under that name is found.
+
+    This is not raised for invalid subcommands, rather just the
+    initial main command that is attempted to be invoked.
+    """
+
+    pass
+
+
+class MissingRequiredArgument(UserInputError):
+    """Exception raised when parsing a command and a parameter
+    that is required is not encountered.
+
+    Attributes
+    -----------
+    param: :class:`inspect.Parameter`
+        The argument that is missing.
+    """
+
+    def __init__(self, param):
+        self.param = param
+        super().__init__("{0.name} is a required argument that is missing.".format(param))
+
+
+class TooManyArguments(UserInputError):
+    """Exception raised when the command was passed too many arguments and its
+    :attr:`.Command.ignore_extra` attribute was not set to ``True``.
+    """
+
+    pass
+
+
+class BadArgument(UserInputError):
+    """Exception raised when a parsing or conversion failure is encountered
+    on an argument to pass into a command.
+    """
+
+    pass
+
+
+class CheckFailure(CommandError):
+    """Exception raised when the predicates in :attr:`.Command.checks` have failed."""
+
+    pass
+
+
+class NoPrivateMessage(CheckFailure):
+    """Exception raised when an operation does not work in private message
+    contexts.
+    """
+
+    pass
+
+
+class NotOwner(CheckFailure):
+    """Exception raised when the message author is not the owner of the bot."""
+
+    pass
+
+
+class DisabledCommand(CommandError):
+    """Exception raised when the command being invoked is disabled."""
+
+    pass
+
+
+class CommandInvokeError(CommandError):
+    """Exception raised when the command being invoked raised an exception.
+
+    Attributes
+    -----------
+    original
+        The original exception that was raised. You can also get this via
+        the ``__cause__`` attribute.
+    """
+
+    def __init__(self, e):
+        self.original = e
+        super().__init__("Command raised an exception: {0.__class__.__name__}: {0}".format(e))
+
+
+class CommandOnCooldown(CommandError):
+    """Exception raised when the command being invoked is on cooldown.
+
+    Attributes
+    -----------
+    cooldown: Cooldown
+        A class with attributes ``rate``, ``per``, and ``type`` similar to
+        the :func:`.cooldown` decorator.
+    retry_after: :class:`float`
+        The amount of seconds to wait before you can retry again.
+    """
+
+    def __init__(self, cooldown, retry_after):
+        self.cooldown = cooldown
+        self.retry_after = retry_after
+        super().__init__("You are on cooldown. Try again in {:.2f}s".format(retry_after))
+
+
+class MissingPermissions(CheckFailure):
+    """Exception raised when the command invoker lacks permissions to run
+    command.
+
+    Attributes
+    -----------
+    missing_perms: :class:`list`
+        The required permissions that are missing.
+    """
+
+    def __init__(self, missing_perms, *args):
+        self.missing_perms = missing_perms
+
+        missing = [
+            perm.replace("_", " ").replace("guild", "server").title() for perm in missing_perms
+        ]
+
+        if len(missing) > 2:
+            fmt = "{}, and {}".format(", ".join(missing[:-1]), missing[-1])
+        else:
+            fmt = " and ".join(missing)
+        message = "You are missing {} permission(s) to run command.".format(fmt)
+        super().__init__(message, *args)
+
+
+class BotMissingPermissions(CheckFailure):
+    """Exception raised when the bot lacks permissions to run command.
+
+    Attributes
+    -----------
+    missing_perms: :class:`list`
+        The required permissions that are missing.
+    """
+
+    def __init__(self, missing_perms, *args):
+        self.missing_perms = missing_perms
+
+        missing = [
+            perm.replace("_", " ").replace("guild", "server").title() for perm in missing_perms
+        ]
+
+        if len(missing) > 2:
+            fmt = "{}, and {}".format(", ".join(missing[:-1]), missing[-1])
+        else:
+            fmt = " and ".join(missing)
+        message = "Bot requires {} permission(s) to run command.".format(fmt)
+        super().__init__(message, *args)
+
+
+class BadUnionArgument(UserInputError):
+    """Exception raised when a :class:`typing.Union` converter fails for all
+    its associated types.
+
+    Attributes
+    -----------
+    param: :class:`inspect.Parameter`
+        The parameter that failed being converted.
+    converters: Tuple[Type, ...]
+        A tuple of converters attempted in conversion, in order of failure.
+    errors: List[:class:`CommandError`]
+        A list of errors that were caught from failing the conversion.
+    """
+
+    def __init__(self, param, converters, errors):
+        self.param = param
+        self.converters = converters
+        self.errors = errors
+
+        def _get_name(x):
+            try:
+                return x.__name__
+            except AttributeError:
+                return x.__class__.__name__
+
+        to_string = [_get_name(x) for x in converters]
+        if len(to_string) > 2:
+            fmt = "{}, or {}".format(", ".join(to_string[:-1]), to_string[-1])
+        else:
+            fmt = " or ".join(to_string)
+
+        super().__init__('Could not convert "{0.name}" into {1}.'.format(param, fmt))

discord/ext/commands/formatter.py

@@ -0,0 +1,370 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import itertools
+import inspect
+import discord.utils
+
+from .core import GroupMixin, Command
+from .errors import CommandError
+
+# from discord.iterators import _FilteredAsyncIterator
+
+# help -> shows info of bot on top/bottom and lists subcommands
+# help command -> shows detailed info of command
+# help command <subcommand chain> -> same as above
+
+# <description>
+
+# <command signature with aliases>
+
+# <long doc>
+
+# Cog:
+#   <command> <shortdoc>
+#   <command> <shortdoc>
+# Other Cog:
+#   <command> <shortdoc>
+# No Category:
+#   <command> <shortdoc>
+
+# Type <prefix>help command for more info on a command.
+# You can also type <prefix>help category for more info on a category.
+
+
+class Paginator:
+    """A class that aids in paginating code blocks for Discord messages.
+
+    Attributes
+    -----------
+    prefix: :class:`str`
+        The prefix inserted to every page. e.g. three backticks.
+    suffix: :class:`str`
+        The suffix appended at the end of every page. e.g. three backticks.
+    max_size: :class:`int`
+        The maximum amount of codepoints allowed in a page.
+    """
+
+    def __init__(self, prefix="```", suffix="```", max_size=2000):
+        self.prefix = prefix
+        self.suffix = suffix
+        self.max_size = max_size - len(suffix)
+        self._current_page = [prefix]
+        self._count = len(prefix) + 1  # prefix + newline
+        self._pages = []
+
+    def add_line(self, line="", *, empty=False):
+        """Adds a line to the current page.
+
+        If the line exceeds the :attr:`max_size` then an exception
+        is raised.
+
+        Parameters
+        -----------
+        line: str
+            The line to add.
+        empty: bool
+            Indicates if another empty line should be added.
+
+        Raises
+        ------
+        RuntimeError
+            The line was too big for the current :attr:`max_size`.
+        """
+        if len(line) > self.max_size - len(self.prefix) - 2:
+            raise RuntimeError(
+                "Line exceeds maximum page size %s" % (self.max_size - len(self.prefix) - 2)
+            )
+
+        if self._count + len(line) + 1 > self.max_size:
+            self.close_page()
+
+        self._count += len(line) + 1
+        self._current_page.append(line)
+
+        if empty:
+            self._current_page.append("")
+            self._count += 1
+
+    def close_page(self):
+        """Prematurely terminate a page."""
+        self._current_page.append(self.suffix)
+        self._pages.append("\n".join(self._current_page))
+        self._current_page = [self.prefix]
+        self._count = len(self.prefix) + 1  # prefix + newline
+
+    @property
+    def pages(self):
+        """Returns the rendered list of pages."""
+        # we have more than just the prefix in our current page
+        if len(self._current_page) > 1:
+            self.close_page()
+        return self._pages
+
+    def __repr__(self):
+        fmt = "<Paginator prefix: {0.prefix} suffix: {0.suffix} max_size: {0.max_size} count: {0._count}>"
+        return fmt.format(self)
+
+
+class HelpFormatter:
+    """The default base implementation that handles formatting of the help
+    command.
+
+    To override the behaviour of the formatter, :meth:`~.HelpFormatter.format`
+    should be overridden. A number of utility functions are provided for use
+    inside that method.
+
+    Attributes
+    -----------
+    show_hidden: :class:`bool`
+        Dictates if hidden commands should be shown in the output.
+        Defaults to ``False``.
+    show_check_failure: :class:`bool`
+        Dictates if commands that have their :attr:`.Command.checks` failed
+        shown. Defaults to ``False``.
+    width: :class:`int`
+        The maximum number of characters that fit in a line.
+        Defaults to 80.
+    """
+
+    def __init__(self, show_hidden=False, show_check_failure=False, width=80):
+        self.width = width
+        self.show_hidden = show_hidden
+        self.show_check_failure = show_check_failure
+
+    def has_subcommands(self):
+        """:class:`bool`: Specifies if the command has subcommands."""
+        return isinstance(self.command, GroupMixin)
+
+    def is_bot(self):
+        """:class:`bool`: Specifies if the command being formatted is the bot itself."""
+        return self.command is self.context.bot
+
+    def is_cog(self):
+        """:class:`bool`: Specifies if the command being formatted is actually a cog."""
+        return not self.is_bot() and not isinstance(self.command, Command)
+
+    def shorten(self, text):
+        """Shortens text to fit into the :attr:`width`."""
+        if len(text) > self.width:
+            return text[: self.width - 3] + "..."
+        return text
+
+    @property
+    def max_name_size(self):
+        """:class:`int`: Returns the largest name length of a command or if it has subcommands
+        the largest subcommand name."""
+        try:
+            commands = (
+                self.command.all_commands if not self.is_cog() else self.context.bot.all_commands
+            )
+            if commands:
+                return max(
+                    map(
+                        lambda c: discord.utils._string_width(c.name)
+                        if self.show_hidden or not c.hidden
+                        else 0,
+                        commands.values(),
+                    )
+                )
+            return 0
+        except AttributeError:
+            return len(self.command.name)
+
+    @property
+    def clean_prefix(self):
+        """The cleaned up invoke prefix. i.e. mentions are ``@name`` instead of ``<@id>``."""
+        user = self.context.guild.me if self.context.guild else self.context.bot.user
+        # this breaks if the prefix mention is not the bot itself but I
+        # consider this to be an *incredibly* strange use case. I'd rather go
+        # for this common use case rather than waste performance for the
+        # odd one.
+        return self.context.prefix.replace(user.mention, "@" + user.display_name)
+
+    def get_command_signature(self):
+        """Retrieves the signature portion of the help page."""
+        prefix = self.clean_prefix
+        cmd = self.command
+        return prefix + cmd.signature
+
+    def get_ending_note(self):
+        command_name = self.context.invoked_with
+        return (
+            "Type {0}{1} command for more info on a command.\n"
+            "You can also type {0}{1} category for more info on a category.".format(
+                self.clean_prefix, command_name
+            )
+        )
+
+    async def filter_command_list(self):
+        """Returns a filtered list of commands based on the two attributes
+        provided, :attr:`show_check_failure` and :attr:`show_hidden`.
+        Also filters based on if :meth:`~.HelpFormatter.is_cog` is valid.
+
+        Returns
+        --------
+        iterable
+            An iterable with the filter being applied. The resulting value is
+            a (key, value) :class:`tuple` of the command name and the command itself.
+        """
+
+        def sane_no_suspension_point_predicate(tup):
+            cmd = tup[1]
+            if self.is_cog():
+                # filter commands that don't exist to this cog.
+                if cmd.instance is not self.command:
+                    return False
+
+            if cmd.hidden and not self.show_hidden:
+                return False
+
+            return True
+
+        async def predicate(tup):
+            if sane_no_suspension_point_predicate(tup) is False:
+                return False
+
+            cmd = tup[1]
+            try:
+                return await cmd.can_run(self.context)
+            except CommandError:
+                return False
+
+        iterator = (
+            self.command.all_commands.items()
+            if not self.is_cog()
+            else self.context.bot.all_commands.items()
+        )
+        if self.show_check_failure:
+            return filter(sane_no_suspension_point_predicate, iterator)
+
+        # Gotta run every check and verify it
+        ret = []
+        for elem in iterator:
+            valid = await predicate(elem)
+            if valid:
+                ret.append(elem)
+
+        return ret
+
+    def _add_subcommands_to_page(self, max_width, commands):
+        for name, command in commands:
+            if name in command.aliases:
+                # skip aliases
+                continue
+            width_gap = discord.utils._string_width(name) - len(name)
+            entry = "  {0:<{width}} {1}".format(
+                name, command.short_doc, width=max_width - width_gap
+            )
+            shortened = self.shorten(entry)
+            self._paginator.add_line(shortened)
+
+    async def format_help_for(self, context, command_or_bot):
+        """Formats the help page and handles the actual heavy lifting of how
+        the help command looks like. To change the behaviour, override the
+        :meth:`~.HelpFormatter.format` method.
+
+        Parameters
+        -----------
+        context: :class:`.Context`
+            The context of the invoked help command.
+        command_or_bot: :class:`.Command` or :class:`.Bot`
+            The bot or command that we are getting the help of.
+
+        Returns
+        --------
+        list
+            A paginated output of the help command.
+        """
+        self.context = context
+        self.command = command_or_bot
+        return await self.format()
+
+    async def format(self):
+        """Handles the actual behaviour involved with formatting.
+
+        To change the behaviour, this method should be overridden.
+
+        Returns
+        --------
+        list
+            A paginated output of the help command.
+        """
+        self._paginator = Paginator()
+
+        # we need a padding of ~80 or so
+
+        description = (
+            self.command.description if not self.is_cog() else inspect.getdoc(self.command)
+        )
+
+        if description:
+            # <description> portion
+            self._paginator.add_line(description, empty=True)
+
+        if isinstance(self.command, Command):
+            # <signature portion>
+            signature = self.get_command_signature()
+            self._paginator.add_line(signature, empty=True)
+
+            # <long doc> section
+            if self.command.help:
+                self._paginator.add_line(self.command.help, empty=True)
+
+            # end it here if it's just a regular command
+            if not self.has_subcommands():
+                self._paginator.close_page()
+                return self._paginator.pages
+
+        max_width = self.max_name_size
+
+        def category(tup):
+            cog = tup[1].cog_name
+            # we insert the zero width space there to give it approximate
+            # last place sorting position.
+            return cog + ":" if cog is not None else "\u200bNo Category:"
+
+        filtered = await self.filter_command_list()
+        if self.is_bot():
+            data = sorted(filtered, key=category)
+            for category, commands in itertools.groupby(data, key=category):
+                # there simply is no prettier way of doing this.
+                commands = sorted(commands)
+                if len(commands) > 0:
+                    self._paginator.add_line(category)
+
+                self._add_subcommands_to_page(max_width, commands)
+        else:
+            filtered = sorted(filtered)
+            if filtered:
+                self._paginator.add_line("Commands:")
+                self._add_subcommands_to_page(max_width, filtered)
+
+        # add the ending note
+        self._paginator.add_line()
+        ending_note = self.get_ending_note()
+        self._paginator.add_line(ending_note)
+        return self._paginator.pages

discord/ext/commands/view.py

@@ -0,0 +1,201 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from .errors import BadArgument
+
+
+class StringView:
+    def __init__(self, buffer):
+        self.index = 0
+        self.buffer = buffer
+        self.end = len(buffer)
+        self.previous = 0
+
+    @property
+    def current(self):
+        return None if self.eof else self.buffer[self.index]
+
+    @property
+    def eof(self):
+        return self.index >= self.end
+
+    def undo(self):
+        self.index = self.previous
+
+    def skip_ws(self):
+        pos = 0
+        while not self.eof:
+            try:
+                current = self.buffer[self.index + pos]
+                if not current.isspace():
+                    break
+                pos += 1
+            except IndexError:
+                break
+
+        self.previous = self.index
+        self.index += pos
+        return self.previous != self.index
+
+    def skip_string(self, string):
+        strlen = len(string)
+        if self.buffer[self.index : self.index + strlen] == string:
+            self.previous = self.index
+            self.index += strlen
+            return True
+        return False
+
+    def read_rest(self):
+        result = self.buffer[self.index :]
+        self.previous = self.index
+        self.index = self.end
+        return result
+
+    def read(self, n):
+        result = self.buffer[self.index : self.index + n]
+        self.previous = self.index
+        self.index += n
+        return result
+
+    def get(self):
+        try:
+            result = self.buffer[self.index + 1]
+        except IndexError:
+            result = None
+
+        self.previous = self.index
+        self.index += 1
+        return result
+
+    def get_word(self):
+        pos = 0
+        while not self.eof:
+            try:
+                current = self.buffer[self.index + pos]
+                if current.isspace():
+                    break
+                pos += 1
+            except IndexError:
+                break
+        self.previous = self.index
+        result = self.buffer[self.index : self.index + pos]
+        self.index += pos
+        return result
+
+    def __repr__(self):
+        return "<StringView pos: {0.index} prev: {0.previous} end: {0.end} eof: {0.eof}>".format(
+            self
+        )
+
+
+# Parser
+
+# map from opening quotes to closing quotes
+_quotes = {
+    '"': '"',
+    "‘": "’",
+    "‚": "‛",
+    "“": "”",
+    "„": "‟",
+    "⹂": "⹂",
+    "「": "」",
+    "『": "』",
+    "〝": "〞",
+    "﹁": "﹂",
+    "﹃": "﹄",
+    "＂": "＂",
+    "｢": "｣",
+    "«": "»",
+    "‹": "›",
+    "《": "》",
+    "〈": "〉",
+}
+_all_quotes = set(_quotes.keys()) | set(_quotes.values())
+
+
+def quoted_word(view):
+    current = view.current
+
+    if current is None:
+        return None
+
+    close_quote = _quotes.get(current)
+    is_quoted = bool(close_quote)
+    if is_quoted:
+        result = []
+        _escaped_quotes = (current, close_quote)
+    else:
+        result = [current]
+        _escaped_quotes = _all_quotes
+
+    while not view.eof:
+        current = view.get()
+        if not current:
+            if is_quoted:
+                # unexpected EOF
+                raise BadArgument("Expected closing {}.".format(close_quote))
+            return "".join(result)
+
+        # currently we accept strings in the format of "hello world"
+        # to embed a quote inside the string you must escape it: "a \"world\""
+        if current == "\\":
+            next_char = view.get()
+            if not next_char:
+                # string ends with \ and no character after it
+                if is_quoted:
+                    # if we're quoted then we're expecting a closing quote
+                    raise BadArgument("Expected closing {}.".format(close_quote))
+                # if we aren't then we just let it through
+                return "".join(result)
+
+            if next_char in _escaped_quotes:
+                # escaped quote
+                result.append(next_char)
+            else:
+                # different escape character, ignore it
+                view.undo()
+                result.append(current)
+            continue
+
+        if not is_quoted and current in _all_quotes:
+            # we aren't quoted
+            raise BadArgument("Unexpected quote mark in non-quoted string")
+
+        # closing quote
+        if is_quoted and current == close_quote:
+            next_char = view.get()
+            valid_eof = not next_char or next_char.isspace()
+            if not valid_eof:
+                raise BadArgument("Expected space after closing quotation")
+
+            # we're quoted so it's okay
+            return "".join(result)
+
+        if current.isspace() and not is_quoted:
+            # end of word found
+            return "".join(result)
+
+        result.append(current)

discord/file.py

@@ -0,0 +1,81 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import os.path
+
+
+class File:
+    """A parameter object used for :meth:`abc.Messageable.send`
+    for sending file objects.
+
+    Attributes
+    -----------
+    fp: Union[:class:`str`, BinaryIO]
+        A file-like object opened in binary mode and read mode
+        or a filename representing a file in the hard drive to
+        open.
+
+        .. note::
+
+            If the file-like object passed is opened via ``open`` then the
+            modes 'rb' should be used.
+
+            To pass binary data, consider usage of ``io.BytesIO``.
+
+    filename: Optional[:class:`str`]
+        The filename to display when uploading to Discord.
+        If this is not given then it defaults to ``fp.name`` or if ``fp`` is
+        a string then the ``filename`` will default to the string given.
+    spoiler: :class:`bool`
+        Whether the attachment is a spoiler.
+    """
+
+    __slots__ = ("fp", "filename", "_true_fp")
+
+    def __init__(self, fp, filename=None, *, spoiler=False):
+        self.fp = fp
+        self._true_fp = None
+
+        if filename is None:
+            if isinstance(fp, str):
+                _, self.filename = os.path.split(fp)
+            else:
+                self.filename = getattr(fp, "name", None)
+        else:
+            self.filename = filename
+
+        if spoiler and not self.filename.startswith("SPOILER_"):
+            self.filename = "SPOILER_" + self.filename
+
+    def open_file(self):
+        fp = self.fp
+        if isinstance(fp, str):
+            self._true_fp = fp = open(fp, "rb")
+        return fp
+
+    def close(self):
+        if self._true_fp:
+            self._true_fp.close()

discord/gateway.py

@@ -0,0 +1,735 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import asyncio
+from collections import namedtuple
+import concurrent.futures
+import json
+import logging
+import struct
+import sys
+import time
+import threading
+import zlib
+
+import websockets
+
+from . import utils
+from .activity import _ActivityTag
+from .enums import SpeakingState
+from .errors import ConnectionClosed, InvalidArgument
+
+log = logging.getLogger(__name__)
+
+__all__ = [
+    "DiscordWebSocket",
+    "KeepAliveHandler",
+    "VoiceKeepAliveHandler",
+    "DiscordVoiceWebSocket",
+    "ResumeWebSocket",
+]
+
+
+class ResumeWebSocket(Exception):
+    """Signals to initialise via RESUME opcode instead of IDENTIFY."""
+
+    def __init__(self, shard_id):
+        self.shard_id = shard_id
+
+
+EventListener = namedtuple("EventListener", "predicate event result future")
+
+
+class KeepAliveHandler(threading.Thread):
+    def __init__(self, *args, **kwargs):
+        ws = kwargs.pop("ws", None)
+        interval = kwargs.pop("interval", None)
+        shard_id = kwargs.pop("shard_id", None)
+        threading.Thread.__init__(self, *args, **kwargs)
+        self.ws = ws
+        self.interval = interval
+        self.daemon = True
+        self.shard_id = shard_id
+        self.msg = "Keeping websocket alive with sequence %s."
+        self.block_msg = "Heartbeat blocked for more than %s seconds."
+        self.behind_msg = "Can't keep up, websocket is %.1fs behind."
+        self._stop_ev = threading.Event()
+        self._last_ack = time.perf_counter()
+        self._last_send = time.perf_counter()
+        self.latency = float("inf")
+        self.heartbeat_timeout = ws._max_heartbeat_timeout
+
+    def run(self):
+        while not self._stop_ev.wait(self.interval):
+            if self._last_ack + self.heartbeat_timeout < time.perf_counter():
+                log.warning(
+                    "Shard ID %s has stopped responding to the gateway. Closing and restarting.",
+                    self.shard_id,
+                )
+                coro = self.ws.close(4000)
+                f = asyncio.run_coroutine_threadsafe(coro, loop=self.ws.loop)
+
+                try:
+                    f.result()
+                except Exception:
+                    pass
+                finally:
+                    self.stop()
+                    return
+
+            data = self.get_payload()
+            log.debug(self.msg, data["d"])
+            coro = self.ws.send_as_json(data)
+            f = asyncio.run_coroutine_threadsafe(coro, loop=self.ws.loop)
+            try:
+                # block until sending is complete
+                total = 0
+                while True:
+                    try:
+                        f.result(5)
+                        break
+                    except concurrent.futures.TimeoutError:
+                        total += 5
+                        log.warning(self.block_msg, total)
+
+            except Exception:
+                self.stop()
+            else:
+                self._last_send = time.perf_counter()
+
+    def get_payload(self):
+        return {"op": self.ws.HEARTBEAT, "d": self.ws.sequence}
+
+    def stop(self):
+        self._stop_ev.set()
+
+    def ack(self):
+        ack_time = time.perf_counter()
+        self._last_ack = ack_time
+        self.latency = ack_time - self._last_send
+        if self.latency > 10:
+            log.warning(self.behind_msg, self.latency)
+
+
+class VoiceKeepAliveHandler(KeepAliveHandler):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.msg = "Keeping voice websocket alive with timestamp %s."
+        self.block_msg = "Voice heartbeat blocked for more than %s seconds"
+        self.behind_msg = "Can't keep up, voice websocket is %.1fs behind"
+
+    def get_payload(self):
+        return {"op": self.ws.HEARTBEAT, "d": int(time.time() * 1000)}
+
+
+class DiscordWebSocket(websockets.client.WebSocketClientProtocol):
+    """Implements a WebSocket for Discord's gateway v6.
+
+    This is created through :func:`create_main_websocket`. Library
+    users should never create this manually.
+
+    Attributes
+    -----------
+    DISPATCH
+        Receive only. Denotes an event to be sent to Discord, such as READY.
+    HEARTBEAT
+        When received tells Discord to keep the connection alive.
+        When sent asks if your connection is currently alive.
+    IDENTIFY
+        Send only. Starts a new session.
+    PRESENCE
+        Send only. Updates your presence.
+    VOICE_STATE
+        Send only. Starts a new connection to a voice guild.
+    VOICE_PING
+        Send only. Checks ping time to a voice guild, do not use.
+    RESUME
+        Send only. Resumes an existing connection.
+    RECONNECT
+        Receive only. Tells the client to reconnect to a new gateway.
+    REQUEST_MEMBERS
+        Send only. Asks for the full member list of a guild.
+    INVALIDATE_SESSION
+        Receive only. Tells the client to optionally invalidate the session
+        and IDENTIFY again.
+    HELLO
+        Receive only. Tells the client the heartbeat interval.
+    HEARTBEAT_ACK
+        Receive only. Confirms receiving of a heartbeat. Not having it implies
+        a connection issue.
+    GUILD_SYNC
+        Send only. Requests a guild sync.
+    gateway
+        The gateway we are currently connected to.
+    token
+        The authentication token for discord.
+    """
+
+    DISPATCH = 0
+    HEARTBEAT = 1
+    IDENTIFY = 2
+    PRESENCE = 3
+    VOICE_STATE = 4
+    VOICE_PING = 5
+    RESUME = 6
+    RECONNECT = 7
+    REQUEST_MEMBERS = 8
+    INVALIDATE_SESSION = 9
+    HELLO = 10
+    HEARTBEAT_ACK = 11
+    GUILD_SYNC = 12
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.max_size = None
+        # an empty dispatcher to prevent crashes
+        self._dispatch = lambda *args: None
+        # generic event listeners
+        self._dispatch_listeners = []
+        # the keep alive
+        self._keep_alive = None
+
+        # ws related stuff
+        self.session_id = None
+        self.sequence = None
+        self._zlib = zlib.decompressobj()
+        self._buffer = bytearray()
+
+    @classmethod
+    async def from_client(
+        cls, client, *, shard_id=None, session=None, sequence=None, resume=False
+    ):
+        """Creates a main websocket for Discord from a :class:`Client`.
+
+        This is for internal use only.
+        """
+        gateway = await client.http.get_gateway()
+        ws = await websockets.connect(gateway, loop=client.loop, klass=cls, compression=None)
+
+        # dynamically add attributes needed
+        ws.token = client.http.token
+        ws._connection = client._connection
+        ws._dispatch = client.dispatch
+        ws.gateway = gateway
+        ws.shard_id = shard_id
+        ws.shard_count = client._connection.shard_count
+        ws.session_id = session
+        ws.sequence = sequence
+        ws._max_heartbeat_timeout = client._connection.heartbeat_timeout
+
+        client._connection._update_references(ws)
+
+        log.info("Created websocket connected to %s", gateway)
+
+        # poll event for OP Hello
+        await ws.poll_event()
+
+        if not resume:
+            await ws.identify()
+            return ws
+
+        await ws.resume()
+        try:
+            await ws.ensure_open()
+        except websockets.exceptions.ConnectionClosed:
+            # ws got closed so let's just do a regular IDENTIFY connect.
+            log.info(
+                "RESUME failed (the websocket decided to close) for Shard ID %s. Retrying.",
+                shard_id,
+            )
+            return await cls.from_client(client, shard_id=shard_id)
+        else:
+            return ws
+
+    def wait_for(self, event, predicate, result=None):
+        """Waits for a DISPATCH'd event that meets the predicate.
+
+        Parameters
+        -----------
+        event : str
+            The event name in all upper case to wait for.
+        predicate
+            A function that takes a data parameter to check for event
+            properties. The data parameter is the 'd' key in the JSON message.
+        result
+            A function that takes the same data parameter and executes to send
+            the result to the future. If None, returns the data.
+
+        Returns
+        --------
+        asyncio.Future
+            A future to wait for.
+        """
+
+        future = self.loop.create_future()
+        entry = EventListener(event=event, predicate=predicate, result=result, future=future)
+        self._dispatch_listeners.append(entry)
+        return future
+
+    async def identify(self):
+        """Sends the IDENTIFY packet."""
+        payload = {
+            "op": self.IDENTIFY,
+            "d": {
+                "token": self.token,
+                "properties": {
+                    "$os": sys.platform,
+                    "$browser": "discord.py",
+                    "$device": "discord.py",
+                    "$referrer": "",
+                    "$referring_domain": "",
+                },
+                "compress": True,
+                "large_threshold": 250,
+                "v": 3,
+            },
+        }
+
+        if not self._connection.is_bot:
+            payload["d"]["synced_guilds"] = []
+
+        if self.shard_id is not None and self.shard_count is not None:
+            payload["d"]["shard"] = [self.shard_id, self.shard_count]
+
+        state = self._connection
+        if state._activity is not None or state._status is not None:
+            payload["d"]["presence"] = {
+                "status": state._status,
+                "game": state._activity,
+                "since": 0,
+                "afk": False,
+            }
+
+        await self.send_as_json(payload)
+        log.info("Shard ID %s has sent the IDENTIFY payload.", self.shard_id)
+
+    async def resume(self):
+        """Sends the RESUME packet."""
+        payload = {
+            "op": self.RESUME,
+            "d": {"seq": self.sequence, "session_id": self.session_id, "token": self.token},
+        }
+
+        await self.send_as_json(payload)
+        log.info("Shard ID %s has sent the RESUME payload.", self.shard_id)
+
+    async def received_message(self, msg):
+        self._dispatch("socket_raw_receive", msg)
+
+        if type(msg) is bytes:
+            self._buffer.extend(msg)
+
+            if len(msg) >= 4:
+                if msg[-4:] == b"\x00\x00\xff\xff":
+                    msg = self._zlib.decompress(self._buffer)
+                    msg = msg.decode("utf-8")
+                    self._buffer = bytearray()
+                else:
+                    return
+            else:
+                return
+
+        msg = json.loads(msg)
+
+        log.debug("For Shard ID %s: WebSocket Event: %s", self.shard_id, msg)
+        self._dispatch("socket_response", msg)
+
+        op = msg.get("op")
+        data = msg.get("d")
+        seq = msg.get("s")
+        if seq is not None:
+            self.sequence = seq
+
+        if op != self.DISPATCH:
+            if op == self.RECONNECT:
+                # "reconnect" can only be handled by the Client
+                # so we terminate our connection and raise an
+                # internal exception signalling to reconnect.
+                log.info("Received RECONNECT opcode.")
+                await self.close()
+                raise ResumeWebSocket(self.shard_id)
+
+            if op == self.HEARTBEAT_ACK:
+                self._keep_alive.ack()
+                return
+
+            if op == self.HEARTBEAT:
+                beat = self._keep_alive.get_payload()
+                await self.send_as_json(beat)
+                return
+
+            if op == self.HELLO:
+                interval = data["heartbeat_interval"] / 1000.0
+                self._keep_alive = KeepAliveHandler(
+                    ws=self, interval=interval, shard_id=self.shard_id
+                )
+                # send a heartbeat immediately
+                await self.send_as_json(self._keep_alive.get_payload())
+                self._keep_alive.start()
+                return
+
+            if op == self.INVALIDATE_SESSION:
+                if data is True:
+                    await asyncio.sleep(5.0, loop=self.loop)
+                    await self.close()
+                    raise ResumeWebSocket(self.shard_id)
+
+                self.sequence = None
+                self.session_id = None
+                log.info("Shard ID %s session has been invalidated.", self.shard_id)
+                await self.identify()
+                return
+
+            log.warning("Unknown OP code %s.", op)
+            return
+
+        event = msg.get("t")
+
+        if event == "READY":
+            self._trace = trace = data.get("_trace", [])
+            self.sequence = msg["s"]
+            self.session_id = data["session_id"]
+            log.info(
+                "Shard ID %s has connected to Gateway: %s (Session ID: %s).",
+                self.shard_id,
+                ", ".join(trace),
+                self.session_id,
+            )
+
+        elif event == "RESUMED":
+            self._trace = trace = data.get("_trace", [])
+            log.info(
+                "Shard ID %s has successfully RESUMED session %s under trace %s.",
+                self.shard_id,
+                self.session_id,
+                ", ".join(trace),
+            )
+
+        parser = "parse_" + event.lower()
+
+        try:
+            func = getattr(self._connection, parser)
+        except AttributeError:
+            log.warning("Unknown event %s.", event)
+        else:
+            func(data)
+
+        # remove the dispatched listeners
+        removed = []
+        for index, entry in enumerate(self._dispatch_listeners):
+            if entry.event != event:
+                continue
+
+            future = entry.future
+            if future.cancelled():
+                removed.append(index)
+                continue
+
+            try:
+                valid = entry.predicate(data)
+            except Exception as exc:
+                future.set_exception(exc)
+                removed.append(index)
+            else:
+                if valid:
+                    ret = data if entry.result is None else entry.result(data)
+                    future.set_result(ret)
+                    removed.append(index)
+
+        for index in reversed(removed):
+            del self._dispatch_listeners[index]
+
+    @property
+    def latency(self):
+        """:obj:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds."""
+        heartbeat = self._keep_alive
+        return float("inf") if heartbeat is None else heartbeat.latency
+
+    def _can_handle_close(self, code):
+        return code not in (1000, 4004, 4010, 4011)
+
+    async def poll_event(self):
+        """Polls for a DISPATCH event and handles the general gateway loop.
+
+        Raises
+        ------
+        ConnectionClosed
+            The websocket connection was terminated for unhandled reasons.
+        """
+        try:
+            msg = await self.recv()
+            await self.received_message(msg)
+        except websockets.exceptions.ConnectionClosed as exc:
+            if self._can_handle_close(exc.code):
+                log.info(
+                    "Websocket closed with %s (%s), attempting a reconnect.", exc.code, exc.reason
+                )
+                raise ResumeWebSocket(self.shard_id) from exc
+            else:
+                log.info("Websocket closed with %s (%s), cannot reconnect.", exc.code, exc.reason)
+                raise ConnectionClosed(exc, shard_id=self.shard_id) from exc
+
+    async def send(self, data):
+        self._dispatch("socket_raw_send", data)
+        await super().send(data)
+
+    async def send_as_json(self, data):
+        try:
+            await self.send(utils.to_json(data))
+        except websockets.exceptions.ConnectionClosed as exc:
+            if not self._can_handle_close(exc.code):
+                raise ConnectionClosed(exc, shard_id=self.shard_id) from exc
+
+    async def change_presence(self, *, activity=None, status=None, afk=False, since=0.0):
+        if activity is not None:
+            if not isinstance(activity, _ActivityTag):
+                raise InvalidArgument("activity must be one of Game, Streaming, or Activity.")
+            activity = activity.to_dict()
+
+        if status == "idle":
+            since = int(time.time() * 1000)
+
+        payload = {
+            "op": self.PRESENCE,
+            "d": {"game": activity, "afk": afk, "since": since, "status": status},
+        }
+
+        sent = utils.to_json(payload)
+        log.debug('Sending "%s" to change status', sent)
+        await self.send(sent)
+
+    async def request_sync(self, guild_ids):
+        payload = {"op": self.GUILD_SYNC, "d": list(guild_ids)}
+        await self.send_as_json(payload)
+
+    async def voice_state(self, guild_id, channel_id, self_mute=False, self_deaf=False):
+        payload = {
+            "op": self.VOICE_STATE,
+            "d": {
+                "guild_id": guild_id,
+                "channel_id": channel_id,
+                "self_mute": self_mute,
+                "self_deaf": self_deaf,
+            },
+        }
+
+        log.debug("Updating our voice state to %s.", payload)
+        await self.send_as_json(payload)
+
+    async def close(self, code=1000, reason=""):
+        if self._keep_alive:
+            self._keep_alive.stop()
+
+        await super().close(code, reason)
+
+    async def close_connection(self, *args, **kwargs):
+        if self._keep_alive:
+            self._keep_alive.stop()
+
+        await super().close_connection(*args, **kwargs)
+
+
+class DiscordVoiceWebSocket(websockets.client.WebSocketClientProtocol):
+    """Implements the websocket protocol for handling voice connections.
+
+    Attributes
+    -----------
+    IDENTIFY
+        Send only. Starts a new voice session.
+    SELECT_PROTOCOL
+        Send only. Tells discord what encryption mode and how to connect for voice.
+    READY
+        Receive only. Tells the websocket that the initial connection has completed.
+    HEARTBEAT
+        Send only. Keeps your websocket connection alive.
+    SESSION_DESCRIPTION
+        Receive only. Gives you the secret key required for voice.
+    SPEAKING
+        Send only. Notifies the client if you are currently speaking.
+    HEARTBEAT_ACK
+        Receive only. Tells you your heartbeat has been acknowledged.
+    RESUME
+        Sent only. Tells the client to resume its session.
+    HELLO
+        Receive only. Tells you that your websocket connection was acknowledged.
+    INVALIDATE_SESSION
+        Sent only. Tells you that your RESUME request has failed and to re-IDENTIFY.
+    CLIENT_CONNECT
+        Indicates a user has connected to voice.
+    CLIENT_DISCONNECT
+        Receive only.  Indicates a user has disconnected from voice.
+    """
+
+    IDENTIFY = 0
+    SELECT_PROTOCOL = 1
+    READY = 2
+    HEARTBEAT = 3
+    SESSION_DESCRIPTION = 4
+    SPEAKING = 5
+    HEARTBEAT_ACK = 6
+    RESUME = 7
+    HELLO = 8
+    INVALIDATE_SESSION = 9
+    CLIENT_CONNECT = 12
+    CLIENT_DISCONNECT = 13
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.max_size = None
+        self._keep_alive = None
+
+    async def send_as_json(self, data):
+        log.debug("Sending voice websocket frame: %s.", data)
+        await self.send(utils.to_json(data))
+
+    async def resume(self):
+        state = self._connection
+        payload = {
+            "op": self.RESUME,
+            "d": {
+                "token": state.token,
+                "server_id": str(state.server_id),
+                "session_id": state.session_id,
+            },
+        }
+        await self.send_as_json(payload)
+
+    async def identify(self):
+        state = self._connection
+        payload = {
+            "op": self.IDENTIFY,
+            "d": {
+                "server_id": str(state.server_id),
+                "user_id": str(state.user.id),
+                "session_id": state.session_id,
+                "token": state.token,
+            },
+        }
+        await self.send_as_json(payload)
+
+    @classmethod
+    async def from_client(cls, client, *, resume=False):
+        """Creates a voice websocket for the :class:`VoiceClient`."""
+        gateway = "wss://" + client.endpoint + "/?v=4"
+        ws = await websockets.connect(gateway, loop=client.loop, klass=cls, compression=None)
+        ws.gateway = gateway
+        ws._connection = client
+        ws._max_heartbeat_timeout = 60.0
+
+        if resume:
+            await ws.resume()
+        else:
+            await ws.identify()
+
+        return ws
+
+    async def select_protocol(self, ip, port, mode):
+        payload = {
+            "op": self.SELECT_PROTOCOL,
+            "d": {"protocol": "udp", "data": {"address": ip, "port": port, "mode": mode}},
+        }
+
+        await self.send_as_json(payload)
+
+    async def client_connect(self):
+        payload = {"op": self.CLIENT_CONNECT, "d": {"audio_ssrc": self._connection.ssrc}}
+
+        await self.send_as_json(payload)
+
+    async def speak(self, state=SpeakingState.voice):
+        payload = {"op": self.SPEAKING, "d": {"speaking": int(state), "delay": 0}}
+
+        await self.send_as_json(payload)
+
+    async def received_message(self, msg):
+        log.debug("Voice websocket frame received: %s", msg)
+        op = msg["op"]
+        data = msg.get("d")
+
+        if op == self.READY:
+            await self.initial_connection(data)
+        elif op == self.HEARTBEAT_ACK:
+            self._keep_alive.ack()
+        elif op == self.INVALIDATE_SESSION:
+            log.info("Voice RESUME failed.")
+            await self.identify()
+        elif op == self.SESSION_DESCRIPTION:
+            self._connection.mode = data["mode"]
+            await self.load_secret_key(data)
+        elif op == self.HELLO:
+            interval = data["heartbeat_interval"] / 1000.0
+            self._keep_alive = VoiceKeepAliveHandler(ws=self, interval=interval)
+            self._keep_alive.start()
+
+    async def initial_connection(self, data):
+        state = self._connection
+        state.ssrc = data["ssrc"]
+        state.voice_port = data["port"]
+
+        packet = bytearray(70)
+        struct.pack_into(">I", packet, 0, state.ssrc)
+        state.socket.sendto(packet, (state.endpoint_ip, state.voice_port))
+        recv = await self.loop.sock_recv(state.socket, 70)
+        log.debug("received packet in initial_connection: %s", recv)
+
+        # the ip is ascii starting at the 4th byte and ending at the first null
+        ip_start = 4
+        ip_end = recv.index(0, ip_start)
+        state.ip = recv[ip_start:ip_end].decode("ascii")
+
+        # the port is a little endian unsigned short in the last two bytes
+        # yes, this is different endianness from everything else
+        state.port = struct.unpack_from("<H", recv, len(recv) - 2)[0]
+        log.debug("detected ip: %s port: %s", state.ip, state.port)
+
+        # there *should* always be at least one supported mode (xsalsa20_poly1305)
+        modes = [mode for mode in data["modes"] if mode in self._connection.supported_modes]
+        log.debug("received supported encryption modes: %s", ", ".join(modes))
+
+        mode = modes[0]
+        await self.select_protocol(state.ip, state.port, mode)
+        log.info("selected the voice protocol for use (%s)", mode)
+
+        await self.client_connect()
+
+    async def load_secret_key(self, data):
+        log.info("received secret key for voice connection")
+        self._connection.secret_key = data.get("secret_key")
+        await self.speak()
+        await self.speak(False)
+
+    async def poll_event(self):
+        try:
+            msg = await asyncio.wait_for(self.recv(), timeout=30.0, loop=self.loop)
+            await self.received_message(json.loads(msg))
+        except websockets.exceptions.ConnectionClosed as exc:
+            raise ConnectionClosed(exc, shard_id=None) from exc
+
+    async def close_connection(self, *args, **kwargs):
+        if self._keep_alive:
+            self._keep_alive.stop()
+
+        await super().close_connection(*args, **kwargs)

discord/http.py

@@ -0,0 +1,909 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import asyncio
+import json
+import logging
+import sys
+from urllib.parse import quote as _uriquote
+import weakref
+
+import aiohttp
+
+from .errors import HTTPException, Forbidden, NotFound, LoginFailure, GatewayNotFound
+from . import __version__, utils
+
+log = logging.getLogger(__name__)
+
+
+async def json_or_text(response):
+    text = await response.text(encoding="utf-8")
+    if response.headers["content-type"] == "application/json":
+        return json.loads(text)
+    return text
+
+
+class Route:
+    BASE = "https://discordapp.com/api/v7"
+
+    def __init__(self, method, path, **parameters):
+        self.path = path
+        self.method = method
+        url = self.BASE + self.path
+        if parameters:
+            self.url = url.format(
+                **{k: _uriquote(v) if isinstance(v, str) else v for k, v in parameters.items()}
+            )
+        else:
+            self.url = url
+
+        # major parameters:
+        self.channel_id = parameters.get("channel_id")
+        self.guild_id = parameters.get("guild_id")
+
+    @property
+    def bucket(self):
+        # the bucket is just method + path w/ major parameters
+        return "{0.method}:{0.channel_id}:{0.guild_id}:{0.path}".format(self)
+
+
+class MaybeUnlock:
+    def __init__(self, lock):
+        self.lock = lock
+        self._unlock = True
+
+    def __enter__(self):
+        return self
+
+    def defer(self):
+        self._unlock = False
+
+    def __exit__(self, type, value, traceback):
+        if self._unlock:
+            self.lock.release()
+
+
+class HTTPClient:
+    """Represents an HTTP client sending HTTP requests to the Discord API."""
+
+    SUCCESS_LOG = "{method} {url} has received {text}"
+    REQUEST_LOG = "{method} {url} with {json} has returned {status}"
+
+    def __init__(self, connector=None, *, proxy=None, proxy_auth=None, loop=None):
+        self.loop = asyncio.get_event_loop() if loop is None else loop
+        self.connector = connector
+        self._session = aiohttp.ClientSession(connector=connector, loop=self.loop)
+        self._locks = weakref.WeakValueDictionary()
+        self._global_over = asyncio.Event(loop=self.loop)
+        self._global_over.set()
+        self.token = None
+        self.bot_token = False
+        self.proxy = proxy
+        self.proxy_auth = proxy_auth
+
+        user_agent = "DiscordBot (https://github.com/Rapptz/discord.py {0}) Python/{1[0]}.{1[1]} aiohttp/{2}"
+        self.user_agent = user_agent.format(__version__, sys.version_info, aiohttp.__version__)
+
+    def recreate(self):
+        if self._session.closed:
+            self._session = aiohttp.ClientSession(connector=self.connector, loop=self.loop)
+
+    async def request(self, route, *, header_bypass_delay=None, **kwargs):
+        bucket = route.bucket
+        method = route.method
+        url = route.url
+
+        lock = self._locks.get(bucket)
+        if lock is None:
+            lock = asyncio.Lock(loop=self.loop)
+            if bucket is not None:
+                self._locks[bucket] = lock
+
+        # header creation
+        headers = {"User-Agent": self.user_agent}
+
+        if self.token is not None:
+            headers["Authorization"] = "Bot " + self.token if self.bot_token else self.token
+        # some checking if it's a JSON request
+        if "json" in kwargs:
+            headers["Content-Type"] = "application/json"
+            kwargs["data"] = utils.to_json(kwargs.pop("json"))
+
+        try:
+            reason = kwargs.pop("reason")
+        except KeyError:
+            pass
+        else:
+            if reason:
+                headers["X-Audit-Log-Reason"] = _uriquote(reason, safe="/ ")
+
+        kwargs["headers"] = headers
+
+        # Proxy support
+        if self.proxy is not None:
+            kwargs["proxy"] = self.proxy
+        if self.proxy_auth is not None:
+            kwargs["proxy_auth"] = self.proxy_auth
+
+        if not self._global_over.is_set():
+            # wait until the global lock is complete
+            await self._global_over.wait()
+
+        await lock.acquire()
+        with MaybeUnlock(lock) as maybe_lock:
+            for tries in range(5):
+                async with self._session.request(method, url, **kwargs) as r:
+                    log.debug(
+                        "%s %s with %s has returned %s", method, url, kwargs.get("data"), r.status
+                    )
+
+                    # even errors have text involved in them so this is safe to call
+                    data = await json_or_text(r)
+
+                    # check if we have rate limit header information
+                    remaining = r.headers.get("X-Ratelimit-Remaining")
+                    if remaining == "0" and r.status != 429:
+                        # we've depleted our current bucket
+                        if header_bypass_delay is None:
+                            delta = utils._parse_ratelimit_header(r)
+                        else:
+                            delta = header_bypass_delay
+
+                        log.debug(
+                            "A rate limit bucket has been exhausted (bucket: %s, retry: %s).",
+                            bucket,
+                            delta,
+                        )
+                        maybe_lock.defer()
+                        self.loop.call_later(delta, lock.release)
+
+                    # the request was successful so just return the text/json
+                    if 300 > r.status >= 200:
+                        log.debug("%s %s has received %s", method, url, data)
+                        return data
+
+                    # we are being rate limited
+                    if r.status == 429:
+                        fmt = 'We are being rate limited. Retrying in %.2f seconds. Handled under the bucket "%s"'
+
+                        # sleep a bit
+                        retry_after = data["retry_after"] / 1000.0
+                        log.warning(fmt, retry_after, bucket)
+
+                        # check if it's a global rate limit
+                        is_global = data.get("global", False)
+                        if is_global:
+                            log.warning(
+                                "Global rate limit has been hit. Retrying in %.2f seconds.",
+                                retry_after,
+                            )
+                            self._global_over.clear()
+
+                        await asyncio.sleep(retry_after, loop=self.loop)
+                        log.debug("Done sleeping for the rate limit. Retrying...")
+
+                        # release the global lock now that the
+                        # global rate limit has passed
+                        if is_global:
+                            self._global_over.set()
+                            log.debug("Global rate limit is now over.")
+
+                        continue
+
+                    # we've received a 500 or 502, unconditional retry
+                    if r.status in {500, 502}:
+                        await asyncio.sleep(1 + tries * 2, loop=self.loop)
+                        continue
+
+                    # the usual error cases
+                    if r.status == 403:
+                        raise Forbidden(r, data)
+                    elif r.status == 404:
+                        raise NotFound(r, data)
+                    else:
+                        raise HTTPException(r, data)
+
+            # We've run out of retries, raise.
+            raise HTTPException(r, data)
+
+    async def get_attachment(self, url):
+        async with self._session.get(url) as resp:
+            if resp.status == 200:
+                return await resp.read()
+            elif resp.status == 404:
+                raise NotFound(resp, "attachment not found")
+            elif resp.status == 403:
+                raise Forbidden(resp, "cannot retrieve attachment")
+            else:
+                raise HTTPException(resp, "failed to get attachment")
+
+    # state management
+
+    async def close(self):
+        await self._session.close()
+
+    def _token(self, token, *, bot=True):
+        self.token = token
+        self.bot_token = bot
+        self._ack_token = None
+
+    # login management
+
+    async def static_login(self, token, *, bot):
+        old_token, old_bot = self.token, self.bot_token
+        self._token(token, bot=bot)
+
+        try:
+            data = await self.request(Route("GET", "/users/@me"))
+        except HTTPException as exc:
+            self._token(old_token, bot=old_bot)
+            if exc.response.status == 401:
+                raise LoginFailure("Improper token has been passed.") from exc
+            raise
+
+        return data
+
+    def logout(self):
+        return self.request(Route("POST", "/auth/logout"))
+
+    # Group functionality
+
+    def start_group(self, user_id, recipients):
+        payload = {"recipients": recipients}
+
+        return self.request(
+            Route("POST", "/users/{user_id}/channels", user_id=user_id), json=payload
+        )
+
+    def leave_group(self, channel_id):
+        return self.request(Route("DELETE", "/channels/{channel_id}", channel_id=channel_id))
+
+    def add_group_recipient(self, channel_id, user_id):
+        r = Route(
+            "PUT",
+            "/channels/{channel_id}/recipients/{user_id}",
+            channel_id=channel_id,
+            user_id=user_id,
+        )
+        return self.request(r)
+
+    def remove_group_recipient(self, channel_id, user_id):
+        r = Route(
+            "DELETE",
+            "/channels/{channel_id}/recipients/{user_id}",
+            channel_id=channel_id,
+            user_id=user_id,
+        )
+        return self.request(r)
+
+    def edit_group(self, channel_id, **options):
+        valid_keys = ("name", "icon")
+        payload = {k: v for k, v in options.items() if k in valid_keys}
+
+        return self.request(
+            Route("PATCH", "/channels/{channel_id}", channel_id=channel_id), json=payload
+        )
+
+    def convert_group(self, channel_id):
+        return self.request(Route("POST", "/channels/{channel_id}/convert", channel_id=channel_id))
+
+    # Message management
+
+    def start_private_message(self, user_id):
+        payload = {"recipient_id": user_id}
+
+        return self.request(Route("POST", "/users/@me/channels"), json=payload)
+
+    def send_message(self, channel_id, content, *, tts=False, embed=None, nonce=None):
+        r = Route("POST", "/channels/{channel_id}/messages", channel_id=channel_id)
+        payload = {}
+
+        if content:
+            payload["content"] = content
+
+        if tts:
+            payload["tts"] = True
+
+        if embed:
+            payload["embed"] = embed
+
+        if nonce:
+            payload["nonce"] = nonce
+
+        return self.request(r, json=payload)
+
+    def send_typing(self, channel_id):
+        return self.request(Route("POST", "/channels/{channel_id}/typing", channel_id=channel_id))
+
+    def send_files(self, channel_id, *, files, content=None, tts=False, embed=None, nonce=None):
+        r = Route("POST", "/channels/{channel_id}/messages", channel_id=channel_id)
+        form = aiohttp.FormData()
+
+        payload = {"tts": tts}
+        if content:
+            payload["content"] = content
+        if embed:
+            payload["embed"] = embed
+        if nonce:
+            payload["nonce"] = nonce
+
+        form.add_field("payload_json", utils.to_json(payload))
+        if len(files) == 1:
+            fp = files[0]
+            form.add_field("file", fp[0], filename=fp[1], content_type="application/octet-stream")
+        else:
+            for index, (buffer, filename) in enumerate(files):
+                form.add_field(
+                    "file%s" % index,
+                    buffer,
+                    filename=filename,
+                    content_type="application/octet-stream",
+                )
+
+        return self.request(r, data=form)
+
+    async def ack_message(self, channel_id, message_id):
+        r = Route(
+            "POST",
+            "/channels/{channel_id}/messages/{message_id}/ack",
+            channel_id=channel_id,
+            message_id=message_id,
+        )
+        data = await self.request(r, json={"token": self._ack_token})
+        self._ack_token = data["token"]
+
+    def ack_guild(self, guild_id):
+        return self.request(Route("POST", "/guilds/{guild_id}/ack", guild_id=guild_id))
+
+    def delete_message(self, channel_id, message_id, *, reason=None):
+        r = Route(
+            "DELETE",
+            "/channels/{channel_id}/messages/{message_id}",
+            channel_id=channel_id,
+            message_id=message_id,
+        )
+        return self.request(r, reason=reason)
+
+    def delete_messages(self, channel_id, message_ids, *, reason=None):
+        r = Route("POST", "/channels/{channel_id}/messages/bulk_delete", channel_id=channel_id)
+        payload = {"messages": message_ids}
+
+        return self.request(r, json=payload, reason=reason)
+
+    def edit_message(self, message_id, channel_id, **fields):
+        r = Route(
+            "PATCH",
+            "/channels/{channel_id}/messages/{message_id}",
+            channel_id=channel_id,
+            message_id=message_id,
+        )
+        return self.request(r, json=fields)
+
+    def add_reaction(self, message_id, channel_id, emoji):
+        r = Route(
+            "PUT",
+            "/channels/{channel_id}/messages/{message_id}/reactions/{emoji}/@me",
+            channel_id=channel_id,
+            message_id=message_id,
+            emoji=emoji,
+        )
+        return self.request(r, header_bypass_delay=0.25)
+
+    def remove_reaction(self, message_id, channel_id, emoji, member_id):
+        r = Route(
+            "DELETE",
+            "/channels/{channel_id}/messages/{message_id}/reactions/{emoji}/{member_id}",
+            channel_id=channel_id,
+            message_id=message_id,
+            member_id=member_id,
+            emoji=emoji,
+        )
+        return self.request(r, header_bypass_delay=0.25)
+
+    def remove_own_reaction(self, message_id, channel_id, emoji):
+        r = Route(
+            "DELETE",
+            "/channels/{channel_id}/messages/{message_id}/reactions/{emoji}/@me",
+            channel_id=channel_id,
+            message_id=message_id,
+            emoji=emoji,
+        )
+        return self.request(r, header_bypass_delay=0.25)
+
+    def get_reaction_users(self, message_id, channel_id, emoji, limit, after=None):
+        r = Route(
+            "GET",
+            "/channels/{channel_id}/messages/{message_id}/reactions/{emoji}",
+            channel_id=channel_id,
+            message_id=message_id,
+            emoji=emoji,
+        )
+
+        params = {"limit": limit}
+        if after:
+            params["after"] = after
+        return self.request(r, params=params)
+
+    def clear_reactions(self, message_id, channel_id):
+        r = Route(
+            "DELETE",
+            "/channels/{channel_id}/messages/{message_id}/reactions",
+            channel_id=channel_id,
+            message_id=message_id,
+        )
+
+        return self.request(r)
+
+    def get_message(self, channel_id, message_id):
+        r = Route(
+            "GET",
+            "/channels/{channel_id}/messages/{message_id}",
+            channel_id=channel_id,
+            message_id=message_id,
+        )
+        return self.request(r)
+
+    def logs_from(self, channel_id, limit, before=None, after=None, around=None):
+        params = {"limit": limit}
+
+        if before:
+            params["before"] = before
+        if after:
+            params["after"] = after
+        if around:
+            params["around"] = around
+
+        return self.request(
+            Route("GET", "/channels/{channel_id}/messages", channel_id=channel_id), params=params
+        )
+
+    def pin_message(self, channel_id, message_id):
+        return self.request(
+            Route(
+                "PUT",
+                "/channels/{channel_id}/pins/{message_id}",
+                channel_id=channel_id,
+                message_id=message_id,
+            )
+        )
+
+    def unpin_message(self, channel_id, message_id):
+        return self.request(
+            Route(
+                "DELETE",
+                "/channels/{channel_id}/pins/{message_id}",
+                channel_id=channel_id,
+                message_id=message_id,
+            )
+        )
+
+    def pins_from(self, channel_id):
+        return self.request(Route("GET", "/channels/{channel_id}/pins", channel_id=channel_id))
+
+    # Member management
+
+    def kick(self, user_id, guild_id, reason=None):
+        r = Route(
+            "DELETE", "/guilds/{guild_id}/members/{user_id}", guild_id=guild_id, user_id=user_id
+        )
+        if reason:
+            # thanks aiohttp
+            r.url = "{0.url}?reason={1}".format(r, _uriquote(reason))
+
+        return self.request(r)
+
+    def ban(self, user_id, guild_id, delete_message_days=1, reason=None):
+        r = Route("PUT", "/guilds/{guild_id}/bans/{user_id}", guild_id=guild_id, user_id=user_id)
+        params = {"delete-message-days": delete_message_days}
+
+        if reason:
+            # thanks aiohttp
+            r.url = "{0.url}?reason={1}".format(r, _uriquote(reason))
+
+        return self.request(r, params=params)
+
+    def unban(self, user_id, guild_id, *, reason=None):
+        r = Route(
+            "DELETE", "/guilds/{guild_id}/bans/{user_id}", guild_id=guild_id, user_id=user_id
+        )
+        return self.request(r, reason=reason)
+
+    def guild_voice_state(self, user_id, guild_id, *, mute=None, deafen=None, reason=None):
+        r = Route(
+            "PATCH", "/guilds/{guild_id}/members/{user_id}", guild_id=guild_id, user_id=user_id
+        )
+        payload = {}
+        if mute is not None:
+            payload["mute"] = mute
+
+        if deafen is not None:
+            payload["deaf"] = deafen
+
+        return self.request(r, json=payload, reason=reason)
+
+    def edit_profile(self, password, username, avatar, **fields):
+        payload = {"password": password, "username": username, "avatar": avatar}
+
+        if "email" in fields:
+            payload["email"] = fields["email"]
+
+        if "new_password" in fields:
+            payload["new_password"] = fields["new_password"]
+
+        return self.request(Route("PATCH", "/users/@me"), json=payload)
+
+    def change_my_nickname(self, guild_id, nickname, *, reason=None):
+        r = Route("PATCH", "/guilds/{guild_id}/members/@me/nick", guild_id=guild_id)
+        payload = {"nick": nickname}
+        return self.request(r, json=payload, reason=reason)
+
+    def change_nickname(self, guild_id, user_id, nickname, *, reason=None):
+        r = Route(
+            "PATCH", "/guilds/{guild_id}/members/{user_id}", guild_id=guild_id, user_id=user_id
+        )
+        payload = {"nick": nickname}
+        return self.request(r, json=payload, reason=reason)
+
+    def edit_member(self, guild_id, user_id, *, reason=None, **fields):
+        r = Route(
+            "PATCH", "/guilds/{guild_id}/members/{user_id}", guild_id=guild_id, user_id=user_id
+        )
+        return self.request(r, json=fields, reason=reason)
+
+    # Channel management
+
+    def edit_channel(self, channel_id, *, reason=None, **options):
+        r = Route("PATCH", "/channels/{channel_id}", channel_id=channel_id)
+        valid_keys = (
+            "name",
+            "parent_id",
+            "topic",
+            "bitrate",
+            "nsfw",
+            "user_limit",
+            "position",
+            "permission_overwrites",
+            "rate_limit_per_user",
+        )
+        payload = {k: v for k, v in options.items() if k in valid_keys}
+
+        return self.request(r, reason=reason, json=payload)
+
+    def bulk_channel_update(self, guild_id, data, *, reason=None):
+        r = Route("PATCH", "/guilds/{guild_id}/channels", guild_id=guild_id)
+        return self.request(r, json=data, reason=reason)
+
+    def create_channel(self, guild_id, channel_type, *, reason=None, **options):
+        payload = {"type": channel_type}
+
+        valid_keys = (
+            "name",
+            "parent_id",
+            "topic",
+            "bitrate",
+            "nsfw",
+            "user_limit",
+            "position",
+            "permission_overwrites",
+            "rate_limit_per_user",
+        )
+        payload.update({k: v for k, v in options.items() if k in valid_keys and v is not None})
+
+        return self.request(
+            Route("POST", "/guilds/{guild_id}/channels", guild_id=guild_id),
+            json=payload,
+            reason=reason,
+        )
+
+    def delete_channel(self, channel_id, *, reason=None):
+        return self.request(
+            Route("DELETE", "/channels/{channel_id}", channel_id=channel_id), reason=reason
+        )
+
+    # Webhook management
+
+    def create_webhook(self, channel_id, *, name, avatar=None):
+        payload = {"name": name}
+        if avatar is not None:
+            payload["avatar"] = avatar
+
+        return self.request(
+            Route("POST", "/channels/{channel_id}/webhooks", channel_id=channel_id), json=payload
+        )
+
+    def channel_webhooks(self, channel_id):
+        return self.request(Route("GET", "/channels/{channel_id}/webhooks", channel_id=channel_id))
+
+    def guild_webhooks(self, guild_id):
+        return self.request(Route("GET", "/guilds/{guild_id}/webhooks", guild_id=guild_id))
+
+    def get_webhook(self, webhook_id):
+        return self.request(Route("GET", "/webhooks/{webhook_id}", webhook_id=webhook_id))
+
+    # Guild management
+
+    def leave_guild(self, guild_id):
+        return self.request(Route("DELETE", "/users/@me/guilds/{guild_id}", guild_id=guild_id))
+
+    def delete_guild(self, guild_id):
+        return self.request(Route("DELETE", "/guilds/{guild_id}", guild_id=guild_id))
+
+    def create_guild(self, name, region, icon):
+        payload = {"name": name, "icon": icon, "region": region}
+
+        return self.request(Route("POST", "/guilds"), json=payload)
+
+    def edit_guild(self, guild_id, *, reason=None, **fields):
+        valid_keys = (
+            "name",
+            "region",
+            "icon",
+            "afk_timeout",
+            "owner_id",
+            "afk_channel_id",
+            "splash",
+            "verification_level",
+            "system_channel_id",
+            "default_message_notifications",
+            "explicit_content_filter",
+        )
+
+        payload = {k: v for k, v in fields.items() if k in valid_keys}
+
+        return self.request(
+            Route("PATCH", "/guilds/{guild_id}", guild_id=guild_id), json=payload, reason=reason
+        )
+
+    def get_bans(self, guild_id):
+        return self.request(Route("GET", "/guilds/{guild_id}/bans", guild_id=guild_id))
+
+    def get_ban(self, user_id, guild_id):
+        return self.request(
+            Route("GET", "/guilds/{guild_id}/bans/{user_id}", guild_id=guild_id, user_id=user_id)
+        )
+
+    def get_vanity_code(self, guild_id):
+        return self.request(Route("GET", "/guilds/{guild_id}/vanity-url", guild_id=guild_id))
+
+    def change_vanity_code(self, guild_id, code, *, reason=None):
+        payload = {"code": code}
+        return self.request(
+            Route("PATCH", "/guilds/{guild_id}/vanity-url", guild_id=guild_id),
+            json=payload,
+            reason=reason,
+        )
+
+    def prune_members(self, guild_id, days, *, reason=None):
+        params = {"days": days}
+        return self.request(
+            Route("POST", "/guilds/{guild_id}/prune", guild_id=guild_id),
+            params=params,
+            reason=reason,
+        )
+
+    def estimate_pruned_members(self, guild_id, days):
+        params = {"days": days}
+        return self.request(
+            Route("GET", "/guilds/{guild_id}/prune", guild_id=guild_id), params=params
+        )
+
+    def create_custom_emoji(self, guild_id, name, image, *, roles=None, reason=None):
+        payload = {"name": name, "image": image, "roles": roles or []}
+
+        r = Route("POST", "/guilds/{guild_id}/emojis", guild_id=guild_id)
+        return self.request(r, json=payload, reason=reason)
+
+    def delete_custom_emoji(self, guild_id, emoji_id, *, reason=None):
+        r = Route(
+            "DELETE", "/guilds/{guild_id}/emojis/{emoji_id}", guild_id=guild_id, emoji_id=emoji_id
+        )
+        return self.request(r, reason=reason)
+
+    def edit_custom_emoji(self, guild_id, emoji_id, *, name, roles=None, reason=None):
+        payload = {"name": name, "roles": roles or []}
+        r = Route(
+            "PATCH", "/guilds/{guild_id}/emojis/{emoji_id}", guild_id=guild_id, emoji_id=emoji_id
+        )
+        return self.request(r, json=payload, reason=reason)
+
+    def get_audit_logs(
+        self, guild_id, limit=100, before=None, after=None, user_id=None, action_type=None
+    ):
+        params = {"limit": limit}
+        if before:
+            params["before"] = before
+        if after:
+            params["after"] = after
+        if user_id:
+            params["user_id"] = user_id
+        if action_type:
+            params["action_type"] = action_type
+
+        r = Route("GET", "/guilds/{guild_id}/audit-logs", guild_id=guild_id)
+        return self.request(r, params=params)
+
+    # Invite management
+
+    def create_invite(self, channel_id, *, reason=None, **options):
+        r = Route("POST", "/channels/{channel_id}/invites", channel_id=channel_id)
+        payload = {
+            "max_age": options.get("max_age", 0),
+            "max_uses": options.get("max_uses", 0),
+            "temporary": options.get("temporary", False),
+            "unique": options.get("unique", True),
+        }
+
+        return self.request(r, reason=reason, json=payload)
+
+    def get_invite(self, invite_id):
+        return self.request(Route("GET", "/invite/{invite_id}", invite_id=invite_id))
+
+    def invites_from(self, guild_id):
+        return self.request(Route("GET", "/guilds/{guild_id}/invites", guild_id=guild_id))
+
+    def invites_from_channel(self, channel_id):
+        return self.request(Route("GET", "/channels/{channel_id}/invites", channel_id=channel_id))
+
+    def delete_invite(self, invite_id, *, reason=None):
+        return self.request(
+            Route("DELETE", "/invite/{invite_id}", invite_id=invite_id), reason=reason
+        )
+
+    # Role management
+
+    def edit_role(self, guild_id, role_id, *, reason=None, **fields):
+        r = Route(
+            "PATCH", "/guilds/{guild_id}/roles/{role_id}", guild_id=guild_id, role_id=role_id
+        )
+        valid_keys = ("name", "permissions", "color", "hoist", "mentionable")
+        payload = {k: v for k, v in fields.items() if k in valid_keys}
+        return self.request(r, json=payload, reason=reason)
+
+    def delete_role(self, guild_id, role_id, *, reason=None):
+        r = Route(
+            "DELETE", "/guilds/{guild_id}/roles/{role_id}", guild_id=guild_id, role_id=role_id
+        )
+        return self.request(r, reason=reason)
+
+    def replace_roles(self, user_id, guild_id, role_ids, *, reason=None):
+        return self.edit_member(guild_id=guild_id, user_id=user_id, roles=role_ids, reason=reason)
+
+    def create_role(self, guild_id, *, reason=None, **fields):
+        r = Route("POST", "/guilds/{guild_id}/roles", guild_id=guild_id)
+        return self.request(r, json=fields, reason=reason)
+
+    def move_role_position(self, guild_id, positions, *, reason=None):
+        r = Route("PATCH", "/guilds/{guild_id}/roles", guild_id=guild_id)
+        return self.request(r, json=positions, reason=reason)
+
+    def add_role(self, guild_id, user_id, role_id, *, reason=None):
+        r = Route(
+            "PUT",
+            "/guilds/{guild_id}/members/{user_id}/roles/{role_id}",
+            guild_id=guild_id,
+            user_id=user_id,
+            role_id=role_id,
+        )
+        return self.request(r, reason=reason)
+
+    def remove_role(self, guild_id, user_id, role_id, *, reason=None):
+        r = Route(
+            "DELETE",
+            "/guilds/{guild_id}/members/{user_id}/roles/{role_id}",
+            guild_id=guild_id,
+            user_id=user_id,
+            role_id=role_id,
+        )
+        return self.request(r, reason=reason)
+
+    def edit_channel_permissions(self, channel_id, target, allow, deny, type, *, reason=None):
+        payload = {"id": target, "allow": allow, "deny": deny, "type": type}
+        r = Route(
+            "PUT",
+            "/channels/{channel_id}/permissions/{target}",
+            channel_id=channel_id,
+            target=target,
+        )
+        return self.request(r, json=payload, reason=reason)
+
+    def delete_channel_permissions(self, channel_id, target, *, reason=None):
+        r = Route(
+            "DELETE",
+            "/channels/{channel_id}/permissions/{target}",
+            channel_id=channel_id,
+            target=target,
+        )
+        return self.request(r, reason=reason)
+
+    # Voice management
+
+    def move_member(self, user_id, guild_id, channel_id, *, reason=None):
+        return self.edit_member(
+            guild_id=guild_id, user_id=user_id, channel_id=channel_id, reason=reason
+        )
+
+    # Relationship related
+
+    def remove_relationship(self, user_id):
+        r = Route("DELETE", "/users/@me/relationships/{user_id}", user_id=user_id)
+        return self.request(r)
+
+    def add_relationship(self, user_id, type=None):
+        r = Route("PUT", "/users/@me/relationships/{user_id}", user_id=user_id)
+        payload = {}
+        if type is not None:
+            payload["type"] = type
+
+        return self.request(r, json=payload)
+
+    def send_friend_request(self, username, discriminator):
+        r = Route("POST", "/users/@me/relationships")
+        payload = {"username": username, "discriminator": int(discriminator)}
+        return self.request(r, json=payload)
+
+    # Misc
+
+    def application_info(self):
+        return self.request(Route("GET", "/oauth2/applications/@me"))
+
+    async def get_gateway(self, *, encoding="json", v=6, zlib=True):
+        try:
+            data = await self.request(Route("GET", "/gateway"))
+        except HTTPException as exc:
+            raise GatewayNotFound() from exc
+        if zlib:
+            value = "{0}?encoding={1}&v={2}&compress=zlib-stream"
+        else:
+            value = "{0}?encoding={1}&v={2}"
+        return value.format(data["url"], encoding, v)
+
+    async def get_bot_gateway(self, *, encoding="json", v=6, zlib=True):
+        try:
+            data = await self.request(Route("GET", "/gateway/bot"))
+        except HTTPException as exc:
+            raise GatewayNotFound() from exc
+
+        if zlib:
+            value = "{0}?encoding={1}&v={2}&compress=zlib-stream"
+        else:
+            value = "{0}?encoding={1}&v={2}"
+        return data["shards"], value.format(data["url"], encoding, v)
+
+    def get_user_info(self, user_id):
+        return self.request(Route("GET", "/users/{user_id}", user_id=user_id))
+
+    def get_user_profile(self, user_id):
+        return self.request(Route("GET", "/users/{user_id}/profile", user_id=user_id))
+
+    def get_mutual_friends(self, user_id):
+        return self.request(Route("GET", "/users/{user_id}/relationships", user_id=user_id))
+
+    def change_hypesquad_house(self, house_id):
+        payload = {"house_id": house_id}
+        return self.request(Route("POST", "/hypesquad/online"), json=payload)
+
+    def leave_hypesquad_house(self):
+        return self.request(Route("DELETE", "/hypesquad/online"))

discord/invite.py

@@ -0,0 +1,176 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from .utils import parse_time
+from .mixins import Hashable
+from .object import Object
+
+
+class Invite(Hashable):
+    """Represents a Discord :class:`Guild` or :class:`abc.GuildChannel` invite.
+
+    Depending on the way this object was created, some of the attributes can
+    have a value of ``None``.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two invites are equal.
+
+        .. describe:: x != y
+
+            Checks if two invites are not equal.
+
+        .. describe:: hash(x)
+
+            Returns the invite hash.
+
+        .. describe:: str(x)
+
+            Returns the invite URL.
+
+    Attributes
+    -----------
+    max_age: :class:`int`
+        How long the before the invite expires in seconds. A value of 0 indicates that it doesn't expire.
+    code: :class:`str`
+        The URL fragment used for the invite.
+    guild: :class:`Guild`
+        The guild the invite is for.
+    revoked: :class:`bool`
+        Indicates if the invite has been revoked.
+    created_at: `datetime.datetime`
+        A datetime object denoting the time the invite was created.
+    temporary: :class:`bool`
+        Indicates that the invite grants temporary membership.
+        If True, members who joined via this invite will be kicked upon disconnect.
+    uses: :class:`int`
+        How many times the invite has been used.
+    max_uses: :class:`int`
+        How many times the invite can be used.
+    inviter: :class:`User`
+        The user who created the invite.
+    channel: :class:`abc.GuildChannel`
+        The channel the invite is for.
+    """
+
+    __slots__ = (
+        "max_age",
+        "code",
+        "guild",
+        "revoked",
+        "created_at",
+        "uses",
+        "temporary",
+        "max_uses",
+        "inviter",
+        "channel",
+        "_state",
+    )
+
+    def __init__(self, *, state, data):
+        self._state = state
+        self.max_age = data.get("max_age")
+        self.code = data.get("code")
+        self.guild = data.get("guild")
+        self.revoked = data.get("revoked")
+        self.created_at = parse_time(data.get("created_at"))
+        self.temporary = data.get("temporary")
+        self.uses = data.get("uses")
+        self.max_uses = data.get("max_uses")
+
+        inviter_data = data.get("inviter")
+        self.inviter = None if inviter_data is None else self._state.store_user(inviter_data)
+        self.channel = data.get("channel")
+
+    @classmethod
+    def from_incomplete(cls, *, state, data):
+        guild_id = int(data["guild"]["id"])
+        channel_id = int(data["channel"]["id"])
+        guild = state._get_guild(guild_id)
+        if guild is not None:
+            channel = guild.get_channel(channel_id)
+        else:
+            guild = Object(id=guild_id)
+            channel = Object(id=channel_id)
+            guild.name = data["guild"]["name"]
+
+            guild.splash = data["guild"]["splash"]
+            guild.splash_url = ""
+            if guild.splash:
+                guild.splash_url = "https://cdn.discordapp.com/splashes/{0.id}/{0.splash}.jpg?size=2048".format(
+                    guild
+                )
+
+            channel.name = data["channel"]["name"]
+
+        data["guild"] = guild
+        data["channel"] = channel
+        return cls(state=state, data=data)
+
+    def __str__(self):
+        return self.url
+
+    def __repr__(self):
+        return "<Invite code={0.code!r}>".format(self)
+
+    def __hash__(self):
+        return hash(self.code)
+
+    @property
+    def id(self):
+        """Returns the proper code portion of the invite."""
+        return self.code
+
+    @property
+    def url(self):
+        """A property that retrieves the invite URL."""
+        return "http://discord.gg/" + self.code
+
+    async def delete(self, *, reason=None):
+        """|coro|
+
+        Revokes the instant invite.
+
+        You must have the :attr:`~Permissions.manage_channels` permission to do this.
+
+        Parameters
+        -----------
+        reason: Optional[str]
+            The reason for deleting this invite. Shows up on the audit log.
+
+        Raises
+        -------
+        Forbidden
+            You do not have permissions to revoke invites.
+        NotFound
+            The invite is invalid or expired.
+        HTTPException
+            Revoking the invite failed.
+        """
+
+        await self._state.http.delete_invite(self.code, reason=reason)

discord/iterators.py

@@ -0,0 +1,489 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import asyncio
+import datetime
+
+from .errors import NoMoreItems
+from .utils import time_snowflake, maybe_coroutine
+from .object import Object
+from .audit_logs import AuditLogEntry
+
+
+class _AsyncIterator:
+    __slots__ = ()
+
+    def get(self, **attrs):
+        def predicate(elem):
+            for attr, val in attrs.items():
+                nested = attr.split("__")
+                obj = elem
+                for attribute in nested:
+                    obj = getattr(obj, attribute)
+
+                if obj != val:
+                    return False
+            return True
+
+        return self.find(predicate)
+
+    async def find(self, predicate):
+        while True:
+            try:
+                elem = await self.next()
+            except NoMoreItems:
+                return None
+
+            ret = await maybe_coroutine(predicate, elem)
+            if ret:
+                return elem
+
+    def map(self, func):
+        return _MappedAsyncIterator(self, func)
+
+    def filter(self, predicate):
+        return _FilteredAsyncIterator(self, predicate)
+
+    async def flatten(self):
+        ret = []
+        while True:
+            try:
+                item = await self.next()
+            except NoMoreItems:
+                return ret
+            else:
+                ret.append(item)
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        try:
+            msg = await self.next()
+        except NoMoreItems:
+            raise StopAsyncIteration()
+        else:
+            return msg
+
+
+def _identity(x):
+    return x
+
+
+class _MappedAsyncIterator(_AsyncIterator):
+    def __init__(self, iterator, func):
+        self.iterator = iterator
+        self.func = func
+
+    async def next(self):
+        # this raises NoMoreItems and will propagate appropriately
+        item = await self.iterator.next()
+        return await maybe_coroutine(self.func, item)
+
+
+class _FilteredAsyncIterator(_AsyncIterator):
+    def __init__(self, iterator, predicate):
+        self.iterator = iterator
+
+        if predicate is None:
+            predicate = _identity
+
+        self.predicate = predicate
+
+    async def next(self):
+        getter = self.iterator.next
+        pred = self.predicate
+        while True:
+            # propagate NoMoreItems similar to _MappedAsyncIterator
+            item = await getter()
+            ret = await maybe_coroutine(pred, item)
+            if ret:
+                return item
+
+
+class ReactionIterator(_AsyncIterator):
+    def __init__(self, message, emoji, limit=100, after=None):
+        self.message = message
+        self.limit = limit
+        self.after = after
+        state = message._state
+        self.getter = state.http.get_reaction_users
+        self.state = state
+        self.emoji = emoji
+        self.guild = message.guild
+        self.channel_id = message.channel.id
+        self.users = asyncio.Queue(loop=state.loop)
+
+    async def next(self):
+        if self.users.empty():
+            await self.fill_users()
+
+        try:
+            return self.users.get_nowait()
+        except asyncio.QueueEmpty:
+            raise NoMoreItems()
+
+    async def fill_users(self):
+        # this is a hack because >circular imports<
+        from .user import User
+
+        if self.limit > 0:
+            retrieve = self.limit if self.limit <= 100 else 100
+
+            after = self.after.id if self.after else None
+            data = await self.getter(
+                self.message.id, self.channel_id, self.emoji, retrieve, after=after
+            )
+
+            if data:
+                self.limit -= retrieve
+                self.after = Object(id=int(data[-1]["id"]))
+
+            if self.guild is None:
+                for element in reversed(data):
+                    await self.users.put(User(state=self.state, data=element))
+            else:
+                for element in reversed(data):
+                    member_id = int(element["id"])
+                    member = self.guild.get_member(member_id)
+                    if member is not None:
+                        await self.users.put(member)
+                    else:
+                        await self.users.put(User(state=self.state, data=element))
+
+
+class HistoryIterator(_AsyncIterator):
+    """Iterator for receiving a channel's message history.
+
+    The messages endpoint has two behaviours we care about here:
+    If `before` is specified, the messages endpoint returns the `limit`
+    newest messages before `before`, sorted with newest first. For filling over
+    100 messages, update the `before` parameter to the oldest message received.
+    Messages will be returned in order by time.
+    If `after` is specified, it returns the `limit` oldest messages after
+    `after`, sorted with newest first. For filling over 100 messages, update the
+    `after` parameter to the newest message received. If messages are not
+    reversed, they will be out of order (99-0, 199-100, so on)
+
+    A note that if both before and after are specified, before is ignored by the
+    messages endpoint.
+
+    Parameters
+    -----------
+    messageable: :class:`abc.Messageable`
+        Messageable class to retrieve message history fro.
+    limit : int
+        Maximum number of messages to retrieve
+    before : :class:`Message` or id-like
+        Message before which all messages must be.
+    after : :class:`Message` or id-like
+        Message after which all messages must be.
+    around : :class:`Message` or id-like
+        Message around which all messages must be. Limit max 101. Note that if
+        limit is an even number, this will return at most limit+1 messages.
+    reverse: bool
+        If set to true, return messages in oldest->newest order. Recommended
+        when using with "after" queries with limit over 100, otherwise messages
+        will be out of order.
+    """
+
+    def __init__(self, messageable, limit, before=None, after=None, around=None, reverse=None):
+
+        if isinstance(before, datetime.datetime):
+            before = Object(id=time_snowflake(before, high=False))
+        if isinstance(after, datetime.datetime):
+            after = Object(id=time_snowflake(after, high=True))
+        if isinstance(around, datetime.datetime):
+            around = Object(id=time_snowflake(around))
+
+        self.messageable = messageable
+        self.limit = limit
+        self.before = before
+        self.after = after
+        self.around = around
+
+        if reverse is None:
+            self.reverse = after is not None
+        else:
+            self.reverse = reverse
+
+        self._filter = None  # message dict -> bool
+
+        self.state = self.messageable._state
+        self.logs_from = self.state.http.logs_from
+        self.messages = asyncio.Queue(loop=self.state.loop)
+
+        if self.around:
+            if self.limit is None:
+                raise ValueError("history does not support around with limit=None")
+            if self.limit > 101:
+                raise ValueError("history max limit 101 when specifying around parameter")
+            elif self.limit == 101:
+                self.limit = 100  # Thanks discord
+            elif self.limit == 1:
+                raise ValueError("Use get_message.")
+
+            self._retrieve_messages = self._retrieve_messages_around_strategy
+            if self.before and self.after:
+                self._filter = lambda m: self.after.id < int(m["id"]) < self.before.id
+            elif self.before:
+                self._filter = lambda m: int(m["id"]) < self.before.id
+            elif self.after:
+                self._filter = lambda m: self.after.id < int(m["id"])
+        elif self.before and self.after:
+            if self.reverse:
+                self._retrieve_messages = self._retrieve_messages_after_strategy
+                self._filter = lambda m: int(m["id"]) < self.before.id
+            else:
+                self._retrieve_messages = self._retrieve_messages_before_strategy
+                self._filter = lambda m: int(m["id"]) > self.after.id
+        elif self.after:
+            self._retrieve_messages = self._retrieve_messages_after_strategy
+        else:
+            self._retrieve_messages = self._retrieve_messages_before_strategy
+
+    async def next(self):
+        if self.messages.empty():
+            await self.fill_messages()
+
+        try:
+            return self.messages.get_nowait()
+        except asyncio.QueueEmpty:
+            raise NoMoreItems()
+
+    def _get_retrieve(self):
+        l = self.limit
+        if l is None:
+            r = 100
+        elif l <= 100:
+            r = l
+        else:
+            r = 100
+
+        self.retrieve = r
+        return r > 0
+
+    async def flatten(self):
+        # this is similar to fill_messages except it uses a list instead
+        # of a queue to place the messages in.
+        result = []
+        channel = await self.messageable._get_channel()
+        self.channel = channel
+        while self._get_retrieve():
+            data = await self._retrieve_messages(self.retrieve)
+            if len(data) < 100:
+                self.limit = 0  # terminate the infinite loop
+
+            if self.reverse:
+                data = reversed(data)
+            if self._filter:
+                data = filter(self._filter, data)
+
+            for element in data:
+                result.append(self.state.create_message(channel=channel, data=element))
+        return result
+
+    async def fill_messages(self):
+        if not hasattr(self, "channel"):
+            # do the required set up
+            channel = await self.messageable._get_channel()
+            self.channel = channel
+
+        if self._get_retrieve():
+            data = await self._retrieve_messages(self.retrieve)
+            if self.limit is None and len(data) < 100:
+                self.limit = 0  # terminate the infinite loop
+
+            if self.reverse:
+                data = reversed(data)
+            if self._filter:
+                data = filter(self._filter, data)
+
+            channel = self.channel
+            for element in data:
+                await self.messages.put(self.state.create_message(channel=channel, data=element))
+
+    async def _retrieve_messages(self, retrieve):
+        """Retrieve messages and update next parameters."""
+        pass
+
+    async def _retrieve_messages_before_strategy(self, retrieve):
+        """Retrieve messages using before parameter."""
+        before = self.before.id if self.before else None
+        data = await self.logs_from(self.channel.id, retrieve, before=before)
+        if len(data):
+            if self.limit is not None:
+                self.limit -= retrieve
+            self.before = Object(id=int(data[-1]["id"]))
+        return data
+
+    async def _retrieve_messages_after_strategy(self, retrieve):
+        """Retrieve messages using after parameter."""
+        after = self.after.id if self.after else None
+        data = await self.logs_from(self.channel.id, retrieve, after=after)
+        if len(data):
+            if self.limit is not None:
+                self.limit -= retrieve
+            self.after = Object(id=int(data[0]["id"]))
+        return data
+
+    async def _retrieve_messages_around_strategy(self, retrieve):
+        """Retrieve messages using around parameter."""
+        if self.around:
+            around = self.around.id if self.around else None
+            data = await self.logs_from(self.channel.id, retrieve, around=around)
+            self.around = None
+            return data
+        return []
+
+
+class AuditLogIterator(_AsyncIterator):
+    def __init__(
+        self,
+        guild,
+        limit=None,
+        before=None,
+        after=None,
+        reverse=None,
+        user_id=None,
+        action_type=None,
+    ):
+        if isinstance(before, datetime.datetime):
+            before = Object(id=time_snowflake(before, high=False))
+        if isinstance(after, datetime.datetime):
+            after = Object(id=time_snowflake(after, high=True))
+
+        self.guild = guild
+        self.loop = guild._state.loop
+        self.request = guild._state.http.get_audit_logs
+        self.limit = limit
+        self.before = before
+        self.user_id = user_id
+        self.action_type = action_type
+        self.after = after
+        self._users = {}
+        self._state = guild._state
+
+        if reverse is None:
+            self.reverse = after is not None
+        else:
+            self.reverse = reverse
+
+        self._filter = None  # entry dict -> bool
+
+        self.entries = asyncio.Queue(loop=self.loop)
+
+        if self.before and self.after:
+            if self.reverse:
+                self._strategy = self._after_strategy
+                self._filter = lambda m: int(m["id"]) < self.before.id
+            else:
+                self._strategy = self._before_strategy
+                self._filter = lambda m: int(m["id"]) > self.after.id
+        elif self.after:
+            self._strategy = self._after_strategy
+        else:
+            self._strategy = self._before_strategy
+
+    async def _before_strategy(self, retrieve):
+        before = self.before.id if self.before else None
+        data = await self.request(
+            self.guild.id,
+            limit=retrieve,
+            user_id=self.user_id,
+            action_type=self.action_type,
+            before=before,
+        )
+
+        entries = data.get("audit_log_entries", [])
+        if len(data) and entries:
+            if self.limit is not None:
+                self.limit -= retrieve
+            self.before = Object(id=int(entries[-1]["id"]))
+        return data.get("users", []), entries
+
+    async def _after_strategy(self, retrieve):
+        after = self.after.id if self.after else None
+        data = await self.request(
+            self.guild.id,
+            limit=retrieve,
+            user_id=self.user_id,
+            action_type=self.action_type,
+            after=after,
+        )
+        entries = data.get("audit_log_entries", [])
+        if len(data) and entries:
+            if self.limit is not None:
+                self.limit -= retrieve
+            self.after = Object(id=int(entries[0]["id"]))
+        return data.get("users", []), entries
+
+    async def next(self):
+        if self.entries.empty():
+            await self._fill()
+
+        try:
+            return self.entries.get_nowait()
+        except asyncio.QueueEmpty:
+            raise NoMoreItems()
+
+    def _get_retrieve(self):
+        l = self.limit
+        if l is None:
+            r = 100
+        elif l <= 100:
+            r = l
+        else:
+            r = 100
+
+        self.retrieve = r
+        return r > 0
+
+    async def _fill(self):
+        from .user import User
+
+        if self._get_retrieve():
+            users, data = await self._strategy(self.retrieve)
+            if self.limit is None and len(data) < 100:
+                self.limit = 0  # terminate the infinite loop
+
+            if self.reverse:
+                data = reversed(data)
+            if self._filter:
+                data = filter(self._filter, data)
+
+            for user in users:
+                u = User(data=user, state=self._state)
+                self._users[u.id] = u
+
+            for element in data:
+                # TODO: remove this if statement later
+                if element["action_type"] is None:
+                    continue
+
+                await self.entries.put(
+                    AuditLogEntry(data=element, users=self._users, guild=self.guild)
+                )

discord/member.py

@@ -0,0 +1,621 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import itertools
+
+import discord.abc
+
+from . import utils
+from .user import BaseUser, User
+from .activity import create_activity
+from .permissions import Permissions
+from .enums import Status, try_enum
+from .colour import Colour
+from .object import Object
+
+
+class VoiceState:
+    """Represents a Discord user's voice state.
+
+    Attributes
+    ------------
+    deaf: :class:`bool`
+        Indicates if the user is currently deafened by the guild.
+    mute: :class:`bool`
+        Indicates if the user is currently muted by the guild.
+    self_mute: :class:`bool`
+        Indicates if the user is currently muted by their own accord.
+    self_deaf: :class:`bool`
+        Indicates if the user is currently deafened by their own accord.
+    afk: :class:`bool`
+        Indicates if the user is currently in the AFK channel in the guild.
+    channel: :class:`VoiceChannel`
+        The voice channel that the user is currently connected to. None if the user
+        is not currently in a voice channel.
+    """
+
+    __slots__ = ("session_id", "deaf", "mute", "self_mute", "self_deaf", "afk", "channel")
+
+    def __init__(self, *, data, channel=None):
+        self.session_id = data.get("session_id")
+        self._update(data, channel)
+
+    def _update(self, data, channel):
+        self.self_mute = data.get("self_mute", False)
+        self.self_deaf = data.get("self_deaf", False)
+        self.afk = data.get("suppress", False)
+        self.mute = data.get("mute", False)
+        self.deaf = data.get("deaf", False)
+        self.channel = channel
+
+    def __repr__(self):
+        return "<VoiceState self_mute={0.self_mute} self_deaf={0.self_deaf} channel={0.channel!r}>".format(
+            self
+        )
+
+
+def flatten_user(cls):
+    for attr, value in itertools.chain(BaseUser.__dict__.items(), User.__dict__.items()):
+        # ignore private/special methods
+        if attr.startswith("_"):
+            continue
+
+        # don't override what we already have
+        if attr in cls.__dict__:
+            continue
+
+        # if it's a slotted attribute or a property, redirect it
+        # slotted members are implemented as member_descriptors in Type.__dict__
+        if not hasattr(value, "__annotations__"):
+
+            def getter(self, x=attr):
+                return getattr(self._user, x)
+
+            setattr(cls, attr, property(getter, doc="Equivalent to :attr:`User.%s`" % attr))
+        else:
+            # probably a member function by now
+            def generate_function(x):
+                def general(self, *args, **kwargs):
+                    return getattr(self._user, x)(*args, **kwargs)
+
+                general.__name__ = x
+                return general
+
+            func = generate_function(attr)
+            func.__doc__ = value.__doc__
+            setattr(cls, attr, func)
+
+    return cls
+
+
+_BaseUser = discord.abc.User
+
+
+@flatten_user
+class Member(discord.abc.Messageable, _BaseUser):
+    """Represents a Discord member to a :class:`Guild`.
+
+    This implements a lot of the functionality of :class:`User`.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two members are equal.
+            Note that this works with :class:`User` instances too.
+
+        .. describe:: x != y
+
+            Checks if two members are not equal.
+            Note that this works with :class:`User` instances too.
+
+        .. describe:: hash(x)
+
+            Returns the member's hash.
+
+        .. describe:: str(x)
+
+            Returns the member's name with the discriminator.
+
+    Attributes
+    ----------
+    joined_at: `datetime.datetime`
+        A datetime object that specifies the date and time in UTC that the member joined the guild for
+        the first time.
+    activities: Tuple[Union[:class:`Game`, :class:`Streaming`, :class:`Spotify`, :class:`Activity`]]
+        The activities that the user is currently doing.
+    guild: :class:`Guild`
+        The guild that the member belongs to.
+    nick: Optional[:class:`str`]
+        The guild specific nickname of the user.
+    """
+
+    __slots__ = (
+        "_roles",
+        "joined_at",
+        "_client_status",
+        "activities",
+        "guild",
+        "nick",
+        "_user",
+        "_state",
+    )
+
+    def __init__(self, *, data, guild, state):
+        self._state = state
+        self._user = state.store_user(data["user"])
+        self.guild = guild
+        self.joined_at = utils.parse_time(data.get("joined_at"))
+        self._update_roles(data)
+        self._client_status = {None: Status.offline}
+        self.activities = tuple(map(create_activity, data.get("activities", [])))
+        self.nick = data.get("nick", None)
+
+    def __str__(self):
+        return str(self._user)
+
+    def __repr__(self):
+        return (
+            "<Member id={1.id} name={1.name!r} discriminator={1.discriminator!r}"
+            " bot={1.bot} nick={0.nick!r} guild={0.guild!r}>".format(self, self._user)
+        )
+
+    def __eq__(self, other):
+        return isinstance(other, _BaseUser) and other.id == self.id
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def __hash__(self):
+        return hash(self._user)
+
+    @classmethod
+    def _copy(cls, member):
+        self = cls.__new__(cls)  # to bypass __init__
+
+        self._roles = utils.SnowflakeList(member._roles, is_sorted=True)
+        self.joined_at = member.joined_at
+        self._client_status = member._client_status.copy()
+        self.guild = member.guild
+        self.nick = member.nick
+        self.activities = member.activities
+        self._state = member._state
+        self._user = User._copy(member._user)
+        return self
+
+    async def _get_channel(self):
+        ch = await self.create_dm()
+        return ch
+
+    def _update_roles(self, data):
+        self._roles = utils.SnowflakeList(map(int, data["roles"]))
+
+    def _update(self, data, user=None):
+        if user:
+            self._user.name = user["username"]
+            self._user.discriminator = user["discriminator"]
+            self._user.avatar = user["avatar"]
+            self._user.bot = user.get("bot", False)
+
+        # the nickname change is optional,
+        # if it isn't in the payload then it didn't change
+        try:
+            self.nick = data["nick"]
+        except KeyError:
+            pass
+
+        self._update_roles(data)
+
+    def _presence_update(self, data, user):
+        self.activities = tuple(map(create_activity, data.get("activities", [])))
+        self._client_status = {key: value for key, value in data.get("client_status", {}).items()}
+        self._client_status[None] = data["status"]
+
+        if len(user) > 1:
+            u = self._user
+            u.name = user.get("username", u.name)
+            u.avatar = user.get("avatar", u.avatar)
+            u.discriminator = user.get("discriminator", u.discriminator)
+
+    @property
+    def status(self):
+        """:class:`Status`: The member's overall status. If the value is unknown, then it will be a :class:`str` instead."""
+        return try_enum(Status, self._client_status[None])
+
+    @status.setter
+    def status(self, value):
+        # internal use only
+        self._client_status[None] = str(value)
+
+    @property
+    def mobile_status(self):
+        """:class:`Status`: The member's status on a mobile device, if applicable."""
+        return try_enum(Status, self._client_status.get("mobile", "offline"))
+
+    @property
+    def desktop_status(self):
+        """:class:`Status`: The member's status on the desktop client, if applicable."""
+        return try_enum(Status, self._client_status.get("desktop", "offline"))
+
+    @property
+    def web_status(self):
+        """:class:`Status`: The member's status on the web client, if applicable."""
+        return try_enum(Status, self._client_status.get("web", "offline"))
+
+    def is_on_mobile(self):
+        """:class:`bool`: A helper function that determines if a member is active on a mobile device."""
+        return "mobile" in self._client_status
+
+    @property
+    def colour(self):
+        """A property that returns a :class:`Colour` denoting the rendered colour
+        for the member. If the default colour is the one rendered then an instance
+        of :meth:`Colour.default` is returned.
+
+        There is an alias for this under ``color``.
+        """
+
+        roles = self.roles[1:]  # remove @everyone
+
+        # highest order of the colour is the one that gets rendered.
+        # if the highest is the default colour then the next one with a colour
+        # is chosen instead
+        for role in reversed(roles):
+            if role.colour.value:
+                return role.colour
+        return Colour.default()
+
+    color = colour
+
+    @property
+    def roles(self):
+        """A :class:`list` of :class:`Role` that the member belongs to. Note
+        that the first element of this list is always the default '@everyone'
+        role.
+
+        These roles are sorted by their position in the role hierarchy.
+        """
+        result = []
+        g = self.guild
+        for role_id in self._roles:
+            role = g.get_role(role_id)
+            if role:
+                result.append(role)
+        result.append(g.default_role)
+        result.sort()
+        return result
+
+    @property
+    def mention(self):
+        """Returns a string that mentions the member."""
+        if self.nick:
+            return "<@!%s>" % self.id
+        return "<@%s>" % self.id
+
+    @property
+    def display_name(self):
+        """Returns the user's display name.
+
+        For regular users this is just their username, but
+        if they have a guild specific nickname then that
+        is returned instead.
+        """
+        return self.nick if self.nick is not None else self.name
+
+    @property
+    def activity(self):
+        """Returns a class Union[:class:`Game`, :class:`Streaming`, :class:`Spotify`, :class:`Activity`] for the primary
+        activity the user is currently doing. Could be None if no activity is being done.
+
+        .. note::
+
+            A user may have multiple activities, these can be accessed under :attr:`activities`.
+        """
+        if self.activities:
+            return self.activities[0]
+
+    def mentioned_in(self, message):
+        """Checks if the member is mentioned in the specified message.
+
+        Parameters
+        -----------
+        message: :class:`Message`
+            The message to check if you're mentioned in.
+        """
+        if self._user.mentioned_in(message):
+            return True
+
+        for role in message.role_mentions:
+            has_role = utils.get(self.roles, id=role.id) is not None
+            if has_role:
+                return True
+
+        return False
+
+    def permissions_in(self, channel):
+        """An alias for :meth:`abc.GuildChannel.permissions_for`.
+
+        Basically equivalent to:
+
+        .. code-block:: python3
+
+            channel.permissions_for(self)
+
+        Parameters
+        -----------
+        channel
+            The channel to check your permissions for.
+        """
+        return channel.permissions_for(self)
+
+    @property
+    def top_role(self):
+        """Returns the member's highest role.
+
+        This is useful for figuring where a member stands in the role
+        hierarchy chain.
+        """
+        return self.roles[-1]
+
+    @property
+    def guild_permissions(self):
+        """Returns the member's guild permissions.
+
+        This only takes into consideration the guild permissions
+        and not most of the implied permissions or any of the
+        channel permission overwrites. For 100% accurate permission
+        calculation, please use either :meth:`permissions_in` or
+        :meth:`abc.GuildChannel.permissions_for`.
+
+        This does take into consideration guild ownership and the
+        administrator implication.
+        """
+
+        if self.guild.owner == self:
+            return Permissions.all()
+
+        base = Permissions.none()
+        for r in self.roles:
+            base.value |= r.permissions.value
+
+        if base.administrator:
+            return Permissions.all()
+
+        return base
+
+    @property
+    def voice(self):
+        """Optional[:class:`VoiceState`]: Returns the member's current voice state."""
+        return self.guild._voice_state_for(self._user.id)
+
+    async def ban(self, **kwargs):
+        """|coro|
+
+        Bans this member. Equivalent to :meth:`Guild.ban`
+        """
+        await self.guild.ban(self, **kwargs)
+
+    async def unban(self, *, reason=None):
+        """|coro|
+
+        Unbans this member. Equivalent to :meth:`Guild.unban`
+        """
+        await self.guild.unban(self, reason=reason)
+
+    async def kick(self, *, reason=None):
+        """|coro|
+
+        Kicks this member. Equivalent to :meth:`Guild.kick`
+        """
+        await self.guild.kick(self, reason=reason)
+
+    async def edit(self, *, reason=None, **fields):
+        """|coro|
+
+        Edits the member's data.
+
+        Depending on the parameter passed, this requires different permissions listed below:
+
+        +---------------+--------------------------------------+
+        |   Parameter   |              Permission              |
+        +---------------+--------------------------------------+
+        | nick          | :attr:`Permissions.manage_nicknames` |
+        +---------------+--------------------------------------+
+        | mute          | :attr:`Permissions.mute_members`     |
+        +---------------+--------------------------------------+
+        | deafen        | :attr:`Permissions.deafen_members`   |
+        +---------------+--------------------------------------+
+        | roles         | :attr:`Permissions.manage_roles`     |
+        +---------------+--------------------------------------+
+        | voice_channel | :attr:`Permissions.move_members`     |
+        +---------------+--------------------------------------+
+
+        All parameters are optional.
+
+        Parameters
+        -----------
+        nick: str
+            The member's new nickname. Use ``None`` to remove the nickname.
+        mute: bool
+            Indicates if the member should be guild muted or un-muted.
+        deafen: bool
+            Indicates if the member should be guild deafened or un-deafened.
+        roles: List[:class:`Roles`]
+            The member's new list of roles. This *replaces* the roles.
+        voice_channel: :class:`VoiceChannel`
+            The voice channel to move the member to.
+        reason: Optional[str]
+            The reason for editing this member. Shows up on the audit log.
+
+        Raises
+        -------
+        Forbidden
+            You do not have the proper permissions to the action requested.
+        HTTPException
+            The operation failed.
+        """
+        http = self._state.http
+        guild_id = self.guild.id
+        payload = {}
+
+        try:
+            nick = fields["nick"]
+        except KeyError:
+            # nick not present so...
+            pass
+        else:
+            nick = nick if nick else ""
+            if self._state.self_id == self.id:
+                await http.change_my_nickname(guild_id, nick, reason=reason)
+            else:
+                payload["nick"] = nick
+
+        deafen = fields.get("deafen")
+        if deafen is not None:
+            payload["deaf"] = deafen
+
+        mute = fields.get("mute")
+        if mute is not None:
+            payload["mute"] = mute
+
+        try:
+            vc = fields["voice_channel"]
+        except KeyError:
+            pass
+        else:
+            payload["channel_id"] = vc.id
+
+        try:
+            roles = fields["roles"]
+        except KeyError:
+            pass
+        else:
+            payload["roles"] = tuple(r.id for r in roles)
+
+        await http.edit_member(guild_id, self.id, reason=reason, **payload)
+
+        # TODO: wait for WS event for modify-in-place behaviour
+
+    async def move_to(self, channel, *, reason=None):
+        """|coro|
+
+        Moves a member to a new voice channel (they must be connected first).
+
+        You must have the :attr:`~Permissions.move_members` permission to
+        use this.
+
+        This raises the same exceptions as :meth:`edit`.
+
+        Parameters
+        -----------
+        channel: :class:`VoiceChannel`
+            The new voice channel to move the member to.
+        reason: Optional[str]
+            The reason for doing this action. Shows up on the audit log.
+        """
+        await self.edit(voice_channel=channel, reason=reason)
+
+    async def add_roles(self, *roles, reason=None, atomic=True):
+        r"""|coro|
+
+        Gives the member a number of :class:`Role`\s.
+
+        You must have the :attr:`~Permissions.manage_roles` permission to
+        use this.
+
+        Parameters
+        -----------
+        \*roles
+            An argument list of :class:`abc.Snowflake` representing a :class:`Role`
+            to give to the member.
+        reason: Optional[str]
+            The reason for adding these roles. Shows up on the audit log.
+        atomic: bool
+            Whether to atomically add roles. This will ensure that multiple
+            operations will always be applied regardless of the current
+            state of the cache.
+
+        Raises
+        -------
+        Forbidden
+            You do not have permissions to add these roles.
+        HTTPException
+            Adding roles failed.
+        """
+
+        if not atomic:
+            new_roles = utils._unique(Object(id=r.id) for s in (self.roles[1:], roles) for r in s)
+            await self.edit(roles=new_roles, reason=reason)
+        else:
+            req = self._state.http.add_role
+            guild_id = self.guild.id
+            user_id = self.id
+            for role in roles:
+                await req(guild_id, user_id, role.id, reason=reason)
+
+    async def remove_roles(self, *roles, reason=None, atomic=True):
+        r"""|coro|
+
+        Removes :class:`Role`\s from this member.
+
+        You must have the :attr:`~Permissions.manage_roles` permission to
+        use this.
+
+        Parameters
+        -----------
+        \*roles
+            An argument list of :class:`abc.Snowflake` representing a :class:`Role`
+            to remove from the member.
+        reason: Optional[str]
+            The reason for removing these roles. Shows up on the audit log.
+        atomic: bool
+            Whether to atomically remove roles. This will ensure that multiple
+            operations will always be applied regardless of the current
+            state of the cache.
+
+        Raises
+        -------
+        Forbidden
+            You do not have permissions to remove these roles.
+        HTTPException
+            Removing the roles failed.
+        """
+
+        if not atomic:
+            new_roles = [Object(id=r.id) for r in self.roles[1:]]  # remove @everyone
+            for role in roles:
+                try:
+                    new_roles.remove(Object(id=role.id))
+                except ValueError:
+                    pass
+
+            await self.edit(roles=new_roles, reason=reason)
+        else:
+            req = self._state.http.remove_role
+            guild_id = self.guild.id
+            user_id = self.id
+            for role in roles:
+                await req(guild_id, user_id, role.id, reason=reason)

discord/message.py

@@ -0,0 +1,799 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import asyncio
+import re
+
+from . import utils
+from .reaction import Reaction
+from .emoji import Emoji, PartialEmoji
+from .calls import CallMessage
+from .enums import MessageType, try_enum
+from .errors import InvalidArgument, ClientException, HTTPException
+from .embeds import Embed
+
+
+class Attachment:
+    """Represents an attachment from Discord.
+
+    Attributes
+    ------------
+    id: :class:`int`
+        The attachment ID.
+    size: :class:`int`
+        The attachment size in bytes.
+    height: Optional[:class:`int`]
+        The attachment's height, in pixels. Only applicable to images.
+    width: Optional[:class:`int`]
+        The attachment's width, in pixels. Only applicable to images.
+    filename: :class:`str`
+        The attachment's filename.
+    url: :class:`str`
+        The attachment URL. If the message this attachment was attached
+        to is deleted, then this will 404.
+    proxy_url: :class:`str`
+        The proxy URL. This is a cached version of the :attr:`~Attachment.url` in the
+        case of images. When the message is deleted, this URL might be valid for a few
+        minutes or not valid at all.
+    """
+
+    __slots__ = ("id", "size", "height", "width", "filename", "url", "proxy_url", "_http")
+
+    def __init__(self, *, data, state):
+        self.id = int(data["id"])
+        self.size = data["size"]
+        self.height = data.get("height")
+        self.width = data.get("width")
+        self.filename = data["filename"]
+        self.url = data.get("url")
+        self.proxy_url = data.get("proxy_url")
+        self._http = state.http
+
+    def is_spoiler(self):
+        """:class:`bool`: Whether this attachment contains a spoiler."""
+        return self.filename.startswith("SPOILER_")
+
+    async def save(self, fp, *, seek_begin=True):
+        """|coro|
+
+        Saves this attachment into a file-like object.
+
+        Parameters
+        -----------
+        fp: Union[BinaryIO, str]
+            The file-like object to save this attachment to or the filename
+            to use. If a filename is passed then a file is created with that
+            filename and used instead.
+        seek_begin: bool
+            Whether to seek to the beginning of the file after saving is
+            successfully done.
+
+        Raises
+        --------
+        HTTPException
+            Saving the attachment failed.
+        NotFound
+            The attachment was deleted.
+
+        Returns
+        --------
+        int
+            The number of bytes written.
+        """
+
+        data = await self._http.get_attachment(self.url)
+        if isinstance(fp, str):
+            with open(fp, "wb") as f:
+                return f.write(data)
+        else:
+            written = fp.write(data)
+            if seek_begin:
+                fp.seek(0)
+            return written
+
+
+class Message:
+    r"""Represents a message from Discord.
+
+    There should be no need to create one of these manually.
+
+    Attributes
+    -----------
+    tts: :class:`bool`
+        Specifies if the message was done with text-to-speech.
+    type: :class:`MessageType`
+        The type of message. In most cases this should not be checked, but it is helpful
+        in cases where it might be a system message for :attr:`system_content`.
+    author
+        A :class:`Member` that sent the message. If :attr:`channel` is a
+        private channel or the user has the left the guild, then it is a :class:`User` instead.
+    content: :class:`str`
+        The actual contents of the message.
+    nonce
+        The value used by the discord guild and the client to verify that the message is successfully sent.
+        This is typically non-important.
+    embeds: List[:class:`Embed`]
+        A list of embeds the message has.
+    channel
+        The :class:`TextChannel` that the message was sent from.
+        Could be a :class:`DMChannel` or :class:`GroupChannel` if it's a private message.
+    call: Optional[:class:`CallMessage`]
+        The call that the message refers to. This is only applicable to messages of type
+        :attr:`MessageType.call`.
+    mention_everyone: :class:`bool`
+        Specifies if the message mentions everyone.
+
+        .. note::
+
+            This does not check if the ``@everyone`` or the ``@here`` text is in the message itself.
+            Rather this boolean indicates if either the ``@everyone`` or the ``@here`` text is in the message
+            **and** it did end up mentioning.
+
+    mentions: :class:`list`
+        A list of :class:`Member` that were mentioned. If the message is in a private message
+        then the list will be of :class:`User` instead. For messages that are not of type
+        :attr:`MessageType.default`\, this array can be used to aid in system messages.
+        For more information, see :attr:`system_content`.
+
+        .. warning::
+
+            The order of the mentions list is not in any particular order so you should
+            not rely on it. This is a discord limitation, not one with the library.
+
+    channel_mentions: :class:`list`
+        A list of :class:`abc.GuildChannel` that were mentioned. If the message is in a private message
+        then the list is always empty.
+    role_mentions: :class:`list`
+        A list of :class:`Role` that were mentioned. If the message is in a private message
+        then the list is always empty.
+    id: :class:`int`
+        The message ID.
+    webhook_id: Optional[:class:`int`]
+        If this message was sent by a webhook, then this is the webhook ID's that sent this
+        message.
+    attachments: List[:class:`Attachment`]
+        A list of attachments given to a message.
+    pinned: :class:`bool`
+        Specifies if the message is currently pinned.
+    reactions : List[:class:`Reaction`]
+        Reactions to a message. Reactions can be either custom emoji or standard unicode emoji.
+    activity: Optional[:class:`dict`]
+        The activity associated with this message. Sent with Rich-Presence related messages that for
+        example, request joining, spectating, or listening to or with another member.
+
+        It is a dictionary with the following optional keys:
+
+        - ``type``: An integer denoting the type of message activity being requested.
+        - ``party_id``: The party ID associated with the party.
+    application: Optional[:class:`dict`]
+        The rich presence enabled application associated with this message.
+
+        It is a dictionary with the following keys:
+
+        - ``id``: A string representing the application's ID.
+        - ``name``: A string representing the application's name.
+        - ``description``: A string representing the application's description.
+        - ``icon``: A string representing the icon ID of the application.
+        - ``cover_image``: A string representing the embed's image asset ID.
+    """
+
+    __slots__ = (
+        "_edited_timestamp",
+        "tts",
+        "content",
+        "channel",
+        "webhook_id",
+        "mention_everyone",
+        "embeds",
+        "id",
+        "mentions",
+        "author",
+        "_cs_channel_mentions",
+        "_cs_raw_mentions",
+        "attachments",
+        "_cs_clean_content",
+        "_cs_raw_channel_mentions",
+        "nonce",
+        "pinned",
+        "role_mentions",
+        "_cs_raw_role_mentions",
+        "type",
+        "call",
+        "_cs_system_content",
+        "_cs_guild",
+        "_state",
+        "reactions",
+        "application",
+        "activity",
+    )
+
+    def __init__(self, *, state, channel, data):
+        self._state = state
+        self.id = int(data["id"])
+        self.webhook_id = utils._get_as_snowflake(data, "webhook_id")
+        self.reactions = [Reaction(message=self, data=d) for d in data.get("reactions", [])]
+        self.application = data.get("application")
+        self.activity = data.get("activity")
+        self._update(channel, data)
+
+    def __repr__(self):
+        return "<Message id={0.id} pinned={0.pinned} author={0.author!r}>".format(self)
+
+    def _try_patch(self, data, key, transform=None):
+        try:
+            value = data[key]
+        except KeyError:
+            pass
+        else:
+            if transform is None:
+                setattr(self, key, value)
+            else:
+                setattr(self, key, transform(value))
+
+    def _add_reaction(self, data, emoji, user_id):
+        reaction = utils.find(lambda r: r.emoji == emoji, self.reactions)
+        is_me = data["me"] = user_id == self._state.self_id
+
+        if reaction is None:
+            reaction = Reaction(message=self, data=data, emoji=emoji)
+            self.reactions.append(reaction)
+        else:
+            reaction.count += 1
+            if is_me:
+                reaction.me = is_me
+
+        return reaction
+
+    def _remove_reaction(self, data, emoji, user_id):
+        reaction = utils.find(lambda r: r.emoji == emoji, self.reactions)
+
+        if reaction is None:
+            # already removed?
+            raise ValueError("Emoji already removed?")
+
+        # if reaction isn't in the list, we crash. This means discord
+        # sent bad data, or we stored improperly
+        reaction.count -= 1
+
+        if user_id == self._state.self_id:
+            reaction.me = False
+        if reaction.count == 0:
+            # this raises ValueError if something went wrong as well.
+            self.reactions.remove(reaction)
+
+        return reaction
+
+    def _update(self, channel, data):
+        self.channel = channel
+        self._edited_timestamp = utils.parse_time(data.get("edited_timestamp"))
+        self._try_patch(data, "pinned")
+        self._try_patch(data, "application")
+        self._try_patch(data, "activity")
+        self._try_patch(data, "mention_everyone")
+        self._try_patch(data, "tts")
+        self._try_patch(data, "type", lambda x: try_enum(MessageType, x))
+        self._try_patch(data, "content")
+        self._try_patch(
+            data, "attachments", lambda x: [Attachment(data=a, state=self._state) for a in x]
+        )
+        self._try_patch(data, "embeds", lambda x: list(map(Embed.from_data, x)))
+        self._try_patch(data, "nonce")
+
+        for handler in ("author", "mentions", "mention_roles", "call"):
+            try:
+                getattr(self, "_handle_%s" % handler)(data[handler])
+            except KeyError:
+                continue
+
+        # clear the cached properties
+        cached = filter(lambda attr: attr.startswith("_cs_"), self.__slots__)
+        for attr in cached:
+            try:
+                delattr(self, attr)
+            except AttributeError:
+                pass
+
+    def _handle_author(self, author):
+        self.author = self._state.store_user(author)
+        if self.guild is not None:
+            found = self.guild.get_member(self.author.id)
+            if found is not None:
+                self.author = found
+
+    def _handle_mentions(self, mentions):
+        self.mentions = []
+        if self.guild is None:
+            self.mentions = [self._state.store_user(m) for m in mentions]
+            return
+
+        for mention in filter(None, mentions):
+            id_search = int(mention["id"])
+            member = self.guild.get_member(id_search)
+            if member is not None:
+                self.mentions.append(member)
+
+    def _handle_mention_roles(self, role_mentions):
+        self.role_mentions = []
+        if self.guild is not None:
+            for role_id in map(int, role_mentions):
+                role = self.guild.get_role(role_id)
+                if role is not None:
+                    self.role_mentions.append(role)
+
+    def _handle_call(self, call):
+        if call is None or self.type is not MessageType.call:
+            self.call = None
+            return
+
+        # we get the participant source from the mentions array or
+        # the author
+
+        participants = []
+        for uid in map(int, call.get("participants", [])):
+            if uid == self.author.id:
+                participants.append(self.author)
+            else:
+                user = utils.find(lambda u: u.id == uid, self.mentions)
+                if user is not None:
+                    participants.append(user)
+
+        call["participants"] = participants
+        self.call = CallMessage(message=self, **call)
+
+    @utils.cached_slot_property("_cs_guild")
+    def guild(self):
+        """Optional[:class:`Guild`]: The guild that the message belongs to, if applicable."""
+        return getattr(self.channel, "guild", None)
+
+    @utils.cached_slot_property("_cs_raw_mentions")
+    def raw_mentions(self):
+        """A property that returns an array of user IDs matched with
+        the syntax of <@user_id> in the message content.
+
+        This allows you to receive the user IDs of mentioned users
+        even in a private message context.
+        """
+        return [int(x) for x in re.findall(r"<@!?([0-9]+)>", self.content)]
+
+    @utils.cached_slot_property("_cs_raw_channel_mentions")
+    def raw_channel_mentions(self):
+        """A property that returns an array of channel IDs matched with
+        the syntax of <#channel_id> in the message content.
+        """
+        return [int(x) for x in re.findall(r"<#([0-9]+)>", self.content)]
+
+    @utils.cached_slot_property("_cs_raw_role_mentions")
+    def raw_role_mentions(self):
+        """A property that returns an array of role IDs matched with
+        the syntax of <@&role_id> in the message content.
+        """
+        return [int(x) for x in re.findall(r"<@&([0-9]+)>", self.content)]
+
+    @utils.cached_slot_property("_cs_channel_mentions")
+    def channel_mentions(self):
+        if self.guild is None:
+            return []
+        it = filter(None, map(self.guild.get_channel, self.raw_channel_mentions))
+        return utils._unique(it)
+
+    @utils.cached_slot_property("_cs_clean_content")
+    def clean_content(self):
+        """A property that returns the content in a "cleaned up"
+        manner. This basically means that mentions are transformed
+        into the way the client shows it. e.g. ``<#id>`` will transform
+        into ``#name``.
+
+        This will also transform @everyone and @here mentions into
+        non-mentions.
+        """
+
+        transformations = {
+            re.escape("<#%s>" % channel.id): "#" + channel.name
+            for channel in self.channel_mentions
+        }
+
+        mention_transforms = {
+            re.escape("<@%s>" % member.id): "@" + member.display_name for member in self.mentions
+        }
+
+        # add the <@!user_id> cases as well..
+        second_mention_transforms = {
+            re.escape("<@!%s>" % member.id): "@" + member.display_name for member in self.mentions
+        }
+
+        transformations.update(mention_transforms)
+        transformations.update(second_mention_transforms)
+
+        if self.guild is not None:
+            role_transforms = {
+                re.escape("<@&%s>" % role.id): "@" + role.name for role in self.role_mentions
+            }
+            transformations.update(role_transforms)
+
+        def repl(obj):
+            return transformations.get(re.escape(obj.group(0)), "")
+
+        pattern = re.compile("|".join(transformations.keys()))
+        result = pattern.sub(repl, self.content)
+
+        transformations = {"@everyone": "@\u200beveryone", "@here": "@\u200bhere"}
+
+        def repl2(obj):
+            return transformations.get(obj.group(0), "")
+
+        pattern = re.compile("|".join(transformations.keys()))
+        return pattern.sub(repl2, result)
+
+    @property
+    def created_at(self):
+        """datetime.datetime: The message's creation time in UTC."""
+        return utils.snowflake_time(self.id)
+
+    @property
+    def edited_at(self):
+        """Optional[datetime.datetime]: A naive UTC datetime object containing the edited time of the message."""
+        return self._edited_timestamp
+
+    @property
+    def jump_url(self):
+        """:class:`str`: Returns a URL that allows the client to jump to this message."""
+        guild_id = getattr(self.guild, "id", "@me")
+        return "https://discordapp.com/channels/{0}/{1.channel.id}/{1.id}".format(guild_id, self)
+
+    @utils.cached_slot_property("_cs_system_content")
+    def system_content(self):
+        r"""A property that returns the content that is rendered
+        regardless of the :attr:`Message.type`.
+
+        In the case of :attr:`MessageType.default`\, this just returns the
+        regular :attr:`Message.content`. Otherwise this returns an English
+        message denoting the contents of the system message.
+        """
+
+        if self.type is MessageType.default:
+            return self.content
+
+        if self.type is MessageType.pins_add:
+            return "{0.name} pinned a message to this channel.".format(self.author)
+
+        if self.type is MessageType.recipient_add:
+            return "{0.name} added {1.name} to the group.".format(self.author, self.mentions[0])
+
+        if self.type is MessageType.recipient_remove:
+            return "{0.name} removed {1.name} from the group.".format(
+                self.author, self.mentions[0]
+            )
+
+        if self.type is MessageType.channel_name_change:
+            return "{0.author.name} changed the channel name: {0.content}".format(self)
+
+        if self.type is MessageType.channel_icon_change:
+            return "{0.author.name} changed the channel icon.".format(self)
+
+        if self.type is MessageType.new_member:
+            formats = [
+                "{0} just joined the server - glhf!",
+                "{0} just joined. Everyone, look busy!",
+                "{0} just joined. Can I get a heal?",
+                "{0} joined your party.",
+                "{0} joined. You must construct additional pylons.",
+                "Ermagherd. {0} is here.",
+                "Welcome, {0}. Stay awhile and listen.",
+                "Welcome, {0}. We were expecting you ( ͡° ͜ʖ ͡°)",
+                "Welcome, {0}. We hope you brought pizza.",
+                "Welcome {0}. Leave your weapons by the door.",
+                "A wild {0} appeared.",
+                "Swoooosh. {0} just landed.",
+                "Brace yourselves. {0} just joined the server.",
+                "{0} just joined. Hide your bananas.",
+                "{0} just arrived. Seems OP - please nerf.",
+                "{0} just slid into the server.",
+                "A {0} has spawned in the server.",
+                "Big {0} showed up!",
+                "Where’s {0}? In the server!",
+                "{0} hopped into the server. Kangaroo!!",
+                "{0} just showed up. Hold my beer.",
+                "Challenger approaching - {0} has appeared!",
+                "It's a bird! It's a plane! Nevermind, it's just {0}.",
+                "It's {0}! Praise the sun! [T]/",
+                "Never gonna give {0} up. Never gonna let {0} down.",
+                "Ha! {0} has joined! You activated my trap card!",
+                "Cheers, love! {0}'s here!",
+                "Hey! Listen! {0} has joined!",
+                "We've been expecting you {0}",
+                "It's dangerous to go alone, take {0}!",
+                "{0} has joined the server! It's super effective!",
+                "Cheers, love! {0} is here!",
+                "{0} is here, as the prophecy foretold.",
+                "{0} has arrived. Party's over.",
+                "Ready player {0}",
+                "{0} is here to kick butt and chew bubblegum. And {0} is all out of gum.",
+                "Hello. Is it {0} you're looking for?",
+                "{0} has joined. Stay a while and listen!",
+                "Roses are red, violets are blue, {0} joined this server with you",
+            ]
+
+            index = int(self.created_at.timestamp()) % len(formats)
+            return formats[index].format(self.author.name)
+
+        if self.type is MessageType.call:
+            # we're at the call message type now, which is a bit more complicated.
+            # we can make the assumption that Message.channel is a PrivateChannel
+            # with the type ChannelType.group or ChannelType.private
+            call_ended = self.call.ended_timestamp is not None
+
+            if self.channel.me in self.call.participants:
+                return "{0.author.name} started a call.".format(self)
+            elif call_ended:
+                return "You missed a call from {0.author.name}".format(self)
+            else:
+                return "{0.author.name} started a call \N{EM DASH} Join the call.".format(self)
+
+    async def delete(self):
+        """|coro|
+
+        Deletes the message.
+
+        Your own messages could be deleted without any proper permissions. However to
+        delete other people's messages, you need the :attr:`~Permissions.manage_messages`
+        permission.
+
+        Raises
+        ------
+        Forbidden
+            You do not have proper permissions to delete the message.
+        HTTPException
+            Deleting the message failed.
+        """
+        await self._state.http.delete_message(self.channel.id, self.id)
+
+    async def edit(self, **fields):
+        """|coro|
+
+        Edits the message.
+
+        The content must be able to be transformed into a string via ``str(content)``.
+
+        Parameters
+        -----------
+        content: Optional[str]
+            The new content to replace the message with.
+            Could be ``None`` to remove the content.
+        embed: Optional[:class:`Embed`]
+            The new embed to replace the original with.
+            Could be ``None`` to remove the embed.
+        delete_after: Optional[float]
+            If provided, the number of seconds to wait in the background
+            before deleting the message we just edited. If the deletion fails,
+            then it is silently ignored.
+
+        Raises
+        -------
+        HTTPException
+            Editing the message failed.
+        """
+
+        try:
+            content = fields["content"]
+        except KeyError:
+            pass
+        else:
+            if content is not None:
+                fields["content"] = str(content)
+
+        try:
+            embed = fields["embed"]
+        except KeyError:
+            pass
+        else:
+            if embed is not None:
+                fields["embed"] = embed.to_dict()
+
+        data = await self._state.http.edit_message(self.id, self.channel.id, **fields)
+        self._update(channel=self.channel, data=data)
+
+        try:
+            delete_after = fields["delete_after"]
+        except KeyError:
+            pass
+        else:
+            if delete_after is not None:
+
+                async def delete():
+                    await asyncio.sleep(delete_after, loop=self._state.loop)
+                    try:
+                        await self._state.http.delete_message(self.channel.id, self.id)
+                    except HTTPException:
+                        pass
+
+                asyncio.ensure_future(delete(), loop=self._state.loop)
+
+    async def pin(self):
+        """|coro|
+
+        Pins the message.
+
+        You must have the :attr:`~Permissions.manage_messages` permission to do
+        this in a non-private channel context.
+
+        Raises
+        -------
+        Forbidden
+            You do not have permissions to pin the message.
+        NotFound
+            The message or channel was not found or deleted.
+        HTTPException
+            Pinning the message failed, probably due to the channel
+            having more than 50 pinned messages.
+        """
+
+        await self._state.http.pin_message(self.channel.id, self.id)
+        self.pinned = True
+
+    async def unpin(self):
+        """|coro|
+
+        Unpins the message.
+
+        You must have the :attr:`~Permissions.manage_messages` permission to do
+        this in a non-private channel context.
+
+        Raises
+        -------
+        Forbidden
+            You do not have permissions to unpin the message.
+        NotFound
+            The message or channel was not found or deleted.
+        HTTPException
+            Unpinning the message failed.
+        """
+
+        await self._state.http.unpin_message(self.channel.id, self.id)
+        self.pinned = False
+
+    async def add_reaction(self, emoji):
+        """|coro|
+
+        Add a reaction to the message.
+
+        The emoji may be a unicode emoji or a custom guild :class:`Emoji`.
+
+        You must have the :attr:`~Permissions.read_message_history` permission
+        to use this. If nobody else has reacted to the message using this
+        emoji, the :attr:`~Permissions.add_reactions` permission is required.
+
+        Parameters
+        ------------
+        emoji: Union[:class:`Emoji`, :class:`Reaction`, :class:`PartialEmoji`, str]
+            The emoji to react with.
+
+        Raises
+        --------
+        HTTPException
+            Adding the reaction failed.
+        Forbidden
+            You do not have the proper permissions to react to the message.
+        NotFound
+            The emoji you specified was not found.
+        InvalidArgument
+            The emoji parameter is invalid.
+        """
+
+        emoji = self._emoji_reaction(emoji)
+        await self._state.http.add_reaction(self.id, self.channel.id, emoji)
+
+    async def remove_reaction(self, emoji, member):
+        """|coro|
+
+        Remove a reaction by the member from the message.
+
+        The emoji may be a unicode emoji or a custom guild :class:`Emoji`.
+
+        If the reaction is not your own (i.e. ``member`` parameter is not you) then
+        the :attr:`~Permissions.manage_messages` permission is needed.
+
+        The ``member`` parameter must represent a member and meet
+        the :class:`abc.Snowflake` abc.
+
+        Parameters
+        ------------
+        emoji: Union[:class:`Emoji`, :class:`Reaction`, :class:`PartialEmoji`, str]
+            The emoji to remove.
+        member: :class:`abc.Snowflake`
+            The member for which to remove the reaction.
+
+        Raises
+        --------
+        HTTPException
+            Removing the reaction failed.
+        Forbidden
+            You do not have the proper permissions to remove the reaction.
+        NotFound
+            The member or emoji you specified was not found.
+        InvalidArgument
+            The emoji parameter is invalid.
+        """
+
+        emoji = self._emoji_reaction(emoji)
+
+        if member.id == self._state.self_id:
+            await self._state.http.remove_own_reaction(self.id, self.channel.id, emoji)
+        else:
+            await self._state.http.remove_reaction(self.id, self.channel.id, emoji, member.id)
+
+    @staticmethod
+    def _emoji_reaction(emoji):
+        if isinstance(emoji, Reaction):
+            emoji = emoji.emoji
+
+        if isinstance(emoji, Emoji):
+            return "%s:%s" % (emoji.name, emoji.id)
+        if isinstance(emoji, PartialEmoji):
+            return emoji._as_reaction()
+        if isinstance(emoji, str):
+            return emoji  # this is okay
+
+        raise InvalidArgument(
+            "emoji argument must be str, Emoji, or Reaction not {.__class__.__name__}.".format(
+                emoji
+            )
+        )
+
+    async def clear_reactions(self):
+        """|coro|
+
+        Removes all the reactions from the message.
+
+        You need the :attr:`~Permissions.manage_messages` permission to use this.
+
+        Raises
+        --------
+        HTTPException
+            Removing the reactions failed.
+        Forbidden
+            You do not have the proper permissions to remove all the reactions.
+        """
+        await self._state.http.clear_reactions(self.id, self.channel.id)
+
+    def ack(self):
+        """|coro|
+
+        Marks this message as read.
+
+        The user must not be a bot user.
+
+        Raises
+        -------
+        HTTPException
+            Acking failed.
+        ClientException
+            You must not be a bot user.
+        """
+
+        state = self._state
+        if state.is_bot:
+            raise ClientException("Must not be a bot account to ack messages.")
+        return state.http.ack_message(self.channel.id, self.id)

discord/mixins.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+
+class EqualityComparable:
+    __slots__ = ()
+
+    def __eq__(self, other):
+        return isinstance(other, self.__class__) and other.id == self.id
+
+    def __ne__(self, other):
+        if isinstance(other, self.__class__):
+            return other.id != self.id
+        return True
+
+
+class Hashable(EqualityComparable):
+    __slots__ = ()
+
+    def __hash__(self):
+        return self.id >> 22

discord/object.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from . import utils
+from .mixins import Hashable
+
+
+class Object(Hashable):
+    """Represents a generic Discord object.
+
+    The purpose of this class is to allow you to create 'miniature'
+    versions of data classes if you want to pass in just an ID. Most functions
+    that take in a specific data class with an ID can also take in this class
+    as a substitute instead. Note that even though this is the case, not all
+    objects (if any) actually inherit from this class.
+
+    There are also some cases where some websocket events are received
+    in :issue:`strange order <21>` and when such events happened you would
+    receive this class rather than the actual data class. These cases are
+    extremely rare.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two objects are equal.
+
+        .. describe:: x != y
+
+            Checks if two objects are not equal.
+
+        .. describe:: hash(x)
+
+            Returns the object's hash.
+
+    Attributes
+    -----------
+    id : :class:`str`
+        The ID of the object.
+    """
+
+    def __init__(self, id):
+        self.id = id
+
+    @property
+    def created_at(self):
+        """Returns the snowflake's creation time in UTC."""
+        return utils.snowflake_time(self.id)

discord/opus.py

@@ -0,0 +1,286 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import array
+import ctypes
+import ctypes.util
+import logging
+import os.path
+import sys
+
+from .errors import DiscordException
+
+log = logging.getLogger(__name__)
+c_int_ptr = ctypes.POINTER(ctypes.c_int)
+c_int16_ptr = ctypes.POINTER(ctypes.c_int16)
+c_float_ptr = ctypes.POINTER(ctypes.c_float)
+
+
+class EncoderStruct(ctypes.Structure):
+    pass
+
+
+EncoderStructPtr = ctypes.POINTER(EncoderStruct)
+
+
+def _err_lt(result, func, args):
+    if result < 0:
+        log.info("error has happened in %s", func.__name__)
+        raise OpusError(result)
+    return result
+
+
+def _err_ne(result, func, args):
+    ret = args[-1]._obj
+    if ret.value != 0:
+        log.info("error has happened in %s", func.__name__)
+        raise OpusError(ret.value)
+    return result
+
+
+# A list of exported functions.
+# The first argument is obviously the name.
+# The second one are the types of arguments it takes.
+# The third is the result type.
+# The fourth is the error handler.
+exported_functions = [
+    ("opus_strerror", [ctypes.c_int], ctypes.c_char_p, None),
+    ("opus_encoder_get_size", [ctypes.c_int], ctypes.c_int, None),
+    (
+        "opus_encoder_create",
+        [ctypes.c_int, ctypes.c_int, ctypes.c_int, c_int_ptr],
+        EncoderStructPtr,
+        _err_ne,
+    ),
+    (
+        "opus_encode",
+        [EncoderStructPtr, c_int16_ptr, ctypes.c_int, ctypes.c_char_p, ctypes.c_int32],
+        ctypes.c_int32,
+        _err_lt,
+    ),
+    ("opus_encoder_ctl", None, ctypes.c_int32, _err_lt),
+    ("opus_encoder_destroy", [EncoderStructPtr], None, None),
+]
+
+
+def libopus_loader(name):
+    # create the library...
+    lib = ctypes.cdll.LoadLibrary(name)
+
+    # register the functions...
+    for item in exported_functions:
+        func = getattr(lib, item[0])
+
+        try:
+            if item[1]:
+                func.argtypes = item[1]
+
+            func.restype = item[2]
+        except KeyError:
+            pass
+
+        try:
+            if item[3]:
+                func.errcheck = item[3]
+        except KeyError:
+            log.exception("Error assigning check function to %s", func)
+
+    return lib
+
+
+try:
+    if sys.platform == "win32":
+        _basedir = os.path.dirname(os.path.abspath(__file__))
+        _bitness = "x64" if sys.maxsize > 2 ** 32 else "x86"
+        _filename = os.path.join(_basedir, "bin", "libopus-0.{}.dll".format(_bitness))
+        _lib = libopus_loader(_filename)
+    else:
+        _lib = libopus_loader(ctypes.util.find_library("opus"))
+except Exception:
+    _lib = None
+
+
+def load_opus(name):
+    """Loads the libopus shared library for use with voice.
+
+    If this function is not called then the library uses the function
+    `ctypes.util.find_library`__ and then loads that one
+    if available.
+
+    .. _find library: https://docs.python.org/3.5/library/ctypes.html#finding-shared-libraries
+    __ `find library`_
+
+    Not loading a library leads to voice not working.
+
+    This function propagates the exceptions thrown.
+
+    Warning
+    --------
+    The bitness of the library must match the bitness of your python
+    interpreter. If the library is 64-bit then your python interpreter
+    must be 64-bit as well. Usually if there's a mismatch in bitness then
+    the load will throw an exception.
+
+    Note
+    ----
+    On Windows, the .dll extension is not necessary. However, on Linux
+    the full extension is required to load the library, e.g. ``libopus.so.1``.
+    On Linux however, `find library`_ will usually find the library automatically
+    without you having to call this.
+
+    Parameters
+    ----------
+    name: str
+        The filename of the shared library.
+    """
+    global _lib
+    _lib = libopus_loader(name)
+
+
+def is_loaded():
+    """Function to check if opus lib is successfully loaded either
+    via the ``ctypes.util.find_library`` call of :func:`load_opus`.
+
+    This must return ``True`` for voice to work.
+
+    Returns
+    -------
+    bool
+        Indicates if the opus library has been loaded.
+    """
+    global _lib
+    return _lib is not None
+
+
+class OpusError(DiscordException):
+    """An exception that is thrown for libopus related errors.
+
+    Attributes
+    ----------
+    code : :class:`int`
+        The error code returned.
+    """
+
+    def __init__(self, code):
+        self.code = code
+        msg = _lib.opus_strerror(self.code).decode("utf-8")
+        log.info('"%s" has happened', msg)
+        super().__init__(msg)
+
+
+class OpusNotLoaded(DiscordException):
+    """An exception that is thrown for when libopus is not loaded."""
+
+    pass
+
+
+# Some constants...
+OK = 0
+APPLICATION_AUDIO = 2049
+APPLICATION_VOIP = 2048
+APPLICATION_LOWDELAY = 2051
+CTL_SET_BITRATE = 4002
+CTL_SET_BANDWIDTH = 4008
+CTL_SET_FEC = 4012
+CTL_SET_PLP = 4014
+CTL_SET_SIGNAL = 4024
+
+band_ctl = {"narrow": 1101, "medium": 1102, "wide": 1103, "superwide": 1104, "full": 1105}
+
+signal_ctl = {"auto": -1000, "voice": 3001, "music": 3002}
+
+
+class Encoder:
+    SAMPLING_RATE = 48000
+    CHANNELS = 2
+    FRAME_LENGTH = 20
+    SAMPLE_SIZE = 4  # (bit_rate / 8) * CHANNELS (bit_rate == 16)
+    SAMPLES_PER_FRAME = int(SAMPLING_RATE / 1000 * FRAME_LENGTH)
+
+    FRAME_SIZE = SAMPLES_PER_FRAME * SAMPLE_SIZE
+
+    def __init__(self, application=APPLICATION_AUDIO):
+        self.application = application
+
+        if not is_loaded():
+            raise OpusNotLoaded()
+
+        self._state = self._create_state()
+        self.set_bitrate(128)
+        self.set_fec(True)
+        self.set_expected_packet_loss_percent(0.15)
+        self.set_bandwidth("full")
+        self.set_signal_type("auto")
+
+    def __del__(self):
+        if hasattr(self, "_state"):
+            _lib.opus_encoder_destroy(self._state)
+            self._state = None
+
+    def _create_state(self):
+        ret = ctypes.c_int()
+        return _lib.opus_encoder_create(
+            self.SAMPLING_RATE, self.CHANNELS, self.application, ctypes.byref(ret)
+        )
+
+    def set_bitrate(self, kbps):
+        kbps = min(128, max(16, int(kbps)))
+
+        _lib.opus_encoder_ctl(self._state, CTL_SET_BITRATE, kbps * 1024)
+        return kbps
+
+    def set_bandwidth(self, req):
+        if req not in band_ctl:
+            raise KeyError(
+                "%r is not a valid bandwidth setting. Try one of: %s" % (req, ",".join(band_ctl))
+            )
+
+        k = band_ctl[req]
+        _lib.opus_encoder_ctl(self._state, CTL_SET_BANDWIDTH, k)
+
+    def set_signal_type(self, req):
+        if req not in signal_ctl:
+            raise KeyError(
+                "%r is not a valid signal setting. Try one of: %s" % (req, ",".join(signal_ctl))
+            )
+
+        k = signal_ctl[req]
+        _lib.opus_encoder_ctl(self._state, CTL_SET_SIGNAL, k)
+
+    def set_fec(self, enabled=True):
+        _lib.opus_encoder_ctl(self._state, CTL_SET_FEC, 1 if enabled else 0)
+
+    def set_expected_packet_loss_percent(self, percentage):
+        _lib.opus_encoder_ctl(self._state, CTL_SET_PLP, min(100, max(0, int(percentage * 100))))
+
+    def encode(self, pcm, frame_size):
+        max_data_bytes = len(pcm)
+        pcm = ctypes.cast(pcm, c_int16_ptr)
+        data = (ctypes.c_char * max_data_bytes)()
+
+        ret = _lib.opus_encode(self._state, pcm, frame_size, data, max_data_bytes)
+
+        return array.array("b", data[:ret]).tobytes()

discord/permissions.py

@@ -0,0 +1,643 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+
+class Permissions:
+    """Wraps up the Discord permission value.
+
+    The properties provided are two way. You can set and retrieve individual
+    bits using the properties as if they were regular bools. This allows
+    you to edit permissions.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two permissions are equal.
+        .. describe:: x != y
+
+            Checks if two permissions are not equal.
+        .. describe:: x <= y
+
+            Checks if a permission is a subset of another permission.
+        .. describe:: x >= y
+
+            Checks if a permission is a superset of another permission.
+        .. describe:: x < y
+
+             Checks if a permission is a strict subset of another permission.
+        .. describe:: x > y
+
+             Checks if a permission is a strict superset of another permission.
+        .. describe:: hash(x)
+
+               Return the permission's hash.
+        .. describe:: iter(x)
+
+               Returns an iterator of ``(perm, value)`` pairs. This allows it
+               to be, for example, constructed as a dict or a list of pairs.
+
+    Attributes
+    -----------
+    value
+        The raw value. This value is a bit array field of a 53-bit integer
+        representing the currently available permissions. You should query
+        permissions via the properties rather than using this raw value.
+    """
+
+    __slots__ = ("value",)
+
+    def __init__(self, permissions=0):
+        if not isinstance(permissions, int):
+            raise TypeError(
+                "Expected int parameter, received %s instead." % permissions.__class__.__name__
+            )
+
+        self.value = permissions
+
+    def __eq__(self, other):
+        return isinstance(other, Permissions) and self.value == other.value
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def __hash__(self):
+        return hash(self.value)
+
+    def __repr__(self):
+        return "<Permissions value=%s>" % self.value
+
+    def _perm_iterator(self):
+        for attr in dir(self):
+            # check if it's a property, because if so it's a permission
+            is_property = isinstance(getattr(self.__class__, attr), property)
+            if is_property:
+                yield (attr, getattr(self, attr))
+
+    def __iter__(self):
+        return self._perm_iterator()
+
+    def is_subset(self, other):
+        """Returns True if self has the same or fewer permissions as other."""
+        if isinstance(other, Permissions):
+            return (self.value & other.value) == self.value
+        else:
+            raise TypeError(
+                "cannot compare {} with {}".format(
+                    self.__class__.__name__, other.__class__.__name__
+                )
+            )
+
+    def is_superset(self, other):
+        """Returns True if self has the same or more permissions as other."""
+        if isinstance(other, Permissions):
+            return (self.value | other.value) == self.value
+        else:
+            raise TypeError(
+                "cannot compare {} with {}".format(
+                    self.__class__.__name__, other.__class__.__name__
+                )
+            )
+
+    def is_strict_subset(self, other):
+        """Returns True if the permissions on other are a strict subset of those on self."""
+        return self.is_subset(other) and self != other
+
+    def is_strict_superset(self, other):
+        """Returns True if the permissions on other are a strict superset of those on self."""
+        return self.is_superset(other) and self != other
+
+    __le__ = is_subset
+    __ge__ = is_superset
+    __lt__ = is_strict_subset
+    __gt__ = is_strict_superset
+
+    @classmethod
+    def none(cls):
+        """A factory method that creates a :class:`Permissions` with all
+        permissions set to False."""
+        return cls(0)
+
+    @classmethod
+    def all(cls):
+        """A factory method that creates a :class:`Permissions` with all
+        permissions set to True."""
+        return cls(0b01111111111101111111110111111111)
+
+    @classmethod
+    def all_channel(cls):
+        """A :class:`Permissions` with all channel-specific permissions set to
+        True and the guild-specific ones set to False. The guild-specific
+        permissions are currently:
+
+        - manage_guild
+        - kick_members
+        - ban_members
+        - administrator
+        - change_nickname
+        - manage_nicknames
+        """
+        return cls(0b00110011111101111111110001010001)
+
+    @classmethod
+    def general(cls):
+        """A factory method that creates a :class:`Permissions` with all
+        "General" permissions from the official Discord UI set to True."""
+        return cls(0b01111100000000000000000010111111)
+
+    @classmethod
+    def text(cls):
+        """A factory method that creates a :class:`Permissions` with all
+        "Text" permissions from the official Discord UI set to True."""
+        return cls(0b00000000000001111111110001000000)
+
+    @classmethod
+    def voice(cls):
+        """A factory method that creates a :class:`Permissions` with all
+        "Voice" permissions from the official Discord UI set to True."""
+        return cls(0b00000011111100000000000100000000)
+
+    def update(self, **kwargs):
+        r"""Bulk updates this permission object.
+
+        Allows you to set multiple attributes by using keyword
+        arguments. The names must be equivalent to the properties
+        listed. Extraneous key/value pairs will be silently ignored.
+
+        Parameters
+        ------------
+        \*\*kwargs
+            A list of key/value pairs to bulk update permissions with.
+        """
+        for key, value in kwargs.items():
+            try:
+                is_property = isinstance(getattr(self.__class__, key), property)
+            except AttributeError:
+                continue
+
+            if is_property:
+                setattr(self, key, value)
+
+    def _bit(self, index):
+        return bool((self.value >> index) & 1)
+
+    def _set(self, index, value):
+        if value is True:
+            self.value |= 1 << index
+        elif value is False:
+            self.value &= ~(1 << index)
+        else:
+            raise TypeError("Value to set for Permissions must be a bool.")
+
+    def handle_overwrite(self, allow, deny):
+        # Basically this is what's happening here.
+        # We have an original bit array, e.g. 1010
+        # Then we have another bit array that is 'denied', e.g. 1111
+        # And then we have the last one which is 'allowed', e.g. 0101
+        # We want original OP denied to end up resulting in
+        # whatever is in denied to be set to 0.
+        # So 1010 OP 1111 -> 0000
+        # Then we take this value and look at the allowed values.
+        # And whatever is allowed is set to 1.
+        # So 0000 OP2 0101 -> 0101
+        # The OP is base  & ~denied.
+        # The OP2 is base | allowed.
+        self.value = (self.value & ~deny) | allow
+
+    @property
+    def create_instant_invite(self):
+        """Returns True if the user can create instant invites."""
+        return self._bit(0)
+
+    @create_instant_invite.setter
+    def create_instant_invite(self, value):
+        self._set(0, value)
+
+    @property
+    def kick_members(self):
+        """Returns True if the user can kick users from the guild."""
+        return self._bit(1)
+
+    @kick_members.setter
+    def kick_members(self, value):
+        self._set(1, value)
+
+    @property
+    def ban_members(self):
+        """Returns True if a user can ban users from the guild."""
+        return self._bit(2)
+
+    @ban_members.setter
+    def ban_members(self, value):
+        self._set(2, value)
+
+    @property
+    def administrator(self):
+        """Returns True if a user is an administrator. This role overrides all other permissions.
+
+        This also bypasses all channel-specific overrides.
+        """
+        return self._bit(3)
+
+    @administrator.setter
+    def administrator(self, value):
+        self._set(3, value)
+
+    @property
+    def manage_channels(self):
+        """Returns True if a user can edit, delete, or create channels in the guild.
+
+        This also corresponds to the "Manage Channel" channel-specific override."""
+        return self._bit(4)
+
+    @manage_channels.setter
+    def manage_channels(self, value):
+        self._set(4, value)
+
+    @property
+    def manage_guild(self):
+        """Returns True if a user can edit guild properties."""
+        return self._bit(5)
+
+    @manage_guild.setter
+    def manage_guild(self, value):
+        self._set(5, value)
+
+    @property
+    def add_reactions(self):
+        """Returns True if a user can add reactions to messages."""
+        return self._bit(6)
+
+    @add_reactions.setter
+    def add_reactions(self, value):
+        self._set(6, value)
+
+    @property
+    def view_audit_log(self):
+        """Returns True if a user can view the guild's audit log."""
+        return self._bit(7)
+
+    @view_audit_log.setter
+    def view_audit_log(self, value):
+        self._set(7, value)
+
+    @property
+    def priority_speaker(self):
+        """Returns True if a user can be more easily heard while talking."""
+        return self._bit(8)
+
+    @priority_speaker.setter
+    def priority_speaker(self, value):
+        self._set(8, value)
+
+    # 1 unused
+
+    @property
+    def read_messages(self):
+        """Returns True if a user can read messages from all or specific text channels."""
+        return self._bit(10)
+
+    @read_messages.setter
+    def read_messages(self, value):
+        self._set(10, value)
+
+    @property
+    def send_messages(self):
+        """Returns True if a user can send messages from all or specific text channels."""
+        return self._bit(11)
+
+    @send_messages.setter
+    def send_messages(self, value):
+        self._set(11, value)
+
+    @property
+    def send_tts_messages(self):
+        """Returns True if a user can send TTS messages from all or specific text channels."""
+        return self._bit(12)
+
+    @send_tts_messages.setter
+    def send_tts_messages(self, value):
+        self._set(12, value)
+
+    @property
+    def manage_messages(self):
+        """Returns True if a user can delete or pin messages in a text channel. Note that there are currently no ways to edit other people's messages."""
+        return self._bit(13)
+
+    @manage_messages.setter
+    def manage_messages(self, value):
+        self._set(13, value)
+
+    @property
+    def embed_links(self):
+        """Returns True if a user's messages will automatically be embedded by Discord."""
+        return self._bit(14)
+
+    @embed_links.setter
+    def embed_links(self, value):
+        self._set(14, value)
+
+    @property
+    def attach_files(self):
+        """Returns True if a user can send files in their messages."""
+        return self._bit(15)
+
+    @attach_files.setter
+    def attach_files(self, value):
+        self._set(15, value)
+
+    @property
+    def read_message_history(self):
+        """Returns True if a user can read a text channel's previous messages."""
+        return self._bit(16)
+
+    @read_message_history.setter
+    def read_message_history(self, value):
+        self._set(16, value)
+
+    @property
+    def mention_everyone(self):
+        """Returns True if a user's @everyone or @here will mention everyone in the text channel."""
+        return self._bit(17)
+
+    @mention_everyone.setter
+    def mention_everyone(self, value):
+        self._set(17, value)
+
+    @property
+    def external_emojis(self):
+        """Returns True if a user can use emojis from other guilds."""
+        return self._bit(18)
+
+    @external_emojis.setter
+    def external_emojis(self, value):
+        self._set(18, value)
+
+    # 1 unused
+
+    @property
+    def connect(self):
+        """Returns True if a user can connect to a voice channel."""
+        return self._bit(20)
+
+    @connect.setter
+    def connect(self, value):
+        self._set(20, value)
+
+    @property
+    def speak(self):
+        """Returns True if a user can speak in a voice channel."""
+        return self._bit(21)
+
+    @speak.setter
+    def speak(self, value):
+        self._set(21, value)
+
+    @property
+    def mute_members(self):
+        """Returns True if a user can mute other users."""
+        return self._bit(22)
+
+    @mute_members.setter
+    def mute_members(self, value):
+        self._set(22, value)
+
+    @property
+    def deafen_members(self):
+        """Returns True if a user can deafen other users."""
+        return self._bit(23)
+
+    @deafen_members.setter
+    def deafen_members(self, value):
+        self._set(23, value)
+
+    @property
+    def move_members(self):
+        """Returns True if a user can move users between other voice channels."""
+        return self._bit(24)
+
+    @move_members.setter
+    def move_members(self, value):
+        self._set(24, value)
+
+    @property
+    def use_voice_activation(self):
+        """Returns True if a user can use voice activation in voice channels."""
+        return self._bit(25)
+
+    @use_voice_activation.setter
+    def use_voice_activation(self, value):
+        self._set(25, value)
+
+    @property
+    def change_nickname(self):
+        """Returns True if a user can change their nickname in the guild."""
+        return self._bit(26)
+
+    @change_nickname.setter
+    def change_nickname(self, value):
+        self._set(26, value)
+
+    @property
+    def manage_nicknames(self):
+        """Returns True if a user can change other user's nickname in the guild."""
+        return self._bit(27)
+
+    @manage_nicknames.setter
+    def manage_nicknames(self, value):
+        self._set(27, value)
+
+    @property
+    def manage_roles(self):
+        """Returns True if a user can create or edit roles less than their role's position.
+
+        This also corresponds to the "Manage Permissions" channel-specific override.
+        """
+        return self._bit(28)
+
+    @manage_roles.setter
+    def manage_roles(self, value):
+        self._set(28, value)
+
+    @property
+    def manage_webhooks(self):
+        """Returns True if a user can create, edit, or delete webhooks."""
+        return self._bit(29)
+
+    @manage_webhooks.setter
+    def manage_webhooks(self, value):
+        self._set(29, value)
+
+    @property
+    def manage_emojis(self):
+        """Returns True if a user can create, edit, or delete emojis."""
+        return self._bit(30)
+
+    @manage_emojis.setter
+    def manage_emojis(self, value):
+        self._set(30, value)
+
+    # 1 unused
+
+    # after these 32 bits, there's 21 more unused ones technically
+
+
+def augment_from_permissions(cls):
+    cls.VALID_NAMES = {
+        name for name in dir(Permissions) if isinstance(getattr(Permissions, name), property)
+    }
+
+    # make descriptors for all the valid names
+    for name in cls.VALID_NAMES:
+        # god bless Python
+        def getter(self, x=name):
+            return self._values.get(x)
+
+        def setter(self, value, x=name):
+            self._set(x, value)
+
+        prop = property(getter, setter)
+        setattr(cls, name, prop)
+
+    return cls
+
+
+@augment_from_permissions
+class PermissionOverwrite:
+    r"""A type that is used to represent a channel specific permission.
+
+    Unlike a regular :class:`Permissions`\, the default value of a
+    permission is equivalent to ``None`` and not ``False``. Setting
+    a value to ``False`` is **explicitly** denying that permission,
+    while setting a value to ``True`` is **explicitly** allowing
+    that permission.
+
+    The values supported by this are the same as :class:`Permissions`
+    with the added possibility of it being set to ``None``.
+
+    Supported operations:
+
+    +-----------+------------------------------------------+
+    | Operation |               Description                |
+    +===========+==========================================+
+    | x == y    | Checks if two overwrites are equal.      |
+    +-----------+------------------------------------------+
+    | x != y    | Checks if two overwrites are not equal.  |
+    +-----------+------------------------------------------+
+    | iter(x)   | Returns an iterator of (perm, value)     |
+    |           | pairs. This allows this class to be used |
+    |           | as an iterable in e.g. set/list/dict     |
+    |           | constructions.                           |
+    +-----------+------------------------------------------+
+
+    Parameters
+    -----------
+    \*\*kwargs
+        Set the value of permissions by their name.
+    """
+
+    __slots__ = ("_values",)
+
+    def __init__(self, **kwargs):
+        self._values = {}
+
+        for key, value in kwargs.items():
+            if key not in self.VALID_NAMES:
+                raise ValueError("no permission called {0}.".format(key))
+
+            setattr(self, key, value)
+
+    def __eq__(self, other):
+        return self._values == other._values
+
+    def _set(self, key, value):
+        if value not in (True, None, False):
+            raise TypeError(
+                "Expected bool or NoneType, received {0.__class__.__name__}".format(value)
+            )
+
+        self._values[key] = value
+
+    def pair(self):
+        """Returns the (allow, deny) pair from this overwrite.
+
+        The value of these pairs is :class:`Permissions`.
+        """
+
+        allow = Permissions.none()
+        deny = Permissions.none()
+
+        for key, value in self._values.items():
+            if value is True:
+                setattr(allow, key, True)
+            elif value is False:
+                setattr(deny, key, True)
+
+        return allow, deny
+
+    @classmethod
+    def from_pair(cls, allow, deny):
+        """Creates an overwrite from an allow/deny pair of :class:`Permissions`."""
+        ret = cls()
+        for key, value in allow:
+            if value is True:
+                setattr(ret, key, True)
+
+        for key, value in deny:
+            if value is True:
+                setattr(ret, key, False)
+
+        return ret
+
+    def is_empty(self):
+        """Checks if the permission overwrite is currently empty.
+
+        An empty permission overwrite is one that has no overwrites set
+        to True or False.
+        """
+        return all(x is None for x in self._values.values())
+
+    def update(self, **kwargs):
+        r"""Bulk updates this permission overwrite object.
+
+        Allows you to set multiple attributes by using keyword
+        arguments. The names must be equivalent to the properties
+        listed. Extraneous key/value pairs will be silently ignored.
+
+        Parameters
+        ------------
+        \*\*kwargs
+            A list of key/value pairs to bulk update with.
+        """
+        for key, value in kwargs.items():
+            if key not in self.VALID_NAMES:
+                continue
+
+            setattr(self, key, value)
+
+    def __iter__(self):
+        for key in self.VALID_NAMES:
+            yield key, self._values.get(key)

discord/player.py

@@ -0,0 +1,369 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import threading
+import subprocess
+import audioop
+import asyncio
+import logging
+import shlex
+import time
+
+from .errors import ClientException
+from .opus import Encoder as OpusEncoder
+
+log = logging.getLogger(__name__)
+
+__all__ = ["AudioSource", "PCMAudio", "FFmpegPCMAudio", "PCMVolumeTransformer"]
+
+
+class AudioSource:
+    """Represents an audio stream.
+
+    The audio stream can be Opus encoded or not, however if the audio stream
+    is not Opus encoded then the audio format must be 16-bit 48KHz stereo PCM.
+
+    .. warning::
+
+        The audio source reads are done in a separate thread.
+    """
+
+    def read(self):
+        """Reads 20ms worth of audio.
+
+        Subclasses must implement this.
+
+        If the audio is complete, then returning an empty
+        :term:`py:bytes-like object` to signal this is the way to do so.
+
+        If :meth:`is_opus` method returns ``True``, then it must return
+        20ms worth of Opus encoded audio. Otherwise, it must be 20ms
+        worth of 16-bit 48KHz stereo PCM, which is about 3,840 bytes
+        per frame (20ms worth of audio).
+
+        Returns
+        --------
+        bytes
+            A bytes like object that represents the PCM or Opus data.
+        """
+        raise NotImplementedError
+
+    def is_opus(self):
+        """Checks if the audio source is already encoded in Opus.
+
+        Defaults to ``False``.
+        """
+        return False
+
+    def cleanup(self):
+        """Called when clean-up is needed to be done.
+
+        Useful for clearing buffer data or processes after
+        it is done playing audio.
+        """
+        pass
+
+    def __del__(self):
+        self.cleanup()
+
+
+class PCMAudio(AudioSource):
+    """Represents raw 16-bit 48KHz stereo PCM audio source.
+
+    Attributes
+    -----------
+    stream: file-like object
+        A file-like object that reads byte data representing raw PCM.
+    """
+
+    def __init__(self, stream):
+        self.stream = stream
+
+    def read(self):
+        ret = self.stream.read(OpusEncoder.FRAME_SIZE)
+        if len(ret) != OpusEncoder.FRAME_SIZE:
+            return b""
+        return ret
+
+
+class FFmpegPCMAudio(AudioSource):
+    """An audio source from FFmpeg (or AVConv).
+
+    This launches a sub-process to a specific input file given.
+
+    .. warning::
+
+        You must have the ffmpeg or avconv executable in your path environment
+        variable in order for this to work.
+
+    Parameters
+    ------------
+    source: Union[str, BinaryIO]
+        The input that ffmpeg will take and convert to PCM bytes.
+        If ``pipe`` is True then this is a file-like object that is
+        passed to the stdin of ffmpeg.
+    executable: str
+        The executable name (and path) to use. Defaults to ``ffmpeg``.
+    pipe: bool
+        If true, denotes that ``source`` parameter will be passed
+        to the stdin of ffmpeg. Defaults to ``False``.
+    stderr: Optional[BinaryIO]
+        A file-like object to pass to the Popen constructor.
+        Could also be an instance of ``subprocess.PIPE``.
+    options: Optional[str]
+        Extra command line arguments to pass to ffmpeg after the ``-i`` flag.
+    before_options: Optional[str]
+        Extra command line arguments to pass to ffmpeg before the ``-i`` flag.
+
+    Raises
+    --------
+    ClientException
+        The subprocess failed to be created.
+    """
+
+    def __init__(
+        self,
+        source,
+        *,
+        executable="ffmpeg",
+        pipe=False,
+        stderr=None,
+        before_options=None,
+        options=None
+    ):
+        stdin = None if not pipe else source
+
+        args = [executable]
+
+        if isinstance(before_options, str):
+            args.extend(shlex.split(before_options))
+
+        args.append("-i")
+        args.append("-" if pipe else source)
+        args.extend(("-f", "s16le", "-ar", "48000", "-ac", "2", "-loglevel", "warning"))
+
+        if isinstance(options, str):
+            args.extend(shlex.split(options))
+
+        args.append("pipe:1")
+
+        self._process = None
+        try:
+            self._process = subprocess.Popen(
+                args, stdin=stdin, stdout=subprocess.PIPE, stderr=stderr
+            )
+            self._stdout = self._process.stdout
+        except FileNotFoundError:
+            raise ClientException(executable + " was not found.") from None
+        except subprocess.SubprocessError as exc:
+            raise ClientException("Popen failed: {0.__class__.__name__}: {0}".format(exc)) from exc
+
+    def read(self):
+        ret = self._stdout.read(OpusEncoder.FRAME_SIZE)
+        if len(ret) != OpusEncoder.FRAME_SIZE:
+            return b""
+        return ret
+
+    def cleanup(self):
+        proc = self._process
+        if proc is None:
+            return
+
+        log.info("Preparing to terminate ffmpeg process %s.", proc.pid)
+        proc.kill()
+        if proc.poll() is None:
+            log.info("ffmpeg process %s has not terminated. Waiting to terminate...", proc.pid)
+            proc.communicate()
+            log.info(
+                "ffmpeg process %s should have terminated with a return code of %s.",
+                proc.pid,
+                proc.returncode,
+            )
+        else:
+            log.info(
+                "ffmpeg process %s successfully terminated with return code of %s.",
+                proc.pid,
+                proc.returncode,
+            )
+
+        self._process = None
+
+
+class PCMVolumeTransformer(AudioSource):
+    """Transforms a previous :class:`AudioSource` to have volume controls.
+
+    This does not work on audio sources that have :meth:`AudioSource.is_opus`
+    set to ``True``.
+
+    Parameters
+    ------------
+    original: :class:`AudioSource`
+        The original AudioSource to transform.
+    volume: float
+        The initial volume to set it to.
+        See :attr:`volume` for more info.
+
+    Raises
+    -------
+    TypeError
+        Not an audio source.
+    ClientException
+        The audio source is opus encoded.
+    """
+
+    def __init__(self, original, volume=1.0):
+        if not isinstance(original, AudioSource):
+            raise TypeError("expected AudioSource not {0.__class__.__name__}.".format(original))
+
+        if original.is_opus():
+            raise ClientException("AudioSource must not be Opus encoded.")
+
+        self.original = original
+        self.volume = volume
+
+    @property
+    def volume(self):
+        """Retrieves or sets the volume as a floating point percentage (e.g. 1.0 for 100%)."""
+        return self._volume
+
+    @volume.setter
+    def volume(self, value):
+        self._volume = max(value, 0.0)
+
+    def cleanup(self):
+        self.original.cleanup()
+
+    def read(self):
+        ret = self.original.read()
+        return audioop.mul(ret, 2, min(self._volume, 2.0))
+
+
+class AudioPlayer(threading.Thread):
+    DELAY = OpusEncoder.FRAME_LENGTH / 1000.0
+
+    def __init__(self, source, client, *, after=None):
+        threading.Thread.__init__(self)
+        self.daemon = True
+        self.source = source
+        self.client = client
+        self.after = after
+
+        self._end = threading.Event()
+        self._resumed = threading.Event()
+        self._resumed.set()  # we are not paused
+        self._current_error = None
+        self._connected = client._connected
+        self._lock = threading.Lock()
+
+        if after is not None and not callable(after):
+            raise TypeError('Expected a callable for the "after" parameter.')
+
+    def _do_run(self):
+        self.loops = 0
+        self._start = time.time()
+
+        # getattr lookup speed ups
+        play_audio = self.client.send_audio_packet
+        self._speak(True)
+
+        while not self._end.is_set():
+            # are we paused?
+            if not self._resumed.is_set():
+                # wait until we aren't
+                self._resumed.wait()
+                continue
+
+            # are we disconnected from voice?
+            if not self._connected.is_set():
+                # wait until we are connected
+                self._connected.wait()
+                # reset our internal data
+                self.loops = 0
+                self._start = time.time()
+
+            self.loops += 1
+            data = self.source.read()
+
+            if not data:
+                self.stop()
+                break
+
+            play_audio(data, encode=not self.source.is_opus())
+            next_time = self._start + self.DELAY * self.loops
+            delay = max(0, self.DELAY + (next_time - time.time()))
+            time.sleep(delay)
+
+    def run(self):
+        try:
+            self._do_run()
+        except Exception as exc:
+            self._current_error = exc
+            self.stop()
+        finally:
+            self.source.cleanup()
+            self._call_after()
+
+    def _call_after(self):
+        if self.after is not None:
+            try:
+                self.after(self._current_error)
+            except Exception:
+                log.exception("Calling the after function failed.")
+
+    def stop(self):
+        self._end.set()
+        self._resumed.set()
+        self._speak(False)
+
+    def pause(self, *, update_speaking=True):
+        self._resumed.clear()
+        if update_speaking:
+            self._speak(False)
+
+    def resume(self, *, update_speaking=True):
+        self.loops = 0
+        self._start = time.time()
+        self._resumed.set()
+        if update_speaking:
+            self._speak(True)
+
+    def is_playing(self):
+        return self._resumed.is_set() and not self._end.is_set()
+
+    def is_paused(self):
+        return not self._end.is_set() and not self._resumed.is_set()
+
+    def _set_source(self, source):
+        with self._lock:
+            self.pause(update_speaking=False)
+            self.source = source
+            self.resume(update_speaking=False)
+
+    def _speak(self, speaking):
+        try:
+            asyncio.run_coroutine_threadsafe(self.client.ws.speak(speaking), self.client.loop)
+        except Exception as e:
+            log.info("Speaking call in player failed: %s", e)

discord/raw_models.py

@@ -0,0 +1,151 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+
+class RawMessageDeleteEvent:
+    """Represents the event payload for a :func:`on_raw_message_delete` event.
+
+    Attributes
+    ------------
+    channel_id: :class:`int`
+        The channel ID where the deletion took place.
+    guild_id: Optional[:class:`int`]
+        The guild ID where the deletion took place, if applicable.
+    message_id: :class:`int`
+        The message ID that got deleted.
+    """
+
+    __slots__ = ("message_id", "channel_id", "guild_id")
+
+    def __init__(self, data):
+        self.message_id = int(data["id"])
+        self.channel_id = int(data["channel_id"])
+
+        try:
+            self.guild_id = int(data["guild_id"])
+        except KeyError:
+            self.guild_id = None
+
+
+class RawBulkMessageDeleteEvent:
+    """Represents the event payload for a :func:`on_raw_bulk_message_delete` event.
+
+    Attributes
+    -----------
+    message_ids: Set[:class:`int`]
+        A :class:`set` of the message IDs that were deleted.
+    channel_id: :class:`int`
+        The channel ID where the message got deleted.
+    guild_id: Optional[:class:`int`]
+        The guild ID where the message got deleted, if applicable.
+    """
+
+    __slots__ = ("message_ids", "channel_id", "guild_id")
+
+    def __init__(self, data):
+        self.message_ids = {int(x) for x in data.get("ids", [])}
+        self.channel_id = int(data["channel_id"])
+
+        try:
+            self.guild_id = int(data["guild_id"])
+        except KeyError:
+            self.guild_id = None
+
+
+class RawMessageUpdateEvent:
+    """Represents the payload for a :func:`on_raw_message_edit` event.
+
+    Attributes
+    -----------
+    message_id: :class:`int`
+        The message ID that got updated.
+    data: :class:`dict`
+        The raw data given by the
+        `gateway <https://discordapp.com/developers/docs/topics/gateway#message-update>`_
+    """
+
+    __slots__ = ("message_id", "data")
+
+    def __init__(self, data):
+        self.message_id = int(data["id"])
+        self.data = data
+
+
+class RawReactionActionEvent:
+    """Represents the payload for a :func:`on_raw_reaction_add` or
+    :func:`on_raw_reaction_remove` event.
+
+    Attributes
+    -----------
+    message_id: :class:`int`
+        The message ID that got or lost a reaction.
+    user_id: :class:`int`
+        The user ID who added the reaction or whose reaction was removed.
+    channel_id: :class:`int`
+        The channel ID where the reaction got added or removed.
+    guild_id: Optional[:class:`int`]
+        The guild ID where the reaction got added or removed, if applicable.
+    emoji: :class:`PartialEmoji`
+        The custom or unicode emoji being used.
+    """
+
+    __slots__ = ("message_id", "user_id", "channel_id", "guild_id", "emoji")
+
+    def __init__(self, data, emoji):
+        self.message_id = int(data["message_id"])
+        self.channel_id = int(data["channel_id"])
+        self.user_id = int(data["user_id"])
+        self.emoji = emoji
+
+        try:
+            self.guild_id = int(data["guild_id"])
+        except KeyError:
+            self.guild_id = None
+
+
+class RawReactionClearEvent:
+    """Represents the payload for a :func:`on_raw_reaction_clear` event.
+
+    Attributes
+    -----------
+    message_id: :class:`int`
+        The message ID that got its reactions cleared.
+    channel_id: :class:`int`
+        The channel ID where the reactions got cleared.
+    guild_id: Optional[:class:`int`]
+        The guild ID where the reactions got cleared.
+    """
+
+    __slots__ = ("message_id", "channel_id", "guild_id")
+
+    def __init__(self, data):
+        self.message_id = int(data["message_id"])
+        self.channel_id = int(data["channel_id"])
+
+        try:
+            self.guild_id = int(data["guild_id"])
+        except KeyError:
+            self.guild_id = None

discord/reaction.py

@@ -0,0 +1,151 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from .iterators import ReactionIterator
+
+
+class Reaction:
+    """Represents a reaction to a message.
+
+    Depending on the way this object was created, some of the attributes can
+    have a value of ``None``.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two reactions are equal. This works by checking if the emoji
+            is the same. So two messages with the same reaction will be considered
+            "equal".
+
+        .. describe:: x != y
+
+            Checks if two reactions are not equal.
+
+        .. describe:: hash(x)
+
+            Returns the reaction's hash.
+
+        .. describe:: str(x)
+
+            Returns the string form of the reaction's emoji.
+
+    Attributes
+    -----------
+    emoji: :class:`Emoji` or :class:`str`
+        The reaction emoji. May be a custom emoji, or a unicode emoji.
+    count: :class:`int`
+        Number of times this reaction was made
+    me: :class:`bool`
+        If the user sent this reaction.
+    message: :class:`Message`
+        Message this reaction is for.
+    """
+
+    __slots__ = ("message", "count", "emoji", "me")
+
+    def __init__(self, *, message, data, emoji=None):
+        self.message = message
+        self.emoji = emoji or message._state.get_reaction_emoji(data["emoji"])
+        self.count = data.get("count", 1)
+        self.me = data.get("me")
+
+    @property
+    def custom_emoji(self):
+        """:class:`bool`: If this is a custom emoji."""
+        return not isinstance(self.emoji, str)
+
+    def __eq__(self, other):
+        return isinstance(other, self.__class__) and other.emoji == self.emoji
+
+    def __ne__(self, other):
+        if isinstance(other, self.__class__):
+            return other.emoji != self.emoji
+        return True
+
+    def __hash__(self):
+        return hash(self.emoji)
+
+    def __str__(self):
+        return str(self.emoji)
+
+    def __repr__(self):
+        return "<Reaction emoji={0.emoji!r} me={0.me} count={0.count}>".format(self)
+
+    def users(self, limit=None, after=None):
+        """Returns an :class:`AsyncIterator` representing the users that have reacted to the message.
+
+        The ``after`` parameter must represent a member
+        and meet the :class:`abc.Snowflake` abc.
+
+        Parameters
+        ------------
+        limit: int
+            The maximum number of results to return.
+            If not provided, returns all the users who
+            reacted to the message.
+        after: :class:`abc.Snowflake`
+            For pagination, reactions are sorted by member.
+
+        Raises
+        --------
+        HTTPException
+            Getting the users for the reaction failed.
+
+        Examples
+        ---------
+
+        Usage ::
+
+            # I do not actually recommend doing this.
+            async for user in reaction.users():
+                await channel.send('{0} has reacted with {1.emoji}!'.format(user, reaction))
+
+        Flattening into a list: ::
+
+            users = await reaction.users().flatten()
+            # users is now a list...
+            winner = random.choice(users)
+            await channel.send('{} has won the raffle.'.format(winner))
+
+        Yields
+        --------
+        Union[:class:`User`, :class:`Member`]
+            The member (if retrievable) or the user that has reacted
+            to this message. The case where it can be a :class:`Member` is
+            in a guild message context. Sometimes it can be a :class:`User`
+            if the member has left the guild.
+        """
+
+        if self.custom_emoji:
+            emoji = "{0.name}:{0.id}".format(self.emoji)
+        else:
+            emoji = self.emoji
+
+        if limit is None:
+            limit = self.count
+
+        return ReactionIterator(self.message, emoji, limit, after)

discord/relationship.py

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from .enums import RelationshipType, try_enum
+
+
+class Relationship:
+    """Represents a relationship in Discord.
+
+    A relationship is like a friendship, a person who is blocked, etc.
+    Only non-bot accounts can have relationships.
+
+    Attributes
+    -----------
+    user: :class:`User`
+        The user you have the relationship with.
+    type: :class:`RelationshipType`
+        The type of relationship you have.
+    """
+
+    __slots__ = ("type", "user", "_state")
+
+    def __init__(self, *, state, data):
+        self._state = state
+        self.type = try_enum(RelationshipType, data["type"])
+        self.user = state.store_user(data["user"])
+
+    def __repr__(self):
+        return "<Relationship user={0.user!r} type={0.type!r}>".format(self)
+
+    async def delete(self):
+        """|coro|
+
+        Deletes the relationship.
+
+        Raises
+        ------
+        HTTPException
+            Deleting the relationship failed.
+        """
+
+        await self._state.http.remove_relationship(self.user.id)
+
+    async def accept(self):
+        """|coro|
+
+        Accepts the relationship request. e.g. accepting a
+        friend request.
+
+        Raises
+        -------
+        HTTPException
+            Accepting the relationship failed.
+        """
+
+        await self._state.http.add_relationship(self.user.id)

discord/role.py

@@ -0,0 +1,297 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from .permissions import Permissions
+from .errors import InvalidArgument
+from .colour import Colour
+from .mixins import Hashable
+from .utils import snowflake_time
+
+
+class Role(Hashable):
+    """Represents a Discord role in a :class:`Guild`.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two roles are equal.
+
+        .. describe:: x != y
+
+            Checks if two roles are not equal.
+
+        .. describe:: x > y
+
+            Checks if a role is higher than another in the hierarchy.
+
+        .. describe:: x < y
+
+            Checks if a role is lower than another in the hierarchy.
+
+        .. describe:: x >= y
+
+            Checks if a role is higher or equal to another in the hierarchy.
+
+        .. describe:: x <= y
+
+            Checks if a role is lower or equal to another in the hierarchy.
+
+        .. describe:: hash(x)
+
+            Return the role's hash.
+
+        .. describe:: str(x)
+
+            Returns the role's name.
+
+    Attributes
+    ----------
+    id: :class:`int`
+        The ID for the role.
+    name: :class:`str`
+        The name of the role.
+    permissions: :class:`Permissions`
+        Represents the role's permissions.
+    guild: :class:`Guild`
+        The guild the role belongs to.
+    colour: :class:`Colour`
+        Represents the role colour. An alias exists under ``color``.
+    hoist: :class:`bool`
+         Indicates if the role will be displayed separately from other members.
+    position: :class:`int`
+        The position of the role. This number is usually positive. The bottom
+        role has a position of 0.
+    managed: :class:`bool`
+        Indicates if the role is managed by the guild through some form of
+        integrations such as Twitch.
+    mentionable: :class:`bool`
+        Indicates if the role can be mentioned by users.
+    """
+
+    __slots__ = (
+        "id",
+        "name",
+        "permissions",
+        "color",
+        "colour",
+        "position",
+        "managed",
+        "mentionable",
+        "hoist",
+        "guild",
+        "_state",
+    )
+
+    def __init__(self, *, guild, state, data):
+        self.guild = guild
+        self._state = state
+        self.id = int(data["id"])
+        self._update(data)
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return "<Role id={0.id} name={0.name!r}>".format(self)
+
+    def __lt__(self, other):
+        if not isinstance(other, Role) or not isinstance(self, Role):
+            return NotImplemented
+
+        if self.guild != other.guild:
+            raise RuntimeError("cannot compare roles from two different guilds.")
+
+        # the @everyone role is always the lowest role in hierarchy
+        guild_id = self.guild.id
+        if self.id == guild_id:
+            # everyone_role < everyone_role -> False
+            return other.id != guild_id
+
+        if self.position < other.position:
+            return True
+
+        if self.position == other.position:
+            return int(self.id) > int(other.id)
+
+        return False
+
+    def __le__(self, other):
+        r = Role.__lt__(other, self)
+        if r is NotImplemented:
+            return NotImplemented
+        return not r
+
+    def __gt__(self, other):
+        return Role.__lt__(other, self)
+
+    def __ge__(self, other):
+        r = Role.__lt__(self, other)
+        if r is NotImplemented:
+            return NotImplemented
+        return not r
+
+    def _update(self, data):
+        self.name = data["name"]
+        self.permissions = Permissions(data.get("permissions", 0))
+        self.position = data.get("position", 0)
+        self.colour = Colour(data.get("color", 0))
+        self.hoist = data.get("hoist", False)
+        self.managed = data.get("managed", False)
+        self.mentionable = data.get("mentionable", False)
+        self.color = self.colour
+
+    def is_default(self):
+        """Checks if the role is the default role."""
+        return self.guild.id == self.id
+
+    @property
+    def created_at(self):
+        """Returns the role's creation time in UTC."""
+        return snowflake_time(self.id)
+
+    @property
+    def mention(self):
+        """Returns a string that allows you to mention a role."""
+        return "<@&%s>" % self.id
+
+    @property
+    def members(self):
+        """Returns a :class:`list` of :class:`Member` with this role."""
+        all_members = self.guild.members
+        if self.is_default():
+            return all_members
+
+        role_id = self.id
+        return [member for member in all_members if member._roles.has(role_id)]
+
+    async def _move(self, position, reason):
+        if position <= 0:
+            raise InvalidArgument("Cannot move role to position 0 or below")
+
+        if self.is_default():
+            raise InvalidArgument("Cannot move default role")
+
+        if self.position == position:
+            return  # Save discord the extra request.
+
+        http = self._state.http
+
+        change_range = range(min(self.position, position), max(self.position, position) + 1)
+        roles = [
+            r.id for r in self.guild.roles[1:] if r.position in change_range and r.id != self.id
+        ]
+
+        if self.position > position:
+            roles.insert(0, self.id)
+        else:
+            roles.append(self.id)
+
+        payload = [{"id": z[0], "position": z[1]} for z in zip(roles, change_range)]
+        await http.move_role_position(self.guild.id, payload, reason=reason)
+
+    async def edit(self, *, reason=None, **fields):
+        """|coro|
+
+        Edits the role.
+
+        You must have the :attr:`~Permissions.manage_roles` permission to
+        use this.
+
+        All fields are optional.
+
+        Parameters
+        -----------
+        name: str
+            The new role name to change to.
+        permissions: :class:`Permissions`
+            The new permissions to change to.
+        colour: :class:`Colour`
+            The new colour to change to. (aliased to color as well)
+        hoist: bool
+            Indicates if the role should be shown separately in the member list.
+        mentionable: bool
+            Indicates if the role should be mentionable by others.
+        position: int
+            The new role's position. This must be below your top role's
+            position or it will fail.
+        reason: Optional[str]
+            The reason for editing this role. Shows up on the audit log.
+
+        Raises
+        -------
+        Forbidden
+            You do not have permissions to change the role.
+        HTTPException
+            Editing the role failed.
+        InvalidArgument
+            An invalid position was given or the default
+            role was asked to be moved.
+        """
+
+        position = fields.get("position")
+        if position is not None:
+            await self._move(position, reason=reason)
+            self.position = position
+
+        try:
+            colour = fields["colour"]
+        except KeyError:
+            colour = fields.get("color", self.colour)
+
+        payload = {
+            "name": fields.get("name", self.name),
+            "permissions": fields.get("permissions", self.permissions).value,
+            "color": colour.value,
+            "hoist": fields.get("hoist", self.hoist),
+            "mentionable": fields.get("mentionable", self.mentionable),
+        }
+
+        data = await self._state.http.edit_role(self.guild.id, self.id, reason=reason, **payload)
+        self._update(data)
+
+    async def delete(self, *, reason=None):
+        """|coro|
+
+        Deletes the role.
+
+        You must have the :attr:`~Permissions.manage_roles` permission to
+        use this.
+
+        Parameters
+        -----------
+        reason: Optional[str]
+            The reason for deleting this role. Shows up on the audit log.
+
+        Raises
+        --------
+        Forbidden
+            You do not have permissions to delete the role.
+        HTTPException
+            Deleting the role failed.
+        """
+
+        await self._state.http.delete_role(self.guild.id, self.id, reason=reason)

discord/shard.py

@@ -0,0 +1,370 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import asyncio
+import itertools
+import logging
+
+import websockets
+
+from .state import AutoShardedConnectionState
+from .client import Client
+from .gateway import *
+from .errors import ClientException, InvalidArgument
+from . import utils
+from .enums import Status
+
+log = logging.getLogger(__name__)
+
+
+class Shard:
+    def __init__(self, ws, client):
+        self.ws = ws
+        self._client = client
+        self.loop = self._client.loop
+        self._current = self.loop.create_future()
+        self._current.set_result(None)  # we just need an already done future
+        self._pending = asyncio.Event(loop=self.loop)
+        self._pending_task = None
+
+    @property
+    def id(self):
+        return self.ws.shard_id
+
+    def is_pending(self):
+        return not self._pending.is_set()
+
+    def complete_pending_reads(self):
+        self._pending.set()
+
+    async def _pending_reads(self):
+        try:
+            while self.is_pending():
+                await self.poll()
+        except asyncio.CancelledError:
+            pass
+
+    def launch_pending_reads(self):
+        self._pending_task = asyncio.ensure_future(self._pending_reads(), loop=self.loop)
+
+    def wait(self):
+        return self._pending_task
+
+    async def poll(self):
+        try:
+            await self.ws.poll_event()
+        except ResumeWebSocket:
+            log.info("Got a request to RESUME the websocket at Shard ID %s.", self.id)
+            coro = DiscordWebSocket.from_client(
+                self._client,
+                resume=True,
+                shard_id=self.id,
+                session=self.ws.session_id,
+                sequence=self.ws.sequence,
+            )
+            self.ws = await asyncio.wait_for(coro, timeout=180.0, loop=self.loop)
+
+    def get_future(self):
+        if self._current.done():
+            self._current = asyncio.ensure_future(self.poll(), loop=self.loop)
+
+        return self._current
+
+
+class AutoShardedClient(Client):
+    """A client similar to :class:`Client` except it handles the complications
+    of sharding for the user into a more manageable and transparent single
+    process bot.
+
+    When using this client, you will be able to use it as-if it was a regular
+    :class:`Client` with a single shard when implementation wise internally it
+    is split up into multiple shards. This allows you to not have to deal with
+    IPC or other complicated infrastructure.
+
+    It is recommended to use this client only if you have surpassed at least
+    1000 guilds.
+
+    If no :attr:`shard_count` is provided, then the library will use the
+    Bot Gateway endpoint call to figure out how many shards to use.
+
+    If a ``shard_ids`` parameter is given, then those shard IDs will be used
+    to launch the internal shards. Note that :attr:`shard_count` must be provided
+    if this is used. By default, when omitted, the client will launch shards from
+    0 to ``shard_count - 1``.
+
+    Attributes
+    ------------
+    shard_ids: Optional[List[:class:`int`]]
+        An optional list of shard_ids to launch the shards with.
+    """
+
+    def __init__(self, *args, loop=None, **kwargs):
+        kwargs.pop("shard_id", None)
+        self.shard_ids = kwargs.pop("shard_ids", None)
+        super().__init__(*args, loop=loop, **kwargs)
+
+        if self.shard_ids is not None:
+            if self.shard_count is None:
+                raise ClientException(
+                    "When passing manual shard_ids, you must provide a shard_count."
+                )
+            elif not isinstance(self.shard_ids, (list, tuple)):
+                raise ClientException("shard_ids parameter must be a list or a tuple.")
+
+        self._connection = AutoShardedConnectionState(
+            dispatch=self.dispatch,
+            chunker=self._chunker,
+            handlers=self._handlers,
+            syncer=self._syncer,
+            http=self.http,
+            loop=self.loop,
+            **kwargs
+        )
+
+        # instead of a single websocket, we have multiple
+        # the key is the shard_id
+        self.shards = {}
+
+        def _get_websocket(guild_id):
+            i = (guild_id >> 22) % self.shard_count
+            return self.shards[i].ws
+
+        self._connection._get_websocket = _get_websocket
+
+    async def _chunker(self, guild, *, shard_id=None):
+        try:
+            guild_id = guild.id
+            shard_id = shard_id or guild.shard_id
+        except AttributeError:
+            guild_id = [s.id for s in guild]
+
+        payload = {"op": 8, "d": {"guild_id": guild_id, "query": "", "limit": 0}}
+
+        ws = self.shards[shard_id].ws
+        await ws.send_as_json(payload)
+
+    @property
+    def latency(self):
+        """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
+
+        This operates similarly to :meth:`.Client.latency` except it uses the average
+        latency of every shard's latency. To get a list of shard latency, check the
+        :attr:`latencies` property. Returns ``nan`` if there are no shards ready.
+        """
+        if not self.shards:
+            return float("nan")
+        return sum(latency for _, latency in self.latencies) / len(self.shards)
+
+    @property
+    def latencies(self):
+        """List[Tuple[:class:`int`, :class:`float`]]: A list of latencies between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
+
+        This returns a list of tuples with elements ``(shard_id, latency)``.
+        """
+        return [(shard_id, shard.ws.latency) for shard_id, shard in self.shards.items()]
+
+    async def request_offline_members(self, *guilds):
+        r"""|coro|
+
+        Requests previously offline members from the guild to be filled up
+        into the :attr:`Guild.members` cache. This function is usually not
+        called. It should only be used if you have the ``fetch_offline_members``
+        parameter set to ``False``.
+
+        When the client logs on and connects to the websocket, Discord does
+        not provide the library with offline members if the number of members
+        in the guild is larger than 250. You can check if a guild is large
+        if :attr:`Guild.large` is ``True``.
+
+        Parameters
+        -----------
+        \*guilds
+            An argument list of guilds to request offline members for.
+
+        Raises
+        -------
+        InvalidArgument
+            If any guild is unavailable or not large in the collection.
+        """
+        if any(not g.large or g.unavailable for g in guilds):
+            raise InvalidArgument("An unavailable or non-large guild was passed.")
+
+        _guilds = sorted(guilds, key=lambda g: g.shard_id)
+        for shard_id, sub_guilds in itertools.groupby(_guilds, key=lambda g: g.shard_id):
+            sub_guilds = list(sub_guilds)
+            await self._connection.request_offline_members(sub_guilds, shard_id=shard_id)
+
+    async def launch_shard(self, gateway, shard_id):
+        try:
+            coro = websockets.connect(
+                gateway, loop=self.loop, klass=DiscordWebSocket, compression=None
+            )
+            ws = await asyncio.wait_for(coro, loop=self.loop, timeout=180.0)
+        except Exception:
+            log.info("Failed to connect for shard_id: %s. Retrying...", shard_id)
+            await asyncio.sleep(5.0, loop=self.loop)
+            return await self.launch_shard(gateway, shard_id)
+
+        ws.token = self.http.token
+        ws._connection = self._connection
+        ws._dispatch = self.dispatch
+        ws.gateway = gateway
+        ws.shard_id = shard_id
+        ws.shard_count = self.shard_count
+        ws._max_heartbeat_timeout = self._connection.heartbeat_timeout
+
+        try:
+            # OP HELLO
+            await asyncio.wait_for(ws.poll_event(), loop=self.loop, timeout=180.0)
+            await asyncio.wait_for(ws.identify(), loop=self.loop, timeout=180.0)
+        except asyncio.TimeoutError:
+            log.info("Timed out when connecting for shard_id: %s. Retrying...", shard_id)
+            await asyncio.sleep(5.0, loop=self.loop)
+            return await self.launch_shard(gateway, shard_id)
+
+        # keep reading the shard while others connect
+        self.shards[shard_id] = ret = Shard(ws, self)
+        ret.launch_pending_reads()
+        await asyncio.sleep(5.0, loop=self.loop)
+
+    async def launch_shards(self):
+        if self.shard_count is None:
+            self.shard_count, gateway = await self.http.get_bot_gateway()
+        else:
+            gateway = await self.http.get_gateway()
+
+        self._connection.shard_count = self.shard_count
+
+        shard_ids = self.shard_ids if self.shard_ids else range(self.shard_count)
+
+        for shard_id in shard_ids:
+            await self.launch_shard(gateway, shard_id)
+
+        shards_to_wait_for = []
+        for shard in self.shards.values():
+            shard.complete_pending_reads()
+            shards_to_wait_for.append(shard.wait())
+
+        # wait for all pending tasks to finish
+        await utils.sane_wait_for(shards_to_wait_for, timeout=300.0, loop=self.loop)
+
+    async def _connect(self):
+        await self.launch_shards()
+
+        while True:
+            pollers = [shard.get_future() for shard in self.shards.values()]
+            done, _ = await asyncio.wait(
+                pollers, loop=self.loop, return_when=asyncio.FIRST_COMPLETED
+            )
+            for f in done:
+                # we wanna re-raise to the main Client.connect handler if applicable
+                f.result()
+
+    async def close(self):
+        """|coro|
+
+        Closes the connection to discord.
+        """
+        if self.is_closed():
+            return
+
+        self._closed.set()
+
+        for vc in self.voice_clients:
+            try:
+                await vc.disconnect()
+            except Exception:
+                pass
+
+        to_close = [shard.ws.close() for shard in self.shards.values()]
+        if to_close:
+            await asyncio.wait(to_close, loop=self.loop)
+
+        await self.http.close()
+
+    async def change_presence(self, *, activity=None, status=None, afk=False, shard_id=None):
+        """|coro|
+
+        Changes the client's presence.
+
+        The activity parameter is a :class:`Activity` object (not a string) that represents
+        the activity being done currently. This could also be the slimmed down versions,
+        :class:`Game` and :class:`Streaming`.
+
+        Example: ::
+
+            game = discord.Game("with the API")
+            await client.change_presence(status=discord.Status.idle, activity=game)
+
+        Parameters
+        ----------
+        activity: Optional[Union[:class:`Game`, :class:`Streaming`, :class:`Activity`]]
+            The activity being done. ``None`` if no currently active activity is done.
+        status: Optional[:class:`Status`]
+            Indicates what status to change to. If None, then
+            :attr:`Status.online` is used.
+        afk: bool
+            Indicates if you are going AFK. This allows the discord
+            client to know how to handle push notifications better
+            for you in case you are actually idle and not lying.
+        shard_id: Optional[int]
+            The shard_id to change the presence to. If not specified
+            or ``None``, then it will change the presence of every
+            shard the bot can see.
+
+        Raises
+        ------
+        InvalidArgument
+            If the ``activity`` parameter is not of proper type.
+        """
+
+        if status is None:
+            status = "online"
+            status_enum = Status.online
+        elif status is Status.offline:
+            status = "invisible"
+            status_enum = Status.offline
+        else:
+            status_enum = status
+            status = str(status)
+
+        if shard_id is None:
+            for shard in self.shards.values():
+                await shard.ws.change_presence(activity=activity, status=status, afk=afk)
+
+            guilds = self._connection.guilds
+        else:
+            shard = self.shards[shard_id]
+            await shard.ws.change_presence(activity=activity, status=status, afk=afk)
+            guilds = [g for g in self._connection.guilds if g.shard_id == shard_id]
+
+        for guild in guilds:
+            me = guild.me
+            if me is None:
+                continue
+
+            me.activities = (activity,)
+            me.status = status_enum

discord/user.py

@@ -0,0 +1,699 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2017 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+from collections import namedtuple
+
+import discord.abc
+from .utils import snowflake_time, _bytes_to_base64_data, parse_time, valid_icon_size
+from .enums import DefaultAvatar, RelationshipType, UserFlags, HypeSquadHouse
+from .errors import ClientException, InvalidArgument
+from .colour import Colour
+
+VALID_STATIC_FORMATS = {"jpeg", "jpg", "webp", "png"}
+VALID_AVATAR_FORMATS = VALID_STATIC_FORMATS | {"gif"}
+
+
+class Profile(namedtuple("Profile", "flags user mutual_guilds connected_accounts premium_since")):
+    __slots__ = ()
+
+    @property
+    def nitro(self):
+        return self.premium_since is not None
+
+    premium = nitro
+
+    def _has_flag(self, o):
+        v = o.value
+        return (self.flags & v) == v
+
+    @property
+    def staff(self):
+        return self._has_flag(UserFlags.staff)
+
+    @property
+    def partner(self):
+        return self._has_flag(UserFlags.partner)
+
+    @property
+    def bug_hunter(self):
+        return self._has_flag(UserFlags.bug_hunter)
+
+    @property
+    def early_supporter(self):
+        return self._has_flag(UserFlags.early_supporter)
+
+    @property
+    def hypesquad(self):
+        return self._has_flag(UserFlags.hypesquad)
+
+    @property
+    def hypesquad_houses(self):
+        flags = (
+            UserFlags.hypesquad_bravery,
+            UserFlags.hypesquad_brilliance,
+            UserFlags.hypesquad_balance,
+        )
+        return [house for house, flag in zip(HypeSquadHouse, flags) if self._has_flag(flag)]
+
+
+_BaseUser = discord.abc.User
+
+
+class BaseUser(_BaseUser):
+    __slots__ = ("name", "id", "discriminator", "avatar", "bot", "_state")
+
+    def __init__(self, *, state, data):
+        self._state = state
+        self.name = data["username"]
+        self.id = int(data["id"])
+        self.discriminator = data["discriminator"]
+        self.avatar = data["avatar"]
+        self.bot = data.get("bot", False)
+
+    def __str__(self):
+        return "{0.name}#{0.discriminator}".format(self)
+
+    def __eq__(self, other):
+        return isinstance(other, _BaseUser) and other.id == self.id
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def __hash__(self):
+        return self.id >> 22
+
+    @classmethod
+    def _copy(cls, user):
+        self = cls.__new__(cls)  # bypass __init__
+
+        self.name = user.name
+        self.id = user.id
+        self.discriminator = user.discriminator
+        self.avatar = user.avatar
+        self.bot = user.bot
+        self._state = user._state
+
+        return self
+
+    @property
+    def avatar_url(self):
+        """Returns a friendly URL version of the avatar the user has.
+
+        If the user does not have a traditional avatar, their default
+        avatar URL is returned instead.
+
+        This is equivalent to calling :meth:`avatar_url_as` with
+        the default parameters (i.e. webp/gif detection and a size of 1024).
+        """
+        return self.avatar_url_as(format=None, size=1024)
+
+    def is_avatar_animated(self):
+        """:class:`bool`: Returns True if the user has an animated avatar."""
+        return bool(self.avatar and self.avatar.startswith("a_"))
+
+    def avatar_url_as(self, *, format=None, static_format="webp", size=1024):
+        """Returns a friendly URL version of the avatar the user has.
+
+        If the user does not have a traditional avatar, their default
+        avatar URL is returned instead.
+
+        The format must be one of 'webp', 'jpeg', 'jpg', 'png' or 'gif', and
+        'gif' is only valid for animated avatars. The size must be a power of 2
+        between 16 and 1024.
+
+        Parameters
+        -----------
+        format: Optional[str]
+            The format to attempt to convert the avatar to.
+            If the format is ``None``, then it is automatically
+            detected into either 'gif' or static_format depending on the
+            avatar being animated or not.
+        static_format: 'str'
+            Format to attempt to convert only non-animated avatars to.
+            Defaults to 'webp'
+        size: int
+            The size of the image to display.
+
+        Returns
+        --------
+        str
+            The resulting CDN URL.
+
+        Raises
+        ------
+        InvalidArgument
+            Bad image format passed to ``format`` or ``static_format``, or
+            invalid ``size``.
+        """
+        if not valid_icon_size(size):
+            raise InvalidArgument("size must be a power of 2 between 16 and 1024")
+        if format is not None and format not in VALID_AVATAR_FORMATS:
+            raise InvalidArgument("format must be None or one of {}".format(VALID_AVATAR_FORMATS))
+        if format == "gif" and not self.is_avatar_animated():
+            raise InvalidArgument("non animated avatars do not support gif format")
+        if static_format not in VALID_STATIC_FORMATS:
+            raise InvalidArgument("static_format must be one of {}".format(VALID_STATIC_FORMATS))
+
+        if self.avatar is None:
+            return self.default_avatar_url
+
+        if format is None:
+            if self.is_avatar_animated():
+                format = "gif"
+            else:
+                format = static_format
+
+        return "https://cdn.discordapp.com/avatars/{0.id}/{0.avatar}.{1}?size={2}".format(
+            self, format, size
+        )
+
+    @property
+    def default_avatar(self):
+        """Returns the default avatar for a given user. This is calculated by the user's discriminator"""
+        return DefaultAvatar(int(self.discriminator) % len(DefaultAvatar))
+
+    @property
+    def default_avatar_url(self):
+        """Returns a URL for a user's default avatar."""
+        return "https://cdn.discordapp.com/embed/avatars/{}.png".format(self.default_avatar.value)
+
+    @property
+    def colour(self):
+        """A property that returns a :class:`Colour` denoting the rendered colour
+        for the user. This always returns :meth:`Colour.default`.
+
+        There is an alias for this under ``color``.
+        """
+        return Colour.default()
+
+    color = colour
+
+    @property
+    def mention(self):
+        """Returns a string that allows you to mention the given user."""
+        return "<@{0.id}>".format(self)
+
+    def permissions_in(self, channel):
+        """An alias for :meth:`abc.GuildChannel.permissions_for`.
+
+        Basically equivalent to:
+
+        .. code-block:: python3
+
+            channel.permissions_for(self)
+
+        Parameters
+        -----------
+        channel
+            The channel to check your permissions for.
+        """
+        return channel.permissions_for(self)
+
+    @property
+    def created_at(self):
+        """Returns the user's creation time in UTC.
+
+        This is when the user's discord account was created."""
+        return snowflake_time(self.id)
+
+    @property
+    def display_name(self):
+        """Returns the user's display name.
+
+        For regular users this is just their username, but
+        if they have a guild specific nickname then that
+        is returned instead.
+        """
+        return self.name
+
+    def mentioned_in(self, message):
+        """Checks if the user is mentioned in the specified message.
+
+        Parameters
+        -----------
+        message : :class:`Message`
+            The message to check if you're mentioned in.
+        """
+
+        if message.mention_everyone:
+            return True
+
+        for user in message.mentions:
+            if user.id == self.id:
+                return True
+
+        return False
+
+
+class ClientUser(BaseUser):
+    """Represents your Discord user.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two users are equal.
+
+        .. describe:: x != y
+
+            Checks if two users are not equal.
+
+        .. describe:: hash(x)
+
+            Return the user's hash.
+
+        .. describe:: str(x)
+
+            Returns the user's name with discriminator.
+
+    Attributes
+    -----------
+    name: :class:`str`
+        The user's username.
+    id: :class:`int`
+        The user's unique ID.
+    discriminator: :class:`str`
+        The user's discriminator. This is given when the username has conflicts.
+    avatar: Optional[:class:`str`]
+        The avatar hash the user has. Could be None.
+    bot: :class:`bool`
+        Specifies if the user is a bot account.
+    verified: :class:`bool`
+        Specifies if the user is a verified account.
+    email: Optional[:class:`str`]
+        The email the user used when registering.
+    mfa_enabled: :class:`bool`
+        Specifies if the user has MFA turned on and working.
+    premium: :class:`bool`
+        Specifies if the user is a premium user (e.g. has Discord Nitro).
+    """
+
+    __slots__ = ("email", "verified", "mfa_enabled", "premium", "_relationships")
+
+    def __init__(self, *, state, data):
+        super().__init__(state=state, data=data)
+        self.verified = data.get("verified", False)
+        self.email = data.get("email")
+        self.mfa_enabled = data.get("mfa_enabled", False)
+        self.premium = data.get("premium", False)
+        self._relationships = {}
+
+    def __repr__(self):
+        return (
+            "<ClientUser id={0.id} name={0.name!r} discriminator={0.discriminator!r}"
+            " bot={0.bot} verified={0.verified} mfa_enabled={0.mfa_enabled}>".format(self)
+        )
+
+    def get_relationship(self, user_id):
+        """Retrieves the :class:`Relationship` if applicable.
+
+        Parameters
+        -----------
+        user_id: int
+            The user ID to check if we have a relationship with them.
+
+        Returns
+        --------
+        Optional[:class:`Relationship`]
+            The relationship if available or ``None``
+        """
+        return self._relationships.get(user_id)
+
+    @property
+    def relationships(self):
+        """Returns a :class:`list` of :class:`Relationship` that the user has."""
+        return list(self._relationships.values())
+
+    @property
+    def friends(self):
+        r"""Returns a :class:`list` of :class:`User`\s that the user is friends with."""
+        return [r.user for r in self._relationships.values() if r.type is RelationshipType.friend]
+
+    @property
+    def blocked(self):
+        r"""Returns a :class:`list` of :class:`User`\s that the user has blocked."""
+        return [r.user for r in self._relationships.values() if r.type is RelationshipType.blocked]
+
+    async def edit(self, **fields):
+        """|coro|
+
+        Edits the current profile of the client.
+
+        If a bot account is used then a password field is optional,
+        otherwise it is required.
+
+        Note
+        -----
+        To upload an avatar, a :term:`py:bytes-like object` must be passed in that
+        represents the image being uploaded. If this is done through a file
+        then the file must be opened via ``open('some_filename', 'rb')`` and
+        the :term:`py:bytes-like object` is given through the use of ``fp.read()``.
+
+        The only image formats supported for uploading is JPEG and PNG.
+
+        Parameters
+        -----------
+        password : str
+            The current password for the client's account.
+            Only applicable to user accounts.
+        new_password: str
+            The new password you wish to change to.
+            Only applicable to user accounts.
+        email: str
+            The new email you wish to change to.
+            Only applicable to user accounts.
+        house: Optional[:class:`HypeSquadHouse`]
+            The hypesquad house you wish to change to.
+            Could be ``None`` to leave the current house.
+            Only applicable to user accounts.
+        username :str
+            The new username you wish to change to.
+        avatar: bytes
+            A :term:`py:bytes-like object` representing the image to upload.
+            Could be ``None`` to denote no avatar.
+
+        Raises
+        ------
+        HTTPException
+            Editing your profile failed.
+        InvalidArgument
+            Wrong image format passed for ``avatar``.
+        ClientException
+            Password is required for non-bot accounts.
+            House field was not a HypeSquadHouse.
+        """
+
+        try:
+            avatar_bytes = fields["avatar"]
+        except KeyError:
+            avatar = self.avatar
+        else:
+            if avatar_bytes is not None:
+                avatar = _bytes_to_base64_data(avatar_bytes)
+            else:
+                avatar = None
+
+        not_bot_account = not self.bot
+        password = fields.get("password")
+        if not_bot_account and password is None:
+            raise ClientException("Password is required for non-bot accounts.")
+
+        args = {
+            "password": password,
+            "username": fields.get("username", self.name),
+            "avatar": avatar,
+        }
+
+        if not_bot_account:
+            args["email"] = fields.get("email", self.email)
+
+            if "new_password" in fields:
+                args["new_password"] = fields["new_password"]
+
+        http = self._state.http
+
+        if "house" in fields:
+            house = fields["house"]
+            if house is None:
+                await http.leave_hypesquad_house()
+            elif not isinstance(house, HypeSquadHouse):
+                raise ClientException("`house` parameter was not a HypeSquadHouse")
+            else:
+                value = house.value
+
+            await http.change_hypesquad_house(value)
+
+        data = await http.edit_profile(**args)
+        if not_bot_account:
+            self.email = data["email"]
+            try:
+                http._token(data["token"], bot=False)
+            except KeyError:
+                pass
+
+        # manually update data by calling __init__ explicitly.
+        self.__init__(state=self._state, data=data)
+
+    async def create_group(self, *recipients):
+        r"""|coro|
+
+        Creates a group direct message with the recipients
+        provided. These recipients must be have a relationship
+        of type :attr:`RelationshipType.friend`.
+
+        Bot accounts cannot create a group.
+
+        Parameters
+        -----------
+        \*recipients
+            An argument :class:`list` of :class:`User` to have in
+            your group.
+
+        Return
+        -------
+        :class:`GroupChannel`
+            The new group channel.
+
+        Raises
+        -------
+        HTTPException
+            Failed to create the group direct message.
+        ClientException
+            Attempted to create a group with only one recipient.
+            This does not include yourself.
+        """
+
+        from .channel import GroupChannel
+
+        if len(recipients) < 2:
+            raise ClientException("You must have two or more recipients to create a group.")
+
+        users = [str(u.id) for u in recipients]
+        data = await self._state.http.start_group(self.id, users)
+        return GroupChannel(me=self, data=data, state=self._state)
+
+
+class User(BaseUser, discord.abc.Messageable):
+    """Represents a Discord user.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two users are equal.
+
+        .. describe:: x != y
+
+            Checks if two users are not equal.
+
+        .. describe:: hash(x)
+
+            Return the user's hash.
+
+        .. describe:: str(x)
+
+            Returns the user's name with discriminator.
+
+    Attributes
+    -----------
+    name: :class:`str`
+        The user's username.
+    id: :class:`int`
+        The user's unique ID.
+    discriminator: :class:`str`
+        The user's discriminator. This is given when the username has conflicts.
+    avatar: Optional[:class:`str`]
+        The avatar hash the user has. Could be None.
+    bot: :class:`bool`
+        Specifies if the user is a bot account.
+    """
+
+    __slots__ = ("__weakref__",)
+
+    def __repr__(self):
+        return "<User id={0.id} name={0.name!r} discriminator={0.discriminator!r} bot={0.bot}>".format(
+            self
+        )
+
+    async def _get_channel(self):
+        ch = await self.create_dm()
+        return ch
+
+    @property
+    def dm_channel(self):
+        """Returns the :class:`DMChannel` associated with this user if it exists.
+
+        If this returns ``None``, you can create a DM channel by calling the
+        :meth:`create_dm` coroutine function.
+        """
+        return self._state._get_private_channel_by_user(self.id)
+
+    async def create_dm(self):
+        """Creates a :class:`DMChannel` with this user.
+
+        This should be rarely called, as this is done transparently for most
+        people.
+        """
+        found = self.dm_channel
+        if found is not None:
+            return found
+
+        state = self._state
+        data = await state.http.start_private_message(self.id)
+        return state.add_dm_channel(data)
+
+    @property
+    def relationship(self):
+        """Returns the :class:`Relationship` with this user if applicable, ``None`` otherwise."""
+        return self._state.user.get_relationship(self.id)
+
+    async def mutual_friends(self):
+        """|coro|
+
+        Gets all mutual friends of this user. This can only be used by non-bot accounts
+
+        Returns
+        -------
+        List[:class:`User`]
+            The users that are mutual friends.
+
+        Raises
+        -------
+        Forbidden
+            Not allowed to get mutual friends of this user.
+        HTTPException
+            Getting mutual friends failed.
+        """
+        state = self._state
+        mutuals = await state.http.get_mutual_friends(self.id)
+        return [User(state=state, data=friend) for friend in mutuals]
+
+    def is_friend(self):
+        """:class:`bool`: Checks if the user is your friend."""
+        r = self.relationship
+        if r is None:
+            return False
+        return r.type is RelationshipType.friend
+
+    def is_blocked(self):
+        """:class:`bool`: Checks if the user is blocked."""
+        r = self.relationship
+        if r is None:
+            return False
+        return r.type is RelationshipType.blocked
+
+    async def block(self):
+        """|coro|
+
+        Blocks the user.
+
+        Raises
+        -------
+        Forbidden
+            Not allowed to block this user.
+        HTTPException
+            Blocking the user failed.
+        """
+
+        await self._state.http.add_relationship(self.id, type=RelationshipType.blocked.value)
+
+    async def unblock(self):
+        """|coro|
+
+        Unblocks the user.
+
+        Raises
+        -------
+        Forbidden
+            Not allowed to unblock this user.
+        HTTPException
+            Unblocking the user failed.
+        """
+        await self._state.http.remove_relationship(self.id)
+
+    async def remove_friend(self):
+        """|coro|
+
+        Removes the user as a friend.
+
+        Raises
+        -------
+        Forbidden
+            Not allowed to remove this user as a friend.
+        HTTPException
+            Removing the user as a friend failed.
+        """
+        await self._state.http.remove_relationship(self.id)
+
+    async def send_friend_request(self):
+        """|coro|
+
+        Sends the user a friend request.
+
+        Raises
+        -------
+        Forbidden
+            Not allowed to send a friend request to the user.
+        HTTPException
+            Sending the friend request failed.
+        """
+        await self._state.http.send_friend_request(
+            username=self.name, discriminator=self.discriminator
+        )
+
+    async def profile(self):
+        """|coro|
+
+        Gets the user's profile. This can only be used by non-bot accounts.
+
+        Raises
+        -------
+        Forbidden
+            Not allowed to fetch profiles.
+        HTTPException
+            Fetching the profile failed.
+
+        Returns
+        --------
+        :class:`Profile`
+            The profile of the user.
+        """
+
+        state = self._state
+        data = await state.http.get_user_profile(self.id)
+
+        def transform(d):
+            return state._get_guild(int(d["id"]))
+
+        since = data.get("premium_since")
+        mutual_guilds = list(filter(None, map(transform, data.get("mutual_guilds", []))))
+        return Profile(
+            flags=data["user"].get("flags", 0),
+            premium_since=parse_time(since),
+            mutual_guilds=mutual_guilds,
+            user=self,
+            connected_accounts=data["connected_accounts"],
+        )

discord/utils.py

@@ -0,0 +1,369 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import array
+import asyncio
+import unicodedata
+from base64 import b64encode
+from bisect import bisect_left
+import datetime
+from email.utils import parsedate_to_datetime
+import functools
+from inspect import isawaitable as _isawaitable
+import json
+import re
+import warnings
+
+from .errors import InvalidArgument
+
+DISCORD_EPOCH = 1420070400000
+
+
+class cached_property:
+    def __init__(self, function):
+        self.function = function
+        self.__doc__ = getattr(function, "__doc__")
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+
+        value = self.function(instance)
+        setattr(instance, self.function.__name__, value)
+
+        return value
+
+
+class CachedSlotProperty:
+    def __init__(self, name, function):
+        self.name = name
+        self.function = function
+        self.__doc__ = getattr(function, "__doc__")
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+
+        try:
+            return getattr(instance, self.name)
+        except AttributeError:
+            value = self.function(instance)
+            setattr(instance, self.name, value)
+            return value
+
+
+def cached_slot_property(name):
+    def decorator(func):
+        return CachedSlotProperty(name, func)
+
+    return decorator
+
+
+def parse_time(timestamp):
+    if timestamp:
+        return datetime.datetime(*map(int, re.split(r"[^\d]", timestamp.replace("+00:00", ""))))
+    return None
+
+
+def deprecated(instead=None):
+    def actual_decorator(func):
+        @functools.wraps(func)
+        def decorated(*args, **kwargs):
+            warnings.simplefilter("always", DeprecationWarning)  # turn off filter
+            if instead:
+                fmt = "{0.__name__} is deprecated, use {1} instead."
+            else:
+                fmt = "{0.__name__} is deprecated."
+
+            warnings.warn(fmt.format(func, instead), stacklevel=3, category=DeprecationWarning)
+            warnings.simplefilter("default", DeprecationWarning)  # reset filter
+            return func(*args, **kwargs)
+
+        return decorated
+
+    return actual_decorator
+
+
+def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None):
+    """A helper function that returns the OAuth2 URL for inviting the bot
+    into guilds.
+
+    Parameters
+    -----------
+    client_id : str
+        The client ID for your bot.
+    permissions : :class:`Permissions`
+        The permissions you're requesting. If not given then you won't be requesting any
+        permissions.
+    guild : :class:`Guild`
+        The guild to pre-select in the authorization screen, if available.
+    redirect_uri : str
+        An optional valid redirect URI.
+    """
+    url = "https://discordapp.com/oauth2/authorize?client_id={}&scope=bot".format(client_id)
+    if permissions is not None:
+        url = url + "&permissions=" + str(permissions.value)
+    if guild is not None:
+        url = url + "&guild_id=" + str(guild.id)
+    if redirect_uri is not None:
+        from urllib.parse import urlencode
+
+        url = url + "&response_type=code&" + urlencode({"redirect_uri": redirect_uri})
+    return url
+
+
+def snowflake_time(id):
+    """Returns the creation date in UTC of a discord id."""
+    return datetime.datetime.utcfromtimestamp(((id >> 22) + DISCORD_EPOCH) / 1000)
+
+
+def time_snowflake(datetime_obj, high=False):
+    """Returns a numeric snowflake pretending to be created at the given date.
+
+    When using as the lower end of a range, use time_snowflake(high=False) - 1 to be inclusive, high=True to be exclusive
+    When using as the higher end of a range, use time_snowflake(high=True) + 1 to be inclusive, high=False to be exclusive
+
+    Parameters
+    -----------
+    datetime_obj
+        A timezone-naive datetime object representing UTC time.
+    high
+        Whether or not to set the lower 22 bit to high or low.
+    """
+    unix_seconds = (datetime_obj - type(datetime_obj)(1970, 1, 1)).total_seconds()
+    discord_millis = int(unix_seconds * 1000 - DISCORD_EPOCH)
+
+    return (discord_millis << 22) + (2 ** 22 - 1 if high else 0)
+
+
+def find(predicate, seq):
+    """A helper to return the first element found in the sequence
+    that meets the predicate. For example: ::
+
+        member = find(lambda m: m.name == 'Mighty', channel.guild.members)
+
+    would find the first :class:`Member` whose name is 'Mighty' and return it.
+    If an entry is not found, then ``None`` is returned.
+
+    This is different from `filter`_ due to the fact it stops the moment it finds
+    a valid entry.
+
+
+    .. _filter: https://docs.python.org/3.6/library/functions.html#filter
+
+    Parameters
+    -----------
+    predicate
+        A function that returns a boolean-like result.
+    seq : iterable
+        The iterable to search through.
+    """
+
+    for element in seq:
+        if predicate(element):
+            return element
+    return None
+
+
+def get(iterable, **attrs):
+    r"""A helper that returns the first element in the iterable that meets
+    all the traits passed in ``attrs``. This is an alternative for
+    :func:`discord.utils.find`.
+
+    When multiple attributes are specified, they are checked using
+    logical AND, not logical OR. Meaning they have to meet every
+    attribute passed in and not one of them.
+
+    To have a nested attribute search (i.e. search by ``x.y``) then
+    pass in ``x__y`` as the keyword argument.
+
+    If nothing is found that matches the attributes passed, then
+    ``None`` is returned.
+
+    Examples
+    ---------
+
+    Basic usage:
+
+    .. code-block:: python3
+
+        member = discord.utils.get(message.guild.members, name='Foo')
+
+    Multiple attribute matching:
+
+    .. code-block:: python3
+
+        channel = discord.utils.get(guild.voice_channels, name='Foo', bitrate=64000)
+
+    Nested attribute matching:
+
+    .. code-block:: python3
+
+        channel = discord.utils.get(client.get_all_channels(), guild__name='Cool', name='general')
+
+    Parameters
+    -----------
+    iterable
+        An iterable to search through.
+    \*\*attrs
+        Keyword arguments that denote attributes to search with.
+    """
+
+    def predicate(elem):
+        for attr, val in attrs.items():
+            nested = attr.split("__")
+            obj = elem
+            for attribute in nested:
+                obj = getattr(obj, attribute)
+
+            if obj != val:
+                return False
+        return True
+
+    return find(predicate, iterable)
+
+
+def _unique(iterable):
+    seen = set()
+    adder = seen.add
+    return [x for x in iterable if not (x in seen or adder(x))]
+
+
+def _get_as_snowflake(data, key):
+    try:
+        value = data[key]
+    except KeyError:
+        return None
+    else:
+        return value and int(value)
+
+
+def _get_mime_type_for_image(data):
+    if data.startswith(b"\x89\x50\x4E\x47\x0D\x0A\x1A\x0A"):
+        return "image/png"
+    elif data.startswith(b"\xFF\xD8") and data.rstrip(b"\0").endswith(b"\xFF\xD9"):
+        return "image/jpeg"
+    elif data.startswith((b"\x47\x49\x46\x38\x37\x61", b"\x47\x49\x46\x38\x39\x61")):
+        return "image/gif"
+    elif data.startswith(b"RIFF") and data[8:12] == b"WEBP":
+        return "image/webp"
+    else:
+        raise InvalidArgument("Unsupported image type given")
+
+
+def _bytes_to_base64_data(data):
+    fmt = "data:{mime};base64,{data}"
+    mime = _get_mime_type_for_image(data)
+    b64 = b64encode(data).decode("ascii")
+    return fmt.format(mime=mime, data=b64)
+
+
+def to_json(obj):
+    return json.dumps(obj, separators=(",", ":"), ensure_ascii=True)
+
+
+def _parse_ratelimit_header(request):
+    now = parsedate_to_datetime(request.headers["Date"])
+    reset = datetime.datetime.fromtimestamp(
+        int(request.headers["X-Ratelimit-Reset"]), datetime.timezone.utc
+    )
+    return (reset - now).total_seconds()
+
+
+async def maybe_coroutine(f, *args, **kwargs):
+    value = f(*args, **kwargs)
+    if _isawaitable(value):
+        return await value
+    else:
+        return value
+
+
+async def async_all(gen, *, check=_isawaitable):
+    for elem in gen:
+        if check(elem):
+            elem = await elem
+        if not elem:
+            return False
+    return True
+
+
+async def sane_wait_for(futures, *, timeout, loop):
+    _, pending = await asyncio.wait(futures, timeout=timeout, loop=loop)
+
+    if len(pending) != 0:
+        raise asyncio.TimeoutError()
+
+
+def valid_icon_size(size):
+    """Icons must be power of 2 within [16, 2048]."""
+    return not size & (size - 1) and size in range(16, 2049)
+
+
+class SnowflakeList(array.array):
+    """Internal data storage class to efficiently store a list of snowflakes.
+
+    This should have the following characteristics:
+
+    - Low memory usage
+    - O(n) iteration (obviously)
+    - O(n log n) initial creation if data is unsorted
+    - O(log n) search and indexing
+    - O(n) insertion
+    """
+
+    __slots__ = ()
+
+    def __new__(cls, data, *, is_sorted=False):
+        return array.array.__new__(cls, "Q", data if is_sorted else sorted(data))
+
+    def add(self, element):
+        i = bisect_left(self, element)
+        self.insert(i, element)
+
+    def get(self, element):
+        i = bisect_left(self, element)
+        return self[i] if i != len(self) and self[i] == element else None
+
+    def has(self, element):
+        i = bisect_left(self, element)
+        return i != len(self) and self[i] == element
+
+
+_IS_ASCII = re.compile(r"^[\x00-\x7f]+$")
+
+
+def _string_width(string, *, _IS_ASCII=_IS_ASCII):
+    """Returns string's width."""
+    match = _IS_ASCII.match(string)
+    if match:
+        return match.endpos
+
+    UNICODE_WIDE_CHAR_TYPE = "WFA"
+    width = 0
+    func = unicodedata.east_asian_width
+    for char in string:
+        width += 2 if func(char) in UNICODE_WIDE_CHAR_TYPE else 1
+    return width

discord/voice_client.py

@@ -0,0 +1,448 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+"""Some documentation to refer to:
+
+- Our main web socket (mWS) sends opcode 4 with a guild ID and channel ID.
+- The mWS receives VOICE_STATE_UPDATE and VOICE_SERVER_UPDATE.
+- We pull the session_id from VOICE_STATE_UPDATE.
+- We pull the token, endpoint and server_id from VOICE_SERVER_UPDATE.
+- Then we initiate the voice web socket (vWS) pointing to the endpoint.
+- We send opcode 0 with the user_id, server_id, session_id and token using the vWS.
+- The vWS sends back opcode 2 with an ssrc, port, modes(array) and hearbeat_interval.
+- We send a UDP discovery packet to endpoint:port and receive our IP and our port in LE.
+- Then we send our IP and port via vWS with opcode 1.
+- When that's all done, we receive opcode 4 from the vWS.
+- Finally we can transmit data to endpoint:port.
+"""
+
+import asyncio
+import socket
+import logging
+import struct
+import threading
+
+from . import opus
+from .backoff import ExponentialBackoff
+from .gateway import *
+from .errors import ClientException, ConnectionClosed
+from .player import AudioPlayer, AudioSource
+
+try:
+    import nacl.secret
+
+    has_nacl = True
+except ImportError:
+    has_nacl = False
+
+
+log = logging.getLogger(__name__)
+
+
+class VoiceClient:
+    """Represents a Discord voice connection.
+
+    You do not create these, you typically get them from
+    e.g. :meth:`VoiceChannel.connect`.
+
+    Warning
+    --------
+    In order to play audio, you must have loaded the opus library
+    through :func:`opus.load_opus`.
+
+    If you don't do this then the library will not be able to
+    transmit audio.
+
+    Attributes
+    -----------
+    session_id: :class:`str`
+        The voice connection session ID.
+    token: :class:`str`
+        The voice connection token.
+    endpoint: :class:`str`
+        The endpoint we are connecting to.
+    channel: :class:`abc.Connectable`
+        The voice channel connected to.
+    loop
+        The event loop that the voice client is running on.
+    """
+
+    def __init__(self, state, timeout, channel):
+        if not has_nacl:
+            raise RuntimeError("PyNaCl library needed in order to use voice")
+
+        self.channel = channel
+        self.main_ws = None
+        self.timeout = timeout
+        self.ws = None
+        self.socket = None
+        self.loop = state.loop
+        self._state = state
+        # this will be used in the AudioPlayer thread
+        self._connected = threading.Event()
+        self._handshake_complete = asyncio.Event(loop=self.loop)
+
+        self.mode = None
+        self._connections = 0
+        self.sequence = 0
+        self.timestamp = 0
+        self._runner = None
+        self._player = None
+        self.encoder = opus.Encoder()
+
+    warn_nacl = not has_nacl
+    supported_modes = ("xsalsa20_poly1305_suffix", "xsalsa20_poly1305")
+
+    @property
+    def guild(self):
+        """Optional[:class:`Guild`]: The guild we're connected to, if applicable."""
+        return getattr(self.channel, "guild", None)
+
+    @property
+    def user(self):
+        """:class:`ClientUser`: The user connected to voice (i.e. ourselves)."""
+        return self._state.user
+
+    def checked_add(self, attr, value, limit):
+        val = getattr(self, attr)
+        if val + value > limit:
+            setattr(self, attr, 0)
+        else:
+            setattr(self, attr, val + value)
+
+    # connection related
+
+    async def start_handshake(self):
+        log.info("Starting voice handshake...")
+
+        guild_id, channel_id = self.channel._get_voice_state_pair()
+        state = self._state
+        self.main_ws = ws = state._get_websocket(guild_id)
+        self._connections += 1
+
+        # request joining
+        await ws.voice_state(guild_id, channel_id)
+
+        try:
+            await asyncio.wait_for(
+                self._handshake_complete.wait(), timeout=self.timeout, loop=self.loop
+            )
+        except asyncio.TimeoutError:
+            await self.terminate_handshake(remove=True)
+            raise
+
+        log.info(
+            "Voice handshake complete. Endpoint found %s (IP: %s)", self.endpoint, self.endpoint_ip
+        )
+
+    async def terminate_handshake(self, *, remove=False):
+        guild_id, channel_id = self.channel._get_voice_state_pair()
+        self._handshake_complete.clear()
+        await self.main_ws.voice_state(guild_id, None, self_mute=True)
+
+        log.info(
+            "The voice handshake is being terminated for Channel ID %s (Guild ID %s)",
+            channel_id,
+            guild_id,
+        )
+        if remove:
+            log.info(
+                "The voice client has been removed for Channel ID %s (Guild ID %s)",
+                channel_id,
+                guild_id,
+            )
+            key_id, _ = self.channel._get_voice_client_key()
+            self._state._remove_voice_client(key_id)
+
+    async def _create_socket(self, server_id, data):
+        self._connected.clear()
+        self.session_id = self.main_ws.session_id
+        self.server_id = server_id
+        self.token = data.get("token")
+        endpoint = data.get("endpoint")
+
+        if endpoint is None or self.token is None:
+            log.warning(
+                "Awaiting endpoint... This requires waiting. "
+                "If timeout occurred considering raising the timeout and reconnecting."
+            )
+            return
+
+        self.endpoint = endpoint.replace(":80", "")
+        self.endpoint_ip = socket.gethostbyname(self.endpoint)
+
+        if self.socket:
+            try:
+                self.socket.close()
+            except Exception:
+                pass
+
+        self.socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self.socket.setblocking(False)
+
+        if self._handshake_complete.is_set():
+            # terminate the websocket and handle the reconnect loop if necessary.
+            self._handshake_complete.clear()
+            await self.ws.close(4000)
+            return
+
+        self._handshake_complete.set()
+
+    async def connect(self, *, reconnect=True, _tries=0, do_handshake=True):
+        log.info("Connecting to voice...")
+        try:
+            del self.secret_key
+        except AttributeError:
+            pass
+
+        if do_handshake:
+            await self.start_handshake()
+
+        try:
+            self.ws = await DiscordVoiceWebSocket.from_client(self)
+            self._connected.clear()
+            while not hasattr(self, "secret_key"):
+                await self.ws.poll_event()
+            self._connected.set()
+        except (ConnectionClosed, asyncio.TimeoutError):
+            if reconnect and _tries < 5:
+                log.exception("Failed to connect to voice... Retrying...")
+                await asyncio.sleep(1 + _tries * 2.0, loop=self.loop)
+                await self.terminate_handshake()
+                await self.connect(reconnect=reconnect, _tries=_tries + 1)
+            else:
+                raise
+
+        if self._runner is None:
+            self._runner = self.loop.create_task(self.poll_voice_ws(reconnect))
+
+    async def poll_voice_ws(self, reconnect):
+        backoff = ExponentialBackoff()
+        while True:
+            try:
+                await self.ws.poll_event()
+            except (ConnectionClosed, asyncio.TimeoutError) as exc:
+                if isinstance(exc, ConnectionClosed):
+                    if exc.code == 1000:
+                        await self.disconnect()
+                        break
+
+                if not reconnect:
+                    await self.disconnect()
+                    raise
+
+                retry = backoff.delay()
+                log.exception("Disconnected from voice... Reconnecting in %.2fs.", retry)
+                self._connected.clear()
+                await asyncio.sleep(retry, loop=self.loop)
+                await self.terminate_handshake()
+                try:
+                    await self.connect(reconnect=True)
+                except asyncio.TimeoutError:
+                    # at this point we've retried 5 times... let's continue the loop.
+                    log.warning("Could not connect to voice... Retrying...")
+                    continue
+
+    async def disconnect(self, *, force=False):
+        """|coro|
+
+        Disconnects this voice client from voice.
+        """
+        if not force and not self._connected.is_set():
+            return
+
+        self.stop()
+        self._connected.clear()
+
+        try:
+            if self.ws:
+                await self.ws.close()
+
+            await self.terminate_handshake(remove=True)
+        finally:
+            if self.socket:
+                self.socket.close()
+
+    async def move_to(self, channel):
+        """|coro|
+
+        Moves you to a different voice channel.
+
+        Parameters
+        -----------
+        channel: :class:`abc.Snowflake`
+            The channel to move to. Must be a voice channel.
+        """
+        guild_id, _ = self.channel._get_voice_state_pair()
+        await self.main_ws.voice_state(guild_id, channel.id)
+
+    def is_connected(self):
+        """:class:`bool`: Indicates if the voice client is connected to voice."""
+        return self._connected.is_set()
+
+    # audio related
+
+    def _get_voice_packet(self, data):
+        header = bytearray(12)
+
+        # Formulate rtp header
+        header[0] = 0x80
+        header[1] = 0x78
+        struct.pack_into(">H", header, 2, self.sequence)
+        struct.pack_into(">I", header, 4, self.timestamp)
+        struct.pack_into(">I", header, 8, self.ssrc)
+
+        encrypt_packet = getattr(self, "_encrypt_" + self.mode)
+        return encrypt_packet(header, data)
+
+    def _encrypt_xsalsa20_poly1305(self, header, data):
+        box = nacl.secret.SecretBox(bytes(self.secret_key))
+        nonce = bytearray(24)
+        nonce[:12] = header
+
+        return header + box.encrypt(bytes(data), bytes(nonce)).ciphertext
+
+    def _encrypt_xsalsa20_poly1305_suffix(self, header, data):
+        box = nacl.secret.SecretBox(bytes(self.secret_key))
+        nonce = nacl.utils.random(nacl.secret.SecretBox.NONCE_SIZE)
+
+        return header + box.encrypt(bytes(data), nonce).ciphertext + nonce
+
+    def play(self, source, *, after=None):
+        """Plays an :class:`AudioSource`.
+
+        The finalizer, ``after`` is called after the source has been exhausted
+        or an error occurred.
+
+        If an error happens while the audio player is running, the exception is
+        caught and the audio player is then stopped.
+
+        Parameters
+        -----------
+        source: :class:`AudioSource`
+            The audio source we're reading from.
+        after
+            The finalizer that is called after the stream is exhausted.
+            All exceptions it throws are silently discarded. This function
+            must have a single parameter, ``error``, that denotes an
+            optional exception that was raised during playing.
+
+        Raises
+        -------
+        ClientException
+            Already playing audio or not connected.
+        TypeError
+            source is not a :class:`AudioSource` or after is not a callable.
+        """
+
+        if not self._connected:
+            raise ClientException("Not connected to voice.")
+
+        if self.is_playing():
+            raise ClientException("Already playing audio.")
+
+        if not isinstance(source, AudioSource):
+            raise TypeError("source must an AudioSource not {0.__class__.__name__}".format(source))
+
+        self._player = AudioPlayer(source, self, after=after)
+        self._player.start()
+
+    def is_playing(self):
+        """Indicates if we're currently playing audio."""
+        return self._player is not None and self._player.is_playing()
+
+    def is_paused(self):
+        """Indicates if we're playing audio, but if we're paused."""
+        return self._player is not None and self._player.is_paused()
+
+    def stop(self):
+        """Stops playing audio."""
+        if self._player:
+            self._player.stop()
+            self._player = None
+
+    def pause(self):
+        """Pauses the audio playing."""
+        if self._player:
+            self._player.pause()
+
+    def resume(self):
+        """Resumes the audio playing."""
+        if self._player:
+            self._player.resume()
+
+    @property
+    def source(self):
+        """Optional[:class:`AudioSource`]: The audio source being played, if playing.
+
+        This property can also be used to change the audio source currently being played.
+        """
+        return self._player.source if self._player else None
+
+    @source.setter
+    def source(self, value):
+        if not isinstance(value, AudioSource):
+            raise TypeError("expected AudioSource not {0.__class__.__name__}.".format(value))
+
+        if self._player is None:
+            raise ValueError("Not playing anything.")
+
+        self._player._set_source(value)
+
+    def send_audio_packet(self, data, *, encode=True):
+        """Sends an audio packet composed of the data.
+
+        You must be connected to play audio.
+
+        Parameters
+        ----------
+        data: bytes
+            The :term:`py:bytes-like object` denoting PCM or Opus voice data.
+        encode: bool
+            Indicates if ``data`` should be encoded into Opus.
+
+        Raises
+        -------
+        ClientException
+            You are not connected.
+        OpusError
+            Encoding the data failed.
+        """
+
+        self.checked_add("sequence", 1, 65535)
+        if encode:
+            encoded_data = self.encoder.encode(data, self.encoder.SAMPLES_PER_FRAME)
+        else:
+            encoded_data = data
+        packet = self._get_voice_packet(encoded_data)
+        try:
+            self.socket.sendto(packet, (self.endpoint_ip, self.voice_port))
+        except BlockingIOError:
+            log.warning(
+                "A packet has been dropped (seq: %s, timestamp: %s)", self.sequence, self.timestamp
+            )
+
+        self.checked_add("timestamp", self.encoder.SAMPLES_PER_FRAME, 4294967295)

discord/webhook.py

@@ -0,0 +1,703 @@
+# -*- coding: utf-8 -*-
+
+"""
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 Rapptz
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+"""
+
+import asyncio
+import json
+import time
+import re
+
+import aiohttp
+
+from . import utils
+from .errors import InvalidArgument, HTTPException, Forbidden, NotFound
+from .user import BaseUser, User
+
+__all__ = ["WebhookAdapter", "AsyncWebhookAdapter", "RequestsWebhookAdapter", "Webhook"]
+
+
+class WebhookAdapter:
+    """Base class for all webhook adapters.
+
+    Attributes
+    ------------
+    webhook: :class:`Webhook`
+        The webhook that owns this adapter.
+    """
+
+    BASE = "https://discordapp.com/api/v7"
+
+    def _prepare(self, webhook):
+        self._webhook_id = webhook.id
+        self._webhook_token = webhook.token
+        self._request_url = "{0.BASE}/webhooks/{1}/{2}".format(self, webhook.id, webhook.token)
+        self.webhook = webhook
+
+    def request(self, verb, url, payload=None, multipart=None):
+        """Actually does the request.
+
+        Subclasses must implement this.
+
+        Parameters
+        -----------
+        verb: str
+            The HTTP verb to use for the request.
+        url: str
+            The URL to send the request to. This will have
+            the query parameters already added to it, if any.
+        multipart: Optional[dict]
+            A dict containing multipart form data to send with
+            the request. If a filename is being uploaded, then it will
+            be under a ``file`` key which will have a 3-element :class:`tuple`
+            denoting ``(filename, file, content_type)``.
+        payload: Optional[dict]
+            The JSON to send with the request, if any.
+        """
+        raise NotImplementedError()
+
+    def delete_webhook(self):
+        return self.request("DELETE", self._request_url)
+
+    def edit_webhook(self, **payload):
+        return self.request("PATCH", self._request_url, payload=payload)
+
+    def handle_execution_response(self, data, *, wait):
+        """Transforms the webhook execution response into something
+        more meaningful.
+
+        This is mainly used to convert the data into a :class:`Message`
+        if necessary.
+
+        Subclasses must implement this.
+
+        Parameters
+        ------------
+        data
+            The data that was returned from the request.
+        wait: bool
+            Whether the webhook execution was asked to wait or not.
+        """
+        raise NotImplementedError()
+
+    def store_user(self, data):
+        # mocks a ConnectionState for appropriate use for Message
+        return BaseUser(state=self.webhook._state, data=data)
+
+    def execute_webhook(self, *, payload, wait=False, file=None, files=None):
+        if file is not None:
+            multipart = {"file": file, "payload_json": utils.to_json(payload)}
+            data = None
+        elif files is not None:
+            multipart = {"payload_json": utils.to_json(payload)}
+            for i, file in enumerate(files, start=1):
+                multipart["file%i" % i] = file
+            data = None
+        else:
+            data = payload
+            multipart = None
+
+        url = "%s?wait=%d" % (self._request_url, wait)
+        maybe_coro = self.request("POST", url, multipart=multipart, payload=data)
+        return self.handle_execution_response(maybe_coro, wait=wait)
+
+
+class AsyncWebhookAdapter(WebhookAdapter):
+    """A webhook adapter suited for use with aiohttp.
+
+    .. note::
+
+        You are responsible for cleaning up the client session.
+
+    Parameters
+    -----------
+    session: aiohttp.ClientSession
+        The session to use to send requests.
+    """
+
+    def __init__(self, session):
+        self.session = session
+        self.loop = session.loop
+
+    async def request(self, verb, url, payload=None, multipart=None):
+        headers = {}
+        data = None
+        if payload:
+            headers["Content-Type"] = "application/json"
+            data = utils.to_json(payload)
+
+        if multipart:
+            data = aiohttp.FormData()
+            for key, value in multipart.items():
+                if key.startswith("file"):
+                    data.add_field(key, value[1], filename=value[0], content_type=value[2])
+                else:
+                    data.add_field(key, value)
+
+        for tries in range(5):
+            async with self.session.request(verb, url, headers=headers, data=data) as r:
+                data = await r.text(encoding="utf-8")
+                if r.headers["Content-Type"] == "application/json":
+                    data = json.loads(data)
+
+                # check if we have rate limit header information
+                remaining = r.headers.get("X-Ratelimit-Remaining")
+                if remaining == "0" and r.status != 429:
+                    delta = utils._parse_ratelimit_header(r)
+                    await asyncio.sleep(delta, loop=self.loop)
+
+                if 300 > r.status >= 200:
+                    return data
+
+                # we are being rate limited
+                if r.status == 429:
+                    retry_after = data["retry_after"] / 1000.0
+                    await asyncio.sleep(retry_after, loop=self.loop)
+                    continue
+
+                if r.status in (500, 502):
+                    await asyncio.sleep(1 + tries * 2, loop=self.loop)
+                    continue
+
+                if r.status == 403:
+                    raise Forbidden(r, data)
+                elif r.status == 404:
+                    raise NotFound(r, data)
+                else:
+                    raise HTTPException(r, data)
+
+    async def handle_execution_response(self, response, *, wait):
+        data = await response
+        if not wait:
+            return data
+
+        # transform into Message object
+        from .message import Message
+
+        return Message(data=data, state=self.webhook._state, channel=self.webhook.channel)
+
+
+class RequestsWebhookAdapter(WebhookAdapter):
+    """A webhook adapter suited for use with ``requests``.
+
+    Only versions of requests higher than 2.13.0 are supported.
+
+    Parameters
+    -----------
+    session: Optional[`requests.Session <http://docs.python-requests.org/en/latest/api/#requests.Session>`_]
+        The requests session to use for sending requests. If not given then
+        each request will create a new session. Note if a session is given,
+        the webhook adapter **will not** clean it up for you. You must close
+        the session yourself.
+    sleep: bool
+        Whether to sleep the thread when encountering a 429 or pre-emptive
+        rate limit or a 5xx status code. Defaults to ``True``. If set to
+        ``False`` then this will raise an :exc:`HTTPException` instead.
+    """
+
+    def __init__(self, session=None, *, sleep=True):
+        import requests
+
+        self.session = session or requests
+        self.sleep = sleep
+
+    def request(self, verb, url, payload=None, multipart=None):
+        headers = {}
+        data = None
+        if payload:
+            headers["Content-Type"] = "application/json"
+            data = utils.to_json(payload)
+
+        if multipart is not None:
+            data = {"payload_json": multipart.pop("payload_json")}
+
+        for tries in range(5):
+            r = self.session.request(verb, url, headers=headers, data=data, files=multipart)
+            r.encoding = "utf-8"
+            data = r.text
+
+            # compatibility with aiohttp
+            r.status = r.status_code
+
+            if r.headers["Content-Type"] == "application/json":
+                data = json.loads(data)
+
+            # check if we have rate limit header information
+            remaining = r.headers.get("X-Ratelimit-Remaining")
+            if remaining == "0" and r.status != 429 and self.sleep:
+                delta = utils._parse_ratelimit_header(r)
+                time.sleep(delta)
+
+            if 300 > r.status >= 200:
+                return data
+
+            # we are being rate limited
+            if r.status == 429:
+                if self.sleep:
+                    retry_after = data["retry_after"] / 1000.0
+                    time.sleep(retry_after)
+                    continue
+                else:
+                    raise HTTPException(r, data)
+
+            if self.sleep and r.status in (500, 502):
+                time.sleep(1 + tries * 2)
+                continue
+
+            if r.status == 403:
+                raise Forbidden(r, data)
+            elif r.status == 404:
+                raise NotFound(r, data)
+            else:
+                raise HTTPException(r, data)
+
+    def handle_execution_response(self, response, *, wait):
+        if not wait:
+            return response
+
+        # transform into Message object
+        from .message import Message
+
+        return Message(data=response, state=self.webhook._state, channel=self.webhook.channel)
+
+
+class Webhook:
+    """Represents a Discord webhook.
+
+    Webhooks are a form to send messages to channels in Discord without a
+    bot user or authentication.
+
+    There are two main ways to use Webhooks. The first is through the ones
+    received by the library such as :meth:`.Guild.webhooks` and
+    :meth:`.TextChannel.webhooks`. The ones received by the library will
+    automatically have an adapter bound using the library's HTTP session.
+    Those webhooks will have :meth:`~.Webhook.send`, :meth:`~.Webhook.delete` and
+    :meth:`~.Webhook.edit` as coroutines.
+
+    The second form involves creating a webhook object manually without having
+    it bound to a websocket connection using the :meth:`~.Webhook.from_url` or
+    :meth:`~.Webhook.partial` classmethods. This form allows finer grained control
+    over how requests are done, allowing you to mix async and sync code using either
+    ``aiohttp`` or ``requests``.
+
+    For example, creating a webhook from a URL and using ``aiohttp``:
+
+    .. code-block:: python3
+
+        from discord import Webhook, AsyncWebhookAdapter
+        import aiohttp
+
+        async def foo():
+            async with aiohttp.ClientSession() as session:
+                webhook = Webhook.from_url('url-here', adapter=AsyncWebhookAdapter(session))
+                await webhook.send('Hello World', username='Foo')
+
+    Or creating a webhook from an ID and token and using ``requests``:
+
+    .. code-block:: python3
+
+        import requests
+        from discord import Webhook, RequestsWebhookAdapter
+
+        webhook = Webhook.partial(123456, 'abcdefg', adapter=RequestsWebhookAdapter())
+        webhook.send('Hello World', username='Foo')
+
+    Attributes
+    ------------
+    id: :class:`int`
+        The webhook's ID
+    token: :class:`str`
+        The authentication token of the webhook.
+    guild_id: Optional[:class:`int`]
+        The guild ID this webhook is for.
+    channel_id: Optional[:class:`int`]
+        The channel ID this webhook is for.
+    user: Optional[:class:`abc.User`]
+        The user this webhook was created by. If the webhook was
+        received without authentication then this will be ``None``.
+    name: Optional[:class:`str`]
+        The default name of the webhook.
+    avatar: Optional[:class:`str`]
+        The default avatar of the webhook.
+    """
+
+    __slots__ = (
+        "id",
+        "guild_id",
+        "channel_id",
+        "user",
+        "name",
+        "avatar",
+        "token",
+        "_state",
+        "_adapter",
+    )
+
+    def __init__(self, data, *, adapter, state=None):
+        self.id = int(data["id"])
+        self.channel_id = utils._get_as_snowflake(data, "channel_id")
+        self.guild_id = utils._get_as_snowflake(data, "guild_id")
+        self.name = data.get("name")
+        self.avatar = data.get("avatar")
+        self.token = data["token"]
+        self._state = state
+        self._adapter = adapter
+        self._adapter._prepare(self)
+
+        user = data.get("user")
+        if user is None:
+            self.user = None
+        elif state is None:
+            self.user = BaseUser(state=None, data=user)
+        else:
+            self.user = User(state=state, data=user)
+
+    def __repr__(self):
+        return "<Webhook id=%r>" % self.id
+
+    @property
+    def url(self):
+        """Returns the webhook's url."""
+        return "https://discordapp.com/api/webhooks/{}/{}".format(self.id, self.token)
+
+    @classmethod
+    def partial(cls, id, token, *, adapter):
+        """Creates a partial :class:`Webhook`.
+
+        A partial webhook is just a webhook object with an ID and a token.
+
+        Parameters
+        -----------
+        id: int
+            The ID of the webhook.
+        token: str
+            The authentication token of the webhook.
+        adapter: :class:`WebhookAdapter`
+            The webhook adapter to use when sending requests. This is
+            typically :class:`AsyncWebhookAdapter` for ``aiohttp`` or
+            :class:`RequestsWebhookAdapter` for ``requests``.
+        """
+
+        if not isinstance(adapter, WebhookAdapter):
+            raise TypeError("adapter must be a subclass of WebhookAdapter")
+
+        data = {"id": id, "token": token}
+
+        return cls(data, adapter=adapter)
+
+    @classmethod
+    def from_url(cls, url, *, adapter):
+        """Creates a partial :class:`Webhook` from a webhook URL.
+
+        Parameters
+        ------------
+        url: str
+            The URL of the webhook.
+        adapter: :class:`WebhookAdapter`
+            The webhook adapter to use when sending requests. This is
+            typically :class:`AsyncWebhookAdapter` for ``aiohttp`` or
+            :class:`RequestsWebhookAdapter` for ``requests``.
+
+        Raises
+        -------
+        InvalidArgument
+            The URL is invalid.
+        """
+
+        m = re.search(
+            r"discordapp.com/api/webhooks/(?P<id>[0-9]{17,21})/(?P<token>[A-Za-z0-9\.\-\_]{60,68})",
+            url,
+        )
+        if m is None:
+            raise InvalidArgument("Invalid webhook URL given.")
+        return cls(m.groupdict(), adapter=adapter)
+
+    @classmethod
+    def from_state(cls, data, state):
+        return cls(data, adapter=AsyncWebhookAdapter(session=state.http._session), state=state)
+
+    @property
+    def guild(self):
+        """Optional[:class:`Guild`]: The guild this webhook belongs to.
+
+        If this is a partial webhook, then this will always return ``None``.
+        """
+        return self._state and self._state._get_guild(self.guild_id)
+
+    @property
+    def channel(self):
+        """Optional[:class:`TextChannel`]: The text channel this webhook belongs to.
+
+        If this is a partial webhook, then this will always return ``None``.
+        """
+        guild = self.guild
+        return guild and guild.get_channel(self.channel_id)
+
+    @property
+    def created_at(self):
+        """Returns the webhook's creation time in UTC."""
+        return utils.snowflake_time(self.id)
+
+    @property
+    def avatar_url(self):
+        """Returns a friendly URL version of the avatar the webhook has.
+
+        If the webhook does not have a traditional avatar, their default
+        avatar URL is returned instead.
+
+        This is equivalent to calling :meth:`avatar_url_as` with the
+        default parameters.
+        """
+        return self.avatar_url_as()
+
+    def avatar_url_as(self, *, format=None, size=1024):
+        """Returns a friendly URL version of the avatar the webhook has.
+
+        If the webhook does not have a traditional avatar, their default
+        avatar URL is returned instead.
+
+        The format must be one of 'jpeg', 'jpg', or 'png'.
+        The size must be a power of 2 between 16 and 1024.
+
+        Parameters
+        -----------
+        format: Optional[str]
+            The format to attempt to convert the avatar to.
+            If the format is ``None``, then it is equivalent to png.
+        size: int
+            The size of the image to display.
+
+        Returns
+        --------
+        str
+            The resulting CDN URL.
+
+        Raises
+        ------
+        InvalidArgument
+            Bad image format passed to ``format`` or invalid ``size``.
+        """
+        if self.avatar is None:
+            # Default is always blurple apparently
+            return "https://cdn.discordapp.com/embed/avatars/0.png"
+
+        if not utils.valid_icon_size(size):
+            raise InvalidArgument("size must be a power of 2 between 16 and 1024")
+
+        format = format or "png"
+
+        if format not in ("png", "jpg", "jpeg"):
+            raise InvalidArgument("format must be one of 'png', 'jpg', or 'jpeg'.")
+
+        return "https://cdn.discordapp.com/avatars/{0.id}/{0.avatar}.{1}?size={2}".format(
+            self, format, size
+        )
+
+    def delete(self):
+        """|maybecoro|
+
+        Deletes this Webhook.
+
+        If the webhook is constructed with a :class:`RequestsWebhookAdapter` then this is
+        not a coroutine.
+
+        Raises
+        -------
+        HTTPException
+            Deleting the webhook failed.
+        NotFound
+            This webhook does not exist.
+        Forbidden
+            You do not have permissions to delete this webhook.
+        """
+        return self._adapter.delete_webhook()
+
+    def edit(self, **kwargs):
+        """|maybecoro|
+
+        Edits this Webhook.
+
+        If the webhook is constructed with a :class:`RequestsWebhookAdapter` then this is
+        not a coroutine.
+
+        Parameters
+        -------------
+        name: Optional[str]
+            The webhook's new default name.
+        avatar: Optional[bytes]
+            A :term:`py:bytes-like object` representing the webhook's new default avatar.
+
+        Raises
+        -------
+        HTTPException
+            Editing the webhook failed.
+        NotFound
+            This webhook does not exist.
+        Forbidden
+            You do not have permissions to edit this webhook.
+        """
+        payload = {}
+
+        try:
+            name = kwargs["name"]
+        except KeyError:
+            pass
+        else:
+            if name is not None:
+                payload["name"] = str(name)
+            else:
+                payload["name"] = None
+
+        try:
+            avatar = kwargs["avatar"]
+        except KeyError:
+            pass
+        else:
+            if avatar is not None:
+                payload["avatar"] = utils._bytes_to_base64_data(avatar)
+            else:
+                payload["avatar"] = None
+
+        return self._adapter.edit_webhook(**payload)
+
+    def send(
+        self,
+        content=None,
+        *,
+        wait=False,
+        username=None,
+        avatar_url=None,
+        tts=False,
+        file=None,
+        files=None,
+        embed=None,
+        embeds=None
+    ):
+        """|maybecoro|
+
+        Sends a message using the webhook.
+
+        If the webhook is constructed with a :class:`RequestsWebhookAdapter` then this is
+        not a coroutine.
+
+        The content must be a type that can convert to a string through ``str(content)``.
+
+        To upload a single file, the ``file`` parameter should be used with a
+        single :class:`File` object.
+
+        If the ``embed`` parameter is provided, it must be of type :class:`Embed` and
+        it must be a rich embed type. You cannot mix the ``embed`` parameter with the
+        ``embeds`` parameter, which must be a :class:`list` of :class:`Embed` objects to send.
+
+        Parameters
+        ------------
+        content
+            The content of the message to send.
+        wait: bool
+            Whether the server should wait before sending a response. This essentially
+            means that the return type of this function changes from ``None`` to
+            a :class:`Message` if set to ``True``.
+        username: str
+            The username to send with this message. If no username is provided
+            then the default username for the webhook is used.
+        avatar_url: str
+            The avatar URL to send with this message. If no avatar URL is provided
+            then the default avatar for the webhook is used.
+        tts: bool
+            Indicates if the message should be sent using text-to-speech.
+        file: :class:`File`
+            The file to upload. This cannot be mixed with ``files`` parameter.
+        files: List[:class:`File`]
+            A list of files to send with the content. This cannot be mixed with the
+            ``file`` parameter.
+        embed: :class:`Embed`
+            The rich embed for the content to send. This cannot be mixed with
+            ``embeds`` parameter.
+        embeds: List[:class:`Embed`]
+            A list of embeds to send with the content. Maximum of 10. This cannot
+            be mixed with the ``embed`` parameter.
+
+        Raises
+        --------
+        HTTPException
+            Sending the message failed.
+        NotFound
+            This webhook was not found.
+        Forbidden
+            The authorization token for the webhook is incorrect.
+        InvalidArgument
+            You specified both ``embed`` and ``embeds`` or the length of
+            ``embeds`` was invalid.
+
+        Returns
+        ---------
+        Optional[:class:`Message`]
+            The message that was sent.
+        """
+
+        payload = {}
+
+        if files is not None and file is not None:
+            raise InvalidArgument("Cannot mix file and files keyword arguments.")
+        if embeds is not None and embed is not None:
+            raise InvalidArgument("Cannot mix embed and embeds keyword arguments.")
+
+        if embeds is not None:
+            if len(embeds) > 10:
+                raise InvalidArgument("embeds has a maximum of 10 elements.")
+            payload["embeds"] = [e.to_dict() for e in embeds]
+
+        if embed is not None:
+            payload["embeds"] = [embed.to_dict()]
+
+        if content is not None:
+            payload["content"] = str(content)
+
+        payload["tts"] = tts
+        if avatar_url:
+            payload["avatar_url"] = avatar_url
+        if username:
+            payload["username"] = username
+
+        if file is not None:
+            try:
+                to_pass = (file.filename, file.open_file(), "application/octet-stream")
+                return self._adapter.execute_webhook(wait=wait, file=to_pass, payload=payload)
+            finally:
+                file.close()
+        elif files is not None:
+            try:
+                to_pass = [
+                    (file.filename, file.open_file(), "application/octet-stream") for file in files
+                ]
+                return self._adapter.execute_webhook(wait=wait, files=to_pass, payload=payload)
+            finally:
+                for file in files:
+                    file.close()
+        else:
+            return self._adapter.execute_webhook(wait=wait, payload=payload)
+
+    def execute(self, *args, **kwargs):
+        """An alias for :meth:`~.Webhook.send`."""
+        return self.send(*args, **kwargs)

docs/Makefile

@@ -14,9 +14,6 @@ help:
 
 .PHONY: help Makefile
 
-init:
-	cd .. && pipenv lock -r --dev > docs/requirements.txt && echo 'git+https://github.com/Rapptz/discord.py@rewrite#egg=discord.py-1.0' >> docs/requirements.txt
-
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

docs/autostart_systemd.rst

@@ -10,7 +10,7 @@ Creating the service file
 
 Create the new service file:
 
-:code:`sudo nano /etc/systemd/system/red@.service`
+:code:`sudo -e /etc/systemd/system/red@.service`
 
 Paste the following and replace all instances of :code:`username` with the username your bot is running under (hopefully not root):
 

docs/cog_customcom.rst

@@ -0,0 +1,109 @@
+.. CustomCommands Cog Reference
+
+============================
+CustomCommands Cog Reference
+============================
+
+------------
+How it works
+------------
+
+CustomCommands allows you to create simple commands for your bot without requiring you to code your own cog for Red.
+
+If the command you attempt to create shares a name with an already loaded command, you cannot overwrite it with this cog.
+
+---------
+Cooldowns
+---------
+
+You can set cooldowns for your custom commands. If a command is on cooldown, it will not be triggered.
+
+You can set cooldowns per member or per channel, or set a cooldown guild-wide. You can also set multiple types of cooldown on a single custom command. All cooldowns must pass before the command will trigger.
+
+------------------
+Context Parameters
+------------------
+
+You can enhance your custom command's response by leaving spaces for the bot to substitute.
+
++-----------+----------------------------------------+
+| Argument  | Substitute                             |
++===========+========================================+
+| {message} | The message the bot is responding to.  |
++-----------+----------------------------------------+
+| {author}  | The user who called the command.       |
++-----------+----------------------------------------+
+| {channel} | The channel the command was called in. |
++-----------+----------------------------------------+
+| {server}  | The server the command was called in.  |
++-----------+----------------------------------------+
+| {guild}   | Same as with {server}.                 |
++-----------+----------------------------------------+
+
+You can further refine the response with dot notation. For example, {author.mention} will mention the user who called the command.
+
+------------------
+Command Parameters
+------------------
+
+You can further enhance your custom command's response by leaving spaces for the user to substitute.
+
+To do this, simply put {#} in the response, replacing # with any number starting with 0. Each number will be replaced with what the user gave the command, in order.
+
+You can refine the response with colon notation. For example, {0:Member} will accept members of the server, and {0:int} will accept a number. If no colon notation is provided, the argument will be returned unchanged.
+
++-----------------+--------------------------------+
+| Argument        | Substitute                     |
++=================+================================+
+| {#:Member}      | A member of your server.       |
++-----------------+--------------------------------+
+| {#:TextChannel} | A text channel in your server. |
++-----------------+--------------------------------+
+| {#:Role}        | A role in your server.         |
++-----------------+--------------------------------+
+| {#:int}         | A whole number.                |
++-----------------+--------------------------------+
+| {#:float}       | A decimal number.              |
++-----------------+--------------------------------+
+| {#:bool}        | True or False.                 |
++-----------------+--------------------------------+
+
+You can specify more than the above with colon notation, but those are the most common.
+
+As with context parameters, you can use dot notation to further refine the response. For example, {0.mention:Member} will mention the Member specified.
+
+----------------
+Example commands
+----------------
+
+Showing your own avatar
+
+.. code-block:: none
+
+    [p]customcom add simple avatar {author.avatar_url}
+    [p]avatar
+        https://cdn.discordapp.com/avatars/133801473317404673/be4c4a4fe47cb3e74c31a0504e7a295e.webp?size=1024
+
+Repeating the user
+
+.. code-block:: none
+
+    [p]customcom add simple say {0}
+    [p]say Pete and Repeat
+        Pete and Repeat
+
+Greeting the specified member
+
+.. code-block:: none
+
+    [p]customcom add simple greet Hello, {0.mention:Member}!
+    [p]greet Twentysix
+        Hello, @Twentysix!
+
+Comparing two text channel's categories
+
+.. code-block:: none
+
+    [p]customcom add simple comparecategory {0.category:TextChannel}  |  {1.category:TextChannel}
+    [p]comparecategory #support #general
+        Red  |  Community

docs/cog_permissions.rst

@@ -8,100 +8,90 @@ Permissions Cog Reference
 How it works
 ------------
 
-When loaded, the permissions cog will allow you
-to define extra custom rules for who can use a command
+When loaded, the permissions cog will allow you to define extra custom rules for who can use a
+command.
 
-If no applicable rules are found, the command will behave as if
-the cog was not loaded.
+If no applicable rules are found, the command will behave normally.
+
+Rules can also be added to cogs, which will affect all commands from that cog. The cog name can be
+found from the help menu.
 
 -------------
 Rule priority
 -------------
 
-Rules set will be checked in the following order
+Rules set for subcommands will take precedence over rules set for the parent commands, which
+lastly take precedence over rules set for the cog. So for example, if a user is denied the Core
+cog, but allowed the ``[p]set token`` command, the user will not be able to use any command in the
+Core cog except for ``[p]set token``.
 
+In terms of scope, global rules will be checked first, then server rules.
 
-    1. Owner level command specific settings
-    2. Owner level cog specific settings
-    3. Server level command specific settings
-    4. Server level cog specific settings
+For each of those, the first rule pertaining to one of the following models will be used:
 
-For each of those, settings have varying priorities (listed below, highest to lowest priority)
+1. User
+2. Voice channel
+3. Text channel
+4. Channel category
+5. Roles, highest to lowest
+6. Server (can only be in global rules)
+7. Default rules
 
-    1. User whitelist
-    2. User blacklist
-    3. Voice Channel whitelist
-    4. Voice Channel blacklist
-    5. Text Channel whitelist
-    6. Text Channel blacklist
-    7. Role settings (see below)
-    8. Server whitelist
-    9. Server blacklist
-    10. Default settings
-
-For the role whitelist and blacklist settings,
-roles will be checked individually in order from highest to lowest role the user has
-Each role will be checked for whitelist, then blacklist. The first role with a setting
-found will be the one used.
+In private messages, only global rules about a user will be checked.
 
 -------------------------
-Setting Rules from a file
+Setting Rules From a File
 -------------------------
 
-The permissions cog can set rules from a yaml file:
-All entries are based on ID. 
-An example of the expected format is shown below.
+The permissions cog can also set, display or update rules with a YAML file with the
+``[p]permissions yaml`` command. Models must be represented by ID. Rules must be ``true`` for
+allow, or ``false`` for deny. Here is an example:
 
 .. code-block:: yaml
 
-    cogs:
+    COG:
       Admin:
-        allow:
-          - 78631113035100160
-        deny:
-          - 96733288462286848
+        78631113035100160: true
+        96733288462286848: false
       Audio:
-        allow: 
-          - 133049272517001216
-        default: deny
-    commands:
+        133049272517001216: true
+        default: false
+    COMMAND:
       cleanup bot:
-        allow:
-          - 78631113035100160
-        default: deny
+        78631113035100160: true
+        default: false
       ping:
-        deny:
-          - 96733288462286848
-        default: allow
+        96733288462286848: false
+        default: true
 
 ----------------------
 Example configurations
 ----------------------
 
-Locking Audio cog to approved server(s) as a bot owner
+Locking the ``[p]play`` command to approved server(s) as a bot owner:
 
 .. code-block:: none
 
-    [p]permissions setglobaldefault Audio deny
-    [p]permissions addglobalrule allow Audio [server ID or name]
+    [p]permissions setglobaldefault play deny
+    [p]permissions addglobalrule allow play [server ID or name]
 
-Locking Audio to specific voice channel(s) as a serverowner or admin:
+Locking the ``[p]play`` command to specific voice channel(s) as a serverowner or admin:
 
 .. code-block:: none
 
-    [p]permissions setguilddefault deny play
-    [p]permissions setguilddefault deny "playlist start"
-    [p]permissions addguildrule allow play [voice channel ID or name]
-    [p]permissions addguildrule allow "playlist start" [voice channel ID or name]
+    [p]permissions setserverdefault deny play
+    [p]permissions setserverdefault deny "playlist start"
+    [p]permissions addserverrule allow play [voice channel ID or name]
+    [p]permissions addserverrule allow "playlist start" [voice channel ID or name]
 
-Allowing extra roles to use cleanup
+Allowing extra roles to use ``[p]cleanup``:
 
 .. code-block:: none
 
-    [p]permissions addguildrule allow Cleanup [role ID]
+    [p]permissions addserverrule allow cleanup [role ID]
 
-Preventing cleanup from being used in channels where message history is important:
+Preventing ``[p]cleanup`` from being used in channels where message history is important:
 
 .. code-block:: none
 
-    [p]permissions addguildrule deny Cleanup [channel ID or mention]
+    [p]permissions addserverrule deny cleanup [channel ID or mention]

docs/conf.py

@@ -39,6 +39,7 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx.ext.doctest",
     "sphinxcontrib.asyncio",
 ]
 
@@ -190,9 +191,23 @@ texinfo_documents = [
 ]
 
 
-# Example configuration for intersphinx: refer to the Python standard library.
+# -- Options for linkcheck builder ----------------------------------------
+
+# A list of regular expressions that match URIs that should not be
+# checked when doing a linkcheck build.
+linkcheck_ignore = [r"https://java.com*"]
+
+
+# -- Options for extensions -----------------------------------------------
+
+# Intersphinx
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3.6", None),
     "dpy": ("https://discordpy.readthedocs.io/en/rewrite/", None),
     "motor": ("https://motor.readthedocs.io/en/stable/", None),
 }
+
+# Doctest
+# If this string is non-empty, all blocks with ``>>>`` in them will be
+# tested, not just the ones explicitly marked with ``.. doctest::``
+doctest_test_doctest_blocks = ""

docs/framework_checks.rst

@@ -0,0 +1,11 @@
+.. _checks:
+
+========================
+Command Check Decorators
+========================
+
+The following are all decorators for commands, which add restrictions to where and when they can be
+run.
+
+.. automodule:: redbot.core.checks
+    :members:

docs/framework_commands.rst

@@ -5,8 +5,9 @@ Commands Package
 ================
 
 This package acts almost identically to :doc:`discord.ext.commands <dpy:ext/commands/api>`; i.e.
-they both have the same attributes. Some of these attributes, however, have been slightly modified,
-as outlined below.
+all of the attributes from discord.py's are also in ours. 
+Some of these attributes, however, have been slightly modified, while others have been added to
+extend functionlities used throughout the bot, as outlined below.
 
 .. autofunction:: redbot.core.commands.command
 
@@ -20,3 +21,6 @@ as outlined below.
 
 .. autoclass:: redbot.core.commands.Context
     :members:
+
+.. automodule:: redbot.core.commands.requires
+    :members: PrivilegeLevel, PermState, Requires

docs/framework_config.rst

@@ -187,6 +187,7 @@ This usage guide will cover the following features:
 
 - :py:meth:`Group.get_raw`
 - :py:meth:`Group.set_raw`
+- :py:meth:`Group.clear_raw`
 
 For this example let's suppose that we're creating a cog that allows users to buy and own multiple pets using
 the built-in Economy credits::
@@ -290,6 +291,37 @@ We're responsible pet owners here, so we've also got to have a way to feed our p
 
             await ctx.send("Your pet is now at {}/100 hunger!".format(new_hunger)
 
+Of course, if we're less than responsible pet owners, there are consequences::
+
+    #continued
+        @commands.command()
+        async def adopt(self, ctx, pet_name: str, *, member: discord.Member):
+            try:
+                pet = await self.conf.user(member).pets.get_raw(pet_name)
+            except KeyError:
+                await ctx.send("That person doesn't own that pet!")
+                return
+
+            hunger = pet.get("hunger")
+            if hunger < 80:
+                await ctx.send("That pet is too well taken care of to be adopted.")
+                return
+
+            await self.conf.user(member).pets.clear_raw(pet_name)
+
+            # this is equivalent to doing the following
+
+            pets = await self.conf.user(member).pets()
+            del pets[pet_name]
+            await self.conf.user(member).pets.set(pets)
+
+            await self.conf.user(ctx.author).pets.set_raw(pet_name, value=pet)
+            await ctx.send(
+                "Your request to adopt this pet has been granted due to "
+                "how poorly it was taken care of."
+            )
+
+
 *************
 V2 Data Usage
 *************
@@ -342,6 +374,21 @@ API Reference
     inside the bot itself! Simply take a peek inside of the :code:`tests/core/test_config.py` file for examples of using
     Config in all kinds of ways.
 
+.. important::
+
+    When getting, setting or clearing values in Config, all keys are casted to `str` for you. This
+    includes keys within a `dict` when one is being set, as well as keys in  nested dictionaries
+    within that `dict`. For example::
+
+        >>> conf = Config.get_conf(self, identifier=999)
+        >>> conf.register_global(foo={})
+        >>> await conf.foo.set_raw(123, value=True)
+        >>> await conf.foo()
+        {'123': True}
+        >>> await conf.foo.set({123: True, 456: {789: False}}
+        >>> await conf.foo()
+        {'123': True, '456': {'789': False}}
+
 .. automodule:: redbot.core.config
 
 Config

docs/framework_utils.rst

@@ -4,6 +4,12 @@
 Utility Functions
 =================
 
+General Utility
+===============
+
+.. automodule:: redbot.core.utils
+    :members: deduplicate_iterables, bounded_gather, bounded_gather_iter
+
 Chat Formatting
 ===============
 
@@ -16,12 +22,18 @@ Embed Helpers
 .. automodule:: redbot.core.utils.embed
     :members:
 
-Menu Helpers
-============
+Reaction Menus
+==============
 
 .. automodule:: redbot.core.utils.menus
     :members:
 
+Event Predicates
+================
+
+.. automodule:: redbot.core.utils.predicates
+    :members:
+
 Mod Helpers
 ===========
 
@@ -38,4 +50,10 @@ Tunnel
 ======
 
 .. automodule:: redbot.core.utils.tunnel
-    :members: Tunnel
+    :members: Tunnel
+
+Common Filters
+==============
+
+.. automodule:: redbot.core.utils.common_filters
+    :members:

docs/guide_cog_creation.rst

@@ -17,8 +17,8 @@ you in the process.
 Getting started
 ---------------
 
-To start off, be sure that you have installed Python 3.6 or higher. Open a terminal or command prompt and type
-:code:`pip install --process-dependency-links -U git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=redbot[test]`
+To start off, be sure that you have installed Python 3.6.2 or higher (3.6.6 or higher on Windows).
+Open a terminal or command prompt and type :code:`pip install -U git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=redbot[test]`
 (note that if you get an error with this, try again but put :code:`python -m` in front of the command
 This will install the latest version of V3.
 
@@ -44,7 +44,7 @@ In that file, place the following code:
 
 .. code-block:: python
 
-    from discord.ext import commands
+    from redbot.core import commands
 
     class Mycog:
         """My custom cog"""

docs/index.rst

@@ -11,13 +11,8 @@ Welcome to Red - Discord Bot's documentation!
     :caption: Installation Guides:
 
     install_windows
-    install_mac
-    install_ubuntu_xenial
-    install_ubuntu_bionic
-    install_debian
-    install_centos
-    install_arch
-    install_raspbian
+    install_linux_mac
+    venv_guide
     cog_dataconverter
     autostart_systemd
 
@@ -25,6 +20,7 @@ Welcome to Red - Discord Bot's documentation!
     :maxdepth: 2
     :caption: Cog Reference:
 
+    cog_customcom
     cog_downloader
     cog_permissions
 
@@ -37,14 +33,15 @@ Welcome to Red - Discord Bot's documentation!
     guide_data_conversion
     framework_bank
     framework_bot
+    framework_checks
     framework_cogmanager
+    framework_commands
     framework_config
     framework_datamanager
     framework_downloader
     framework_events
     framework_i18n
     framework_modlog
-    framework_commands
     framework_rpc
     framework_utils
 

docs/install_arch.rst

@@ -1,55 +0,0 @@
-.. arch install guide
-
-==============================
-Installing Red on Arch Linux
-==============================
-
-.. warning:: For safety reasons, DO NOT install Red with a root user. Instead, make a new one.
-
-:code:`https://wiki.archlinux.org/index.php/Users_and_groups`
-
--------------------------------
-Installing the pre-requirements
--------------------------------
-
-.. code-block:: none
-
-    sudo pacman -Syu python-pip git base-devel jre8-openjdk
-
-------------------
-Installing the bot
-------------------
-
-To install without audio:
-
-:code:`pip3 install -U --process-dependency-links red-discordbot --user`
-
-To install with audio:
-
-:code:`pip3 install -U --process-dependency-links red-discordbot[voice] --user`
-
-To install the development version (without audio):
-
-:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot --user`
-
-To install the development version (with audio):
-
-:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice] --user`
-
-------------------------
-Setting up your instance
-------------------------
-
-Run :code:`redbot-setup` and follow the prompts. It will ask first for where you want to
-store the data (the default is :code:`~/.local/share/Red-DiscordBot`) and will then ask
-for confirmation of that selection. Next, it will ask you to choose your storage backend
-(the default here is JSON). It will then ask for a name for your instance. This can be
-anything as long as it does not contain spaces; however, keep in mind that this is the
-name you will use to run your bot, and so it should be something you can remember.
-
------------
-Running Red
------------
-
-Run :code:`redbot <your instance name>` and run through the initial setup. This will ask for
-your token and a prefix.

docs/install_centos.rst

@@ -1,55 +0,0 @@
-.. centos install guide
-
-==========================
-Installing Red on CentOS 7
-==========================
-
-.. warning:: For safety reasons, DO NOT install Red with a root user. Instead, `make a new one <https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/4/html/Step_by_Step_Guide/s1-starting-create-account.html>`_.
-
----------------------------
-Installing pre-requirements
----------------------------
-
-.. code-block:: none
-
-    yum -y groupinstall development
-    yum -y install https://centos7.iuscommunity.org/ius-release.rpm
-    yum -y install yum-utils wget which python36u python36u-pip python36u-devel openssl-devel libffi-devel git java-1.8.0-openjdk
-
---------------
-Installing Red
---------------
-
-Without audio:
-
-:code:`pip3 install -U --process-dependency-links red-discordbot --user`
-
-With audio:
-
-:code:`pip3 install -U --process-dependency-links red-discordbot[voice] --user`
-
-To install the development version (without audio):
-
-:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot --user`
-
-To install the development version (with audio):
-
-:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice] --user`
-
-----------------------
-Setting up an instance
-----------------------
-
-Run :code:`redbot-setup` and follow the prompts. It will ask first for where you want to
-store the data (the default is :code:`~/.local/share/Red-DiscordBot`) and will then ask
-for confirmation of that selection. Next, it will ask you to choose your storage backend
-(the default here is JSON). It will then ask for a name for your instance. This can be
-anything as long as it does not contain spaces; however, keep in mind that this is the
-name you will use to run your bot, and so it should be something you can remember.
-
------------
-Running Red
------------
-
-Run :code:`redbot <your instance name>` and run through the initial setup. This will ask for
-your token and a prefix.

docs/install_debian.rst

@@ -1,70 +0,0 @@
-.. debian install guide
-
-================================
-Installing Red on Debian Stretch
-================================
-
-.. warning:: For safety reasons, DO NOT install Red with a root user. Instead, `make a new one <https://manpages.debian.org/stretch/adduser/adduser.8.en.html>`_.
-
----------------------------
-Installing pre-requirements
----------------------------
-
-.. code-block:: none
-
-    sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev git unzip default-jre
-    curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash
-
-After that last command, you may see a warning about 'pyenv' not being in the load path. Follow the instructions given to fix that, then close and reopen your shell
-
-Then run the following command:
-
-.. code-block:: none
-
-    CONFIGURE_OPTS=--enable-optimizations pyenv install 3.6.5 -v
-
-This may take a long time to complete.
-
-After that is finished, run:
-
-.. code-block:: none
-
-    pyenv global 3.6.5
-
-------------------
-Installing the bot
-------------------
-
-To install without audio:
-
-:code:`pip3 install -U --process-dependency-links red-discordbot`
-
-To install with audio:
-
-:code:`pip3 install -U --process-dependency-links red-discordbot[voice]`
-
-To install the development version (without audio):
-
-:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot`
-
-To install the development version (with audio):
-
-:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice]`
-
-------------------------
-Setting up your instance
-------------------------
-
-Run :code:`redbot-setup` and follow the prompts. It will ask first for where you want to
-store the data (the default is :code:`~/.local/share/Red-DiscordBot`) and will then ask
-for confirmation of that selection. Next, it will ask you to choose your storage backend
-(the default here is JSON). It will then ask for a name for your instance. This can be
-anything as long as it does not contain spaces; however, keep in mind that this is the
-name you will use to run your bot, and so it should be something you can remember.
-
------------
-Running Red
------------
-
-Run :code:`redbot <your instance name>` and run through the initial setup. This will ask for
-your token and a prefix.

docs/install_linux_mac.rst

@@ -0,0 +1,203 @@
+.. _linux-mac-install-guide:
+
+==============================
+Installing Red on Linux or Mac
+==============================
+
+.. warning::
+
+    For safety reasons, DO NOT install Red with a root user. If you are unsure how to create
+    a new user, see the man page for the ``useradd`` command.
+
+-------------------------------
+Installing the pre-requirements
+-------------------------------
+
+Please install the pre-requirements using the commands listed for your operating system.
+
+The pre-requirements are:
+ - Python 3.6.2 or greater
+ - pip 9.0 or greater
+ - git
+ - Java Runtime Environment 8 or later (for audio support)
+
+~~~~~~~~~~
+Arch Linux
+~~~~~~~~~~
+
+.. code-block:: none
+
+    sudo pacman -Syu python-pip git base-devel jre8-openjdk
+
+~~~~~~~~
+CentOS 7
+~~~~~~~~
+
+.. code-block:: none
+
+    yum -y groupinstall development
+    yum -y install https://centos7.iuscommunity.org/ius-release.rpm
+    yum -y install yum-utils wget which python36u python36u-pip python36u-devel openssl-devel libffi-devel git java-1.8.0-openjdk
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Debian and Raspbian Stretch
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+
+    Audio will not work on Raspberry Pi's **below** 2B. This is a CPU problem and
+    *cannot* be fixed.
+
+We recommend installing pyenv as a method of installing non-native versions of python on
+Debian/Raspbian Stretch. This guide will tell you how. First, run the following commands:
+
+.. code-block:: none
+
+    sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev git unzip default-jre
+    curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash
+
+After that last command, you may see a warning about 'pyenv' not being in the load path. Follow the
+instructions given to fix that, then close and reopen your shell.
+
+Then run the following command:
+
+.. code-block:: none
+
+    CONFIGURE_OPTS=--enable-optimizations pyenv install 3.7.0 -v
+
+This may take a long time to complete.
+
+After that is finished, run:
+
+.. code-block:: none
+
+    pyenv global 3.7.0
+
+Pyenv is now installed and your system should be configured to run Python 3.7.
+
+~~~
+Mac
+~~~
+
+Install Brew: in Finder or Spotlight, search for and open *Terminal*. In the terminal, paste the
+following, then press Enter:
+
+.. code-block:: none
+
+    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+
+After the installation, install the required packages by pasting the commands and pressing enter,
+one-by-one:
+
+.. code-block:: none
+
+    brew install python3 --with-brewed-openssl
+    brew install git
+    brew tap caskroom/versions
+    brew cask install java8
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Ubuntu 18.04 Bionic Beaver
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: none
+
+    sudo apt install python3.6-dev python3-pip build-essential libssl-dev libffi-dev git unzip default-jre -y
+
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Ubuntu 16.04 Xenial Xerus
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We recommend adding the ``deadsnakes`` apt repository to install Python 3.6.2 or greater:
+
+.. code-block:: none
+
+    sudo apt install software-properties-common
+    sudo add-apt-repository ppa:deadsnakes/ppa
+    sudo apt update
+
+Now, install python, pip, git and java with the following commands:
+
+.. code-block:: none
+
+    sudo apt install python3.6-dev build-essential libssl-dev libffi-dev git unzip default-jre wget -y
+    wget https://bootstrap.pypa.io/get-pip.py
+    sudo python3.6 get-pip.py
+
+------------------------------
+Creating a Virtual Environment
+------------------------------
+
+We **strongly** recommend installing Red into a virtual environment. See the section
+`installing-in-virtual-environment`.
+
+.. _installing-red-linux-mac:
+
+--------------
+Installing Red
+--------------
+
+Choose one of the following commands to install Red.
+
+.. note::
+
+    If you're not inside an activated virtual environment, include the ``--user`` flag with all
+    ``pip3`` commands.
+
+To install without audio support:
+
+.. code-block:: none
+
+    pip3 install -U Red-DiscordBot
+
+Or, to install with audio support:
+
+.. code-block:: none
+
+    pip3 install -U Red-DiscordBot[voice]
+
+Or, install with audio and MongoDB support:
+
+.. code-block:: none
+
+    pip3 install -U Red-DiscordBot[voice,mongo]
+
+.. note::
+
+  To install the development version, replace ``Red-DiscordBot`` in the above commands with the
+  following link:
+
+  .. code-block:: none
+
+      git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=Red-DiscordBot
+
+--------------------------
+Setting Up and Running Red
+--------------------------
+
+After installation, set up your instance with the following command:
+
+.. code-block:: none
+
+    redbot-setup
+
+This will set the location where data will be stored, as well as your
+storage backend and the name of the instance (which will be used for
+running the bot).
+
+Once done setting up the instance, run the following command to run Red:
+
+.. code-block:: none
+
+    redbot <your instance name>
+
+It will walk through the initial setup, asking for your token and a prefix.
+
+You may also run Red via the launcher, which allows you to restart the bot
+from discord, and enable auto-restart. You may also update the bot from the
+launcher menu. Use the following command to run the launcher:
+
+.. code-block:: none
+
+    redbot-launcher
+

docs/install_mac.rst

@@ -1,53 +0,0 @@
-.. mac install guide
-
-=====================
-Installing Red on Mac
-=====================
-
----------------------------
-Installing pre-requirements
----------------------------
-
-* Install Brew
-    * In Finder or Spotlight, search for and open terminal. In the window that will open, paste this:
-      :code:`/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
-      and press enter.
-* After the installation, install the required packages by pasting the commands and pressing enter, one-by-one:
-    * :code:`brew install python3 --with-brewed-openssl`
-    * :code:`brew install git`
-    * :code:`brew tap caskroom/versions`
-    * :code:`brew cask install java8`
-
---------------
-Installing Red
---------------
-
-Without audio:
-
-:code:`pip3 install -U --process-dependency-links red-discordbot`
-
-With audio:
-
-:code:`pip3 install -U --process-dependency-links red-discordbot[voice]`
-
-To install the development version (without audio):
-
-:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot`
-
-To install the development version (with audio):
-
-:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice]`
-
-----------------------
-Setting up an instance
-----------------------
-
-To set up an instance, run :code:`redbot-setup` and follow the steps there, providing the requested information
-or accepting the defaults. Keep in mind that the instance name will be the one you use when running the bot, so
-make it something you can remember
-
------------
-Running Red
------------
-
-Run :code:`redbot <your instance name>` and go through the initial setup (it will ask for the token and a prefix).

docs/install_raspbian.rst

@@ -1,72 +0,0 @@
-.. raspbian install guide
-
-==================================
-Installing Red on Raspbian Stretch
-==================================
-
-.. warning:: For safety reasons, DO NOT install Red with a root user. Instead, `make a new one <https://www.raspberrypi.org/documentation/linux/usage/users.md>`_.
-
----------------------------
-Installing pre-requirements
----------------------------
-
-.. code-block:: none
-
-    sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev git unzip default-jre
-    curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash
-
-After that last command, you may see a warning about 'pyenv' not being in the load path. Follow the instructions given to fix that, then close and reopen your shell
-
-Then run the following command:
-
-.. code-block:: none
-
-    CONFIGURE_OPTS=--enable-optimizations pyenv install 3.6.5 -v
-
-This may take a long time to complete.
-
-After that is finished, run:
-
-.. code-block:: none
-
-    pyenv global 3.6.5
-
---------------
-Installing Red
---------------
-
-Without audio:
-
-:code:`pip3 install -U --process-dependency-links red-discordbot --user`
-
-With audio:
-
-:code:`pip3 install -U --process-dependency-links red-discordbot[voice] --user`
-
-To install the development version (without audio):
-
-:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot --user`
-
-To install the development version (with audio):
-
-:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice] --user`
-
-----------------------
-Setting up an instance
-----------------------
-
-Run :code:`redbot-setup` and follow the prompts. It will ask first for where you want to
-store the data (the default is :code:`~/.local/share/Red-DiscordBot`) and will then ask
-for confirmation of that selection. Next, it will ask you to choose your storage backend
-(the default here is JSON). It will then ask for a name for your instance. This can be
-anything as long as it does not contain spaces; however, keep in mind that this is the
-name you will use to run your bot, and so it should be something you can remember.
-
------------
-Running Red
------------
-
-Run :code:`redbot <your instance name>` and run through the initial setup. This will ask for
-your token and a prefix.
-
-.. warning:: Audio will not work on Raspberry Pi's **below** 2B. This is a CPU problem and *cannot* be fixed.

docs/install_ubuntu_bionic.rst

@@ -1,54 +0,0 @@
-.. ubuntu bionic install guide
-
-==============================
-Installing Red on Ubuntu 18.04
-==============================
-
-.. warning:: For safety reasons, DO NOT install Red with a root user. Instead, `make a new one <http://manpages.ubuntu.com/manpages/artful/man8/adduser.8.html>`_.
-
--------------------------------
-Installing the pre-requirements
--------------------------------
-
-.. code-block:: none
-
-    sudo apt install python3.6-dev python3-pip build-essential libssl-dev libffi-dev git unzip default-jre -y
-
-
-------------------
-Installing the bot
-------------------
-
-To install without audio:
-
-:code:`pip3 install -U --process-dependency-links red-discordbot --user`
-
-To install with audio:
-
-:code:`pip3 install -U --process-dependency-links red-discordbot[voice] --user`
-
-To install the development version (without audio):
-
-:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot --user`
-
-To install the development version (with audio):
-
-:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice] --user`
-
-------------------------
-Setting up your instance
-------------------------
-
-Run :code:`redbot-setup` and follow the prompts. It will ask first for where you want to
-store the data (the default is :code:`~/.local/share/Red-DiscordBot`) and will then ask
-for confirmation of that selection. Next, it will ask you to choose your storage backend
-(the default here is JSON). It will then ask for a name for your instance. This can be
-anything as long as it does not contain spaces; however, keep in mind that this is the
-name you will use to run your bot, and so it should be something you can remember.
-
------------
-Running Red
------------
-
-Run :code:`redbot <your instance name>` and run through the initial setup. This will ask for
-your token and a prefix.

docs/install_ubuntu_xenial.rst

@@ -1,59 +0,0 @@
-.. ubuntu xenial install guide
-
-==============================
-Installing Red on Ubuntu 16.04
-==============================
-
-.. warning:: For safety reasons, DO NOT install Red with a root user. Instead, `make a new one <http://manpages.ubuntu.com/manpages/artful/man8/adduser.8.html>`_.
-
--------------------------------
-Installing the pre-requirements
--------------------------------
-
-.. code-block:: none
-
-    sudo apt install software-properties-common
-    sudo add-apt-repository ppa:deadsnakes/ppa
-    sudo apt update
-    sudo apt install python3.6-dev build-essential libssl-dev libffi-dev git unzip default-jre wget -y
-    wget https://bootstrap.pypa.io/get-pip.py
-    sudo python3.6 get-pip.py
-
-
-------------------
-Installing the bot
-------------------
-
-To install without audio:
-
-:code:`pip3.6 install -U --process-dependency-links red-discordbot --user`
-
-To install with audio:
-
-:code:`pip3.6 install -U --process-dependency-links red-discordbot[voice] --user`
-
-To install the development version (without audio):
-
-:code:`pip3.6 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot --user`
-
-To install the development version (with audio):
-
-:code:`pip3.6 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice] --user`
-
-------------------------
-Setting up your instance
-------------------------
-
-Run :code:`redbot-setup` and follow the prompts. It will ask first for where you want to
-store the data (the default is :code:`~/.local/share/Red-DiscordBot`) and will then ask
-for confirmation of that selection. Next, it will ask you to choose your storage backend
-(the default here is JSON). It will then ask for a name for your instance. This can be
-anything as long as it does not contain spaces; however, keep in mind that this is the
-name you will use to run your bot, and so it should be something you can remember.
-
------------
-Running Red
------------
-
-Run :code:`redbot <your instance name>` and run through the initial setup. This will ask for
-your token and a prefix.

docs/install_windows.rst

@@ -1,4 +1,4 @@
-.. windows installation docs
+.. _windows-install-guide:
 
 =========================
 Installing Red on Windows
@@ -8,7 +8,7 @@ Installing Red on Windows
 Needed Software
 ---------------
 
-* `Python <https://python.org/downloads/>`_ - Red needs Python 3.6
+* `Python <https://www.python.org/downloads/>`_ - Red needs Python 3.6.6 or greater on Windows
 
 .. note:: Please make sure that the box to add Python to PATH is CHECKED, otherwise
           you may run into issues when trying to run Red
@@ -21,23 +21,74 @@ Needed Software
 
 .. attention:: Please choose the "Windows Online" installer
 
+.. _installing-red-windows:
+
 --------------
 Installing Red
 --------------
 
 1. Open a command prompt (open Start, search for "command prompt", then click it)
-2. Run the appropriate command, depending on if you want audio or not
+2. Create and activate a virtual environment (strongly recommended), see the section `using-venv`
+3. Run **one** of the following commands, depending on what extras you want installed
 
-  * No audio: :code:`python -m pip install -U --process-dependency-links Red-DiscordBot`
-  * Audio: :code:`python -m pip install -U --process-dependency-links Red-DiscordBot[voice]`
-  * Development version (without audio): :code:`python -m pip install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot`
-  * Development version (with audio): :code:`python -m pip install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice]`
+  .. note::
 
-3. Once that has completed, run :code:`redbot-setup` to set up your instance
+      If you're not inside an activated virtual environment, include the ``--user`` flag with all
+      ``pip`` commands.
 
-  * This will set the location where data will be stored, as well as your
-    storage backend and the name of the instance (which will be used for
-    running the bot)
+  * No audio:
 
-4. Once done setting up the instance, run :code:`redbot <your instance name>` to run Red.
-   It will walk through the initial setup, asking for your token and a prefix
+    .. code-block:: none
+
+        python -m pip install -U Red-DiscordBot
+
+  * With audio:
+
+    .. code-block:: none
+
+        python -m pip install -U Red-DiscordBot[voice]
+
+  * With audio and MongoDB support:
+
+    .. code-block:: none
+
+        python -m pip install -U Red-DiscordBot[voice,mongo]
+
+  .. note::
+
+      To install the development version, replace ``Red-DiscordBot`` in the above commands with the
+      following link:
+
+      .. code-block:: none
+
+          git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=Red-DiscordBot
+
+--------------------------
+Setting Up and Running Red
+--------------------------
+
+After installation, set up your instance with the following command:
+
+.. code-block:: none
+
+    redbot-setup
+
+This will set the location where data will be stored, as well as your
+storage backend and the name of the instance (which will be used for
+running the bot).
+
+Once done setting up the instance, run the following command to run Red:
+
+.. code-block:: none
+
+    redbot <your instance name>
+
+It will walk through the initial setup, asking for your token and a prefix.
+
+You may also run Red via the launcher, which allows you to restart the bot
+from discord, and enable auto-restart. You may also update the bot from the
+launcher menu. Use the following command to run the launcher:
+
+.. code-block:: none
+
+    redbot-launcher

docs/requirements.txt

@@ -1,37 +0,0 @@
--i https://pypi.org/simple
-alabaster==0.7.10
-appdirs==1.4.3
-atomicwrites==1.1.5
-attrs==18.1.0
-babel==2.6.0
-black==18.6b2
-certifi==2018.4.16
-chardet==3.0.4
-click==6.7
-docutils==0.14
-idna==2.6
-imagesize==1.0.0
-jinja2==2.10
-markupsafe==1.0
-more-itertools==4.2.0
-packaging==17.1
-pluggy==0.6.0
-py==1.5.3
-pygments==2.2.0
-pyparsing==2.2.0
-pytest-asyncio==0.8.0
-pytest==3.6.1
-pytz==2018.4
-requests==2.18.4
-six==1.11.0
-snowballstemmer==1.2.1
-sphinx-rtd-theme==0.4.0
-sphinx==1.7.5
-sphinxcontrib-asyncio==0.2.0
-sphinxcontrib-websupport==1.1.0
-toml==0.9.4
-tox==3.0.0
-urllib3==1.22
-virtualenv==16.0.0
-yarl==0.18.0
-git+https://github.com/Rapptz/discord.py@7eb918b19e3e60b56eb9039eb267f8f3477c5e17#egg=discord.py-1.0

docs/venv_guide.rst

@@ -0,0 +1,132 @@
+.. _installing-in-virtual-environment:
+
+=======================================
+Installing Red in a Virtual Environment
+=======================================
+Virtual environments allow you to isolate red's library dependencies, cog dependencies and python
+binaries from the rest of your system. It is strongly recommended you use this if you use python
+for more than just Red.
+
+.. _using-venv:
+
+--------------
+Using ``venv``
+--------------
+This is the quickest way to get your virtual environment up and running, as `venv` is shipped with
+python.
+
+First, choose a directory where you would like to create your virtual environment. It's a good idea
+to keep it in a location which is easy to type out the path to. From now, we'll call it
+``path/to/venv/`` (or ``path\to\venv\`` on Windows).
+
+~~~~~~~~~~~~~~~~~~~~~~~~
+``venv`` on Linux or Mac
+~~~~~~~~~~~~~~~~~~~~~~~~
+Create your virtual environment with the following command::
+
+    python3 -m venv path/to/venv/
+
+And activate it with the following command::
+
+    source path/to/venv/bin/activate
+
+.. important::
+
+    You must activate the virtual environment with the above command every time you open a new
+    shell to run, install or update Red.
+
+Continue reading `below <after-activating-virtual-environment>`.
+
+~~~~~~~~~~~~~~~~~~~
+``venv`` on Windows
+~~~~~~~~~~~~~~~~~~~
+Create your virtual environment with the following command::
+
+    python -m venv path\to\venv\
+
+And activate it with the following command::
+
+    path\to\venv\Scripts\activate.bat
+
+.. important::
+
+    You must activate the virtual environment with the above command every time you open a new
+    Command Prompt to run, install or update Red.
+
+Continue reading `below <after-activating-virtual-environment>`.
+
+.. _using-pyenv-virtualenv:
+
+--------------------------
+Using ``pyenv virtualenv``
+--------------------------
+
+.. note::
+
+    This is for non-Windows users only.
+
+Using ``pyenv virtualenv`` saves you the headache of remembering where you installed your virtual
+environments. If you haven't already, install pyenv with `pyenv-installer`_.
+
+First, ensure your pyenv interpreter is set to python 3.6.2 or greater with the following command::
+
+    pyenv version
+
+Now, create a virtual environment with the following command::
+
+    pyenv virtualenv <name>
+
+Replace ``<name>`` with whatever you like. If you forget what you named it, use the command ``pyenv
+versions``.
+
+Now activate your virtualenv with the following command::
+
+    pyenv shell <name>
+
+.. important::
+
+    You must activate the virtual environment with the above command every time you open a new
+    shell to run, install or update Red.
+
+Continue reading `below <after-activating-virtual-environment>`.
+
+.. _pyenv-installer: https://github.com/pyenv/pyenv-installer/blob/master/README.rst
+
+----
+
+.. _after-activating-virtual-environment:
+
+Once activated, your ``PATH`` environment variable will be modified to use the virtual
+environment's python executables, as well as other executables like ``pip``.
+
+From here, install Red using the commands listed on your installation guide (`Windows
+<installing-red-windows>` or `Non-Windows <installing-red-linux-mac>`).
+
+.. note::
+
+    The alternative to activating the virtual environment each time you open a new shell is to
+    provide the full path to the executable. This will automatically use the virtual environment's
+    python interpreter and installed libraries.
+
+--------------------------------------------
+Virtual Environments with Multiple Instances
+--------------------------------------------
+If you are running multiple instances of Red on the same machine, you have the option of either
+using the same virtual environment for all of them, or creating separate ones.
+
+.. note::
+
+    This only applies for multiple instances of V3. If you are running a V2 instance as well,
+    You **must** use separate virtual environments.
+
+The advantages of using a *single* virtual environment for all of your V3 instances are:
+
+- When updating Red, you will only need to update it once for all instances (however you will still need to restart all instances for the changes to take effect)
+- It will save space on your hard drive
+
+On the other hand, you may wish to update each of your instances individually.
+
+.. important::
+
+    Windows users with multiple instances should create *separate* virtual environments, as
+    updating multiple running instances at once is likely to cause errors.

generate_strings.py

@@ -1,37 +0,0 @@
-#!/usr/bin/env python3
-import subprocess
-import os
-import sys
-
-
-def main():
-    interpreter = sys.executable
-    print(interpreter)
-    root_dir = os.getcwd()
-    cogs = [i for i in os.listdir("redbot/cogs") if os.path.isdir(os.path.join("redbot/cogs", i))]
-    for d in cogs:
-        if "locales" in os.listdir(os.path.join("redbot/cogs", d)):
-            os.chdir(os.path.join("redbot/cogs", d, "locales"))
-            if "regen_messages.py" not in os.listdir(os.getcwd()):
-                print(
-                    f"Directory 'locales' exists for {d} but no 'regen_messages.py' is available!"
-                )
-                return 1
-            else:
-                print("Running 'regen_messages.py' for {}".format(d))
-                retval = subprocess.run([interpreter, "regen_messages.py"])
-                if retval.returncode != 0:
-                    return 1
-                os.chdir(root_dir)
-    os.chdir("redbot/core/locales")
-    print("Running 'regen_messages.py' for core")
-    retval = subprocess.run([interpreter, "regen_messages.py"])
-    if retval.returncode != 0:
-        return 1
-    os.chdir(root_dir)
-    subprocess.run(["crowdin", "upload"])
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

make.bat

@@ -1,6 +1,6 @@
 @echo off
 
-if "%1"=="" goto help
+if [%1] == [] goto help
 
 REM This allows us to expand variables at execution
 setlocal ENABLEDELAYEDEXPANSION
@@ -14,13 +14,24 @@ for /F "tokens=* USEBACKQ" %%A in (`git ls-files "*.py"`) do (
 goto %1
 
 :reformat
-black -l 99 !PYFILES!
+black -l 99 -N !PYFILES!
 exit /B %ERRORLEVEL%
 
 :stylecheck
-black -l 99 --check !PYFILES!
+black -l 99 -N --check !PYFILES!
 exit /B %ERRORLEVEL%
 
+:update_vendor
+if [%REF%] == [] (
+    set REF2="rewrite"
+) else (
+    set REF2=%REF%
+)
+pip install --upgrade --no-deps -t . https://github.com/Rapptz/discord.py/archive/!REF2!.tar.gz#egg=discord.py
+del /S /Q "discord.py*-info"
+for /F %%i in ('dir /S /B discord.py*.egg-info') do rmdir /S /Q %%i
+goto reformat
+
 :help
 echo Usage:
 echo   make ^<command^>
@@ -28,3 +39,5 @@ echo.
 echo Commands:
 echo   reformat                   Reformat all .py files being tracked by git.
 echo   stylecheck                 Check which tracked .py files need reformatting.
+echo   update_vendor              Update vendored discord.py library to %%REF%%, which defaults to
+echo                              "rewrite"

redbot/__init__.py

@@ -1,14 +1,34 @@
 import sys
+import warnings
 import discord
-from colorama import init, Back
+import colorama
 
-init()
 # Let's do all the dumb version checking in one place.
+if sys.platform == "win32":
+    # Due to issues with ProactorEventLoop prior to 3.6.6 (bpo-26819)
+    MIN_PYTHON_VERSION = (3, 6, 6)
+else:
+    MIN_PYTHON_VERSION = (3, 6, 2)
+
+if sys.version_info < MIN_PYTHON_VERSION:
+    print(
+        f"Python {'.'.join(map(str, MIN_PYTHON_VERSION))} is required to run Red, but you have "
+        f"{sys.version}! Please update Python."
+    )
+    sys.exit(1)
 
 if discord.version_info.major < 1:
     print(
         "You are not running the rewritten version of discord.py.\n\n"
-        "In order to use Red v3 you MUST be running d.py version"
-        " >= 1.0.0."
+        "In order to use Red V3 you MUST be running d.py version "
+        "1.0.0 or greater."
     )
     sys.exit(1)
+
+
+colorama.init()
+
+# Filter fuzzywuzzy slow sequence matcher warning
+warnings.filterwarnings("ignore", module=r"fuzzywuzzy.*")
+# Prevent discord PyNaCl missing warning
+discord.voice_client.VoiceClient.warn_nacl = False

redbot/__main__.py

@@ -19,6 +19,18 @@ import logging.handlers
 import logging
 import os
 
+# Let's not force this dependency, uvloop is much faster on cpython
+if sys.implementation.name == "cpython":
+    try:
+        import uvloop
+    except ImportError:
+        pass
+    else:
+        asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
+
+if sys.platform == "win32":
+    asyncio.set_event_loop(asyncio.ProactorEventLoop())
+
 
 #
 #               Red - Discord Bot v3
@@ -51,7 +63,7 @@ def init_loggers(cli_flags):
         os.environ["PYTHONASYNCIODEBUG"] = "1"
         logger.setLevel(logging.DEBUG)
     else:
-        logger.setLevel(logging.WARNING)
+        logger.setLevel(logging.INFO)
 
     from redbot.core.data_manager import core_data_path
 
@@ -99,7 +111,7 @@ def list_instances():
 
 
 def main():
-    description = "Red - Version {}".format(__version__)
+    description = "Red V3"
     cli_flags = parse_cli_flags(sys.argv[1:])
     if cli_flags.list_instances:
         list_instances()
@@ -149,14 +161,9 @@ def main():
     if tmp_data["enable_sentry"]:
         red.enable_sentry()
     try:
-        loop.run_until_complete(red.start(token, bot=not cli_flags.not_bot))
+        loop.run_until_complete(red.start(token, bot=True))
     except discord.LoginFailure:
-        log.critical(
-            "This token doesn't seem to be valid. If it belongs to "
-            "a user account, remember that the --not-bot flag "
-            "must be used. For self-bot functionalities instead, "
-            "--self-bot"
-        )
+        log.critical("This token doesn't seem to be valid.")
         db_token = loop.run_until_complete(red.db.token())
         if db_token and not cli_flags.no_prompt:
             print("\nDo you want to reset the token? (y/n)")
@@ -176,7 +183,7 @@ def main():
         gathered = asyncio.gather(*pending, loop=red.loop, return_exceptions=True)
         gathered.cancel()
         try:
-            red.rpc.server.close()
+            loop.run_until_complete(red.rpc.close())
         except AttributeError:
             pass
 

redbot/cogs/admin/admin.py

@@ -1,45 +1,52 @@
+import logging
 from typing import Tuple
 
 import discord
 
 from redbot.core import Config, checks, commands
-
-import logging
-
+from redbot.core.i18n import Translator, cog_i18n
 from redbot.core.utils.chat_formatting import box
 from .announcer import Announcer
 from .converters import MemberDefaultAuthor, SelfRole
 
 log = logging.getLogger("red.admin")
 
-GENERIC_FORBIDDEN = (
+T_ = Translator("Admin", __file__)
+
+_ = lambda s: s
+GENERIC_FORBIDDEN = _(
     "I attempted to do something that Discord denied me permissions for."
     " Your command failed to successfully complete."
 )
 
-HIERARCHY_ISSUE = (
+HIERARCHY_ISSUE = _(
     "I tried to add {role.name} to {member.display_name} but that role"
     " is higher than my highest role in the Discord hierarchy so I was"
     " unable to successfully add it. Please give me a higher role and "
     "try again."
 )
 
-USER_HIERARCHY_ISSUE = (
+USER_HIERARCHY_ISSUE = _(
     "I tried to add {role.name} to {member.display_name} but that role"
     " is higher than your highest role in the Discord hierarchy so I was"
     " unable to successfully add it. Please get a higher role and "
     "try again."
 )
 
-RUNNING_ANNOUNCEMENT = (
+RUNNING_ANNOUNCEMENT = _(
     "I am already announcing something. If you would like to make a"
     " different announcement please use `{prefix}announce cancel`"
     " first."
 )
+_ = T_
 
 
-class Admin:
+@cog_i18n(_)
+class Admin(commands.Cog):
+    """A collection of server administration utilities."""
+
     def __init__(self, config=Config):
+        super().__init__()
         self.conf = config.get_conf(self, 8237492837454039, force_registration=True)
 
         self.conf.register_global(serverlocked=False)
@@ -97,13 +104,14 @@ class Admin:
             await member.add_roles(role)
         except discord.Forbidden:
             if not self.pass_hierarchy_check(ctx, role):
-                await self.complain(ctx, HIERARCHY_ISSUE, role=role, member=member)
+                await self.complain(ctx, T_(HIERARCHY_ISSUE), role=role, member=member)
             else:
-                await self.complain(ctx, GENERIC_FORBIDDEN)
+                await self.complain(ctx, T_(GENERIC_FORBIDDEN))
         else:
             await ctx.send(
-                "I successfully added {role.name} to"
-                " {member.display_name}".format(role=role, member=member)
+                _("I successfully added {role.name} to {member.display_name}").format(
+                    role=role, member=member
+                )
             )
 
     async def _removerole(self, ctx: commands.Context, member: discord.Member, role: discord.Role):
@@ -111,13 +119,14 @@ class Admin:
             await member.remove_roles(role)
         except discord.Forbidden:
             if not self.pass_hierarchy_check(ctx, role):
-                await self.complain(ctx, HIERARCHY_ISSUE, role=role, member=member)
+                await self.complain(ctx, T_(HIERARCHY_ISSUE), role=role, member=member)
             else:
-                await self.complain(ctx, GENERIC_FORBIDDEN)
+                await self.complain(ctx, T_(GENERIC_FORBIDDEN))
         else:
             await ctx.send(
-                "I successfully removed {role.name} from"
-                " {member.display_name}".format(role=role, member=member)
+                _("I successfully removed {role.name} from {member.display_name}").format(
+                    role=role, member=member
+                )
             )
 
     @commands.command()
@@ -126,8 +135,8 @@ class Admin:
     async def addrole(
         self, ctx: commands.Context, rolename: discord.Role, *, user: MemberDefaultAuthor = None
     ):
-        """
-        Adds a role to a user.
+        """Add a role to a user.
+
         If user is left blank it defaults to the author of the command.
         """
         if user is None:
@@ -136,7 +145,7 @@ class Admin:
             # noinspection PyTypeChecker
             await self._addrole(ctx, user, rolename)
         else:
-            await self.complain(ctx, USER_HIERARCHY_ISSUE, member=ctx.author)
+            await self.complain(ctx, T_(USER_HIERARCHY_ISSUE), member=ctx.author, role=rolename)
 
     @commands.command()
     @commands.guild_only()
@@ -144,8 +153,8 @@ class Admin:
     async def removerole(
         self, ctx: commands.Context, rolename: discord.Role, *, user: MemberDefaultAuthor = None
     ):
-        """
-        Removes a role from a user.
+        """Remove a role from a user.
+
         If user is left blank it defaults to the author of the command.
         """
         if user is None:
@@ -154,50 +163,54 @@ class Admin:
             # noinspection PyTypeChecker
             await self._removerole(ctx, user, rolename)
         else:
-            await self.complain(ctx, USER_HIERARCHY_ISSUE)
+            await self.complain(ctx, T_(USER_HIERARCHY_ISSUE))
 
     @commands.group()
     @commands.guild_only()
     @checks.admin_or_permissions(manage_roles=True)
     async def editrole(self, ctx: commands.Context):
-        """Edits roles settings"""
+        """Edit role settings."""
         pass
 
     @editrole.command(name="colour", aliases=["color"])
     async def editrole_colour(
         self, ctx: commands.Context, role: discord.Role, value: discord.Colour
     ):
-        """Edits a role's colour
+        """Edit a role's colour.
 
         Use double quotes if the role contains spaces.
         Colour must be in hexadecimal format.
-        \"http://www.w3schools.com/colors/colors_picker.asp\"
+        [Online colour picker](http://www.w3schools.com/colors/colors_picker.asp)
+
         Examples:
-        !editrole colour \"The Transistor\" #ff0000
-        !editrole colour Test #ff9900"""
+            `[p]editrole colour "The Transistor" #ff0000`
+            `[p]editrole colour Test #ff9900`
+        """
         author = ctx.author
         reason = "{}({}) changed the colour of role '{}'".format(author.name, author.id, role.name)
 
         if not self.pass_user_hierarchy_check(ctx, role):
-            await self.complain(ctx, USER_HIERARCHY_ISSUE)
+            await self.complain(ctx, T_(USER_HIERARCHY_ISSUE))
             return
 
         try:
             await role.edit(reason=reason, color=value)
         except discord.Forbidden:
-            await self.complain(ctx, GENERIC_FORBIDDEN)
+            await self.complain(ctx, T_(GENERIC_FORBIDDEN))
         else:
             log.info(reason)
-            await ctx.send("Done.")
+            await ctx.send(_("Done."))
 
     @editrole.command(name="name")
     @checks.admin_or_permissions(administrator=True)
     async def edit_role_name(self, ctx: commands.Context, role: discord.Role, *, name: str):
-        """Edits a role's name
+        """Edit a role's name.
 
         Use double quotes if the role or the name contain spaces.
+
         Examples:
-        !editrole name \"The Transistor\" Test"""
+            `[p]editrole name \"The Transistor\" Test`
+        """
         author = ctx.message.author
         old_name = role.name
         reason = "{}({}) changed the name of role '{}' to '{}'".format(
@@ -205,73 +218,74 @@ class Admin:
         )
 
         if not self.pass_user_hierarchy_check(ctx, role):
-            await self.complain(ctx, USER_HIERARCHY_ISSUE)
+            await self.complain(ctx, T_(USER_HIERARCHY_ISSUE))
             return
 
         try:
             await role.edit(reason=reason, name=name)
         except discord.Forbidden:
-            await self.complain(ctx, GENERIC_FORBIDDEN)
+            await self.complain(ctx, T_(GENERIC_FORBIDDEN))
         else:
             log.info(reason)
-            await ctx.send("Done.")
+            await ctx.send(_("Done."))
 
     @commands.group(invoke_without_command=True)
     @checks.is_owner()
     async def announce(self, ctx: commands.Context, *, message: str):
-        """
-        Announces a message to all servers the bot is in.
-        """
+        """Announce a message to all servers the bot is in."""
         if not self.is_announcing():
             announcer = Announcer(ctx, message, config=self.conf)
             announcer.start()
 
             self.__current_announcer = announcer
 
-            await ctx.send("The announcement has begun.")
+            await ctx.send(_("The announcement has begun."))
         else:
             prefix = ctx.prefix
-            await self.complain(ctx, RUNNING_ANNOUNCEMENT, prefix=prefix)
+            await self.complain(ctx, T_(RUNNING_ANNOUNCEMENT), prefix=prefix)
 
     @announce.command(name="cancel")
     @checks.is_owner()
     async def announce_cancel(self, ctx):
-        """
-        Cancels a running announce.
-        """
+        """Cancel a running announce."""
         try:
             self.__current_announcer.cancel()
         except AttributeError:
             pass
 
-        await ctx.send("The current announcement has been cancelled.")
+        await ctx.send(_("The current announcement has been cancelled."))
 
     @announce.command(name="channel")
     @commands.guild_only()
     @checks.guildowner_or_permissions(administrator=True)
     async def announce_channel(self, ctx, *, channel: discord.TextChannel = None):
-        """
-        Changes the channel on which the bot makes announcements.
-        """
+        """Change the channel to which the bot makes announcements."""
         if channel is None:
             channel = ctx.channel
         await self.conf.guild(ctx.guild).announce_channel.set(channel.id)
 
-        await ctx.send("The announcement channel has been set to {}".format(channel.mention))
+        await ctx.send(
+            _("The announcement channel has been set to {channel.mention}").format(channel=channel)
+        )
 
     @announce.command(name="ignore")
     @commands.guild_only()
     @checks.guildowner_or_permissions(administrator=True)
     async def announce_ignore(self, ctx):
-        """
-        Toggles whether the announcements will ignore the current server.
-        """
+        """Toggle announcements being enabled this server."""
         ignored = await self.conf.guild(ctx.guild).announce_ignore()
         await self.conf.guild(ctx.guild).announce_ignore.set(not ignored)
 
-        verb = "will" if ignored else "will not"
-
-        await ctx.send(f"The server {ctx.guild.name} {verb} receive announcements.")
+        if ignored:  # Keeping original logic....
+            await ctx.send(
+                _("The server {guild.name} will receive announcements.").format(guild=ctx.guild)
+            )
+        else:
+            await ctx.send(
+                _("The server {guild.name} will not receive announcements.").format(
+                    guild=ctx.guild
+                )
+            )
 
     async def _valid_selfroles(self, guild: discord.Guild) -> Tuple[discord.Role]:
         """
@@ -294,8 +308,9 @@ class Admin:
     @commands.guild_only()
     @commands.group(invoke_without_command=True)
     async def selfrole(self, ctx: commands.Context, *, selfrole: SelfRole):
-        """
-        Add a role to yourself that server admins have configured as user settable.
+        """Add a role to yourself.
+
+        Server admins must have configured the role as user settable.
 
         NOTE: The role is case sensitive!
         """
@@ -304,8 +319,7 @@ class Admin:
 
     @selfrole.command(name="remove")
     async def selfrole_remove(self, ctx: commands.Context, *, selfrole: SelfRole):
-        """
-        Removes a selfrole from yourself.
+        """Remove a selfrole from yourself.
 
         NOTE: The role is case sensitive!
         """
@@ -315,8 +329,7 @@ class Admin:
     @selfrole.command(name="add")
     @checks.admin_or_permissions(manage_roles=True)
     async def selfrole_add(self, ctx: commands.Context, *, role: discord.Role):
-        """
-        Add a role to the list of available selfroles.
+        """Add a role to the list of available selfroles.
 
         NOTE: The role is case sensitive!
         """
@@ -324,20 +337,19 @@ class Admin:
             if role.id not in curr_selfroles:
                 curr_selfroles.append(role.id)
 
-        await ctx.send("The selfroles list has been successfully modified.")
+        await ctx.send(_("The selfroles list has been successfully modified."))
 
     @selfrole.command(name="delete")
     @checks.admin_or_permissions(manage_roles=True)
     async def selfrole_delete(self, ctx: commands.Context, *, role: SelfRole):
-        """
-        Removes a role from the list of available selfroles.
+        """Remove a role from the list of available selfroles.
 
         NOTE: The role is case sensitive!
         """
         async with self.conf.guild(ctx.guild).selfroles() as curr_selfroles:
             curr_selfroles.remove(role.id)
 
-        await ctx.send("The selfroles list has been successfully modified.")
+        await ctx.send(_("The selfroles list has been successfully modified."))
 
     @selfrole.command(name="list")
     async def selfrole_list(self, ctx: commands.Context):
@@ -347,7 +359,7 @@ class Admin:
         selfroles = await self._valid_selfroles(ctx.guild)
         fmt_selfroles = "\n".join(["+ " + r.name for r in selfroles])
 
-        msg = "Available Selfroles:\n{}".format(fmt_selfroles)
+        msg = _("Available Selfroles:\n{selfroles}").format(selfroles=fmt_selfroles)
         await ctx.send(box(msg, "diff"))
 
     async def _serverlock_check(self, guild: discord.Guild) -> bool:
@@ -364,15 +376,14 @@ class Admin:
     @commands.command()
     @checks.is_owner()
     async def serverlock(self, ctx: commands.Context):
-        """
-        Locks a bot to its current servers only.
-        """
+        """Lock a bot to its current servers only."""
         serverlocked = await self.conf.serverlocked()
         await self.conf.serverlocked.set(not serverlocked)
 
-        verb = "is now" if not serverlocked else "is no longer"
-
-        await ctx.send("The bot {} serverlocked.".format(verb))
+        if serverlocked:
+            await ctx.send(_("The bot is no longer serverlocked."))
+        else:
+            await ctx.send(_("The bot is now serverlocked."))
 
     # region Event Handlers
     async def on_guild_join(self, guild: discord.Guild):

redbot/cogs/admin/announcer.py

@@ -2,6 +2,9 @@ import asyncio
 
 import discord
 from redbot.core import commands
+from redbot.core.i18n import Translator
+
+_ = Translator("Announcer", __file__)
 
 
 class Announcer:
@@ -63,7 +66,9 @@ class Announcer:
             try:
                 await channel.send(self.message)
             except discord.Forbidden:
-                await bot_owner.send("I could not announce to server: {}".format(g.id))
+                await bot_owner.send(
+                    _("I could not announce to server: {server.id}").format(server=g)
+                )
             await asyncio.sleep(0.5)
 
         self.active = False

redbot/cogs/admin/converters.py

@@ -1,5 +1,8 @@
 import discord
 from redbot.core import commands
+from redbot.core.i18n import Translator
+
+_ = Translator("AdminConverters", __file__)
 
 
 class MemberDefaultAuthor(commands.Converter):
@@ -19,7 +22,7 @@ class SelfRole(commands.Converter):
     async def convert(self, ctx: commands.Context, arg: str) -> discord.Role:
         admin = ctx.command.instance
         if admin is None:
-            raise commands.BadArgument("Admin is not loaded.")
+            raise commands.BadArgument(_("The Admin cog is not loaded."))
 
         conf = admin.conf
         selfroles = await conf.guild(ctx.guild).selfroles()
@@ -28,5 +31,5 @@ class SelfRole(commands.Converter):
         role = await role_converter.convert(ctx, arg)
 
         if role.id not in selfroles:
-            raise commands.BadArgument("The provided role is not a valid selfrole.")
+            raise commands.BadArgument(_("The provided role is not a valid selfrole."))
         return role

redbot/cogs/admin/locales/messages.pot

@@ -1,17 +0,0 @@
-# SOME DESCRIPTIVE TITLE.
-# Copyright (C) YEAR ORGANIZATION
-# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
-#
-msgid ""
-msgstr ""
-"Project-Id-Version: PACKAGE VERSION\n"
-"POT-Creation-Date: 2018-02-18 14:42+AKST\n"
-"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
-"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
-"Language-Team: LANGUAGE <LL@li.org>\n"
-"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=CHARSET\n"
-"Content-Transfer-Encoding: ENCODING\n"
-"Generated-By: pygettext.py 1.5\n"
-
-

redbot/cogs/admin/locales/regen_messages.py

@@ -1,11 +0,0 @@
-import subprocess
-
-TO_TRANSLATE = ["../admin.py"]
-
-
-def regen_messages():
-    subprocess.run(["pygettext", "-n"] + TO_TRANSLATE)
-
-
-if __name__ == "__main__":
-    regen_messages()

redbot/cogs/alias/alias.py

@@ -1,6 +1,6 @@
 from copy import copy
 from re import search
-from typing import Generator, Tuple, Iterable
+from typing import Generator, Tuple, Iterable, Optional
 
 import discord
 from redbot.core import Config, commands, checks
@@ -14,16 +14,15 @@ _ = Translator("Alias", __file__)
 
 
 @cog_i18n(_)
-class Alias:
-    """
-    Alias
-    
-    Aliases are per server shortcuts for commands. They
-        can act as both a lambda (storing arguments for repeated use)
-        or as simply a shortcut to saying "x y z".
-    
+class Alias(commands.Cog):
+    """Create aliases for commands.
+
+    Aliases are alternative names shortcuts for commands. They
+    can act as both a lambda (storing arguments for repeated use)
+    or as simply a shortcut to saying "x y z".
+
     When run, aliases will accept any additional arguments
-        and append them to the stored alias
+    and append them to the stored alias.
     """
 
     default_global_settings = {"entries": []}
@@ -31,6 +30,7 @@ class Alias:
     default_guild_settings = {"enabled": False, "entries": []}  # Going to be a list of dicts
 
     def __init__(self, bot: Red):
+        super().__init__()
         self.bot = bot
         self._aliases = Config.get_conf(self, 8927348724)
 
@@ -53,10 +53,13 @@ class Alias:
         return (AliasEntry.from_json(d, bot=self.bot) for d in (await self._aliases.entries()))
 
     async def is_alias(
-        self, guild: discord.Guild, alias_name: str, server_aliases: Iterable[AliasEntry] = ()
-    ) -> (bool, AliasEntry):
+        self,
+        guild: Optional[discord.Guild],
+        alias_name: str,
+        server_aliases: Iterable[AliasEntry] = (),
+    ) -> Tuple[bool, Optional[AliasEntry]]:
 
-        if not server_aliases:
+        if not server_aliases and guild is not None:
             server_aliases = await self.unloaded_aliases(guild)
 
         global_aliases = await self.unloaded_global_aliases()
@@ -173,32 +176,28 @@ class Alias:
     @commands.group()
     @commands.guild_only()
     async def alias(self, ctx: commands.Context):
-        """Manage per-server aliases for commands"""
+        """Manage command aliases."""
         pass
 
     @alias.group(name="global")
     async def global_(self, ctx: commands.Context):
-        """
-        Manage global aliases.
-        """
+        """Manage global aliases."""
         pass
 
     @checks.mod_or_permissions(manage_guild=True)
     @alias.command(name="add")
     @commands.guild_only()
     async def _add_alias(self, ctx: commands.Context, alias_name: str, *, command):
-        """
-        Add an alias for a command.
-        """
+        """Add an alias for a command."""
         # region Alias Add Validity Checking
         is_command = self.is_command(alias_name)
         if is_command:
             await ctx.send(
                 _(
                     "You attempted to create a new alias"
-                    " with the name {} but that"
+                    " with the name {name} but that"
                     " name is already a command on this bot."
-                ).format(alias_name)
+                ).format(name=alias_name)
             )
             return
 
@@ -207,9 +206,9 @@ class Alias:
             await ctx.send(
                 _(
                     "You attempted to create a new alias"
-                    " with the name {} but that"
+                    " with the name {name} but that"
                     " alias already exists on this server."
-                ).format(alias_name)
+                ).format(name=alias_name)
             )
             return
 
@@ -218,10 +217,10 @@ class Alias:
             await ctx.send(
                 _(
                     "You attempted to create a new alias"
-                    " with the name {} but that"
+                    " with the name {name} but that"
                     " name is an invalid alias name. Alias"
                     " names may not contain spaces."
-                ).format(alias_name)
+                ).format(name=alias_name)
             )
             return
         # endregion
@@ -231,23 +230,23 @@ class Alias:
 
         await self.add_alias(ctx, alias_name, command)
 
-        await ctx.send(_("A new alias with the trigger `{}` has been created.").format(alias_name))
+        await ctx.send(
+            _("A new alias with the trigger `{name}` has been created.").format(name=alias_name)
+        )
 
     @checks.is_owner()
     @global_.command(name="add")
     async def _add_global_alias(self, ctx: commands.Context, alias_name: str, *, command):
-        """
-        Add a global alias for a command.
-        """
+        """Add a global alias for a command."""
         # region Alias Add Validity Checking
         is_command = self.is_command(alias_name)
         if is_command:
             await ctx.send(
                 _(
                     "You attempted to create a new global alias"
-                    " with the name {} but that"
+                    " with the name {name} but that"
                     " name is already a command on this bot."
-                ).format(alias_name)
+                ).format(name=alias_name)
             )
             return
 
@@ -256,9 +255,9 @@ class Alias:
             await ctx.send(
                 _(
                     "You attempted to create a new global alias"
-                    " with the name {} but that"
+                    " with the name {name} but that"
                     " alias already exists on this server."
-                ).format(alias_name)
+                ).format(name=alias_name)
             )
             return
 
@@ -267,10 +266,10 @@ class Alias:
             await ctx.send(
                 _(
                     "You attempted to create a new global alias"
-                    " with the name {} but that"
+                    " with the name {name} but that"
                     " name is an invalid alias name. Alias"
                     " names may not contain spaces."
-                ).format(alias_name)
+                ).format(name=alias_name)
             )
             return
         # endregion
@@ -278,63 +277,68 @@ class Alias:
         await self.add_alias(ctx, alias_name, command, global_=True)
 
         await ctx.send(
-            _("A new global alias with the trigger `{}` has been created.").format(alias_name)
+            _("A new global alias with the trigger `{name}` has been created.").format(
+                name=alias_name
+            )
         )
 
     @alias.command(name="help")
     @commands.guild_only()
     async def _help_alias(self, ctx: commands.Context, alias_name: str):
-        """Tries to execute help for the base command of the alias"""
+        """Try to execute help for the base command of the alias."""
         is_alias, alias = await self.is_alias(ctx.guild, alias_name=alias_name)
         if is_alias:
-            base_cmd = alias.command[0]
+            if self.is_command(alias.command):
+                base_cmd = alias.command
+            else:
+                base_cmd = alias.command.rsplit(" ", 1)[0]
 
             new_msg = copy(ctx.message)
-            new_msg.content = "{}help {}".format(ctx.prefix, base_cmd)
+            new_msg.content = _("{prefix}help {command}").format(
+                prefix=ctx.prefix, command=base_cmd
+            )
             await self.bot.process_commands(new_msg)
         else:
-            ctx.send(_("No such alias exists."))
+            await ctx.send(_("No such alias exists."))
 
     @alias.command(name="show")
     @commands.guild_only()
     async def _show_alias(self, ctx: commands.Context, alias_name: str):
-        """Shows what command the alias executes."""
+        """Show what command the alias executes."""
         is_alias, alias = await self.is_alias(ctx.guild, alias_name)
 
         if is_alias:
             await ctx.send(
-                _("The `{}` alias will execute the command `{}`").format(alias_name, alias.command)
+                _("The `{alias_name}` alias will execute the command `{command}`").format(
+                    alias_name=alias_name, command=alias.command
+                )
             )
         else:
-            await ctx.send(_("There is no alias with the name `{}`").format(alias_name))
+            await ctx.send(_("There is no alias with the name `{name}`").format(name=alias_name))
 
     @checks.mod_or_permissions(manage_guild=True)
     @alias.command(name="del")
     @commands.guild_only()
     async def _del_alias(self, ctx: commands.Context, alias_name: str):
-        """
-        Deletes an existing alias on this server.
-        """
+        """Delete an existing alias on this server."""
         aliases = await self.unloaded_aliases(ctx.guild)
         try:
             next(aliases)
         except StopIteration:
-            await ctx.send(_("There are no aliases on this guild."))
+            await ctx.send(_("There are no aliases on this server."))
             return
 
         if await self.delete_alias(ctx, alias_name):
             await ctx.send(
-                _("Alias with the name `{}` was successfully deleted.").format(alias_name)
+                _("Alias with the name `{name}` was successfully deleted.").format(name=alias_name)
             )
         else:
-            await ctx.send(_("Alias with name `{}` was not found.").format(alias_name))
+            await ctx.send(_("Alias with name `{name}` was not found.").format(name=alias_name))
 
     @checks.is_owner()
     @global_.command(name="del")
     async def _del_global_alias(self, ctx: commands.Context, alias_name: str):
-        """
-        Deletes an existing global alias.
-        """
+        """Delete an existing global alias."""
         aliases = await self.unloaded_global_aliases()
         try:
             next(aliases)
@@ -344,17 +348,15 @@ class Alias:
 
         if await self.delete_alias(ctx, alias_name, global_=True):
             await ctx.send(
-                _("Alias with the name `{}` was successfully deleted.").format(alias_name)
+                _("Alias with the name `{name}` was successfully deleted.").format(name=alias_name)
             )
         else:
-            await ctx.send(_("Alias with name `{}` was not found.").format(alias_name))
+            await ctx.send(_("Alias with name `{name}` was not found.").format(name=alias_name))
 
     @alias.command(name="list")
     @commands.guild_only()
     async def _list_alias(self, ctx: commands.Context):
-        """
-        Lists the available aliases on this server.
-        """
+        """List the available aliases on this server."""
         names = [_("Aliases:")] + sorted(
             ["+ " + a.name for a in (await self.unloaded_aliases(ctx.guild))]
         )
@@ -365,9 +367,7 @@ class Alias:
 
     @global_.command(name="list")
     async def _list_global_alias(self, ctx: commands.Context):
-        """
-        Lists the available global aliases on this bot.
-        """
+        """List the available global aliases on this bot."""
         names = [_("Aliases:")] + sorted(
             ["+ " + a.name for a in await self.unloaded_global_aliases()]
         )

redbot/cogs/alias/locales/messages.pot

@@ -1,89 +0,0 @@
-# SOME DESCRIPTIVE TITLE.
-# Copyright (C) YEAR ORGANIZATION
-# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
-#
-msgid ""
-msgstr ""
-"Project-Id-Version: PACKAGE VERSION\n"
-"POT-Creation-Date: 2018-02-18 14:42+AKST\n"
-"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
-"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
-"Language-Team: LANGUAGE <LL@li.org>\n"
-"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=CHARSET\n"
-"Content-Transfer-Encoding: ENCODING\n"
-"Generated-By: pygettext.py 1.5\n"
-
-
-#: ../alias.py:129
-msgid "No prefix found."
-msgstr ""
-
-#: ../alias.py:198
-msgid "You attempted to create a new alias with the name {} but that name is already a command on this bot."
-msgstr ""
-
-#: ../alias.py:205
-msgid "You attempted to create a new alias with the name {} but that alias already exists on this server."
-msgstr ""
-
-#: ../alias.py:212
-msgid "You attempted to create a new alias with the name {} but that name is an invalid alias name. Alias names may not contain spaces."
-msgstr ""
-
-#: ../alias.py:224
-msgid "A new alias with the trigger `{}` has been created."
-msgstr ""
-
-#: ../alias.py:236
-msgid "You attempted to create a new global alias with the name {} but that name is already a command on this bot."
-msgstr ""
-
-#: ../alias.py:243
-msgid "You attempted to create a new global alias with the name {} but that alias already exists on this server."
-msgstr ""
-
-#: ../alias.py:250
-msgid "You attempted to create a new global alias with the name {} but that name is an invalid alias name. Alias names may not contain spaces."
-msgstr ""
-
-#: ../alias.py:259
-msgid "A new global alias with the trigger `{}` has been created."
-msgstr ""
-
-#: ../alias.py:274
-msgid "No such alias exists."
-msgstr ""
-
-#: ../alias.py:283
-msgid "The `{}` alias will execute the command `{}`"
-msgstr ""
-
-#: ../alias.py:286
-msgid "There is no alias with the name `{}`"
-msgstr ""
-
-#: ../alias.py:298
-msgid "There are no aliases on this guild."
-msgstr ""
-
-#: ../alias.py:302 ../alias.py:320
-msgid "Alias with the name `{}` was successfully deleted."
-msgstr ""
-
-#: ../alias.py:305 ../alias.py:323
-msgid "Alias with name `{}` was not found."
-msgstr ""
-
-#: ../alias.py:316
-msgid "There are no aliases on this bot."
-msgstr ""
-
-#: ../alias.py:331 ../alias.py:342
-msgid "Aliases:"
-msgstr ""
-
-#: ../alias.py:333 ../alias.py:344
-msgid "There are no aliases on this server."
-msgstr ""
-

redbot/cogs/alias/locales/regen_messages.py

@@ -1,11 +0,0 @@
-import subprocess
-
-TO_TRANSLATE = ["../alias.py"]
-
-
-def regen_messages():
-    subprocess.run(["pygettext", "-n"] + TO_TRANSLATE)
-
-
-if __name__ == "__main__":
-    regen_messages()

redbot/cogs/audio/__init__.py

@@ -1,10 +1,8 @@
 from pathlib import Path
-from aiohttp import ClientSession
-import shutil
 import logging
 
 from .audio import Audio
-from .manager import start_lavalink_server
+from .manager import start_lavalink_server, maybe_download_lavalink
 from redbot.core import commands
 from redbot.core.data_manager import cog_data_path
 import redbot.core
@@ -19,31 +17,7 @@ LAVALINK_DOWNLOAD_DIR = cog_data_path(raw_name="Audio")
 LAVALINK_JAR_FILE = LAVALINK_DOWNLOAD_DIR / "Lavalink.jar"
 
 APP_YML_FILE = LAVALINK_DOWNLOAD_DIR / "application.yml"
-BUNDLED_APP_YML_FILE = Path(__file__).parent / "application.yml"
-
-
-async def download_lavalink(session):
-    with LAVALINK_JAR_FILE.open(mode="wb") as f:
-        async with session.get(LAVALINK_DOWNLOAD_URL) as resp:
-            while True:
-                chunk = await resp.content.read(512)
-                if not chunk:
-                    break
-                f.write(chunk)
-
-
-async def maybe_download_lavalink(loop, cog):
-    jar_exists = LAVALINK_JAR_FILE.exists()
-    current_build = redbot.core.VersionInfo(*await cog.config.current_build())
-
-    if not jar_exists or current_build < redbot.core.version_info:
-        log.info("Downloading Lavalink.jar")
-        LAVALINK_DOWNLOAD_DIR.mkdir(parents=True, exist_ok=True)
-        async with ClientSession(loop=loop) as session:
-            await download_lavalink(session)
-        await cog.config.current_build.set(redbot.core.version_info.to_json())
-
-    shutil.copyfile(str(BUNDLED_APP_YML_FILE), str(APP_YML_FILE))
+BUNDLED_APP_YML_FILE = Path(__file__).parent / "data/application.yml"
 
 
 async def setup(bot: commands.Bot):
@@ -52,6 +26,6 @@ async def setup(bot: commands.Bot):
         await maybe_download_lavalink(bot.loop, cog)
         await start_lavalink_server(bot.loop)
 
+    await cog.initialize()
+
     bot.add_cog(cog)
-    bot.loop.create_task(cog.disconnect_timer())
-    bot.loop.create_task(cog.init_config())

redbot/cogs/audio/data/application.yml

@@ -14,7 +14,7 @@ lavalink:
       vimeo: true
       mixer: true
       http: true
-      local: false
+      local: true
     sentryDsn: ""
     bufferDurationMs: 400
-    youtubePlaylistLoadLimit: 10000
+    youtubePlaylistLoadLimit: 10000

redbot/cogs/audio/locales/messages.pot

@@ -1,41 +0,0 @@
-# SOME DESCRIPTIVE TITLE.
-# Copyright (C) YEAR ORGANIZATION
-# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
-#
-msgid ""
-msgstr ""
-"Project-Id-Version: PACKAGE VERSION\n"
-"POT-Creation-Date: 2018-02-18 14:42+AKST\n"
-"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
-"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
-"Language-Team: LANGUAGE <LL@li.org>\n"
-"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=CHARSET\n"
-"Content-Transfer-Encoding: ENCODING\n"
-"Generated-By: pygettext.py 1.5\n"
-
-
-#: ../audio.py:25 ../audio.py:45
-msgid "Join a voice channel first!"
-msgstr ""
-
-#: ../audio.py:33
-msgid "Let's play a file that exists pls"
-msgstr ""
-
-#: ../audio.py:38 ../audio.py:58
-msgid "{} is playing a song..."
-msgstr ""
-
-#: ../audio.py:48
-msgid "Youtube links pls"
-msgstr ""
-
-#: ../audio.py:67 ../audio.py:77 ../audio.py:87 ../audio.py:97
-msgid "I'm not even connected to a voice channel!"
-msgstr ""
-
-#: ../audio.py:95
-msgid "Volume set."
-msgstr ""
-

redbot/cogs/audio/locales/regen_messages.py

@@ -1,11 +0,0 @@
-import subprocess
-
-TO_TRANSLATE = ["../audio.py"]
-
-
-def regen_messages():
-    subprocess.run(["pygettext", "-n"] + TO_TRANSLATE)
-
-
-if __name__ == "__main__":
-    regen_messages()

redbot/cogs/audio/manager.py

@@ -1,11 +1,17 @@
 import shlex
 import shutil
 import asyncio
-from subprocess import Popen, DEVNULL, PIPE
+import asyncio.subprocess
 import os
 import logging
+import re
+from subprocess import Popen, DEVNULL
 from typing import Optional, Tuple
 
+from aiohttp import ClientSession
+
+import redbot.core
+
 _JavaVersion = Tuple[int, int]
 
 log = logging.getLogger("red.audio.manager")
@@ -45,23 +51,48 @@ async def has_java(loop) -> Tuple[bool, Optional[_JavaVersion]]:
         return False, None
 
     version = await get_java_version(loop)
-    return version >= (1, 8), version
+    return (2, 0) > version >= (1, 8) or version >= (8, 0), version
 
 
 async def get_java_version(loop) -> _JavaVersion:
     """
     This assumes we've already checked that java exists.
     """
-    proc = Popen(shlex.split("java -version", posix=os.name == "posix"), stdout=PIPE, stderr=PIPE)
-    _, err = proc.communicate()
+    _proc: asyncio.subprocess.Process = await asyncio.create_subprocess_exec(
+        "java",
+        "-version",
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        loop=loop,
+    )
+    # java -version outputs to stderr
+    _, err = await _proc.communicate()
 
-    version_info = str(err, encoding="utf-8")
+    version_info: str = err.decode("utf-8")
+    # We expect the output to look something like:
+    #     $ java -version
+    #     ...
+    #     ... version "MAJOR.MINOR.PATCH[_BUILD]" ...
+    #     ...
+    # We only care about the major and minor parts though.
+    version_line_re = re.compile(
+        r'version "(?P<major>\d+).(?P<minor>\d+).\d+(?:_\d+)?(?:-[A-Za-z0-9]+)?"'
+    )
+    short_version_re = re.compile(r'version "(?P<major>\d+)"')
 
-    version_line = version_info.split("\n")[0]
-    version_start = version_line.find('"')
-    version_string = version_line[version_start + 1 : -1]
-    major, minor = version_string.split(".")[:2]
-    return int(major), int(minor)
+    lines = version_info.splitlines()
+    for line in lines:
+        match = version_line_re.search(line)
+        short_match = short_version_re.search(line)
+        if match:
+            return int(match["major"]), int(match["minor"])
+        elif short_match:
+            return int(short_match["major"]), 0
+
+    raise RuntimeError(
+        "The output of `java -version` was unexpected. Please report this issue on Red's "
+        "issue tracker."
+    )
 
 
 async def start_lavalink_server(loop):
@@ -69,15 +100,22 @@ async def start_lavalink_server(loop):
     if not java_available:
         raise RuntimeError("You must install Java 1.8+ for Lavalink to run.")
 
-    extra_flags = ""
     if java_version == (1, 8):
         extra_flags = "-Dsun.zip.disableMemoryMapping=true"
+    elif java_version >= (11, 0):
+        extra_flags = "-Djdk.tls.client.protocols=TLSv1.2"
+    else:
+        extra_flags = ""
 
     from . import LAVALINK_DOWNLOAD_DIR, LAVALINK_JAR_FILE
 
     start_cmd = "java {} -jar {}".format(extra_flags, LAVALINK_JAR_FILE.resolve())
 
     global proc
+
+    if proc and proc.poll() is None:
+        return  # already running
+
     proc = Popen(
         shlex.split(start_cmd, posix=os.name == "posix"),
         cwd=str(LAVALINK_DOWNLOAD_DIR),
@@ -91,10 +129,39 @@ async def start_lavalink_server(loop):
 
 
 def shutdown_lavalink_server():
-    log.info("Shutting down lavalink server.")
-    SHUTDOWN.set()
+    global shutdown
+    shutdown = True
     global proc
     if proc is not None:
+        log.info("Shutting down lavalink server.")
         proc.terminate()
         proc.wait()
         proc = None
+
+
+async def download_lavalink(session):
+    from . import LAVALINK_DOWNLOAD_URL, LAVALINK_JAR_FILE
+
+    with LAVALINK_JAR_FILE.open(mode="wb") as f:
+        async with session.get(LAVALINK_DOWNLOAD_URL) as resp:
+            while True:
+                chunk = await resp.content.read(512)
+                if not chunk:
+                    break
+                f.write(chunk)
+
+
+async def maybe_download_lavalink(loop, cog):
+    from . import LAVALINK_DOWNLOAD_DIR, LAVALINK_JAR_FILE, BUNDLED_APP_YML_FILE, APP_YML_FILE
+
+    jar_exists = LAVALINK_JAR_FILE.exists()
+    current_build = redbot.core.VersionInfo.from_json(await cog.config.current_version())
+
+    if not jar_exists or current_build < redbot.core.version_info:
+        log.info("Downloading Lavalink.jar")
+        LAVALINK_DOWNLOAD_DIR.mkdir(parents=True, exist_ok=True)
+        async with ClientSession(loop=loop) as session:
+            await download_lavalink(session)
+        await cog.config.current_version.set(redbot.core.version_info.to_json())
+
+    shutil.copyfile(str(BUNDLED_APP_YML_FILE), str(APP_YML_FILE))