[ { "path": ".github/CONTRIBUTING.md", "content": "## Contributing to discord.py\n\nFirst off, thanks for taking the time to contribute. It makes the library substantially better. :+1:\n\nThe following is a set of guidelines for contributing to the repository. These are guidelines, not hard rules.\n\n## This is too much to read! I want to ask a question!\n\nGenerally speaking questions are better suited in our resources below.\n\n- The official support server: https://discord.gg/r3sSKJJ\n- The Discord API server under #python_discord-py: https://discord.gg/discord-api\n- [The FAQ in the documentation](https://discordpy.readthedocs.io/en/latest/faq.html)\n- [StackOverflow's `discord.py` tag](https://stackoverflow.com/questions/tagged/discord.py)\n\nPlease try your best not to ask questions in our issue tracker. Most of them don't belong there unless they provide value to a larger audience.\n\n## Good Bug Reports\n\nPlease be aware of the following things when filing bug reports.\n\n1. Don't open duplicate issues. Please search your issue to see if it has been asked already. Duplicate issues will be closed.\n2. When filing a bug about exceptions or tracebacks, please include the *complete* traceback. Without the complete traceback the issue might be **unsolvable** and you will be asked to provide more information.\n3. Make sure to provide enough information to make the issue workable. The issue template will generally walk you through the process but they are enumerated here as well:\n - A **summary** of your bug report. This is generally a quick sentence or two to describe the issue in human terms.\n - Guidance on **how to reproduce the issue**. Ideally, this should have a small code sample that allows us to run and see the issue for ourselves to debug. **Please make sure that the token is not displayed**. If you cannot provide a code snippet, then let us know what the steps were, how often it happens, etc.\n - Tell us **what you expected to happen**. That way we can meet that expectation.\n - Tell us **what actually happens**. What ends up happening in reality? It's not helpful to say \"it fails\" or \"it doesn't work\". Say *how* it failed, do you get an exception? Does it hang? How are the expectations different from reality?\n - Tell us **information about your environment**. What version of discord.py are you using? How was it installed? What operating system are you running on? These are valuable questions and information that we use.\n\nIf the bug report is missing this information then it'll take us longer to fix the issue. We will probably ask for clarification, and barring that if no response was given then the issue will be closed.\n\n## Submitting a Pull Request\n\nSubmitting a pull request is fairly simple, just make sure it focuses on a single aspect and doesn't manage to have scope creep and it's probably good to go. It would be incredibly lovely if the style is consistent to that found in the project. This project follows PEP-8 guidelines (mostly) with a column limit of 125.\n\n### Git Commit Guidelines\n\n- Use present tense (e.g. \"Add feature\" not \"Added feature\")\n- Limit all lines to 72 characters or less.\n- Reference issues or pull requests outside of the first line.\n - Please use the shorthand `#123` and not the full URL.\n- Commits regarding the commands extension must be prefixed with `[commands]`\n\nIf you do not meet any of these guidelines, don't fret. Chances are they will be fixed upon rebasing but please do try to meet them to remove some of the workload.\n" }, { "path": ".github/FUNDING.yml", "content": "open_collective: discordpy\n" }, { "path": ".github/ISSUE_TEMPLATE/bug_report.yml", "content": "name: Bug Report\ndescription: Report broken or incorrect behaviour\nlabels: unconfirmed bug\nbody:\n - type: markdown\n attributes:\n value: >\n Thanks for taking the time to fill out a bug.\n If you want real-time support, consider joining our Discord at https://discord.gg/r3sSKJJ instead.\n\n Please note that this form is for bugs only!\n - type: input\n attributes:\n label: Summary\n description: A simple summary of your bug report\n validations:\n required: true\n - type: textarea\n attributes:\n label: Reproduction Steps\n description: >\n What you did to make it happen.\n validations:\n required: true\n - type: textarea\n attributes:\n label: Minimal Reproducible Code\n description: >\n A short snippet of code that showcases the bug.\n render: python\n - type: textarea\n attributes:\n label: Expected Results\n description: >\n What did you expect to happen?\n validations:\n required: true\n - type: textarea\n attributes:\n label: Actual Results\n description: >\n What actually happened?\n validations:\n required: true\n - type: input\n attributes:\n label: Intents\n description: >\n What intents are you using for your bot?\n This is the `discord.Intents` class you pass to the client.\n validations:\n required: true\n - type: textarea\n attributes:\n label: System Information\n description: >\n Run `python -m discord -v` and paste this information below.\n\n This command required v1.1.0 or higher of the library. If this errors out then show some basic\n information involving your system such as operating system and Python version.\n validations:\n required: true\n - type: checkboxes\n attributes:\n label: Checklist\n description: >\n Let's make sure you've properly done due diligence when reporting this issue!\n options:\n - label: I have searched the open issues for duplicates.\n required: true\n - label: I have shown the entire traceback, if possible.\n required: true\n - label: I have removed my token from display, if visible.\n required: true\n - type: textarea\n attributes:\n label: Additional Context\n description: If there is anything else to say, please do so here.\n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "blank_issues_enabled: false\ncontact_links:\n - name: Ask a question\n about: Ask questions and discuss with other users of the library.\n url: https://github.com/Rapptz/discord.py/discussions\n - name: Discord Server\n about: Use our official Discord server to ask for help and questions as well.\n url: https://discord.gg/r3sSKJJ\n" }, { "path": ".github/ISSUE_TEMPLATE/feature_request.yml", "content": "name: Feature Request\ndescription: Suggest a feature for this library\nlabels: feature request\nbody:\n - type: input\n attributes:\n label: Summary\n description: >\n A short summary of what your feature request is.\n validations:\n required: true\n - type: dropdown\n attributes:\n multiple: false\n label: What is the feature request for?\n options:\n - The core library\n - discord.ext.commands\n - discord.ext.tasks\n - The documentation\n validations:\n required: true\n - type: textarea\n attributes:\n label: The Problem\n description: >\n What problem is your feature trying to solve?\n What becomes easier or possible when this feature is implemented?\n validations:\n required: true\n - type: textarea\n attributes:\n label: The Ideal Solution\n description: >\n What is your ideal solution to the problem?\n What would you like this feature to do?\n validations:\n required: true\n - type: textarea\n attributes:\n label: The Current Solution\n description: >\n What is the current solution to the problem, if any?\n validations:\n required: false\n - type: textarea\n attributes:\n label: Additional Context\n description: If there is anything else to say, please do so here.\n" }, { "path": ".github/PULL_REQUEST_TEMPLATE.md", "content": "## Summary\n\n\n\n## Checklist\n\n\n\n- [ ] If code changes were made then they have been tested.\n - [ ] I have updated the documentation to reflect the changes.\n- [ ] This PR fixes an issue.\n- [ ] This PR adds something new (e.g. new method or parameters).\n- [ ] This PR is a breaking change (e.g. methods or parameters removed/renamed)\n- [ ] This PR is **not** a code change (e.g. documentation, README, ...)\n" }, { "path": ".github/workflows/build.yml", "content": "name: build\n\non:\n push:\n pull_request:\n types: [ opened, reopened, synchronize ]\n\njobs:\n dists-and-docs:\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n python-version: [ '3.8', '3.x' ]\n language: [ 'en', 'ja' ]\n\n name: dists & docs (${{ matrix.python-version }}/${{ matrix.language }})\n steps:\n - uses: actions/checkout@v3\n with:\n fetch-depth: 0\n\n - name: Set up CPython ${{ matrix.python-version }}\n uses: actions/setup-python@v4\n with:\n python-version: ${{ matrix.python-version }}\n\n - name: Install dependencies\n run: |\n python -m pip install --upgrade pip setuptools wheel\n pip install -U -r requirements.txt\n\n - name: Build distributions\n run: |\n python ./setup.py sdist bdist_wheel\n\n # - name: Upload artifacts\n # uses: actions/upload-artifact@v2\n # with:\n # name: distributions\n # path: dist/*\n\n - name: Install package\n run: |\n pip install -e .[docs,speed,voice]\n\n - name: Build docs\n shell: bash\n run: |\n cd docs\n sphinx-build -b html -D language=${DOCS_LANGUAGE} -j auto -a -n -T -W --keep-going . _build/html\n env:\n DOCS_LANGUAGE: ${{ matrix.language }}\n\n # - name: Upload docs\n # uses: actions/upload-artifact@v2\n # if: always()\n # with:\n # name: docs-${{ matrix.language }}\n # path: docs/_build/html/*\n" }, { "path": ".github/workflows/crowdin_download.yml", "content": "name: crowdin download\n\non:\n schedule:\n - cron: '0 18 * * 1'\n workflow_dispatch:\n\njobs:\n check-environment:\n runs-on: ubuntu-latest\n environment: Crowdin\n outputs:\n available: ${{ steps.check.outputs.available }}\n steps:\n - id: check\n if: env.CROWDIN_API_KEY != null\n run: |\n echo \"available=true\" >> $GITHUB_OUTPUT\n env:\n CROWDIN_API_KEY: ${{ secrets.CROWDIN_API_KEY }}\n\n download:\n runs-on: ubuntu-latest\n needs: [ check-environment ]\n # secrets cannot be accessed inside an `if` so this needs to be checked in separate job\n if: needs.check-environment.outputs.available == 'true'\n environment: Crowdin\n name: download\n steps:\n - uses: actions/checkout@v2\n with:\n fetch-depth: 0\n ref: master\n\n - name: Install system dependencies\n run: |\n wget -qO - https://artifacts.crowdin.com/repo/GPG-KEY-crowdin | sudo apt-key add -\n echo \"deb https://artifacts.crowdin.com/repo/deb/ /\" | sudo tee -a /etc/apt/sources.list.d/crowdin.list\n sudo apt-get update -qq\n sudo apt-get install -y crowdin3\n\n - name: Download translations\n shell: bash\n run: |\n cd docs\n crowdin download --all\n env:\n CROWDIN_API_KEY: ${{ secrets.CROWDIN_API_KEY }}\n\n - name: Create pull request\n id: cpr_crowdin\n uses: peter-evans/create-pull-request@v3\n with:\n token: ${{ secrets.GITHUB_TOKEN }}\n commit-message: Crowdin translations download\n title: \"[Crowdin] Updated translation files\"\n body: |\n Created by the [Crowdin download workflow](.github/workflows/crowdin_download.yml).\n branch: \"auto/crowdin\"\n author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>\n\n - name: Close and reopen the PR with different token to trigger CI\n uses: actions/github-script@v3\n env:\n PR_NUMBER: ${{ steps.cpr_crowdin.outputs.pull-request-number }}\n PR_OPERATION: ${{ steps.cpr_crowdin.outputs.pull-request-operation }}\n with:\n github-token: ${{ secrets.GH_REPO_SCOPED_TOKEN }}\n script: |\n const script = require(\n `${process.env.GITHUB_WORKSPACE}/.github/workflows/scripts/close_and_reopen_pr.js`\n );\n console.log(script({github, context}));\n" }, { "path": ".github/workflows/crowdin_upload.yml", "content": "name: crowdin upload\n\non:\n workflow_dispatch:\n\njobs:\n upload:\n runs-on: ubuntu-latest\n environment: Crowdin\n name: upload\n steps:\n - uses: actions/checkout@v3\n with:\n fetch-depth: 0\n\n - name: Set up CPython 3.x\n uses: actions/setup-python@v4\n with:\n python-version: 3.x\n\n - name: Install system dependencies\n run: |\n wget -qO - https://artifacts.crowdin.com/repo/GPG-KEY-crowdin | sudo apt-key add -\n echo \"deb https://artifacts.crowdin.com/repo/deb/ /\" | sudo tee -a /etc/apt/sources.list.d/crowdin.list\n sudo apt-get update -qq\n sudo apt-get install -y crowdin3\n\n - name: Install Python dependencies\n run: |\n python -m pip install --upgrade pip setuptools wheel\n pip install -e .[docs,speed,voice]\n\n - name: Build gettext\n run: |\n cd docs\n make gettext\n\n - name: Upload sources\n shell: bash\n run: |\n cd docs\n crowdin upload\n env:\n CROWDIN_API_KEY: ${{ secrets.CROWDIN_API_KEY }}\n" }, { "path": ".github/workflows/lint.yml", "content": "name: lint\n\non:\n push:\n pull_request:\n types: [ opened, reopened, synchronize ]\n\njobs:\n check:\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n python-version: [ '3.8', '3.x' ]\n\n name: check ${{ matrix.python-version }}\n steps:\n - uses: actions/checkout@v3\n with:\n fetch-depth: 0\n\n - name: Set up CPython ${{ matrix.python-version }}\n uses: actions/setup-python@v4\n with:\n python-version: ${{ matrix.python-version }}\n\n - name: Install dependencies\n id: install-deps\n run: |\n python -m pip install --upgrade pip setuptools wheel black==22.6 requests\n pip install -U -r requirements.txt\n\n - name: Setup node.js\n uses: actions/setup-node@v3\n with:\n node-version: '16'\n\n - name: Run Pyright\n uses: jakebailey/pyright-action@v1\n with:\n version: '1.1.351'\n warnings: false\n no-comments: ${{ matrix.python-version != '3.x' }}\n\n - name: Run black\n if: ${{ always() && steps.install-deps.outcome == 'success' }}\n run: |\n black --check discord examples\n" }, { "path": ".github/workflows/scripts/close_and_reopen_pr.js", "content": "module.exports = (async function ({github, context}) {\n const pr_number = process.env.PR_NUMBER;\n const pr_operation = process.env.PR_OPERATION;\n\n if (!['created', 'updated'].includes(pr_operation)) {\n console.log('PR was not created as there were no changes.')\n return;\n }\n\n for (const state of ['closed', 'open']) {\n // Wait a moment for GitHub to process the previous action..\n await new Promise(r => setTimeout(r, 5000));\n\n // Close the PR\n github.issues.update({\n issue_number: pr_number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n state\n });\n }\n})\n" }, { "path": ".github/workflows/test.yml", "content": "name: test\n\non:\n push:\n pull_request:\n types: [ opened, reopened, synchronize ]\n\njobs:\n pytest:\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n python-version: [ '3.8', '3.x' ]\n\n name: pytest ${{ matrix.python-version }}\n steps:\n - uses: actions/checkout@v3\n with:\n fetch-depth: 0\n\n - name: Set up CPython ${{ matrix.python-version }}\n uses: actions/setup-python@v4\n with:\n python-version: ${{ matrix.python-version }}\n\n - name: Install dependencies\n run: |\n python -m pip install -e .[test]\n\n - name: Run tests\n shell: bash\n run: |\n PYTHONPATH=\"$(pwd)\" pytest -vs --cov=discord --cov-report term-missing:skip-covered\n" }, { "path": ".gitignore", "content": "*.json\n*.py[cod]\n*.log\n*.egg-info\nvenv\n.venv\ndocs/_build\ndocs/crowdin.py\n*.buildinfo\n*.mp3\n*.m4a\n*.wav\n*.png\n*.jpg\n*.flac\n*.mo\n/.coverage\nbuild/*\n" }, { "path": ".readthedocs.yml", "content": "version: 2\nformats: []\n\nbuild:\n os: \"ubuntu-22.04\"\n tools:\n python: \"3.8\"\n\nsphinx:\n configuration: docs/conf.py\n fail_on_warning: false\n builder: html\n\npython:\n install:\n - method: pip\n path: .\n extra_requirements:\n - docs\n" }, { "path": "LICENSE", "content": "The MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n" }, { "path": "MANIFEST.in", "content": "include README.rst\ninclude LICENSE\ninclude requirements.txt\ninclude discord/bin/*.dll\ninclude discord/py.typed\n" }, { "path": "README.ja.rst", "content": "discord.py\n==========\n\n.. image:: https://discord.com/api/guilds/336642139381301249/embed.png\n :target: https://discord.gg/nXzj3dg\n :alt: Discordサーバーの招待\n.. image:: https://img.shields.io/pypi/v/discord.py.svg\n :target: https://pypi.python.org/pypi/discord.py\n :alt: PyPIのバージョン情報\n.. image:: https://img.shields.io/pypi/pyversions/discord.py.svg\n :target: https://pypi.python.org/pypi/discord.py\n :alt: PyPIのサポートしているPythonのバージョン\n\ndiscord.py は機能豊富かつモダンで使いやすい、非同期処理にも対応したDiscord用のAPIラッパーです。\n\n主な特徴\n-------------\n\n- ``async`` と ``await`` を使ったモダンなPythonらしいAPI。\n- 適切なレート制限処理\n- メモリと速度の両方を最適化。\n\nインストール\n-------------\n\n**Python 3.8 以降のバージョンが必須です**\n\n完全な音声サポートなしでライブラリをインストールする場合は次のコマンドを実行してください:\n\n.. code:: sh\n\n # Linux/macOS\n python3 -m pip install -U discord.py\n\n # Windows\n py -3 -m pip install -U discord.py\n\n音声サポートが必要なら、次のコマンドを実行しましょう:\n\n.. code:: sh\n\n # Linux/macOS\n python3 -m pip install -U discord.py[voice]\n\n # Windows\n py -3 -m pip install -U discord.py[voice]\n\n\n開発版をインストールしたいのならば、次の手順に従ってください:\n\n.. code:: sh\n\n $ git clone https://github.com/Rapptz/discord.py\n $ cd discord.py\n $ python3 -m pip install -U .[voice]\n\n\nオプションパッケージ\n~~~~~~~~~~~~~~~~~~~~~~\n\n* PyNaCl (音声サポート用)\n\nLinuxで音声サポートを導入するには、前述のコマンドを実行する前にお気に入りのパッケージマネージャー(例えば ``apt`` や ``dnf`` など)を使って以下のパッケージをインストールする必要があります:\n\n* libffi-dev (システムによっては ``libffi-devel``)\n* python-dev (例えばPython 3.8用の ``python3.8-dev``)\n\n簡単な例\n--------------\n\n.. code:: py\n\n import discord\n\n class MyClient(discord.Client):\n async def on_ready(self):\n print('Logged on as', self.user)\n\n async def on_message(self, message):\n # don't respond to ourselves\n if message.author == self.user:\n return\n\n if message.content == 'ping':\n await message.channel.send('pong')\n\n intents = discord.Intents.default()\n intents.message_content = True\n client = MyClient(intents=intents)\n client.run('token')\n\nBotの例\n~~~~~~~~~~~~~\n\n.. code:: py\n\n import discord\n from discord.ext import commands\n\n intents = discord.Intents.default()\n intents.message_content = True\n bot = commands.Bot(command_prefix='>', intents=intents)\n\n @bot.command()\n async def ping(ctx):\n await ctx.send('pong')\n\n bot.run('token')\n\nexamplesディレクトリに更に多くのサンプルがあります。\n\nリンク\n------\n\n- `ドキュメント `_\n- `公式Discordサーバー `_\n- `Discord API `_\n" }, { "path": "README.rst", "content": "discord.py\n==========\n\n.. image:: https://discord.com/api/guilds/336642139381301249/embed.png\n :target: https://discord.gg/r3sSKJJ\n :alt: Discord server invite\n.. image:: https://img.shields.io/pypi/v/discord.py.svg\n :target: https://pypi.python.org/pypi/discord.py\n :alt: PyPI version info\n.. image:: https://img.shields.io/pypi/pyversions/discord.py.svg\n :target: https://pypi.python.org/pypi/discord.py\n :alt: PyPI supported Python versions\n\nA modern, easy to use, feature-rich, and async ready API wrapper for Discord written in Python.\n\nKey Features\n-------------\n\n- Modern Pythonic API using ``async`` and ``await``.\n- Proper rate limit handling.\n- Optimised in both speed and memory.\n\nInstalling\n----------\n\n**Python 3.8 or higher is required**\n\nTo install the library without full voice support, you can just run the following command:\n\n.. code:: sh\n\n # Linux/macOS\n python3 -m pip install -U discord.py\n\n # Windows\n py -3 -m pip install -U discord.py\n\nOtherwise to get voice support you should run the following command:\n\n.. code:: sh\n\n # Linux/macOS\n python3 -m pip install -U \"discord.py[voice]\"\n\n # Windows\n py -3 -m pip install -U discord.py[voice]\n\n\nTo install the development version, do the following:\n\n.. code:: sh\n\n $ git clone https://github.com/Rapptz/discord.py\n $ cd discord.py\n $ python3 -m pip install -U .[voice]\n\n\nOptional Packages\n~~~~~~~~~~~~~~~~~~\n\n* `PyNaCl `__ (for voice support)\n\nPlease note that when installing voice support on Linux, you must install the following packages via your favourite package manager (e.g. ``apt``, ``dnf``, etc) before running the above commands:\n\n* libffi-dev (or ``libffi-devel`` on some systems)\n* python-dev (e.g. ``python3.8-dev`` for Python 3.8)\n\nQuick Example\n--------------\n\n.. code:: py\n\n import discord\n\n class MyClient(discord.Client):\n async def on_ready(self):\n print('Logged on as', self.user)\n\n async def on_message(self, message):\n # don't respond to ourselves\n if message.author == self.user:\n return\n\n if message.content == 'ping':\n await message.channel.send('pong')\n\n intents = discord.Intents.default()\n intents.message_content = True\n client = MyClient(intents=intents)\n client.run('token')\n\nBot Example\n~~~~~~~~~~~~~\n\n.. code:: py\n\n import discord\n from discord.ext import commands\n\n intents = discord.Intents.default()\n intents.message_content = True\n bot = commands.Bot(command_prefix='>', intents=intents)\n\n @bot.command()\n async def ping(ctx):\n await ctx.send('pong')\n\n bot.run('token')\n\nYou can find more examples in the examples directory.\n\nLinks\n------\n\n- `Documentation `_\n- `Official Discord Server `_\n- `Discord API `_\n" }, { "path": "discord/__init__.py", "content": "\"\"\"\nDiscord API Wrapper\n~~~~~~~~~~~~~~~~~~~\n\nA basic wrapper for the Discord API.\n\n:copyright: (c) 2015-present Rapptz\n:license: MIT, see LICENSE for more details.\n\n\"\"\"\n\n__title__ = 'discord'\n__author__ = 'Rapptz'\n__license__ = 'MIT'\n__copyright__ = 'Copyright 2015-present Rapptz'\n__version__ = '2.5.0a'\n\n__path__ = __import__('pkgutil').extend_path(__path__, __name__)\n\nimport logging\nfrom typing import NamedTuple, Literal\n\nfrom .client import *\nfrom .appinfo import *\nfrom .user import *\nfrom .emoji import *\nfrom .partial_emoji import *\nfrom .activity import *\nfrom .channel import *\nfrom .guild import *\nfrom .flags import *\nfrom .member import *\nfrom .message import *\nfrom .asset import *\nfrom .errors import *\nfrom .permissions import *\nfrom .role import *\nfrom .file import *\nfrom .colour import *\nfrom .integrations import *\nfrom .invite import *\nfrom .template import *\nfrom .welcome_screen import *\nfrom .sku import *\nfrom .widget import *\nfrom .object import *\nfrom .reaction import *\nfrom . import (\n utils as utils,\n opus as opus,\n abc as abc,\n ui as ui,\n app_commands as app_commands,\n)\nfrom .enums import *\nfrom .embeds import *\nfrom .mentions import *\nfrom .shard import *\nfrom .player import *\nfrom .webhook import *\nfrom .voice_client import *\nfrom .audit_logs import *\nfrom .raw_models import *\nfrom .team import *\nfrom .sticker import *\nfrom .stage_instance import *\nfrom .scheduled_event import *\nfrom .interactions import *\nfrom .components import *\nfrom .threads import *\nfrom .automod import *\nfrom .poll import *\n\n\nclass VersionInfo(NamedTuple):\n major: int\n minor: int\n micro: int\n releaselevel: Literal[\"alpha\", \"beta\", \"candidate\", \"final\"]\n serial: int\n\n\nversion_info: VersionInfo = VersionInfo(major=2, minor=5, micro=0, releaselevel='alpha', serial=0)\n\nlogging.getLogger(__name__).addHandler(logging.NullHandler())\n\ndel logging, NamedTuple, Literal, VersionInfo\n" }, { "path": "discord/__main__.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import Optional, Tuple, Dict\n\nimport argparse\nimport sys\nfrom pathlib import Path\n\nimport discord\nimport importlib.metadata\nimport aiohttp\nimport platform\n\n\ndef show_version() -> None:\n entries = []\n\n entries.append('- Python v{0.major}.{0.minor}.{0.micro}-{0.releaselevel}'.format(sys.version_info))\n version_info = discord.version_info\n entries.append('- discord.py v{0.major}.{0.minor}.{0.micro}-{0.releaselevel}'.format(version_info))\n if version_info.releaselevel != 'final':\n version = importlib.metadata.version('discord.py')\n if version:\n entries.append(f' - discord.py metadata: v{version}')\n\n entries.append(f'- aiohttp v{aiohttp.__version__}')\n uname = platform.uname()\n entries.append('- system info: {0.system} {0.release} {0.version}'.format(uname))\n print('\\n'.join(entries))\n\n\ndef core(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None:\n if args.version:\n show_version()\n else:\n parser.print_help()\n\n\n_bot_template = \"\"\"#!/usr/bin/env python3\n\nfrom discord.ext import commands\nimport discord\nimport config\n\nclass Bot(commands.{base}):\n def __init__(self, intents: discord.Intents, **kwargs):\n super().__init__(command_prefix=commands.when_mentioned_or('{prefix}'), intents=intents, **kwargs)\n\n async def setup_hook(self):\n for cog in config.cogs:\n try:\n await self.load_extension(cog)\n except Exception as exc:\n print(f'Could not load extension {{cog}} due to {{exc.__class__.__name__}}: {{exc}}')\n\n async def on_ready(self):\n print(f'Logged on as {{self.user}} (ID: {{self.user.id}})')\n\n\nintents = discord.Intents.default()\nintents.message_content = True\nbot = Bot(intents=intents)\n\n# write general commands here\n\nbot.run(config.token)\n\"\"\"\n\n_gitignore_template = \"\"\"# Byte-compiled / optimized / DLL files\n__pycache__/\n*.py[cod]\n*$py.class\n\n# C extensions\n*.so\n\n# Distribution / packaging\n.Python\nenv/\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\nparts/\nsdist/\nvar/\n*.egg-info/\n.installed.cfg\n*.egg\n\n# Our configuration files\nconfig.py\n\"\"\"\n\n_cog_template = '''from discord.ext import commands\nimport discord\n\nclass {name}(commands.Cog{attrs}):\n \"\"\"The description for {name} goes here.\"\"\"\n\n def __init__(self, bot):\n self.bot = bot\n{extra}\nasync def setup(bot):\n await bot.add_cog({name}(bot))\n'''\n\n_cog_extras = '''\n async def cog_load(self):\n # loading logic goes here\n pass\n\n async def cog_unload(self):\n # clean up logic goes here\n pass\n\n async def cog_check(self, ctx):\n # checks that apply to every command in here\n return True\n\n async def bot_check(self, ctx):\n # checks that apply to every command to the bot\n return True\n\n async def bot_check_once(self, ctx):\n # check that apply to every command but is guaranteed to be called only once\n return True\n\n async def cog_command_error(self, ctx, error):\n # error handling to every command in here\n pass\n\n async def cog_app_command_error(self, interaction, error):\n # error handling to every application command in here\n pass\n\n async def cog_before_invoke(self, ctx):\n # called before a command is called here\n pass\n\n async def cog_after_invoke(self, ctx):\n # called after a command is called here\n pass\n\n'''\n\n\n# certain file names and directory names are forbidden\n# see: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247%28v=vs.85%29.aspx\n# although some of this doesn't apply to Linux, we might as well be consistent\n_base_table: Dict[str, Optional[str]] = {\n '<': '-',\n '>': '-',\n ':': '-',\n '\"': '-',\n # '/': '-', these are fine\n # '\\\\': '-',\n '|': '-',\n '?': '-',\n '*': '-',\n}\n\n# NUL (0) and 1-31 are disallowed\n_base_table.update((chr(i), None) for i in range(32))\n\n_translation_table = str.maketrans(_base_table)\n\n\ndef to_path(parser: argparse.ArgumentParser, name: str, *, replace_spaces: bool = False) -> Path:\n if isinstance(name, Path):\n return name\n\n if sys.platform == 'win32':\n forbidden = (\n 'CON',\n 'PRN',\n 'AUX',\n 'NUL',\n 'COM1',\n 'COM2',\n 'COM3',\n 'COM4',\n 'COM5',\n 'COM6',\n 'COM7',\n 'COM8',\n 'COM9',\n 'LPT1',\n 'LPT2',\n 'LPT3',\n 'LPT4',\n 'LPT5',\n 'LPT6',\n 'LPT7',\n 'LPT8',\n 'LPT9',\n )\n if len(name) <= 4 and name.upper() in forbidden:\n parser.error('invalid directory name given, use a different one')\n\n name = name.translate(_translation_table)\n if replace_spaces:\n name = name.replace(' ', '-')\n return Path(name)\n\n\ndef newbot(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None:\n new_directory = to_path(parser, args.directory) / to_path(parser, args.name)\n\n # as a note exist_ok for Path is a 3.5+ only feature\n # since we already checked above that we're >3.5\n try:\n new_directory.mkdir(exist_ok=True, parents=True)\n except OSError as exc:\n parser.error(f'could not create our bot directory ({exc})')\n\n cogs = new_directory / 'cogs'\n\n try:\n cogs.mkdir(exist_ok=True)\n init = cogs / '__init__.py'\n init.touch()\n except OSError as exc:\n print(f'warning: could not create cogs directory ({exc})')\n\n try:\n with open(str(new_directory / 'config.py'), 'w', encoding='utf-8') as fp:\n fp.write('token = \"place your token here\"\\ncogs = []\\n')\n except OSError as exc:\n parser.error(f'could not create config file ({exc})')\n\n try:\n with open(str(new_directory / 'bot.py'), 'w', encoding='utf-8') as fp:\n base = 'Bot' if not args.sharded else 'AutoShardedBot'\n fp.write(_bot_template.format(base=base, prefix=args.prefix))\n except OSError as exc:\n parser.error(f'could not create bot file ({exc})')\n\n if not args.no_git:\n try:\n with open(str(new_directory / '.gitignore'), 'w', encoding='utf-8') as fp:\n fp.write(_gitignore_template)\n except OSError as exc:\n print(f'warning: could not create .gitignore file ({exc})')\n\n print('successfully made bot at', new_directory)\n\n\ndef newcog(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None:\n cog_dir = to_path(parser, args.directory)\n try:\n cog_dir.mkdir(exist_ok=True)\n except OSError as exc:\n print(f'warning: could not create cogs directory ({exc})')\n\n directory = cog_dir / to_path(parser, args.name)\n directory = directory.with_suffix('.py')\n try:\n with open(str(directory), 'w', encoding='utf-8') as fp:\n attrs = ''\n extra = _cog_extras if args.full else ''\n if args.class_name:\n name = args.class_name\n else:\n name = str(directory.stem)\n if '-' in name or '_' in name:\n translation = str.maketrans('-_', ' ')\n name = name.translate(translation).title().replace(' ', '')\n else:\n name = name.title()\n\n if args.display_name:\n attrs += f', name=\"{args.display_name}\"'\n if args.hide_commands:\n attrs += ', command_attrs=dict(hidden=True)'\n fp.write(_cog_template.format(name=name, extra=extra, attrs=attrs))\n except OSError as exc:\n parser.error(f'could not create cog file ({exc})')\n else:\n print('successfully made cog at', directory)\n\n\ndef add_newbot_args(subparser: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:\n parser = subparser.add_parser('newbot', help='creates a command bot project quickly')\n parser.set_defaults(func=newbot)\n\n parser.add_argument('name', help='the bot project name')\n parser.add_argument('directory', help='the directory to place it in (default: .)', nargs='?', default=Path.cwd())\n parser.add_argument('--prefix', help='the bot prefix (default: $)', default='$', metavar='')\n parser.add_argument('--sharded', help='whether to use AutoShardedBot', action='store_true')\n parser.add_argument('--no-git', help='do not create a .gitignore file', action='store_true', dest='no_git')\n\n\ndef add_newcog_args(subparser: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:\n parser = subparser.add_parser('newcog', help='creates a new cog template quickly')\n parser.set_defaults(func=newcog)\n\n parser.add_argument('name', help='the cog name')\n parser.add_argument('directory', help='the directory to place it in (default: cogs)', nargs='?', default=Path('cogs'))\n parser.add_argument('--class-name', help='the class name of the cog (default: )', dest='class_name')\n parser.add_argument('--display-name', help='the cog name (default: )')\n parser.add_argument('--hide-commands', help='whether to hide all commands in the cog', action='store_true')\n parser.add_argument('--full', help='add all special methods as well', action='store_true')\n\n\ndef parse_args() -> Tuple[argparse.ArgumentParser, argparse.Namespace]:\n parser = argparse.ArgumentParser(prog='discord', description='Tools for helping with discord.py')\n parser.add_argument('-v', '--version', action='store_true', help='shows the library version')\n parser.set_defaults(func=core)\n\n subparser = parser.add_subparsers(dest='subcommand', title='subcommands')\n add_newbot_args(subparser)\n add_newcog_args(subparser)\n return parser, parser.parse_args()\n\n\ndef main() -> None:\n parser, args = parse_args()\n args.func(parser, args)\n\n\nif __name__ == '__main__':\n main()\n" }, { "path": "discord/_types.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TypeVar, TYPE_CHECKING\n\nif TYPE_CHECKING:\n from typing_extensions import TypeVar\n from .client import Client\n\n ClientT = TypeVar('ClientT', bound=Client, covariant=True, default=Client)\nelse:\n ClientT = TypeVar('ClientT', bound='Client', covariant=True)\n" }, { "path": "discord/abc.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport copy\nimport time\nimport asyncio\nfrom datetime import datetime\nfrom typing import (\n Any,\n AsyncIterator,\n Callable,\n Dict,\n Iterable,\n List,\n Optional,\n TYPE_CHECKING,\n Protocol,\n Sequence,\n Tuple,\n TypeVar,\n Union,\n overload,\n runtime_checkable,\n)\n\nfrom .object import OLDEST_OBJECT, Object\nfrom .context_managers import Typing\nfrom .enums import ChannelType, InviteTarget\nfrom .errors import ClientException, NotFound\nfrom .mentions import AllowedMentions\nfrom .permissions import PermissionOverwrite, Permissions\nfrom .role import Role\nfrom .invite import Invite\nfrom .file import File\nfrom .http import handle_message_parameters\nfrom .voice_client import VoiceClient, VoiceProtocol\nfrom .sticker import GuildSticker, StickerItem\nfrom . import utils\n\n__all__ = (\n 'Snowflake',\n 'User',\n 'PrivateChannel',\n 'GuildChannel',\n 'Messageable',\n 'Connectable',\n)\n\nT = TypeVar('T', bound=VoiceProtocol)\n\nif TYPE_CHECKING:\n from typing_extensions import Self\n\n from .client import Client\n from .user import ClientUser\n from .asset import Asset\n from .state import ConnectionState\n from .guild import Guild\n from .member import Member\n from .channel import CategoryChannel\n from .embeds import Embed\n from .message import Message, MessageReference, PartialMessage\n from .channel import (\n TextChannel,\n DMChannel,\n GroupChannel,\n PartialMessageable,\n VocalGuildChannel,\n VoiceChannel,\n StageChannel,\n )\n from .poll import Poll\n from .threads import Thread\n from .ui.view import View\n from .types.channel import (\n PermissionOverwrite as PermissionOverwritePayload,\n Channel as ChannelPayload,\n GuildChannel as GuildChannelPayload,\n OverwriteType,\n )\n from .types.snowflake import (\n SnowflakeList,\n )\n\n PartialMessageableChannel = Union[TextChannel, VoiceChannel, StageChannel, Thread, DMChannel, PartialMessageable]\n MessageableChannel = Union[PartialMessageableChannel, GroupChannel]\n SnowflakeTime = Union[\"Snowflake\", datetime]\n\nMISSING = utils.MISSING\n\n\nclass _Undefined:\n def __repr__(self) -> str:\n return 'see-below'\n\n\n_undefined: Any = _Undefined()\n\n\nasync def _single_delete_strategy(messages: Iterable[Message], *, reason: Optional[str] = None):\n for m in messages:\n try:\n await m.delete()\n except NotFound as exc:\n if exc.code == 10008:\n continue # bulk deletion ignores not found messages, single deletion does not.\n # several other race conditions with deletion should fail without continuing,\n # such as the channel being deleted and not found.\n raise\n\n\nasync def _purge_helper(\n channel: Union[Thread, TextChannel, VocalGuildChannel],\n *,\n limit: Optional[int] = 100,\n check: Callable[[Message], bool] = MISSING,\n before: Optional[SnowflakeTime] = None,\n after: Optional[SnowflakeTime] = None,\n around: Optional[SnowflakeTime] = None,\n oldest_first: Optional[bool] = None,\n bulk: bool = True,\n reason: Optional[str] = None,\n) -> List[Message]:\n if check is MISSING:\n check = lambda m: True\n\n iterator = channel.history(limit=limit, before=before, after=after, oldest_first=oldest_first, around=around)\n ret: List[Message] = []\n count = 0\n\n minimum_time = int((time.time() - 14 * 24 * 60 * 60) * 1000.0 - 1420070400000) << 22\n strategy = channel.delete_messages if bulk else _single_delete_strategy\n\n async for message in iterator:\n if count == 100:\n to_delete = ret[-100:]\n await strategy(to_delete, reason=reason)\n count = 0\n await asyncio.sleep(1)\n\n if not check(message):\n continue\n\n if message.id < minimum_time:\n # older than 14 days old\n if count == 1:\n await ret[-1].delete()\n elif count >= 2:\n to_delete = ret[-count:]\n await strategy(to_delete, reason=reason)\n\n count = 0\n strategy = _single_delete_strategy\n\n count += 1\n ret.append(message)\n\n # Some messages remaining to poll\n if count >= 2:\n # more than 2 messages -> bulk delete\n to_delete = ret[-count:]\n await strategy(to_delete, reason=reason)\n elif count == 1:\n # delete a single message\n await ret[-1].delete()\n\n return ret\n\n\n@runtime_checkable\nclass Snowflake(Protocol):\n \"\"\"An ABC that details the common operations on a Discord model.\n\n Almost all :ref:`Discord models ` meet this\n abstract base class.\n\n If you want to create a snowflake on your own, consider using\n :class:`.Object`.\n\n Attributes\n -----------\n id: :class:`int`\n The model's unique ID.\n \"\"\"\n\n id: int\n\n\n@runtime_checkable\nclass User(Snowflake, Protocol):\n \"\"\"An ABC that details the common operations on a Discord user.\n\n The following implement this ABC:\n\n - :class:`~discord.User`\n - :class:`~discord.ClientUser`\n - :class:`~discord.Member`\n\n This ABC must also implement :class:`~discord.abc.Snowflake`.\n\n Attributes\n -----------\n name: :class:`str`\n The user's username.\n discriminator: :class:`str`\n The user's discriminator. This is a legacy concept that is no longer used.\n global_name: Optional[:class:`str`]\n The user's global nickname.\n bot: :class:`bool`\n If the user is a bot account.\n system: :class:`bool`\n If the user is a system account.\n \"\"\"\n\n name: str\n discriminator: str\n global_name: Optional[str]\n bot: bool\n system: bool\n\n @property\n def display_name(self) -> str:\n \"\"\":class:`str`: Returns the user's display name.\"\"\"\n raise NotImplementedError\n\n @property\n def mention(self) -> str:\n \"\"\":class:`str`: Returns a string that allows you to mention the given user.\"\"\"\n raise NotImplementedError\n\n @property\n def avatar(self) -> Optional[Asset]:\n \"\"\"Optional[:class:`~discord.Asset`]: Returns an Asset that represents the user's avatar, if present.\"\"\"\n raise NotImplementedError\n\n @property\n def avatar_decoration(self) -> Optional[Asset]:\n \"\"\"Optional[:class:`~discord.Asset`]: Returns an Asset that represents the user's avatar decoration, if present.\n\n .. versionadded:: 2.4\n \"\"\"\n raise NotImplementedError\n\n @property\n def avatar_decoration_sku_id(self) -> Optional[int]:\n \"\"\"Optional[:class:`int`]: Returns an integer that represents the user's avatar decoration SKU ID, if present.\n\n .. versionadded:: 2.4\n \"\"\"\n raise NotImplementedError\n\n @property\n def default_avatar(self) -> Asset:\n \"\"\":class:`~discord.Asset`: Returns the default avatar for a given user.\"\"\"\n raise NotImplementedError\n\n @property\n def display_avatar(self) -> Asset:\n \"\"\":class:`~discord.Asset`: Returns the user's display avatar.\n\n For regular users this is just their default avatar or uploaded avatar.\n\n .. versionadded:: 2.0\n \"\"\"\n raise NotImplementedError\n\n def mentioned_in(self, message: Message) -> bool:\n \"\"\"Checks if the user is mentioned in the specified message.\n\n Parameters\n -----------\n message: :class:`~discord.Message`\n The message to check if you're mentioned in.\n\n Returns\n -------\n :class:`bool`\n Indicates if the user is mentioned in the message.\n \"\"\"\n raise NotImplementedError\n\n\nclass PrivateChannel:\n \"\"\"An ABC that details the common operations on a private Discord channel.\n\n The following implement this ABC:\n\n - :class:`~discord.DMChannel`\n - :class:`~discord.GroupChannel`\n\n This ABC must also implement :class:`~discord.abc.Snowflake`.\n\n Attributes\n -----------\n me: :class:`~discord.ClientUser`\n The user presenting yourself.\n \"\"\"\n\n __slots__ = ()\n\n id: int\n me: ClientUser\n\n\nclass _Overwrites:\n __slots__ = ('id', 'allow', 'deny', 'type')\n\n ROLE = 0\n MEMBER = 1\n\n def __init__(self, data: PermissionOverwritePayload) -> None:\n self.id: int = int(data['id'])\n self.allow: int = int(data.get('allow', 0))\n self.deny: int = int(data.get('deny', 0))\n self.type: OverwriteType = data['type']\n\n def _asdict(self) -> PermissionOverwritePayload:\n return {\n 'id': self.id,\n 'allow': str(self.allow),\n 'deny': str(self.deny),\n 'type': self.type,\n }\n\n def is_role(self) -> bool:\n return self.type == 0\n\n def is_member(self) -> bool:\n return self.type == 1\n\n\nclass GuildChannel:\n \"\"\"An ABC that details the common operations on a Discord guild channel.\n\n The following implement this ABC:\n\n - :class:`~discord.TextChannel`\n - :class:`~discord.VoiceChannel`\n - :class:`~discord.CategoryChannel`\n - :class:`~discord.StageChannel`\n - :class:`~discord.ForumChannel`\n\n This ABC must also implement :class:`~discord.abc.Snowflake`.\n\n Attributes\n -----------\n name: :class:`str`\n The channel name.\n guild: :class:`~discord.Guild`\n The guild the channel belongs to.\n position: :class:`int`\n The position in the channel list. This is a number that starts at 0.\n e.g. the top channel is position 0.\n \"\"\"\n\n __slots__ = ()\n\n id: int\n name: str\n guild: Guild\n type: ChannelType\n position: int\n category_id: Optional[int]\n _state: ConnectionState\n _overwrites: List[_Overwrites]\n\n if TYPE_CHECKING:\n\n def __init__(self, *, state: ConnectionState, guild: Guild, data: GuildChannelPayload):\n ...\n\n def __str__(self) -> str:\n return self.name\n\n @property\n def _sorting_bucket(self) -> int:\n raise NotImplementedError\n\n def _update(self, guild: Guild, data: Dict[str, Any]) -> None:\n raise NotImplementedError\n\n async def _move(\n self,\n position: int,\n parent_id: Optional[Any] = None,\n lock_permissions: bool = False,\n *,\n reason: Optional[str],\n ) -> None:\n if position < 0:\n raise ValueError('Channel position cannot be less than 0.')\n\n http = self._state.http\n bucket = self._sorting_bucket\n channels: List[GuildChannel] = [c for c in self.guild.channels if c._sorting_bucket == bucket]\n\n channels.sort(key=lambda c: c.position)\n\n try:\n # remove ourselves from the channel list\n channels.remove(self)\n except ValueError:\n # not there somehow lol\n return\n else:\n index = next((i for i, c in enumerate(channels) if c.position >= position), len(channels))\n # add ourselves at our designated position\n channels.insert(index, self)\n\n payload = []\n for index, c in enumerate(channels):\n d: Dict[str, Any] = {'id': c.id, 'position': index}\n if parent_id is not _undefined and c.id == self.id:\n d.update(parent_id=parent_id, lock_permissions=lock_permissions)\n payload.append(d)\n\n await http.bulk_channel_update(self.guild.id, payload, reason=reason)\n\n async def _edit(self, options: Dict[str, Any], reason: Optional[str]) -> Optional[ChannelPayload]:\n try:\n parent = options.pop('category')\n except KeyError:\n parent_id = _undefined\n else:\n parent_id = parent and parent.id\n\n try:\n options['rate_limit_per_user'] = options.pop('slowmode_delay')\n except KeyError:\n pass\n\n try:\n options['default_thread_rate_limit_per_user'] = options.pop('default_thread_slowmode_delay')\n except KeyError:\n pass\n\n try:\n rtc_region = options.pop('rtc_region')\n except KeyError:\n pass\n else:\n options['rtc_region'] = None if rtc_region is None else str(rtc_region)\n\n try:\n video_quality_mode = options.pop('video_quality_mode')\n except KeyError:\n pass\n else:\n options['video_quality_mode'] = int(video_quality_mode)\n\n lock_permissions = options.pop('sync_permissions', False)\n\n try:\n position = options.pop('position')\n except KeyError:\n if parent_id is not _undefined:\n if lock_permissions:\n category = self.guild.get_channel(parent_id)\n if category:\n options['permission_overwrites'] = [c._asdict() for c in category._overwrites]\n options['parent_id'] = parent_id\n elif lock_permissions and self.category_id is not None:\n # if we're syncing permissions on a pre-existing channel category without changing it\n # we need to update the permissions to point to the pre-existing category\n category = self.guild.get_channel(self.category_id)\n if category:\n options['permission_overwrites'] = [c._asdict() for c in category._overwrites]\n else:\n await self._move(position, parent_id=parent_id, lock_permissions=lock_permissions, reason=reason)\n\n overwrites = options.get('overwrites', None)\n if overwrites is not None:\n perms = []\n for target, perm in overwrites.items():\n if not isinstance(perm, PermissionOverwrite):\n raise TypeError(f'Expected PermissionOverwrite received {perm.__class__.__name__}')\n\n allow, deny = perm.pair()\n payload = {\n 'allow': allow.value,\n 'deny': deny.value,\n 'id': target.id,\n }\n\n if isinstance(target, Role):\n payload['type'] = _Overwrites.ROLE\n elif isinstance(target, Object):\n payload['type'] = _Overwrites.ROLE if target.type is Role else _Overwrites.MEMBER\n else:\n payload['type'] = _Overwrites.MEMBER\n\n perms.append(payload)\n options['permission_overwrites'] = perms\n\n try:\n ch_type = options['type']\n except KeyError:\n pass\n else:\n if not isinstance(ch_type, ChannelType):\n raise TypeError('type field must be of type ChannelType')\n options['type'] = ch_type.value\n\n try:\n status = options.pop('status')\n except KeyError:\n pass\n else:\n await self._state.http.edit_voice_channel_status(status, channel_id=self.id, reason=reason)\n\n if options:\n return await self._state.http.edit_channel(self.id, reason=reason, **options)\n\n def _fill_overwrites(self, data: GuildChannelPayload) -> None:\n self._overwrites = []\n everyone_index = 0\n everyone_id = self.guild.id\n\n for index, overridden in enumerate(data.get('permission_overwrites', [])):\n overwrite = _Overwrites(overridden)\n self._overwrites.append(overwrite)\n\n if overwrite.type == _Overwrites.MEMBER:\n continue\n\n if overwrite.id == everyone_id:\n # the @everyone role is not guaranteed to be the first one\n # in the list of permission overwrites, however the permission\n # resolution code kind of requires that it is the first one in\n # the list since it is special. So we need the index so we can\n # swap it to be the first one.\n everyone_index = index\n\n # do the swap\n tmp = self._overwrites\n if tmp:\n tmp[everyone_index], tmp[0] = tmp[0], tmp[everyone_index]\n\n @property\n def changed_roles(self) -> List[Role]:\n \"\"\"List[:class:`~discord.Role`]: Returns a list of roles that have been overridden from\n their default values in the :attr:`~discord.Guild.roles` attribute.\"\"\"\n ret = []\n g = self.guild\n for overwrite in filter(lambda o: o.is_role(), self._overwrites):\n role = g.get_role(overwrite.id)\n if role is None:\n continue\n\n role = copy.copy(role)\n role.permissions.handle_overwrite(overwrite.allow, overwrite.deny)\n ret.append(role)\n return ret\n\n @property\n def mention(self) -> str:\n \"\"\":class:`str`: The string that allows you to mention the channel.\"\"\"\n return f'<#{self.id}>'\n\n @property\n def jump_url(self) -> str:\n \"\"\":class:`str`: Returns a URL that allows the client to jump to the channel.\n\n .. versionadded:: 2.0\n \"\"\"\n return f'https://discord.com/channels/{self.guild.id}/{self.id}'\n\n @property\n def created_at(self) -> datetime:\n \"\"\":class:`datetime.datetime`: Returns the channel's creation time in UTC.\"\"\"\n return utils.snowflake_time(self.id)\n\n def overwrites_for(self, obj: Union[Role, User, Object]) -> PermissionOverwrite:\n \"\"\"Returns the channel-specific overwrites for a member or a role.\n\n Parameters\n -----------\n obj: Union[:class:`~discord.Role`, :class:`~discord.abc.User`, :class:`~discord.Object`]\n The role or user denoting whose overwrite to get.\n\n Returns\n ---------\n :class:`~discord.PermissionOverwrite`\n The permission overwrites for this object.\n \"\"\"\n\n if isinstance(obj, User):\n predicate = lambda p: p.is_member()\n elif isinstance(obj, Role):\n predicate = lambda p: p.is_role()\n else:\n predicate = lambda p: True\n\n for overwrite in filter(predicate, self._overwrites):\n if overwrite.id == obj.id:\n allow = Permissions(overwrite.allow)\n deny = Permissions(overwrite.deny)\n return PermissionOverwrite.from_pair(allow, deny)\n\n return PermissionOverwrite()\n\n @property\n def overwrites(self) -> Dict[Union[Role, Member, Object], PermissionOverwrite]:\n \"\"\"Returns all of the channel's overwrites.\n\n This is returned as a dictionary where the key contains the target which\n can be either a :class:`~discord.Role` or a :class:`~discord.Member` and the value is the\n overwrite as a :class:`~discord.PermissionOverwrite`.\n\n .. versionchanged:: 2.0\n Overwrites can now be type-aware :class:`~discord.Object` in case of cache lookup failure\n\n Returns\n --------\n Dict[Union[:class:`~discord.Role`, :class:`~discord.Member`, :class:`~discord.Object`], :class:`~discord.PermissionOverwrite`]\n The channel's permission overwrites.\n \"\"\"\n ret = {}\n for ow in self._overwrites:\n allow = Permissions(ow.allow)\n deny = Permissions(ow.deny)\n overwrite = PermissionOverwrite.from_pair(allow, deny)\n target = None\n\n if ow.is_role():\n target = self.guild.get_role(ow.id)\n elif ow.is_member():\n target = self.guild.get_member(ow.id)\n\n if target is None:\n target_type = Role if ow.is_role() else User\n target = Object(id=ow.id, type=target_type) # type: ignore\n\n ret[target] = overwrite\n return ret\n\n @property\n def category(self) -> Optional[CategoryChannel]:\n \"\"\"Optional[:class:`~discord.CategoryChannel`]: The category this channel belongs to.\n\n If there is no category then this is ``None``.\n \"\"\"\n return self.guild.get_channel(self.category_id) # type: ignore # These are coerced into CategoryChannel\n\n @property\n def permissions_synced(self) -> bool:\n \"\"\":class:`bool`: Whether or not the permissions for this channel are synced with the\n category it belongs to.\n\n If there is no category then this is ``False``.\n\n .. versionadded:: 1.3\n \"\"\"\n if self.category_id is None:\n return False\n\n category = self.guild.get_channel(self.category_id)\n return bool(category and category.overwrites == self.overwrites)\n\n def _apply_implicit_permissions(self, base: Permissions) -> None:\n # if you can't send a message in a channel then you can't have certain\n # permissions as well\n if not base.send_messages:\n base.send_tts_messages = False\n base.mention_everyone = False\n base.embed_links = False\n base.attach_files = False\n\n # if you can't read a channel then you have no permissions there\n if not base.read_messages:\n denied = Permissions.all_channel()\n base.value &= ~denied.value\n\n def permissions_for(self, obj: Union[Member, Role], /) -> Permissions:\n \"\"\"Handles permission resolution for the :class:`~discord.Member`\n or :class:`~discord.Role`.\n\n This function takes into consideration the following cases:\n\n - Guild owner\n - Guild roles\n - Channel overrides\n - Member overrides\n - Implicit permissions\n - Member timeout\n - User installed app\n\n If a :class:`~discord.Role` is passed, then it checks the permissions\n someone with that role would have, which is essentially:\n\n - The default role permissions\n - The permissions of the role used as a parameter\n - The default role permission overwrites\n - The permission overwrites of the role used as a parameter\n\n .. versionchanged:: 2.0\n The object passed in can now be a role object.\n\n .. versionchanged:: 2.0\n ``obj`` parameter is now positional-only.\n\n .. versionchanged:: 2.4\n User installed apps are now taken into account.\n The permissions returned for a user installed app mirrors the\n permissions Discord returns in :attr:`~discord.Interaction.app_permissions`,\n though it is recommended to use that attribute instead.\n\n Parameters\n ----------\n obj: Union[:class:`~discord.Member`, :class:`~discord.Role`]\n The object to resolve permissions for. This could be either\n a member or a role. If it's a role then member overwrites\n are not computed.\n\n Returns\n -------\n :class:`~discord.Permissions`\n The resolved permissions for the member or role.\n \"\"\"\n\n # The current cases can be explained as:\n # Guild owner get all permissions -- no questions asked. Otherwise...\n # The @everyone role gets the first application.\n # After that, the applied roles that the user has in the channel\n # (or otherwise) are then OR'd together.\n # After the role permissions are resolved, the member permissions\n # have to take into effect.\n # After all that is done.. you have to do the following:\n\n # If manage permissions is True, then all permissions are set to True.\n\n # The operation first takes into consideration the denied\n # and then the allowed.\n\n if self.guild.owner_id == obj.id:\n return Permissions.all()\n\n default = self.guild.default_role\n if default is None:\n\n if self._state.self_id == obj.id:\n return Permissions._user_installed_permissions(in_guild=True)\n else:\n return Permissions.none()\n\n base = Permissions(default.permissions.value)\n\n # Handle the role case first\n if isinstance(obj, Role):\n base.value |= obj._permissions\n\n if base.administrator:\n return Permissions.all()\n\n # Apply @everyone allow/deny first since it's special\n try:\n maybe_everyone = self._overwrites[0]\n if maybe_everyone.id == self.guild.id:\n base.handle_overwrite(allow=maybe_everyone.allow, deny=maybe_everyone.deny)\n except IndexError:\n pass\n\n if obj.is_default():\n return base\n\n overwrite = utils.get(self._overwrites, type=_Overwrites.ROLE, id=obj.id)\n if overwrite is not None:\n base.handle_overwrite(overwrite.allow, overwrite.deny)\n\n return base\n\n roles = obj._roles\n get_role = self.guild.get_role\n\n # Apply guild roles that the member has.\n for role_id in roles:\n role = get_role(role_id)\n if role is not None:\n base.value |= role._permissions\n\n # Guild-wide Administrator -> True for everything\n # Bypass all channel-specific overrides\n if base.administrator:\n return Permissions.all()\n\n # Apply @everyone allow/deny first since it's special\n try:\n maybe_everyone = self._overwrites[0]\n if maybe_everyone.id == self.guild.id:\n base.handle_overwrite(allow=maybe_everyone.allow, deny=maybe_everyone.deny)\n remaining_overwrites = self._overwrites[1:]\n else:\n remaining_overwrites = self._overwrites\n except IndexError:\n remaining_overwrites = self._overwrites\n\n denies = 0\n allows = 0\n\n # Apply channel specific role permission overwrites\n for overwrite in remaining_overwrites:\n if overwrite.is_role() and roles.has(overwrite.id):\n denies |= overwrite.deny\n allows |= overwrite.allow\n\n base.handle_overwrite(allow=allows, deny=denies)\n\n # Apply member specific permission overwrites\n for overwrite in remaining_overwrites:\n if overwrite.is_member() and overwrite.id == obj.id:\n base.handle_overwrite(allow=overwrite.allow, deny=overwrite.deny)\n break\n\n if obj.is_timed_out():\n # Timeout leads to every permission except VIEW_CHANNEL and READ_MESSAGE_HISTORY\n # being explicitly denied\n # N.B.: This *must* come last, because it's a conclusive mask\n base.value &= Permissions._timeout_mask()\n\n return base\n\n async def delete(self, *, reason: Optional[str] = None) -> None:\n \"\"\"|coro|\n\n Deletes the channel.\n\n You must have :attr:`~discord.Permissions.manage_channels` to do this.\n\n Parameters\n -----------\n reason: Optional[:class:`str`]\n The reason for deleting this channel.\n Shows up on the audit log.\n\n Raises\n -------\n ~discord.Forbidden\n You do not have proper permissions to delete the channel.\n ~discord.NotFound\n The channel was not found or was already deleted.\n ~discord.HTTPException\n Deleting the channel failed.\n \"\"\"\n await self._state.http.delete_channel(self.id, reason=reason)\n\n @overload\n async def set_permissions(\n self,\n target: Union[Member, Role],\n *,\n overwrite: Optional[Union[PermissionOverwrite, _Undefined]] = ...,\n reason: Optional[str] = ...,\n ) -> None:\n ...\n\n @overload\n async def set_permissions(\n self,\n target: Union[Member, Role],\n *,\n reason: Optional[str] = ...,\n **permissions: Optional[bool],\n ) -> None:\n ...\n\n async def set_permissions(\n self,\n target: Union[Member, Role],\n *,\n overwrite: Any = _undefined,\n reason: Optional[str] = None,\n **permissions: Optional[bool],\n ) -> None:\n r\"\"\"|coro|\n\n Sets the channel specific permission overwrites for a target in the\n channel.\n\n The ``target`` parameter should either be a :class:`~discord.Member` or a\n :class:`~discord.Role` that belongs to guild.\n\n The ``overwrite`` parameter, if given, must either be ``None`` or\n :class:`~discord.PermissionOverwrite`. For convenience, you can pass in\n keyword arguments denoting :class:`~discord.Permissions` attributes. If this is\n done, then you cannot mix the keyword arguments with the ``overwrite``\n parameter.\n\n If the ``overwrite`` parameter is ``None``, then the permission\n overwrites are deleted.\n\n You must have :attr:`~discord.Permissions.manage_roles` to do this.\n\n .. note::\n\n This method *replaces* the old overwrites with the ones given.\n\n Examples\n ----------\n\n Setting allow and deny: ::\n\n await message.channel.set_permissions(message.author, read_messages=True,\n send_messages=False)\n\n Deleting overwrites ::\n\n await channel.set_permissions(member, overwrite=None)\n\n Using :class:`~discord.PermissionOverwrite` ::\n\n overwrite = discord.PermissionOverwrite()\n overwrite.send_messages = False\n overwrite.read_messages = True\n await channel.set_permissions(member, overwrite=overwrite)\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`TypeError` instead of\n ``InvalidArgument``.\n\n\n Parameters\n -----------\n target: Union[:class:`~discord.Member`, :class:`~discord.Role`]\n The member or role to overwrite permissions for.\n overwrite: Optional[:class:`~discord.PermissionOverwrite`]\n The permissions to allow and deny to the target, or ``None`` to\n delete the overwrite.\n \\*\\*permissions\n A keyword argument list of permissions to set for ease of use.\n Cannot be mixed with ``overwrite``.\n reason: Optional[:class:`str`]\n The reason for doing this action. Shows up on the audit log.\n\n Raises\n -------\n ~discord.Forbidden\n You do not have permissions to edit channel specific permissions.\n ~discord.HTTPException\n Editing channel specific permissions failed.\n ~discord.NotFound\n The role or member being edited is not part of the guild.\n TypeError\n The ``overwrite`` parameter was invalid or the target type was not\n :class:`~discord.Role` or :class:`~discord.Member`.\n ValueError\n The ``overwrite`` parameter and ``positions`` parameters were both\n unset.\n \"\"\"\n\n http = self._state.http\n\n if isinstance(target, User):\n perm_type = _Overwrites.MEMBER\n elif isinstance(target, Role):\n perm_type = _Overwrites.ROLE\n else:\n raise ValueError('target parameter must be either Member or Role')\n\n if overwrite is _undefined:\n if len(permissions) == 0:\n raise ValueError('No overwrite provided.')\n try:\n overwrite = PermissionOverwrite(**permissions)\n except (ValueError, TypeError):\n raise TypeError('Invalid permissions given to keyword arguments.')\n else:\n if len(permissions) > 0:\n raise TypeError('Cannot mix overwrite and keyword arguments.')\n\n if overwrite is None:\n await http.delete_channel_permissions(self.id, target.id, reason=reason)\n elif isinstance(overwrite, PermissionOverwrite):\n (allow, deny) = overwrite.pair()\n await http.edit_channel_permissions(\n self.id, target.id, str(allow.value), str(deny.value), perm_type, reason=reason\n )\n else:\n raise TypeError('Invalid overwrite type provided.')\n\n async def _clone_impl(\n self,\n base_attrs: Dict[str, Any],\n *,\n name: Optional[str] = None,\n reason: Optional[str] = None,\n ) -> Self:\n base_attrs['permission_overwrites'] = [x._asdict() for x in self._overwrites]\n base_attrs['parent_id'] = self.category_id\n base_attrs['name'] = name or self.name\n guild_id = self.guild.id\n cls = self.__class__\n data = await self._state.http.create_channel(guild_id, self.type.value, reason=reason, **base_attrs)\n obj = cls(state=self._state, guild=self.guild, data=data)\n\n # temporarily add it to the cache\n self.guild._channels[obj.id] = obj # type: ignore # obj is a GuildChannel\n return obj\n\n async def clone(self, *, name: Optional[str] = None, reason: Optional[str] = None) -> Self:\n \"\"\"|coro|\n\n Clones this channel. This creates a channel with the same properties\n as this channel.\n\n You must have :attr:`~discord.Permissions.manage_channels` to do this.\n\n .. versionadded:: 1.1\n\n Parameters\n ------------\n name: Optional[:class:`str`]\n The name of the new channel. If not provided, defaults to this\n channel name.\n reason: Optional[:class:`str`]\n The reason for cloning this channel. Shows up on the audit log.\n\n Raises\n -------\n ~discord.Forbidden\n You do not have the proper permissions to create this channel.\n ~discord.HTTPException\n Creating the channel failed.\n\n Returns\n --------\n :class:`.abc.GuildChannel`\n The channel that was created.\n \"\"\"\n raise NotImplementedError\n\n @overload\n async def move(\n self,\n *,\n beginning: bool,\n offset: int = MISSING,\n category: Optional[Snowflake] = MISSING,\n sync_permissions: bool = MISSING,\n reason: Optional[str] = MISSING,\n ) -> None:\n ...\n\n @overload\n async def move(\n self,\n *,\n end: bool,\n offset: int = MISSING,\n category: Optional[Snowflake] = MISSING,\n sync_permissions: bool = MISSING,\n reason: str = MISSING,\n ) -> None:\n ...\n\n @overload\n async def move(\n self,\n *,\n before: Snowflake,\n offset: int = MISSING,\n category: Optional[Snowflake] = MISSING,\n sync_permissions: bool = MISSING,\n reason: str = MISSING,\n ) -> None:\n ...\n\n @overload\n async def move(\n self,\n *,\n after: Snowflake,\n offset: int = MISSING,\n category: Optional[Snowflake] = MISSING,\n sync_permissions: bool = MISSING,\n reason: str = MISSING,\n ) -> None:\n ...\n\n async def move(self, **kwargs: Any) -> None:\n \"\"\"|coro|\n\n A rich interface to help move a channel relative to other channels.\n\n If exact position movement is required, ``edit`` should be used instead.\n\n You must have :attr:`~discord.Permissions.manage_channels` to do this.\n\n .. note::\n\n Voice channels will always be sorted below text channels.\n This is a Discord limitation.\n\n .. versionadded:: 1.7\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`TypeError` or\n :exc:`ValueError` instead of ``InvalidArgument``.\n\n Parameters\n ------------\n beginning: :class:`bool`\n Whether to move the channel to the beginning of the\n channel list (or category if given).\n This is mutually exclusive with ``end``, ``before``, and ``after``.\n end: :class:`bool`\n Whether to move the channel to the end of the\n channel list (or category if given).\n This is mutually exclusive with ``beginning``, ``before``, and ``after``.\n before: :class:`~discord.abc.Snowflake`\n Whether to move the channel before the given channel.\n This is mutually exclusive with ``beginning``, ``end``, and ``after``.\n after: :class:`~discord.abc.Snowflake`\n Whether to move the channel after the given channel.\n This is mutually exclusive with ``beginning``, ``end``, and ``before``.\n offset: :class:`int`\n The number of channels to offset the move by. For example,\n an offset of ``2`` with ``beginning=True`` would move\n it 2 after the beginning. A positive number moves it below\n while a negative number moves it above. Note that this\n number is relative and computed after the ``beginning``,\n ``end``, ``before``, and ``after`` parameters.\n category: Optional[:class:`~discord.abc.Snowflake`]\n The category to move this channel under.\n If ``None`` is given then it moves it out of the category.\n This parameter is ignored if moving a category channel.\n sync_permissions: :class:`bool`\n Whether to sync the permissions with the category (if given).\n reason: :class:`str`\n The reason for the move.\n\n Raises\n -------\n ValueError\n An invalid position was given.\n TypeError\n A bad mix of arguments were passed.\n Forbidden\n You do not have permissions to move the channel.\n HTTPException\n Moving the channel failed.\n \"\"\"\n\n if not kwargs:\n return\n\n beginning, end = kwargs.get('beginning'), kwargs.get('end')\n before, after = kwargs.get('before'), kwargs.get('after')\n offset = kwargs.get('offset', 0)\n if sum(bool(a) for a in (beginning, end, before, after)) > 1:\n raise TypeError('Only one of [before, after, end, beginning] can be used.')\n\n bucket = self._sorting_bucket\n parent_id = kwargs.get('category', MISSING)\n # fmt: off\n channels: List[GuildChannel]\n if parent_id not in (MISSING, None):\n parent_id = parent_id.id\n channels = [\n ch\n for ch in self.guild.channels\n if ch._sorting_bucket == bucket\n and ch.category_id == parent_id\n ]\n else:\n channels = [\n ch\n for ch in self.guild.channels\n if ch._sorting_bucket == bucket\n and ch.category_id == self.category_id\n ]\n # fmt: on\n\n channels.sort(key=lambda c: (c.position, c.id))\n\n try:\n # Try to remove ourselves from the channel list\n channels.remove(self)\n except ValueError:\n # If we're not there then it's probably due to not being in the category\n pass\n\n index = None\n if beginning:\n index = 0\n elif end:\n index = len(channels)\n elif before:\n index = next((i for i, c in enumerate(channels) if c.id == before.id), None)\n elif after:\n index = next((i + 1 for i, c in enumerate(channels) if c.id == after.id), None)\n\n if index is None:\n raise ValueError('Could not resolve appropriate move position')\n\n channels.insert(max((index + offset), 0), self)\n payload = []\n lock_permissions = kwargs.get('sync_permissions', False)\n reason = kwargs.get('reason')\n for index, channel in enumerate(channels):\n d = {'id': channel.id, 'position': index}\n if parent_id is not MISSING and channel.id == self.id:\n d.update(parent_id=parent_id, lock_permissions=lock_permissions)\n payload.append(d)\n\n await self._state.http.bulk_channel_update(self.guild.id, payload, reason=reason)\n\n async def create_invite(\n self,\n *,\n reason: Optional[str] = None,\n max_age: int = 0,\n max_uses: int = 0,\n temporary: bool = False,\n unique: bool = True,\n target_type: Optional[InviteTarget] = None,\n target_user: Optional[User] = None,\n target_application_id: Optional[int] = None,\n ) -> Invite:\n \"\"\"|coro|\n\n Creates an instant invite from a text or voice channel.\n\n You must have :attr:`~discord.Permissions.create_instant_invite` to do this.\n\n Parameters\n ------------\n max_age: :class:`int`\n How long the invite should last in seconds. If it's 0 then the invite\n doesn't expire. Defaults to ``0``.\n max_uses: :class:`int`\n How many uses the invite could be used for. If it's 0 then there\n are unlimited uses. Defaults to ``0``.\n temporary: :class:`bool`\n Denotes that the invite grants temporary membership\n (i.e. they get kicked after they disconnect). Defaults to ``False``.\n unique: :class:`bool`\n Indicates if a unique invite URL should be created. Defaults to True.\n If this is set to ``False`` then it will return a previously created\n invite.\n reason: Optional[:class:`str`]\n The reason for creating this invite. Shows up on the audit log.\n target_type: Optional[:class:`.InviteTarget`]\n The type of target for the voice channel invite, if any.\n\n .. versionadded:: 2.0\n\n target_user: Optional[:class:`User`]\n The user whose stream to display for this invite, required if ``target_type`` is :attr:`.InviteTarget.stream`. The user must be streaming in the channel.\n\n .. versionadded:: 2.0\n\n target_application_id:: Optional[:class:`int`]\n The id of the embedded application for the invite, required if ``target_type`` is :attr:`.InviteTarget.embedded_application`.\n\n .. versionadded:: 2.0\n\n Raises\n -------\n ~discord.HTTPException\n Invite creation failed.\n\n ~discord.NotFound\n The channel that was passed is a category or an invalid channel.\n\n Returns\n --------\n :class:`~discord.Invite`\n The invite that was created.\n \"\"\"\n if target_type is InviteTarget.unknown:\n raise ValueError('Cannot create invite with an unknown target type')\n\n data = await self._state.http.create_invite(\n self.id,\n reason=reason,\n max_age=max_age,\n max_uses=max_uses,\n temporary=temporary,\n unique=unique,\n target_type=target_type.value if target_type else None,\n target_user_id=target_user.id if target_user else None,\n target_application_id=target_application_id,\n )\n return Invite.from_incomplete(data=data, state=self._state)\n\n async def invites(self) -> List[Invite]:\n \"\"\"|coro|\n\n Returns a list of all active instant invites from this channel.\n\n You must have :attr:`~discord.Permissions.manage_channels` to get this information.\n\n Raises\n -------\n ~discord.Forbidden\n You do not have proper permissions to get the information.\n ~discord.HTTPException\n An error occurred while fetching the information.\n\n Returns\n -------\n List[:class:`~discord.Invite`]\n The list of invites that are currently active.\n \"\"\"\n\n state = self._state\n data = await state.http.invites_from_channel(self.id)\n guild = self.guild\n return [Invite(state=state, data=invite, channel=self, guild=guild) for invite in data]\n\n\nclass Messageable:\n \"\"\"An ABC that details the common operations on a model that can send messages.\n\n The following classes implement this ABC:\n\n - :class:`~discord.TextChannel`\n - :class:`~discord.VoiceChannel`\n - :class:`~discord.StageChannel`\n - :class:`~discord.DMChannel`\n - :class:`~discord.GroupChannel`\n - :class:`~discord.PartialMessageable`\n - :class:`~discord.User`\n - :class:`~discord.Member`\n - :class:`~discord.ext.commands.Context`\n - :class:`~discord.Thread`\n \"\"\"\n\n __slots__ = ()\n _state: ConnectionState\n\n async def _get_channel(self) -> MessageableChannel:\n raise NotImplementedError\n\n @overload\n async def send(\n self,\n content: Optional[str] = ...,\n *,\n tts: bool = ...,\n embed: Embed = ...,\n file: File = ...,\n stickers: Sequence[Union[GuildSticker, StickerItem]] = ...,\n delete_after: float = ...,\n nonce: Union[str, int] = ...,\n allowed_mentions: AllowedMentions = ...,\n reference: Union[Message, MessageReference, PartialMessage] = ...,\n mention_author: bool = ...,\n view: View = ...,\n suppress_embeds: bool = ...,\n silent: bool = ...,\n poll: Poll = ...,\n ) -> Message:\n ...\n\n @overload\n async def send(\n self,\n content: Optional[str] = ...,\n *,\n tts: bool = ...,\n embed: Embed = ...,\n files: Sequence[File] = ...,\n stickers: Sequence[Union[GuildSticker, StickerItem]] = ...,\n delete_after: float = ...,\n nonce: Union[str, int] = ...,\n allowed_mentions: AllowedMentions = ...,\n reference: Union[Message, MessageReference, PartialMessage] = ...,\n mention_author: bool = ...,\n view: View = ...,\n suppress_embeds: bool = ...,\n silent: bool = ...,\n poll: Poll = ...,\n ) -> Message:\n ...\n\n @overload\n async def send(\n self,\n content: Optional[str] = ...,\n *,\n tts: bool = ...,\n embeds: Sequence[Embed] = ...,\n file: File = ...,\n stickers: Sequence[Union[GuildSticker, StickerItem]] = ...,\n delete_after: float = ...,\n nonce: Union[str, int] = ...,\n allowed_mentions: AllowedMentions = ...,\n reference: Union[Message, MessageReference, PartialMessage] = ...,\n mention_author: bool = ...,\n view: View = ...,\n suppress_embeds: bool = ...,\n silent: bool = ...,\n poll: Poll = ...,\n ) -> Message:\n ...\n\n @overload\n async def send(\n self,\n content: Optional[str] = ...,\n *,\n tts: bool = ...,\n embeds: Sequence[Embed] = ...,\n files: Sequence[File] = ...,\n stickers: Sequence[Union[GuildSticker, StickerItem]] = ...,\n delete_after: float = ...,\n nonce: Union[str, int] = ...,\n allowed_mentions: AllowedMentions = ...,\n reference: Union[Message, MessageReference, PartialMessage] = ...,\n mention_author: bool = ...,\n view: View = ...,\n suppress_embeds: bool = ...,\n silent: bool = ...,\n poll: Poll = ...,\n ) -> Message:\n ...\n\n async def send(\n self,\n content: Optional[str] = None,\n *,\n tts: bool = False,\n embed: Optional[Embed] = None,\n embeds: Optional[Sequence[Embed]] = None,\n file: Optional[File] = None,\n files: Optional[Sequence[File]] = None,\n stickers: Optional[Sequence[Union[GuildSticker, StickerItem]]] = None,\n delete_after: Optional[float] = None,\n nonce: Optional[Union[str, int]] = None,\n allowed_mentions: Optional[AllowedMentions] = None,\n reference: Optional[Union[Message, MessageReference, PartialMessage]] = None,\n mention_author: Optional[bool] = None,\n view: Optional[View] = None,\n suppress_embeds: bool = False,\n silent: bool = False,\n poll: Optional[Poll] = None,\n ) -> Message:\n \"\"\"|coro|\n\n Sends a message to the destination with the content given.\n\n The content must be a type that can convert to a string through ``str(content)``.\n If the content is set to ``None`` (the default), then the ``embed`` parameter must\n be provided.\n\n To upload a single file, the ``file`` parameter should be used with a\n single :class:`~discord.File` object. To upload multiple files, the ``files``\n parameter should be used with a :class:`list` of :class:`~discord.File` objects.\n **Specifying both parameters will lead to an exception**.\n\n To upload a single embed, the ``embed`` parameter should be used with a\n single :class:`~discord.Embed` object. To upload multiple embeds, the ``embeds``\n parameter should be used with a :class:`list` of :class:`~discord.Embed` objects.\n **Specifying both parameters will lead to an exception**.\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`TypeError` or\n :exc:`ValueError` instead of ``InvalidArgument``.\n\n Parameters\n ------------\n content: Optional[:class:`str`]\n The content of the message to send.\n tts: :class:`bool`\n Indicates if the message should be sent using text-to-speech.\n embed: :class:`~discord.Embed`\n The rich embed for the content.\n embeds: List[:class:`~discord.Embed`]\n A list of embeds to upload. Must be a maximum of 10.\n\n .. versionadded:: 2.0\n file: :class:`~discord.File`\n The file to upload.\n files: List[:class:`~discord.File`]\n A list of files to upload. Must be a maximum of 10.\n nonce: :class:`int`\n The nonce to use for sending this message. If the message was successfully sent,\n then the message will have a nonce with this value.\n delete_after: :class:`float`\n If provided, the number of seconds to wait in the background\n before deleting the message we just sent. If the deletion fails,\n then it is silently ignored.\n allowed_mentions: :class:`~discord.AllowedMentions`\n Controls the mentions being processed in this message. If this is\n passed, then the object is merged with :attr:`~discord.Client.allowed_mentions`.\n The merging behaviour only overrides attributes that have been explicitly passed\n to the object, otherwise it uses the attributes set in :attr:`~discord.Client.allowed_mentions`.\n If no object is passed at all then the defaults given by :attr:`~discord.Client.allowed_mentions`\n are used instead.\n\n .. versionadded:: 1.4\n\n reference: Union[:class:`~discord.Message`, :class:`~discord.MessageReference`, :class:`~discord.PartialMessage`]\n A reference to the :class:`~discord.Message` to which you are replying, this can be created using\n :meth:`~discord.Message.to_reference` or passed directly as a :class:`~discord.Message`. You can control\n whether this mentions the author of the referenced message using the :attr:`~discord.AllowedMentions.replied_user`\n attribute of ``allowed_mentions`` or by setting ``mention_author``.\n\n .. versionadded:: 1.6\n\n mention_author: Optional[:class:`bool`]\n If set, overrides the :attr:`~discord.AllowedMentions.replied_user` attribute of ``allowed_mentions``.\n\n .. versionadded:: 1.6\n view: :class:`discord.ui.View`\n A Discord UI View to add to the message.\n\n .. versionadded:: 2.0\n stickers: Sequence[Union[:class:`~discord.GuildSticker`, :class:`~discord.StickerItem`]]\n A list of stickers to upload. Must be a maximum of 3.\n\n .. versionadded:: 2.0\n suppress_embeds: :class:`bool`\n Whether to suppress embeds for the message. This sends the message without any embeds if set to ``True``.\n\n .. versionadded:: 2.0\n silent: :class:`bool`\n Whether to suppress push and desktop notifications for the message. This will increment the mention counter\n in the UI, but will not actually send a notification.\n\n .. versionadded:: 2.2\n poll: :class:`~discord.Poll`\n The poll to send with this message.\n\n .. versionadded:: 2.4\n\n Raises\n --------\n ~discord.HTTPException\n Sending the message failed.\n ~discord.Forbidden\n You do not have the proper permissions to send the message.\n ValueError\n The ``files`` or ``embeds`` list is not of the appropriate size.\n TypeError\n You specified both ``file`` and ``files``,\n or you specified both ``embed`` and ``embeds``,\n or the ``reference`` object is not a :class:`~discord.Message`,\n :class:`~discord.MessageReference` or :class:`~discord.PartialMessage`.\n\n Returns\n ---------\n :class:`~discord.Message`\n The message that was sent.\n \"\"\"\n\n channel = await self._get_channel()\n state = self._state\n content = str(content) if content is not None else None\n previous_allowed_mention = state.allowed_mentions\n\n if stickers is not None:\n sticker_ids: SnowflakeList = [sticker.id for sticker in stickers]\n else:\n sticker_ids = MISSING\n\n if reference is not None:\n try:\n reference_dict = reference.to_message_reference_dict()\n except AttributeError:\n raise TypeError('reference parameter must be Message, MessageReference, or PartialMessage') from None\n else:\n reference_dict = MISSING\n\n if view and not hasattr(view, '__discord_ui_view__'):\n raise TypeError(f'view parameter must be View not {view.__class__.__name__}')\n\n if suppress_embeds or silent:\n from .message import MessageFlags # circular import\n\n flags = MessageFlags._from_value(0)\n flags.suppress_embeds = suppress_embeds\n flags.suppress_notifications = silent\n else:\n flags = MISSING\n\n with handle_message_parameters(\n content=content,\n tts=tts,\n file=file if file is not None else MISSING,\n files=files if files is not None else MISSING,\n embed=embed if embed is not None else MISSING,\n embeds=embeds if embeds is not None else MISSING,\n nonce=nonce,\n allowed_mentions=allowed_mentions,\n message_reference=reference_dict,\n previous_allowed_mentions=previous_allowed_mention,\n mention_author=mention_author,\n stickers=sticker_ids,\n view=view,\n flags=flags,\n poll=poll,\n ) as params:\n data = await state.http.send_message(channel.id, params=params)\n\n ret = state.create_message(channel=channel, data=data)\n if view and not view.is_finished():\n state.store_view(view, ret.id)\n\n if poll:\n poll._update(ret)\n\n if delete_after is not None:\n await ret.delete(delay=delete_after)\n return ret\n\n def typing(self) -> Typing:\n \"\"\"Returns an asynchronous context manager that allows you to send a typing indicator to\n the destination for an indefinite period of time, or 10 seconds if the context manager\n is called using ``await``.\n\n Example Usage: ::\n\n async with channel.typing():\n # simulate something heavy\n await asyncio.sleep(20)\n\n await channel.send('Done!')\n\n Example Usage: ::\n\n await channel.typing()\n # Do some computational magic for about 10 seconds\n await channel.send('Done!')\n\n .. versionchanged:: 2.0\n This no longer works with the ``with`` syntax, ``async with`` must be used instead.\n\n .. versionchanged:: 2.0\n Added functionality to ``await`` the context manager to send a typing indicator for 10 seconds.\n \"\"\"\n return Typing(self)\n\n async def fetch_message(self, id: int, /) -> Message:\n \"\"\"|coro|\n\n Retrieves a single :class:`~discord.Message` from the destination.\n\n Parameters\n ------------\n id: :class:`int`\n The message ID to look for.\n\n Raises\n --------\n ~discord.NotFound\n The specified message was not found.\n ~discord.Forbidden\n You do not have the permissions required to get a message.\n ~discord.HTTPException\n Retrieving the message failed.\n\n Returns\n --------\n :class:`~discord.Message`\n The message asked for.\n \"\"\"\n\n channel = await self._get_channel()\n data = await self._state.http.get_message(channel.id, id)\n return self._state.create_message(channel=channel, data=data)\n\n async def pins(self) -> List[Message]:\n \"\"\"|coro|\n\n Retrieves all messages that are currently pinned in the channel.\n\n .. note::\n\n Due to a limitation with the Discord API, the :class:`.Message`\n objects returned by this method do not contain complete\n :attr:`.Message.reactions` data.\n\n Raises\n -------\n ~discord.Forbidden\n You do not have the permission to retrieve pinned messages.\n ~discord.HTTPException\n Retrieving the pinned messages failed.\n\n Returns\n --------\n List[:class:`~discord.Message`]\n The messages that are currently pinned.\n \"\"\"\n\n channel = await self._get_channel()\n state = self._state\n data = await state.http.pins_from(channel.id)\n return [state.create_message(channel=channel, data=m) for m in data]\n\n async def history(\n self,\n *,\n limit: Optional[int] = 100,\n before: Optional[SnowflakeTime] = None,\n after: Optional[SnowflakeTime] = None,\n around: Optional[SnowflakeTime] = None,\n oldest_first: Optional[bool] = None,\n ) -> AsyncIterator[Message]:\n \"\"\"Returns an :term:`asynchronous iterator` that enables receiving the destination's message history.\n\n You must have :attr:`~discord.Permissions.read_message_history` to do this.\n\n Examples\n ---------\n\n Usage ::\n\n counter = 0\n async for message in channel.history(limit=200):\n if message.author == client.user:\n counter += 1\n\n Flattening into a list: ::\n\n messages = [message async for message in channel.history(limit=123)]\n # messages is now a list of Message...\n\n All parameters are optional.\n\n Parameters\n -----------\n limit: Optional[:class:`int`]\n The number of messages to retrieve.\n If ``None``, retrieves every message in the channel. Note, however,\n that this would make it a slow operation.\n before: Optional[Union[:class:`~discord.abc.Snowflake`, :class:`datetime.datetime`]]\n Retrieve messages before this date or message.\n If a datetime is provided, it is recommended to use a UTC aware datetime.\n If the datetime is naive, it is assumed to be local time.\n after: Optional[Union[:class:`~discord.abc.Snowflake`, :class:`datetime.datetime`]]\n Retrieve messages after this date or message.\n If a datetime is provided, it is recommended to use a UTC aware datetime.\n If the datetime is naive, it is assumed to be local time.\n around: Optional[Union[:class:`~discord.abc.Snowflake`, :class:`datetime.datetime`]]\n Retrieve messages around this date or message.\n If a datetime is provided, it is recommended to use a UTC aware datetime.\n If the datetime is naive, it is assumed to be local time.\n When using this argument, the maximum limit is 101. Note that if the limit is an\n even number then this will return at most limit + 1 messages.\n oldest_first: Optional[:class:`bool`]\n If set to ``True``, return messages in oldest->newest order. Defaults to ``True`` if\n ``after`` is specified, otherwise ``False``.\n\n Raises\n ------\n ~discord.Forbidden\n You do not have permissions to get channel message history.\n ~discord.HTTPException\n The request to get message history failed.\n\n Yields\n -------\n :class:`~discord.Message`\n The message with the message data parsed.\n \"\"\"\n\n async def _around_strategy(retrieve: int, around: Optional[Snowflake], limit: Optional[int]):\n if not around:\n return [], None, 0\n\n around_id = around.id if around else None\n data = await self._state.http.logs_from(channel.id, retrieve, around=around_id)\n\n return data, None, 0\n\n async def _after_strategy(retrieve: int, after: Optional[Snowflake], limit: Optional[int]):\n after_id = after.id if after else None\n data = await self._state.http.logs_from(channel.id, retrieve, after=after_id)\n\n if data:\n if limit is not None:\n limit -= len(data)\n\n after = Object(id=int(data[0]['id']))\n\n return data, after, limit\n\n async def _before_strategy(retrieve: int, before: Optional[Snowflake], limit: Optional[int]):\n before_id = before.id if before else None\n data = await self._state.http.logs_from(channel.id, retrieve, before=before_id)\n\n if data:\n if limit is not None:\n limit -= len(data)\n\n before = Object(id=int(data[-1]['id']))\n\n return data, before, limit\n\n if isinstance(before, datetime):\n before = Object(id=utils.time_snowflake(before, high=False))\n if isinstance(after, datetime):\n after = Object(id=utils.time_snowflake(after, high=True))\n if isinstance(around, datetime):\n around = Object(id=utils.time_snowflake(around))\n\n if oldest_first is None:\n reverse = after is not None\n else:\n reverse = oldest_first\n\n after = after or OLDEST_OBJECT\n predicate = None\n\n if around:\n if limit is None:\n raise ValueError('history does not support around with limit=None')\n if limit > 101:\n raise ValueError(\"history max limit 101 when specifying around parameter\")\n\n # Strange Discord quirk\n limit = 100 if limit == 101 else limit\n\n strategy, state = _around_strategy, around\n\n if before and after:\n predicate = lambda m: after.id < int(m['id']) < before.id\n elif before:\n predicate = lambda m: int(m['id']) < before.id\n elif after:\n predicate = lambda m: after.id < int(m['id'])\n elif reverse:\n strategy, state = _after_strategy, after\n if before:\n predicate = lambda m: int(m['id']) < before.id\n else:\n strategy, state = _before_strategy, before\n if after and after != OLDEST_OBJECT:\n predicate = lambda m: int(m['id']) > after.id\n\n channel = await self._get_channel()\n\n while True:\n retrieve = 100 if limit is None else min(limit, 100)\n if retrieve < 1:\n return\n\n data, state, limit = await strategy(retrieve, state, limit)\n\n if reverse:\n data = reversed(data)\n if predicate:\n data = filter(predicate, data)\n\n count = 0\n\n for count, raw_message in enumerate(data, 1):\n yield self._state.create_message(channel=channel, data=raw_message)\n\n if count < 100:\n # There's no data left after this\n break\n\n\nclass Connectable(Protocol):\n \"\"\"An ABC that details the common operations on a channel that can\n connect to a voice server.\n\n The following implement this ABC:\n\n - :class:`~discord.VoiceChannel`\n - :class:`~discord.StageChannel`\n \"\"\"\n\n __slots__ = ()\n _state: ConnectionState\n\n def _get_voice_client_key(self) -> Tuple[int, str]:\n raise NotImplementedError\n\n def _get_voice_state_pair(self) -> Tuple[int, int]:\n raise NotImplementedError\n\n async def connect(\n self,\n *,\n timeout: float = 30.0,\n reconnect: bool = True,\n cls: Callable[[Client, Connectable], T] = VoiceClient,\n self_deaf: bool = False,\n self_mute: bool = False,\n ) -> T:\n \"\"\"|coro|\n\n Connects to voice and creates a :class:`~discord.VoiceClient` to establish\n your connection to the voice server.\n\n This requires :attr:`~discord.Intents.voice_states`.\n\n Parameters\n -----------\n timeout: :class:`float`\n The timeout in seconds to wait the connection to complete.\n reconnect: :class:`bool`\n Whether the bot should automatically attempt\n a reconnect if a part of the handshake fails\n or the gateway goes down.\n cls: Type[:class:`~discord.VoiceProtocol`]\n A type that subclasses :class:`~discord.VoiceProtocol` to connect with.\n Defaults to :class:`~discord.VoiceClient`.\n self_mute: :class:`bool`\n Indicates if the client should be self-muted.\n\n .. versionadded:: 2.0\n self_deaf: :class:`bool`\n Indicates if the client should be self-deafened.\n\n .. versionadded:: 2.0\n\n Raises\n -------\n asyncio.TimeoutError\n Could not connect to the voice channel in time.\n ~discord.ClientException\n You are already connected to a voice channel.\n ~discord.opus.OpusNotLoaded\n The opus library has not been loaded.\n\n Returns\n --------\n :class:`~discord.VoiceProtocol`\n A voice client that is fully connected to the voice server.\n \"\"\"\n\n key_id, _ = self._get_voice_client_key()\n state = self._state\n\n if state._get_voice_client(key_id):\n raise ClientException('Already connected to a voice channel.')\n\n client = state._get_client()\n voice: T = cls(client, self)\n\n if not isinstance(voice, VoiceProtocol):\n raise TypeError('Type must meet VoiceProtocol abstract base class.')\n\n state._add_voice_client(key_id, voice)\n\n try:\n await voice.connect(timeout=timeout, reconnect=reconnect, self_deaf=self_deaf, self_mute=self_mute)\n except asyncio.TimeoutError:\n try:\n await voice.disconnect(force=True)\n except Exception:\n # we don't care if disconnect failed because connection failed\n pass\n raise # re-raise\n\n return voice\n" }, { "path": "discord/activity.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport datetime\nfrom typing import Any, Dict, List, Optional, TYPE_CHECKING, Union, overload\n\nfrom .asset import Asset\nfrom .enums import ActivityType, try_enum\nfrom .colour import Colour\nfrom .partial_emoji import PartialEmoji\nfrom .utils import _get_as_snowflake\n\n__all__ = (\n 'BaseActivity',\n 'Activity',\n 'Streaming',\n 'Game',\n 'Spotify',\n 'CustomActivity',\n)\n\n\"\"\"If curious, this is the current schema for an activity.\n\nIt's fairly long so I will document it here:\n\nAll keys are optional.\n\nstate: str (max: 128),\ndetails: str (max: 128)\ntimestamps: dict\n start: int (min: 1)\n end: int (min: 1)\nassets: dict\n large_image: str (max: 32)\n large_text: str (max: 128)\n small_image: str (max: 32)\n small_text: str (max: 128)\nparty: dict\n id: str (max: 128),\n size: List[int] (max-length: 2)\n elem: int (min: 1)\nsecrets: dict\n match: str (max: 128)\n join: str (max: 128)\n spectate: str (max: 128)\ninstance: bool\napplication_id: str\nname: str (max: 128)\nurl: str\ntype: int\nsync_id: str\nsession_id: str\nflags: int\nbuttons: list[str (max: 32)]\n\nThere are also activity flags which are mostly uninteresting for the library atm.\n\nt.ActivityFlags = {\n INSTANCE: 1,\n JOIN: 2,\n SPECTATE: 4,\n JOIN_REQUEST: 8,\n SYNC: 16,\n PLAY: 32\n}\n\"\"\"\n\nif TYPE_CHECKING:\n from .types.activity import (\n Activity as ActivityPayload,\n ActivityTimestamps,\n ActivityParty,\n ActivityAssets,\n )\n\n from .state import ConnectionState\n\n\nclass BaseActivity:\n \"\"\"The base activity that all user-settable activities inherit from.\n A user-settable activity is one that can be used in :meth:`Client.change_presence`.\n\n The following types currently count as user-settable:\n\n - :class:`Activity`\n - :class:`Game`\n - :class:`Streaming`\n - :class:`CustomActivity`\n\n Note that although these types are considered user-settable by the library,\n Discord typically ignores certain combinations of activity depending on\n what is currently set. This behaviour may change in the future so there are\n no guarantees on whether Discord will actually let you set these types.\n\n .. versionadded:: 1.3\n \"\"\"\n\n __slots__ = ('_created_at',)\n\n def __init__(self, **kwargs: Any) -> None:\n self._created_at: Optional[float] = kwargs.pop('created_at', None)\n\n @property\n def created_at(self) -> Optional[datetime.datetime]:\n \"\"\"Optional[:class:`datetime.datetime`]: When the user started doing this activity in UTC.\n\n .. versionadded:: 1.3\n \"\"\"\n if self._created_at is not None:\n return datetime.datetime.fromtimestamp(self._created_at / 1000, tz=datetime.timezone.utc)\n\n def to_dict(self) -> ActivityPayload:\n raise NotImplementedError\n\n\nclass Activity(BaseActivity):\n \"\"\"Represents an activity in Discord.\n\n This could be an activity such as streaming, playing, listening\n or watching.\n\n For memory optimisation purposes, some activities are offered in slimmed\n down versions:\n\n - :class:`Game`\n - :class:`Streaming`\n\n Attributes\n ------------\n application_id: Optional[:class:`int`]\n The application ID of the game.\n name: Optional[:class:`str`]\n The name of the activity.\n url: Optional[:class:`str`]\n A stream URL that the activity could be doing.\n type: :class:`ActivityType`\n The type of activity currently being done.\n state: Optional[:class:`str`]\n The user's current state. For example, \"In Game\".\n details: Optional[:class:`str`]\n The detail of the user's current activity.\n platform: Optional[:class:`str`]\n The user's current platform.\n\n .. versionadded:: 2.4\n timestamps: :class:`dict`\n A dictionary of timestamps. It contains the following optional keys:\n\n - ``start``: Corresponds to when the user started doing the\n activity in milliseconds since Unix epoch.\n - ``end``: Corresponds to when the user will finish doing the\n activity in milliseconds since Unix epoch.\n\n assets: :class:`dict`\n A dictionary representing the images and their hover text of an activity.\n It contains the following optional keys:\n\n - ``large_image``: A string representing the ID for the large image asset.\n - ``large_text``: A string representing the text when hovering over the large image asset.\n - ``small_image``: A string representing the ID for the small image asset.\n - ``small_text``: A string representing the text when hovering over the small image asset.\n\n party: :class:`dict`\n A dictionary representing the activity party. It contains the following optional keys:\n\n - ``id``: A string representing the party ID.\n - ``size``: A list of up to two integer elements denoting (current_size, maximum_size).\n buttons: List[:class:`str`]\n A list of strings representing the labels of custom buttons shown in a rich presence.\n\n .. versionadded:: 2.0\n\n emoji: Optional[:class:`PartialEmoji`]\n The emoji that belongs to this activity.\n \"\"\"\n\n __slots__ = (\n 'state',\n 'details',\n 'timestamps',\n 'platform',\n 'assets',\n 'party',\n 'flags',\n 'sync_id',\n 'session_id',\n 'type',\n 'name',\n 'url',\n 'application_id',\n 'emoji',\n 'buttons',\n )\n\n def __init__(self, **kwargs: Any) -> None:\n super().__init__(**kwargs)\n self.state: Optional[str] = kwargs.pop('state', None)\n self.details: Optional[str] = kwargs.pop('details', None)\n self.timestamps: ActivityTimestamps = kwargs.pop('timestamps', {})\n self.platform: Optional[str] = kwargs.pop('platform', None)\n self.assets: ActivityAssets = kwargs.pop('assets', {})\n self.party: ActivityParty = kwargs.pop('party', {})\n self.application_id: Optional[int] = _get_as_snowflake(kwargs, 'application_id')\n self.name: Optional[str] = kwargs.pop('name', None)\n self.url: Optional[str] = kwargs.pop('url', None)\n self.flags: int = kwargs.pop('flags', 0)\n self.sync_id: Optional[str] = kwargs.pop('sync_id', None)\n self.session_id: Optional[str] = kwargs.pop('session_id', None)\n self.buttons: List[str] = kwargs.pop('buttons', [])\n\n activity_type = kwargs.pop('type', -1)\n self.type: ActivityType = (\n activity_type if isinstance(activity_type, ActivityType) else try_enum(ActivityType, activity_type)\n )\n\n emoji = kwargs.pop('emoji', None)\n self.emoji: Optional[PartialEmoji] = PartialEmoji.from_dict(emoji) if emoji is not None else None\n\n def __repr__(self) -> str:\n attrs = (\n ('type', self.type),\n ('name', self.name),\n ('url', self.url),\n ('platform', self.platform),\n ('details', self.details),\n ('application_id', self.application_id),\n ('session_id', self.session_id),\n ('emoji', self.emoji),\n )\n inner = ' '.join('%s=%r' % t for t in attrs)\n return f''\n\n def to_dict(self) -> Dict[str, Any]:\n ret: Dict[str, Any] = {}\n for attr in self.__slots__:\n value = getattr(self, attr, None)\n if value is None:\n continue\n\n if isinstance(value, dict) and len(value) == 0:\n continue\n\n ret[attr] = value\n ret['type'] = int(self.type)\n if self.emoji:\n ret['emoji'] = self.emoji.to_dict()\n return ret\n\n @property\n def start(self) -> Optional[datetime.datetime]:\n \"\"\"Optional[:class:`datetime.datetime`]: When the user started doing this activity in UTC, if applicable.\"\"\"\n try:\n timestamp = self.timestamps['start'] / 1000\n except KeyError:\n return None\n else:\n return datetime.datetime.fromtimestamp(timestamp, tz=datetime.timezone.utc)\n\n @property\n def end(self) -> Optional[datetime.datetime]:\n \"\"\"Optional[:class:`datetime.datetime`]: When the user will stop doing this activity in UTC, if applicable.\"\"\"\n try:\n timestamp = self.timestamps['end'] / 1000\n except KeyError:\n return None\n else:\n return datetime.datetime.fromtimestamp(timestamp, tz=datetime.timezone.utc)\n\n @property\n def large_image_url(self) -> Optional[str]:\n \"\"\"Optional[:class:`str`]: Returns a URL pointing to the large image asset of this activity, if applicable.\"\"\"\n try:\n large_image = self.assets['large_image']\n except KeyError:\n return None\n else:\n return self._image_url(large_image)\n\n @property\n def small_image_url(self) -> Optional[str]:\n \"\"\"Optional[:class:`str`]: Returns a URL pointing to the small image asset of this activity, if applicable.\"\"\"\n try:\n small_image = self.assets['small_image']\n except KeyError:\n return None\n else:\n return self._image_url(small_image)\n\n def _image_url(self, image: str) -> Optional[str]:\n if image.startswith('mp:'):\n return f'https://media.discordapp.net/{image[3:]}'\n elif self.application_id is not None:\n return Asset.BASE + f'/app-assets/{self.application_id}/{image}.png'\n\n @property\n def large_image_text(self) -> Optional[str]:\n \"\"\"Optional[:class:`str`]: Returns the large image asset hover text of this activity, if applicable.\"\"\"\n return self.assets.get('large_text', None)\n\n @property\n def small_image_text(self) -> Optional[str]:\n \"\"\"Optional[:class:`str`]: Returns the small image asset hover text of this activity, if applicable.\"\"\"\n return self.assets.get('small_text', None)\n\n\nclass Game(BaseActivity):\n \"\"\"A slimmed down version of :class:`Activity` that represents a Discord game.\n\n This is typically displayed via **Playing** on the official Discord client.\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two games are equal.\n\n .. describe:: x != y\n\n Checks if two games are not equal.\n\n .. describe:: hash(x)\n\n Returns the game's hash.\n\n .. describe:: str(x)\n\n Returns the game's name.\n\n Parameters\n -----------\n name: :class:`str`\n The game's name.\n\n Attributes\n -----------\n name: :class:`str`\n The game's name.\n platform: Optional[:class:`str`]\n Where the user is playing from (ie. PS5, Xbox).\n\n .. versionadded:: 2.4\n\n assets: :class:`dict`\n A dictionary representing the images and their hover text of a game.\n It contains the following optional keys:\n\n - ``large_image``: A string representing the ID for the large image asset.\n - ``large_text``: A string representing the text when hovering over the large image asset.\n - ``small_image``: A string representing the ID for the small image asset.\n - ``small_text``: A string representing the text when hovering over the small image asset.\n\n .. versionadded:: 2.4\n \"\"\"\n\n __slots__ = ('name', '_end', '_start', 'platform', 'assets')\n\n def __init__(self, name: str, **extra: Any) -> None:\n super().__init__(**extra)\n self.name: str = name\n self.platform: Optional[str] = extra.get('platform')\n self.assets: ActivityAssets = extra.get('assets', {}) or {}\n\n try:\n timestamps: ActivityTimestamps = extra['timestamps']\n except KeyError:\n self._start = 0\n self._end = 0\n else:\n self._start = timestamps.get('start', 0)\n self._end = timestamps.get('end', 0)\n\n @property\n def type(self) -> ActivityType:\n \"\"\":class:`ActivityType`: Returns the game's type. This is for compatibility with :class:`Activity`.\n\n It always returns :attr:`ActivityType.playing`.\n \"\"\"\n return ActivityType.playing\n\n @property\n def start(self) -> Optional[datetime.datetime]:\n \"\"\"Optional[:class:`datetime.datetime`]: When the user started playing this game in UTC, if applicable.\"\"\"\n if self._start:\n return datetime.datetime.fromtimestamp(self._start / 1000, tz=datetime.timezone.utc)\n return None\n\n @property\n def end(self) -> Optional[datetime.datetime]:\n \"\"\"Optional[:class:`datetime.datetime`]: When the user will stop playing this game in UTC, if applicable.\"\"\"\n if self._end:\n return datetime.datetime.fromtimestamp(self._end / 1000, tz=datetime.timezone.utc)\n return None\n\n def __str__(self) -> str:\n return str(self.name)\n\n def __repr__(self) -> str:\n return f''\n\n def to_dict(self) -> Dict[str, Any]:\n timestamps: Dict[str, Any] = {}\n if self._start:\n timestamps['start'] = self._start\n\n if self._end:\n timestamps['end'] = self._end\n\n return {\n 'type': ActivityType.playing.value,\n 'name': str(self.name),\n 'timestamps': timestamps,\n 'platform': str(self.platform) if self.platform else None,\n 'assets': self.assets,\n }\n\n def __eq__(self, other: object) -> bool:\n return isinstance(other, Game) and other.name == self.name\n\n def __ne__(self, other: object) -> bool:\n return not self.__eq__(other)\n\n def __hash__(self) -> int:\n return hash(self.name)\n\n\nclass Streaming(BaseActivity):\n \"\"\"A slimmed down version of :class:`Activity` that represents a Discord streaming status.\n\n This is typically displayed via **Streaming** on the official Discord client.\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two streams are equal.\n\n .. describe:: x != y\n\n Checks if two streams are not equal.\n\n .. describe:: hash(x)\n\n Returns the stream's hash.\n\n .. describe:: str(x)\n\n Returns the stream's name.\n\n Attributes\n -----------\n platform: Optional[:class:`str`]\n Where the user is streaming from (ie. YouTube, Twitch).\n\n .. versionadded:: 1.3\n\n name: Optional[:class:`str`]\n The stream's name.\n details: Optional[:class:`str`]\n An alias for :attr:`name`\n game: Optional[:class:`str`]\n The game being streamed.\n\n .. versionadded:: 1.3\n\n url: :class:`str`\n The stream's URL.\n assets: :class:`dict`\n A dictionary comprising of similar keys than those in :attr:`Activity.assets`.\n \"\"\"\n\n __slots__ = ('platform', 'name', 'game', 'url', 'details', 'assets')\n\n def __init__(self, *, name: Optional[str], url: str, **extra: Any) -> None:\n super().__init__(**extra)\n self.platform: Optional[str] = name\n self.name: Optional[str] = extra.pop('details', name)\n self.game: Optional[str] = extra.pop('state', None)\n self.url: str = url\n self.details: Optional[str] = extra.pop('details', self.name) # compatibility\n self.assets: ActivityAssets = extra.pop('assets', {})\n\n @property\n def type(self) -> ActivityType:\n \"\"\":class:`ActivityType`: Returns the game's type. This is for compatibility with :class:`Activity`.\n\n It always returns :attr:`ActivityType.streaming`.\n \"\"\"\n return ActivityType.streaming\n\n def __str__(self) -> str:\n return str(self.name)\n\n def __repr__(self) -> str:\n return f''\n\n @property\n def twitch_name(self) -> Optional[str]:\n \"\"\"Optional[:class:`str`]: If provided, the twitch name of the user streaming.\n\n This corresponds to the ``large_image`` key of the :attr:`Streaming.assets`\n dictionary if it starts with ``twitch:``. Typically set by the Discord client.\n \"\"\"\n\n try:\n name = self.assets['large_image']\n except KeyError:\n return None\n else:\n return name[7:] if name[:7] == 'twitch:' else None\n\n def to_dict(self) -> Dict[str, Any]:\n ret: Dict[str, Any] = {\n 'type': ActivityType.streaming.value,\n 'name': str(self.name),\n 'url': str(self.url),\n 'assets': self.assets,\n }\n if self.details:\n ret['details'] = self.details\n return ret\n\n def __eq__(self, other: object) -> bool:\n return isinstance(other, Streaming) and other.name == self.name and other.url == self.url\n\n def __ne__(self, other: object) -> bool:\n return not self.__eq__(other)\n\n def __hash__(self) -> int:\n return hash(self.name)\n\n\nclass Spotify:\n \"\"\"Represents a Spotify listening activity from Discord. This is a special case of\n :class:`Activity` that makes it easier to work with the Spotify integration.\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two activities are equal.\n\n .. describe:: x != y\n\n Checks if two activities are not equal.\n\n .. describe:: hash(x)\n\n Returns the activity's hash.\n\n .. describe:: str(x)\n\n Returns the string 'Spotify'.\n \"\"\"\n\n __slots__ = ('_state', '_details', '_timestamps', '_assets', '_party', '_sync_id', '_session_id', '_created_at')\n\n def __init__(self, **data: Any) -> None:\n self._state: str = data.pop('state', '')\n self._details: str = data.pop('details', '')\n self._timestamps: ActivityTimestamps = data.pop('timestamps', {})\n self._assets: ActivityAssets = data.pop('assets', {})\n self._party: ActivityParty = data.pop('party', {})\n self._sync_id: str = data.pop('sync_id', '')\n self._session_id: Optional[str] = data.pop('session_id')\n self._created_at: Optional[float] = data.pop('created_at', None)\n\n @property\n def type(self) -> ActivityType:\n \"\"\":class:`ActivityType`: Returns the activity's type. This is for compatibility with :class:`Activity`.\n\n It always returns :attr:`ActivityType.listening`.\n \"\"\"\n return ActivityType.listening\n\n @property\n def created_at(self) -> Optional[datetime.datetime]:\n \"\"\"Optional[:class:`datetime.datetime`]: When the user started listening in UTC.\n\n .. versionadded:: 1.3\n \"\"\"\n if self._created_at is not None:\n return datetime.datetime.fromtimestamp(self._created_at / 1000, tz=datetime.timezone.utc)\n\n @property\n def colour(self) -> Colour:\n \"\"\":class:`Colour`: Returns the Spotify integration colour, as a :class:`Colour`.\n\n There is an alias for this named :attr:`color`\"\"\"\n return Colour(0x1DB954)\n\n @property\n def color(self) -> Colour:\n \"\"\":class:`Colour`: Returns the Spotify integration colour, as a :class:`Colour`.\n\n There is an alias for this named :attr:`colour`\"\"\"\n return self.colour\n\n def to_dict(self) -> Dict[str, Any]:\n return {\n 'flags': 48, # SYNC | PLAY\n 'name': 'Spotify',\n 'assets': self._assets,\n 'party': self._party,\n 'sync_id': self._sync_id,\n 'session_id': self._session_id,\n 'timestamps': self._timestamps,\n 'details': self._details,\n 'state': self._state,\n }\n\n @property\n def name(self) -> str:\n \"\"\":class:`str`: The activity's name. This will always return \"Spotify\".\"\"\"\n return 'Spotify'\n\n def __eq__(self, other: object) -> bool:\n return (\n isinstance(other, Spotify)\n and other._session_id == self._session_id\n and other._sync_id == self._sync_id\n and other.start == self.start\n )\n\n def __ne__(self, other: object) -> bool:\n return not self.__eq__(other)\n\n def __hash__(self) -> int:\n return hash(self._session_id)\n\n def __str__(self) -> str:\n return 'Spotify'\n\n def __repr__(self) -> str:\n return f''\n\n @property\n def title(self) -> str:\n \"\"\":class:`str`: The title of the song being played.\"\"\"\n return self._details\n\n @property\n def artists(self) -> List[str]:\n \"\"\"List[:class:`str`]: The artists of the song being played.\"\"\"\n return self._state.split('; ')\n\n @property\n def artist(self) -> str:\n \"\"\":class:`str`: The artist of the song being played.\n\n This does not attempt to split the artist information into\n multiple artists. Useful if there's only a single artist.\n \"\"\"\n return self._state\n\n @property\n def album(self) -> str:\n \"\"\":class:`str`: The album that the song being played belongs to.\"\"\"\n return self._assets.get('large_text', '')\n\n @property\n def album_cover_url(self) -> str:\n \"\"\":class:`str`: The album cover image URL from Spotify's CDN.\"\"\"\n large_image = self._assets.get('large_image', '')\n if large_image[:8] != 'spotify:':\n return ''\n album_image_id = large_image[8:]\n return 'https://i.scdn.co/image/' + album_image_id\n\n @property\n def track_id(self) -> str:\n \"\"\":class:`str`: The track ID used by Spotify to identify this song.\"\"\"\n return self._sync_id\n\n @property\n def track_url(self) -> str:\n \"\"\":class:`str`: The track URL to listen on Spotify.\n\n .. versionadded:: 2.0\n \"\"\"\n return f'https://open.spotify.com/track/{self.track_id}'\n\n @property\n def start(self) -> datetime.datetime:\n \"\"\":class:`datetime.datetime`: When the user started playing this song in UTC.\"\"\"\n # the start key will be present here\n return datetime.datetime.fromtimestamp(self._timestamps['start'] / 1000, tz=datetime.timezone.utc) # type: ignore\n\n @property\n def end(self) -> datetime.datetime:\n \"\"\":class:`datetime.datetime`: When the user will stop playing this song in UTC.\"\"\"\n # the end key will be present here\n return datetime.datetime.fromtimestamp(self._timestamps['end'] / 1000, tz=datetime.timezone.utc) # type: ignore\n\n @property\n def duration(self) -> datetime.timedelta:\n \"\"\":class:`datetime.timedelta`: The duration of the song being played.\"\"\"\n return self.end - self.start\n\n @property\n def party_id(self) -> str:\n \"\"\":class:`str`: The party ID of the listening party.\"\"\"\n return self._party.get('id', '')\n\n\nclass CustomActivity(BaseActivity):\n \"\"\"Represents a custom activity from Discord.\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two activities are equal.\n\n .. describe:: x != y\n\n Checks if two activities are not equal.\n\n .. describe:: hash(x)\n\n Returns the activity's hash.\n\n .. describe:: str(x)\n\n Returns the custom status text.\n\n .. versionadded:: 1.3\n\n Attributes\n -----------\n name: Optional[:class:`str`]\n The custom activity's name.\n emoji: Optional[:class:`PartialEmoji`]\n The emoji to pass to the activity, if any.\n \"\"\"\n\n __slots__ = ('name', 'emoji', 'state')\n\n def __init__(\n self, name: Optional[str], *, emoji: Optional[Union[PartialEmoji, Dict[str, Any], str]] = None, **extra: Any\n ) -> None:\n super().__init__(**extra)\n self.name: Optional[str] = name\n self.state: Optional[str] = extra.pop('state', name)\n if self.name == 'Custom Status':\n self.name = self.state\n\n self.emoji: Optional[PartialEmoji]\n if emoji is None:\n self.emoji = emoji\n elif isinstance(emoji, dict):\n self.emoji = PartialEmoji.from_dict(emoji)\n elif isinstance(emoji, str):\n self.emoji = PartialEmoji(name=emoji)\n elif isinstance(emoji, PartialEmoji):\n self.emoji = emoji\n else:\n raise TypeError(f'Expected str, PartialEmoji, or None, received {type(emoji)!r} instead.')\n\n @property\n def type(self) -> ActivityType:\n \"\"\":class:`ActivityType`: Returns the activity's type. This is for compatibility with :class:`Activity`.\n\n It always returns :attr:`ActivityType.custom`.\n \"\"\"\n return ActivityType.custom\n\n def to_dict(self) -> Dict[str, Any]:\n if self.name == self.state:\n o = {\n 'type': ActivityType.custom.value,\n 'state': self.name,\n 'name': 'Custom Status',\n }\n else:\n o = {\n 'type': ActivityType.custom.value,\n 'name': self.name,\n }\n\n if self.emoji:\n o['emoji'] = self.emoji.to_dict()\n return o\n\n def __eq__(self, other: object) -> bool:\n return isinstance(other, CustomActivity) and other.name == self.name and other.emoji == self.emoji\n\n def __ne__(self, other: object) -> bool:\n return not self.__eq__(other)\n\n def __hash__(self) -> int:\n return hash((self.name, str(self.emoji)))\n\n def __str__(self) -> str:\n if self.emoji:\n if self.name:\n return f'{self.emoji} {self.name}'\n return str(self.emoji)\n else:\n return str(self.name)\n\n def __repr__(self) -> str:\n return f''\n\n\nActivityTypes = Union[Activity, Game, CustomActivity, Streaming, Spotify]\n\n\n@overload\ndef create_activity(data: ActivityPayload, state: ConnectionState) -> ActivityTypes:\n ...\n\n\n@overload\ndef create_activity(data: None, state: ConnectionState) -> None:\n ...\n\n\ndef create_activity(data: Optional[ActivityPayload], state: ConnectionState) -> Optional[ActivityTypes]:\n if not data:\n return None\n\n game_type = try_enum(ActivityType, data.get('type', -1))\n if game_type is ActivityType.playing:\n if 'application_id' in data or 'session_id' in data:\n return Activity(**data)\n return Game(**data)\n elif game_type is ActivityType.custom:\n try:\n name = data.pop('name') # type: ignore\n except KeyError:\n ret = Activity(**data)\n else:\n # we removed the name key from data already\n ret = CustomActivity(name=name, **data) # type: ignore\n elif game_type is ActivityType.streaming:\n if 'url' in data:\n # the url won't be None here\n return Streaming(**data) # type: ignore\n return Activity(**data)\n elif game_type is ActivityType.listening and 'sync_id' in data and 'session_id' in data:\n return Spotify(**data)\n else:\n ret = Activity(**data)\n\n if isinstance(ret.emoji, PartialEmoji):\n ret.emoji._state = state\n return ret\n" }, { "path": "discord/app_commands/__init__.py", "content": "\"\"\"\ndiscord.app_commands\n~~~~~~~~~~~~~~~~~~~~~\n\nApplication commands support for the Discord API\n\n:copyright: (c) 2015-present Rapptz\n:license: MIT, see LICENSE for more details.\n\n\"\"\"\n\nfrom .commands import *\nfrom .errors import *\nfrom .models import *\nfrom .tree import *\nfrom .namespace import *\nfrom .transformers import *\nfrom .translator import *\nfrom .installs import *\nfrom . import checks as checks\nfrom .checks import Cooldown as Cooldown\n" }, { "path": "discord/app_commands/checks.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import (\n Any,\n Coroutine,\n Dict,\n Hashable,\n Union,\n Callable,\n TypeVar,\n Optional,\n TYPE_CHECKING,\n)\n\nimport time\n\nfrom .commands import check\nfrom .errors import (\n NoPrivateMessage,\n MissingRole,\n MissingAnyRole,\n MissingPermissions,\n BotMissingPermissions,\n CommandOnCooldown,\n)\n\nfrom ..user import User\nfrom ..permissions import Permissions\nfrom ..utils import get as utils_get, MISSING, maybe_coroutine\n\nT = TypeVar('T')\n\nif TYPE_CHECKING:\n from typing_extensions import Self\n from ..interactions import Interaction\n\n CooldownFunction = Union[\n Callable[[Interaction[Any]], Coroutine[Any, Any, T]],\n Callable[[Interaction[Any]], T],\n ]\n\n__all__ = (\n 'has_role',\n 'has_any_role',\n 'has_permissions',\n 'bot_has_permissions',\n 'cooldown',\n 'dynamic_cooldown',\n)\n\n\nclass Cooldown:\n \"\"\"Represents a cooldown for a command.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n rate: :class:`float`\n The total number of tokens available per :attr:`per` seconds.\n per: :class:`float`\n The length of the cooldown period in seconds.\n \"\"\"\n\n __slots__ = ('rate', 'per', '_window', '_tokens', '_last')\n\n def __init__(self, rate: float, per: float) -> None:\n self.rate: int = int(rate)\n self.per: float = float(per)\n self._window: float = 0.0\n self._tokens: int = self.rate\n self._last: float = 0.0\n\n def get_tokens(self, current: Optional[float] = None) -> int:\n \"\"\"Returns the number of available tokens before rate limiting is applied.\n\n Parameters\n ------------\n current: Optional[:class:`float`]\n The time in seconds since Unix epoch to calculate tokens at.\n If not supplied then :func:`time.time()` is used.\n\n Returns\n --------\n :class:`int`\n The number of tokens available before the cooldown is to be applied.\n \"\"\"\n if not current:\n current = time.time()\n\n # the calculated tokens should be non-negative\n tokens = max(self._tokens, 0)\n\n if current > self._window + self.per:\n tokens = self.rate\n return tokens\n\n def get_retry_after(self, current: Optional[float] = None) -> float:\n \"\"\"Returns the time in seconds until the cooldown will be reset.\n\n Parameters\n -------------\n current: Optional[:class:`float`]\n The current time in seconds since Unix epoch.\n If not supplied, then :func:`time.time()` is used.\n\n Returns\n -------\n :class:`float`\n The number of seconds to wait before this cooldown will be reset.\n \"\"\"\n current = current or time.time()\n tokens = self.get_tokens(current)\n\n if tokens == 0:\n return self.per - (current - self._window)\n\n return 0.0\n\n def update_rate_limit(self, current: Optional[float] = None, *, tokens: int = 1) -> Optional[float]:\n \"\"\"Updates the cooldown rate limit.\n\n Parameters\n -------------\n current: Optional[:class:`float`]\n The time in seconds since Unix epoch to update the rate limit at.\n If not supplied, then :func:`time.time()` is used.\n tokens: :class:`int`\n The amount of tokens to deduct from the rate limit.\n\n Returns\n -------\n Optional[:class:`float`]\n The retry-after time in seconds if rate limited.\n \"\"\"\n current = current or time.time()\n self._last = current\n\n self._tokens = self.get_tokens(current)\n\n # first token used means that we start a new rate limit window\n if self._tokens == self.rate:\n self._window = current\n\n # decrement tokens by specified number\n self._tokens -= tokens\n\n # check if we are rate limited and return retry-after\n if self._tokens < 0:\n return self.per - (current - self._window)\n\n def reset(self) -> None:\n \"\"\"Reset the cooldown to its initial state.\"\"\"\n self._tokens = self.rate\n self._last = 0.0\n\n def copy(self) -> Self:\n \"\"\"Creates a copy of this cooldown.\n\n Returns\n --------\n :class:`Cooldown`\n A new instance of this cooldown.\n \"\"\"\n return self.__class__(self.rate, self.per)\n\n def __repr__(self) -> str:\n return f''\n\n\ndef has_role(item: Union[int, str], /) -> Callable[[T], T]:\n \"\"\"A :func:`~discord.app_commands.check` that is added that checks if the member invoking the\n command has the role specified via the name or ID specified.\n\n If a string is specified, you must give the exact name of the role, including\n caps and spelling.\n\n If an integer is specified, you must give the exact snowflake ID of the role.\n\n This check raises one of two special exceptions, :exc:`~discord.app_commands.MissingRole`\n if the user is missing a role, or :exc:`~discord.app_commands.NoPrivateMessage` if\n it is used in a private message. Both inherit from :exc:`~discord.app_commands.CheckFailure`.\n\n .. versionadded:: 2.0\n\n .. note::\n\n This is different from the permission system that Discord provides for application\n commands. This is done entirely locally in the program rather than being handled\n by Discord.\n\n Parameters\n -----------\n item: Union[:class:`int`, :class:`str`]\n The name or ID of the role to check.\n \"\"\"\n\n def predicate(interaction: Interaction) -> bool:\n if isinstance(interaction.user, User):\n raise NoPrivateMessage()\n\n if isinstance(item, int):\n role = interaction.user.get_role(item)\n else:\n role = utils_get(interaction.user.roles, name=item)\n\n if role is None:\n raise MissingRole(item)\n return True\n\n return check(predicate)\n\n\ndef has_any_role(*items: Union[int, str]) -> Callable[[T], T]:\n r\"\"\"A :func:`~discord.app_commands.check` that is added that checks if the member\n invoking the command has **any** of the roles specified. This means that if they have\n one out of the three roles specified, then this check will return ``True``.\n\n Similar to :func:`has_role`\\, the names or IDs passed in must be exact.\n\n This check raises one of two special exceptions, :exc:`~discord.app_commands.MissingAnyRole`\n if the user is missing all roles, or :exc:`~discord.app_commands.NoPrivateMessage` if\n it is used in a private message. Both inherit from :exc:`~discord.app_commands.CheckFailure`.\n\n .. versionadded:: 2.0\n\n .. note::\n\n This is different from the permission system that Discord provides for application\n commands. This is done entirely locally in the program rather than being handled\n by Discord.\n\n Parameters\n -----------\n items: List[Union[:class:`str`, :class:`int`]]\n An argument list of names or IDs to check that the member has roles wise.\n\n Example\n --------\n\n .. code-block:: python3\n\n @tree.command()\n @app_commands.checks.has_any_role('Library Devs', 'Moderators', 492212595072434186)\n async def cool(interaction: discord.Interaction):\n await interaction.response.send_message('You are cool indeed')\n \"\"\"\n\n def predicate(interaction: Interaction) -> bool:\n if isinstance(interaction.user, User):\n raise NoPrivateMessage()\n\n if any(\n interaction.user.get_role(item) is not None\n if isinstance(item, int)\n else utils_get(interaction.user.roles, name=item) is not None\n for item in items\n ):\n return True\n raise MissingAnyRole(list(items))\n\n return check(predicate)\n\n\ndef has_permissions(**perms: bool) -> Callable[[T], T]:\n r\"\"\"A :func:`~discord.app_commands.check` that is added that checks if the member\n has all of the permissions necessary.\n\n Note that this check operates on the permissions given by\n :attr:`discord.Interaction.permissions`.\n\n The permissions passed in must be exactly like the properties shown under\n :class:`discord.Permissions`.\n\n This check raises a special exception, :exc:`~discord.app_commands.MissingPermissions`\n that is inherited from :exc:`~discord.app_commands.CheckFailure`.\n\n .. versionadded:: 2.0\n\n .. note::\n\n This is different from the permission system that Discord provides for application\n commands. This is done entirely locally in the program rather than being handled\n by Discord.\n\n Parameters\n ------------\n \\*\\*perms: :class:`bool`\n Keyword arguments denoting the permissions to check for.\n\n Example\n ---------\n\n .. code-block:: python3\n\n @tree.command()\n @app_commands.checks.has_permissions(manage_messages=True)\n async def test(interaction: discord.Interaction):\n await interaction.response.send_message('You can manage messages.')\n\n \"\"\"\n\n invalid = perms.keys() - Permissions.VALID_FLAGS.keys()\n if invalid:\n raise TypeError(f\"Invalid permission(s): {', '.join(invalid)}\")\n\n def predicate(interaction: Interaction) -> bool:\n permissions = interaction.permissions\n\n missing = [perm for perm, value in perms.items() if getattr(permissions, perm) != value]\n\n if not missing:\n return True\n\n raise MissingPermissions(missing)\n\n return check(predicate)\n\n\ndef bot_has_permissions(**perms: bool) -> Callable[[T], T]:\n \"\"\"Similar to :func:`has_permissions` except checks if the bot itself has\n the permissions listed. This relies on :attr:`discord.Interaction.app_permissions`.\n\n This check raises a special exception, :exc:`~discord.app_commands.BotMissingPermissions`\n that is inherited from :exc:`~discord.app_commands.CheckFailure`.\n\n .. versionadded:: 2.0\n \"\"\"\n\n invalid = set(perms) - set(Permissions.VALID_FLAGS)\n if invalid:\n raise TypeError(f\"Invalid permission(s): {', '.join(invalid)}\")\n\n def predicate(interaction: Interaction) -> bool:\n permissions = interaction.app_permissions\n missing = [perm for perm, value in perms.items() if getattr(permissions, perm) != value]\n\n if not missing:\n return True\n\n raise BotMissingPermissions(missing)\n\n return check(predicate)\n\n\ndef _create_cooldown_decorator(\n key: CooldownFunction[Hashable], factory: CooldownFunction[Optional[Cooldown]]\n) -> Callable[[T], T]:\n\n mapping: Dict[Any, Cooldown] = {}\n\n async def get_bucket(\n interaction: Interaction,\n *,\n mapping: Dict[Any, Cooldown] = mapping,\n key: CooldownFunction[Hashable] = key,\n factory: CooldownFunction[Optional[Cooldown]] = factory,\n ) -> Optional[Cooldown]:\n current = interaction.created_at.timestamp()\n dead_keys = [k for k, v in mapping.items() if current > v._last + v.per]\n for k in dead_keys:\n del mapping[k]\n\n k = await maybe_coroutine(key, interaction)\n if k not in mapping:\n bucket: Optional[Cooldown] = await maybe_coroutine(factory, interaction)\n if bucket is not None:\n mapping[k] = bucket\n else:\n bucket = mapping[k]\n\n return bucket\n\n async def predicate(interaction: Interaction) -> bool:\n bucket = await get_bucket(interaction)\n if bucket is None:\n return True\n\n retry_after = bucket.update_rate_limit(interaction.created_at.timestamp())\n if retry_after is None:\n return True\n\n raise CommandOnCooldown(bucket, retry_after)\n\n return check(predicate)\n\n\ndef cooldown(\n rate: float,\n per: float,\n *,\n key: Optional[CooldownFunction[Hashable]] = MISSING,\n) -> Callable[[T], T]:\n \"\"\"A decorator that adds a cooldown to a command.\n\n A cooldown allows a command to only be used a specific amount\n of times in a specific time frame. These cooldowns are based off\n of the ``key`` function provided. If a ``key`` is not provided\n then it defaults to a user-level cooldown. The ``key`` function\n must take a single parameter, the :class:`discord.Interaction` and\n return a value that is used as a key to the internal cooldown mapping.\n\n The ``key`` function can optionally be a coroutine.\n\n If a cooldown is triggered, then :exc:`~discord.app_commands.CommandOnCooldown` is\n raised to the error handlers.\n\n Examples\n ---------\n\n Setting a one per 5 seconds per member cooldown on a command:\n\n .. code-block:: python3\n\n @tree.command()\n @app_commands.checks.cooldown(1, 5.0, key=lambda i: (i.guild_id, i.user.id))\n async def test(interaction: discord.Interaction):\n await interaction.response.send_message('Hello')\n\n @test.error\n async def on_test_error(interaction: discord.Interaction, error: app_commands.AppCommandError):\n if isinstance(error, app_commands.CommandOnCooldown):\n await interaction.response.send_message(str(error), ephemeral=True)\n\n Parameters\n ------------\n rate: :class:`int`\n The number of times a command can be used before triggering a cooldown.\n per: :class:`float`\n The amount of seconds to wait for a cooldown when it's been triggered.\n key: Optional[Callable[[:class:`discord.Interaction`], :class:`collections.abc.Hashable`]]\n A function that returns a key to the mapping denoting the type of cooldown.\n Can optionally be a coroutine. If not given then defaults to a user-level\n cooldown. If ``None`` is passed then it is interpreted as a \"global\" cooldown.\n \"\"\"\n\n if key is MISSING:\n key_func = lambda interaction: interaction.user.id\n elif key is None:\n key_func = lambda i: None\n else:\n key_func = key\n\n factory = lambda interaction: Cooldown(rate, per)\n\n return _create_cooldown_decorator(key_func, factory)\n\n\ndef dynamic_cooldown(\n factory: CooldownFunction[Optional[Cooldown]],\n *,\n key: Optional[CooldownFunction[Hashable]] = MISSING,\n) -> Callable[[T], T]:\n \"\"\"A decorator that adds a dynamic cooldown to a command.\n\n A cooldown allows a command to only be used a specific amount\n of times in a specific time frame. These cooldowns are based off\n of the ``key`` function provided. If a ``key`` is not provided\n then it defaults to a user-level cooldown. The ``key`` function\n must take a single parameter, the :class:`discord.Interaction` and\n return a value that is used as a key to the internal cooldown mapping.\n\n If a ``factory`` function is given, it must be a function that\n accepts a single parameter of type :class:`discord.Interaction` and must\n return a :class:`~discord.app_commands.Cooldown` or ``None``.\n If ``None`` is returned then that cooldown is effectively bypassed.\n\n Both ``key`` and ``factory`` can optionally be coroutines.\n\n If a cooldown is triggered, then :exc:`~discord.app_commands.CommandOnCooldown` is\n raised to the error handlers.\n\n Examples\n ---------\n\n Setting a cooldown for everyone but the owner.\n\n .. code-block:: python3\n\n def cooldown_for_everyone_but_me(interaction: discord.Interaction) -> Optional[app_commands.Cooldown]:\n if interaction.user.id == 80088516616269824:\n return None\n return app_commands.Cooldown(1, 10.0)\n\n @tree.command()\n @app_commands.checks.dynamic_cooldown(cooldown_for_everyone_but_me)\n async def test(interaction: discord.Interaction):\n await interaction.response.send_message('Hello')\n\n @test.error\n async def on_test_error(interaction: discord.Interaction, error: app_commands.AppCommandError):\n if isinstance(error, app_commands.CommandOnCooldown):\n await interaction.response.send_message(str(error), ephemeral=True)\n\n Parameters\n ------------\n factory: Optional[Callable[[:class:`discord.Interaction`], Optional[:class:`~discord.app_commands.Cooldown`]]]\n A function that takes an interaction and returns a cooldown that will apply to that interaction\n or ``None`` if the interaction should not have a cooldown.\n key: Optional[Callable[[:class:`discord.Interaction`], :class:`collections.abc.Hashable`]]\n A function that returns a key to the mapping denoting the type of cooldown.\n Can optionally be a coroutine. If not given then defaults to a user-level\n cooldown. If ``None`` is passed then it is interpreted as a \"global\" cooldown.\n \"\"\"\n\n if key is MISSING:\n key_func = lambda interaction: interaction.user.id\n elif key is None:\n key_func = lambda i: None\n else:\n key_func = key\n\n return _create_cooldown_decorator(key_func, factory)\n" }, { "path": "discord/app_commands/commands.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\nimport inspect\n\nfrom typing import (\n Any,\n Callable,\n ClassVar,\n Coroutine,\n Dict,\n Generator,\n Generic,\n List,\n MutableMapping,\n Optional,\n Set,\n TYPE_CHECKING,\n Tuple,\n Type,\n TypeVar,\n Union,\n overload,\n)\n\nimport re\nfrom copy import copy as shallow_copy\n\nfrom ..enums import AppCommandOptionType, AppCommandType, ChannelType, Locale\nfrom .installs import AppCommandContext, AppInstallationType\nfrom .models import Choice\nfrom .transformers import annotation_to_parameter, CommandParameter, NoneType\nfrom .errors import AppCommandError, CheckFailure, CommandInvokeError, CommandSignatureMismatch, CommandAlreadyRegistered\nfrom .translator import TranslationContextLocation, TranslationContext, Translator, locale_str\nfrom ..message import Message\nfrom ..user import User\nfrom ..member import Member\nfrom ..permissions import Permissions\nfrom ..utils import resolve_annotation, MISSING, is_inside_class, maybe_coroutine, async_all, _shorten, _to_kebab_case\n\nif TYPE_CHECKING:\n from typing_extensions import ParamSpec, Concatenate\n from ..interactions import Interaction\n from ..abc import Snowflake\n from .namespace import Namespace\n from .models import ChoiceT\n from .tree import CommandTree\n from .._types import ClientT\n\n # Generally, these two libraries are supposed to be separate from each other.\n # However, for type hinting purposes it's unfortunately necessary for one to\n # reference the other to prevent type checking errors in callbacks\n from discord.ext import commands\n\n ErrorFunc = Callable[[Interaction, AppCommandError], Coroutine[Any, Any, None]]\n\n__all__ = (\n 'Command',\n 'ContextMenu',\n 'Group',\n 'Parameter',\n 'context_menu',\n 'command',\n 'describe',\n 'check',\n 'rename',\n 'choices',\n 'autocomplete',\n 'guilds',\n 'guild_only',\n 'dm_only',\n 'private_channel_only',\n 'allowed_contexts',\n 'guild_install',\n 'user_install',\n 'allowed_installs',\n 'default_permissions',\n)\n\nif TYPE_CHECKING:\n P = ParamSpec('P')\nelse:\n P = TypeVar('P')\n\nT = TypeVar('T')\nF = TypeVar('F', bound=Callable[..., Any])\nGroupT = TypeVar('GroupT', bound='Binding')\nCoro = Coroutine[Any, Any, T]\nUnboundError = Callable[['Interaction[Any]', AppCommandError], Coro[Any]]\nError = Union[\n Callable[[GroupT, 'Interaction[Any]', AppCommandError], Coro[Any]],\n UnboundError,\n]\nCheck = Callable[['Interaction[Any]'], Union[bool, Coro[bool]]]\nBinding = Union['Group', 'commands.Cog']\n\n\nif TYPE_CHECKING:\n CommandCallback = Union[\n Callable[Concatenate[GroupT, 'Interaction[Any]', P], Coro[T]],\n Callable[Concatenate['Interaction[Any]', P], Coro[T]],\n ]\n\n ContextMenuCallback = Union[\n # If groups end up support context menus these would be uncommented\n # Callable[[GroupT, 'Interaction', Member], Coro[Any]],\n # Callable[[GroupT, 'Interaction', User], Coro[Any]],\n # Callable[[GroupT, 'Interaction', Message], Coro[Any]],\n # Callable[[GroupT, 'Interaction', Union[Member, User]], Coro[Any]],\n Callable[['Interaction[Any]', Member], Coro[Any]],\n Callable[['Interaction[Any]', User], Coro[Any]],\n Callable[['Interaction[Any]', Message], Coro[Any]],\n Callable[['Interaction[Any]', Union[Member, User]], Coro[Any]],\n ]\n\n AutocompleteCallback = Union[\n Callable[[GroupT, 'Interaction[Any]', str], Coro[List[Choice[ChoiceT]]]],\n Callable[['Interaction[Any]', str], Coro[List[Choice[ChoiceT]]]],\n ]\nelse:\n CommandCallback = Callable[..., Coro[T]]\n ContextMenuCallback = Callable[..., Coro[T]]\n AutocompleteCallback = Callable[..., Coro[T]]\n\n\nCheckInputParameter = Union['Command[Any, ..., Any]', 'ContextMenu', 'CommandCallback[Any, ..., Any]', ContextMenuCallback]\n\n# The re module doesn't support \\p{} so we have to list characters from Thai and Devanagari manually.\nTHAI_COMBINING = r'\\u0e31-\\u0e3a\\u0e47-\\u0e4e'\nDEVANAGARI_COMBINING = r'\\u0900-\\u0903\\u093a\\u093b\\u093c\\u093e\\u093f\\u0940-\\u094f\\u0955\\u0956\\u0957\\u0962\\u0963'\nVALID_SLASH_COMMAND_NAME = re.compile(r'^[-_\\w' + THAI_COMBINING + DEVANAGARI_COMBINING + r']{1,32}$')\n\nARG_NAME_SUBREGEX = r'(?:\\\\?\\*){0,2}(?P\\w+)'\n\nARG_DESCRIPTION_SUBREGEX = r'(?P(?:.|\\n)+?(?:\\Z|\\r?\\n(?=[\\S\\r\\n])))'\n\nARG_TYPE_SUBREGEX = r'(?:.+)'\n\nGOOGLE_DOCSTRING_ARG_REGEX = re.compile(\n rf'^{ARG_NAME_SUBREGEX}[ \\t]*(?:\\({ARG_TYPE_SUBREGEX}\\))?[ \\t]*:[ \\t]*{ARG_DESCRIPTION_SUBREGEX}',\n re.MULTILINE,\n)\n\nSPHINX_DOCSTRING_ARG_REGEX = re.compile(\n rf'^:param {ARG_NAME_SUBREGEX}:[ \\t]+{ARG_DESCRIPTION_SUBREGEX}',\n re.MULTILINE,\n)\n\nNUMPY_DOCSTRING_ARG_REGEX = re.compile(\n rf'^{ARG_NAME_SUBREGEX}(?:[ \\t]*:)?(?:[ \\t]+{ARG_TYPE_SUBREGEX})?[ \\t]*\\r?\\n[ \\t]+{ARG_DESCRIPTION_SUBREGEX}',\n re.MULTILINE,\n)\n\n\ndef _parse_args_from_docstring(func: Callable[..., Any], params: Dict[str, CommandParameter]) -> Dict[str, str]:\n docstring = inspect.getdoc(func)\n\n if docstring is None:\n return {}\n\n # Extract the arguments\n # Note: These are loose regexes, but they are good enough for our purposes\n # For Google-style, look only at the lines that are indented\n section_lines = inspect.cleandoc('\\n'.join(line for line in docstring.splitlines() if line.startswith(' ')))\n docstring_styles = (\n GOOGLE_DOCSTRING_ARG_REGEX.finditer(section_lines),\n SPHINX_DOCSTRING_ARG_REGEX.finditer(docstring),\n NUMPY_DOCSTRING_ARG_REGEX.finditer(docstring),\n )\n\n return {\n m.group('name'): m.group('description') for matches in docstring_styles for m in matches if m.group('name') in params\n }\n\n\ndef validate_name(name: str) -> str:\n match = VALID_SLASH_COMMAND_NAME.match(name)\n if match is None:\n raise ValueError(\n f'{name!r} must be between 1-32 characters and contain only lower-case letters, numbers, hyphens, or underscores.'\n )\n\n # Ideally, name.islower() would work instead but since certain characters\n # are Lo (e.g. CJK) those don't pass the test. I'd use `casefold` instead as\n # well, but chances are the server-side check is probably something similar to\n # this code anyway.\n if name.lower() != name:\n raise ValueError(f'{name!r} must be all lower-case')\n return name\n\n\ndef validate_context_menu_name(name: str) -> str:\n if not name or len(name) > 32:\n raise ValueError('context menu names must be between 1-32 characters')\n return name\n\n\ndef validate_auto_complete_callback(\n callback: AutocompleteCallback[GroupT, ChoiceT]\n) -> AutocompleteCallback[GroupT, ChoiceT]:\n # This function needs to ensure the following is true:\n # If self.foo is passed then don't pass command.binding to the callback\n # If Class.foo is passed then it is assumed command.binding has to be passed\n # If free_function_foo is passed then no binding should be passed at all\n # Passing command.binding is mandated by pass_command_binding\n\n binding = getattr(callback, '__self__', None)\n pass_command_binding = binding is None and is_inside_class(callback)\n\n # 'method' objects can't have dynamic attributes\n if binding is None:\n callback.pass_command_binding = pass_command_binding\n\n required_parameters = 2 + pass_command_binding\n params = inspect.signature(callback).parameters\n if len(params) != required_parameters:\n raise TypeError(f'autocomplete callback {callback.__qualname__!r} requires either 2 or 3 parameters to be passed')\n\n return callback\n\n\ndef _context_menu_annotation(annotation: Any, *, _none: type = NoneType) -> AppCommandType:\n if annotation is Message:\n return AppCommandType.message\n\n supported_types: Set[Any] = {Member, User}\n if annotation in supported_types:\n return AppCommandType.user\n\n # Check if there's an origin\n origin = getattr(annotation, '__origin__', None)\n if origin is not Union:\n # Only Union is supported so bail early\n msg = (\n f'unsupported type annotation {annotation!r}, must be either discord.Member, '\n 'discord.User, discord.Message, or a typing.Union of discord.Member and discord.User'\n )\n raise TypeError(msg)\n\n # Only Union[Member, User] is supported\n if not all(arg in supported_types for arg in annotation.__args__):\n raise TypeError(f'unsupported types given inside {annotation!r}')\n\n return AppCommandType.user\n\n\ndef _populate_descriptions(params: Dict[str, CommandParameter], descriptions: Dict[str, Any]) -> None:\n for name, param in params.items():\n description = descriptions.pop(name, MISSING)\n if description is MISSING:\n param.description = '…'\n continue\n\n if not isinstance(description, (str, locale_str)):\n raise TypeError('description must be a string')\n\n if isinstance(description, str):\n param.description = _shorten(description)\n else:\n param.description = description\n\n if descriptions:\n first = next(iter(descriptions))\n raise TypeError(f'unknown parameter given: {first}')\n\n\ndef _populate_renames(params: Dict[str, CommandParameter], renames: Dict[str, Union[str, locale_str]]) -> None:\n rename_map: Dict[str, Union[str, locale_str]] = {}\n\n # original name to renamed name\n\n for name in params.keys():\n new_name = renames.pop(name, MISSING)\n\n if new_name is MISSING:\n rename_map[name] = name\n continue\n\n if name in rename_map:\n raise ValueError(f'{new_name} is already used')\n\n if isinstance(new_name, str):\n new_name = validate_name(new_name)\n else:\n validate_name(new_name.message)\n\n rename_map[name] = new_name\n params[name]._rename = new_name\n\n if renames:\n first = next(iter(renames))\n raise ValueError(f'unknown parameter given: {first}')\n\n\ndef _populate_choices(params: Dict[str, CommandParameter], all_choices: Dict[str, List[Choice]]) -> None:\n for name, param in params.items():\n choices = all_choices.pop(name, MISSING)\n if choices is MISSING:\n continue\n\n if not isinstance(choices, list):\n raise TypeError('choices must be a list of Choice')\n\n if not all(isinstance(choice, Choice) for choice in choices):\n raise TypeError('choices must be a list of Choice')\n\n if param.type not in (AppCommandOptionType.string, AppCommandOptionType.number, AppCommandOptionType.integer):\n raise TypeError('choices are only supported for integer, string, or number option types')\n\n if not all(param.type == choice._option_type for choice in choices):\n raise TypeError('choices must all have the same inner option type as the parameter choice type')\n\n param.choices = choices\n\n if all_choices:\n first = next(iter(all_choices))\n raise TypeError(f'unknown parameter given: {first}')\n\n\ndef _populate_autocomplete(params: Dict[str, CommandParameter], autocomplete: Dict[str, Any]) -> None:\n for name, param in params.items():\n callback = autocomplete.pop(name, MISSING)\n if callback is MISSING:\n continue\n\n if not inspect.iscoroutinefunction(callback):\n raise TypeError('autocomplete callback must be a coroutine function')\n\n if param.type not in (AppCommandOptionType.string, AppCommandOptionType.number, AppCommandOptionType.integer):\n raise TypeError('autocomplete is only supported for integer, string, or number option types')\n\n if param.is_choice_annotation():\n raise TypeError(\n 'Choice annotation unsupported for autocomplete parameters, consider using a regular annotation instead'\n )\n\n param.autocomplete = validate_auto_complete_callback(callback)\n\n if autocomplete:\n first = next(iter(autocomplete))\n raise TypeError(f'unknown parameter given: {first}')\n\n\ndef _extract_parameters_from_callback(func: Callable[..., Any], globalns: Dict[str, Any]) -> Dict[str, CommandParameter]:\n params = inspect.signature(func).parameters\n cache = {}\n required_params = is_inside_class(func) + 1\n if len(params) < required_params:\n raise TypeError(f'callback {func.__qualname__!r} must have more than {required_params - 1} parameter(s)')\n\n iterator = iter(params.values())\n for _ in range(0, required_params):\n next(iterator)\n\n parameters: List[CommandParameter] = []\n for parameter in iterator:\n if parameter.annotation is parameter.empty:\n raise TypeError(f'parameter {parameter.name!r} is missing a type annotation in callback {func.__qualname__!r}')\n\n resolved = resolve_annotation(parameter.annotation, globalns, globalns, cache)\n param = annotation_to_parameter(resolved, parameter)\n parameters.append(param)\n\n values = sorted(parameters, key=lambda a: a.required, reverse=True)\n result = {v.name: v for v in values}\n\n descriptions = _parse_args_from_docstring(func, result)\n\n try:\n descriptions.update(func.__discord_app_commands_param_description__)\n except AttributeError:\n for param in values:\n if param.description is MISSING:\n param.description = '…'\n if descriptions:\n _populate_descriptions(result, descriptions)\n\n try:\n renames = func.__discord_app_commands_param_rename__\n except AttributeError:\n pass\n else:\n _populate_renames(result, renames.copy())\n\n try:\n choices = func.__discord_app_commands_param_choices__\n except AttributeError:\n pass\n else:\n _populate_choices(result, choices.copy())\n\n try:\n autocomplete = func.__discord_app_commands_param_autocomplete__\n except AttributeError:\n pass\n else:\n _populate_autocomplete(result, autocomplete.copy())\n\n return result\n\n\ndef _get_context_menu_parameter(func: ContextMenuCallback) -> Tuple[str, Any, AppCommandType]:\n params = inspect.signature(func).parameters\n if is_inside_class(func) and not hasattr(func, '__self__'):\n raise TypeError('context menus cannot be defined inside a class')\n\n if len(params) != 2:\n msg = (\n f'context menu callback {func.__qualname__!r} requires 2 parameters, '\n 'the first one being the interaction and the other one explicitly '\n 'annotated with either discord.Message, discord.User, discord.Member, '\n 'or a typing.Union of discord.Member and discord.User'\n )\n raise TypeError(msg)\n\n iterator = iter(params.values())\n next(iterator) # skip interaction\n parameter = next(iterator)\n if parameter.annotation is parameter.empty:\n msg = (\n f'second parameter of context menu callback {func.__qualname__!r} must be explicitly '\n 'annotated with either discord.Message, discord.User, discord.Member, or '\n 'a typing.Union of discord.Member and discord.User'\n )\n raise TypeError(msg)\n\n resolved = resolve_annotation(parameter.annotation, func.__globals__, func.__globals__, {})\n type = _context_menu_annotation(resolved)\n return (parameter.name, resolved, type)\n\n\ndef mark_overrideable(func: F) -> F:\n func.__discord_app_commands_base_function__ = None\n return func\n\n\nclass Parameter:\n \"\"\"A class that contains the parameter information of a :class:`Command` callback.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n name: :class:`str`\n The name of the parameter. This is the Python identifier for the parameter.\n display_name: :class:`str`\n The displayed name of the parameter on Discord.\n description: :class:`str`\n The description of the parameter.\n autocomplete: :class:`bool`\n Whether the parameter has an autocomplete handler.\n locale_name: Optional[:class:`locale_str`]\n The display name's locale string, if available.\n locale_description: Optional[:class:`locale_str`]\n The description's locale string, if available.\n required: :class:`bool`\n Whether the parameter is required\n choices: List[:class:`~discord.app_commands.Choice`]\n A list of choices this parameter takes, if any.\n type: :class:`~discord.AppCommandOptionType`\n The underlying type of this parameter.\n channel_types: List[:class:`~discord.ChannelType`]\n The channel types that are allowed for this parameter.\n min_value: Optional[Union[:class:`int`, :class:`float`]]\n The minimum supported value for this parameter.\n max_value: Optional[Union[:class:`int`, :class:`float`]]\n The maximum supported value for this parameter.\n default: Any\n The default value of the parameter, if given.\n If not given then this is :data:`~discord.utils.MISSING`.\n command: :class:`Command`\n The command this parameter is attached to.\n \"\"\"\n\n def __init__(self, parent: CommandParameter, command: Command[Any, ..., Any]) -> None:\n self.__parent: CommandParameter = parent\n self.__command: Command[Any, ..., Any] = command\n\n @property\n def command(self) -> Command[Any, ..., Any]:\n return self.__command\n\n @property\n def name(self) -> str:\n return self.__parent.name\n\n @property\n def display_name(self) -> str:\n return self.__parent.display_name\n\n @property\n def required(self) -> bool:\n return self.__parent.required\n\n @property\n def description(self) -> str:\n return str(self.__parent.description)\n\n @property\n def locale_name(self) -> Optional[locale_str]:\n if isinstance(self.__parent._rename, locale_str):\n return self.__parent._rename\n return None\n\n @property\n def locale_description(self) -> Optional[locale_str]:\n if isinstance(self.__parent.description, locale_str):\n return self.__parent.description\n return None\n\n @property\n def autocomplete(self) -> bool:\n return self.__parent.autocomplete is not None\n\n @property\n def default(self) -> Any:\n return self.__parent.default\n\n @property\n def type(self) -> AppCommandOptionType:\n return self.__parent.type\n\n @property\n def choices(self) -> List[Choice[Union[int, float, str]]]:\n choices = self.__parent.choices\n if choices is MISSING:\n return []\n return choices.copy()\n\n @property\n def channel_types(self) -> List[ChannelType]:\n channel_types = self.__parent.channel_types\n if channel_types is MISSING:\n return []\n return channel_types.copy()\n\n @property\n def min_value(self) -> Optional[Union[int, float]]:\n return self.__parent.min_value\n\n @property\n def max_value(self) -> Optional[Union[int, float]]:\n return self.__parent.max_value\n\n\nclass Command(Generic[GroupT, P, T]):\n \"\"\"A class that implements an application command.\n\n These are usually not created manually, instead they are created using\n one of the following decorators:\n\n - :func:`~discord.app_commands.command`\n - :meth:`Group.command `\n - :meth:`CommandTree.command `\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n name: Union[:class:`str`, :class:`locale_str`]\n The name of the application command.\n description: Union[:class:`str`, :class:`locale_str`]\n The description of the application command. This shows up in the UI to describe\n the application command.\n callback: :ref:`coroutine `\n The coroutine that is executed when the command is called.\n auto_locale_strings: :class:`bool`\n If this is set to ``True``, then all translatable strings will implicitly\n be wrapped into :class:`locale_str` rather than :class:`str`. This could\n avoid some repetition and be more ergonomic for certain defaults such\n as default command names, command descriptions, and parameter names.\n Defaults to ``True``.\n nsfw: :class:`bool`\n Whether the command is NSFW and should only work in NSFW channels.\n Defaults to ``False``.\n\n Due to a Discord limitation, this does not work on subcommands.\n parent: Optional[:class:`Group`]\n The parent application command. ``None`` if there isn't one.\n extras: :class:`dict`\n A dictionary that can be used to store extraneous data.\n The library will not touch any values or keys within this dictionary.\n\n Attributes\n ------------\n name: :class:`str`\n The name of the application command.\n description: :class:`str`\n The description of the application command. This shows up in the UI to describe\n the application command.\n checks\n A list of predicates that take a :class:`~discord.Interaction` parameter\n to indicate whether the command callback should be executed. If an exception\n is necessary to be thrown to signal failure, then one inherited from\n :exc:`AppCommandError` should be used. If all the checks fail without\n propagating an exception, :exc:`CheckFailure` is raised.\n default_permissions: Optional[:class:`~discord.Permissions`]\n The default permissions that can execute this command on Discord. Note\n that server administrators can override this value in the client.\n Setting an empty permissions field will disallow anyone except server\n administrators from using the command in a guild.\n\n Due to a Discord limitation, this does not work on subcommands.\n guild_only: :class:`bool`\n Whether the command should only be usable in guild contexts.\n\n Due to a Discord limitation, this does not work on subcommands.\n allowed_contexts: Optional[:class:`~discord.app_commands.AppCommandContext`]\n The contexts that the command is allowed to be used in.\n Overrides ``guild_only`` if this is set.\n\n .. versionadded:: 2.4\n allowed_installs: Optional[:class:`~discord.app_commands.AppInstallationType`]\n The installation contexts that the command is allowed to be installed\n on.\n\n .. versionadded:: 2.4\n nsfw: :class:`bool`\n Whether the command is NSFW and should only work in NSFW channels.\n\n Due to a Discord limitation, this does not work on subcommands.\n parent: Optional[:class:`Group`]\n The parent application command. ``None`` if there isn't one.\n extras: :class:`dict`\n A dictionary that can be used to store extraneous data.\n The library will not touch any values or keys within this dictionary.\n \"\"\"\n\n def __init__(\n self,\n *,\n name: Union[str, locale_str],\n description: Union[str, locale_str],\n callback: CommandCallback[GroupT, P, T],\n nsfw: bool = False,\n parent: Optional[Group] = None,\n guild_ids: Optional[List[int]] = None,\n allowed_contexts: Optional[AppCommandContext] = None,\n allowed_installs: Optional[AppInstallationType] = None,\n auto_locale_strings: bool = True,\n extras: Dict[Any, Any] = MISSING,\n ):\n name, locale = (name.message, name) if isinstance(name, locale_str) else (name, None)\n self.name: str = validate_name(name)\n self._locale_name: Optional[locale_str] = locale\n description, locale = (\n (description.message, description) if isinstance(description, locale_str) else (description, None)\n )\n self.description: str = description\n self._locale_description: Optional[locale_str] = locale\n self._attr: Optional[str] = None\n self._callback: CommandCallback[GroupT, P, T] = callback\n self.parent: Optional[Group] = parent\n self.binding: Optional[GroupT] = None\n self.on_error: Optional[Error[GroupT]] = None\n self.module: Optional[str] = callback.__module__\n\n # Unwrap __self__ for bound methods\n try:\n self.binding = callback.__self__\n self._callback = callback = callback.__func__\n except AttributeError:\n pass\n\n self._params: Dict[str, CommandParameter] = _extract_parameters_from_callback(callback, callback.__globals__)\n self.checks: List[Check] = getattr(callback, '__discord_app_commands_checks__', [])\n self._guild_ids: Optional[List[int]] = guild_ids or getattr(\n callback, '__discord_app_commands_default_guilds__', None\n )\n self.default_permissions: Optional[Permissions] = getattr(\n callback, '__discord_app_commands_default_permissions__', None\n )\n self.guild_only: bool = getattr(callback, '__discord_app_commands_guild_only__', False)\n self.allowed_contexts: Optional[AppCommandContext] = allowed_contexts or getattr(\n callback, '__discord_app_commands_contexts__', None\n )\n self.allowed_installs: Optional[AppInstallationType] = allowed_installs or getattr(\n callback, '__discord_app_commands_installation_types__', None\n )\n\n self.nsfw: bool = nsfw\n self.extras: Dict[Any, Any] = extras or {}\n\n if self._guild_ids is not None and self.parent is not None:\n raise ValueError('child commands cannot have default guilds set, consider setting them in the parent instead')\n\n if auto_locale_strings:\n self._convert_to_locale_strings()\n\n def _convert_to_locale_strings(self) -> None:\n if self._locale_name is None:\n self._locale_name = locale_str(self.name)\n if self._locale_description is None:\n self._locale_description = locale_str(self.description)\n\n for param in self._params.values():\n param._convert_to_locale_strings()\n\n def __set_name__(self, owner: Type[Any], name: str) -> None:\n self._attr = name\n\n @property\n def callback(self) -> CommandCallback[GroupT, P, T]:\n \"\"\":ref:`coroutine `: The coroutine that is executed when the command is called.\"\"\"\n return self._callback\n\n def _copy_with(\n self,\n *,\n parent: Optional[Group],\n binding: GroupT,\n bindings: MutableMapping[GroupT, GroupT] = MISSING,\n set_on_binding: bool = True,\n ) -> Command:\n bindings = {} if bindings is MISSING else bindings\n\n copy = shallow_copy(self)\n copy._params = self._params.copy()\n copy.parent = parent\n copy.binding = bindings.get(self.binding) if self.binding is not None else binding\n\n if copy._attr and set_on_binding:\n setattr(copy.binding, copy._attr, copy)\n\n return copy\n\n async def get_translated_payload(self, tree: CommandTree[ClientT], translator: Translator) -> Dict[str, Any]:\n base = self.to_dict(tree)\n name_localizations: Dict[str, str] = {}\n description_localizations: Dict[str, str] = {}\n\n # Prevent creating these objects in a heavy loop\n name_context = TranslationContext(location=TranslationContextLocation.command_name, data=self)\n description_context = TranslationContext(location=TranslationContextLocation.command_description, data=self)\n\n for locale in Locale:\n if self._locale_name:\n translation = await translator._checked_translate(self._locale_name, locale, name_context)\n if translation is not None:\n name_localizations[locale.value] = translation\n\n if self._locale_description:\n translation = await translator._checked_translate(self._locale_description, locale, description_context)\n if translation is not None:\n description_localizations[locale.value] = translation\n\n base['name_localizations'] = name_localizations\n base['description_localizations'] = description_localizations\n base['options'] = [\n await param.get_translated_payload(translator, Parameter(param, self)) for param in self._params.values()\n ]\n return base\n\n def to_dict(self, tree: CommandTree[ClientT]) -> Dict[str, Any]:\n # If we have a parent then our type is a subcommand\n # Otherwise, the type falls back to the specific command type (e.g. slash command or context menu)\n option_type = AppCommandType.chat_input.value if self.parent is None else AppCommandOptionType.subcommand.value\n base: Dict[str, Any] = {\n 'name': self.name,\n 'description': self.description,\n 'type': option_type,\n 'options': [param.to_dict() for param in self._params.values()],\n }\n\n if self.parent is None:\n base['nsfw'] = self.nsfw\n base['dm_permission'] = not self.guild_only\n base['default_member_permissions'] = None if self.default_permissions is None else self.default_permissions.value\n base['contexts'] = tree.allowed_contexts._merge_to_array(self.allowed_contexts)\n base['integration_types'] = tree.allowed_installs._merge_to_array(self.allowed_installs)\n\n return base\n\n async def _invoke_error_handlers(self, interaction: Interaction, error: AppCommandError) -> None:\n # These type ignores are because the type checker can't narrow this type properly.\n if self.on_error is not None:\n if self.binding is not None:\n await self.on_error(self.binding, interaction, error) # type: ignore\n else:\n await self.on_error(interaction, error) # type: ignore\n\n parent = self.parent\n if parent is not None:\n await parent.on_error(interaction, error)\n\n if parent.parent is not None:\n await parent.parent.on_error(interaction, error)\n\n binding_error_handler = getattr(self.binding, '__discord_app_commands_error_handler__', None)\n if binding_error_handler is not None:\n await binding_error_handler(interaction, error)\n\n def _has_any_error_handlers(self) -> bool:\n if self.on_error is not None:\n return True\n\n parent = self.parent\n if parent is not None:\n # Check if the on_error is overridden\n if not hasattr(parent.on_error, '__discord_app_commands_base_function__'):\n return True\n\n if parent.parent is not None:\n if not hasattr(parent.parent.on_error, '__discord_app_commands_base_function__'):\n return True\n\n # Check if we have a bound error handler\n if getattr(self.binding, '__discord_app_commands_error_handler__', None) is not None:\n return True\n\n return False\n\n async def _transform_arguments(self, interaction: Interaction, namespace: Namespace) -> Dict[str, Any]:\n values = namespace.__dict__\n transformed_values = {}\n\n for param in self._params.values():\n try:\n value = values[param.display_name]\n except KeyError:\n if not param.required:\n transformed_values[param.name] = param.default\n else:\n raise CommandSignatureMismatch(self) from None\n else:\n transformed_values[param.name] = await param.transform(interaction, value)\n\n return transformed_values\n\n async def _do_call(self, interaction: Interaction, params: Dict[str, Any]) -> T:\n # These type ignores are because the type checker doesn't quite understand the narrowing here\n # Likewise, it thinks we're missing positional arguments when there aren't any.\n try:\n if self.binding is not None:\n return await self._callback(self.binding, interaction, **params) # type: ignore\n return await self._callback(interaction, **params) # type: ignore\n except TypeError as e:\n # In order to detect mismatch from the provided signature and the Discord data,\n # there are many ways it can go wrong yet all of them eventually lead to a TypeError\n # from the Python compiler showcasing that the signature is incorrect. This lovely\n # piece of code essentially checks the last frame of the caller and checks if the\n # locals contains our `self` reference.\n #\n # This is because there is a possibility that a TypeError is raised within the body\n # of the function, and in that case the locals wouldn't contain a reference to\n # the command object under the name `self`.\n frame = inspect.trace()[-1].frame\n if frame.f_locals.get('self') is self:\n raise CommandSignatureMismatch(self) from None\n raise CommandInvokeError(self, e) from e\n except AppCommandError:\n raise\n except Exception as e:\n raise CommandInvokeError(self, e) from e\n\n async def _invoke_with_namespace(self, interaction: Interaction, namespace: Namespace) -> T:\n if not await self._check_can_run(interaction):\n raise CheckFailure(f'The check functions for command {self.name!r} failed.')\n\n transformed_values = await self._transform_arguments(interaction, namespace)\n return await self._do_call(interaction, transformed_values)\n\n async def _invoke_autocomplete(self, interaction: Interaction, name: str, namespace: Namespace):\n # The namespace contains the Discord provided names so this will be fine\n # even if the name is renamed\n value = namespace.__dict__[name]\n\n try:\n param = self._params[name]\n except KeyError:\n # Slow case, it might be a rename\n params = {param.display_name: param for param in self._params.values()}\n try:\n param = params[name]\n except KeyError:\n raise CommandSignatureMismatch(self) from None\n\n if param.autocomplete is None:\n raise CommandSignatureMismatch(self)\n\n predicates = getattr(param.autocomplete, '__discord_app_commands_checks__', [])\n if predicates:\n try:\n passed = await async_all(f(interaction) for f in predicates)\n except Exception:\n passed = False\n\n if not passed:\n if not interaction.response.is_done():\n await interaction.response.autocomplete([])\n return\n\n if getattr(param.autocomplete, 'pass_command_binding', False):\n binding = self.binding\n if binding is not None:\n choices = await param.autocomplete(binding, interaction, value)\n else:\n raise TypeError('autocomplete parameter expected a bound self parameter but one was not provided')\n else:\n choices = await param.autocomplete(interaction, value)\n\n if interaction.response.is_done():\n return\n\n await interaction.response.autocomplete(choices)\n\n def _get_internal_command(self, name: str) -> Optional[Union[Command, Group]]:\n return None\n\n @property\n def parameters(self) -> List[Parameter]:\n \"\"\"Returns a list of parameters for this command.\n\n This does not include the ``self`` or ``interaction`` parameters.\n\n Returns\n --------\n List[:class:`Parameter`]\n The parameters of this command.\n \"\"\"\n return [Parameter(p, self) for p in self._params.values()]\n\n def get_parameter(self, name: str) -> Optional[Parameter]:\n \"\"\"Retrieves a parameter by its name.\n\n The name must be the Python identifier rather than the renamed\n one for display on Discord.\n\n Parameters\n -----------\n name: :class:`str`\n The parameter name in the callback function.\n\n Returns\n --------\n Optional[:class:`Parameter`]\n The parameter or ``None`` if not found.\n \"\"\"\n\n parent = self._params.get(name)\n if parent is not None:\n return Parameter(parent, self)\n return None\n\n @property\n def root_parent(self) -> Optional[Group]:\n \"\"\"Optional[:class:`Group`]: The root parent of this command.\"\"\"\n if self.parent is None:\n return None\n parent = self.parent\n return parent.parent or parent\n\n @property\n def qualified_name(self) -> str:\n \"\"\":class:`str`: Returns the fully qualified command name.\n\n The qualified name includes the parent name as well. For example,\n in a command like ``/foo bar`` the qualified name is ``foo bar``.\n \"\"\"\n # A B C\n # ^ self\n # ^ parent\n # ^ grandparent\n if self.parent is None:\n return self.name\n\n names = [self.name, self.parent.name]\n grandparent = self.parent.parent\n if grandparent is not None:\n names.append(grandparent.name)\n\n return ' '.join(reversed(names))\n\n async def _check_can_run(self, interaction: Interaction) -> bool:\n if self.parent is not None and self.parent is not self.binding:\n # For commands with a parent which isn't the binding, i.e.\n # \n # \n # \n # The parent check needs to be called first\n if not await maybe_coroutine(self.parent.interaction_check, interaction):\n return False\n\n if self.binding is not None:\n check: Optional[Check] = getattr(self.binding, 'interaction_check', None)\n if check:\n ret = await maybe_coroutine(check, interaction)\n if not ret:\n return False\n\n predicates = self.checks\n if not predicates:\n return True\n\n return await async_all(f(interaction) for f in predicates)\n\n def error(self, coro: Error[GroupT]) -> Error[GroupT]:\n \"\"\"A decorator that registers a coroutine as a local error handler.\n\n The local error handler is called whenever an exception is raised in the body\n of the command or during handling of the command. The error handler must take\n 2 parameters, the interaction and the error.\n\n The error passed will be derived from :exc:`AppCommandError`.\n\n Parameters\n -----------\n coro: :ref:`coroutine `\n The coroutine to register as the local error handler.\n\n Raises\n -------\n TypeError\n The coroutine passed is not actually a coroutine.\n \"\"\"\n\n if not inspect.iscoroutinefunction(coro):\n raise TypeError('The error handler must be a coroutine.')\n\n self.on_error = coro\n return coro\n\n def autocomplete(\n self, name: str\n ) -> Callable[[AutocompleteCallback[GroupT, ChoiceT]], AutocompleteCallback[GroupT, ChoiceT]]:\n \"\"\"A decorator that registers a coroutine as an autocomplete prompt for a parameter.\n\n The coroutine callback must have 2 parameters, the :class:`~discord.Interaction`,\n and the current value by the user (the string currently being typed by the user).\n\n To get the values from other parameters that may be filled in, accessing\n :attr:`.Interaction.namespace` will give a :class:`Namespace` object with those\n values.\n\n Parent :func:`checks ` are ignored within an autocomplete. However, checks can be added\n to the autocomplete callback and the ones added will be called. If the checks fail for any reason\n then an empty list is sent as the interaction response.\n\n The coroutine decorator **must** return a list of :class:`~discord.app_commands.Choice` objects.\n Only up to 25 objects are supported.\n\n .. warning::\n The choices returned from this coroutine are suggestions. The user may ignore them and input their own value.\n\n Example:\n\n .. code-block:: python3\n\n @app_commands.command()\n async def fruits(interaction: discord.Interaction, fruit: str):\n await interaction.response.send_message(f'Your favourite fruit seems to be {fruit}')\n\n @fruits.autocomplete('fruit')\n async def fruits_autocomplete(\n interaction: discord.Interaction,\n current: str,\n ) -> List[app_commands.Choice[str]]:\n fruits = ['Banana', 'Pineapple', 'Apple', 'Watermelon', 'Melon', 'Cherry']\n return [\n app_commands.Choice(name=fruit, value=fruit)\n for fruit in fruits if current.lower() in fruit.lower()\n ]\n\n\n Parameters\n -----------\n name: :class:`str`\n The parameter name to register as autocomplete.\n\n Raises\n -------\n TypeError\n The coroutine passed is not actually a coroutine or\n the parameter is not found or of an invalid type.\n \"\"\"\n\n def decorator(coro: AutocompleteCallback[GroupT, ChoiceT]) -> AutocompleteCallback[GroupT, ChoiceT]:\n if not inspect.iscoroutinefunction(coro):\n raise TypeError('The autocomplete callback must be a coroutine function.')\n\n try:\n param = self._params[name]\n except KeyError:\n raise TypeError(f'unknown parameter: {name!r}') from None\n\n if param.type not in (AppCommandOptionType.string, AppCommandOptionType.number, AppCommandOptionType.integer):\n raise TypeError('autocomplete is only supported for integer, string, or number option types')\n\n if param.is_choice_annotation():\n raise TypeError(\n 'Choice annotation unsupported for autocomplete parameters, consider using a regular annotation instead'\n )\n\n param.autocomplete = validate_auto_complete_callback(coro)\n return coro\n\n return decorator\n\n def add_check(self, func: Check, /) -> None:\n \"\"\"Adds a check to the command.\n\n This is the non-decorator interface to :func:`check`.\n\n Parameters\n -----------\n func\n The function that will be used as a check.\n \"\"\"\n\n self.checks.append(func)\n\n def remove_check(self, func: Check, /) -> None:\n \"\"\"Removes a check from the command.\n\n This function is idempotent and will not raise an exception\n if the function is not in the command's checks.\n\n Parameters\n -----------\n func\n The function to remove from the checks.\n \"\"\"\n\n try:\n self.checks.remove(func)\n except ValueError:\n pass\n\n\nclass ContextMenu:\n \"\"\"A class that implements a context menu application command.\n\n These are usually not created manually, instead they are created using\n one of the following decorators:\n\n - :func:`~discord.app_commands.context_menu`\n - :meth:`CommandTree.context_menu `\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n name: Union[:class:`str`, :class:`locale_str`]\n The name of the context menu.\n callback: :ref:`coroutine `\n The coroutine that is executed when the command is called.\n type: :class:`.AppCommandType`\n The type of context menu application command. By default, this is inferred\n by the parameter of the callback.\n auto_locale_strings: :class:`bool`\n If this is set to ``True``, then all translatable strings will implicitly\n be wrapped into :class:`locale_str` rather than :class:`str`. This could\n avoid some repetition and be more ergonomic for certain defaults such\n as default command names, command descriptions, and parameter names.\n Defaults to ``True``.\n nsfw: :class:`bool`\n Whether the command is NSFW and should only work in NSFW channels.\n Defaults to ``False``.\n extras: :class:`dict`\n A dictionary that can be used to store extraneous data.\n The library will not touch any values or keys within this dictionary.\n\n Attributes\n ------------\n name: :class:`str`\n The name of the context menu.\n type: :class:`.AppCommandType`\n The type of context menu application command. By default, this is inferred\n by the parameter of the callback.\n default_permissions: Optional[:class:`~discord.Permissions`]\n The default permissions that can execute this command on Discord. Note\n that server administrators can override this value in the client.\n Setting an empty permissions field will disallow anyone except server\n administrators from using the command in a guild.\n guild_only: :class:`bool`\n Whether the command should only be usable in guild contexts.\n Defaults to ``False``.\n allowed_contexts: Optional[:class:`~discord.app_commands.AppCommandContext`]\n The contexts that this context menu is allowed to be used in.\n Overrides ``guild_only`` if set.\n\n .. versionadded:: 2.4\n allowed_installs: Optional[:class:`~discord.app_commands.AppInstallationType`]\n The installation contexts that the command is allowed to be installed\n on.\n\n .. versionadded:: 2.4\n nsfw: :class:`bool`\n Whether the command is NSFW and should only work in NSFW channels.\n Defaults to ``False``.\n checks\n A list of predicates that take a :class:`~discord.Interaction` parameter\n to indicate whether the command callback should be executed. If an exception\n is necessary to be thrown to signal failure, then one inherited from\n :exc:`AppCommandError` should be used. If all the checks fail without\n propagating an exception, :exc:`CheckFailure` is raised.\n extras: :class:`dict`\n A dictionary that can be used to store extraneous data.\n The library will not touch any values or keys within this dictionary.\n \"\"\"\n\n def __init__(\n self,\n *,\n name: Union[str, locale_str],\n callback: ContextMenuCallback,\n type: AppCommandType = MISSING,\n nsfw: bool = False,\n guild_ids: Optional[List[int]] = None,\n allowed_contexts: Optional[AppCommandContext] = None,\n allowed_installs: Optional[AppInstallationType] = None,\n auto_locale_strings: bool = True,\n extras: Dict[Any, Any] = MISSING,\n ):\n name, locale = (name.message, name) if isinstance(name, locale_str) else (name, None)\n self.name: str = validate_context_menu_name(name)\n self._locale_name: Optional[locale_str] = locale\n self._callback: ContextMenuCallback = callback\n (param, annotation, actual_type) = _get_context_menu_parameter(callback)\n if type is MISSING:\n type = actual_type\n\n if actual_type != type:\n raise ValueError(f'context menu callback implies a type of {actual_type} but {type} was passed.')\n\n self.type: AppCommandType = type\n self._param_name = param\n self._annotation = annotation\n self.module: Optional[str] = callback.__module__\n self._guild_ids = guild_ids or getattr(callback, '__discord_app_commands_default_guilds__', None)\n self.on_error: Optional[UnboundError] = None\n self.default_permissions: Optional[Permissions] = getattr(\n callback, '__discord_app_commands_default_permissions__', None\n )\n self.nsfw: bool = nsfw\n self.guild_only: bool = getattr(callback, '__discord_app_commands_guild_only__', False)\n self.allowed_contexts: Optional[AppCommandContext] = allowed_contexts or getattr(\n callback, '__discord_app_commands_contexts__', None\n )\n self.allowed_installs: Optional[AppInstallationType] = allowed_installs or getattr(\n callback, '__discord_app_commands_installation_types__', None\n )\n self.checks: List[Check] = getattr(callback, '__discord_app_commands_checks__', [])\n self.extras: Dict[Any, Any] = extras or {}\n\n if auto_locale_strings:\n if self._locale_name is None:\n self._locale_name = locale_str(self.name)\n\n @property\n def callback(self) -> ContextMenuCallback:\n \"\"\":ref:`coroutine `: The coroutine that is executed when the context menu is called.\"\"\"\n return self._callback\n\n @property\n def qualified_name(self) -> str:\n \"\"\":class:`str`: Returns the fully qualified command name.\"\"\"\n return self.name\n\n async def get_translated_payload(self, tree: CommandTree[ClientT], translator: Translator) -> Dict[str, Any]:\n base = self.to_dict(tree)\n context = TranslationContext(location=TranslationContextLocation.command_name, data=self)\n if self._locale_name:\n name_localizations: Dict[str, str] = {}\n for locale in Locale:\n translation = await translator._checked_translate(self._locale_name, locale, context)\n if translation is not None:\n name_localizations[locale.value] = translation\n\n base['name_localizations'] = name_localizations\n return base\n\n def to_dict(self, tree: CommandTree[ClientT]) -> Dict[str, Any]:\n return {\n 'name': self.name,\n 'type': self.type.value,\n 'dm_permission': not self.guild_only,\n 'contexts': tree.allowed_contexts._merge_to_array(self.allowed_contexts),\n 'integration_types': tree.allowed_installs._merge_to_array(self.allowed_installs),\n 'default_member_permissions': None if self.default_permissions is None else self.default_permissions.value,\n 'nsfw': self.nsfw,\n }\n\n async def _check_can_run(self, interaction: Interaction) -> bool:\n predicates = self.checks\n if not predicates:\n return True\n\n return await async_all(f(interaction) for f in predicates)\n\n def _has_any_error_handlers(self) -> bool:\n return self.on_error is not None\n\n async def _invoke(self, interaction: Interaction, arg: Any):\n try:\n if not await self._check_can_run(interaction):\n raise CheckFailure(f'The check functions for context menu {self.name!r} failed.')\n\n await self._callback(interaction, arg)\n except AppCommandError:\n raise\n except Exception as e:\n raise CommandInvokeError(self, e) from e\n\n def error(self, coro: UnboundError) -> UnboundError:\n \"\"\"A decorator that registers a coroutine as a local error handler.\n\n The local error handler is called whenever an exception is raised in the body\n of the command or during handling of the command. The error handler must take\n 2 parameters, the interaction and the error.\n\n The error passed will be derived from :exc:`AppCommandError`.\n\n Parameters\n -----------\n coro: :ref:`coroutine `\n The coroutine to register as the local error handler.\n\n Raises\n -------\n TypeError\n The coroutine passed is not actually a coroutine.\n \"\"\"\n\n if not inspect.iscoroutinefunction(coro):\n raise TypeError('The error handler must be a coroutine.')\n\n self.on_error = coro\n return coro\n\n def add_check(self, func: Check, /) -> None:\n \"\"\"Adds a check to the command.\n\n This is the non-decorator interface to :func:`check`.\n\n Parameters\n -----------\n func\n The function that will be used as a check.\n \"\"\"\n\n self.checks.append(func)\n\n def remove_check(self, func: Check, /) -> None:\n \"\"\"Removes a check from the command.\n\n This function is idempotent and will not raise an exception\n if the function is not in the command's checks.\n\n Parameters\n -----------\n func\n The function to remove from the checks.\n \"\"\"\n\n try:\n self.checks.remove(func)\n except ValueError:\n pass\n\n\nclass Group:\n \"\"\"A class that implements an application command group.\n\n These are usually inherited rather than created manually.\n\n Decorators such as :func:`guild_only`, :func:`guilds`, and :func:`default_permissions`\n will apply to the group if used on top of a subclass. For example:\n\n .. code-block:: python3\n\n from discord import app_commands\n\n @app_commands.guild_only()\n class MyGroup(app_commands.Group):\n pass\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n name: Union[:class:`str`, :class:`locale_str`]\n The name of the group. If not given, it defaults to a lower-case\n kebab-case version of the class name.\n description: Union[:class:`str`, :class:`locale_str`]\n The description of the group. This shows up in the UI to describe\n the group. If not given, it defaults to the docstring of the\n class shortened to 100 characters.\n auto_locale_strings: :class:`bool`\n If this is set to ``True``, then all translatable strings will implicitly\n be wrapped into :class:`locale_str` rather than :class:`str`. This could\n avoid some repetition and be more ergonomic for certain defaults such\n as default command names, command descriptions, and parameter names.\n Defaults to ``True``.\n default_permissions: Optional[:class:`~discord.Permissions`]\n The default permissions that can execute this group on Discord. Note\n that server administrators can override this value in the client.\n Setting an empty permissions field will disallow anyone except server\n administrators from using the command in a guild.\n\n Due to a Discord limitation, this does not work on subcommands.\n guild_only: :class:`bool`\n Whether the group should only be usable in guild contexts.\n Defaults to ``False``.\n\n Due to a Discord limitation, this does not work on subcommands.\n nsfw: :class:`bool`\n Whether the command is NSFW and should only work in NSFW channels.\n Defaults to ``False``.\n\n Due to a Discord limitation, this does not work on subcommands.\n parent: Optional[:class:`Group`]\n The parent application command. ``None`` if there isn't one.\n extras: :class:`dict`\n A dictionary that can be used to store extraneous data.\n The library will not touch any values or keys within this dictionary.\n\n Attributes\n ------------\n name: :class:`str`\n The name of the group.\n description: :class:`str`\n The description of the group. This shows up in the UI to describe\n the group.\n default_permissions: Optional[:class:`~discord.Permissions`]\n The default permissions that can execute this group on Discord. Note\n that server administrators can override this value in the client.\n Setting an empty permissions field will disallow anyone except server\n administrators from using the command in a guild.\n\n Due to a Discord limitation, this does not work on subcommands.\n guild_only: :class:`bool`\n Whether the group should only be usable in guild contexts.\n\n Due to a Discord limitation, this does not work on subcommands.\n allowed_contexts: Optional[:class:`~discord.app_commands.AppCommandContext`]\n The contexts that this group is allowed to be used in. Overrides\n guild_only if set.\n\n .. versionadded:: 2.4\n allowed_installs: Optional[:class:`~discord.app_commands.AppInstallationType`]\n The installation contexts that the command is allowed to be installed\n on.\n\n .. versionadded:: 2.4\n nsfw: :class:`bool`\n Whether the command is NSFW and should only work in NSFW channels.\n\n Due to a Discord limitation, this does not work on subcommands.\n parent: Optional[:class:`Group`]\n The parent group. ``None`` if there isn't one.\n extras: :class:`dict`\n A dictionary that can be used to store extraneous data.\n The library will not touch any values or keys within this dictionary.\n \"\"\"\n\n __discord_app_commands_group_children__: ClassVar[List[Union[Command[Any, ..., Any], Group]]] = []\n __discord_app_commands_skip_init_binding__: bool = False\n __discord_app_commands_group_name__: str = MISSING\n __discord_app_commands_group_description__: str = MISSING\n __discord_app_commands_group_locale_name__: Optional[locale_str] = None\n __discord_app_commands_group_locale_description__: Optional[locale_str] = None\n __discord_app_commands_group_nsfw__: bool = False\n __discord_app_commands_guild_only__: bool = MISSING\n __discord_app_commands_contexts__: Optional[AppCommandContext] = MISSING\n __discord_app_commands_installation_types__: Optional[AppInstallationType] = MISSING\n __discord_app_commands_default_permissions__: Optional[Permissions] = MISSING\n __discord_app_commands_has_module__: bool = False\n __discord_app_commands_error_handler__: Optional[\n Callable[[Interaction, AppCommandError], Coroutine[Any, Any, None]]\n ] = None\n\n def __init_subclass__(\n cls,\n *,\n name: Union[str, locale_str] = MISSING,\n description: Union[str, locale_str] = MISSING,\n guild_only: bool = MISSING,\n nsfw: bool = False,\n default_permissions: Optional[Permissions] = MISSING,\n ) -> None:\n if not cls.__discord_app_commands_group_children__:\n children: List[Union[Command[Any, ..., Any], Group]] = [\n member for member in cls.__dict__.values() if isinstance(member, (Group, Command)) and member.parent is None\n ]\n\n cls.__discord_app_commands_group_children__ = children\n\n found = set()\n for child in children:\n if child.name in found:\n raise TypeError(f'Command {child.name!r} is a duplicate')\n found.add(child.name)\n\n if len(children) > 25:\n raise TypeError('groups cannot have more than 25 commands')\n\n if name is MISSING:\n cls.__discord_app_commands_group_name__ = validate_name(_to_kebab_case(cls.__name__))\n elif isinstance(name, str):\n cls.__discord_app_commands_group_name__ = validate_name(name)\n else:\n cls.__discord_app_commands_group_name__ = validate_name(name.message)\n cls.__discord_app_commands_group_locale_name__ = name\n\n if description is MISSING:\n if cls.__doc__ is None:\n cls.__discord_app_commands_group_description__ = '…'\n else:\n cls.__discord_app_commands_group_description__ = _shorten(cls.__doc__)\n elif isinstance(description, str):\n cls.__discord_app_commands_group_description__ = description\n else:\n cls.__discord_app_commands_group_description__ = description.message\n cls.__discord_app_commands_group_locale_description__ = description\n\n if guild_only is not MISSING:\n cls.__discord_app_commands_guild_only__ = guild_only\n\n if default_permissions is not MISSING:\n cls.__discord_app_commands_default_permissions__ = default_permissions\n\n if cls.__module__ != __name__:\n cls.__discord_app_commands_has_module__ = True\n cls.__discord_app_commands_group_nsfw__ = nsfw\n\n def __init__(\n self,\n *,\n name: Union[str, locale_str] = MISSING,\n description: Union[str, locale_str] = MISSING,\n parent: Optional[Group] = None,\n guild_ids: Optional[List[int]] = None,\n guild_only: bool = MISSING,\n allowed_contexts: Optional[AppCommandContext] = MISSING,\n allowed_installs: Optional[AppInstallationType] = MISSING,\n nsfw: bool = MISSING,\n auto_locale_strings: bool = True,\n default_permissions: Optional[Permissions] = MISSING,\n extras: Dict[Any, Any] = MISSING,\n ):\n cls = self.__class__\n\n if name is MISSING:\n name, locale = cls.__discord_app_commands_group_name__, cls.__discord_app_commands_group_locale_name__\n elif isinstance(name, str):\n name, locale = validate_name(name), None\n else:\n name, locale = validate_name(name.message), name\n self.name: str = name\n self._locale_name: Optional[locale_str] = locale\n\n if description is MISSING:\n description, locale = (\n cls.__discord_app_commands_group_description__,\n cls.__discord_app_commands_group_locale_description__,\n )\n elif isinstance(description, str):\n description, locale = description, None\n else:\n description, locale = description.message, description\n self.description: str = description\n self._locale_description: Optional[locale_str] = locale\n\n self._attr: Optional[str] = None\n self._owner_cls: Optional[Type[Any]] = None\n self._guild_ids: Optional[List[int]] = guild_ids or getattr(cls, '__discord_app_commands_default_guilds__', None)\n\n if default_permissions is MISSING:\n if cls.__discord_app_commands_default_permissions__ is MISSING:\n default_permissions = None\n else:\n default_permissions = cls.__discord_app_commands_default_permissions__\n\n self.default_permissions: Optional[Permissions] = default_permissions\n\n if guild_only is MISSING:\n if cls.__discord_app_commands_guild_only__ is MISSING:\n guild_only = False\n else:\n guild_only = cls.__discord_app_commands_guild_only__\n\n self.guild_only: bool = guild_only\n\n if allowed_contexts is MISSING:\n if cls.__discord_app_commands_contexts__ is MISSING:\n allowed_contexts = None\n else:\n allowed_contexts = cls.__discord_app_commands_contexts__\n\n self.allowed_contexts: Optional[AppCommandContext] = allowed_contexts\n\n if allowed_installs is MISSING:\n if cls.__discord_app_commands_installation_types__ is MISSING:\n allowed_installs = None\n else:\n allowed_installs = cls.__discord_app_commands_installation_types__\n\n self.allowed_installs: Optional[AppInstallationType] = allowed_installs\n\n if nsfw is MISSING:\n nsfw = cls.__discord_app_commands_group_nsfw__\n\n self.nsfw: bool = nsfw\n\n if not self.description:\n raise TypeError('groups must have a description')\n\n if not self.name:\n raise TypeError('groups must have a name')\n\n self.parent: Optional[Group] = parent\n self.module: Optional[str]\n if cls.__discord_app_commands_has_module__:\n self.module = cls.__module__\n else:\n try:\n # This is pretty hacky\n # It allows the module to be fetched if someone just constructs a bare Group object though.\n self.module = inspect.currentframe().f_back.f_globals['__name__'] # type: ignore\n except (AttributeError, IndexError, KeyError):\n self.module = None\n\n self._children: Dict[str, Union[Command, Group]] = {}\n self.extras: Dict[Any, Any] = extras or {}\n\n bindings: Dict[Group, Group] = {}\n\n for child in self.__discord_app_commands_group_children__:\n # commands and groups created directly in this class (no parent)\n copy = (\n child._copy_with(parent=self, binding=self, bindings=bindings, set_on_binding=False)\n if not cls.__discord_app_commands_skip_init_binding__\n else child\n )\n\n self._children[copy.name] = copy\n if copy._attr and not cls.__discord_app_commands_skip_init_binding__:\n setattr(self, copy._attr, copy)\n\n if parent is not None:\n if parent.parent is not None:\n raise ValueError('groups can only be nested at most one level')\n parent.add_command(self)\n\n if auto_locale_strings:\n self._convert_to_locale_strings()\n\n def _convert_to_locale_strings(self) -> None:\n if self._locale_name is None:\n self._locale_name = locale_str(self.name)\n if self._locale_description is None:\n self._locale_description = locale_str(self.description)\n\n # I don't know if propagating to the children is the right behaviour here.\n\n def __set_name__(self, owner: Type[Any], name: str) -> None:\n self._attr = name\n self.module = owner.__module__\n self._owner_cls = owner\n\n def _copy_with(\n self,\n *,\n parent: Optional[Group],\n binding: Binding,\n bindings: MutableMapping[Group, Group] = MISSING,\n set_on_binding: bool = True,\n ) -> Group:\n bindings = {} if bindings is MISSING else bindings\n\n copy = shallow_copy(self)\n copy.parent = parent\n copy._children = {}\n\n bindings[self] = copy\n\n for child in self._children.values():\n child_copy = child._copy_with(parent=copy, binding=binding, bindings=bindings)\n child_copy.parent = copy\n copy._children[child_copy.name] = child_copy\n\n if isinstance(child_copy, Group) and child_copy._attr and set_on_binding:\n if binding.__class__ is child_copy._owner_cls:\n setattr(binding, child_copy._attr, child_copy)\n elif child_copy._owner_cls is copy.__class__:\n setattr(copy, child_copy._attr, child_copy)\n\n if copy._attr and set_on_binding:\n setattr(parent or binding, copy._attr, copy)\n\n return copy\n\n async def get_translated_payload(self, tree: CommandTree[ClientT], translator: Translator) -> Dict[str, Any]:\n base = self.to_dict(tree)\n name_localizations: Dict[str, str] = {}\n description_localizations: Dict[str, str] = {}\n\n # Prevent creating these objects in a heavy loop\n name_context = TranslationContext(location=TranslationContextLocation.group_name, data=self)\n description_context = TranslationContext(location=TranslationContextLocation.group_description, data=self)\n for locale in Locale:\n if self._locale_name:\n translation = await translator._checked_translate(self._locale_name, locale, name_context)\n if translation is not None:\n name_localizations[locale.value] = translation\n\n if self._locale_description:\n translation = await translator._checked_translate(self._locale_description, locale, description_context)\n if translation is not None:\n description_localizations[locale.value] = translation\n\n base['name_localizations'] = name_localizations\n base['description_localizations'] = description_localizations\n base['options'] = [await child.get_translated_payload(tree, translator) for child in self._children.values()]\n return base\n\n def to_dict(self, tree: CommandTree[ClientT]) -> Dict[str, Any]:\n # If this has a parent command then it's part of a subcommand group\n # Otherwise, it's just a regular command\n option_type = 1 if self.parent is None else AppCommandOptionType.subcommand_group.value\n base: Dict[str, Any] = {\n 'name': self.name,\n 'description': self.description,\n 'type': option_type,\n 'options': [child.to_dict(tree) for child in self._children.values()],\n }\n\n if self.parent is None:\n base['nsfw'] = self.nsfw\n base['dm_permission'] = not self.guild_only\n base['default_member_permissions'] = None if self.default_permissions is None else self.default_permissions.value\n base['contexts'] = tree.allowed_contexts._merge_to_array(self.allowed_contexts)\n base['integration_types'] = tree.allowed_installs._merge_to_array(self.allowed_installs)\n\n return base\n\n @property\n def root_parent(self) -> Optional[Group]:\n \"\"\"Optional[:class:`Group`]: The parent of this group.\"\"\"\n return self.parent\n\n @property\n def qualified_name(self) -> str:\n \"\"\":class:`str`: Returns the fully qualified group name.\n\n The qualified name includes the parent name as well. For example,\n in a group like ``/foo bar`` the qualified name is ``foo bar``.\n \"\"\"\n\n if self.parent is None:\n return self.name\n return f'{self.parent.name} {self.name}'\n\n def _get_internal_command(self, name: str) -> Optional[Union[Command[Any, ..., Any], Group]]:\n return self._children.get(name)\n\n @property\n def commands(self) -> List[Union[Command[Any, ..., Any], Group]]:\n \"\"\"List[Union[:class:`Command`, :class:`Group`]]: The commands that this group contains.\"\"\"\n return list(self._children.values())\n\n def walk_commands(self) -> Generator[Union[Command[Any, ..., Any], Group], None, None]:\n \"\"\"An iterator that recursively walks through all commands that this group contains.\n\n Yields\n ---------\n Union[:class:`Command`, :class:`Group`]\n The commands in this group.\n \"\"\"\n\n for command in self._children.values():\n yield command\n if isinstance(command, Group):\n yield from command.walk_commands()\n\n @mark_overrideable\n async def on_error(self, interaction: Interaction, error: AppCommandError, /) -> None:\n \"\"\"|coro|\n\n A callback that is called when a child's command raises an :exc:`AppCommandError`.\n\n To get the command that failed, :attr:`discord.Interaction.command` should be used.\n\n The default implementation does nothing.\n\n Parameters\n -----------\n interaction: :class:`~discord.Interaction`\n The interaction that is being handled.\n error: :exc:`AppCommandError`\n The exception that was raised.\n \"\"\"\n\n pass\n\n def error(self, coro: ErrorFunc) -> ErrorFunc:\n \"\"\"A decorator that registers a coroutine as a local error handler.\n\n The local error handler is called whenever an exception is raised in a child command.\n The error handler must take 2 parameters, the interaction and the error.\n\n The error passed will be derived from :exc:`AppCommandError`.\n\n Parameters\n -----------\n coro: :ref:`coroutine `\n The coroutine to register as the local error handler.\n\n Raises\n -------\n TypeError\n The coroutine passed is not actually a coroutine, or is an invalid coroutine.\n \"\"\"\n\n if not inspect.iscoroutinefunction(coro):\n raise TypeError('The error handler must be a coroutine.')\n\n params = inspect.signature(coro).parameters\n if len(params) != 2:\n raise TypeError('The error handler must have 2 parameters.')\n\n self.on_error = coro\n return coro\n\n async def interaction_check(self, interaction: Interaction, /) -> bool:\n \"\"\"|coro|\n\n A callback that is called when an interaction happens within the group\n that checks whether a command inside the group should be executed.\n\n This is useful to override if, for example, you want to ensure that the\n interaction author is a given user.\n\n The default implementation of this returns ``True``.\n\n .. note::\n\n If an exception occurs within the body then the check\n is considered a failure and error handlers such as\n :meth:`on_error` is called. See :exc:`AppCommandError`\n for more information.\n\n Parameters\n -----------\n interaction: :class:`~discord.Interaction`\n The interaction that occurred.\n\n Returns\n ---------\n :class:`bool`\n Whether the view children's callbacks should be called.\n \"\"\"\n\n return True\n\n def add_command(self, command: Union[Command[Any, ..., Any], Group], /, *, override: bool = False) -> None:\n \"\"\"Adds a command or group to this group's internal list of commands.\n\n Parameters\n -----------\n command: Union[:class:`Command`, :class:`Group`]\n The command or group to add.\n override: :class:`bool`\n Whether to override a pre-existing command or group with the same name.\n If ``False`` then an exception is raised.\n\n Raises\n -------\n CommandAlreadyRegistered\n The command or group is already registered. Note that the :attr:`CommandAlreadyRegistered.guild_id`\n attribute will always be ``None`` in this case.\n ValueError\n There are too many commands already registered or the group is too\n deeply nested.\n TypeError\n The wrong command type was passed.\n \"\"\"\n\n if not isinstance(command, (Command, Group)):\n raise TypeError(f'expected Command or Group not {command.__class__.__name__}')\n\n if isinstance(command, Group) and self.parent is not None:\n # In a tree like so:\n # \n # \n # \n # this needs to be forbidden\n raise ValueError(f'{command.name!r} is too nested, groups can only be nested at most one level')\n\n if not override and command.name in self._children:\n raise CommandAlreadyRegistered(command.name, guild_id=None)\n\n self._children[command.name] = command\n command.parent = self\n if len(self._children) > 25:\n raise ValueError('maximum number of child commands exceeded')\n\n def remove_command(self, name: str, /) -> Optional[Union[Command[Any, ..., Any], Group]]:\n \"\"\"Removes a command or group from the internal list of commands.\n\n Parameters\n -----------\n name: :class:`str`\n The name of the command or group to remove.\n\n Returns\n --------\n Optional[Union[:class:`~discord.app_commands.Command`, :class:`~discord.app_commands.Group`]]\n The command that was removed. If nothing was removed\n then ``None`` is returned instead.\n \"\"\"\n\n self._children.pop(name, None)\n\n def get_command(self, name: str, /) -> Optional[Union[Command[Any, ..., Any], Group]]:\n \"\"\"Retrieves a command or group from its name.\n\n Parameters\n -----------\n name: :class:`str`\n The name of the command or group to retrieve.\n\n Returns\n --------\n Optional[Union[:class:`~discord.app_commands.Command`, :class:`~discord.app_commands.Group`]]\n The command or group that was retrieved. If nothing was found\n then ``None`` is returned instead.\n \"\"\"\n return self._children.get(name)\n\n def command(\n self,\n *,\n name: Union[str, locale_str] = MISSING,\n description: Union[str, locale_str] = MISSING,\n nsfw: bool = False,\n auto_locale_strings: bool = True,\n extras: Dict[Any, Any] = MISSING,\n ) -> Callable[[CommandCallback[GroupT, P, T]], Command[GroupT, P, T]]:\n \"\"\"A decorator that creates an application command from a regular function under this group.\n\n Parameters\n ------------\n name: Union[:class:`str`, :class:`locale_str`]\n The name of the application command. If not given, it defaults to a lower-case\n version of the callback name.\n description: Union[:class:`str`, :class:`locale_str`]\n The description of the application command. This shows up in the UI to describe\n the application command. If not given, it defaults to the first line of the docstring\n of the callback shortened to 100 characters.\n nsfw: :class:`bool`\n Whether the command is NSFW and should only work in NSFW channels. Defaults to ``False``.\n auto_locale_strings: :class:`bool`\n If this is set to ``True``, then all translatable strings will implicitly\n be wrapped into :class:`locale_str` rather than :class:`str`. This could\n avoid some repetition and be more ergonomic for certain defaults such\n as default command names, command descriptions, and parameter names.\n Defaults to ``True``.\n extras: :class:`dict`\n A dictionary that can be used to store extraneous data.\n The library will not touch any values or keys within this dictionary.\n \"\"\"\n\n def decorator(func: CommandCallback[GroupT, P, T]) -> Command[GroupT, P, T]:\n if not inspect.iscoroutinefunction(func):\n raise TypeError('command function must be a coroutine function')\n\n if description is MISSING:\n if func.__doc__ is None:\n desc = '…'\n else:\n desc = _shorten(func.__doc__)\n else:\n desc = description\n\n command = Command(\n name=name if name is not MISSING else func.__name__,\n description=desc,\n callback=func,\n nsfw=nsfw,\n parent=self,\n auto_locale_strings=auto_locale_strings,\n extras=extras,\n )\n self.add_command(command)\n return command\n\n return decorator\n\n\ndef command(\n *,\n name: Union[str, locale_str] = MISSING,\n description: Union[str, locale_str] = MISSING,\n nsfw: bool = False,\n auto_locale_strings: bool = True,\n extras: Dict[Any, Any] = MISSING,\n) -> Callable[[CommandCallback[GroupT, P, T]], Command[GroupT, P, T]]:\n \"\"\"Creates an application command from a regular function.\n\n Parameters\n ------------\n name: :class:`str`\n The name of the application command. If not given, it defaults to a lower-case\n version of the callback name.\n description: :class:`str`\n The description of the application command. This shows up in the UI to describe\n the application command. If not given, it defaults to the first line of the docstring\n of the callback shortened to 100 characters.\n nsfw: :class:`bool`\n Whether the command is NSFW and should only work in NSFW channels. Defaults to ``False``.\n\n Due to a Discord limitation, this does not work on subcommands.\n auto_locale_strings: :class:`bool`\n If this is set to ``True``, then all translatable strings will implicitly\n be wrapped into :class:`locale_str` rather than :class:`str`. This could\n avoid some repetition and be more ergonomic for certain defaults such\n as default command names, command descriptions, and parameter names.\n Defaults to ``True``.\n extras: :class:`dict`\n A dictionary that can be used to store extraneous data.\n The library will not touch any values or keys within this dictionary.\n \"\"\"\n\n def decorator(func: CommandCallback[GroupT, P, T]) -> Command[GroupT, P, T]:\n if not inspect.iscoroutinefunction(func):\n raise TypeError('command function must be a coroutine function')\n\n if description is MISSING:\n if func.__doc__ is None:\n desc = '…'\n else:\n desc = _shorten(func.__doc__)\n else:\n desc = description\n\n return Command(\n name=name if name is not MISSING else func.__name__,\n description=desc,\n callback=func,\n parent=None,\n nsfw=nsfw,\n auto_locale_strings=auto_locale_strings,\n extras=extras,\n )\n\n return decorator\n\n\ndef context_menu(\n *,\n name: Union[str, locale_str] = MISSING,\n nsfw: bool = False,\n auto_locale_strings: bool = True,\n extras: Dict[Any, Any] = MISSING,\n) -> Callable[[ContextMenuCallback], ContextMenu]:\n \"\"\"Creates an application command context menu from a regular function.\n\n This function must have a signature of :class:`~discord.Interaction` as its first parameter\n and taking either a :class:`~discord.Member`, :class:`~discord.User`, or :class:`~discord.Message`,\n or a :obj:`typing.Union` of ``Member`` and ``User`` as its second parameter.\n\n Examples\n ---------\n\n .. code-block:: python3\n\n @app_commands.context_menu()\n async def react(interaction: discord.Interaction, message: discord.Message):\n await interaction.response.send_message('Very cool message!', ephemeral=True)\n\n @app_commands.context_menu()\n async def ban(interaction: discord.Interaction, user: discord.Member):\n await interaction.response.send_message(f'Should I actually ban {user}...', ephemeral=True)\n\n Parameters\n ------------\n name: Union[:class:`str`, :class:`locale_str`]\n The name of the context menu command. If not given, it defaults to a title-case\n version of the callback name. Note that unlike regular slash commands this can\n have spaces and upper case characters in the name.\n nsfw: :class:`bool`\n Whether the command is NSFW and should only work in NSFW channels. Defaults to ``False``.\n\n Due to a Discord limitation, this does not work on subcommands.\n auto_locale_strings: :class:`bool`\n If this is set to ``True``, then all translatable strings will implicitly\n be wrapped into :class:`locale_str` rather than :class:`str`. This could\n avoid some repetition and be more ergonomic for certain defaults such\n as default command names, command descriptions, and parameter names.\n Defaults to ``True``.\n extras: :class:`dict`\n A dictionary that can be used to store extraneous data.\n The library will not touch any values or keys within this dictionary.\n \"\"\"\n\n def decorator(func: ContextMenuCallback) -> ContextMenu:\n if not inspect.iscoroutinefunction(func):\n raise TypeError('context menu function must be a coroutine function')\n\n actual_name = func.__name__.title() if name is MISSING else name\n return ContextMenu(\n name=actual_name,\n nsfw=nsfw,\n callback=func,\n auto_locale_strings=auto_locale_strings,\n extras=extras,\n )\n\n return decorator\n\n\ndef describe(**parameters: Union[str, locale_str]) -> Callable[[T], T]:\n r'''Describes the given parameters by their name using the key of the keyword argument\n as the name.\n\n Example:\n\n .. code-block:: python3\n\n @app_commands.command(description='Bans a member')\n @app_commands.describe(member='the member to ban')\n async def ban(interaction: discord.Interaction, member: discord.Member):\n await interaction.response.send_message(f'Banned {member}')\n\n Alternatively, you can describe parameters using Google, Sphinx, or Numpy style docstrings.\n\n Example:\n\n .. code-block:: python3\n\n @app_commands.command()\n async def ban(interaction: discord.Interaction, member: discord.Member):\n \"\"\"Bans a member\n\n Parameters\n -----------\n member: discord.Member\n the member to ban\n \"\"\"\n await interaction.response.send_message(f'Banned {member}')\n\n Parameters\n -----------\n \\*\\*parameters: Union[:class:`str`, :class:`locale_str`]\n The description of the parameters.\n\n Raises\n --------\n TypeError\n The parameter name is not found.\n '''\n\n def decorator(inner: T) -> T:\n if isinstance(inner, Command):\n _populate_descriptions(inner._params, parameters)\n else:\n try:\n inner.__discord_app_commands_param_description__.update(parameters) # type: ignore # Runtime attribute access\n except AttributeError:\n inner.__discord_app_commands_param_description__ = parameters # type: ignore # Runtime attribute assignment\n\n return inner\n\n return decorator\n\n\ndef rename(**parameters: Union[str, locale_str]) -> Callable[[T], T]:\n r\"\"\"Renames the given parameters by their name using the key of the keyword argument\n as the name.\n\n This renames the parameter within the Discord UI. When referring to the parameter in other\n decorators, the parameter name used in the function is used instead of the renamed one.\n\n Example:\n\n .. code-block:: python3\n\n @app_commands.command()\n @app_commands.rename(the_member_to_ban='member')\n async def ban(interaction: discord.Interaction, the_member_to_ban: discord.Member):\n await interaction.response.send_message(f'Banned {the_member_to_ban}')\n\n Parameters\n -----------\n \\*\\*parameters: Union[:class:`str`, :class:`locale_str`]\n The name of the parameters.\n\n Raises\n --------\n ValueError\n The parameter name is already used by another parameter.\n TypeError\n The parameter name is not found.\n \"\"\"\n\n def decorator(inner: T) -> T:\n if isinstance(inner, Command):\n _populate_renames(inner._params, parameters)\n else:\n try:\n inner.__discord_app_commands_param_rename__.update(parameters) # type: ignore # Runtime attribute access\n except AttributeError:\n inner.__discord_app_commands_param_rename__ = parameters # type: ignore # Runtime attribute assignment\n\n return inner\n\n return decorator\n\n\ndef choices(**parameters: List[Choice[ChoiceT]]) -> Callable[[T], T]:\n r\"\"\"Instructs the given parameters by their name to use the given choices for their choices.\n\n Example:\n\n .. code-block:: python3\n\n @app_commands.command()\n @app_commands.describe(fruits='fruits to choose from')\n @app_commands.choices(fruits=[\n Choice(name='apple', value=1),\n Choice(name='banana', value=2),\n Choice(name='cherry', value=3),\n ])\n async def fruit(interaction: discord.Interaction, fruits: Choice[int]):\n await interaction.response.send_message(f'Your favourite fruit is {fruits.name}.')\n\n .. note::\n\n This is not the only way to provide choices to a command. There are two more ergonomic ways\n of doing this. The first one is to use a :obj:`typing.Literal` annotation:\n\n .. code-block:: python3\n\n @app_commands.command()\n @app_commands.describe(fruits='fruits to choose from')\n async def fruit(interaction: discord.Interaction, fruits: Literal['apple', 'banana', 'cherry']):\n await interaction.response.send_message(f'Your favourite fruit is {fruits}.')\n\n The second way is to use an :class:`enum.Enum`:\n\n .. code-block:: python3\n\n class Fruits(enum.Enum):\n apple = 1\n banana = 2\n cherry = 3\n\n @app_commands.command()\n @app_commands.describe(fruits='fruits to choose from')\n async def fruit(interaction: discord.Interaction, fruits: Fruits):\n await interaction.response.send_message(f'Your favourite fruit is {fruits}.')\n\n\n Parameters\n -----------\n \\*\\*parameters\n The choices of the parameters.\n\n Raises\n --------\n TypeError\n The parameter name is not found or the parameter type was incorrect.\n \"\"\"\n\n def decorator(inner: T) -> T:\n if isinstance(inner, Command):\n _populate_choices(inner._params, parameters)\n else:\n try:\n inner.__discord_app_commands_param_choices__.update(parameters) # type: ignore # Runtime attribute access\n except AttributeError:\n inner.__discord_app_commands_param_choices__ = parameters # type: ignore # Runtime attribute assignment\n\n return inner\n\n return decorator\n\n\ndef autocomplete(**parameters: AutocompleteCallback[GroupT, ChoiceT]) -> Callable[[T], T]:\n r\"\"\"Associates the given parameters with the given autocomplete callback.\n\n Autocomplete is only supported on types that have :class:`str`, :class:`int`, or :class:`float`\n values.\n\n :func:`Checks ` are supported, however they must be attached to the autocomplete\n callback in order to work. Checks attached to the command are ignored when invoking the autocomplete\n callback.\n\n For more information, see the :meth:`Command.autocomplete` documentation.\n\n .. warning::\n The choices returned from this coroutine are suggestions. The user may ignore them and input their own value.\n\n Example:\n\n .. code-block:: python3\n\n async def fruit_autocomplete(\n interaction: discord.Interaction,\n current: str,\n ) -> List[app_commands.Choice[str]]:\n fruits = ['Banana', 'Pineapple', 'Apple', 'Watermelon', 'Melon', 'Cherry']\n return [\n app_commands.Choice(name=fruit, value=fruit)\n for fruit in fruits if current.lower() in fruit.lower()\n ]\n\n @app_commands.command()\n @app_commands.autocomplete(fruit=fruit_autocomplete)\n async def fruits(interaction: discord.Interaction, fruit: str):\n await interaction.response.send_message(f'Your favourite fruit seems to be {fruit}')\n\n Parameters\n -----------\n \\*\\*parameters\n The parameters to mark as autocomplete.\n\n Raises\n --------\n TypeError\n The parameter name is not found or the parameter type was incorrect.\n \"\"\"\n\n def decorator(inner: T) -> T:\n if isinstance(inner, Command):\n _populate_autocomplete(inner._params, parameters)\n else:\n try:\n inner.__discord_app_commands_param_autocomplete__.update(parameters) # type: ignore # Runtime attribute access\n except AttributeError:\n inner.__discord_app_commands_param_autocomplete__ = parameters # type: ignore # Runtime attribute assignment\n\n return inner\n\n return decorator\n\n\ndef guilds(*guild_ids: Union[Snowflake, int]) -> Callable[[T], T]:\n r\"\"\"Associates the given guilds with the command.\n\n When the command instance is added to a :class:`CommandTree`, the guilds that are\n specified by this decorator become the default guilds that it's added to rather\n than being a global command.\n\n .. note::\n\n Due to an implementation quirk and Python limitation, if this is used in conjunction\n with the :meth:`CommandTree.command` or :meth:`CommandTree.context_menu` decorator\n then this must go below that decorator.\n\n .. note ::\n\n Due to a Discord limitation, this decorator cannot be used in conjunction with\n contexts (e.g. :func:`.app_commands.allowed_contexts`) or installation types\n (e.g. :func:`.app_commands.allowed_installs`).\n\n Example:\n\n .. code-block:: python3\n\n MY_GUILD_ID = discord.Object(...) # Guild ID here\n\n @app_commands.command()\n @app_commands.guilds(MY_GUILD_ID)\n async def bonk(interaction: discord.Interaction):\n await interaction.response.send_message('Bonk', ephemeral=True)\n\n Parameters\n -----------\n \\*guild_ids: Union[:class:`int`, :class:`~discord.abc.Snowflake`]\n The guilds to associate this command with. The command tree will\n use this as the default when added rather than adding it as a global\n command.\n \"\"\"\n\n defaults: List[int] = [g if isinstance(g, int) else g.id for g in guild_ids]\n\n def decorator(inner: T) -> T:\n if isinstance(inner, (Group, ContextMenu)):\n inner._guild_ids = defaults\n elif isinstance(inner, Command):\n if inner.parent is not None:\n raise ValueError('child commands of a group cannot have default guilds set')\n\n inner._guild_ids = defaults\n else:\n # Runtime attribute assignment\n inner.__discord_app_commands_default_guilds__ = defaults # type: ignore\n\n return inner\n\n return decorator\n\n\ndef check(predicate: Check) -> Callable[[T], T]:\n r\"\"\"A decorator that adds a check to an application command.\n\n These checks should be predicates that take in a single parameter taking\n a :class:`~discord.Interaction`. If the check returns a ``False``\\-like value then\n during invocation a :exc:`CheckFailure` exception is raised and sent to\n the appropriate error handlers.\n\n These checks can be either a coroutine or not.\n\n Examples\n ---------\n\n Creating a basic check to see if the command invoker is you.\n\n .. code-block:: python3\n\n def check_if_it_is_me(interaction: discord.Interaction) -> bool:\n return interaction.user.id == 85309593344815104\n\n @tree.command()\n @app_commands.check(check_if_it_is_me)\n async def only_for_me(interaction: discord.Interaction):\n await interaction.response.send_message('I know you!', ephemeral=True)\n\n Transforming common checks into its own decorator:\n\n .. code-block:: python3\n\n def is_me():\n def predicate(interaction: discord.Interaction) -> bool:\n return interaction.user.id == 85309593344815104\n return app_commands.check(predicate)\n\n @tree.command()\n @is_me()\n async def only_me(interaction: discord.Interaction):\n await interaction.response.send_message('Only you!')\n\n Parameters\n -----------\n predicate: Callable[[:class:`~discord.Interaction`], :class:`bool`]\n The predicate to check if the command should be invoked.\n \"\"\"\n\n def decorator(func: CheckInputParameter) -> CheckInputParameter:\n if isinstance(func, (Command, ContextMenu)):\n func.checks.append(predicate)\n else:\n if not hasattr(func, '__discord_app_commands_checks__'):\n func.__discord_app_commands_checks__ = []\n\n func.__discord_app_commands_checks__.append(predicate)\n\n return func\n\n return decorator # type: ignore\n\n\n@overload\ndef guild_only(func: None = ...) -> Callable[[T], T]:\n ...\n\n\n@overload\ndef guild_only(func: T) -> T:\n ...\n\n\ndef guild_only(func: Optional[T] = None) -> Union[T, Callable[[T], T]]:\n \"\"\"A decorator that indicates this command can only be used in a guild context.\n\n This is **not** implemented as a :func:`check`, and is instead verified by Discord server side.\n Therefore, there is no error handler called when a command is used within a private message.\n\n This decorator can be called with or without parentheses.\n\n Due to a Discord limitation, this decorator does nothing in subcommands and is ignored.\n\n Examples\n ---------\n\n .. code-block:: python3\n\n @app_commands.command()\n @app_commands.guild_only()\n async def my_guild_only_command(interaction: discord.Interaction) -> None:\n await interaction.response.send_message('I am only available in guilds!')\n \"\"\"\n\n def inner(f: T) -> T:\n if isinstance(f, (Command, Group, ContextMenu)):\n f.guild_only = True\n allowed_contexts = f.allowed_contexts or AppCommandContext()\n f.allowed_contexts = allowed_contexts\n else:\n f.__discord_app_commands_guild_only__ = True # type: ignore # Runtime attribute assignment\n\n allowed_contexts = getattr(f, '__discord_app_commands_contexts__', None) or AppCommandContext()\n f.__discord_app_commands_contexts__ = allowed_contexts # type: ignore # Runtime attribute assignment\n\n allowed_contexts.guild = True\n\n return f\n\n # Check if called with parentheses or not\n if func is None:\n # Called with parentheses\n return inner\n else:\n return inner(func)\n\n\n@overload\ndef private_channel_only(func: None = ...) -> Callable[[T], T]:\n ...\n\n\n@overload\ndef private_channel_only(func: T) -> T:\n ...\n\n\ndef private_channel_only(func: Optional[T] = None) -> Union[T, Callable[[T], T]]:\n \"\"\"A decorator that indicates this command can only be used in the context of DMs and group DMs.\n\n This is **not** implemented as a :func:`check`, and is instead verified by Discord server side.\n Therefore, there is no error handler called when a command is used within a guild.\n\n This decorator can be called with or without parentheses.\n\n Due to a Discord limitation, this decorator does nothing in subcommands and is ignored.\n\n .. versionadded:: 2.4\n\n Examples\n ---------\n\n .. code-block:: python3\n\n @app_commands.command()\n @app_commands.private_channel_only()\n async def my_private_channel_only_command(interaction: discord.Interaction) -> None:\n await interaction.response.send_message('I am only available in DMs and GDMs!')\n \"\"\"\n\n def inner(f: T) -> T:\n if isinstance(f, (Command, Group, ContextMenu)):\n f.guild_only = False\n allowed_contexts = f.allowed_contexts or AppCommandContext()\n f.allowed_contexts = allowed_contexts\n else:\n allowed_contexts = getattr(f, '__discord_app_commands_contexts__', None) or AppCommandContext()\n f.__discord_app_commands_contexts__ = allowed_contexts # type: ignore # Runtime attribute assignment\n\n allowed_contexts.private_channel = True\n\n return f\n\n # Check if called with parentheses or not\n if func is None:\n # Called with parentheses\n return inner\n else:\n return inner(func)\n\n\n@overload\ndef dm_only(func: None = ...) -> Callable[[T], T]:\n ...\n\n\n@overload\ndef dm_only(func: T) -> T:\n ...\n\n\ndef dm_only(func: Optional[T] = None) -> Union[T, Callable[[T], T]]:\n \"\"\"A decorator that indicates this command can only be used in the context of bot DMs.\n\n This is **not** implemented as a :func:`check`, and is instead verified by Discord server side.\n Therefore, there is no error handler called when a command is used within a guild or group DM.\n\n This decorator can be called with or without parentheses.\n\n Due to a Discord limitation, this decorator does nothing in subcommands and is ignored.\n\n Examples\n ---------\n\n .. code-block:: python3\n\n @app_commands.command()\n @app_commands.dm_only()\n async def my_dm_only_command(interaction: discord.Interaction) -> None:\n await interaction.response.send_message('I am only available in DMs!')\n \"\"\"\n\n def inner(f: T) -> T:\n if isinstance(f, (Command, Group, ContextMenu)):\n f.guild_only = False\n allowed_contexts = f.allowed_contexts or AppCommandContext()\n f.allowed_contexts = allowed_contexts\n else:\n allowed_contexts = getattr(f, '__discord_app_commands_contexts__', None) or AppCommandContext()\n f.__discord_app_commands_contexts__ = allowed_contexts # type: ignore # Runtime attribute assignment\n\n allowed_contexts.dm_channel = True\n return f\n\n # Check if called with parentheses or not\n if func is None:\n # Called with parentheses\n return inner\n else:\n return inner(func)\n\n\ndef allowed_contexts(guilds: bool = MISSING, dms: bool = MISSING, private_channels: bool = MISSING) -> Callable[[T], T]:\n \"\"\"A decorator that indicates this command can only be used in certain contexts.\n Valid contexts are guilds, DMs and private channels.\n\n This is **not** implemented as a :func:`check`, and is instead verified by Discord server side.\n\n Due to a Discord limitation, this decorator does nothing in subcommands and is ignored.\n\n .. versionadded:: 2.4\n\n Examples\n ---------\n\n .. code-block:: python3\n\n @app_commands.command()\n @app_commands.allowed_contexts(guilds=True, dms=False, private_channels=True)\n async def my_command(interaction: discord.Interaction) -> None:\n await interaction.response.send_message('I am only available in guilds and private channels!')\n \"\"\"\n\n def inner(f: T) -> T:\n if isinstance(f, (Command, Group, ContextMenu)):\n f.guild_only = False\n allowed_contexts = f.allowed_contexts or AppCommandContext()\n f.allowed_contexts = allowed_contexts\n else:\n allowed_contexts = getattr(f, '__discord_app_commands_contexts__', None) or AppCommandContext()\n f.__discord_app_commands_contexts__ = allowed_contexts # type: ignore # Runtime attribute assignment\n\n if guilds is not MISSING:\n allowed_contexts.guild = guilds\n\n if dms is not MISSING:\n allowed_contexts.dm_channel = dms\n\n if private_channels is not MISSING:\n allowed_contexts.private_channel = private_channels\n\n return f\n\n return inner\n\n\n@overload\ndef guild_install(func: None = ...) -> Callable[[T], T]:\n ...\n\n\n@overload\ndef guild_install(func: T) -> T:\n ...\n\n\ndef guild_install(func: Optional[T] = None) -> Union[T, Callable[[T], T]]:\n \"\"\"A decorator that indicates this command should be installed in guilds.\n\n This is **not** implemented as a :func:`check`, and is instead verified by Discord server side.\n\n Due to a Discord limitation, this decorator does nothing in subcommands and is ignored.\n\n .. versionadded:: 2.4\n\n Examples\n ---------\n\n .. code-block:: python3\n\n @app_commands.command()\n @app_commands.guild_install()\n async def my_guild_install_command(interaction: discord.Interaction) -> None:\n await interaction.response.send_message('I am installed in guilds by default!')\n \"\"\"\n\n def inner(f: T) -> T:\n if isinstance(f, (Command, Group, ContextMenu)):\n allowed_installs = f.allowed_installs or AppInstallationType()\n f.allowed_installs = allowed_installs\n else:\n allowed_installs = getattr(f, '__discord_app_commands_installation_types__', None) or AppInstallationType()\n f.__discord_app_commands_installation_types__ = allowed_installs # type: ignore # Runtime attribute assignment\n\n allowed_installs.guild = True\n\n return f\n\n # Check if called with parentheses or not\n if func is None:\n # Called with parentheses\n return inner\n else:\n return inner(func)\n\n\n@overload\ndef user_install(func: None = ...) -> Callable[[T], T]:\n ...\n\n\n@overload\ndef user_install(func: T) -> T:\n ...\n\n\ndef user_install(func: Optional[T] = None) -> Union[T, Callable[[T], T]]:\n \"\"\"A decorator that indicates this command should be installed for users.\n\n This is **not** implemented as a :func:`check`, and is instead verified by Discord server side.\n\n Due to a Discord limitation, this decorator does nothing in subcommands and is ignored.\n\n .. versionadded:: 2.4\n\n Examples\n ---------\n\n .. code-block:: python3\n\n @app_commands.command()\n @app_commands.user_install()\n async def my_user_install_command(interaction: discord.Interaction) -> None:\n await interaction.response.send_message('I am installed in users by default!')\n \"\"\"\n\n def inner(f: T) -> T:\n if isinstance(f, (Command, Group, ContextMenu)):\n allowed_installs = f.allowed_installs or AppInstallationType()\n f.allowed_installs = allowed_installs\n else:\n allowed_installs = getattr(f, '__discord_app_commands_installation_types__', None) or AppInstallationType()\n f.__discord_app_commands_installation_types__ = allowed_installs # type: ignore # Runtime attribute assignment\n\n allowed_installs.user = True\n\n return f\n\n # Check if called with parentheses or not\n if func is None:\n # Called with parentheses\n return inner\n else:\n return inner(func)\n\n\ndef allowed_installs(\n guilds: bool = MISSING,\n users: bool = MISSING,\n) -> Callable[[T], T]:\n \"\"\"A decorator that indicates this command should be installed in certain contexts.\n Valid contexts are guilds and users.\n\n This is **not** implemented as a :func:`check`, and is instead verified by Discord server side.\n\n Due to a Discord limitation, this decorator does nothing in subcommands and is ignored.\n\n .. versionadded:: 2.4\n\n Examples\n ---------\n\n .. code-block:: python3\n\n @app_commands.command()\n @app_commands.allowed_installs(guilds=False, users=True)\n async def my_command(interaction: discord.Interaction) -> None:\n await interaction.response.send_message('I am installed in users by default!')\n \"\"\"\n\n def inner(f: T) -> T:\n if isinstance(f, (Command, Group, ContextMenu)):\n allowed_installs = f.allowed_installs or AppInstallationType()\n f.allowed_installs = allowed_installs\n else:\n allowed_installs = getattr(f, '__discord_app_commands_installation_types__', None) or AppInstallationType()\n f.__discord_app_commands_installation_types__ = allowed_installs # type: ignore # Runtime attribute assignment\n\n if guilds is not MISSING:\n allowed_installs.guild = guilds\n\n if users is not MISSING:\n allowed_installs.user = users\n\n return f\n\n return inner\n\n\ndef default_permissions(**perms: bool) -> Callable[[T], T]:\n r\"\"\"A decorator that sets the default permissions needed to execute this command.\n\n When this decorator is used, by default users must have these permissions to execute the command.\n However, an administrator can change the permissions needed to execute this command using the official\n client. Therefore, this only serves as a hint.\n\n Setting an empty permissions field, including via calling this with no arguments, will disallow anyone\n except server administrators from using the command in a guild.\n\n This is sent to Discord server side, and is not a :func:`check`. Therefore, error handlers are not called.\n\n Due to a Discord limitation, this decorator does nothing in subcommands and is ignored.\n\n .. warning::\n\n This serves as a *hint* and members are *not* required to have the permissions given to actually\n execute this command. If you want to ensure that members have the permissions needed, consider using\n :func:`~discord.app_commands.checks.has_permissions` instead.\n\n Parameters\n -----------\n \\*\\*perms: :class:`bool`\n Keyword arguments denoting the permissions to set as the default.\n\n Example\n ---------\n\n .. code-block:: python3\n\n @app_commands.command()\n @app_commands.default_permissions(manage_messages=True)\n async def test(interaction: discord.Interaction):\n await interaction.response.send_message('You may or may not have manage messages.')\n \"\"\"\n\n permissions = Permissions(**perms)\n\n def decorator(func: T) -> T:\n if isinstance(func, (Command, Group, ContextMenu)):\n func.default_permissions = permissions\n else:\n func.__discord_app_commands_default_permissions__ = permissions # type: ignore # Runtime attribute assignment\n\n return func\n\n return decorator\n" }, { "path": "discord/app_commands/errors.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import Any, TYPE_CHECKING, List, Optional, Sequence, Union\n\nfrom ..enums import AppCommandOptionType, AppCommandType, Locale\nfrom ..errors import DiscordException, HTTPException, _flatten_error_dict\nfrom ..utils import _human_join\n\n__all__ = (\n 'AppCommandError',\n 'CommandInvokeError',\n 'TransformerError',\n 'TranslationError',\n 'CheckFailure',\n 'CommandAlreadyRegistered',\n 'CommandSignatureMismatch',\n 'CommandNotFound',\n 'CommandLimitReached',\n 'NoPrivateMessage',\n 'MissingRole',\n 'MissingAnyRole',\n 'MissingPermissions',\n 'BotMissingPermissions',\n 'CommandOnCooldown',\n 'MissingApplicationID',\n 'CommandSyncFailure',\n)\n\nif TYPE_CHECKING:\n from .commands import Command, Group, ContextMenu, Parameter\n from .transformers import Transformer\n from .translator import TranslationContextTypes, locale_str\n from ..types.snowflake import Snowflake, SnowflakeList\n from .checks import Cooldown\n\n CommandTypes = Union[Command[Any, ..., Any], Group, ContextMenu]\n\nAPP_ID_NOT_FOUND = (\n 'Client does not have an application_id set. Either the function was called before on_ready '\n 'was called or application_id was not passed to the Client constructor.'\n)\n\n\nclass AppCommandError(DiscordException):\n \"\"\"The base exception type for all application command related errors.\n\n This inherits from :exc:`discord.DiscordException`.\n\n This exception and exceptions inherited from it are handled\n in a special way as they are caught and passed into various error handlers\n in this order:\n\n - :meth:`Command.error `\n - :meth:`Group.on_error `\n - :meth:`CommandTree.on_error `\n\n .. versionadded:: 2.0\n \"\"\"\n\n pass\n\n\nclass CommandInvokeError(AppCommandError):\n \"\"\"An exception raised when the command being invoked raised an exception.\n\n This inherits from :exc:`~discord.app_commands.AppCommandError`.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n original: :exc:`Exception`\n The original exception that was raised. You can also get this via\n the ``__cause__`` attribute.\n command: Union[:class:`Command`, :class:`ContextMenu`]\n The command that failed.\n \"\"\"\n\n def __init__(self, command: Union[Command[Any, ..., Any], ContextMenu], e: Exception) -> None:\n self.original: Exception = e\n self.command: Union[Command[Any, ..., Any], ContextMenu] = command\n super().__init__(f'Command {command.name!r} raised an exception: {e.__class__.__name__}: {e}')\n\n\nclass TransformerError(AppCommandError):\n \"\"\"An exception raised when a :class:`Transformer` or type annotation fails to\n convert to its target type.\n\n This inherits from :exc:`~discord.app_commands.AppCommandError`.\n\n If an exception occurs while converting that does not subclass\n :exc:`AppCommandError` then the exception is wrapped into this exception.\n The original exception can be retrieved using the ``__cause__`` attribute.\n Otherwise if the exception derives from :exc:`AppCommandError` then it will\n be propagated as-is.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n value: Any\n The value that failed to convert.\n type: :class:`~discord.AppCommandOptionType`\n The type of argument that failed to convert.\n transformer: :class:`Transformer`\n The transformer that failed the conversion.\n \"\"\"\n\n def __init__(self, value: Any, opt_type: AppCommandOptionType, transformer: Transformer):\n self.value: Any = value\n self.type: AppCommandOptionType = opt_type\n self.transformer: Transformer = transformer\n\n super().__init__(f'Failed to convert {value} to {transformer._error_display_name!s}')\n\n\nclass TranslationError(AppCommandError):\n \"\"\"An exception raised when the library fails to translate a string.\n\n This inherits from :exc:`~discord.app_commands.AppCommandError`.\n\n If an exception occurs while calling :meth:`Translator.translate` that does\n not subclass this then the exception is wrapped into this exception.\n The original exception can be retrieved using the ``__cause__`` attribute.\n Otherwise it will be propagated as-is.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n string: Optional[Union[:class:`str`, :class:`locale_str`]]\n The string that caused the error, if any.\n locale: Optional[:class:`~discord.Locale`]\n The locale that caused the error, if any.\n context: :class:`~discord.app_commands.TranslationContext`\n The context of the translation that triggered the error.\n \"\"\"\n\n def __init__(\n self,\n *msg: str,\n string: Optional[Union[str, locale_str]] = None,\n locale: Optional[Locale] = None,\n context: TranslationContextTypes,\n ) -> None:\n self.string: Optional[Union[str, locale_str]] = string\n self.locale: Optional[Locale] = locale\n self.context: TranslationContextTypes = context\n\n if msg:\n super().__init__(*msg)\n else:\n ctx = context.location.name.replace('_', ' ')\n fmt = f'Failed to translate {self.string!r} in a {ctx}'\n if self.locale is not None:\n fmt = f'{fmt} in the {self.locale.value} locale'\n\n super().__init__(fmt)\n\n\nclass CheckFailure(AppCommandError):\n \"\"\"An exception raised when check predicates in a command have failed.\n\n This inherits from :exc:`~discord.app_commands.AppCommandError`.\n\n .. versionadded:: 2.0\n \"\"\"\n\n pass\n\n\nclass NoPrivateMessage(CheckFailure):\n \"\"\"An exception raised when a command does not work in a direct message.\n\n This inherits from :exc:`~discord.app_commands.CheckFailure`.\n\n .. versionadded:: 2.0\n \"\"\"\n\n def __init__(self, message: Optional[str] = None) -> None:\n super().__init__(message or 'This command cannot be used in direct messages.')\n\n\nclass MissingRole(CheckFailure):\n \"\"\"An exception raised when the command invoker lacks a role to run a command.\n\n This inherits from :exc:`~discord.app_commands.CheckFailure`.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n missing_role: Union[:class:`str`, :class:`int`]\n The required role that is missing.\n This is the parameter passed to :func:`~discord.app_commands.checks.has_role`.\n \"\"\"\n\n def __init__(self, missing_role: Snowflake) -> None:\n self.missing_role: Snowflake = missing_role\n message = f'Role {missing_role!r} is required to run this command.'\n super().__init__(message)\n\n\nclass MissingAnyRole(CheckFailure):\n \"\"\"An exception raised when the command invoker lacks any of the roles\n specified to run a command.\n\n This inherits from :exc:`~discord.app_commands.CheckFailure`.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n missing_roles: List[Union[:class:`str`, :class:`int`]]\n The roles that the invoker is missing.\n These are the parameters passed to :func:`~discord.app_commands.checks.has_any_role`.\n \"\"\"\n\n def __init__(self, missing_roles: SnowflakeList) -> None:\n self.missing_roles: SnowflakeList = missing_roles\n\n fmt = _human_join([f\"'{role}'\" for role in missing_roles])\n message = f'You are missing at least one of the required roles: {fmt}'\n super().__init__(message)\n\n\nclass MissingPermissions(CheckFailure):\n \"\"\"An exception raised when the command invoker lacks permissions to run a\n command.\n\n This inherits from :exc:`~discord.app_commands.CheckFailure`.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n missing_permissions: List[:class:`str`]\n The required permissions that are missing.\n \"\"\"\n\n def __init__(self, missing_permissions: List[str], *args: Any) -> None:\n self.missing_permissions: List[str] = missing_permissions\n\n missing = [perm.replace('_', ' ').replace('guild', 'server').title() for perm in missing_permissions]\n fmt = _human_join(missing, final='and')\n message = f'You are missing {fmt} permission(s) to run this command.'\n super().__init__(message, *args)\n\n\nclass BotMissingPermissions(CheckFailure):\n \"\"\"An exception raised when the bot's member lacks permissions to run a\n command.\n\n This inherits from :exc:`~discord.app_commands.CheckFailure`.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n missing_permissions: List[:class:`str`]\n The required permissions that are missing.\n \"\"\"\n\n def __init__(self, missing_permissions: List[str], *args: Any) -> None:\n self.missing_permissions: List[str] = missing_permissions\n\n missing = [perm.replace('_', ' ').replace('guild', 'server').title() for perm in missing_permissions]\n fmt = _human_join(missing, final='and')\n message = f'Bot requires {fmt} permission(s) to run this command.'\n super().__init__(message, *args)\n\n\nclass CommandOnCooldown(CheckFailure):\n \"\"\"An exception raised when the command being invoked is on cooldown.\n\n This inherits from :exc:`~discord.app_commands.CheckFailure`.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n cooldown: :class:`~discord.app_commands.Cooldown`\n The cooldown that was triggered.\n retry_after: :class:`float`\n The amount of seconds to wait before you can retry again.\n \"\"\"\n\n def __init__(self, cooldown: Cooldown, retry_after: float) -> None:\n self.cooldown: Cooldown = cooldown\n self.retry_after: float = retry_after\n super().__init__(f'You are on cooldown. Try again in {retry_after:.2f}s')\n\n\nclass CommandAlreadyRegistered(AppCommandError):\n \"\"\"An exception raised when a command is already registered.\n\n This inherits from :exc:`~discord.app_commands.AppCommandError`.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n name: :class:`str`\n The name of the command already registered.\n guild_id: Optional[:class:`int`]\n The guild ID this command was already registered at.\n If ``None`` then it was a global command.\n \"\"\"\n\n def __init__(self, name: str, guild_id: Optional[int]):\n self.name: str = name\n self.guild_id: Optional[int] = guild_id\n super().__init__(f'Command {name!r} already registered.')\n\n\nclass CommandNotFound(AppCommandError):\n \"\"\"An exception raised when an application command could not be found.\n\n This inherits from :exc:`~discord.app_commands.AppCommandError`.\n\n .. versionadded:: 2.0\n\n Attributes\n ------------\n name: :class:`str`\n The name of the application command not found.\n parents: List[:class:`str`]\n A list of parent command names that were previously found\n prior to the application command not being found.\n type: :class:`~discord.AppCommandType`\n The type of command that was not found.\n \"\"\"\n\n def __init__(self, name: str, parents: List[str], type: AppCommandType = AppCommandType.chat_input):\n self.name: str = name\n self.parents: List[str] = parents\n self.type: AppCommandType = type\n super().__init__(f'Application command {name!r} not found')\n\n\nclass CommandLimitReached(AppCommandError):\n \"\"\"An exception raised when the maximum number of application commands was reached\n either globally or in a guild.\n\n This inherits from :exc:`~discord.app_commands.AppCommandError`.\n\n .. versionadded:: 2.0\n\n Attributes\n ------------\n type: :class:`~discord.AppCommandType`\n The type of command that reached the limit.\n guild_id: Optional[:class:`int`]\n The guild ID that reached the limit or ``None`` if it was global.\n limit: :class:`int`\n The limit that was hit.\n \"\"\"\n\n def __init__(self, guild_id: Optional[int], limit: int, type: AppCommandType = AppCommandType.chat_input):\n self.guild_id: Optional[int] = guild_id\n self.limit: int = limit\n self.type: AppCommandType = type\n\n lookup = {\n AppCommandType.chat_input: 'slash commands',\n AppCommandType.message: 'message context menu commands',\n AppCommandType.user: 'user context menu commands',\n }\n desc = lookup.get(type, 'application commands')\n ns = 'globally' if self.guild_id is None else f'for guild ID {self.guild_id}'\n super().__init__(f'maximum number of {desc} exceeded {limit} {ns}')\n\n\nclass CommandSignatureMismatch(AppCommandError):\n \"\"\"An exception raised when an application command from Discord has a different signature\n from the one provided in the code. This happens because your command definition differs\n from the command definition you provided Discord. Either your code is out of date or the\n data from Discord is out of sync.\n\n This inherits from :exc:`~discord.app_commands.AppCommandError`.\n\n .. versionadded:: 2.0\n\n Attributes\n ------------\n command: Union[:class:`~.app_commands.Command`, :class:`~.app_commands.ContextMenu`, :class:`~.app_commands.Group`]\n The command that had the signature mismatch.\n \"\"\"\n\n def __init__(self, command: Union[Command[Any, ..., Any], ContextMenu, Group]):\n self.command: Union[Command[Any, ..., Any], ContextMenu, Group] = command\n msg = (\n f'The signature for command {command.name!r} is different from the one provided by Discord. '\n 'This can happen because either your code is out of date or you have not synced the '\n 'commands with Discord, causing the mismatch in data. It is recommended to sync the '\n 'command tree to fix this issue.'\n )\n super().__init__(msg)\n\n\nclass MissingApplicationID(AppCommandError):\n \"\"\"An exception raised when the client does not have an application ID set.\n An application ID is required for syncing application commands.\n\n This inherits from :exc:`~discord.app_commands.AppCommandError`.\n\n .. versionadded:: 2.0\n \"\"\"\n\n def __init__(self, message: Optional[str] = None):\n super().__init__(message or APP_ID_NOT_FOUND)\n\n\ndef _get_command_error(\n index: str,\n inner: Any,\n objects: Sequence[Union[Parameter, CommandTypes]],\n messages: List[str],\n indent: int = 0,\n) -> None:\n # Import these here to avoid circular imports\n from .commands import Command, Group, ContextMenu\n\n indentation = ' ' * indent\n\n # Top level errors are:\n # : { : }\n # The dicts could be nested, e.g.\n # : { : { : } }\n # Luckily, this is already handled by the flatten_error_dict utility\n if not index.isdigit():\n errors = _flatten_error_dict(inner, index)\n messages.extend(f'In {k}: {v}' for k, v in errors.items())\n return\n\n idx = int(index)\n try:\n obj = objects[idx]\n except IndexError:\n dedent_one_level = ' ' * (indent - 2)\n errors = _flatten_error_dict(inner, index)\n messages.extend(f'{dedent_one_level}In {k}: {v}' for k, v in errors.items())\n return\n\n children: Sequence[Union[Parameter, CommandTypes]] = []\n if isinstance(obj, Command):\n messages.append(f'{indentation}In command {obj.qualified_name!r} defined in function {obj.callback.__qualname__!r}')\n children = obj.parameters\n elif isinstance(obj, Group):\n messages.append(f'{indentation}In group {obj.qualified_name!r} defined in module {obj.module!r}')\n children = obj.commands\n elif isinstance(obj, ContextMenu):\n messages.append(\n f'{indentation}In context menu {obj.qualified_name!r} defined in function {obj.callback.__qualname__!r}'\n )\n else:\n messages.append(f'{indentation}In parameter {obj.name!r}')\n\n for key, remaining in inner.items():\n # Special case the 'options' key since they have well defined meanings\n if key == 'options':\n for index, d in remaining.items():\n _get_command_error(index, d, children, messages, indent=indent + 2)\n else:\n if isinstance(remaining, dict):\n try:\n inner_errors = remaining['_errors']\n except KeyError:\n errors = _flatten_error_dict(remaining, key=key)\n else:\n errors = {key: ' '.join(x.get('message', '') for x in inner_errors)}\n else:\n errors = _flatten_error_dict(remaining, key=key)\n\n messages.extend(f'{indentation} {k}: {v}' for k, v in errors.items())\n\n\nclass CommandSyncFailure(AppCommandError, HTTPException):\n \"\"\"An exception raised when :meth:`CommandTree.sync` failed.\n\n This provides syncing failures in a slightly more readable format.\n\n This inherits from :exc:`~discord.app_commands.AppCommandError`\n and :exc:`~discord.HTTPException`.\n\n .. versionadded:: 2.0\n \"\"\"\n\n def __init__(self, child: HTTPException, commands: List[CommandTypes]) -> None:\n # Consume the child exception and make it seem as if we are that exception\n self.__dict__.update(child.__dict__)\n\n messages = [f'Failed to upload commands to Discord (HTTP status {self.status}, error code {self.code})']\n\n if self._errors:\n # Handle case where the errors dict has no actual chain such as APPLICATION_COMMAND_TOO_LARGE\n if len(self._errors) == 1 and '_errors' in self._errors:\n errors = self._errors['_errors']\n if len(errors) == 1:\n extra = errors[0].get('message')\n if extra:\n messages[0] += f': {extra}'\n else:\n messages.extend(f'Error {e.get(\"code\", \"\")}: {e.get(\"message\", \"\")}' for e in errors)\n else:\n for index, inner in self._errors.items():\n _get_command_error(index, inner, commands, messages)\n\n # Equivalent to super().__init__(...) but skips other constructors\n self.args = ('\\n'.join(messages),)\n" }, { "path": "discord/app_commands/installs.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TYPE_CHECKING, ClassVar, List, Optional, Sequence\n\n__all__ = (\n 'AppInstallationType',\n 'AppCommandContext',\n)\n\nif TYPE_CHECKING:\n from typing_extensions import Self\n from ..types.interactions import InteractionContextType, InteractionInstallationType\n\n\nclass AppInstallationType:\n r\"\"\"Represents the installation location of an application command.\n\n .. versionadded:: 2.4\n\n Parameters\n -----------\n guild: Optional[:class:`bool`]\n Whether the integration is a guild install.\n user: Optional[:class:`bool`]\n Whether the integration is a user install.\n \"\"\"\n\n __slots__ = ('_guild', '_user')\n\n GUILD: ClassVar[int] = 0\n USER: ClassVar[int] = 1\n\n def __init__(self, *, guild: Optional[bool] = None, user: Optional[bool] = None):\n self._guild: Optional[bool] = guild\n self._user: Optional[bool] = user\n\n @property\n def guild(self) -> bool:\n \"\"\":class:`bool`: Whether the integration is a guild install.\"\"\"\n return bool(self._guild)\n\n @guild.setter\n def guild(self, value: bool) -> None:\n self._guild = bool(value)\n\n @property\n def user(self) -> bool:\n \"\"\":class:`bool`: Whether the integration is a user install.\"\"\"\n return bool(self._user)\n\n @user.setter\n def user(self, value: bool) -> None:\n self._user = bool(value)\n\n def merge(self, other: AppInstallationType) -> AppInstallationType:\n # Merging is similar to AllowedMentions where `self` is the base\n # and the `other` is the override preference\n guild = self._guild if other._guild is None else other._guild\n user = self._user if other._user is None else other._user\n return AppInstallationType(guild=guild, user=user)\n\n def _is_unset(self) -> bool:\n return all(x is None for x in (self._guild, self._user))\n\n def _merge_to_array(self, other: Optional[AppInstallationType]) -> Optional[List[InteractionInstallationType]]:\n result = self.merge(other) if other is not None else self\n if result._is_unset():\n return None\n return result.to_array()\n\n @classmethod\n def _from_value(cls, value: Sequence[InteractionInstallationType]) -> Self:\n self = cls()\n for x in value:\n if x == cls.GUILD:\n self._guild = True\n elif x == cls.USER:\n self._user = True\n return self\n\n def to_array(self) -> List[InteractionInstallationType]:\n values = []\n if self._guild:\n values.append(self.GUILD)\n if self._user:\n values.append(self.USER)\n return values\n\n\nclass AppCommandContext:\n r\"\"\"Wraps up the Discord :class:`~discord.app_commands.Command` execution context.\n\n .. versionadded:: 2.4\n\n Parameters\n -----------\n guild: Optional[:class:`bool`]\n Whether the context allows usage in a guild.\n dm_channel: Optional[:class:`bool`]\n Whether the context allows usage in a DM channel.\n private_channel: Optional[:class:`bool`]\n Whether the context allows usage in a DM or a GDM channel.\n \"\"\"\n\n GUILD: ClassVar[int] = 0\n DM_CHANNEL: ClassVar[int] = 1\n PRIVATE_CHANNEL: ClassVar[int] = 2\n\n __slots__ = ('_guild', '_dm_channel', '_private_channel')\n\n def __init__(\n self,\n *,\n guild: Optional[bool] = None,\n dm_channel: Optional[bool] = None,\n private_channel: Optional[bool] = None,\n ):\n self._guild: Optional[bool] = guild\n self._dm_channel: Optional[bool] = dm_channel\n self._private_channel: Optional[bool] = private_channel\n\n @property\n def guild(self) -> bool:\n \"\"\":class:`bool`: Whether the context allows usage in a guild.\"\"\"\n return bool(self._guild)\n\n @guild.setter\n def guild(self, value: bool) -> None:\n self._guild = bool(value)\n\n @property\n def dm_channel(self) -> bool:\n \"\"\":class:`bool`: Whether the context allows usage in a DM channel.\"\"\"\n return bool(self._dm_channel)\n\n @dm_channel.setter\n def dm_channel(self, value: bool) -> None:\n self._dm_channel = bool(value)\n\n @property\n def private_channel(self) -> bool:\n \"\"\":class:`bool`: Whether the context allows usage in a DM or a GDM channel.\"\"\"\n return bool(self._private_channel)\n\n @private_channel.setter\n def private_channel(self, value: bool) -> None:\n self._private_channel = bool(value)\n\n def merge(self, other: AppCommandContext) -> AppCommandContext:\n guild = self._guild if other._guild is None else other._guild\n dm_channel = self._dm_channel if other._dm_channel is None else other._dm_channel\n private_channel = self._private_channel if other._private_channel is None else other._private_channel\n return AppCommandContext(guild=guild, dm_channel=dm_channel, private_channel=private_channel)\n\n def _is_unset(self) -> bool:\n return all(x is None for x in (self._guild, self._dm_channel, self._private_channel))\n\n def _merge_to_array(self, other: Optional[AppCommandContext]) -> Optional[List[InteractionContextType]]:\n result = self.merge(other) if other is not None else self\n if result._is_unset():\n return None\n return result.to_array()\n\n @classmethod\n def _from_value(cls, value: Sequence[InteractionContextType]) -> Self:\n self = cls()\n for x in value:\n if x == cls.GUILD:\n self._guild = True\n elif x == cls.DM_CHANNEL:\n self._dm_channel = True\n elif x == cls.PRIVATE_CHANNEL:\n self._private_channel = True\n return self\n\n def to_array(self) -> List[InteractionContextType]:\n values = []\n if self._guild:\n values.append(self.GUILD)\n if self._dm_channel:\n values.append(self.DM_CHANNEL)\n if self._private_channel:\n values.append(self.PRIVATE_CHANNEL)\n return values\n" }, { "path": "discord/app_commands/models.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\nfrom datetime import datetime\n\nfrom .errors import MissingApplicationID\nfrom ..flags import AppCommandContext, AppInstallationType\nfrom .translator import TranslationContextLocation, TranslationContext, locale_str, Translator\nfrom ..permissions import Permissions\nfrom ..enums import (\n AppCommandOptionType,\n AppCommandType,\n AppCommandPermissionType,\n ChannelType,\n Locale,\n try_enum,\n)\nfrom ..mixins import Hashable\nfrom ..utils import _get_as_snowflake, parse_time, snowflake_time, MISSING\nfrom ..object import Object\nfrom ..role import Role\nfrom ..member import Member\n\nfrom typing import Any, Dict, Generic, List, TYPE_CHECKING, Optional, TypeVar, Union\n\n__all__ = (\n 'AppCommand',\n 'AppCommandGroup',\n 'AppCommandChannel',\n 'AppCommandThread',\n 'AppCommandPermissions',\n 'GuildAppCommandPermissions',\n 'Argument',\n 'Choice',\n 'AllChannels',\n)\n\nChoiceT = TypeVar('ChoiceT', str, int, float, Union[str, int, float])\n\n\ndef is_app_command_argument_type(value: int) -> bool:\n return 11 >= value >= 3\n\n\nif TYPE_CHECKING:\n from ..types.command import (\n ApplicationCommand as ApplicationCommandPayload,\n ApplicationCommandOption,\n ApplicationCommandOptionChoice,\n ApplicationCommandPermissions,\n GuildApplicationCommandPermissions,\n )\n from ..types.interactions import (\n PartialChannel,\n PartialThread,\n )\n from ..types.threads import (\n ThreadMetadata,\n ThreadArchiveDuration,\n )\n\n from ..abc import Snowflake\n from ..state import ConnectionState\n from ..guild import GuildChannel, Guild\n from ..channel import TextChannel\n from ..threads import Thread\n from ..user import User\n\n ApplicationCommandParent = Union['AppCommand', 'AppCommandGroup']\n\n\nclass AllChannels:\n \"\"\"Represents all channels for application command permissions.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n guild: :class:`~discord.Guild`\n The guild the application command permission is for.\n \"\"\"\n\n __slots__ = ('guild',)\n\n def __init__(self, guild: Guild):\n self.guild: Guild = guild\n\n @property\n def id(self) -> int:\n \"\"\":class:`int`: The ID sentinel used to represent all channels. Equivalent to the guild's ID minus 1.\"\"\"\n return self.guild.id - 1\n\n def __repr__(self) -> str:\n return f''\n\n\ndef _to_locale_dict(data: Dict[str, str]) -> Dict[Locale, str]:\n return {try_enum(Locale, key): value for key, value in data.items()}\n\n\nclass AppCommand(Hashable):\n \"\"\"Represents an application command.\n\n In common parlance this is referred to as a \"Slash Command\" or a\n \"Context Menu Command\".\n\n .. versionadded:: 2.0\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two application commands are equal.\n\n .. describe:: x != y\n\n Checks if two application commands are not equal.\n\n .. describe:: hash(x)\n\n Returns the application command's hash.\n\n .. describe:: str(x)\n\n Returns the application command's name.\n\n Attributes\n -----------\n id: :class:`int`\n The application command's ID.\n application_id: :class:`int`\n The application command's application's ID.\n type: :class:`~discord.AppCommandType`\n The application command's type.\n name: :class:`str`\n The application command's name.\n description: :class:`str`\n The application command's description.\n name_localizations: Dict[:class:`~discord.Locale`, :class:`str`]\n The localised names of the application command. Used for display purposes.\n description_localizations: Dict[:class:`~discord.Locale`, :class:`str`]\n The localised descriptions of the application command. Used for display purposes.\n options: List[Union[:class:`Argument`, :class:`AppCommandGroup`]]\n A list of options.\n default_member_permissions: Optional[:class:`~discord.Permissions`]\n The default member permissions that can run this command.\n dm_permission: :class:`bool`\n A boolean that indicates whether this command can be run in direct messages.\n allowed_contexts: Optional[:class:`~discord.app_commands.AppCommandContext`]\n The contexts that this command is allowed to be used in. Overrides the ``dm_permission`` attribute.\n\n .. versionadded:: 2.4\n allowed_installs: Optional[:class:`~discord.app_commands.AppInstallationType`]\n The installation contexts that this command is allowed to be installed in.\n\n .. versionadded:: 2.4\n guild_id: Optional[:class:`int`]\n The ID of the guild this command is registered in. A value of ``None``\n denotes that it is a global command.\n nsfw: :class:`bool`\n Whether the command is NSFW and should only work in NSFW channels.\n \"\"\"\n\n __slots__ = (\n 'id',\n 'type',\n 'application_id',\n 'name',\n 'description',\n 'name_localizations',\n 'description_localizations',\n 'guild_id',\n 'options',\n 'default_member_permissions',\n 'dm_permission',\n 'allowed_contexts',\n 'allowed_installs',\n 'nsfw',\n '_state',\n )\n\n def __init__(self, *, data: ApplicationCommandPayload, state: ConnectionState) -> None:\n self._state: ConnectionState = state\n self._from_data(data)\n\n def _from_data(self, data: ApplicationCommandPayload) -> None:\n self.id: int = int(data['id'])\n self.application_id: int = int(data['application_id'])\n self.name: str = data['name']\n self.description: str = data['description']\n self.guild_id: Optional[int] = _get_as_snowflake(data, 'guild_id')\n self.type: AppCommandType = try_enum(AppCommandType, data.get('type', 1))\n self.options: List[Union[Argument, AppCommandGroup]] = [\n app_command_option_factory(data=d, parent=self, state=self._state) for d in data.get('options', [])\n ]\n self.default_member_permissions: Optional[Permissions]\n permissions = data.get('default_member_permissions')\n if permissions is None:\n self.default_member_permissions = None\n else:\n self.default_member_permissions = Permissions(int(permissions))\n\n dm_permission = data.get('dm_permission')\n # For some reason this field can be explicit null and mean True\n if dm_permission is None:\n dm_permission = True\n\n self.dm_permission: bool = dm_permission\n\n allowed_contexts = data.get('contexts')\n if allowed_contexts is None:\n self.allowed_contexts: Optional[AppCommandContext] = None\n else:\n self.allowed_contexts = AppCommandContext._from_value(allowed_contexts)\n\n allowed_installs = data.get('integration_types')\n if allowed_installs is None:\n self.allowed_installs: Optional[AppInstallationType] = None\n else:\n self.allowed_installs = AppInstallationType._from_value(allowed_installs)\n\n self.nsfw: bool = data.get('nsfw', False)\n self.name_localizations: Dict[Locale, str] = _to_locale_dict(data.get('name_localizations') or {})\n self.description_localizations: Dict[Locale, str] = _to_locale_dict(data.get('description_localizations') or {})\n\n def to_dict(self) -> ApplicationCommandPayload:\n return {\n 'id': self.id,\n 'type': self.type.value,\n 'application_id': self.application_id,\n 'name': self.name,\n 'description': self.description,\n 'name_localizations': {str(k): v for k, v in self.name_localizations.items()},\n 'description_localizations': {str(k): v for k, v in self.description_localizations.items()},\n 'contexts': self.allowed_contexts.to_array() if self.allowed_contexts is not None else None,\n 'integration_types': self.allowed_installs.to_array() if self.allowed_installs is not None else None,\n 'options': [opt.to_dict() for opt in self.options],\n } # type: ignore # Type checker does not understand this literal.\n\n def __str__(self) -> str:\n return self.name\n\n def __repr__(self) -> str:\n return f'<{self.__class__.__name__} id={self.id!r} name={self.name!r} type={self.type!r}>'\n\n @property\n def mention(self) -> str:\n \"\"\":class:`str`: Returns a string that allows you to mention the given AppCommand.\"\"\"\n return f''\n\n @property\n def guild(self) -> Optional[Guild]:\n \"\"\"Optional[:class:`~discord.Guild`]: Returns the guild this command is registered to\n if it exists.\n \"\"\"\n return self._state._get_guild(self.guild_id)\n\n async def delete(self) -> None:\n \"\"\"|coro|\n\n Deletes the application command.\n\n Raises\n -------\n NotFound\n The application command was not found.\n Forbidden\n You do not have permission to delete this application command.\n HTTPException\n Deleting the application command failed.\n MissingApplicationID\n The client does not have an application ID.\n \"\"\"\n state = self._state\n if not state.application_id:\n raise MissingApplicationID\n\n if self.guild_id:\n await state.http.delete_guild_command(\n state.application_id,\n self.guild_id,\n self.id,\n )\n else:\n await state.http.delete_global_command(\n state.application_id,\n self.id,\n )\n\n async def edit(\n self,\n *,\n name: str = MISSING,\n description: str = MISSING,\n default_member_permissions: Optional[Permissions] = MISSING,\n dm_permission: bool = MISSING,\n options: List[Union[Argument, AppCommandGroup]] = MISSING,\n ) -> AppCommand:\n \"\"\"|coro|\n\n Edits the application command.\n\n Parameters\n -----------\n name: :class:`str`\n The new name for the application command.\n description: :class:`str`\n The new description for the application command.\n default_member_permissions: Optional[:class:`~discord.Permissions`]\n The new default permissions needed to use this application command.\n Pass value of ``None`` to remove any permission requirements.\n dm_permission: :class:`bool`\n Indicates if the application command can be used in DMs.\n options: List[Union[:class:`Argument`, :class:`AppCommandGroup`]]\n List of new options for this application command.\n\n Raises\n -------\n NotFound\n The application command was not found.\n Forbidden\n You do not have permission to edit this application command.\n HTTPException\n Editing the application command failed.\n MissingApplicationID\n The client does not have an application ID.\n\n Returns\n --------\n :class:`AppCommand`\n The newly edited application command.\n \"\"\"\n state = self._state\n if not state.application_id:\n raise MissingApplicationID\n\n payload = {}\n\n if name is not MISSING:\n payload['name'] = name\n\n if description is not MISSING:\n payload['description'] = description\n\n if default_member_permissions is not MISSING:\n if default_member_permissions is not None:\n payload['default_member_permissions'] = default_member_permissions.value\n else:\n payload['default_member_permissions'] = None\n\n if self.guild_id is None and dm_permission is not MISSING:\n payload['dm_permission'] = dm_permission\n\n if options is not MISSING:\n payload['options'] = [option.to_dict() for option in options]\n\n if not payload:\n return self\n\n if self.guild_id:\n data = await state.http.edit_guild_command(\n state.application_id,\n self.guild_id,\n self.id,\n payload,\n )\n else:\n data = await state.http.edit_global_command(\n state.application_id,\n self.id,\n payload,\n )\n return AppCommand(data=data, state=state)\n\n async def fetch_permissions(self, guild: Snowflake) -> GuildAppCommandPermissions:\n \"\"\"|coro|\n\n Retrieves this command's permission in the guild.\n\n Parameters\n -----------\n guild: :class:`~discord.abc.Snowflake`\n The guild to retrieve the permissions from.\n\n Raises\n -------\n Forbidden\n You do not have permission to fetch the application command's permissions.\n HTTPException\n Fetching the application command's permissions failed.\n MissingApplicationID\n The client does not have an application ID.\n NotFound\n The application command's permissions could not be found.\n This can also indicate that the permissions are synced with the guild\n (i.e. they are unchanged from the default).\n\n Returns\n --------\n :class:`GuildAppCommandPermissions`\n An object representing the application command's permissions in the guild.\n \"\"\"\n state = self._state\n if not state.application_id:\n raise MissingApplicationID\n\n data = await state.http.get_application_command_permissions(\n state.application_id,\n guild.id,\n self.id,\n )\n return GuildAppCommandPermissions(data=data, state=state, command=self)\n\n\nclass Choice(Generic[ChoiceT]):\n \"\"\"Represents an application command argument choice.\n\n .. versionadded:: 2.0\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two choices are equal.\n\n .. describe:: x != y\n\n Checks if two choices are not equal.\n\n .. describe:: hash(x)\n\n Returns the choice's hash.\n\n Parameters\n -----------\n name: Union[:class:`str`, :class:`locale_str`]\n The name of the choice. Used for display purposes.\n Can only be up to 100 characters.\n name_localizations: Dict[:class:`~discord.Locale`, :class:`str`]\n The localised names of the choice. Used for display purposes.\n value: Union[:class:`int`, :class:`str`, :class:`float`]\n The value of the choice. If it's a string, it can only be\n up to 100 characters long.\n \"\"\"\n\n __slots__ = ('name', 'value', '_locale_name', 'name_localizations')\n\n def __init__(self, *, name: Union[str, locale_str], value: ChoiceT):\n name, locale = (name.message, name) if isinstance(name, locale_str) else (name, None)\n self.name: str = name\n self._locale_name: Optional[locale_str] = locale\n self.value: ChoiceT = value\n self.name_localizations: Dict[Locale, str] = {}\n\n @classmethod\n def from_dict(cls, data: ApplicationCommandOptionChoice) -> Choice[ChoiceT]:\n self = cls.__new__(cls)\n self.name = data['name']\n self.value = data['value'] # type: ignore # This seems to break every other pyright release\n self.name_localizations = _to_locale_dict(data.get('name_localizations') or {})\n return self\n\n def __eq__(self, o: object) -> bool:\n return isinstance(o, Choice) and self.name == o.name and self.value == o.value\n\n def __hash__(self) -> int:\n return hash((self.name, self.value))\n\n def __repr__(self) -> str:\n return f'{self.__class__.__name__}(name={self.name!r}, value={self.value!r})'\n\n @property\n def _option_type(self) -> AppCommandOptionType:\n if isinstance(self.value, int):\n return AppCommandOptionType.integer\n elif isinstance(self.value, float):\n return AppCommandOptionType.number\n elif isinstance(self.value, str):\n return AppCommandOptionType.string\n else:\n raise TypeError(\n f'invalid Choice value type given, expected int, str, or float but received {self.value.__class__.__name__}'\n )\n\n async def get_translated_payload(self, translator: Translator) -> Dict[str, Any]:\n base = self.to_dict()\n name_localizations: Dict[str, str] = {}\n context = TranslationContext(location=TranslationContextLocation.choice_name, data=self)\n if self._locale_name:\n for locale in Locale:\n translation = await translator._checked_translate(self._locale_name, locale, context)\n if translation is not None:\n name_localizations[locale.value] = translation\n\n if name_localizations:\n base['name_localizations'] = name_localizations\n\n return base\n\n async def get_translated_payload_for_locale(self, translator: Translator, locale: Locale) -> Dict[str, Any]:\n base = self.to_dict()\n if self._locale_name:\n context = TranslationContext(location=TranslationContextLocation.choice_name, data=self)\n translation = await translator._checked_translate(self._locale_name, locale, context)\n if translation is not None:\n base['name'] = translation\n\n return base\n\n def to_dict(self) -> Dict[str, Any]:\n base = {\n 'name': self.name,\n 'value': self.value,\n }\n if self.name_localizations:\n base['name_localizations'] = {str(k): v for k, v in self.name_localizations.items()}\n return base\n\n\nclass AppCommandChannel(Hashable):\n \"\"\"Represents an application command partially resolved channel object.\n\n .. versionadded:: 2.0\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two channels are equal.\n\n .. describe:: x != y\n\n Checks if two channels are not equal.\n\n .. describe:: hash(x)\n\n Returns the channel's hash.\n\n .. describe:: str(x)\n\n Returns the channel's name.\n\n Attributes\n -----------\n id: :class:`int`\n The ID of the channel.\n type: :class:`~discord.ChannelType`\n The type of channel.\n name: :class:`str`\n The name of the channel.\n permissions: :class:`~discord.Permissions`\n The resolved permissions of the user who invoked\n the application command in that channel.\n guild_id: :class:`int`\n The guild ID this channel belongs to.\n \"\"\"\n\n __slots__ = (\n 'id',\n 'type',\n 'name',\n 'permissions',\n 'guild_id',\n '_state',\n )\n\n def __init__(\n self,\n *,\n state: ConnectionState,\n data: PartialChannel,\n guild_id: int,\n ):\n self._state: ConnectionState = state\n self.guild_id: int = guild_id\n self.id: int = int(data['id'])\n self.type: ChannelType = try_enum(ChannelType, data['type'])\n self.name: str = data['name']\n self.permissions: Permissions = Permissions(int(data['permissions']))\n\n def __str__(self) -> str:\n return self.name\n\n def __repr__(self) -> str:\n return f'<{self.__class__.__name__} id={self.id!r} name={self.name!r} type={self.type!r}>'\n\n @property\n def guild(self) -> Optional[Guild]:\n \"\"\"Optional[:class:`~discord.Guild`]: The channel's guild, from cache, if found.\"\"\"\n return self._state._get_guild(self.guild_id)\n\n def resolve(self) -> Optional[GuildChannel]:\n \"\"\"Resolves the application command channel to the appropriate channel\n from cache if found.\n\n Returns\n --------\n Optional[:class:`.abc.GuildChannel`]\n The resolved guild channel or ``None`` if not found in cache.\n \"\"\"\n guild = self._state._get_guild(self.guild_id)\n if guild is not None:\n return guild.get_channel(self.id)\n return None\n\n async def fetch(self) -> GuildChannel:\n \"\"\"|coro|\n\n Fetches the partial channel to a full :class:`.abc.GuildChannel`.\n\n Raises\n --------\n NotFound\n The channel was not found.\n Forbidden\n You do not have the permissions required to get a channel.\n HTTPException\n Retrieving the channel failed.\n\n Returns\n --------\n :class:`.abc.GuildChannel`\n The full channel.\n \"\"\"\n client = self._state._get_client()\n return await client.fetch_channel(self.id) # type: ignore # This is explicit narrowing\n\n @property\n def mention(self) -> str:\n \"\"\":class:`str`: The string that allows you to mention the channel.\"\"\"\n return f'<#{self.id}>'\n\n @property\n def created_at(self) -> datetime:\n \"\"\":class:`datetime.datetime`: An aware timestamp of when this channel was created in UTC.\"\"\"\n return snowflake_time(self.id)\n\n\nclass AppCommandThread(Hashable):\n \"\"\"Represents an application command partially resolved thread object.\n\n .. versionadded:: 2.0\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two thread are equal.\n\n .. describe:: x != y\n\n Checks if two thread are not equal.\n\n .. describe:: hash(x)\n\n Returns the thread's hash.\n\n .. describe:: str(x)\n\n Returns the thread's name.\n\n Attributes\n -----------\n id: :class:`int`\n The ID of the thread.\n type: :class:`~discord.ChannelType`\n The type of thread.\n name: :class:`str`\n The name of the thread.\n parent_id: :class:`int`\n The parent text channel ID this thread belongs to.\n permissions: :class:`~discord.Permissions`\n The resolved permissions of the user who invoked\n the application command in that thread.\n guild_id: :class:`int`\n The guild ID this thread belongs to.\n archived: :class:`bool`\n Whether the thread is archived.\n locked: :class:`bool`\n Whether the thread is locked.\n invitable: :class:`bool`\n Whether non-moderators can add other non-moderators to this thread.\n This is always ``True`` for public threads.\n archiver_id: Optional[:class:`int`]\n The user's ID that archived this thread.\n auto_archive_duration: :class:`int`\n The duration in minutes until the thread is automatically hidden from the channel list.\n Usually a value of 60, 1440, 4320 and 10080.\n archive_timestamp: :class:`datetime.datetime`\n An aware timestamp of when the thread's archived status was last updated in UTC.\n \"\"\"\n\n __slots__ = (\n 'id',\n 'type',\n 'name',\n 'permissions',\n 'guild_id',\n 'parent_id',\n 'archived',\n 'archiver_id',\n 'auto_archive_duration',\n 'archive_timestamp',\n 'locked',\n 'invitable',\n '_created_at',\n '_state',\n )\n\n def __init__(\n self,\n *,\n state: ConnectionState,\n data: PartialThread,\n guild_id: int,\n ):\n self._state: ConnectionState = state\n self.guild_id: int = guild_id\n self.id: int = int(data['id'])\n self.parent_id: int = int(data['parent_id'])\n self.type: ChannelType = try_enum(ChannelType, data['type'])\n self.name: str = data['name']\n self.permissions: Permissions = Permissions(int(data['permissions']))\n self._unroll_metadata(data['thread_metadata'])\n\n def __str__(self) -> str:\n return self.name\n\n def __repr__(self) -> str:\n return f'<{self.__class__.__name__} id={self.id!r} name={self.name!r} archived={self.archived} type={self.type!r}>'\n\n @property\n def guild(self) -> Optional[Guild]:\n \"\"\"Optional[:class:`~discord.Guild`]: The channel's guild, from cache, if found.\"\"\"\n return self._state._get_guild(self.guild_id)\n\n def _unroll_metadata(self, data: ThreadMetadata) -> None:\n self.archived: bool = data['archived']\n self.archiver_id: Optional[int] = _get_as_snowflake(data, 'archiver_id')\n self.auto_archive_duration: ThreadArchiveDuration = data['auto_archive_duration']\n self.archive_timestamp: datetime = parse_time(data['archive_timestamp'])\n self.locked: bool = data.get('locked', False)\n self.invitable: bool = data.get('invitable', True)\n self._created_at: Optional[datetime] = parse_time(data.get('create_timestamp'))\n\n @property\n def parent(self) -> Optional[TextChannel]:\n \"\"\"Optional[:class:`~discord.TextChannel`]: The parent channel this thread belongs to.\"\"\"\n return self.guild.get_channel(self.parent_id) # type: ignore\n\n @property\n def mention(self) -> str:\n \"\"\":class:`str`: The string that allows you to mention the thread.\"\"\"\n return f'<#{self.id}>'\n\n @property\n def created_at(self) -> Optional[datetime]:\n \"\"\"An aware timestamp of when the thread was created in UTC.\n\n .. note::\n\n This timestamp only exists for threads created after 9 January 2022, otherwise returns ``None``.\n \"\"\"\n return self._created_at\n\n def resolve(self) -> Optional[Thread]:\n \"\"\"Resolves the application command channel to the appropriate channel\n from cache if found.\n\n Returns\n --------\n Optional[:class:`.abc.GuildChannel`]\n The resolved guild channel or ``None`` if not found in cache.\n \"\"\"\n guild = self._state._get_guild(self.guild_id)\n if guild is not None:\n return guild.get_thread(self.id)\n return None\n\n async def fetch(self) -> Thread:\n \"\"\"|coro|\n\n Fetches the partial channel to a full :class:`~discord.Thread`.\n\n Raises\n --------\n NotFound\n The thread was not found.\n Forbidden\n You do not have the permissions required to get a thread.\n HTTPException\n Retrieving the thread failed.\n\n Returns\n --------\n :class:`~discord.Thread`\n The full thread.\n \"\"\"\n client = self._state._get_client()\n return await client.fetch_channel(self.id) # type: ignore # This is explicit narrowing\n\n\nclass Argument:\n \"\"\"Represents an application command argument.\n\n .. versionadded:: 2.0\n\n Attributes\n ------------\n type: :class:`~discord.AppCommandOptionType`\n The type of argument.\n name: :class:`str`\n The name of the argument.\n description: :class:`str`\n The description of the argument.\n name_localizations: Dict[:class:`~discord.Locale`, :class:`str`]\n The localised names of the argument. Used for display purposes.\n description_localizations: Dict[:class:`~discord.Locale`, :class:`str`]\n The localised descriptions of the argument. Used for display purposes.\n required: :class:`bool`\n Whether the argument is required.\n choices: List[:class:`Choice`]\n A list of choices for the command to choose from for this argument.\n parent: Union[:class:`AppCommand`, :class:`AppCommandGroup`]\n The parent application command that has this argument.\n channel_types: List[:class:`~discord.ChannelType`]\n The channel types that are allowed for this parameter.\n min_value: Optional[Union[:class:`int`, :class:`float`]]\n The minimum supported value for this parameter.\n max_value: Optional[Union[:class:`int`, :class:`float`]]\n The maximum supported value for this parameter.\n min_length: Optional[:class:`int`]\n The minimum allowed length for this parameter.\n max_length: Optional[:class:`int`]\n The maximum allowed length for this parameter.\n autocomplete: :class:`bool`\n Whether the argument has autocomplete.\n \"\"\"\n\n __slots__ = (\n 'type',\n 'name',\n 'description',\n 'name_localizations',\n 'description_localizations',\n 'required',\n 'choices',\n 'channel_types',\n 'min_value',\n 'max_value',\n 'min_length',\n 'max_length',\n 'autocomplete',\n 'parent',\n '_state',\n )\n\n def __init__(\n self, *, parent: ApplicationCommandParent, data: ApplicationCommandOption, state: Optional[ConnectionState] = None\n ) -> None:\n self._state: Optional[ConnectionState] = state\n self.parent: ApplicationCommandParent = parent\n self._from_data(data)\n\n def __repr__(self) -> str:\n return f'<{self.__class__.__name__} name={self.name!r} type={self.type!r} required={self.required}>'\n\n def _from_data(self, data: ApplicationCommandOption) -> None:\n self.type: AppCommandOptionType = try_enum(AppCommandOptionType, data['type'])\n self.name: str = data['name']\n self.description: str = data['description']\n self.required: bool = data.get('required', False)\n self.min_value: Optional[Union[int, float]] = data.get('min_value')\n self.max_value: Optional[Union[int, float]] = data.get('max_value')\n self.min_length: Optional[int] = data.get('min_length')\n self.max_length: Optional[int] = data.get('max_length')\n self.autocomplete: bool = data.get('autocomplete', False)\n self.channel_types: List[ChannelType] = [try_enum(ChannelType, d) for d in data.get('channel_types', [])]\n self.choices: List[Choice[Union[int, float, str]]] = [Choice.from_dict(d) for d in data.get('choices', [])]\n self.name_localizations: Dict[Locale, str] = _to_locale_dict(data.get('name_localizations') or {})\n self.description_localizations: Dict[Locale, str] = _to_locale_dict(data.get('description_localizations') or {})\n\n def to_dict(self) -> ApplicationCommandOption:\n return {\n 'name': self.name,\n 'type': self.type.value,\n 'description': self.description,\n 'required': self.required,\n 'choices': [choice.to_dict() for choice in self.choices],\n 'channel_types': [channel_type.value for channel_type in self.channel_types],\n 'min_value': self.min_value,\n 'max_value': self.max_value,\n 'min_length': self.min_length,\n 'max_length': self.max_length,\n 'autocomplete': self.autocomplete,\n 'options': [],\n 'name_localizations': {str(k): v for k, v in self.name_localizations.items()},\n 'description_localizations': {str(k): v for k, v in self.description_localizations.items()},\n } # type: ignore # Type checker does not understand this literal.\n\n\nclass AppCommandGroup:\n \"\"\"Represents an application command subcommand.\n\n .. versionadded:: 2.0\n\n Attributes\n ------------\n type: :class:`~discord.AppCommandOptionType`\n The type of subcommand.\n name: :class:`str`\n The name of the subcommand.\n description: :class:`str`\n The description of the subcommand.\n name_localizations: Dict[:class:`~discord.Locale`, :class:`str`]\n The localised names of the subcommand. Used for display purposes.\n description_localizations: Dict[:class:`~discord.Locale`, :class:`str`]\n The localised descriptions of the subcommand. Used for display purposes.\n options: List[Union[:class:`Argument`, :class:`AppCommandGroup`]]\n A list of options.\n parent: Union[:class:`AppCommand`, :class:`AppCommandGroup`]\n The parent application command.\n \"\"\"\n\n __slots__ = (\n 'type',\n 'name',\n 'description',\n 'name_localizations',\n 'description_localizations',\n 'options',\n 'parent',\n '_state',\n )\n\n def __init__(\n self, *, parent: ApplicationCommandParent, data: ApplicationCommandOption, state: Optional[ConnectionState] = None\n ) -> None:\n self.parent: ApplicationCommandParent = parent\n self._state: Optional[ConnectionState] = state\n self._from_data(data)\n\n def __repr__(self) -> str:\n return f'<{self.__class__.__name__} name={self.name!r} type={self.type!r}>'\n\n @property\n def qualified_name(self) -> str:\n \"\"\":class:`str`: Returns the fully qualified command name.\n\n The qualified name includes the parent name as well. For example,\n in a command like ``/foo bar`` the qualified name is ``foo bar``.\n \"\"\"\n # A B C\n # ^ self\n # ^ parent\n # ^ grandparent\n names = [self.name, self.parent.name]\n if isinstance(self.parent, AppCommandGroup):\n names.append(self.parent.parent.name)\n\n return ' '.join(reversed(names))\n\n @property\n def mention(self) -> str:\n \"\"\":class:`str`: Returns a string that allows you to mention the given AppCommandGroup.\"\"\"\n if isinstance(self.parent, AppCommand):\n base_command = self.parent\n else:\n base_command = self.parent.parent\n return f'' # type: ignore\n\n def _from_data(self, data: ApplicationCommandOption) -> None:\n self.type: AppCommandOptionType = try_enum(AppCommandOptionType, data['type'])\n self.name: str = data['name']\n self.description: str = data['description']\n self.options: List[Union[Argument, AppCommandGroup]] = [\n app_command_option_factory(data=d, parent=self, state=self._state) for d in data.get('options', [])\n ]\n self.name_localizations: Dict[Locale, str] = _to_locale_dict(data.get('name_localizations') or {})\n self.description_localizations: Dict[Locale, str] = _to_locale_dict(data.get('description_localizations') or {})\n\n def to_dict(self) -> 'ApplicationCommandOption':\n return {\n 'name': self.name,\n 'type': self.type.value,\n 'description': self.description,\n 'options': [arg.to_dict() for arg in self.options],\n 'name_localizations': {str(k): v for k, v in self.name_localizations.items()},\n 'description_localizations': {str(k): v for k, v in self.description_localizations.items()},\n } # type: ignore # Type checker does not understand this literal.\n\n\nclass AppCommandPermissions:\n \"\"\"Represents the permissions for an application command.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n guild: :class:`~discord.Guild`\n The guild associated with this permission.\n id: :class:`int`\n The ID of the permission target, such as a role, channel, or guild.\n The special ``guild_id - 1`` sentinel is used to represent \"all channels\".\n target: Any\n The role, user, or channel associated with this permission. This could also be the :class:`AllChannels` sentinel type.\n Falls back to :class:`~discord.Object` if the target could not be found in the cache.\n type: :class:`.AppCommandPermissionType`\n The type of permission.\n permission: :class:`bool`\n The permission value. ``True`` for allow, ``False`` for deny.\n \"\"\"\n\n __slots__ = ('id', 'type', 'permission', 'target', 'guild', '_state')\n\n def __init__(self, *, data: ApplicationCommandPermissions, guild: Guild, state: ConnectionState) -> None:\n self._state: ConnectionState = state\n self.guild: Guild = guild\n\n self.id: int = int(data['id'])\n self.type: AppCommandPermissionType = try_enum(AppCommandPermissionType, data['type'])\n self.permission: bool = data['permission']\n\n _object = None\n _type = MISSING\n\n if self.type is AppCommandPermissionType.user:\n _object = guild.get_member(self.id) or self._state.get_user(self.id)\n _type = Member\n elif self.type is AppCommandPermissionType.channel:\n if self.id == (guild.id - 1):\n _object = AllChannels(guild)\n else:\n _object = guild.get_channel(self.id)\n elif self.type is AppCommandPermissionType.role:\n _object = guild.get_role(self.id)\n _type = Role\n\n if _object is None:\n _object = Object(id=self.id, type=_type)\n\n self.target: Union[Object, User, Member, Role, AllChannels, GuildChannel] = _object\n\n def to_dict(self) -> ApplicationCommandPermissions:\n return {\n 'id': self.target.id,\n 'type': self.type.value,\n 'permission': self.permission,\n }\n\n\nclass GuildAppCommandPermissions:\n \"\"\"Represents the permissions for an application command in a guild.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n application_id: :class:`int`\n The application ID.\n command: :class:`.AppCommand`\n The application command associated with the permissions.\n id: :class:`int`\n ID of the command or the application ID.\n When this is the application ID instead of a command ID,\n the permissions apply to all commands that do not contain explicit overwrites.\n guild_id: :class:`int`\n The guild ID associated with the permissions.\n permissions: List[:class:`AppCommandPermissions`]\n The permissions, this is a max of 100.\n \"\"\"\n\n __slots__ = ('id', 'application_id', 'command', 'guild_id', 'permissions', '_state')\n\n def __init__(self, *, data: GuildApplicationCommandPermissions, state: ConnectionState, command: AppCommand) -> None:\n self._state: ConnectionState = state\n self.command: AppCommand = command\n\n self.id: int = int(data['id'])\n self.application_id: int = int(data['application_id'])\n self.guild_id: int = int(data['guild_id'])\n guild = self.guild\n self.permissions: List[AppCommandPermissions] = [\n AppCommandPermissions(data=value, guild=guild, state=self._state) for value in data['permissions']\n ]\n\n def to_dict(self) -> Dict[str, Any]:\n return {'permissions': [p.to_dict() for p in self.permissions]}\n\n @property\n def guild(self) -> Guild:\n \"\"\":class:`~discord.Guild`: The guild associated with the permissions.\"\"\"\n return self._state._get_or_create_unavailable_guild(self.guild_id)\n\n\ndef app_command_option_factory(\n parent: ApplicationCommandParent, data: ApplicationCommandOption, *, state: Optional[ConnectionState] = None\n) -> Union[Argument, AppCommandGroup]:\n if is_app_command_argument_type(data['type']):\n return Argument(parent=parent, data=data, state=state)\n else:\n return AppCommandGroup(parent=parent, data=data, state=state)\n" }, { "path": "discord/app_commands/namespace.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import TYPE_CHECKING, Any, Dict, Iterable, Iterator, List, NamedTuple, Tuple\nfrom ..member import Member\nfrom ..object import Object\nfrom ..role import Role\nfrom ..message import Message, Attachment\nfrom ..channel import PartialMessageable\nfrom ..enums import AppCommandOptionType\nfrom .models import AppCommandChannel, AppCommandThread\n\nif TYPE_CHECKING:\n from ..interactions import Interaction\n from ..types.interactions import ResolvedData, ApplicationCommandInteractionDataOption\n\n__all__ = ('Namespace',)\n\n\nclass ResolveKey(NamedTuple):\n id: str\n # CommandOptionType does not use 0 or negative numbers so those can be safe for library\n # internal use, if necessary. Likewise, only 6, 7, 8, and 11 are actually in use.\n type: int\n\n @classmethod\n def any_with(cls, id: str) -> ResolveKey:\n return ResolveKey(id=id, type=-1)\n\n def __eq__(self, o: object) -> bool:\n if not isinstance(o, ResolveKey):\n return NotImplemented\n if self.type == -1 or o.type == -1:\n return self.id == o.id\n return (self.id, self.type) == (o.id, o.type)\n\n def __hash__(self) -> int:\n # Most of the time an ID lookup is all that is necessary\n # In case of collision then we look up both the ID and the type.\n return hash(self.id)\n\n\nclass Namespace:\n \"\"\"An object that holds the parameters being passed to a command in a mostly raw state.\n\n This class is deliberately simple and just holds the option name and resolved value as a simple\n key-pair mapping. These attributes can be accessed using dot notation. For example, an option\n with the name of ``example`` can be accessed using ``ns.example``. If an attribute is not found,\n then ``None`` is returned rather than an attribute error.\n\n .. warning::\n\n The key names come from the raw Discord data, which means that if a parameter was renamed then the\n renamed key is used instead of the function parameter name.\n\n .. versionadded:: 2.0\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two namespaces are equal by checking if all attributes are equal.\n .. describe:: x != y\n\n Checks if two namespaces are not equal.\n .. describe:: x[key]\n\n Returns an attribute if it is found, otherwise raises\n a :exc:`KeyError`.\n .. describe:: key in x\n\n Checks if the attribute is in the namespace.\n .. describe:: iter(x)\n\n Returns an iterator of ``(name, value)`` pairs. This allows it\n to be, for example, constructed as a dict or a list of pairs.\n\n This namespace object converts resolved objects into their appropriate form depending on their\n type. Consult the table below for conversion information.\n\n +-------------------------------------------+-------------------------------------------------------------------------------+\n | Option Type | Resolved Type |\n +===========================================+===============================================================================+\n | :attr:`.AppCommandOptionType.string` | :class:`str` |\n +-------------------------------------------+-------------------------------------------------------------------------------+\n | :attr:`.AppCommandOptionType.integer` | :class:`int` |\n +-------------------------------------------+-------------------------------------------------------------------------------+\n | :attr:`.AppCommandOptionType.boolean` | :class:`bool` |\n +-------------------------------------------+-------------------------------------------------------------------------------+\n | :attr:`.AppCommandOptionType.number` | :class:`float` |\n +-------------------------------------------+-------------------------------------------------------------------------------+\n | :attr:`.AppCommandOptionType.user` | :class:`~discord.User` or :class:`~discord.Member` |\n +-------------------------------------------+-------------------------------------------------------------------------------+\n | :attr:`.AppCommandOptionType.channel` | :class:`.AppCommandChannel` or :class:`.AppCommandThread` |\n +-------------------------------------------+-------------------------------------------------------------------------------+\n | :attr:`.AppCommandOptionType.role` | :class:`~discord.Role` |\n +-------------------------------------------+-------------------------------------------------------------------------------+\n | :attr:`.AppCommandOptionType.mentionable` | :class:`~discord.User` or :class:`~discord.Member`, or :class:`~discord.Role` |\n +-------------------------------------------+-------------------------------------------------------------------------------+\n | :attr:`.AppCommandOptionType.attachment` | :class:`~discord.Attachment` |\n +-------------------------------------------+-------------------------------------------------------------------------------+\n\n .. note::\n\n In autocomplete interactions, the namespace might not be validated or filled in. Discord does not\n send the resolved data as well, so this means that certain fields end up just as IDs rather than\n the resolved data. In these cases, a :class:`discord.Object` is returned instead.\n\n This is a Discord limitation.\n \"\"\"\n\n def __init__(\n self,\n interaction: Interaction,\n resolved: ResolvedData,\n options: List[ApplicationCommandInteractionDataOption],\n ):\n completed = self._get_resolved_items(interaction, resolved)\n for option in options:\n opt_type = option['type']\n name = option['name']\n focused = option.get('focused', False)\n if opt_type in (3, 4, 5): # string, integer, boolean\n value = option['value'] # type: ignore # Key is there\n self.__dict__[name] = value\n elif opt_type == 10: # number\n value = option['value'] # type: ignore # Key is there\n # This condition is written this way because 0 can be a valid float\n if value is None or value == '':\n self.__dict__[name] = float('nan')\n else:\n if not focused:\n self.__dict__[name] = float(value)\n else:\n # Autocomplete focused values tend to be garbage in\n self.__dict__[name] = value\n elif opt_type in (6, 7, 8, 9, 11):\n # Remaining ones should be snowflake based ones with resolved data\n snowflake: str = option['value'] # type: ignore # Key is there\n if opt_type == 9: # Mentionable\n # Mentionable is User | Role, these do not cause any conflict\n key = ResolveKey.any_with(snowflake)\n else:\n # The remaining keys can conflict, for example, a role and a channel\n # could end up with the same ID in very old guilds since they used to default\n # to sharing the guild ID. Old general channels no longer exist, but some old\n # servers will still have them so this needs to be handled.\n key = ResolveKey(id=snowflake, type=opt_type)\n\n value = completed.get(key) or Object(id=int(snowflake))\n self.__dict__[name] = value\n\n @classmethod\n def _get_resolved_items(cls, interaction: Interaction, resolved: ResolvedData) -> Dict[ResolveKey, Any]:\n completed: Dict[ResolveKey, Any] = {}\n state = interaction._state\n members = resolved.get('members', {})\n guild_id = interaction.guild_id\n guild = interaction.guild\n type = AppCommandOptionType.user.value\n for (user_id, user_data) in resolved.get('users', {}).items():\n try:\n member_data = members[user_id]\n except KeyError:\n completed[ResolveKey(id=user_id, type=type)] = state.create_user(user_data)\n else:\n member_data['user'] = user_data\n # Guild ID can't be None in this case.\n # There's a type mismatch here that I don't actually care about\n member = Member(state=state, guild=guild, data=member_data) # type: ignore\n completed[ResolveKey(id=user_id, type=type)] = member\n\n type = AppCommandOptionType.role.value\n completed.update(\n {\n # The guild ID can't be None in this case.\n ResolveKey(id=role_id, type=type): Role(guild=guild, state=state, data=role_data) # type: ignore\n for role_id, role_data in resolved.get('roles', {}).items()\n }\n )\n\n type = AppCommandOptionType.channel.value\n for (channel_id, channel_data) in resolved.get('channels', {}).items():\n key = ResolveKey(id=channel_id, type=type)\n if channel_data['type'] in (10, 11, 12):\n # The guild ID can't be none in this case\n completed[key] = AppCommandThread(state=state, data=channel_data, guild_id=guild_id) # type: ignore\n else:\n # The guild ID can't be none in this case\n completed[key] = AppCommandChannel(state=state, data=channel_data, guild_id=guild_id) # type: ignore\n\n type = AppCommandOptionType.attachment.value\n completed.update(\n {\n ResolveKey(id=attachment_id, type=type): Attachment(data=attachment_data, state=state)\n for attachment_id, attachment_data in resolved.get('attachments', {}).items()\n }\n )\n\n for (message_id, message_data) in resolved.get('messages', {}).items():\n channel_id = int(message_data['channel_id'])\n if guild is None:\n channel = PartialMessageable(state=state, guild_id=guild_id, id=channel_id)\n else:\n channel = guild.get_channel_or_thread(channel_id) or PartialMessageable(\n state=state, guild_id=guild_id, id=channel_id\n )\n\n # Type checker doesn't understand this due to failure to narrow\n message = Message(state=state, channel=channel, data=message_data) # type: ignore\n message.guild = guild\n key = ResolveKey(id=message_id, type=-1)\n completed[key] = message\n\n return completed\n\n def __repr__(self) -> str:\n items = (f'{k}={v!r}' for k, v in self.__dict__.items())\n return '<{} {}>'.format(self.__class__.__name__, ' '.join(items))\n\n def __eq__(self, other: object) -> bool:\n if isinstance(self, Namespace) and isinstance(other, Namespace):\n return self.__dict__ == other.__dict__\n return NotImplemented\n\n def __getitem__(self, key: str) -> Any:\n return self.__dict__[key]\n\n def __contains__(self, key: str) -> Any:\n return key in self.__dict__\n\n def __getattr__(self, attr: str) -> Any:\n return None\n\n def __iter__(self) -> Iterator[Tuple[str, Any]]:\n yield from self.__dict__.items()\n\n def _update_with_defaults(self, defaults: Iterable[Tuple[str, Any]]) -> None:\n for key, value in defaults:\n self.__dict__.setdefault(key, value)\n" }, { "path": "discord/app_commands/transformers.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\nimport inspect\n\nfrom dataclasses import dataclass\nfrom enum import Enum\nfrom typing import (\n TYPE_CHECKING,\n Any,\n Callable,\n ClassVar,\n Coroutine,\n Dict,\n List,\n Literal,\n Optional,\n Set,\n Tuple,\n Type,\n TypeVar,\n Union,\n)\n\nfrom .errors import AppCommandError, TransformerError\nfrom .models import AppCommandChannel, AppCommandThread, Choice\nfrom .translator import TranslationContextLocation, TranslationContext, Translator, locale_str\nfrom ..channel import StageChannel, VoiceChannel, TextChannel, CategoryChannel, ForumChannel\nfrom ..abc import GuildChannel\nfrom ..threads import Thread\nfrom ..enums import Enum as InternalEnum, AppCommandOptionType, ChannelType, Locale\nfrom ..utils import MISSING, maybe_coroutine\nfrom ..user import User\nfrom ..role import Role\nfrom ..member import Member\nfrom ..message import Attachment\n\n__all__ = (\n 'Transformer',\n 'Transform',\n 'Range',\n)\n\nT = TypeVar('T')\nFuncT = TypeVar('FuncT', bound=Callable[..., Any])\nChoiceT = TypeVar('ChoiceT', str, int, float, Union[str, int, float])\nNoneType = type(None)\n\nif TYPE_CHECKING:\n from ..interactions import Interaction\n from .commands import Parameter\n\n\n@dataclass\nclass CommandParameter:\n # The name of the parameter is *always* the parameter name in the code\n # Therefore, it can't be Union[str, locale_str]\n name: str = MISSING\n description: Union[str, locale_str] = MISSING\n required: bool = MISSING\n default: Any = MISSING\n choices: List[Choice[Union[str, int, float]]] = MISSING\n type: AppCommandOptionType = MISSING\n channel_types: List[ChannelType] = MISSING\n min_value: Optional[Union[int, float]] = None\n max_value: Optional[Union[int, float]] = None\n autocomplete: Optional[Callable[..., Coroutine[Any, Any, Any]]] = None\n _rename: Union[str, locale_str] = MISSING\n _annotation: Any = MISSING\n\n async def get_translated_payload(self, translator: Translator, data: Parameter) -> Dict[str, Any]:\n base = self.to_dict()\n\n rename = self._rename\n description = self.description\n needs_name_translations = isinstance(rename, locale_str)\n needs_description_translations = isinstance(description, locale_str)\n name_localizations: Dict[str, str] = {}\n description_localizations: Dict[str, str] = {}\n\n # Prevent creating these objects in a heavy loop\n name_context = TranslationContext(location=TranslationContextLocation.parameter_name, data=data)\n description_context = TranslationContext(location=TranslationContextLocation.parameter_description, data=data)\n for locale in Locale:\n if needs_name_translations:\n translation = await translator._checked_translate(rename, locale, name_context)\n if translation is not None:\n name_localizations[locale.value] = translation\n\n if needs_description_translations:\n translation = await translator._checked_translate(description, locale, description_context)\n if translation is not None:\n description_localizations[locale.value] = translation\n\n if self.choices:\n base['choices'] = [await choice.get_translated_payload(translator) for choice in self.choices]\n\n if name_localizations:\n base['name_localizations'] = name_localizations\n\n if description_localizations:\n base['description_localizations'] = description_localizations\n\n return base\n\n def to_dict(self) -> Dict[str, Any]:\n base = {\n 'type': self.type.value,\n 'name': self.display_name,\n 'description': str(self.description),\n 'required': self.required,\n }\n\n if self.choices:\n base['choices'] = [choice.to_dict() for choice in self.choices]\n if self.channel_types:\n base['channel_types'] = [t.value for t in self.channel_types]\n if self.autocomplete:\n base['autocomplete'] = True\n\n min_key, max_key = (\n ('min_value', 'max_value') if self.type is not AppCommandOptionType.string else ('min_length', 'max_length')\n )\n if self.min_value is not None:\n base[min_key] = self.min_value\n if self.max_value is not None:\n base[max_key] = self.max_value\n\n return base\n\n def _convert_to_locale_strings(self) -> None:\n if self._rename is MISSING:\n self._rename = locale_str(self.name)\n elif isinstance(self._rename, str):\n self._rename = locale_str(self._rename)\n\n if isinstance(self.description, str):\n self.description = locale_str(self.description)\n\n if self.choices:\n for choice in self.choices:\n if choice._locale_name is None:\n choice._locale_name = locale_str(choice.name)\n\n def is_choice_annotation(self) -> bool:\n return getattr(self._annotation, '__discord_app_commands_is_choice__', False)\n\n async def transform(self, interaction: Interaction, value: Any, /) -> Any:\n if hasattr(self._annotation, '__discord_app_commands_transformer__'):\n # This one needs special handling for type safety reasons\n if self._annotation.__discord_app_commands_is_choice__:\n choice = next((c for c in self.choices if c.value == value), None)\n if choice is None:\n raise TransformerError(value, self.type, self._annotation)\n return choice\n\n try:\n return await maybe_coroutine(self._annotation.transform, interaction, value)\n except AppCommandError:\n raise\n except Exception as e:\n raise TransformerError(value, self.type, self._annotation) from e\n\n return value\n\n @property\n def display_name(self) -> str:\n \"\"\":class:`str`: The name of the parameter as it should be displayed to the user.\"\"\"\n return self.name if self._rename is MISSING else str(self._rename)\n\n\nclass Transformer:\n \"\"\"The base class that allows a type annotation in an application command parameter\n to map into a :class:`~discord.AppCommandOptionType` and transform the raw value into one\n from this type.\n\n This class is customisable through the overriding of methods and properties in the class\n and by using it as the second type parameter of the :class:`~discord.app_commands.Transform`\n class. For example, to convert a string into a custom pair type:\n\n .. code-block:: python3\n\n class Point(typing.NamedTuple):\n x: int\n y: int\n\n class PointTransformer(app_commands.Transformer):\n async def transform(self, interaction: discord.Interaction, value: str) -> Point:\n (x, _, y) = value.partition(',')\n return Point(x=int(x.strip()), y=int(y.strip()))\n\n @app_commands.command()\n async def graph(\n interaction: discord.Interaction,\n point: app_commands.Transform[Point, PointTransformer],\n ):\n await interaction.response.send_message(str(point))\n\n If a class is passed instead of an instance to the second type parameter, then it is\n constructed with no arguments passed to the ``__init__`` method.\n\n .. versionadded:: 2.0\n \"\"\"\n\n __discord_app_commands_transformer__: ClassVar[bool] = True\n __discord_app_commands_is_choice__: ClassVar[bool] = False\n\n # This is needed to pass typing's type checks.\n # e.g. Optional[MyTransformer]\n def __call__(self) -> None:\n pass\n\n def __or__(self, rhs: Any) -> Any:\n return Union[self, rhs] # type: ignore\n\n @property\n def type(self) -> AppCommandOptionType:\n \"\"\":class:`~discord.AppCommandOptionType`: The option type associated with this transformer.\n\n This must be a :obj:`property`.\n\n Defaults to :attr:`~discord.AppCommandOptionType.string`.\n \"\"\"\n return AppCommandOptionType.string\n\n @property\n def channel_types(self) -> List[ChannelType]:\n \"\"\"List[:class:`~discord.ChannelType`]: A list of channel types that are allowed to this parameter.\n\n Only valid if the :meth:`type` returns :attr:`~discord.AppCommandOptionType.channel`.\n\n This must be a :obj:`property`.\n\n Defaults to an empty list.\n \"\"\"\n return []\n\n @property\n def min_value(self) -> Optional[Union[int, float]]:\n \"\"\"Optional[:class:`int`]: The minimum supported value for this parameter.\n\n Only valid if the :meth:`type` returns :attr:`~discord.AppCommandOptionType.number`\n :attr:`~discord.AppCommandOptionType.integer`, or :attr:`~discord.AppCommandOptionType.string`.\n\n This must be a :obj:`property`.\n\n Defaults to ``None``.\n \"\"\"\n return None\n\n @property\n def max_value(self) -> Optional[Union[int, float]]:\n \"\"\"Optional[:class:`int`]: The maximum supported value for this parameter.\n\n Only valid if the :meth:`type` returns :attr:`~discord.AppCommandOptionType.number`\n :attr:`~discord.AppCommandOptionType.integer`, or :attr:`~discord.AppCommandOptionType.string`.\n\n This must be a :obj:`property`.\n\n Defaults to ``None``.\n \"\"\"\n return None\n\n @property\n def choices(self) -> Optional[List[Choice[Union[int, float, str]]]]:\n \"\"\"Optional[List[:class:`~discord.app_commands.Choice`]]: A list of up to 25 choices that are allowed to this parameter.\n\n Only valid if the :meth:`type` returns :attr:`~discord.AppCommandOptionType.number`\n :attr:`~discord.AppCommandOptionType.integer`, or :attr:`~discord.AppCommandOptionType.string`.\n\n This must be a :obj:`property`.\n\n Defaults to ``None``.\n \"\"\"\n return None\n\n @property\n def _error_display_name(self) -> str:\n name = self.__class__.__name__\n if name.endswith('Transformer'):\n return name[:-11]\n else:\n return name\n\n async def transform(self, interaction: Interaction, value: Any, /) -> Any:\n \"\"\"|maybecoro|\n\n Transforms the converted option value into another value.\n\n The value passed into this transform function is the same as the\n one in the :class:`conversion table `.\n\n Parameters\n -----------\n interaction: :class:`~discord.Interaction`\n The interaction being handled.\n value: Any\n The value of the given argument after being resolved.\n See the :class:`conversion table `\n for how certain option types correspond to certain values.\n \"\"\"\n raise NotImplementedError('Derived classes need to implement this.')\n\n async def autocomplete(\n self, interaction: Interaction, value: Union[int, float, str], /\n ) -> List[Choice[Union[int, float, str]]]:\n \"\"\"|coro|\n\n An autocomplete prompt handler to be automatically used by options using this transformer.\n\n .. note::\n\n Autocomplete is only supported for options with a :meth:`~discord.app_commands.Transformer.type`\n of :attr:`~discord.AppCommandOptionType.string`, :attr:`~discord.AppCommandOptionType.integer`,\n or :attr:`~discord.AppCommandOptionType.number`.\n\n Parameters\n -----------\n interaction: :class:`~discord.Interaction`\n The autocomplete interaction being handled.\n value: Union[:class:`str`, :class:`int`, :class:`float`]\n The current value entered by the user.\n\n Returns\n --------\n List[:class:`~discord.app_commands.Choice`]\n A list of choices to be displayed to the user, a maximum of 25.\n\n \"\"\"\n raise NotImplementedError('Derived classes can implement this.')\n\n\nclass IdentityTransformer(Transformer):\n def __init__(self, type: AppCommandOptionType) -> None:\n self._type = type\n\n @property\n def type(self) -> AppCommandOptionType:\n return self._type\n\n async def transform(self, interaction: Interaction, value: Any, /) -> Any:\n return value\n\n\nclass RangeTransformer(IdentityTransformer):\n def __init__(\n self,\n opt_type: AppCommandOptionType,\n *,\n min: Optional[Union[int, float]] = None,\n max: Optional[Union[int, float]] = None,\n ) -> None:\n if min and max and min > max:\n raise TypeError('minimum cannot be larger than maximum')\n\n self._min: Optional[Union[int, float]] = min\n self._max: Optional[Union[int, float]] = max\n super().__init__(opt_type)\n\n @property\n def min_value(self) -> Optional[Union[int, float]]:\n return self._min\n\n @property\n def max_value(self) -> Optional[Union[int, float]]:\n return self._max\n\n\nclass LiteralTransformer(IdentityTransformer):\n def __init__(self, values: Tuple[Any, ...]) -> None:\n first = type(values[0])\n if first is int:\n opt_type = AppCommandOptionType.integer\n elif first is float:\n opt_type = AppCommandOptionType.number\n elif first is str:\n opt_type = AppCommandOptionType.string\n else:\n raise TypeError(f'expected int, str, or float values not {first!r}')\n\n self._choices = [Choice(name=str(v), value=v) for v in values]\n super().__init__(opt_type)\n\n @property\n def choices(self):\n return self._choices\n\n\nclass ChoiceTransformer(IdentityTransformer):\n __discord_app_commands_is_choice__: ClassVar[bool] = True\n\n def __init__(self, inner_type: Any) -> None:\n if inner_type is int:\n opt_type = AppCommandOptionType.integer\n elif inner_type is float:\n opt_type = AppCommandOptionType.number\n elif inner_type is str:\n opt_type = AppCommandOptionType.string\n else:\n raise TypeError(f'expected int, str, or float values not {inner_type!r}')\n\n super().__init__(opt_type)\n\n\nclass EnumValueTransformer(Transformer):\n def __init__(self, enum: Any) -> None:\n super().__init__()\n\n values = list(enum)\n if len(values) < 2:\n raise TypeError('enum.Enum requires at least two values.')\n\n first = type(values[0].value)\n if first is int:\n opt_type = AppCommandOptionType.integer\n elif first is float:\n opt_type = AppCommandOptionType.number\n elif first is str:\n opt_type = AppCommandOptionType.string\n else:\n raise TypeError(f'expected int, str, or float values not {first!r}')\n\n self._type: AppCommandOptionType = opt_type\n self._enum: Any = enum\n self._choices = [Choice(name=v.name, value=v.value) for v in values]\n\n @property\n def _error_display_name(self) -> str:\n return self._enum.__name__\n\n @property\n def type(self) -> AppCommandOptionType:\n return self._type\n\n @property\n def choices(self):\n return self._choices\n\n async def transform(self, interaction: Interaction, value: Any, /) -> Any:\n return self._enum(value)\n\n\nclass EnumNameTransformer(Transformer):\n def __init__(self, enum: Any) -> None:\n super().__init__()\n\n values = list(enum)\n if len(values) < 2:\n raise TypeError('enum.Enum requires at least two values.')\n\n self._enum: Any = enum\n self._choices = [Choice(name=v.name, value=v.name) for v in values]\n\n @property\n def _error_display_name(self) -> str:\n return self._enum.__name__\n\n @property\n def type(self) -> AppCommandOptionType:\n return AppCommandOptionType.string\n\n @property\n def choices(self):\n return self._choices\n\n async def transform(self, interaction: Interaction, value: Any, /) -> Any:\n return self._enum[value]\n\n\nclass InlineTransformer(Transformer):\n def __init__(self, annotation: Any) -> None:\n super().__init__()\n self.annotation: Any = annotation\n\n @property\n def _error_display_name(self) -> str:\n return self.annotation.__name__\n\n @property\n def type(self) -> AppCommandOptionType:\n return AppCommandOptionType.string\n\n async def transform(self, interaction: Interaction, value: Any, /) -> Any:\n return await self.annotation.transform(interaction, value)\n\n\nif TYPE_CHECKING:\n from typing_extensions import Annotated as Transform\n from typing_extensions import Annotated as Range\nelse:\n\n class Transform:\n \"\"\"A type annotation that can be applied to a parameter to customise the behaviour of\n an option type by transforming with the given :class:`Transformer`. This requires\n the usage of two generic parameters, the first one is the type you're converting to and the second\n one is the type of the :class:`Transformer` actually doing the transformation.\n\n During type checking time this is equivalent to :obj:`typing.Annotated` so type checkers understand\n the intent of the code.\n\n For example usage, check :class:`Transformer`.\n\n .. versionadded:: 2.0\n \"\"\"\n\n def __class_getitem__(cls, items) -> Transformer:\n if not isinstance(items, tuple):\n raise TypeError(f'expected tuple for arguments, received {items.__class__.__name__} instead')\n\n if len(items) != 2:\n raise TypeError('Transform only accepts exactly two arguments')\n\n _, transformer = items\n\n if inspect.isclass(transformer):\n if not issubclass(transformer, Transformer):\n raise TypeError(f'second argument of Transform must be a Transformer class not {transformer!r}')\n transformer = transformer()\n elif not isinstance(transformer, Transformer):\n raise TypeError(f'second argument of Transform must be a Transformer not {transformer.__class__.__name__}')\n\n return transformer\n\n class Range:\n \"\"\"A type annotation that can be applied to a parameter to require a numeric or string\n type to fit within the range provided.\n\n During type checking time this is equivalent to :obj:`typing.Annotated` so type checkers understand\n the intent of the code.\n\n Some example ranges:\n\n - ``Range[int, 10]`` means the minimum is 10 with no maximum.\n - ``Range[int, None, 10]`` means the maximum is 10 with no minimum.\n - ``Range[int, 1, 10]`` means the minimum is 1 and the maximum is 10.\n - ``Range[float, 1.0, 5.0]`` means the minimum is 1.0 and the maximum is 5.0.\n - ``Range[str, 1, 10]`` means the minimum length is 1 and the maximum length is 10.\n\n .. versionadded:: 2.0\n\n Examples\n ----------\n\n .. code-block:: python3\n\n @app_commands.command()\n async def range(interaction: discord.Interaction, value: app_commands.Range[int, 10, 12]):\n await interaction.response.send_message(f'Your value is {value}', ephemeral=True)\n \"\"\"\n\n def __class_getitem__(cls, obj) -> RangeTransformer:\n if not isinstance(obj, tuple):\n raise TypeError(f'expected tuple for arguments, received {obj.__class__.__name__} instead')\n\n if len(obj) == 2:\n obj = (*obj, None)\n elif len(obj) != 3:\n raise TypeError('Range accepts either two or three arguments with the first being the type of range.')\n\n obj_type, min, max = obj\n\n if min is None and max is None:\n raise TypeError('Range must not be empty')\n\n if min is not None and max is not None:\n # At this point max and min are both not none\n if type(min) != type(max):\n raise TypeError('Both min and max in Range must be the same type')\n\n if obj_type is int:\n opt_type = AppCommandOptionType.integer\n elif obj_type is float:\n opt_type = AppCommandOptionType.number\n elif obj_type is str:\n opt_type = AppCommandOptionType.string\n else:\n raise TypeError(f'expected int, float, or str as range type, received {obj_type!r} instead')\n\n if obj_type in (str, int):\n cast = int\n else:\n cast = float\n\n transformer = RangeTransformer(\n opt_type,\n min=cast(min) if min is not None else None,\n max=cast(max) if max is not None else None,\n )\n return transformer\n\n\nclass MemberTransformer(Transformer):\n @property\n def type(self) -> AppCommandOptionType:\n return AppCommandOptionType.user\n\n async def transform(self, interaction: Interaction, value: Any, /) -> Member:\n if not isinstance(value, Member):\n raise TransformerError(value, self.type, self)\n return value\n\n\nclass BaseChannelTransformer(Transformer):\n def __init__(self, *channel_types: Type[Any]) -> None:\n super().__init__()\n if len(channel_types) == 1:\n display_name = channel_types[0].__name__\n types = CHANNEL_TO_TYPES[channel_types[0]]\n else:\n display_name = '{}, and {}'.format(', '.join(t.__name__ for t in channel_types[:-1]), channel_types[-1].__name__)\n types = []\n\n for t in channel_types:\n try:\n types.extend(CHANNEL_TO_TYPES[t])\n except KeyError:\n raise TypeError('Union type of channels must be entirely made up of channels') from None\n\n self._types: Tuple[Type[Any], ...] = channel_types\n self._channel_types: List[ChannelType] = types\n self._display_name = display_name\n\n @property\n def _error_display_name(self) -> str:\n return self._display_name\n\n @property\n def type(self) -> AppCommandOptionType:\n return AppCommandOptionType.channel\n\n @property\n def channel_types(self) -> List[ChannelType]:\n return self._channel_types\n\n async def transform(self, interaction: Interaction, value: Any, /):\n resolved = value.resolve()\n if resolved is None or not isinstance(resolved, self._types):\n raise TransformerError(value, AppCommandOptionType.channel, self)\n return resolved\n\n\nclass RawChannelTransformer(BaseChannelTransformer):\n async def transform(self, interaction: Interaction, value: Any, /):\n if not isinstance(value, self._types):\n raise TransformerError(value, AppCommandOptionType.channel, self)\n return value\n\n\nclass UnionChannelTransformer(BaseChannelTransformer):\n async def transform(self, interaction: Interaction, value: Any, /):\n if isinstance(value, self._types):\n return value\n\n resolved = value.resolve()\n if resolved is None or not isinstance(resolved, self._types):\n raise TransformerError(value, AppCommandOptionType.channel, self)\n return resolved\n\n\nCHANNEL_TO_TYPES: Dict[Any, List[ChannelType]] = {\n AppCommandChannel: [\n ChannelType.stage_voice,\n ChannelType.voice,\n ChannelType.text,\n ChannelType.news,\n ChannelType.category,\n ChannelType.forum,\n ],\n GuildChannel: [\n ChannelType.stage_voice,\n ChannelType.voice,\n ChannelType.text,\n ChannelType.news,\n ChannelType.category,\n ChannelType.forum,\n ],\n AppCommandThread: [ChannelType.news_thread, ChannelType.private_thread, ChannelType.public_thread],\n Thread: [ChannelType.news_thread, ChannelType.private_thread, ChannelType.public_thread],\n StageChannel: [ChannelType.stage_voice],\n VoiceChannel: [ChannelType.voice],\n TextChannel: [ChannelType.text, ChannelType.news],\n CategoryChannel: [ChannelType.category],\n ForumChannel: [ChannelType.forum],\n}\n\nBUILT_IN_TRANSFORMERS: Dict[Any, Transformer] = {\n str: IdentityTransformer(AppCommandOptionType.string),\n int: IdentityTransformer(AppCommandOptionType.integer),\n float: IdentityTransformer(AppCommandOptionType.number),\n bool: IdentityTransformer(AppCommandOptionType.boolean),\n User: IdentityTransformer(AppCommandOptionType.user),\n Member: MemberTransformer(),\n Role: IdentityTransformer(AppCommandOptionType.role),\n AppCommandChannel: RawChannelTransformer(AppCommandChannel),\n AppCommandThread: RawChannelTransformer(AppCommandThread),\n GuildChannel: BaseChannelTransformer(GuildChannel),\n Thread: BaseChannelTransformer(Thread),\n StageChannel: BaseChannelTransformer(StageChannel),\n VoiceChannel: BaseChannelTransformer(VoiceChannel),\n TextChannel: BaseChannelTransformer(TextChannel),\n CategoryChannel: BaseChannelTransformer(CategoryChannel),\n ForumChannel: BaseChannelTransformer(ForumChannel),\n Attachment: IdentityTransformer(AppCommandOptionType.attachment),\n}\n\nALLOWED_DEFAULTS: Dict[AppCommandOptionType, Tuple[Type[Any], ...]] = {\n AppCommandOptionType.string: (str, NoneType),\n AppCommandOptionType.integer: (int, NoneType),\n AppCommandOptionType.boolean: (bool, NoneType),\n AppCommandOptionType.number: (float, NoneType),\n}\n\n\ndef get_supported_annotation(\n annotation: Any,\n *,\n _none: type = NoneType,\n _mapping: Dict[Any, Transformer] = BUILT_IN_TRANSFORMERS,\n) -> Tuple[Any, Any, bool]:\n \"\"\"Returns an appropriate, yet supported, annotation along with an optional default value.\n\n The third boolean element of the tuple indicates if default values should be validated.\n\n This differs from the built in mapping by supporting a few more things.\n Likewise, this returns a \"transformed\" annotation that is ready to use with CommandParameter.transform.\n \"\"\"\n\n try:\n return (_mapping[annotation], MISSING, True)\n except (KeyError, TypeError):\n pass\n\n if isinstance(annotation, Transformer):\n return (annotation, MISSING, False)\n\n if inspect.isclass(annotation):\n if issubclass(annotation, Transformer):\n return (annotation(), MISSING, False)\n if issubclass(annotation, (Enum, InternalEnum)):\n if all(isinstance(v.value, (str, int, float)) for v in annotation):\n return (EnumValueTransformer(annotation), MISSING, False)\n else:\n return (EnumNameTransformer(annotation), MISSING, False)\n if annotation is Choice:\n raise TypeError('Choice requires a type argument of int, str, or float')\n\n # Check if a transform @classmethod is given to the class\n # These flatten into simple \"inline\" transformers with implicit strings\n transform_classmethod = annotation.__dict__.get('transform', None)\n if isinstance(transform_classmethod, classmethod):\n params = inspect.signature(transform_classmethod.__func__).parameters\n if len(params) != 3:\n raise TypeError('Inline transformer with transform classmethod requires 3 parameters')\n if not inspect.iscoroutinefunction(transform_classmethod.__func__):\n raise TypeError('Inline transformer with transform classmethod must be a coroutine')\n return (InlineTransformer(annotation), MISSING, False)\n\n # Check if there's an origin\n origin = getattr(annotation, '__origin__', None)\n if origin is Literal:\n args = annotation.__args__\n return (LiteralTransformer(args), MISSING, True)\n\n if origin is Choice:\n arg = annotation.__args__[0]\n return (ChoiceTransformer(arg), MISSING, True)\n\n if origin is not Union:\n # Only Union/Optional is supported right now so bail early\n raise TypeError(f'unsupported type annotation {annotation!r}')\n\n default = MISSING\n args = annotation.__args__\n if args[-1] is _none:\n if len(args) == 2:\n underlying = args[0]\n inner, _, validate_default = get_supported_annotation(underlying)\n if inner is None:\n raise TypeError(f'unsupported inner optional type {underlying!r}')\n return (inner, None, validate_default)\n else:\n args = args[:-1]\n default = None\n\n # Check for channel union types\n if any(arg in CHANNEL_TO_TYPES for arg in args):\n # If any channel type is given, then *all* must be channel types\n return (UnionChannelTransformer(*args), default, True)\n\n # The only valid transformations here are:\n # [Member, User] => user\n # [Member, User, Role] => mentionable\n # [Member | User, Role] => mentionable\n supported_types: Set[Any] = {Role, Member, User}\n if not all(arg in supported_types for arg in args):\n raise TypeError(f'unsupported types given inside {annotation!r}')\n if args == (User, Member) or args == (Member, User):\n return (IdentityTransformer(AppCommandOptionType.user), default, True)\n\n return (IdentityTransformer(AppCommandOptionType.mentionable), default, True)\n\n\ndef annotation_to_parameter(annotation: Any, parameter: inspect.Parameter) -> CommandParameter:\n \"\"\"Returns the appropriate :class:`CommandParameter` for the given annotation.\n\n The resulting ``_annotation`` attribute might not match the one given here and might\n be transformed in order to be easier to call from the ``transform`` asynchronous function\n of a command parameter.\n \"\"\"\n\n (inner, default, validate_default) = get_supported_annotation(annotation)\n type = inner.type\n\n if default is MISSING or default is None:\n param_default = parameter.default\n if param_default is not parameter.empty:\n default = param_default\n\n # Verify validity of the default parameter\n if default is not MISSING and validate_default:\n valid_types: Tuple[Any, ...] = ALLOWED_DEFAULTS.get(type, (NoneType,))\n if not isinstance(default, valid_types):\n raise TypeError(f'invalid default parameter type given ({default.__class__}), expected {valid_types}')\n\n result = CommandParameter(\n type=type,\n _annotation=inner,\n default=default,\n required=default is MISSING,\n name=parameter.name,\n )\n\n choices = inner.choices\n if choices is not None:\n result.choices = choices\n\n # These methods should be duck typed\n if type in (AppCommandOptionType.number, AppCommandOptionType.string, AppCommandOptionType.integer):\n result.min_value = inner.min_value\n result.max_value = inner.max_value\n\n if type is AppCommandOptionType.channel:\n result.channel_types = inner.channel_types\n\n if parameter.kind in (parameter.POSITIONAL_ONLY, parameter.VAR_KEYWORD, parameter.VAR_POSITIONAL):\n raise TypeError(f'unsupported parameter kind in callback: {parameter.kind!s}')\n\n # Check if the method is overridden\n if inner.autocomplete.__func__ is not Transformer.autocomplete:\n from .commands import validate_auto_complete_callback\n\n result.autocomplete = validate_auto_complete_callback(inner.autocomplete)\n\n return result\n" }, { "path": "discord/app_commands/translator.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import TYPE_CHECKING, Any, Generic, Literal, Optional, TypeVar, Union, overload\nfrom .errors import TranslationError\nfrom ..enums import Enum, Locale\n\n\nif TYPE_CHECKING:\n from .commands import Command, ContextMenu, Group, Parameter\n from .models import Choice\n\n\n__all__ = (\n 'TranslationContextLocation',\n 'TranslationContextTypes',\n 'TranslationContext',\n 'Translator',\n 'locale_str',\n)\n\n\nclass TranslationContextLocation(Enum):\n command_name = 0\n command_description = 1\n group_name = 2\n group_description = 3\n parameter_name = 4\n parameter_description = 5\n choice_name = 6\n other = 7\n\n\n_L = TypeVar('_L', bound=TranslationContextLocation)\n_D = TypeVar('_D')\n\n\nclass TranslationContext(Generic[_L, _D]):\n \"\"\"A class that provides context for the :class:`locale_str` being translated.\n\n This is useful to determine where exactly the string is located and aid in looking\n up the actual translation.\n\n Attributes\n -----------\n location: :class:`TranslationContextLocation`\n The location where this string is located.\n data: Any\n The extraneous data that is being translated.\n \"\"\"\n\n __slots__ = ('location', 'data')\n\n @overload\n def __init__(\n self, location: Literal[TranslationContextLocation.command_name], data: Union[Command[Any, ..., Any], ContextMenu]\n ) -> None:\n ...\n\n @overload\n def __init__(\n self, location: Literal[TranslationContextLocation.command_description], data: Command[Any, ..., Any]\n ) -> None:\n ...\n\n @overload\n def __init__(\n self,\n location: Literal[TranslationContextLocation.group_name, TranslationContextLocation.group_description],\n data: Group,\n ) -> None:\n ...\n\n @overload\n def __init__(\n self,\n location: Literal[TranslationContextLocation.parameter_name, TranslationContextLocation.parameter_description],\n data: Parameter,\n ) -> None:\n ...\n\n @overload\n def __init__(self, location: Literal[TranslationContextLocation.choice_name], data: Choice[Any]) -> None:\n ...\n\n @overload\n def __init__(self, location: Literal[TranslationContextLocation.other], data: Any) -> None:\n ...\n\n def __init__(self, location: _L, data: _D) -> None: # type: ignore # pyright doesn't like the overloads\n self.location: _L = location\n self.data: _D = data\n\n\n# For type checking purposes, it makes sense to allow the user to leverage type narrowing\n# So code like this works as expected:\n#\n# if context.type == TranslationContextLocation.command_name:\n# reveal_type(context.data) # Revealed type is Command | ContextMenu\n#\n# This requires a union of types\nCommandNameTranslationContext = TranslationContext[\n Literal[TranslationContextLocation.command_name], Union['Command[Any, ..., Any]', 'ContextMenu']\n]\nCommandDescriptionTranslationContext = TranslationContext[\n Literal[TranslationContextLocation.command_description], 'Command[Any, ..., Any]'\n]\nGroupTranslationContext = TranslationContext[\n Literal[TranslationContextLocation.group_name, TranslationContextLocation.group_description], 'Group'\n]\nParameterTranslationContext = TranslationContext[\n Literal[TranslationContextLocation.parameter_name, TranslationContextLocation.parameter_description], 'Parameter'\n]\nChoiceTranslationContext = TranslationContext[Literal[TranslationContextLocation.choice_name], 'Choice[Any]']\nOtherTranslationContext = TranslationContext[Literal[TranslationContextLocation.other], Any]\n\nTranslationContextTypes = Union[\n CommandNameTranslationContext,\n CommandDescriptionTranslationContext,\n GroupTranslationContext,\n ParameterTranslationContext,\n ChoiceTranslationContext,\n OtherTranslationContext,\n]\n\n\nclass Translator:\n \"\"\"A class that handles translations for commands, parameters, and choices.\n\n Translations are done lazily in order to allow for async enabled translations as well\n as supporting a wide array of translation systems such as :mod:`gettext` and\n `Project Fluent `_.\n\n In order for a translator to be used, it must be set using the :meth:`CommandTree.set_translator`\n method. The translation flow for a string is as follows:\n\n 1. Use :class:`locale_str` instead of :class:`str` in areas of a command you want to be translated.\n - Currently, these are command names, command descriptions, parameter names, parameter descriptions, and choice names.\n - This can also be used inside the :func:`~discord.app_commands.describe` decorator.\n 2. Call :meth:`CommandTree.set_translator` to the translator instance that will handle the translations.\n 3. Call :meth:`CommandTree.sync`\n 4. The library will call :meth:`Translator.translate` on all the relevant strings being translated.\n\n .. versionadded:: 2.0\n \"\"\"\n\n async def load(self) -> None:\n \"\"\"|coro|\n\n An asynchronous setup function for loading the translation system.\n\n The default implementation does nothing.\n\n This is invoked when :meth:`CommandTree.set_translator` is called.\n \"\"\"\n pass\n\n async def unload(self) -> None:\n \"\"\"|coro|\n\n An asynchronous teardown function for unloading the translation system.\n\n The default implementation does nothing.\n\n This is invoked when :meth:`CommandTree.set_translator` is called\n if a tree already has a translator or when :meth:`discord.Client.close` is called.\n \"\"\"\n pass\n\n async def _checked_translate(\n self, string: locale_str, locale: Locale, context: TranslationContextTypes\n ) -> Optional[str]:\n try:\n return await self.translate(string, locale, context)\n except TranslationError:\n raise\n except Exception as e:\n raise TranslationError(string=string, locale=locale, context=context) from e\n\n async def translate(self, string: locale_str, locale: Locale, context: TranslationContextTypes) -> Optional[str]:\n \"\"\"|coro|\n\n Translates the given string to the specified locale.\n\n If the string cannot be translated, ``None`` should be returned.\n\n The default implementation returns ``None``.\n\n If an exception is raised in this method, it should inherit from :exc:`TranslationError`.\n If it doesn't, then when this is called the exception will be chained with it instead.\n\n Parameters\n ------------\n string: :class:`locale_str`\n The string being translated.\n locale: :class:`~discord.Locale`\n The locale being requested for translation.\n context: :class:`TranslationContext`\n The translation context where the string originated from.\n For better type checking ergonomics, the ``TranslationContextTypes``\n type can be used instead to aid with type narrowing. It is functionally\n equivalent to :class:`TranslationContext`.\n \"\"\"\n\n return None\n\n\nclass locale_str:\n \"\"\"Marks a string as ready for translation.\n\n This is done lazily and is not actually translated until :meth:`CommandTree.sync` is called.\n\n The sync method then ultimately defers the responsibility of translating to the :class:`Translator`\n instance used by the :class:`CommandTree`. For more information on the translation flow, see the\n :class:`Translator` documentation.\n\n .. container:: operations\n\n .. describe:: str(x)\n\n Returns the message passed to the string.\n\n .. describe:: x == y\n\n Checks if the string is equal to another string.\n\n .. describe:: x != y\n\n Checks if the string is not equal to another string.\n\n .. describe:: hash(x)\n\n Returns the hash of the string.\n\n .. versionadded:: 2.0\n\n Attributes\n ------------\n message: :class:`str`\n The message being translated. Once set, this cannot be changed.\n\n .. warning::\n\n This must be the default \"message\" that you send to Discord.\n Discord sends this message back to the library and the library\n uses it to access the data in order to dispatch commands.\n\n For example, in a command name context, if the command\n name is ``foo`` then the message *must* also be ``foo``.\n For other translation systems that require a message ID such\n as Fluent, consider using a keyword argument to pass it in.\n extras: :class:`dict`\n A dict of user provided extras to attach to the translated string.\n This can be used to add more context, information, or any metadata necessary\n to aid in actually translating the string.\n\n Since these are passed via keyword arguments, the keys are strings.\n \"\"\"\n\n __slots__ = ('__message', 'extras')\n\n def __init__(self, message: str, /, **kwargs: Any) -> None:\n self.__message: str = message\n self.extras: dict[str, Any] = kwargs\n\n @property\n def message(self) -> str:\n return self.__message\n\n def __str__(self) -> str:\n return self.__message\n\n def __repr__(self) -> str:\n kwargs = ', '.join(f'{k}={v!r}' for k, v in self.extras.items())\n if kwargs:\n return f'{self.__class__.__name__}({self.__message!r}, {kwargs})'\n return f'{self.__class__.__name__}({self.__message!r})'\n\n def __eq__(self, obj: object) -> bool:\n return isinstance(obj, locale_str) and self.message == obj.message\n\n def __hash__(self) -> int:\n return hash(self.__message)\n" }, { "path": "discord/app_commands/tree.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\nimport logging\nimport inspect\n\nfrom typing import (\n Any,\n TYPE_CHECKING,\n Callable,\n Coroutine,\n Dict,\n Generator,\n Generic,\n List,\n Literal,\n Optional,\n Sequence,\n Set,\n Tuple,\n Union,\n overload,\n)\nfrom collections import Counter\n\n\nfrom .namespace import Namespace, ResolveKey\nfrom .models import AppCommand\nfrom .commands import Command, ContextMenu, Group\nfrom .errors import (\n AppCommandError,\n CommandAlreadyRegistered,\n CommandNotFound,\n CommandSignatureMismatch,\n CommandLimitReached,\n CommandSyncFailure,\n MissingApplicationID,\n)\nfrom .installs import AppCommandContext, AppInstallationType\nfrom .translator import Translator, locale_str\nfrom ..errors import ClientException, HTTPException\nfrom ..enums import AppCommandType, InteractionType\nfrom ..utils import MISSING, _get_as_snowflake, _is_submodule, _shorten\nfrom .._types import ClientT\n\n\nif TYPE_CHECKING:\n from ..types.interactions import ApplicationCommandInteractionData, ApplicationCommandInteractionDataOption\n from ..interactions import Interaction\n from ..abc import Snowflake\n from .commands import ContextMenuCallback, CommandCallback, P, T\n\n ErrorFunc = Callable[\n [Interaction, AppCommandError],\n Coroutine[Any, Any, Any],\n ]\n\n__all__ = ('CommandTree',)\n\n_log = logging.getLogger(__name__)\n\n\ndef _retrieve_guild_ids(\n command: Any, guild: Optional[Snowflake] = MISSING, guilds: Sequence[Snowflake] = MISSING\n) -> Optional[Set[int]]:\n if guild is not MISSING and guilds is not MISSING:\n raise TypeError('cannot mix guild and guilds keyword arguments')\n\n # guilds=[] or guilds=[...]\n if guild is MISSING:\n # If no arguments are given then it should default to the ones\n # given to the guilds(...) decorator or None for global.\n if guilds is MISSING:\n return getattr(command, '_guild_ids', None)\n\n # guilds=[] is the same as global\n if len(guilds) == 0:\n return None\n\n return {g.id for g in guilds}\n\n # At this point it should be...\n # guild=None or guild=Object\n if guild is None:\n return None\n return {guild.id}\n\n\nclass CommandTree(Generic[ClientT]):\n \"\"\"Represents a container that holds application command information.\n\n Parameters\n -----------\n client: :class:`~discord.Client`\n The client instance to get application command information from.\n fallback_to_global: :class:`bool`\n If a guild-specific command is not found when invoked, then try falling back into\n a global command in the tree. For example, if the tree locally has a ``/ping`` command\n under the global namespace but the guild has a guild-specific ``/ping``, instead of failing\n to find the guild-specific ``/ping`` command it will fall back to the global ``/ping`` command.\n This has the potential to raise more :exc:`~discord.app_commands.CommandSignatureMismatch` errors\n than usual. Defaults to ``True``.\n allowed_contexts: :class:`~discord.app_commands.AppCommandContext`\n The default allowed contexts that applies to all commands in this tree.\n Note that you can override this on a per command basis.\n\n .. versionadded:: 2.4\n allowed_installs: :class:`~discord.app_commands.AppInstallationType`\n The default allowed install locations that apply to all commands in this tree.\n Note that you can override this on a per command basis.\n\n .. versionadded:: 2.4\n \"\"\"\n\n def __init__(\n self,\n client: ClientT,\n *,\n fallback_to_global: bool = True,\n allowed_contexts: AppCommandContext = MISSING,\n allowed_installs: AppInstallationType = MISSING,\n ):\n self.client: ClientT = client\n self._http = client.http\n self._state = client._connection\n\n if self._state._command_tree is not None:\n raise ClientException('This client already has an associated command tree.')\n\n self._state._command_tree = self\n self.fallback_to_global: bool = fallback_to_global\n self.allowed_contexts = AppCommandContext() if allowed_contexts is MISSING else allowed_contexts\n self.allowed_installs = AppInstallationType() if allowed_installs is MISSING else allowed_installs\n self._guild_commands: Dict[int, Dict[str, Union[Command, Group]]] = {}\n self._global_commands: Dict[str, Union[Command, Group]] = {}\n # (name, guild_id, command_type): Command\n # The above two mappings can use this structure too but we need fast retrieval\n # by name and guild_id in the above case while here it isn't as important since\n # it's uncommon and N=5 anyway.\n self._context_menus: Dict[Tuple[str, Optional[int], int], ContextMenu] = {}\n\n async def fetch_command(self, command_id: int, /, *, guild: Optional[Snowflake] = None) -> AppCommand:\n \"\"\"|coro|\n\n Fetches an application command from the application.\n\n Parameters\n -----------\n command_id: :class:`int`\n The ID of the command to fetch.\n guild: Optional[:class:`~discord.abc.Snowflake`]\n The guild to fetch the command from. If not passed then the global command\n is fetched instead.\n\n Raises\n -------\n HTTPException\n Fetching the command failed.\n MissingApplicationID\n The application ID could not be found.\n NotFound\n The application command was not found.\n This could also be because the command is a guild command\n and the guild was not specified and vice versa.\n\n Returns\n --------\n :class:`~discord.app_commands.AppCommand`\n The application command.\n \"\"\"\n if self.client.application_id is None:\n raise MissingApplicationID\n\n if guild is None:\n command = await self._http.get_global_command(self.client.application_id, command_id)\n else:\n command = await self._http.get_guild_command(self.client.application_id, guild.id, command_id)\n\n return AppCommand(data=command, state=self._state)\n\n async def fetch_commands(self, *, guild: Optional[Snowflake] = None) -> List[AppCommand]:\n \"\"\"|coro|\n\n Fetches the application's current commands.\n\n If no guild is passed then global commands are fetched, otherwise\n the guild's commands are fetched instead.\n\n .. note::\n\n This includes context menu commands.\n\n Parameters\n -----------\n guild: Optional[:class:`~discord.abc.Snowflake`]\n The guild to fetch the commands from. If not passed then global commands\n are fetched instead.\n\n Raises\n -------\n HTTPException\n Fetching the commands failed.\n MissingApplicationID\n The application ID could not be found.\n\n Returns\n --------\n List[:class:`~discord.app_commands.AppCommand`]\n The application's commands.\n \"\"\"\n if self.client.application_id is None:\n raise MissingApplicationID\n\n if guild is None:\n commands = await self._http.get_global_commands(self.client.application_id)\n else:\n commands = await self._http.get_guild_commands(self.client.application_id, guild.id)\n\n return [AppCommand(data=data, state=self._state) for data in commands]\n\n def copy_global_to(self, *, guild: Snowflake) -> None:\n \"\"\"Copies all global commands to the specified guild.\n\n This method is mainly available for development purposes, as it allows you\n to copy your global commands over to a testing guild easily.\n\n Note that this method will *override* pre-existing guild commands that would conflict.\n\n Parameters\n -----------\n guild: :class:`~discord.abc.Snowflake`\n The guild to copy the commands to.\n\n Raises\n --------\n CommandLimitReached\n The maximum number of commands was reached for that guild.\n This is currently 100 for slash commands and 5 for context menu commands.\n \"\"\"\n\n try:\n mapping = self._guild_commands[guild.id].copy()\n except KeyError:\n mapping = {}\n\n mapping.update(self._global_commands)\n if len(mapping) > 100:\n raise CommandLimitReached(guild_id=guild.id, limit=100)\n\n ctx_menu: Dict[Tuple[str, Optional[int], int], ContextMenu] = {\n (name, guild.id, cmd_type): cmd\n for ((name, g, cmd_type), cmd) in self._context_menus.items()\n if g is None or g == guild.id\n }\n\n counter = Counter(cmd_type for _, _, cmd_type in ctx_menu)\n for cmd_type, count in counter.items():\n if count > 5:\n as_enum = AppCommandType(cmd_type)\n raise CommandLimitReached(guild_id=guild.id, limit=5, type=as_enum)\n\n self._context_menus.update(ctx_menu)\n self._guild_commands[guild.id] = mapping\n\n def add_command(\n self,\n command: Union[Command[Any, ..., Any], ContextMenu, Group],\n /,\n *,\n guild: Optional[Snowflake] = MISSING,\n guilds: Sequence[Snowflake] = MISSING,\n override: bool = False,\n ) -> None:\n \"\"\"Adds an application command to the tree.\n\n This only adds the command locally -- in order to sync the commands\n and enable them in the client, :meth:`sync` must be called.\n\n The root parent of the command is added regardless of the type passed.\n\n Parameters\n -----------\n command: Union[:class:`Command`, :class:`Group`]\n The application command or group to add.\n guild: Optional[:class:`~discord.abc.Snowflake`]\n The guild to add the command to. If not given or ``None`` then it\n becomes a global command instead.\n\n .. note ::\n\n Due to a Discord limitation, this keyword argument cannot be used in conjunction with\n contexts (e.g. :func:`.app_commands.allowed_contexts`) or installation types\n (e.g. :func:`.app_commands.allowed_installs`).\n\n guilds: List[:class:`~discord.abc.Snowflake`]\n The list of guilds to add the command to. This cannot be mixed\n with the ``guild`` parameter. If no guilds are given at all\n then it becomes a global command instead.\n\n .. note ::\n\n Due to a Discord limitation, this keyword argument cannot be used in conjunction with\n contexts (e.g. :func:`.app_commands.allowed_contexts`) or installation types\n (e.g. :func:`.app_commands.allowed_installs`).\n\n override: :class:`bool`\n Whether to override a command with the same name. If ``False``\n an exception is raised. Default is ``False``.\n\n Raises\n --------\n ~discord.app_commands.CommandAlreadyRegistered\n The command was already registered and no override was specified.\n TypeError\n The application command passed is not a valid application command.\n Or, ``guild`` and ``guilds`` were both given.\n CommandLimitReached\n The maximum number of commands was reached globally or for that guild.\n This is currently 100 for slash commands and 5 for context menu commands.\n \"\"\"\n\n guild_ids = _retrieve_guild_ids(command, guild, guilds)\n if isinstance(command, ContextMenu):\n type = command.type.value\n name = command.name\n\n def _context_menu_add_helper(\n guild_id: Optional[int],\n data: Dict[Tuple[str, Optional[int], int], ContextMenu],\n name: str = name,\n type: int = type,\n ) -> None:\n key = (name, guild_id, type)\n found = key in self._context_menus\n if found and not override:\n raise CommandAlreadyRegistered(name, guild_id)\n\n # If the key is found and overridden then it shouldn't count as an extra addition\n # read as `0 if override and found else 1` if confusing\n to_add = not (override and found)\n total = sum(1 for _, g, t in self._context_menus if g == guild_id and t == type)\n if total + to_add > 5:\n raise CommandLimitReached(guild_id=guild_id, limit=5, type=AppCommandType(type))\n data[key] = command\n\n if guild_ids is None:\n _context_menu_add_helper(None, self._context_menus)\n else:\n current: Dict[Tuple[str, Optional[int], int], ContextMenu] = {}\n for guild_id in guild_ids:\n _context_menu_add_helper(guild_id, current)\n\n # Update at the end in order to make sure the update is atomic.\n # An error during addition could end up making the context menu mapping\n # have a partial state\n self._context_menus.update(current)\n return\n elif not isinstance(command, (Command, Group)):\n raise TypeError(f'Expected an application command, received {command.__class__.__name__} instead')\n\n # todo: validate application command groups having children (required)\n\n root = command.root_parent or command\n name = root.name\n if guild_ids is not None:\n # Validate that the command can be added first, before actually\n # adding it into the mapping. This ensures atomicity.\n for guild_id in guild_ids:\n commands = self._guild_commands.get(guild_id, {})\n found = name in commands\n if found and not override:\n raise CommandAlreadyRegistered(name, guild_id)\n\n to_add = not (override and found)\n if len(commands) + to_add > 100:\n raise CommandLimitReached(guild_id=guild_id, limit=100)\n\n # Actually add the command now that it has been verified to be okay.\n for guild_id in guild_ids:\n commands = self._guild_commands.setdefault(guild_id, {})\n commands[name] = root\n else:\n found = name in self._global_commands\n if found and not override:\n raise CommandAlreadyRegistered(name, None)\n\n to_add = not (override and found)\n if len(self._global_commands) + to_add > 100:\n raise CommandLimitReached(guild_id=None, limit=100)\n self._global_commands[name] = root\n\n @overload\n def remove_command(\n self,\n command: str,\n /,\n *,\n guild: Optional[Snowflake] = ...,\n type: Literal[AppCommandType.message, AppCommandType.user],\n ) -> Optional[ContextMenu]:\n ...\n\n @overload\n def remove_command(\n self,\n command: str,\n /,\n *,\n guild: Optional[Snowflake] = ...,\n type: Literal[AppCommandType.chat_input] = ...,\n ) -> Optional[Union[Command[Any, ..., Any], Group]]:\n ...\n\n @overload\n def remove_command(\n self,\n command: str,\n /,\n *,\n guild: Optional[Snowflake] = ...,\n type: AppCommandType,\n ) -> Optional[Union[Command[Any, ..., Any], ContextMenu, Group]]:\n ...\n\n def remove_command(\n self,\n command: str,\n /,\n *,\n guild: Optional[Snowflake] = None,\n type: AppCommandType = AppCommandType.chat_input,\n ) -> Optional[Union[Command[Any, ..., Any], ContextMenu, Group]]:\n \"\"\"Removes an application command from the tree.\n\n This only removes the command locally -- in order to sync the commands\n and remove them in the client, :meth:`sync` must be called.\n\n Parameters\n -----------\n command: :class:`str`\n The name of the root command to remove.\n guild: Optional[:class:`~discord.abc.Snowflake`]\n The guild to remove the command from. If not given or ``None`` then it\n removes a global command instead.\n type: :class:`~discord.AppCommandType`\n The type of command to remove. Defaults to :attr:`~discord.AppCommandType.chat_input`,\n i.e. slash commands.\n\n Returns\n ---------\n Optional[Union[:class:`Command`, :class:`ContextMenu`, :class:`Group`]]\n The application command that got removed.\n If nothing was removed then ``None`` is returned instead.\n \"\"\"\n\n if type is AppCommandType.chat_input:\n if guild is None:\n return self._global_commands.pop(command, None)\n else:\n try:\n commands = self._guild_commands[guild.id]\n except KeyError:\n return None\n else:\n return commands.pop(command, None)\n elif type in (AppCommandType.user, AppCommandType.message):\n guild_id = None if guild is None else guild.id\n key = (command, guild_id, type.value)\n return self._context_menus.pop(key, None)\n\n def clear_commands(self, *, guild: Optional[Snowflake], type: Optional[AppCommandType] = None) -> None:\n \"\"\"Clears all application commands from the tree.\n\n This only removes the commands locally -- in order to sync the commands\n and remove them in the client, :meth:`sync` must be called.\n\n Parameters\n -----------\n guild: Optional[:class:`~discord.abc.Snowflake`]\n The guild to remove the commands from. If ``None`` then it\n removes all global commands instead.\n type: :class:`~discord.AppCommandType`\n The type of command to clear. If not given or ``None`` then it removes all commands\n regardless of the type.\n \"\"\"\n\n if type is None or type is AppCommandType.chat_input:\n if guild is None:\n self._global_commands.clear()\n else:\n try:\n commands = self._guild_commands[guild.id]\n except KeyError:\n pass\n else:\n commands.clear()\n\n guild_id = None if guild is None else guild.id\n if type is None:\n self._context_menus = {\n (name, _guild_id, value): cmd\n for (name, _guild_id, value), cmd in self._context_menus.items()\n if _guild_id != guild_id\n }\n elif type in (AppCommandType.user, AppCommandType.message):\n self._context_menus = {\n (name, _guild_id, value): cmd\n for (name, _guild_id, value), cmd in self._context_menus.items()\n if _guild_id != guild_id or value != type.value\n }\n\n @overload\n def get_command(\n self,\n command: str,\n /,\n *,\n guild: Optional[Snowflake] = ...,\n type: Literal[AppCommandType.message, AppCommandType.user],\n ) -> Optional[ContextMenu]:\n ...\n\n @overload\n def get_command(\n self,\n command: str,\n /,\n *,\n guild: Optional[Snowflake] = ...,\n type: Literal[AppCommandType.chat_input] = ...,\n ) -> Optional[Union[Command[Any, ..., Any], Group]]:\n ...\n\n @overload\n def get_command(\n self,\n command: str,\n /,\n *,\n guild: Optional[Snowflake] = ...,\n type: AppCommandType,\n ) -> Optional[Union[Command[Any, ..., Any], ContextMenu, Group]]:\n ...\n\n def get_command(\n self,\n command: str,\n /,\n *,\n guild: Optional[Snowflake] = None,\n type: AppCommandType = AppCommandType.chat_input,\n ) -> Optional[Union[Command[Any, ..., Any], ContextMenu, Group]]:\n \"\"\"Gets an application command from the tree.\n\n Parameters\n -----------\n command: :class:`str`\n The name of the root command to get.\n guild: Optional[:class:`~discord.abc.Snowflake`]\n The guild to get the command from. If not given or ``None`` then it\n gets a global command instead.\n type: :class:`~discord.AppCommandType`\n The type of command to get. Defaults to :attr:`~discord.AppCommandType.chat_input`,\n i.e. slash commands.\n\n Returns\n ---------\n Optional[Union[:class:`Command`, :class:`ContextMenu`, :class:`Group`]]\n The application command that was found.\n If nothing was found then ``None`` is returned instead.\n \"\"\"\n\n if type is AppCommandType.chat_input:\n if guild is None:\n return self._global_commands.get(command)\n else:\n try:\n commands = self._guild_commands[guild.id]\n except KeyError:\n return None\n else:\n return commands.get(command)\n elif type in (AppCommandType.user, AppCommandType.message):\n guild_id = None if guild is None else guild.id\n key = (command, guild_id, type.value)\n return self._context_menus.get(key)\n\n @overload\n def get_commands(\n self,\n *,\n guild: Optional[Snowflake] = ...,\n type: Literal[AppCommandType.message, AppCommandType.user],\n ) -> List[ContextMenu]:\n ...\n\n @overload\n def get_commands(\n self,\n *,\n guild: Optional[Snowflake] = ...,\n type: Literal[AppCommandType.chat_input],\n ) -> List[Union[Command[Any, ..., Any], Group]]:\n ...\n\n @overload\n def get_commands(\n self,\n *,\n guild: Optional[Snowflake] = ...,\n type: AppCommandType,\n ) -> Union[List[Union[Command[Any, ..., Any], Group]], List[ContextMenu]]:\n ...\n\n @overload\n def get_commands(\n self,\n *,\n guild: Optional[Snowflake] = ...,\n type: Optional[AppCommandType] = ...,\n ) -> List[Union[Command[Any, ..., Any], Group, ContextMenu]]:\n ...\n\n def get_commands(\n self,\n *,\n guild: Optional[Snowflake] = None,\n type: Optional[AppCommandType] = None,\n ) -> Union[\n List[ContextMenu],\n List[Union[Command[Any, ..., Any], Group]],\n List[Union[Command[Any, ..., Any], Group, ContextMenu]],\n ]:\n \"\"\"Gets all application commands from the tree.\n\n Parameters\n -----------\n guild: Optional[:class:`~discord.abc.Snowflake`]\n The guild to get the commands from, not including global commands.\n If not given or ``None`` then only global commands are returned.\n type: Optional[:class:`~discord.AppCommandType`]\n The type of commands to get. When not given or ``None``, then all\n command types are returned.\n\n Returns\n ---------\n List[Union[:class:`ContextMenu`, :class:`Command`, :class:`Group`]]\n The application commands from the tree.\n \"\"\"\n if type is None:\n return self._get_all_commands(guild=guild)\n\n if type is AppCommandType.chat_input:\n if guild is None:\n return list(self._global_commands.values())\n else:\n try:\n commands = self._guild_commands[guild.id]\n except KeyError:\n return []\n else:\n return list(commands.values())\n else:\n guild_id = None if guild is None else guild.id\n value = type.value\n return [command for ((_, g, t), command) in self._context_menus.items() if g == guild_id and t == value]\n\n @overload\n def walk_commands(\n self,\n *,\n guild: Optional[Snowflake] = ...,\n type: Literal[AppCommandType.message, AppCommandType.user],\n ) -> Generator[ContextMenu, None, None]:\n ...\n\n @overload\n def walk_commands(\n self,\n *,\n guild: Optional[Snowflake] = ...,\n type: Literal[AppCommandType.chat_input] = ...,\n ) -> Generator[Union[Command[Any, ..., Any], Group], None, None]:\n ...\n\n @overload\n def walk_commands(\n self,\n *,\n guild: Optional[Snowflake] = ...,\n type: AppCommandType,\n ) -> Union[Generator[Union[Command[Any, ..., Any], Group], None, None], Generator[ContextMenu, None, None]]:\n ...\n\n def walk_commands(\n self,\n *,\n guild: Optional[Snowflake] = None,\n type: AppCommandType = AppCommandType.chat_input,\n ) -> Union[Generator[Union[Command[Any, ..., Any], Group], None, None], Generator[ContextMenu, None, None]]:\n \"\"\"An iterator that recursively walks through all application commands and child commands from the tree.\n\n Parameters\n -----------\n guild: Optional[:class:`~discord.abc.Snowflake`]\n The guild to iterate the commands from, not including global commands.\n If not given or ``None`` then only global commands are iterated.\n type: :class:`~discord.AppCommandType`\n The type of commands to iterate over. Defaults to :attr:`~discord.AppCommandType.chat_input`,\n i.e. slash commands.\n\n Yields\n ---------\n Union[:class:`ContextMenu`, :class:`Command`, :class:`Group`]\n The application commands from the tree.\n \"\"\"\n\n if type is AppCommandType.chat_input:\n if guild is None:\n for cmd in self._global_commands.values():\n yield cmd\n if isinstance(cmd, Group):\n yield from cmd.walk_commands()\n else:\n try:\n commands = self._guild_commands[guild.id]\n except KeyError:\n return\n else:\n for cmd in commands.values():\n yield cmd\n if isinstance(cmd, Group):\n yield from cmd.walk_commands()\n else:\n guild_id = None if guild is None else guild.id\n value = type.value\n for (_, g, t), command in self._context_menus.items():\n if g == guild_id and t == value:\n yield command\n\n def _get_all_commands(\n self, *, guild: Optional[Snowflake] = None\n ) -> List[Union[Command[Any, ..., Any], Group, ContextMenu]]:\n if guild is None:\n base: List[Union[Command[Any, ..., Any], Group, ContextMenu]] = list(self._global_commands.values())\n base.extend(cmd for ((_, g, _), cmd) in self._context_menus.items() if g is None)\n return base\n else:\n try:\n commands = self._guild_commands[guild.id]\n except KeyError:\n guild_id = guild.id\n return [cmd for ((_, g, _), cmd) in self._context_menus.items() if g == guild_id]\n else:\n base: List[Union[Command[Any, ..., Any], Group, ContextMenu]] = list(commands.values())\n guild_id = guild.id\n base.extend(cmd for ((_, g, _), cmd) in self._context_menus.items() if g == guild_id)\n return base\n\n def _remove_with_module(self, name: str) -> None:\n remove: List[Any] = []\n for key, cmd in self._context_menus.items():\n if cmd.module is not None and _is_submodule(name, cmd.module):\n remove.append(key)\n\n for key in remove:\n del self._context_menus[key]\n\n remove = []\n for key, cmd in self._global_commands.items():\n if cmd.module is not None and _is_submodule(name, cmd.module):\n remove.append(key)\n\n for key in remove:\n del self._global_commands[key]\n\n for mapping in self._guild_commands.values():\n remove = []\n for key, cmd in mapping.items():\n if cmd.module is not None and _is_submodule(name, cmd.module):\n remove.append(key)\n\n for key in remove:\n del mapping[key]\n\n async def on_error(self, interaction: Interaction[ClientT], error: AppCommandError, /) -> None:\n \"\"\"|coro|\n\n A callback that is called when any command raises an :exc:`AppCommandError`.\n\n The default implementation logs the exception using the library logger\n if the command does not have any error handlers attached to it.\n\n To get the command that failed, :attr:`discord.Interaction.command` should\n be used.\n\n Parameters\n -----------\n interaction: :class:`~discord.Interaction`\n The interaction that is being handled.\n error: :exc:`AppCommandError`\n The exception that was raised.\n \"\"\"\n\n command = interaction.command\n if command is not None:\n if command._has_any_error_handlers():\n return\n\n _log.error('Ignoring exception in command %r', command.name, exc_info=error)\n else:\n _log.error('Ignoring exception in command tree', exc_info=error)\n\n def error(self, coro: ErrorFunc) -> ErrorFunc:\n \"\"\"A decorator that registers a coroutine as a local error handler.\n\n This must match the signature of the :meth:`on_error` callback.\n\n The error passed will be derived from :exc:`AppCommandError`.\n\n Parameters\n -----------\n coro: :ref:`coroutine `\n The coroutine to register as the local error handler.\n\n Raises\n -------\n TypeError\n The coroutine passed is not actually a coroutine or does\n not match the signature.\n \"\"\"\n\n if not inspect.iscoroutinefunction(coro):\n raise TypeError('The error handler must be a coroutine.')\n\n params = inspect.signature(coro).parameters\n if len(params) != 2:\n raise TypeError('error handler must have 2 parameters')\n\n self.on_error = coro\n return coro\n\n def command(\n self,\n *,\n name: Union[str, locale_str] = MISSING,\n description: Union[str, locale_str] = MISSING,\n nsfw: bool = False,\n guild: Optional[Snowflake] = MISSING,\n guilds: Sequence[Snowflake] = MISSING,\n auto_locale_strings: bool = True,\n extras: Dict[Any, Any] = MISSING,\n ) -> Callable[[CommandCallback[Group, P, T]], Command[Group, P, T]]:\n \"\"\"A decorator that creates an application command from a regular function directly under this tree.\n\n Parameters\n ------------\n name: Union[:class:`str`, :class:`locale_str`]\n The name of the application command. If not given, it defaults to a lower-case\n version of the callback name.\n description: Union[:class:`str`, :class:`locale_str`]\n The description of the application command. This shows up in the UI to describe\n the application command. If not given, it defaults to the first line of the docstring\n of the callback shortened to 100 characters.\n nsfw: :class:`bool`\n Whether the command is NSFW and should only work in NSFW channels. Defaults to ``False``.\n\n Due to a Discord limitation, this does not work on subcommands.\n guild: Optional[:class:`~discord.abc.Snowflake`]\n The guild to add the command to. If not given or ``None`` then it\n becomes a global command instead.\n\n .. note ::\n\n Due to a Discord limitation, this keyword argument cannot be used in conjunction with\n contexts (e.g. :func:`.app_commands.allowed_contexts`) or installation types\n (e.g. :func:`.app_commands.allowed_installs`).\n\n guilds: List[:class:`~discord.abc.Snowflake`]\n The list of guilds to add the command to. This cannot be mixed\n with the ``guild`` parameter. If no guilds are given at all\n then it becomes a global command instead.\n\n .. note ::\n\n Due to a Discord limitation, this keyword argument cannot be used in conjunction with\n contexts (e.g. :func:`.app_commands.allowed_contexts`) or installation types\n (e.g. :func:`.app_commands.allowed_installs`).\n\n auto_locale_strings: :class:`bool`\n If this is set to ``True``, then all translatable strings will implicitly\n be wrapped into :class:`locale_str` rather than :class:`str`. This could\n avoid some repetition and be more ergonomic for certain defaults such\n as default command names, command descriptions, and parameter names.\n Defaults to ``True``.\n extras: :class:`dict`\n A dictionary that can be used to store extraneous data.\n The library will not touch any values or keys within this dictionary.\n \"\"\"\n\n def decorator(func: CommandCallback[Group, P, T]) -> Command[Group, P, T]:\n if not inspect.iscoroutinefunction(func):\n raise TypeError('command function must be a coroutine function')\n\n if description is MISSING:\n if func.__doc__ is None:\n desc = '…'\n else:\n desc = _shorten(func.__doc__)\n else:\n desc = description\n\n command = Command(\n name=name if name is not MISSING else func.__name__,\n description=desc,\n callback=func,\n nsfw=nsfw,\n parent=None,\n auto_locale_strings=auto_locale_strings,\n extras=extras,\n )\n self.add_command(command, guild=guild, guilds=guilds)\n return command\n\n return decorator\n\n def context_menu(\n self,\n *,\n name: Union[str, locale_str] = MISSING,\n nsfw: bool = False,\n guild: Optional[Snowflake] = MISSING,\n guilds: Sequence[Snowflake] = MISSING,\n auto_locale_strings: bool = True,\n extras: Dict[Any, Any] = MISSING,\n ) -> Callable[[ContextMenuCallback], ContextMenu]:\n \"\"\"A decorator that creates an application command context menu from a regular function directly under this tree.\n\n This function must have a signature of :class:`~discord.Interaction` as its first parameter\n and taking either a :class:`~discord.Member`, :class:`~discord.User`, or :class:`~discord.Message`,\n or a :obj:`typing.Union` of ``Member`` and ``User`` as its second parameter.\n\n Examples\n ---------\n\n .. code-block:: python3\n\n @app_commands.context_menu()\n async def react(interaction: discord.Interaction, message: discord.Message):\n await interaction.response.send_message('Very cool message!', ephemeral=True)\n\n @app_commands.context_menu()\n async def ban(interaction: discord.Interaction, user: discord.Member):\n await interaction.response.send_message(f'Should I actually ban {user}...', ephemeral=True)\n\n Parameters\n ------------\n name: Union[:class:`str`, :class:`locale_str`]\n The name of the context menu command. If not given, it defaults to a title-case\n version of the callback name. Note that unlike regular slash commands this can\n have spaces and upper case characters in the name.\n nsfw: :class:`bool`\n Whether the command is NSFW and should only work in NSFW channels. Defaults to ``False``.\n\n Due to a Discord limitation, this does not work on subcommands.\n guild: Optional[:class:`~discord.abc.Snowflake`]\n The guild to add the command to. If not given or ``None`` then it\n becomes a global command instead.\n\n .. note ::\n\n Due to a Discord limitation, this keyword argument cannot be used in conjunction with\n contexts (e.g. :func:`.app_commands.allowed_contexts`) or installation types\n (e.g. :func:`.app_commands.allowed_installs`).\n\n guilds: List[:class:`~discord.abc.Snowflake`]\n The list of guilds to add the command to. This cannot be mixed\n with the ``guild`` parameter. If no guilds are given at all\n then it becomes a global command instead.\n\n .. note ::\n\n Due to a Discord limitation, this keyword argument cannot be used in conjunction with\n contexts (e.g. :func:`.app_commands.allowed_contexts`) or installation types\n (e.g. :func:`.app_commands.allowed_installs`).\n\n auto_locale_strings: :class:`bool`\n If this is set to ``True``, then all translatable strings will implicitly\n be wrapped into :class:`locale_str` rather than :class:`str`. This could\n avoid some repetition and be more ergonomic for certain defaults such\n as default command names, command descriptions, and parameter names.\n Defaults to ``True``.\n extras: :class:`dict`\n A dictionary that can be used to store extraneous data.\n The library will not touch any values or keys within this dictionary.\n \"\"\"\n\n def decorator(func: ContextMenuCallback) -> ContextMenu:\n if not inspect.iscoroutinefunction(func):\n raise TypeError('context menu function must be a coroutine function')\n\n actual_name = func.__name__.title() if name is MISSING else name\n context_menu = ContextMenu(\n name=actual_name,\n nsfw=nsfw,\n callback=func,\n auto_locale_strings=auto_locale_strings,\n extras=extras,\n )\n self.add_command(context_menu, guild=guild, guilds=guilds)\n return context_menu\n\n return decorator\n\n @property\n def translator(self) -> Optional[Translator]:\n \"\"\"Optional[:class:`Translator`]: The translator, if any, responsible for handling translation of commands.\n\n To change the translator, use :meth:`set_translator`.\n \"\"\"\n return self._state._translator\n\n async def set_translator(self, translator: Optional[Translator]) -> None:\n \"\"\"|coro|\n\n Sets the translator to use for translating commands.\n\n If a translator was previously set, it will be unloaded using its\n :meth:`Translator.unload` method.\n\n When a translator is set, it will be loaded using its :meth:`Translator.load` method.\n\n Parameters\n ------------\n translator: Optional[:class:`Translator`]\n The translator to use. If ``None`` then the translator is just removed and unloaded.\n\n Raises\n -------\n TypeError\n The translator was not ``None`` or a :class:`Translator` instance.\n \"\"\"\n\n if translator is not None and not isinstance(translator, Translator):\n raise TypeError(f'expected None or Translator instance, received {translator.__class__.__name__} instead')\n\n old_translator = self._state._translator\n if old_translator is not None:\n await old_translator.unload()\n\n if translator is None:\n self._state._translator = None\n else:\n await translator.load()\n self._state._translator = translator\n\n async def sync(self, *, guild: Optional[Snowflake] = None) -> List[AppCommand]:\n \"\"\"|coro|\n\n Syncs the application commands to Discord.\n\n This also runs the translator to get the translated strings necessary for\n feeding back into Discord.\n\n This must be called for the application commands to show up.\n\n Parameters\n -----------\n guild: Optional[:class:`~discord.abc.Snowflake`]\n The guild to sync the commands to. If ``None`` then it\n syncs all global commands instead.\n\n Raises\n -------\n HTTPException\n Syncing the commands failed.\n CommandSyncFailure\n Syncing the commands failed due to a user related error, typically because\n the command has invalid data. This is equivalent to an HTTP status code of\n 400.\n Forbidden\n The client does not have the ``applications.commands`` scope in the guild.\n MissingApplicationID\n The client does not have an application ID.\n TranslationError\n An error occurred while translating the commands.\n\n Returns\n --------\n List[:class:`AppCommand`]\n The application's commands that got synced.\n \"\"\"\n\n if self.client.application_id is None:\n raise MissingApplicationID\n\n commands = self._get_all_commands(guild=guild)\n\n translator = self.translator\n if translator:\n payload = [await command.get_translated_payload(self, translator) for command in commands]\n else:\n payload = [command.to_dict(self) for command in commands]\n\n try:\n if guild is None:\n data = await self._http.bulk_upsert_global_commands(self.client.application_id, payload=payload)\n else:\n data = await self._http.bulk_upsert_guild_commands(self.client.application_id, guild.id, payload=payload)\n except HTTPException as e:\n if e.status == 400 and e.code == 50035:\n raise CommandSyncFailure(e, commands) from None\n raise\n\n return [AppCommand(data=d, state=self._state) for d in data]\n\n async def _dispatch_error(self, interaction: Interaction[ClientT], error: AppCommandError, /) -> None:\n command = interaction.command\n interaction.command_failed = True\n try:\n if isinstance(command, Command):\n await command._invoke_error_handlers(interaction, error)\n finally:\n await self.on_error(interaction, error)\n\n def _from_interaction(self, interaction: Interaction[ClientT]) -> None:\n async def wrapper():\n try:\n await self._call(interaction)\n except AppCommandError as e:\n await self._dispatch_error(interaction, e)\n\n self.client.loop.create_task(wrapper(), name='CommandTree-invoker')\n\n def _get_context_menu(self, data: ApplicationCommandInteractionData) -> Optional[ContextMenu]:\n name = data['name']\n guild_id = _get_as_snowflake(data, 'guild_id')\n t = data.get('type', 1)\n cmd = self._context_menus.get((name, guild_id, t))\n if cmd is None and self.fallback_to_global:\n return self._context_menus.get((name, None, t))\n return cmd\n\n def _get_app_command_options(\n self, data: ApplicationCommandInteractionData\n ) -> Tuple[Command[Any, ..., Any], List[ApplicationCommandInteractionDataOption]]:\n parents: List[str] = []\n name = data['name']\n\n command_guild_id = _get_as_snowflake(data, 'guild_id')\n if command_guild_id:\n try:\n guild_commands = self._guild_commands[command_guild_id]\n except KeyError:\n command = None if not self.fallback_to_global else self._global_commands.get(name)\n else:\n command = guild_commands.get(name)\n if command is None and self.fallback_to_global:\n command = self._global_commands.get(name)\n else:\n command = self._global_commands.get(name)\n\n # If it's not found at this point then it's not gonna be found at any point\n if command is None:\n raise CommandNotFound(name, parents)\n\n # This could be done recursively but it'd be a bother due to the state needed\n # to be tracked above like the parents, the actual command type, and the\n # resulting options we care about\n searching = True\n options: List[ApplicationCommandInteractionDataOption] = data.get('options', [])\n while searching:\n for option in options:\n # Find subcommands\n if option.get('type', 0) in (1, 2):\n parents.append(name)\n name = option['name']\n command = command._get_internal_command(name)\n if command is None:\n raise CommandNotFound(name, parents)\n options = option.get('options', [])\n break\n else:\n searching = False\n break\n else:\n break\n\n if isinstance(command, Group):\n # Right now, groups can't be invoked. This is a Discord limitation in how they\n # do slash commands. So if we're here and we have a Group rather than a Command instance\n # then something in the code is out of date from the data that Discord has.\n raise CommandSignatureMismatch(command)\n\n return (command, options)\n\n async def _call_context_menu(\n self, interaction: Interaction[ClientT], data: ApplicationCommandInteractionData, type: int\n ) -> None:\n name = data['name']\n guild_id = _get_as_snowflake(data, 'guild_id')\n ctx_menu = self._context_menus.get((name, guild_id, type))\n if ctx_menu is None and self.fallback_to_global:\n ctx_menu = self._context_menus.get((name, None, type))\n\n # Pre-fill the cached slot to prevent re-computation\n interaction._cs_command = ctx_menu\n\n if ctx_menu is None:\n raise CommandNotFound(name, [], AppCommandType(type))\n\n resolved = Namespace._get_resolved_items(interaction, data.get('resolved', {}))\n\n # This is annotated as str | int but realistically this will always be str\n target_id: Optional[Union[str, int]] = data.get('target_id')\n # Right now, the only types are message and user\n # Therefore, there's no conflict with snowflakes\n\n # This will always work at runtime\n key = ResolveKey.any_with(target_id) # type: ignore\n value = resolved.get(key)\n if ctx_menu.type.value != type:\n raise CommandSignatureMismatch(ctx_menu)\n\n if value is None:\n raise AppCommandError('This should not happen if Discord sent well-formed data.')\n\n # I assume I don't have to type check here.\n try:\n await ctx_menu._invoke(interaction, value)\n except AppCommandError as e:\n if ctx_menu.on_error is not None:\n await ctx_menu.on_error(interaction, e)\n await self.on_error(interaction, e)\n else:\n self.client.dispatch('app_command_completion', interaction, ctx_menu)\n\n async def interaction_check(self, interaction: Interaction[ClientT], /) -> bool:\n \"\"\"|coro|\n\n A global check to determine if an :class:`~discord.Interaction` should\n be processed by the tree.\n\n The default implementation returns True (all interactions are processed),\n but can be overridden if custom behaviour is desired.\n \"\"\"\n return True\n\n async def _call(self, interaction: Interaction[ClientT]) -> None:\n if not await self.interaction_check(interaction):\n interaction.command_failed = True\n return\n\n data: ApplicationCommandInteractionData = interaction.data # type: ignore\n type = data.get('type', 1)\n if type != 1:\n # Context menu command...\n await self._call_context_menu(interaction, data, type)\n return\n\n command, options = self._get_app_command_options(data)\n\n # Pre-fill the cached slot to prevent re-computation\n interaction._cs_command = command\n\n # At this point options refers to the arguments of the command\n # and command refers to the class type we care about\n namespace = Namespace(interaction, data.get('resolved', {}), options)\n\n # Same pre-fill as above\n interaction._cs_namespace = namespace\n\n # Auto complete handles the namespace differently... so at this point this is where we decide where that is.\n if interaction.type is InteractionType.autocomplete:\n focused = next((opt['name'] for opt in options if opt.get('focused')), None)\n if focused is None:\n raise AppCommandError('This should not happen, but there is no focused element. This is a Discord bug.')\n\n try:\n await command._invoke_autocomplete(interaction, focused, namespace)\n except Exception:\n # Suppress exception since it can't be handled anyway.\n _log.exception('Ignoring exception in autocomplete for %r', command.qualified_name)\n\n return\n\n try:\n await command._invoke_with_namespace(interaction, namespace)\n except AppCommandError as e:\n interaction.command_failed = True\n await command._invoke_error_handlers(interaction, e)\n await self.on_error(interaction, e)\n else:\n if not interaction.command_failed:\n self.client.dispatch('app_command_completion', interaction, command)\n" }, { "path": "discord/appinfo.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import List, TYPE_CHECKING, Optional\n\nfrom . import utils\nfrom .asset import Asset\nfrom .flags import ApplicationFlags\nfrom .permissions import Permissions\nfrom .utils import MISSING\n\nif TYPE_CHECKING:\n from typing import Dict, Any\n\n from .guild import Guild\n from .types.appinfo import (\n AppInfo as AppInfoPayload,\n PartialAppInfo as PartialAppInfoPayload,\n Team as TeamPayload,\n InstallParams as InstallParamsPayload,\n )\n from .user import User\n from .state import ConnectionState\n\n__all__ = (\n 'AppInfo',\n 'PartialAppInfo',\n 'AppInstallParams',\n)\n\n\nclass AppInfo:\n \"\"\"Represents the application info for the bot provided by Discord.\n\n\n Attributes\n -------------\n id: :class:`int`\n The application ID.\n name: :class:`str`\n The application name.\n owner: :class:`User`\n The application owner.\n team: Optional[:class:`Team`]\n The application's team.\n\n .. versionadded:: 1.3\n\n description: :class:`str`\n The application description.\n bot_public: :class:`bool`\n Whether the bot can be invited by anyone or if it is locked\n to the application owner.\n bot_require_code_grant: :class:`bool`\n Whether the bot requires the completion of the full oauth2 code\n grant flow to join.\n rpc_origins: Optional[List[:class:`str`]]\n A list of RPC origin URLs, if RPC is enabled.\n\n verify_key: :class:`str`\n The hex encoded key for verification in interactions and the\n GameSDK's :ddocs:`GetTicket `.\n\n .. versionadded:: 1.3\n\n guild_id: Optional[:class:`int`]\n If this application is a game sold on Discord,\n this field will be the guild to which it has been linked to.\n\n .. versionadded:: 1.3\n\n primary_sku_id: Optional[:class:`int`]\n If this application is a game sold on Discord,\n this field will be the id of the \"Game SKU\" that is created,\n if it exists.\n\n .. versionadded:: 1.3\n\n slug: Optional[:class:`str`]\n If this application is a game sold on Discord,\n this field will be the URL slug that links to the store page.\n\n .. versionadded:: 1.3\n\n terms_of_service_url: Optional[:class:`str`]\n The application's terms of service URL, if set.\n\n .. versionadded:: 2.0\n\n privacy_policy_url: Optional[:class:`str`]\n The application's privacy policy URL, if set.\n\n .. versionadded:: 2.0\n\n tags: List[:class:`str`]\n The list of tags describing the functionality of the application.\n\n .. versionadded:: 2.0\n\n custom_install_url: List[:class:`str`]\n The custom authorization URL for the application, if enabled.\n\n .. versionadded:: 2.0\n\n install_params: Optional[:class:`AppInstallParams`]\n The settings for custom authorization URL of application, if enabled.\n\n .. versionadded:: 2.0\n role_connections_verification_url: Optional[:class:`str`]\n The application's connection verification URL which will render the application as\n a verification method in the guild's role verification configuration.\n\n .. versionadded:: 2.2\n interactions_endpoint_url: Optional[:class:`str`]\n The interactions endpoint url of the application to receive interactions over this endpoint rather than\n over the gateway, if configured.\n\n .. versionadded:: 2.4\n redirect_uris: List[:class:`str`]\n A list of authentication redirect URIs.\n\n .. versionadded:: 2.4\n approximate_guild_count: :class:`int`\n The approximate count of the guilds the bot was added to.\n\n .. versionadded:: 2.4\n \"\"\"\n\n __slots__ = (\n '_state',\n 'description',\n 'id',\n 'name',\n 'rpc_origins',\n 'bot_public',\n 'bot_require_code_grant',\n 'owner',\n '_icon',\n 'verify_key',\n 'team',\n 'guild_id',\n 'primary_sku_id',\n 'slug',\n '_cover_image',\n '_flags',\n 'terms_of_service_url',\n 'privacy_policy_url',\n 'tags',\n 'custom_install_url',\n 'install_params',\n 'role_connections_verification_url',\n 'interactions_endpoint_url',\n 'redirect_uris',\n 'approximate_guild_count',\n )\n\n def __init__(self, state: ConnectionState, data: AppInfoPayload):\n from .team import Team\n\n self._state: ConnectionState = state\n self.id: int = int(data['id'])\n self.name: str = data['name']\n self.description: str = data['description']\n self._icon: Optional[str] = data['icon']\n self.rpc_origins: Optional[List[str]] = data.get('rpc_origins')\n self.bot_public: bool = data['bot_public']\n self.bot_require_code_grant: bool = data['bot_require_code_grant']\n self.owner: User = state.create_user(data['owner'])\n\n team: Optional[TeamPayload] = data.get('team')\n self.team: Optional[Team] = Team(state, team) if team else None\n\n self.verify_key: str = data['verify_key']\n\n self.guild_id: Optional[int] = utils._get_as_snowflake(data, 'guild_id')\n\n self.primary_sku_id: Optional[int] = utils._get_as_snowflake(data, 'primary_sku_id')\n self.slug: Optional[str] = data.get('slug')\n self._flags: int = data.get('flags', 0)\n self._cover_image: Optional[str] = data.get('cover_image')\n self.terms_of_service_url: Optional[str] = data.get('terms_of_service_url')\n self.privacy_policy_url: Optional[str] = data.get('privacy_policy_url')\n self.tags: List[str] = data.get('tags', [])\n self.custom_install_url: Optional[str] = data.get('custom_install_url')\n self.role_connections_verification_url: Optional[str] = data.get('role_connections_verification_url')\n\n params = data.get('install_params')\n self.install_params: Optional[AppInstallParams] = AppInstallParams(params) if params else None\n self.interactions_endpoint_url: Optional[str] = data.get('interactions_endpoint_url')\n self.redirect_uris: List[str] = data.get('redirect_uris', [])\n self.approximate_guild_count: int = data.get('approximate_guild_count', 0)\n\n def __repr__(self) -> str:\n return (\n f'<{self.__class__.__name__} id={self.id} name={self.name!r} '\n f'description={self.description!r} public={self.bot_public} '\n f'owner={self.owner!r}>'\n )\n\n @property\n def icon(self) -> Optional[Asset]:\n \"\"\"Optional[:class:`.Asset`]: Retrieves the application's icon asset, if any.\"\"\"\n if self._icon is None:\n return None\n return Asset._from_icon(self._state, self.id, self._icon, path='app')\n\n @property\n def cover_image(self) -> Optional[Asset]:\n \"\"\"Optional[:class:`.Asset`]: Retrieves the cover image on a store embed, if any.\n\n This is only available if the application is a game sold on Discord.\n \"\"\"\n if self._cover_image is None:\n return None\n return Asset._from_cover_image(self._state, self.id, self._cover_image)\n\n @property\n def guild(self) -> Optional[Guild]:\n \"\"\"Optional[:class:`Guild`]: If this application is a game sold on Discord,\n this field will be the guild to which it has been linked\n\n .. versionadded:: 1.3\n \"\"\"\n return self._state._get_guild(self.guild_id)\n\n @property\n def flags(self) -> ApplicationFlags:\n \"\"\":class:`ApplicationFlags`: The application's flags.\n\n .. versionadded:: 2.0\n \"\"\"\n return ApplicationFlags._from_value(self._flags)\n\n async def edit(\n self,\n *,\n reason: Optional[str] = MISSING,\n custom_install_url: Optional[str] = MISSING,\n description: Optional[str] = MISSING,\n role_connections_verification_url: Optional[str] = MISSING,\n install_params_scopes: Optional[List[str]] = MISSING,\n install_params_permissions: Optional[Permissions] = MISSING,\n flags: Optional[ApplicationFlags] = MISSING,\n icon: Optional[bytes] = MISSING,\n cover_image: Optional[bytes] = MISSING,\n interactions_endpoint_url: Optional[str] = MISSING,\n tags: Optional[List[str]] = MISSING,\n ) -> AppInfo:\n r\"\"\"|coro|\n\n Edits the application info.\n\n .. versionadded:: 2.4\n\n Parameters\n ----------\n custom_install_url: Optional[:class:`str`]\n The new custom authorization URL for the application. Can be ``None`` to remove the URL.\n description: Optional[:class:`str`]\n The new application description. Can be ``None`` to remove the description.\n role_connections_verification_url: Optional[:class:`str`]\n The new application’s connection verification URL which will render the application\n as a verification method in the guild’s role verification configuration. Can be ``None`` to remove the URL.\n install_params_scopes: Optional[List[:class:`str`]]\n The new list of :ddocs:`OAuth2 scopes ` of\n the :attr:`~install_params`. Can be ``None`` to remove the scopes.\n install_params_permissions: Optional[:class:`Permissions`]\n The new permissions of the :attr:`~install_params`. Can be ``None`` to remove the permissions.\n flags: Optional[:class:`ApplicationFlags`]\n The new application’s flags. Only limited intent flags (:attr:`~ApplicationFlags.gateway_presence_limited`,\n :attr:`~ApplicationFlags.gateway_guild_members_limited`, :attr:`~ApplicationFlags.gateway_message_content_limited`)\n can be edited. Can be ``None`` to remove the flags.\n\n .. warning::\n\n Editing the limited intent flags leads to the termination of the bot.\n\n icon: Optional[:class:`bytes`]\n The new application’s icon as a :term:`py:bytes-like object`. Can be ``None`` to remove the icon.\n cover_image: Optional[:class:`bytes`]\n The new application’s cover image as a :term:`py:bytes-like object` on a store embed.\n The cover image is only available if the application is a game sold on Discord.\n Can be ``None`` to remove the image.\n interactions_endpoint_url: Optional[:class:`str`]\n The new interactions endpoint url of the application to receive interactions over this endpoint rather than\n over the gateway. Can be ``None`` to remove the URL.\n tags: Optional[List[:class:`str`]]\n The new list of tags describing the functionality of the application. Can be ``None`` to remove the tags.\n reason: Optional[:class:`str`]\n The reason for editing the application. Shows up on the audit log.\n\n Raises\n -------\n HTTPException\n Editing the application failed\n ValueError\n The image format passed in to ``icon`` or ``cover_image`` is invalid. This is also raised\n when ``install_params_scopes`` and ``install_params_permissions`` are incompatible with each other.\n\n Returns\n -------\n :class:`AppInfo`\n The newly updated application info.\n \"\"\"\n payload: Dict[str, Any] = {}\n\n if custom_install_url is not MISSING:\n payload['custom_install_url'] = custom_install_url\n\n if description is not MISSING:\n payload['description'] = description\n\n if role_connections_verification_url is not MISSING:\n payload['role_connections_verification_url'] = role_connections_verification_url\n\n if install_params_scopes is not MISSING:\n install_params: Optional[Dict[str, Any]] = {}\n if install_params_scopes is None:\n install_params = None\n else:\n if \"bot\" not in install_params_scopes and install_params_permissions is not MISSING:\n raise ValueError(\"'bot' must be in install_params_scopes if install_params_permissions is set\")\n\n install_params['scopes'] = install_params_scopes\n\n if install_params_permissions is MISSING:\n install_params['permissions'] = 0\n else:\n if install_params_permissions is None:\n install_params['permissions'] = 0\n else:\n install_params['permissions'] = install_params_permissions.value\n\n payload['install_params'] = install_params\n\n else:\n if install_params_permissions is not MISSING:\n raise ValueError(\"install_params_scopes must be set if install_params_permissions is set\")\n\n if flags is not MISSING:\n if flags is None:\n payload['flags'] = flags\n else:\n payload['flags'] = flags.value\n\n if icon is not MISSING:\n if icon is None:\n payload['icon'] = icon\n else:\n payload['icon'] = utils._bytes_to_base64_data(icon)\n\n if cover_image is not MISSING:\n if cover_image is None:\n payload['cover_image'] = cover_image\n else:\n payload['cover_image'] = utils._bytes_to_base64_data(cover_image)\n\n if interactions_endpoint_url is not MISSING:\n payload['interactions_endpoint_url'] = interactions_endpoint_url\n\n if tags is not MISSING:\n payload['tags'] = tags\n data = await self._state.http.edit_application_info(reason=reason, payload=payload)\n return AppInfo(data=data, state=self._state)\n\n\nclass PartialAppInfo:\n \"\"\"Represents a partial AppInfo given by :func:`~discord.abc.GuildChannel.create_invite`\n\n .. versionadded:: 2.0\n\n Attributes\n -------------\n id: :class:`int`\n The application ID.\n name: :class:`str`\n The application name.\n description: :class:`str`\n The application description.\n rpc_origins: Optional[List[:class:`str`]]\n A list of RPC origin URLs, if RPC is enabled.\n verify_key: :class:`str`\n The hex encoded key for verification in interactions and the\n GameSDK's :ddocs:`GetTicket `.\n terms_of_service_url: Optional[:class:`str`]\n The application's terms of service URL, if set.\n privacy_policy_url: Optional[:class:`str`]\n The application's privacy policy URL, if set.\n approximate_guild_count: :class:`int`\n The approximate count of the guilds the bot was added to.\n\n .. versionadded:: 2.3\n redirect_uris: List[:class:`str`]\n A list of authentication redirect URIs.\n\n .. versionadded:: 2.3\n interactions_endpoint_url: Optional[:class:`str`]\n The interactions endpoint url of the application to receive interactions over this endpoint rather than\n over the gateway, if configured.\n\n .. versionadded:: 2.3\n role_connections_verification_url: Optional[:class:`str`]\n The application's connection verification URL which will render the application as\n a verification method in the guild's role verification configuration.\n\n .. versionadded:: 2.3\n \"\"\"\n\n __slots__ = (\n '_state',\n 'id',\n 'name',\n 'description',\n 'rpc_origins',\n 'verify_key',\n 'terms_of_service_url',\n 'privacy_policy_url',\n '_icon',\n '_flags',\n '_cover_image',\n 'approximate_guild_count',\n 'redirect_uris',\n 'interactions_endpoint_url',\n 'role_connections_verification_url',\n )\n\n def __init__(self, *, state: ConnectionState, data: PartialAppInfoPayload):\n self._state: ConnectionState = state\n self.id: int = int(data['id'])\n self.name: str = data['name']\n self._icon: Optional[str] = data.get('icon')\n self._flags: int = data.get('flags', 0)\n self._cover_image: Optional[str] = data.get('cover_image')\n self.description: str = data['description']\n self.rpc_origins: Optional[List[str]] = data.get('rpc_origins')\n self.verify_key: str = data['verify_key']\n self.terms_of_service_url: Optional[str] = data.get('terms_of_service_url')\n self.privacy_policy_url: Optional[str] = data.get('privacy_policy_url')\n self.approximate_guild_count: int = data.get('approximate_guild_count', 0)\n self.redirect_uris: List[str] = data.get('redirect_uris', [])\n self.interactions_endpoint_url: Optional[str] = data.get('interactions_endpoint_url')\n self.role_connections_verification_url: Optional[str] = data.get('role_connections_verification_url')\n\n def __repr__(self) -> str:\n return f'<{self.__class__.__name__} id={self.id} name={self.name!r} description={self.description!r}>'\n\n @property\n def icon(self) -> Optional[Asset]:\n \"\"\"Optional[:class:`.Asset`]: Retrieves the application's icon asset, if any.\"\"\"\n if self._icon is None:\n return None\n return Asset._from_icon(self._state, self.id, self._icon, path='app')\n\n @property\n def cover_image(self) -> Optional[Asset]:\n \"\"\"Optional[:class:`.Asset`]: Retrieves the cover image of the application's default rich presence.\n\n This is only available if the application is a game sold on Discord.\n\n .. versionadded:: 2.3\n \"\"\"\n if self._cover_image is None:\n return None\n return Asset._from_cover_image(self._state, self.id, self._cover_image)\n\n @property\n def flags(self) -> ApplicationFlags:\n \"\"\":class:`ApplicationFlags`: The application's flags.\n\n .. versionadded:: 2.0\n \"\"\"\n return ApplicationFlags._from_value(self._flags)\n\n\nclass AppInstallParams:\n \"\"\"Represents the settings for custom authorization URL of an application.\n\n .. versionadded:: 2.0\n\n Attributes\n ----------\n scopes: List[:class:`str`]\n The list of :ddocs:`OAuth2 scopes `\n to add the application to a guild with.\n permissions: :class:`Permissions`\n The permissions to give to application in the guild.\n \"\"\"\n\n __slots__ = ('scopes', 'permissions')\n\n def __init__(self, data: InstallParamsPayload) -> None:\n self.scopes: List[str] = data.get('scopes', [])\n self.permissions: Permissions = Permissions(int(data['permissions']))\n" }, { "path": "discord/asset.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport io\nimport os\nfrom typing import Any, Literal, Optional, TYPE_CHECKING, Tuple, Union\nfrom .errors import DiscordException\nfrom . import utils\nfrom .file import File\n\nimport yarl\n\n# fmt: off\n__all__ = (\n 'Asset',\n)\n# fmt: on\n\nif TYPE_CHECKING:\n from typing_extensions import Self\n\n from .state import ConnectionState\n from .webhook.async_ import _WebhookState\n\n _State = Union[ConnectionState, _WebhookState]\n\n ValidStaticFormatTypes = Literal['webp', 'jpeg', 'jpg', 'png']\n ValidAssetFormatTypes = Literal['webp', 'jpeg', 'jpg', 'png', 'gif']\n\nVALID_STATIC_FORMATS = frozenset({\"jpeg\", \"jpg\", \"webp\", \"png\"})\nVALID_ASSET_FORMATS = VALID_STATIC_FORMATS | {\"gif\"}\n\n\nMISSING = utils.MISSING\n\n\nclass AssetMixin:\n __slots__ = ()\n url: str\n _state: Optional[Any]\n\n async def read(self) -> bytes:\n \"\"\"|coro|\n\n Retrieves the content of this asset as a :class:`bytes` object.\n\n Raises\n ------\n DiscordException\n There was no internal connection state.\n HTTPException\n Downloading the asset failed.\n NotFound\n The asset was deleted.\n\n Returns\n -------\n :class:`bytes`\n The content of the asset.\n \"\"\"\n if self._state is None:\n raise DiscordException('Invalid state (no ConnectionState provided)')\n\n return await self._state.http.get_from_cdn(self.url)\n\n async def save(self, fp: Union[str, bytes, os.PathLike[Any], io.BufferedIOBase], *, seek_begin: bool = True) -> int:\n \"\"\"|coro|\n\n Saves this asset into a file-like object.\n\n Parameters\n ----------\n fp: Union[:class:`io.BufferedIOBase`, :class:`os.PathLike`]\n The file-like object to save this asset to or the filename\n to use. If a filename is passed then a file is created with that\n filename and used instead.\n seek_begin: :class:`bool`\n Whether to seek to the beginning of the file after saving is\n successfully done.\n\n Raises\n ------\n DiscordException\n There was no internal connection state.\n HTTPException\n Downloading the asset failed.\n NotFound\n The asset was deleted.\n\n Returns\n --------\n :class:`int`\n The number of bytes written.\n \"\"\"\n\n data = await self.read()\n if isinstance(fp, io.BufferedIOBase):\n written = fp.write(data)\n if seek_begin:\n fp.seek(0)\n return written\n else:\n with open(fp, 'wb') as f:\n return f.write(data)\n\n async def to_file(\n self,\n *,\n filename: Optional[str] = MISSING,\n description: Optional[str] = None,\n spoiler: bool = False,\n ) -> File:\n \"\"\"|coro|\n\n Converts the asset into a :class:`File` suitable for sending via\n :meth:`abc.Messageable.send`.\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n filename: Optional[:class:`str`]\n The filename of the file. If not provided, then the filename from\n the asset's URL is used.\n description: Optional[:class:`str`]\n The description for the file.\n spoiler: :class:`bool`\n Whether the file is a spoiler.\n\n Raises\n ------\n DiscordException\n The asset does not have an associated state.\n ValueError\n The asset is a unicode emoji.\n TypeError\n The asset is a sticker with lottie type.\n HTTPException\n Downloading the asset failed.\n NotFound\n The asset was deleted.\n\n Returns\n -------\n :class:`File`\n The asset as a file suitable for sending.\n \"\"\"\n\n data = await self.read()\n file_filename = filename if filename is not MISSING else yarl.URL(self.url).name\n return File(io.BytesIO(data), filename=file_filename, description=description, spoiler=spoiler)\n\n\nclass Asset(AssetMixin):\n \"\"\"Represents a CDN asset on Discord.\n\n .. container:: operations\n\n .. describe:: str(x)\n\n Returns the URL of the CDN asset.\n\n .. describe:: len(x)\n\n Returns the length of the CDN asset's URL.\n\n .. describe:: x == y\n\n Checks if the asset is equal to another asset.\n\n .. describe:: x != y\n\n Checks if the asset is not equal to another asset.\n\n .. describe:: hash(x)\n\n Returns the hash of the asset.\n \"\"\"\n\n __slots__: Tuple[str, ...] = (\n '_state',\n '_url',\n '_animated',\n '_key',\n )\n\n BASE = 'https://cdn.discordapp.com'\n\n def __init__(self, state: _State, *, url: str, key: str, animated: bool = False) -> None:\n self._state: _State = state\n self._url: str = url\n self._animated: bool = animated\n self._key: str = key\n\n @classmethod\n def _from_default_avatar(cls, state: _State, index: int) -> Self:\n return cls(\n state,\n url=f'{cls.BASE}/embed/avatars/{index}.png',\n key=str(index),\n animated=False,\n )\n\n @classmethod\n def _from_avatar(cls, state: _State, user_id: int, avatar: str) -> Self:\n animated = avatar.startswith('a_')\n format = 'gif' if animated else 'png'\n return cls(\n state,\n url=f'{cls.BASE}/avatars/{user_id}/{avatar}.{format}?size=1024',\n key=avatar,\n animated=animated,\n )\n\n @classmethod\n def _from_guild_avatar(cls, state: _State, guild_id: int, member_id: int, avatar: str) -> Self:\n animated = avatar.startswith('a_')\n format = 'gif' if animated else 'png'\n return cls(\n state,\n url=f\"{cls.BASE}/guilds/{guild_id}/users/{member_id}/avatars/{avatar}.{format}?size=1024\",\n key=avatar,\n animated=animated,\n )\n\n @classmethod\n def _from_guild_banner(cls, state: _State, guild_id: int, member_id: int, banner: str) -> Self:\n animated = banner.startswith('a_')\n format = 'gif' if animated else 'png'\n return cls(\n state,\n url=f\"{cls.BASE}/guilds/{guild_id}/users/{member_id}/banners/{banner}.{format}?size=1024\",\n key=banner,\n animated=animated,\n )\n\n @classmethod\n def _from_avatar_decoration(cls, state: _State, avatar_decoration: str) -> Self:\n return cls(\n state,\n url=f'{cls.BASE}/avatar-decoration-presets/{avatar_decoration}.png?size=96',\n key=avatar_decoration,\n animated=True,\n )\n\n @classmethod\n def _from_icon(cls, state: _State, object_id: int, icon_hash: str, path: str) -> Self:\n return cls(\n state,\n url=f'{cls.BASE}/{path}-icons/{object_id}/{icon_hash}.png?size=1024',\n key=icon_hash,\n animated=False,\n )\n\n @classmethod\n def _from_app_icon(\n cls, state: _State, object_id: int, icon_hash: str, asset_type: Literal['icon', 'cover_image']\n ) -> Self:\n return cls(\n state,\n url=f'{cls.BASE}/app-icons/{object_id}/{asset_type}.png?size=1024',\n key=icon_hash,\n animated=False,\n )\n\n @classmethod\n def _from_cover_image(cls, state: _State, object_id: int, cover_image_hash: str) -> Self:\n return cls(\n state,\n url=f'{cls.BASE}/app-assets/{object_id}/store/{cover_image_hash}.png?size=1024',\n key=cover_image_hash,\n animated=False,\n )\n\n @classmethod\n def _from_scheduled_event_cover_image(cls, state: _State, scheduled_event_id: int, cover_image_hash: str) -> Self:\n return cls(\n state,\n url=f'{cls.BASE}/guild-events/{scheduled_event_id}/{cover_image_hash}.png?size=1024',\n key=cover_image_hash,\n animated=False,\n )\n\n @classmethod\n def _from_guild_image(cls, state: _State, guild_id: int, image: str, path: str) -> Self:\n animated = image.startswith('a_')\n format = 'gif' if animated else 'png'\n return cls(\n state,\n url=f'{cls.BASE}/{path}/{guild_id}/{image}.{format}?size=1024',\n key=image,\n animated=animated,\n )\n\n @classmethod\n def _from_guild_icon(cls, state: _State, guild_id: int, icon_hash: str) -> Self:\n animated = icon_hash.startswith('a_')\n format = 'gif' if animated else 'png'\n return cls(\n state,\n url=f'{cls.BASE}/icons/{guild_id}/{icon_hash}.{format}?size=1024',\n key=icon_hash,\n animated=animated,\n )\n\n @classmethod\n def _from_sticker_banner(cls, state: _State, banner: int) -> Self:\n return cls(\n state,\n url=f'{cls.BASE}/app-assets/710982414301790216/store/{banner}.png',\n key=str(banner),\n animated=False,\n )\n\n @classmethod\n def _from_user_banner(cls, state: _State, user_id: int, banner_hash: str) -> Self:\n animated = banner_hash.startswith('a_')\n format = 'gif' if animated else 'png'\n return cls(\n state,\n url=f'{cls.BASE}/banners/{user_id}/{banner_hash}.{format}?size=512',\n key=banner_hash,\n animated=animated,\n )\n\n def __str__(self) -> str:\n return self._url\n\n def __len__(self) -> int:\n return len(self._url)\n\n def __repr__(self) -> str:\n shorten = self._url.replace(self.BASE, '')\n return f''\n\n def __eq__(self, other: object) -> bool:\n return isinstance(other, Asset) and self._url == other._url\n\n def __hash__(self) -> int:\n return hash(self._url)\n\n @property\n def url(self) -> str:\n \"\"\":class:`str`: Returns the underlying URL of the asset.\"\"\"\n return self._url\n\n @property\n def key(self) -> str:\n \"\"\":class:`str`: Returns the identifying key of the asset.\"\"\"\n return self._key\n\n def is_animated(self) -> bool:\n \"\"\":class:`bool`: Returns whether the asset is animated.\"\"\"\n return self._animated\n\n def replace(\n self,\n *,\n size: int = MISSING,\n format: ValidAssetFormatTypes = MISSING,\n static_format: ValidStaticFormatTypes = MISSING,\n ) -> Self:\n \"\"\"Returns a new asset with the passed components replaced.\n\n\n .. versionchanged:: 2.0\n ``static_format`` is now preferred over ``format``\n if both are present and the asset is not animated.\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`ValueError` instead of\n ``InvalidArgument``.\n\n Parameters\n -----------\n size: :class:`int`\n The new size of the asset.\n format: :class:`str`\n The new format to change it to. Must be either\n 'webp', 'jpeg', 'jpg', 'png', or 'gif' if it's animated.\n static_format: :class:`str`\n The new format to change it to if the asset isn't animated.\n Must be either 'webp', 'jpeg', 'jpg', or 'png'.\n\n Raises\n -------\n ValueError\n An invalid size or format was passed.\n\n Returns\n --------\n :class:`Asset`\n The newly updated asset.\n \"\"\"\n url = yarl.URL(self._url)\n path, _ = os.path.splitext(url.path)\n\n if format is not MISSING:\n if self._animated:\n if format not in VALID_ASSET_FORMATS:\n raise ValueError(f'format must be one of {VALID_ASSET_FORMATS}')\n else:\n if static_format is MISSING and format not in VALID_STATIC_FORMATS:\n raise ValueError(f'format must be one of {VALID_STATIC_FORMATS}')\n url = url.with_path(f'{path}.{format}')\n\n if static_format is not MISSING and not self._animated:\n if static_format not in VALID_STATIC_FORMATS:\n raise ValueError(f'static_format must be one of {VALID_STATIC_FORMATS}')\n url = url.with_path(f'{path}.{static_format}')\n\n if size is not MISSING:\n if not utils.valid_icon_size(size):\n raise ValueError('size must be a power of 2 between 16 and 4096')\n url = url.with_query(size=size)\n else:\n url = url.with_query(url.raw_query_string)\n\n url = str(url)\n return self.__class__(state=self._state, url=url, key=self._key, animated=self._animated)\n\n def with_size(self, size: int, /) -> Self:\n \"\"\"Returns a new asset with the specified size.\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`ValueError` instead of\n ``InvalidArgument``.\n\n Parameters\n ------------\n size: :class:`int`\n The new size of the asset.\n\n Raises\n -------\n ValueError\n The asset had an invalid size.\n\n Returns\n --------\n :class:`Asset`\n The new updated asset.\n \"\"\"\n if not utils.valid_icon_size(size):\n raise ValueError('size must be a power of 2 between 16 and 4096')\n\n url = str(yarl.URL(self._url).with_query(size=size))\n return self.__class__(state=self._state, url=url, key=self._key, animated=self._animated)\n\n def with_format(self, format: ValidAssetFormatTypes, /) -> Self:\n \"\"\"Returns a new asset with the specified format.\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`ValueError` instead of\n ``InvalidArgument``.\n\n Parameters\n ------------\n format: :class:`str`\n The new format of the asset.\n\n Raises\n -------\n ValueError\n The asset had an invalid format.\n\n Returns\n --------\n :class:`Asset`\n The new updated asset.\n \"\"\"\n\n if self._animated:\n if format not in VALID_ASSET_FORMATS:\n raise ValueError(f'format must be one of {VALID_ASSET_FORMATS}')\n else:\n if format not in VALID_STATIC_FORMATS:\n raise ValueError(f'format must be one of {VALID_STATIC_FORMATS}')\n\n url = yarl.URL(self._url)\n path, _ = os.path.splitext(url.path)\n url = str(url.with_path(f'{path}.{format}').with_query(url.raw_query_string))\n return self.__class__(state=self._state, url=url, key=self._key, animated=self._animated)\n\n def with_static_format(self, format: ValidStaticFormatTypes, /) -> Self:\n \"\"\"Returns a new asset with the specified static format.\n\n This only changes the format if the underlying asset is\n not animated. Otherwise, the asset is not changed.\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`ValueError` instead of\n ``InvalidArgument``.\n\n Parameters\n ------------\n format: :class:`str`\n The new static format of the asset.\n\n Raises\n -------\n ValueError\n The asset had an invalid format.\n\n Returns\n --------\n :class:`Asset`\n The new updated asset.\n \"\"\"\n\n if self._animated:\n return self\n return self.with_format(format)\n" }, { "path": "discord/audit_logs.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import TYPE_CHECKING, Any, Callable, ClassVar, Mapping, Generator, List, Optional, Tuple, Type, TypeVar, Union\n\nfrom . import enums, flags, utils\nfrom .asset import Asset\nfrom .colour import Colour\nfrom .invite import Invite\nfrom .mixins import Hashable\nfrom .object import Object\nfrom .permissions import PermissionOverwrite, Permissions\nfrom .automod import AutoModTrigger, AutoModRuleAction, AutoModRule\nfrom .role import Role\nfrom .emoji import Emoji\nfrom .partial_emoji import PartialEmoji\nfrom .member import Member\nfrom .scheduled_event import ScheduledEvent\nfrom .stage_instance import StageInstance\nfrom .sticker import GuildSticker\nfrom .threads import Thread\nfrom .integrations import PartialIntegration\nfrom .channel import ForumChannel, StageChannel, ForumTag\n\n__all__ = (\n 'AuditLogDiff',\n 'AuditLogChanges',\n 'AuditLogEntry',\n)\n\n\nif TYPE_CHECKING:\n import datetime\n\n from . import abc\n from .guild import Guild\n from .state import ConnectionState\n from .types.audit_log import (\n AuditLogChange as AuditLogChangePayload,\n AuditLogEntry as AuditLogEntryPayload,\n _AuditLogChange_TriggerMetadata as AuditLogChangeTriggerMetadataPayload,\n )\n from .types.channel import (\n PermissionOverwrite as PermissionOverwritePayload,\n ForumTag as ForumTagPayload,\n DefaultReaction as DefaultReactionPayload,\n )\n from .types.invite import Invite as InvitePayload\n from .types.role import Role as RolePayload\n from .types.snowflake import Snowflake\n from .types.command import ApplicationCommandPermissions\n from .types.automod import AutoModerationAction\n from .user import User\n from .app_commands import AppCommand\n from .webhook import Webhook\n\n TargetType = Union[\n Guild,\n abc.GuildChannel,\n Member,\n User,\n Role,\n Invite,\n Emoji,\n StageInstance,\n GuildSticker,\n Thread,\n Object,\n PartialIntegration,\n AutoModRule,\n ScheduledEvent,\n Webhook,\n AppCommand,\n None,\n ]\n\n\ndef _transform_timestamp(entry: AuditLogEntry, data: Optional[str]) -> Optional[datetime.datetime]:\n return utils.parse_time(data)\n\n\ndef _transform_color(entry: AuditLogEntry, data: int) -> Colour:\n return Colour(data)\n\n\ndef _transform_snowflake(entry: AuditLogEntry, data: Snowflake) -> int:\n return int(data)\n\n\ndef _transform_channel(entry: AuditLogEntry, data: Optional[Snowflake]) -> Optional[Union[abc.GuildChannel, Object]]:\n if data is None:\n return None\n return entry.guild.get_channel(int(data)) or Object(id=data)\n\n\ndef _transform_channels_or_threads(\n entry: AuditLogEntry, data: List[Snowflake]\n) -> List[Union[abc.GuildChannel, Thread, Object]]:\n return [entry.guild.get_channel_or_thread(int(data)) or Object(id=data) for data in data]\n\n\ndef _transform_member_id(entry: AuditLogEntry, data: Optional[Snowflake]) -> Union[Member, User, None]:\n if data is None:\n return None\n return entry._get_member(int(data))\n\n\ndef _transform_guild_id(entry: AuditLogEntry, data: Optional[Snowflake]) -> Optional[Guild]:\n if data is None:\n return None\n return entry._state._get_guild(int(data))\n\n\ndef _transform_roles(entry: AuditLogEntry, data: List[Snowflake]) -> List[Union[Role, Object]]:\n return [entry.guild.get_role(int(role_id)) or Object(role_id, type=Role) for role_id in data]\n\n\ndef _transform_applied_forum_tags(entry: AuditLogEntry, data: List[Snowflake]) -> List[Union[ForumTag, Object]]:\n thread = entry.target\n if isinstance(thread, Thread) and isinstance(thread.parent, ForumChannel):\n return [thread.parent.get_tag(tag_id) or Object(id=tag_id, type=ForumTag) for tag_id in map(int, data)]\n return [Object(id=tag_id, type=ForumTag) for tag_id in data]\n\n\ndef _transform_overloaded_flags(entry: AuditLogEntry, data: int) -> Union[int, flags.ChannelFlags]:\n # The `flags` key is definitely overloaded. Right now it's for channels and threads but\n # I am aware of `member.flags` and `user.flags` existing. However, this does not impact audit logs\n # at the moment but better safe than sorry.\n channel_audit_log_types = (\n enums.AuditLogAction.channel_create,\n enums.AuditLogAction.channel_update,\n enums.AuditLogAction.channel_delete,\n enums.AuditLogAction.thread_create,\n enums.AuditLogAction.thread_update,\n enums.AuditLogAction.thread_delete,\n )\n\n if entry.action in channel_audit_log_types:\n return flags.ChannelFlags._from_value(data)\n return data\n\n\ndef _transform_forum_tags(entry: AuditLogEntry, data: List[ForumTagPayload]) -> List[ForumTag]:\n return [ForumTag.from_data(state=entry._state, data=d) for d in data]\n\n\ndef _transform_default_reaction(entry: AuditLogEntry, data: DefaultReactionPayload) -> Optional[PartialEmoji]:\n if data is None:\n return None\n\n emoji_name = data.get('emoji_name') or ''\n emoji_id = utils._get_as_snowflake(data, 'emoji_id') or None # Coerce 0 -> None\n return PartialEmoji.with_state(state=entry._state, name=emoji_name, id=emoji_id)\n\n\ndef _transform_overwrites(\n entry: AuditLogEntry, data: List[PermissionOverwritePayload]\n) -> List[Tuple[Object, PermissionOverwrite]]:\n overwrites = []\n for elem in data:\n allow = Permissions(int(elem['allow']))\n deny = Permissions(int(elem['deny']))\n ow = PermissionOverwrite.from_pair(allow, deny)\n\n ow_type = elem['type']\n ow_id = int(elem['id'])\n target = None\n if ow_type == '0':\n target = entry.guild.get_role(ow_id)\n elif ow_type == '1':\n target = entry._get_member(ow_id)\n\n if target is None:\n target = Object(id=ow_id, type=Role if ow_type == '0' else Member)\n\n overwrites.append((target, ow))\n\n return overwrites\n\n\ndef _transform_icon(entry: AuditLogEntry, data: Optional[str]) -> Optional[Asset]:\n if data is None:\n return None\n if entry.action is enums.AuditLogAction.guild_update:\n return Asset._from_guild_icon(entry._state, entry.guild.id, data)\n else:\n return Asset._from_icon(entry._state, entry._target_id, data, path='role') # type: ignore # target_id won't be None in this case\n\n\ndef _transform_avatar(entry: AuditLogEntry, data: Optional[str]) -> Optional[Asset]:\n if data is None:\n return None\n return Asset._from_avatar(entry._state, entry._target_id, data) # type: ignore # target_id won't be None in this case\n\n\ndef _transform_cover_image(entry: AuditLogEntry, data: Optional[str]) -> Optional[Asset]:\n if data is None:\n return None\n return Asset._from_scheduled_event_cover_image(entry._state, entry._target_id, data) # type: ignore # target_id won't be None in this case\n\n\ndef _guild_hash_transformer(path: str) -> Callable[[AuditLogEntry, Optional[str]], Optional[Asset]]:\n def _transform(entry: AuditLogEntry, data: Optional[str]) -> Optional[Asset]:\n if data is None:\n return None\n return Asset._from_guild_image(entry._state, entry.guild.id, data, path=path)\n\n return _transform\n\n\ndef _transform_automod_actions(entry: AuditLogEntry, data: List[AutoModerationAction]) -> List[AutoModRuleAction]:\n return [AutoModRuleAction.from_data(action) for action in data]\n\n\nE = TypeVar('E', bound=enums.Enum)\n\n\ndef _enum_transformer(enum: Type[E]) -> Callable[[AuditLogEntry, int], E]:\n def _transform(entry: AuditLogEntry, data: int) -> E:\n return enums.try_enum(enum, data)\n\n return _transform\n\n\nF = TypeVar('F', bound=flags.BaseFlags)\n\n\ndef _flag_transformer(cls: Type[F]) -> Callable[[AuditLogEntry, Union[int, str]], F]:\n def _transform(entry: AuditLogEntry, data: Union[int, str]) -> F:\n return cls._from_value(int(data))\n\n return _transform\n\n\ndef _transform_type(\n entry: AuditLogEntry, data: Union[int, str]\n) -> Union[enums.ChannelType, enums.StickerType, enums.WebhookType, str]:\n if entry.action.name.startswith('sticker_'):\n return enums.try_enum(enums.StickerType, data)\n elif entry.action.name.startswith('integration_'):\n return data # type: ignore # integration type is str\n elif entry.action.name.startswith('webhook_'):\n return enums.try_enum(enums.WebhookType, data)\n else:\n return enums.try_enum(enums.ChannelType, data)\n\n\nclass AuditLogDiff:\n def __len__(self) -> int:\n return len(self.__dict__)\n\n def __iter__(self) -> Generator[Tuple[str, Any], None, None]:\n yield from self.__dict__.items()\n\n def __repr__(self) -> str:\n values = ' '.join('%s=%r' % item for item in self.__dict__.items())\n return f''\n\n if TYPE_CHECKING:\n\n def __getattr__(self, item: str) -> Any:\n ...\n\n def __setattr__(self, key: str, value: Any) -> Any:\n ...\n\n\nTransformer = Callable[[\"AuditLogEntry\", Any], Any]\n\n\nclass AuditLogChanges:\n # fmt: off\n TRANSFORMERS: ClassVar[Mapping[str, Tuple[Optional[str], Optional[Transformer]]]] = {\n 'verification_level': (None, _enum_transformer(enums.VerificationLevel)),\n 'explicit_content_filter': (None, _enum_transformer(enums.ContentFilter)),\n 'allow': (None, _flag_transformer(Permissions)),\n 'deny': (None, _flag_transformer(Permissions)),\n 'permissions': (None, _flag_transformer(Permissions)),\n 'id': (None, _transform_snowflake),\n 'color': ('colour', _transform_color),\n 'owner_id': ('owner', _transform_member_id),\n 'inviter_id': ('inviter', _transform_member_id),\n 'channel_id': ('channel', _transform_channel),\n 'afk_channel_id': ('afk_channel', _transform_channel),\n 'system_channel_id': ('system_channel', _transform_channel),\n 'system_channel_flags': (None, _flag_transformer(flags.SystemChannelFlags)),\n 'widget_channel_id': ('widget_channel', _transform_channel),\n 'rules_channel_id': ('rules_channel', _transform_channel),\n 'public_updates_channel_id': ('public_updates_channel', _transform_channel),\n 'permission_overwrites': ('overwrites', _transform_overwrites),\n 'splash_hash': ('splash', _guild_hash_transformer('splashes')),\n 'banner_hash': ('banner', _guild_hash_transformer('banners')),\n 'discovery_splash_hash': ('discovery_splash', _guild_hash_transformer('discovery-splashes')),\n 'icon_hash': ('icon', _transform_icon),\n 'avatar_hash': ('avatar', _transform_avatar),\n 'rate_limit_per_user': ('slowmode_delay', None),\n 'default_thread_rate_limit_per_user': ('default_thread_slowmode_delay', None),\n 'guild_id': ('guild', _transform_guild_id),\n 'tags': ('emoji', None),\n 'default_message_notifications': ('default_notifications', _enum_transformer(enums.NotificationLevel)),\n 'video_quality_mode': (None, _enum_transformer(enums.VideoQualityMode)),\n 'privacy_level': (None, _enum_transformer(enums.PrivacyLevel)),\n 'format_type': (None, _enum_transformer(enums.StickerFormatType)),\n 'type': (None, _transform_type),\n 'communication_disabled_until': ('timed_out_until', _transform_timestamp),\n 'expire_behavior': (None, _enum_transformer(enums.ExpireBehaviour)),\n 'mfa_level': (None, _enum_transformer(enums.MFALevel)),\n 'status': (None, _enum_transformer(enums.EventStatus)),\n 'entity_type': (None, _enum_transformer(enums.EntityType)),\n 'preferred_locale': (None, _enum_transformer(enums.Locale)),\n 'image_hash': ('cover_image', _transform_cover_image),\n 'trigger_type': (None, _enum_transformer(enums.AutoModRuleTriggerType)),\n 'event_type': (None, _enum_transformer(enums.AutoModRuleEventType)),\n 'actions': (None, _transform_automod_actions),\n 'exempt_channels': (None, _transform_channels_or_threads),\n 'exempt_roles': (None, _transform_roles),\n 'applied_tags': (None, _transform_applied_forum_tags),\n 'available_tags': (None, _transform_forum_tags),\n 'flags': (None, _transform_overloaded_flags),\n 'default_reaction_emoji': (None, _transform_default_reaction),\n }\n # fmt: on\n\n def __init__(self, entry: AuditLogEntry, data: List[AuditLogChangePayload]):\n self.before: AuditLogDiff = AuditLogDiff()\n self.after: AuditLogDiff = AuditLogDiff()\n # special case entire process since each\n # element in data is a different target\n # key is the target id\n if entry.action is enums.AuditLogAction.app_command_permission_update:\n self.before.app_command_permissions = []\n self.after.app_command_permissions = []\n\n for elem in data:\n self._handle_app_command_permissions(\n self.before,\n entry,\n elem.get('old_value'), # type: ignore # value will be an ApplicationCommandPermissions if present\n )\n\n self._handle_app_command_permissions(\n self.after,\n entry,\n elem.get('new_value'), # type: ignore # value will be an ApplicationCommandPermissions if present\n )\n return\n\n for elem in data:\n attr = elem['key']\n\n # special cases for role add/remove\n if attr == '$add':\n self._handle_role(self.before, self.after, entry, elem['new_value']) # type: ignore # new_value is a list of roles in this case\n continue\n elif attr == '$remove':\n self._handle_role(self.after, self.before, entry, elem['new_value']) # type: ignore # new_value is a list of roles in this case\n continue\n\n # special case for automod trigger\n if attr == 'trigger_metadata':\n # given full metadata dict\n self._handle_trigger_metadata(entry, elem, data) # type: ignore # should be trigger metadata\n continue\n elif entry.action is enums.AuditLogAction.automod_rule_update and attr.startswith('$'):\n # on update, some trigger attributes are keys and formatted as $(add/remove)_{attribute}\n action, _, trigger_attr = attr.partition('_')\n # new_value should be a list of added/removed strings for keyword_filter, regex_patterns, or allow_list\n if action == '$add':\n self._handle_trigger_attr_update(self.before, self.after, entry, trigger_attr, elem['new_value']) # type: ignore\n elif action == '$remove':\n self._handle_trigger_attr_update(self.after, self.before, entry, trigger_attr, elem['new_value']) # type: ignore\n continue\n\n try:\n key, transformer = self.TRANSFORMERS[attr]\n except (ValueError, KeyError):\n transformer = None\n else:\n if key:\n attr = key\n\n transformer: Optional[Transformer]\n\n try:\n before = elem['old_value']\n except KeyError:\n before = None\n else:\n if transformer:\n before = transformer(entry, before)\n\n setattr(self.before, attr, before)\n\n try:\n after = elem['new_value']\n except KeyError:\n after = None\n else:\n if transformer:\n after = transformer(entry, after)\n\n setattr(self.after, attr, after)\n\n # add an alias\n if hasattr(self.after, 'colour'):\n self.after.color = self.after.colour\n self.before.color = self.before.colour\n if hasattr(self.after, 'expire_behavior'):\n self.after.expire_behaviour = self.after.expire_behavior\n self.before.expire_behaviour = self.before.expire_behavior\n\n def __repr__(self) -> str:\n return f''\n\n def _handle_role(self, first: AuditLogDiff, second: AuditLogDiff, entry: AuditLogEntry, elem: List[RolePayload]) -> None:\n if not hasattr(first, 'roles'):\n setattr(first, 'roles', [])\n\n data = []\n g: Guild = entry.guild\n\n for e in elem:\n role_id = int(e['id'])\n role = g.get_role(role_id)\n\n if role is None:\n role = Object(id=role_id, type=Role)\n role.name = e['name'] # type: ignore # Object doesn't usually have name\n\n data.append(role)\n\n setattr(second, 'roles', data)\n\n def _handle_app_command_permissions(\n self,\n diff: AuditLogDiff,\n entry: AuditLogEntry,\n data: Optional[ApplicationCommandPermissions],\n ):\n if data is None:\n return\n\n # avoid circular import\n from discord.app_commands import AppCommandPermissions\n\n state = entry._state\n guild = entry.guild\n diff.app_command_permissions.append(AppCommandPermissions(data=data, guild=guild, state=state))\n\n def _handle_trigger_metadata(\n self,\n entry: AuditLogEntry,\n data: AuditLogChangeTriggerMetadataPayload,\n full_data: List[AuditLogChangePayload],\n ):\n trigger_value: Optional[int] = None\n trigger_type: Optional[enums.AutoModRuleTriggerType] = None\n\n # try to get trigger type from before or after\n trigger_type = getattr(self.before, 'trigger_type', getattr(self.after, 'trigger_type', None))\n\n if trigger_type is None:\n if isinstance(entry.target, AutoModRule):\n # Trigger type cannot be changed, so it should be the same before and after updates.\n # Avoids checking which keys are in data to guess trigger type\n trigger_value = entry.target.trigger.type.value\n else:\n # found a trigger type from before or after\n trigger_value = trigger_type.value\n\n if trigger_value is None:\n # try to find trigger type in the full list of changes\n _elem = utils.find(lambda elem: elem['key'] == 'trigger_type', full_data)\n if _elem is not None:\n trigger_value = _elem.get('old_value', _elem.get('new_value')) # type: ignore # trigger type values should be int\n\n if trigger_value is None:\n # try to infer trigger_type from the keys in old or new value\n combined = (data.get('old_value') or {}).keys() | (data.get('new_value') or {}).keys()\n if not combined:\n trigger_value = enums.AutoModRuleTriggerType.spam.value\n elif 'presets' in combined:\n trigger_value = enums.AutoModRuleTriggerType.keyword_preset.value\n elif 'keyword_filter' in combined or 'regex_patterns' in combined:\n trigger_value = enums.AutoModRuleTriggerType.keyword.value\n elif 'mention_total_limit' in combined or 'mention_raid_protection_enabled' in combined:\n trigger_value = enums.AutoModRuleTriggerType.mention_spam.value\n else:\n # some unknown type\n trigger_value = -1\n\n self.before.trigger = AutoModTrigger.from_data(trigger_value, data.get('old_value'))\n self.after.trigger = AutoModTrigger.from_data(trigger_value, data.get('new_value'))\n\n def _handle_trigger_attr_update(\n self, first: AuditLogDiff, second: AuditLogDiff, entry: AuditLogEntry, attr: str, data: List[str]\n ):\n self._create_trigger(first, entry)\n trigger = self._create_trigger(second, entry)\n try:\n # guard unexpecte non list attributes or non iterable data\n getattr(trigger, attr).extend(data)\n except (AttributeError, TypeError):\n pass\n\n def _create_trigger(self, diff: AuditLogDiff, entry: AuditLogEntry) -> AutoModTrigger:\n # check if trigger has already been created\n if not hasattr(diff, 'trigger'):\n # create a trigger\n if isinstance(entry.target, AutoModRule):\n # get trigger type from the automod rule\n trigger_type = entry.target.trigger.type\n else:\n # unknown trigger type\n trigger_type = enums.try_enum(enums.AutoModRuleTriggerType, -1)\n\n diff.trigger = AutoModTrigger(type=trigger_type)\n return diff.trigger\n\n\nclass _AuditLogProxy:\n def __init__(self, **kwargs: Any) -> None:\n for k, v in kwargs.items():\n setattr(self, k, v)\n\n\nclass _AuditLogProxyMemberPrune(_AuditLogProxy):\n delete_member_days: int\n members_removed: int\n\n\nclass _AuditLogProxyMemberMoveOrMessageDelete(_AuditLogProxy):\n channel: Union[abc.GuildChannel, Thread]\n count: int\n\n\nclass _AuditLogProxyMemberDisconnect(_AuditLogProxy):\n count: int\n\n\nclass _AuditLogProxyPinAction(_AuditLogProxy):\n channel: Union[abc.GuildChannel, Thread]\n message_id: int\n\n\nclass _AuditLogProxyStageInstanceAction(_AuditLogProxy):\n channel: abc.GuildChannel\n\n\nclass _AuditLogProxyMessageBulkDelete(_AuditLogProxy):\n count: int\n\n\nclass _AuditLogProxyAutoModAction(_AuditLogProxy):\n automod_rule_name: str\n automod_rule_trigger_type: str\n channel: Optional[Union[abc.GuildChannel, Thread]]\n\n\nclass _AuditLogProxyMemberKickOrMemberRoleUpdate(_AuditLogProxy):\n integration_type: Optional[str]\n\n\nclass AuditLogEntry(Hashable):\n r\"\"\"Represents an Audit Log entry.\n\n You retrieve these via :meth:`Guild.audit_logs`.\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two entries are equal.\n\n .. describe:: x != y\n\n Checks if two entries are not equal.\n\n .. describe:: hash(x)\n\n Returns the entry's hash.\n\n .. versionchanged:: 1.7\n Audit log entries are now comparable and hashable.\n\n Attributes\n -----------\n action: :class:`AuditLogAction`\n The action that was done.\n user: Optional[:class:`abc.User`]\n The user who initiated this action. Usually a :class:`Member`\\, unless gone\n then it's a :class:`User`.\n user_id: Optional[:class:`int`]\n The user ID who initiated this action.\n\n .. versionadded:: 2.2\n id: :class:`int`\n The entry ID.\n guild: :class:`Guild`\n The guild that this entry belongs to.\n target: Any\n The target that got changed. The exact type of this depends on\n the action being done.\n reason: Optional[:class:`str`]\n The reason this action was done.\n extra: Any\n Extra information that this entry has that might be useful.\n For most actions, this is ``None``. However in some cases it\n contains extra information. See :class:`AuditLogAction` for\n which actions have this field filled out.\n \"\"\"\n\n def __init__(\n self,\n *,\n users: Mapping[int, User],\n integrations: Mapping[int, PartialIntegration],\n app_commands: Mapping[int, AppCommand],\n automod_rules: Mapping[int, AutoModRule],\n webhooks: Mapping[int, Webhook],\n data: AuditLogEntryPayload,\n guild: Guild,\n ):\n self._state: ConnectionState = guild._state\n self.guild: Guild = guild\n self._users: Mapping[int, User] = users\n self._integrations: Mapping[int, PartialIntegration] = integrations\n self._app_commands: Mapping[int, AppCommand] = app_commands\n self._automod_rules: Mapping[int, AutoModRule] = automod_rules\n self._webhooks: Mapping[int, Webhook] = webhooks\n self._from_data(data)\n\n def _from_data(self, data: AuditLogEntryPayload) -> None:\n self.action: enums.AuditLogAction = enums.try_enum(enums.AuditLogAction, data['action_type'])\n self.id: int = int(data['id'])\n\n # this key is technically not usually present\n self.reason: Optional[str] = data.get('reason')\n extra = data.get('options')\n\n # fmt: off\n self.extra: Union[\n _AuditLogProxyMemberPrune,\n _AuditLogProxyMemberMoveOrMessageDelete,\n _AuditLogProxyMemberDisconnect,\n _AuditLogProxyPinAction,\n _AuditLogProxyStageInstanceAction,\n _AuditLogProxyMessageBulkDelete,\n _AuditLogProxyAutoModAction,\n _AuditLogProxyMemberKickOrMemberRoleUpdate,\n Member, User, None, PartialIntegration,\n Role, Object\n ] = None\n # fmt: on\n\n if isinstance(self.action, enums.AuditLogAction) and extra:\n if self.action is enums.AuditLogAction.member_prune:\n # member prune has two keys with useful information\n self.extra = _AuditLogProxyMemberPrune(\n delete_member_days=int(extra['delete_member_days']),\n members_removed=int(extra['members_removed']),\n )\n elif self.action is enums.AuditLogAction.member_move or self.action is enums.AuditLogAction.message_delete:\n channel_id = int(extra['channel_id'])\n self.extra = _AuditLogProxyMemberMoveOrMessageDelete(\n count=int(extra['count']),\n channel=self.guild.get_channel_or_thread(channel_id) or Object(id=channel_id),\n )\n elif self.action is enums.AuditLogAction.member_disconnect:\n # The member disconnect action has a dict with some information\n self.extra = _AuditLogProxyMemberDisconnect(count=int(extra['count']))\n elif self.action is enums.AuditLogAction.message_bulk_delete:\n # The bulk message delete action has the number of messages deleted\n self.extra = _AuditLogProxyMessageBulkDelete(count=int(extra['count']))\n elif self.action in (enums.AuditLogAction.kick, enums.AuditLogAction.member_role_update):\n # The member kick action has a dict with some information\n integration_type = extra.get('integration_type')\n self.extra = _AuditLogProxyMemberKickOrMemberRoleUpdate(integration_type=integration_type)\n elif self.action.name.endswith('pin'):\n # the pin actions have a dict with some information\n channel_id = int(extra['channel_id'])\n self.extra = _AuditLogProxyPinAction(\n channel=self.guild.get_channel_or_thread(channel_id) or Object(id=channel_id),\n message_id=int(extra['message_id']),\n )\n elif (\n self.action is enums.AuditLogAction.automod_block_message\n or self.action is enums.AuditLogAction.automod_flag_message\n or self.action is enums.AuditLogAction.automod_timeout_member\n ):\n channel_id = utils._get_as_snowflake(extra, 'channel_id')\n channel = None\n\n # May be an empty string instead of None due to a Discord issue\n if channel_id:\n channel = self.guild.get_channel_or_thread(channel_id) or Object(id=channel_id)\n\n self.extra = _AuditLogProxyAutoModAction(\n automod_rule_name=extra['auto_moderation_rule_name'],\n automod_rule_trigger_type=enums.try_enum(\n enums.AutoModRuleTriggerType, extra['auto_moderation_rule_trigger_type']\n ),\n channel=channel,\n )\n\n elif self.action.name.startswith('overwrite_'):\n # the overwrite_ actions have a dict with some information\n instance_id = int(extra['id'])\n the_type = extra.get('type')\n if the_type == '1':\n self.extra = self._get_member(instance_id)\n elif the_type == '0':\n role = self.guild.get_role(instance_id)\n if role is None:\n role = Object(id=instance_id, type=Role)\n role.name = extra.get('role_name') # type: ignore # Object doesn't usually have name\n self.extra = role\n elif self.action.name.startswith('stage_instance'):\n channel_id = int(extra['channel_id'])\n self.extra = _AuditLogProxyStageInstanceAction(\n channel=self.guild.get_channel(channel_id) or Object(id=channel_id, type=StageChannel)\n )\n elif self.action.name.startswith('app_command'):\n app_id = int(extra['application_id'])\n self.extra = self._get_integration_by_app_id(app_id) or Object(app_id, type=PartialIntegration)\n\n # this key is not present when the above is present, typically.\n # It's a list of { new_value: a, old_value: b, key: c }\n # where new_value and old_value are not guaranteed to be there depending\n # on the action type, so let's just fetch it for now and only turn it\n # into meaningful data when requested\n self._changes = data.get('changes', [])\n\n self.user_id: Optional[int] = utils._get_as_snowflake(data, 'user_id')\n self.user: Optional[Union[User, Member]] = self._get_member(self.user_id)\n self._target_id = utils._get_as_snowflake(data, 'target_id')\n\n def _get_member(self, user_id: Optional[int]) -> Union[Member, User, None]:\n if user_id is None:\n return None\n\n return self.guild.get_member(user_id) or self._users.get(user_id)\n\n def _get_integration(self, integration_id: Optional[int]) -> Optional[PartialIntegration]:\n if integration_id is None:\n return None\n\n return self._integrations.get(integration_id)\n\n def _get_integration_by_app_id(self, application_id: Optional[int]) -> Optional[PartialIntegration]:\n if application_id is None:\n return None\n\n # get PartialIntegration by application id\n return utils.get(self._integrations.values(), application_id=application_id)\n\n def _get_app_command(self, app_command_id: Optional[int]) -> Optional[AppCommand]:\n if app_command_id is None:\n return None\n\n return self._app_commands.get(app_command_id)\n\n def __repr__(self) -> str:\n return f''\n\n @utils.cached_property\n def created_at(self) -> datetime.datetime:\n \"\"\":class:`datetime.datetime`: Returns the entry's creation time in UTC.\"\"\"\n return utils.snowflake_time(self.id)\n\n @utils.cached_property\n def target(self) -> TargetType:\n if self.action.target_type is None:\n return None\n\n try:\n converter = getattr(self, '_convert_target_' + self.action.target_type)\n except AttributeError:\n if self._target_id is None:\n return None\n return Object(id=self._target_id)\n else:\n return converter(self._target_id)\n\n @utils.cached_property\n def category(self) -> Optional[enums.AuditLogActionCategory]:\n \"\"\"Optional[:class:`AuditLogActionCategory`]: The category of the action, if applicable.\"\"\"\n return self.action.category\n\n @utils.cached_property\n def changes(self) -> AuditLogChanges:\n \"\"\":class:`AuditLogChanges`: The list of changes this entry has.\"\"\"\n obj = AuditLogChanges(self, self._changes)\n del self._changes\n return obj\n\n @utils.cached_property\n def before(self) -> AuditLogDiff:\n \"\"\":class:`AuditLogDiff`: The target's prior state.\"\"\"\n return self.changes.before\n\n @utils.cached_property\n def after(self) -> AuditLogDiff:\n \"\"\":class:`AuditLogDiff`: The target's subsequent state.\"\"\"\n return self.changes.after\n\n def _convert_target_guild(self, target_id: int) -> Guild:\n return self.guild\n\n def _convert_target_channel(self, target_id: int) -> Union[abc.GuildChannel, Object]:\n return self.guild.get_channel(target_id) or Object(id=target_id)\n\n def _convert_target_user(self, target_id: Optional[int]) -> Optional[Union[Member, User, Object]]:\n # For some reason the member_disconnect and member_move action types\n # do not have a non-null target_id so safeguard against that\n if target_id is None:\n return None\n\n return self._get_member(target_id) or Object(id=target_id, type=Member)\n\n def _convert_target_role(self, target_id: int) -> Union[Role, Object]:\n return self.guild.get_role(target_id) or Object(id=target_id, type=Role)\n\n def _convert_target_invite(self, target_id: None) -> Invite:\n # invites have target_id set to null\n # so figure out which change has the full invite data\n changeset = self.before if self.action is enums.AuditLogAction.invite_delete else self.after\n\n fake_payload: InvitePayload = {\n 'max_age': changeset.max_age,\n 'max_uses': changeset.max_uses,\n 'code': changeset.code,\n 'temporary': changeset.temporary,\n 'uses': changeset.uses,\n 'channel': None, # type: ignore # the channel is passed to the Invite constructor directly\n }\n\n obj = Invite(state=self._state, data=fake_payload, guild=self.guild, channel=changeset.channel)\n try:\n obj.inviter = changeset.inviter\n except AttributeError:\n pass\n return obj\n\n def _convert_target_emoji(self, target_id: int) -> Union[Emoji, Object]:\n return self._state.get_emoji(target_id) or Object(id=target_id, type=Emoji)\n\n def _convert_target_message(self, target_id: int) -> Union[Member, User, Object]:\n return self._get_member(target_id) or Object(id=target_id, type=Member)\n\n def _convert_target_stage_instance(self, target_id: int) -> Union[StageInstance, Object]:\n return self.guild.get_stage_instance(target_id) or Object(id=target_id, type=StageInstance)\n\n def _convert_target_sticker(self, target_id: int) -> Union[GuildSticker, Object]:\n return self._state.get_sticker(target_id) or Object(id=target_id, type=GuildSticker)\n\n def _convert_target_thread(self, target_id: int) -> Union[Thread, Object]:\n return self.guild.get_thread(target_id) or Object(id=target_id, type=Thread)\n\n def _convert_target_guild_scheduled_event(self, target_id: int) -> Union[ScheduledEvent, Object]:\n return self.guild.get_scheduled_event(target_id) or Object(id=target_id, type=ScheduledEvent)\n\n def _convert_target_integration(self, target_id: int) -> Union[PartialIntegration, Object]:\n return self._get_integration(target_id) or Object(target_id, type=PartialIntegration)\n\n def _convert_target_app_command(self, target_id: int) -> Union[AppCommand, Object]:\n target = self._get_app_command(target_id)\n if not target:\n # circular import\n from .app_commands import AppCommand\n\n target = Object(target_id, type=AppCommand)\n\n return target\n\n def _convert_target_integration_or_app_command(self, target_id: int) -> Union[PartialIntegration, AppCommand, Object]:\n target = self._get_integration_by_app_id(target_id) or self._get_app_command(target_id)\n if not target:\n try:\n # circular import\n from .app_commands import AppCommand\n\n # get application id from extras\n # if it matches target id, type should be integration\n target_app = self.extra\n # extra should be an Object or PartialIntegration\n app_id = target_app.application_id if isinstance(target_app, PartialIntegration) else target_app.id # type: ignore\n type = PartialIntegration if target_id == app_id else AppCommand\n except AttributeError:\n return Object(target_id)\n else:\n return Object(target_id, type=type)\n\n return target\n\n def _convert_target_auto_moderation(self, target_id: int) -> Union[AutoModRule, Object]:\n return self._automod_rules.get(target_id) or Object(target_id, type=AutoModRule)\n\n def _convert_target_webhook(self, target_id: int) -> Union[Webhook, Object]:\n # circular import\n from .webhook import Webhook\n\n return self._webhooks.get(target_id) or Object(target_id, type=Webhook)\n" }, { "path": "discord/automod.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\nimport datetime\n\nfrom typing import TYPE_CHECKING, Any, Dict, Optional, List, Set, Union, Sequence, overload, Literal\n\nfrom .enums import AutoModRuleTriggerType, AutoModRuleActionType, AutoModRuleEventType, try_enum\nfrom .flags import AutoModPresets\nfrom . import utils\nfrom .utils import MISSING, cached_slot_property\n\nif TYPE_CHECKING:\n from typing_extensions import Self\n from .abc import Snowflake, GuildChannel\n from .threads import Thread\n from .guild import Guild\n from .member import Member\n from .state import ConnectionState\n from .types.automod import (\n AutoModerationRule as AutoModerationRulePayload,\n AutoModerationTriggerMetadata as AutoModerationTriggerMetadataPayload,\n AutoModerationAction as AutoModerationActionPayload,\n AutoModerationActionExecution as AutoModerationActionExecutionPayload,\n )\n from .role import Role\n\n__all__ = (\n 'AutoModRuleAction',\n 'AutoModTrigger',\n 'AutoModRule',\n 'AutoModAction',\n)\n\n\nclass AutoModRuleAction:\n \"\"\"Represents an auto moderation's rule action.\n\n .. note::\n Only one of ``channel_id``, ``duration``, or ``custom_message`` can be used.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n type: :class:`AutoModRuleActionType`\n The type of action to take.\n Defaults to :attr:`~AutoModRuleActionType.block_message`.\n channel_id: Optional[:class:`int`]\n The ID of the channel or thread to send the alert message to, if any.\n Passing this sets :attr:`type` to :attr:`~AutoModRuleActionType.send_alert_message`.\n duration: Optional[:class:`datetime.timedelta`]\n The duration of the timeout to apply, if any.\n Has a maximum of 28 days.\n Passing this sets :attr:`type` to :attr:`~AutoModRuleActionType.timeout`.\n custom_message: Optional[:class:`str`]\n A custom message which will be shown to a user when their message is blocked.\n Passing this sets :attr:`type` to :attr:`~AutoModRuleActionType.block_message`.\n\n .. versionadded:: 2.2\n \"\"\"\n\n __slots__ = ('type', 'channel_id', 'duration', 'custom_message')\n\n @overload\n def __init__(self, *, channel_id: int = ...) -> None:\n ...\n\n @overload\n def __init__(self, *, type: Literal[AutoModRuleActionType.send_alert_message], channel_id: int = ...) -> None:\n ...\n\n @overload\n def __init__(self, *, duration: datetime.timedelta = ...) -> None:\n ...\n\n @overload\n def __init__(self, *, type: Literal[AutoModRuleActionType.timeout], duration: datetime.timedelta = ...) -> None:\n ...\n\n @overload\n def __init__(self, *, custom_message: str = ...) -> None:\n ...\n\n @overload\n def __init__(self, *, type: Literal[AutoModRuleActionType.block_message]) -> None:\n ...\n\n @overload\n def __init__(self, *, type: Literal[AutoModRuleActionType.block_message], custom_message: Optional[str] = ...) -> None:\n ...\n\n @overload\n def __init__(\n self,\n *,\n type: Optional[AutoModRuleActionType] = ...,\n channel_id: Optional[int] = ...,\n duration: Optional[datetime.timedelta] = ...,\n custom_message: Optional[str] = ...,\n ) -> None:\n ...\n\n def __init__(\n self,\n *,\n type: Optional[AutoModRuleActionType] = None,\n channel_id: Optional[int] = None,\n duration: Optional[datetime.timedelta] = None,\n custom_message: Optional[str] = None,\n ) -> None:\n if sum(v is None for v in (channel_id, duration, custom_message)) < 2:\n raise ValueError('Only one of channel_id, duration, or custom_message can be passed.')\n\n self.type: AutoModRuleActionType\n self.channel_id: Optional[int] = None\n self.duration: Optional[datetime.timedelta] = None\n self.custom_message: Optional[str] = None\n\n if type is not None:\n self.type = type\n elif channel_id is not None:\n self.type = AutoModRuleActionType.send_alert_message\n elif duration is not None:\n self.type = AutoModRuleActionType.timeout\n else:\n self.type = AutoModRuleActionType.block_message\n\n if self.type is AutoModRuleActionType.send_alert_message:\n if channel_id is None:\n raise ValueError('channel_id cannot be None if type is send_alert_message')\n self.channel_id = channel_id\n\n if self.type is AutoModRuleActionType.timeout:\n if duration is None:\n raise ValueError('duration cannot be None set if type is timeout')\n self.duration = duration\n\n if self.type is AutoModRuleActionType.block_message:\n self.custom_message = custom_message\n\n def __repr__(self) -> str:\n return f''\n\n @classmethod\n def from_data(cls, data: AutoModerationActionPayload) -> Self:\n if data['type'] == AutoModRuleActionType.timeout.value:\n duration_seconds = data['metadata']['duration_seconds']\n return cls(duration=datetime.timedelta(seconds=duration_seconds))\n elif data['type'] == AutoModRuleActionType.send_alert_message.value:\n channel_id = int(data['metadata']['channel_id'])\n return cls(channel_id=channel_id)\n elif data['type'] == AutoModRuleActionType.block_message.value:\n custom_message = data.get('metadata', {}).get('custom_message')\n return cls(type=AutoModRuleActionType.block_message, custom_message=custom_message)\n\n return cls(type=AutoModRuleActionType.block_member_interactions)\n\n def to_dict(self) -> Dict[str, Any]:\n ret = {'type': self.type.value, 'metadata': {}}\n if self.type is AutoModRuleActionType.block_message and self.custom_message is not None:\n ret['metadata'] = {'custom_message': self.custom_message}\n elif self.type is AutoModRuleActionType.timeout:\n ret['metadata'] = {'duration_seconds': int(self.duration.total_seconds())} # type: ignore # duration cannot be None here\n elif self.type is AutoModRuleActionType.send_alert_message:\n ret['metadata'] = {'channel_id': str(self.channel_id)}\n return ret\n\n\nclass AutoModTrigger:\n r\"\"\"Represents a trigger for an auto moderation rule.\n\n The following table illustrates relevant attributes for each :class:`AutoModRuleTriggerType`:\n\n +-----------------------------------------------+------------------------------------------------+\n | Type | Attributes |\n +===============================================+================================================+\n | :attr:`AutoModRuleTriggerType.keyword` | :attr:`keyword_filter`, :attr:`regex_patterns`,|\n | | :attr:`allow_list` |\n +-----------------------------------------------+------------------------------------------------+\n | :attr:`AutoModRuleTriggerType.spam` | |\n +-----------------------------------------------+------------------------------------------------+\n | :attr:`AutoModRuleTriggerType.keyword_preset` | :attr:`presets`\\, :attr:`allow_list` |\n +-----------------------------------------------+------------------------------------------------+\n | :attr:`AutoModRuleTriggerType.mention_spam` | :attr:`mention_limit`, |\n | | :attr:`mention_raid_protection` |\n +-----------------------------------------------+------------------------------------------------+\n | :attr:`AutoModRuleTriggerType.member_profile` | :attr:`keyword_filter`, :attr:`regex_patterns`,|\n | | :attr:`allow_list` |\n +-----------------------------------------------+------------------------------------------------+\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n type: :class:`AutoModRuleTriggerType`\n The type of trigger.\n keyword_filter: List[:class:`str`]\n The list of strings that will trigger the filter.\n Maximum of 1000. Keywords can only be up to 60 characters in length.\n\n This could be combined with :attr:`regex_patterns`.\n regex_patterns: List[:class:`str`]\n The regex pattern that will trigger the filter. The syntax is based off of\n `Rust's regex syntax `_.\n Maximum of 10. Regex strings can only be up to 260 characters in length.\n\n This could be combined with :attr:`keyword_filter` and/or :attr:`allow_list`\n\n .. versionadded:: 2.1\n presets: :class:`AutoModPresets`\n The presets used with the preset keyword filter.\n allow_list: List[:class:`str`]\n The list of words that are exempt from the commonly flagged words. Maximum of 100.\n Keywords can only be up to 60 characters in length.\n mention_limit: :class:`int`\n The total number of user and role mentions a message can contain.\n Has a maximum of 50.\n mention_raid_protection: :class:`bool`\n Whether mention raid protection is enabled or not.\n\n .. versionadded:: 2.4\n \"\"\"\n\n __slots__ = (\n 'type',\n 'keyword_filter',\n 'presets',\n 'allow_list',\n 'mention_limit',\n 'regex_patterns',\n 'mention_raid_protection',\n )\n\n def __init__(\n self,\n *,\n type: Optional[AutoModRuleTriggerType] = None,\n keyword_filter: Optional[List[str]] = None,\n presets: Optional[AutoModPresets] = None,\n allow_list: Optional[List[str]] = None,\n mention_limit: Optional[int] = None,\n regex_patterns: Optional[List[str]] = None,\n mention_raid_protection: Optional[bool] = None,\n ) -> None:\n unique_args = (keyword_filter or regex_patterns, presets, mention_limit or mention_raid_protection)\n if type is None and sum(arg is not None for arg in unique_args) > 1:\n raise ValueError(\n 'Please pass only one of keyword_filter/regex_patterns, presets, or mention_limit/mention_raid_protection.'\n )\n\n if type is not None:\n self.type = type\n elif keyword_filter is not None or regex_patterns is not None:\n self.type = AutoModRuleTriggerType.keyword\n elif presets is not None:\n self.type = AutoModRuleTriggerType.keyword_preset\n elif mention_limit is not None or mention_raid_protection is not None:\n self.type = AutoModRuleTriggerType.mention_spam\n else:\n raise ValueError(\n 'Please pass the trigger type explicitly if not using keyword_filter, regex_patterns, presets, mention_limit, or mention_raid_protection.'\n )\n\n self.keyword_filter: List[str] = keyword_filter if keyword_filter is not None else []\n self.presets: AutoModPresets = presets if presets is not None else AutoModPresets()\n self.allow_list: List[str] = allow_list if allow_list is not None else []\n self.mention_limit: int = mention_limit if mention_limit is not None else 0\n self.mention_raid_protection: bool = mention_raid_protection if mention_raid_protection is not None else False\n self.regex_patterns: List[str] = regex_patterns if regex_patterns is not None else []\n\n def __repr__(self) -> str:\n data = self.to_metadata_dict()\n if data:\n joined = ' '.join(f'{k}={v!r}' for k, v in data.items())\n return f''\n\n return f''\n\n @classmethod\n def from_data(cls, type: int, data: Optional[AutoModerationTriggerMetadataPayload]) -> Self:\n type_ = try_enum(AutoModRuleTriggerType, type)\n if data is None:\n return cls(type=type_)\n elif type_ in (AutoModRuleTriggerType.keyword, AutoModRuleTriggerType.member_profile):\n return cls(\n type=type_,\n keyword_filter=data.get('keyword_filter'),\n regex_patterns=data.get('regex_patterns'),\n allow_list=data.get('allow_list'),\n )\n elif type_ is AutoModRuleTriggerType.keyword_preset:\n return cls(\n type=type_, presets=AutoModPresets._from_value(data.get('presets', [])), allow_list=data.get('allow_list')\n )\n elif type_ is AutoModRuleTriggerType.mention_spam:\n return cls(\n type=type_,\n mention_limit=data.get('mention_total_limit'),\n mention_raid_protection=data.get('mention_raid_protection_enabled'),\n )\n else:\n return cls(type=type_)\n\n def to_metadata_dict(self) -> Optional[Dict[str, Any]]:\n if self.type in (AutoModRuleTriggerType.keyword, AutoModRuleTriggerType.member_profile):\n return {\n 'keyword_filter': self.keyword_filter,\n 'regex_patterns': self.regex_patterns,\n 'allow_list': self.allow_list,\n }\n elif self.type is AutoModRuleTriggerType.keyword_preset:\n return {'presets': self.presets.to_array(), 'allow_list': self.allow_list}\n elif self.type is AutoModRuleTriggerType.mention_spam:\n return {\n 'mention_total_limit': self.mention_limit,\n 'mention_raid_protection_enabled': self.mention_raid_protection,\n }\n\n\nclass AutoModRule:\n \"\"\"Represents an auto moderation rule.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n id: :class:`int`\n The ID of the rule.\n guild: :class:`Guild`\n The guild the rule is for.\n name: :class:`str`\n The name of the rule.\n creator_id: :class:`int`\n The ID of the user that created the rule.\n trigger: :class:`AutoModTrigger`\n The rule's trigger.\n enabled: :class:`bool`\n Whether the rule is enabled.\n exempt_role_ids: Set[:class:`int`]\n The IDs of the roles that are exempt from the rule.\n exempt_channel_ids: Set[:class:`int`]\n The IDs of the channels that are exempt from the rule.\n event_type: :class:`AutoModRuleEventType`\n The type of event that will trigger the the rule.\n \"\"\"\n\n __slots__ = (\n '_state',\n '_cs_exempt_roles',\n '_cs_exempt_channels',\n '_cs_actions',\n 'id',\n 'guild',\n 'name',\n 'creator_id',\n 'event_type',\n 'trigger',\n 'enabled',\n 'exempt_role_ids',\n 'exempt_channel_ids',\n '_actions',\n )\n\n def __init__(self, *, data: AutoModerationRulePayload, guild: Guild, state: ConnectionState) -> None:\n self._state: ConnectionState = state\n self.guild: Guild = guild\n self.id: int = int(data['id'])\n self.name: str = data['name']\n self.creator_id = int(data['creator_id'])\n self.event_type: AutoModRuleEventType = try_enum(AutoModRuleEventType, data['event_type'])\n self.trigger: AutoModTrigger = AutoModTrigger.from_data(data['trigger_type'], data=data.get('trigger_metadata'))\n self.enabled: bool = data['enabled']\n self.exempt_role_ids: Set[int] = {int(role_id) for role_id in data['exempt_roles']}\n self.exempt_channel_ids: Set[int] = {int(channel_id) for channel_id in data['exempt_channels']}\n self._actions: List[AutoModerationActionPayload] = data['actions']\n\n def __repr__(self) -> str:\n return f''\n\n def to_dict(self) -> AutoModerationRulePayload:\n ret: AutoModerationRulePayload = {\n 'id': str(self.id),\n 'guild_id': str(self.guild.id),\n 'name': self.name,\n 'creator_id': str(self.creator_id),\n 'event_type': self.event_type.value,\n 'trigger_type': self.trigger.type.value,\n 'trigger_metadata': self.trigger.to_metadata_dict(),\n 'actions': [action.to_dict() for action in self.actions],\n 'enabled': self.enabled,\n 'exempt_roles': [str(role_id) for role_id in self.exempt_role_ids],\n 'exempt_channels': [str(channel_id) for channel_id in self.exempt_channel_ids],\n } # type: ignore # trigger types break the flow here.\n\n return ret\n\n @property\n def creator(self) -> Optional[Member]:\n \"\"\"Optional[:class:`Member`]: The member that created this rule.\"\"\"\n return self.guild.get_member(self.creator_id)\n\n @cached_slot_property('_cs_exempt_roles')\n def exempt_roles(self) -> List[Role]:\n \"\"\"List[:class:`Role`]: The roles that are exempt from this rule.\"\"\"\n result = []\n get_role = self.guild.get_role\n for role_id in self.exempt_role_ids:\n role = get_role(role_id)\n if role is not None:\n result.append(role)\n\n return utils._unique(result)\n\n @cached_slot_property('_cs_exempt_channels')\n def exempt_channels(self) -> List[Union[GuildChannel, Thread]]:\n \"\"\"List[Union[:class:`abc.GuildChannel`, :class:`Thread`]]: The channels that are exempt from this rule.\"\"\"\n it = filter(None, map(self.guild._resolve_channel, self.exempt_channel_ids))\n return utils._unique(it)\n\n @cached_slot_property('_cs_actions')\n def actions(self) -> List[AutoModRuleAction]:\n \"\"\"List[:class:`AutoModRuleAction`]: The actions that are taken when this rule is triggered.\"\"\"\n return [AutoModRuleAction.from_data(action) for action in self._actions]\n\n def is_exempt(self, obj: Snowflake, /) -> bool:\n \"\"\"Check if an object is exempt from the automod rule.\n\n Parameters\n -----------\n obj: :class:`abc.Snowflake`\n The role, channel, or thread to check.\n\n Returns\n --------\n :class:`bool`\n Whether the object is exempt from the automod rule.\n \"\"\"\n return obj.id in self.exempt_channel_ids or obj.id in self.exempt_role_ids\n\n async def edit(\n self,\n *,\n name: str = MISSING,\n event_type: AutoModRuleEventType = MISSING,\n actions: List[AutoModRuleAction] = MISSING,\n trigger: AutoModTrigger = MISSING,\n enabled: bool = MISSING,\n exempt_roles: Sequence[Snowflake] = MISSING,\n exempt_channels: Sequence[Snowflake] = MISSING,\n reason: str = MISSING,\n ) -> Self:\n \"\"\"|coro|\n\n Edits this auto moderation rule.\n\n You must have :attr:`Permissions.manage_guild` to edit rules.\n\n Parameters\n -----------\n name: :class:`str`\n The new name to change to.\n event_type: :class:`AutoModRuleEventType`\n The new event type to change to.\n actions: List[:class:`AutoModRuleAction`]\n The new rule actions to update.\n trigger: :class:`AutoModTrigger`\n The new trigger to update.\n You can only change the trigger metadata, not the type.\n enabled: :class:`bool`\n Whether the rule should be enabled or not.\n exempt_roles: Sequence[:class:`abc.Snowflake`]\n The new roles to exempt from the rule.\n exempt_channels: Sequence[:class:`abc.Snowflake`]\n The new channels to exempt from the rule.\n reason: :class:`str`\n The reason for updating this rule. Shows up on the audit log.\n\n Raises\n -------\n Forbidden\n You do not have permission to edit this rule.\n HTTPException\n Editing the rule failed.\n\n Returns\n --------\n :class:`AutoModRule`\n The updated auto moderation rule.\n \"\"\"\n payload = {}\n if actions is not MISSING:\n payload['actions'] = [action.to_dict() for action in actions]\n\n if name is not MISSING:\n payload['name'] = name\n\n if event_type is not MISSING:\n payload['event_type'] = event_type.value\n\n if trigger is not MISSING:\n trigger_metadata = trigger.to_metadata_dict()\n if trigger_metadata is not None:\n payload['trigger_metadata'] = trigger_metadata\n\n if enabled is not MISSING:\n payload['enabled'] = enabled\n\n if exempt_roles is not MISSING:\n payload['exempt_roles'] = [x.id for x in exempt_roles]\n\n if exempt_channels is not MISSING:\n payload['exempt_channels'] = [x.id for x in exempt_channels]\n\n data = await self._state.http.edit_auto_moderation_rule(\n self.guild.id,\n self.id,\n reason=reason,\n **payload,\n )\n\n return self.__class__(data=data, guild=self.guild, state=self._state)\n\n async def delete(self, *, reason: str = MISSING) -> None:\n \"\"\"|coro|\n\n Deletes the auto moderation rule.\n\n You must have :attr:`Permissions.manage_guild` to delete rules.\n\n Parameters\n -----------\n reason: :class:`str`\n The reason for deleting this rule. Shows up on the audit log.\n\n Raises\n -------\n Forbidden\n You do not have permissions to delete the rule.\n HTTPException\n Deleting the rule failed.\n \"\"\"\n await self._state.http.delete_auto_moderation_rule(self.guild.id, self.id, reason=reason)\n\n\nclass AutoModAction:\n \"\"\"Represents an action that was taken as the result of a moderation rule.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n action: :class:`AutoModRuleAction`\n The action that was taken.\n message_id: Optional[:class:`int`]\n The message ID that triggered the action. This is only available if the\n action is done on an edited message.\n rule_id: :class:`int`\n The ID of the rule that was triggered.\n rule_trigger_type: :class:`AutoModRuleTriggerType`\n The trigger type of the rule that was triggered.\n guild_id: :class:`int`\n The ID of the guild where the rule was triggered.\n user_id: :class:`int`\n The ID of the user that triggered the rule.\n channel_id: :class:`int`\n The ID of the channel where the rule was triggered.\n alert_system_message_id: Optional[:class:`int`]\n The ID of the system message that was sent to the predefined alert channel.\n content: :class:`str`\n The content of the message that triggered the rule.\n Requires the :attr:`Intents.message_content` or it will always return an empty string.\n matched_keyword: Optional[:class:`str`]\n The matched keyword from the triggering message.\n matched_content: Optional[:class:`str`]\n The matched content from the triggering message.\n Requires the :attr:`Intents.message_content` or it will always return ``None``.\n \"\"\"\n\n __slots__ = (\n '_state',\n 'action',\n 'rule_id',\n 'rule_trigger_type',\n 'guild_id',\n 'user_id',\n 'channel_id',\n 'message_id',\n 'alert_system_message_id',\n 'content',\n 'matched_keyword',\n 'matched_content',\n )\n\n def __init__(self, *, data: AutoModerationActionExecutionPayload, state: ConnectionState) -> None:\n self._state: ConnectionState = state\n self.message_id: Optional[int] = utils._get_as_snowflake(data, 'message_id')\n self.action: AutoModRuleAction = AutoModRuleAction.from_data(data['action'])\n self.rule_id: int = int(data['rule_id'])\n self.rule_trigger_type: AutoModRuleTriggerType = try_enum(AutoModRuleTriggerType, data['rule_trigger_type'])\n self.guild_id: int = int(data['guild_id'])\n self.channel_id: Optional[int] = utils._get_as_snowflake(data, 'channel_id')\n self.user_id: int = int(data['user_id'])\n self.alert_system_message_id: Optional[int] = utils._get_as_snowflake(data, 'alert_system_message_id')\n self.content: str = data.get('content', '')\n self.matched_keyword: Optional[str] = data['matched_keyword']\n self.matched_content: Optional[str] = data.get('matched_content')\n\n def __repr__(self) -> str:\n return f''\n\n @property\n def guild(self) -> Guild:\n \"\"\":class:`Guild`: The guild this action was taken in.\"\"\"\n return self._state._get_or_create_unavailable_guild(self.guild_id)\n\n @property\n def channel(self) -> Optional[Union[GuildChannel, Thread]]:\n \"\"\"Optional[Union[:class:`abc.GuildChannel`, :class:`Thread`]]: The channel this action was taken in.\"\"\"\n if self.channel_id:\n return self.guild.get_channel_or_thread(self.channel_id)\n return None\n\n @property\n def member(self) -> Optional[Member]:\n \"\"\"Optional[:class:`Member`]: The member this action was taken against /who triggered this rule.\"\"\"\n return self.guild.get_member(self.user_id)\n\n async def fetch_rule(self) -> AutoModRule:\n \"\"\"|coro|\n\n Fetch the rule whose action was taken.\n\n You must have :attr:`Permissions.manage_guild` to do this.\n\n Raises\n -------\n Forbidden\n You do not have permissions to view the rule.\n HTTPException\n Fetching the rule failed.\n\n Returns\n --------\n :class:`AutoModRule`\n The rule that was executed.\n \"\"\"\n\n data = await self._state.http.get_auto_moderation_rule(self.guild.id, self.rule_id)\n return AutoModRule(data=data, guild=self.guild, state=self._state)\n" }, { "path": "discord/backoff.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\n\nimport time\nimport random\nfrom typing import Callable, Generic, Literal, TypeVar, overload, Union\n\nT = TypeVar('T', bool, Literal[True], Literal[False])\n\n# fmt: off\n__all__ = (\n 'ExponentialBackoff',\n)\n# fmt: on\n\n\nclass ExponentialBackoff(Generic[T]):\n \"\"\"An implementation of the exponential backoff algorithm\n\n Provides a convenient interface to implement an exponential backoff\n for reconnecting or retrying transmissions in a distributed network.\n\n Once instantiated, the delay method will return the next interval to\n wait for when retrying a connection or transmission. The maximum\n delay increases exponentially with each retry up to a maximum of\n 2^10 * base, and is reset if no more attempts are needed in a period\n of 2^11 * base seconds.\n\n Parameters\n ----------\n base: :class:`int`\n The base delay in seconds. The first retry-delay will be up to\n this many seconds.\n integral: :class:`bool`\n Set to ``True`` if whole periods of base is desirable, otherwise any\n number in between may be returned.\n \"\"\"\n\n def __init__(self, base: int = 1, *, integral: T = False):\n self._base: int = base\n\n self._exp: int = 0\n self._max: int = 10\n self._reset_time: int = base * 2**11\n self._last_invocation: float = time.monotonic()\n\n # Use our own random instance to avoid messing with global one\n rand = random.Random()\n rand.seed()\n\n self._randfunc: Callable[..., Union[int, float]] = rand.randrange if integral else rand.uniform\n\n @overload\n def delay(self: ExponentialBackoff[Literal[False]]) -> float:\n ...\n\n @overload\n def delay(self: ExponentialBackoff[Literal[True]]) -> int:\n ...\n\n @overload\n def delay(self: ExponentialBackoff[bool]) -> Union[int, float]:\n ...\n\n def delay(self) -> Union[int, float]:\n \"\"\"Compute the next delay\n\n Returns the next delay to wait according to the exponential\n backoff algorithm. This is a value between 0 and base * 2^exp\n where exponent starts off at 1 and is incremented at every\n invocation of this method up to a maximum of 10.\n\n If a period of more than base * 2^11 has passed since the last\n retry, the exponent is reset to 1.\n \"\"\"\n invocation = time.monotonic()\n interval = invocation - self._last_invocation\n self._last_invocation = invocation\n\n if interval > self._reset_time:\n self._exp = 0\n\n self._exp = min(self._exp + 1, self._max)\n return self._randfunc(0, self._base * 2**self._exp)\n" }, { "path": "discord/bin/COPYING", "content": "Copyright (c) 1994-2013 Xiph.Org Foundation and contributors\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions\nare met:\n\n- Redistributions of source code must retain the above copyright\nnotice, this list of conditions and the following disclaimer.\n\n- Redistributions in binary form must reproduce the above copyright\nnotice, this list of conditions and the following disclaimer in the\ndocumentation and/or other materials provided with the distribution.\n\n- Neither the name of the Xiph.Org Foundation nor the names of its\ncontributors may be used to endorse or promote products derived from\nthis software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS\n``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT\nLIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\nA PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION\nOR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,\nSPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT\nLIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\nDATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\nTHEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n" }, { "path": "discord/channel.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import (\n Any,\n AsyncIterator,\n Callable,\n Dict,\n Iterable,\n List,\n Literal,\n Mapping,\n NamedTuple,\n Optional,\n TYPE_CHECKING,\n Sequence,\n Tuple,\n TypeVar,\n Union,\n overload,\n)\nimport datetime\n\nimport discord.abc\nfrom .scheduled_event import ScheduledEvent\nfrom .permissions import PermissionOverwrite, Permissions\nfrom .enums import ChannelType, ForumLayoutType, ForumOrderType, PrivacyLevel, try_enum, VideoQualityMode, EntityType\nfrom .mixins import Hashable\nfrom . import utils\nfrom .utils import MISSING\nfrom .asset import Asset\nfrom .errors import ClientException\nfrom .stage_instance import StageInstance\nfrom .threads import Thread\nfrom .partial_emoji import _EmojiTag, PartialEmoji\nfrom .flags import ChannelFlags\nfrom .http import handle_message_parameters\n\n__all__ = (\n 'TextChannel',\n 'VoiceChannel',\n 'StageChannel',\n 'DMChannel',\n 'CategoryChannel',\n 'ForumTag',\n 'ForumChannel',\n 'GroupChannel',\n 'PartialMessageable',\n)\n\nif TYPE_CHECKING:\n from typing_extensions import Self\n\n from .types.threads import ThreadArchiveDuration\n from .role import Role\n from .object import Object\n from .member import Member, VoiceState\n from .abc import Snowflake, SnowflakeTime\n from .embeds import Embed\n from .message import Message, PartialMessage, EmojiInputType\n from .mentions import AllowedMentions\n from .webhook import Webhook\n from .state import ConnectionState\n from .sticker import GuildSticker, StickerItem\n from .file import File\n from .user import ClientUser, User, BaseUser\n from .guild import Guild, GuildChannel as GuildChannelType\n from .ui.view import View\n from .types.channel import (\n TextChannel as TextChannelPayload,\n NewsChannel as NewsChannelPayload,\n VoiceChannel as VoiceChannelPayload,\n StageChannel as StageChannelPayload,\n DMChannel as DMChannelPayload,\n CategoryChannel as CategoryChannelPayload,\n GroupDMChannel as GroupChannelPayload,\n ForumChannel as ForumChannelPayload,\n MediaChannel as MediaChannelPayload,\n ForumTag as ForumTagPayload,\n )\n from .types.snowflake import SnowflakeList\n\n OverwriteKeyT = TypeVar('OverwriteKeyT', Role, BaseUser, Object, Union[Role, Member, Object])\n\n\nclass ThreadWithMessage(NamedTuple):\n thread: Thread\n message: Message\n\n\nclass TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):\n \"\"\"Represents a Discord guild text channel.\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two channels are equal.\n\n .. describe:: x != y\n\n Checks if two channels are not equal.\n\n .. describe:: hash(x)\n\n Returns the channel's hash.\n\n .. describe:: str(x)\n\n Returns the channel's name.\n\n Attributes\n -----------\n name: :class:`str`\n The channel name.\n guild: :class:`Guild`\n The guild the channel belongs to.\n id: :class:`int`\n The channel ID.\n category_id: Optional[:class:`int`]\n The category channel ID this channel belongs to, if applicable.\n topic: Optional[:class:`str`]\n The channel's topic. ``None`` if it doesn't exist.\n position: :class:`int`\n The position in the channel list. This is a number that starts at 0. e.g. the\n top channel is position 0.\n last_message_id: Optional[:class:`int`]\n The last message ID of the message sent to this channel. It may\n *not* point to an existing or valid message.\n slowmode_delay: :class:`int`\n The number of seconds a member must wait between sending messages\n in this channel. A value of ``0`` denotes that it is disabled.\n Bots and users with :attr:`~Permissions.manage_channels` or\n :attr:`~Permissions.manage_messages` bypass slowmode.\n nsfw: :class:`bool`\n If the channel is marked as \"not safe for work\" or \"age restricted\".\n default_auto_archive_duration: :class:`int`\n The default auto archive duration in minutes for threads created in this channel.\n\n .. versionadded:: 2.0\n default_thread_slowmode_delay: :class:`int`\n The default slowmode delay in seconds for threads created in this channel.\n\n .. versionadded:: 2.3\n \"\"\"\n\n __slots__ = (\n 'name',\n 'id',\n 'guild',\n 'topic',\n '_state',\n 'nsfw',\n 'category_id',\n 'position',\n 'slowmode_delay',\n '_overwrites',\n '_type',\n 'last_message_id',\n 'default_auto_archive_duration',\n 'default_thread_slowmode_delay',\n )\n\n def __init__(self, *, state: ConnectionState, guild: Guild, data: Union[TextChannelPayload, NewsChannelPayload]):\n self._state: ConnectionState = state\n self.id: int = int(data['id'])\n self._type: Literal[0, 5] = data['type']\n self._update(guild, data)\n\n def __repr__(self) -> str:\n attrs = [\n ('id', self.id),\n ('name', self.name),\n ('position', self.position),\n ('nsfw', self.nsfw),\n ('news', self.is_news()),\n ('category_id', self.category_id),\n ]\n joined = ' '.join('%s=%r' % t for t in attrs)\n return f'<{self.__class__.__name__} {joined}>'\n\n def _update(self, guild: Guild, data: Union[TextChannelPayload, NewsChannelPayload]) -> None:\n self.guild: Guild = guild\n self.name: str = data['name']\n self.category_id: Optional[int] = utils._get_as_snowflake(data, 'parent_id')\n self.topic: Optional[str] = data.get('topic')\n self.position: int = data['position']\n self.nsfw: bool = data.get('nsfw', False)\n # Does this need coercion into `int`? No idea yet.\n self.slowmode_delay: int = data.get('rate_limit_per_user', 0)\n self.default_auto_archive_duration: ThreadArchiveDuration = data.get('default_auto_archive_duration', 1440)\n self.default_thread_slowmode_delay: int = data.get('default_thread_rate_limit_per_user', 0)\n self._type: Literal[0, 5] = data.get('type', self._type)\n self.last_message_id: Optional[int] = utils._get_as_snowflake(data, 'last_message_id')\n self._fill_overwrites(data)\n\n async def _get_channel(self) -> Self:\n return self\n\n @property\n def type(self) -> Literal[ChannelType.text, ChannelType.news]:\n \"\"\":class:`ChannelType`: The channel's Discord type.\"\"\"\n if self._type == 0:\n return ChannelType.text\n return ChannelType.news\n\n @property\n def _sorting_bucket(self) -> int:\n return ChannelType.text.value\n\n @property\n def _scheduled_event_entity_type(self) -> Optional[EntityType]:\n return None\n\n @utils.copy_doc(discord.abc.GuildChannel.permissions_for)\n def permissions_for(self, obj: Union[Member, Role], /) -> Permissions:\n base = super().permissions_for(obj)\n self._apply_implicit_permissions(base)\n\n # text channels do not have voice related permissions\n denied = Permissions.voice()\n base.value &= ~denied.value\n return base\n\n @property\n def members(self) -> List[Member]:\n \"\"\"List[:class:`Member`]: Returns all members that can see this channel.\"\"\"\n return [m for m in self.guild.members if self.permissions_for(m).read_messages]\n\n @property\n def threads(self) -> List[Thread]:\n \"\"\"List[:class:`Thread`]: Returns all the threads that you can see.\n\n .. versionadded:: 2.0\n \"\"\"\n return [thread for thread in self.guild._threads.values() if thread.parent_id == self.id]\n\n def is_nsfw(self) -> bool:\n \"\"\":class:`bool`: Checks if the channel is NSFW.\"\"\"\n return self.nsfw\n\n def is_news(self) -> bool:\n \"\"\":class:`bool`: Checks if the channel is a news channel.\"\"\"\n return self._type == ChannelType.news.value\n\n @property\n def last_message(self) -> Optional[Message]:\n \"\"\"Retrieves the last message from this channel in cache.\n\n The message might not be valid or point to an existing message.\n\n .. admonition:: Reliable Fetching\n :class: helpful\n\n For a slightly more reliable method of fetching the\n last message, consider using either :meth:`history`\n or :meth:`fetch_message` with the :attr:`last_message_id`\n attribute.\n\n Returns\n ---------\n Optional[:class:`Message`]\n The last message in this channel or ``None`` if not found.\n \"\"\"\n return self._state._get_message(self.last_message_id) if self.last_message_id else None\n\n @overload\n async def edit(self) -> Optional[TextChannel]:\n ...\n\n @overload\n async def edit(self, *, position: int, reason: Optional[str] = ...) -> None:\n ...\n\n @overload\n async def edit(\n self,\n *,\n reason: Optional[str] = ...,\n name: str = ...,\n topic: str = ...,\n position: int = ...,\n nsfw: bool = ...,\n sync_permissions: bool = ...,\n category: Optional[CategoryChannel] = ...,\n slowmode_delay: int = ...,\n default_auto_archive_duration: ThreadArchiveDuration = ...,\n default_thread_slowmode_delay: int = ...,\n type: ChannelType = ...,\n overwrites: Mapping[OverwriteKeyT, PermissionOverwrite] = ...,\n ) -> TextChannel:\n ...\n\n async def edit(self, *, reason: Optional[str] = None, **options: Any) -> Optional[TextChannel]:\n \"\"\"|coro|\n\n Edits the channel.\n\n You must have :attr:`~Permissions.manage_channels` to do this.\n\n .. versionchanged:: 1.3\n The ``overwrites`` keyword-only parameter was added.\n\n .. versionchanged:: 1.4\n The ``type`` keyword-only parameter was added.\n\n .. versionchanged:: 2.0\n Edits are no longer in-place, the newly edited channel is returned instead.\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`TypeError` or\n :exc:`ValueError` instead of ``InvalidArgument``.\n\n Parameters\n ----------\n name: :class:`str`\n The new channel name.\n topic: :class:`str`\n The new channel's topic.\n position: :class:`int`\n The new channel's position.\n nsfw: :class:`bool`\n To mark the channel as NSFW or not.\n sync_permissions: :class:`bool`\n Whether to sync permissions with the channel's new or pre-existing\n category. Defaults to ``False``.\n category: Optional[:class:`CategoryChannel`]\n The new category for this channel. Can be ``None`` to remove the\n category.\n slowmode_delay: :class:`int`\n Specifies the slowmode rate limit for user in this channel, in seconds.\n A value of ``0`` disables slowmode. The maximum value possible is ``21600``.\n type: :class:`ChannelType`\n Change the type of this text channel. Currently, only conversion between\n :attr:`ChannelType.text` and :attr:`ChannelType.news` is supported. This\n is only available to guilds that contain ``NEWS`` in :attr:`Guild.features`.\n reason: Optional[:class:`str`]\n The reason for editing this channel. Shows up on the audit log.\n overwrites: :class:`Mapping`\n A :class:`Mapping` of target (either a role or a member) to\n :class:`PermissionOverwrite` to apply to the channel.\n default_auto_archive_duration: :class:`int`\n The new default auto archive duration in minutes for threads created in this channel.\n Must be one of ``60``, ``1440``, ``4320``, or ``10080``.\n\n .. versionadded:: 2.0\n default_thread_slowmode_delay: :class:`int`\n The new default slowmode delay in seconds for threads created in this channel.\n\n .. versionadded:: 2.3\n Raises\n ------\n ValueError\n The new ``position`` is less than 0 or greater than the number of channels.\n TypeError\n The permission overwrite information is not in proper form.\n Forbidden\n You do not have permissions to edit the channel.\n HTTPException\n Editing the channel failed.\n\n Returns\n --------\n Optional[:class:`.TextChannel`]\n The newly edited text channel. If the edit was only positional\n then ``None`` is returned instead.\n \"\"\"\n\n payload = await self._edit(options, reason=reason)\n if payload is not None:\n # the payload will always be the proper channel payload\n return self.__class__(state=self._state, guild=self.guild, data=payload) # type: ignore\n\n @utils.copy_doc(discord.abc.GuildChannel.clone)\n async def clone(self, *, name: Optional[str] = None, reason: Optional[str] = None) -> TextChannel:\n return await self._clone_impl(\n {'topic': self.topic, 'nsfw': self.nsfw, 'rate_limit_per_user': self.slowmode_delay}, name=name, reason=reason\n )\n\n async def delete_messages(self, messages: Iterable[Snowflake], *, reason: Optional[str] = None) -> None:\n \"\"\"|coro|\n\n Deletes a list of messages. This is similar to :meth:`Message.delete`\n except it bulk deletes multiple messages.\n\n As a special case, if the number of messages is 0, then nothing\n is done. If the number of messages is 1 then single message\n delete is done. If it's more than two, then bulk delete is used.\n\n You cannot bulk delete more than 100 messages or messages that\n are older than 14 days old.\n\n You must have :attr:`~Permissions.manage_messages` to do this.\n\n .. versionchanged:: 2.0\n\n ``messages`` parameter is now positional-only.\n\n The ``reason`` keyword-only parameter was added.\n\n Parameters\n -----------\n messages: Iterable[:class:`abc.Snowflake`]\n An iterable of messages denoting which ones to bulk delete.\n reason: Optional[:class:`str`]\n The reason for deleting the messages. Shows up on the audit log.\n\n Raises\n ------\n ClientException\n The number of messages to delete was more than 100.\n Forbidden\n You do not have proper permissions to delete the messages.\n NotFound\n If single delete, then the message was already deleted.\n HTTPException\n Deleting the messages failed.\n \"\"\"\n if not isinstance(messages, (list, tuple)):\n messages = list(messages)\n\n if len(messages) == 0:\n return # do nothing\n\n if len(messages) == 1:\n message_id: int = messages[0].id\n await self._state.http.delete_message(self.id, message_id)\n return\n\n if len(messages) > 100:\n raise ClientException('Can only bulk delete messages up to 100 messages')\n\n message_ids: SnowflakeList = [m.id for m in messages]\n await self._state.http.delete_messages(self.id, message_ids, reason=reason)\n\n async def purge(\n self,\n *,\n limit: Optional[int] = 100,\n check: Callable[[Message], bool] = MISSING,\n before: Optional[SnowflakeTime] = None,\n after: Optional[SnowflakeTime] = None,\n around: Optional[SnowflakeTime] = None,\n oldest_first: Optional[bool] = None,\n bulk: bool = True,\n reason: Optional[str] = None,\n ) -> List[Message]:\n \"\"\"|coro|\n\n Purges a list of messages that meet the criteria given by the predicate\n ``check``. If a ``check`` is not provided then all messages are deleted\n without discrimination.\n\n You must have :attr:`~Permissions.manage_messages` to\n delete messages even if they are your own.\n Having :attr:`~Permissions.read_message_history` is\n also needed to retrieve message history.\n\n .. versionchanged:: 2.0\n\n The ``reason`` keyword-only parameter was added.\n\n Examples\n ---------\n\n Deleting bot's messages ::\n\n def is_me(m):\n return m.author == client.user\n\n deleted = await channel.purge(limit=100, check=is_me)\n await channel.send(f'Deleted {len(deleted)} message(s)')\n\n Parameters\n -----------\n limit: Optional[:class:`int`]\n The number of messages to search through. This is not the number\n of messages that will be deleted, though it can be.\n check: Callable[[:class:`Message`], :class:`bool`]\n The function used to check if a message should be deleted.\n It must take a :class:`Message` as its sole parameter.\n before: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]\n Same as ``before`` in :meth:`history`.\n after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]\n Same as ``after`` in :meth:`history`.\n around: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]\n Same as ``around`` in :meth:`history`.\n oldest_first: Optional[:class:`bool`]\n Same as ``oldest_first`` in :meth:`history`.\n bulk: :class:`bool`\n If ``True``, use bulk delete. Setting this to ``False`` is useful for mass-deleting\n a bot's own messages without :attr:`Permissions.manage_messages`. When ``True``, will\n fall back to single delete if messages are older than two weeks.\n reason: Optional[:class:`str`]\n The reason for purging the messages. Shows up on the audit log.\n\n Raises\n -------\n Forbidden\n You do not have proper permissions to do the actions required.\n HTTPException\n Purging the messages failed.\n\n Returns\n --------\n List[:class:`.Message`]\n The list of messages that were deleted.\n \"\"\"\n return await discord.abc._purge_helper(\n self,\n limit=limit,\n check=check,\n before=before,\n after=after,\n around=around,\n oldest_first=oldest_first,\n bulk=bulk,\n reason=reason,\n )\n\n async def webhooks(self) -> List[Webhook]:\n \"\"\"|coro|\n\n Gets the list of webhooks from this channel.\n\n You must have :attr:`~.Permissions.manage_webhooks` to do this.\n\n Raises\n -------\n Forbidden\n You don't have permissions to get the webhooks.\n\n Returns\n --------\n List[:class:`Webhook`]\n The webhooks for this channel.\n \"\"\"\n\n from .webhook import Webhook\n\n data = await self._state.http.channel_webhooks(self.id)\n return [Webhook.from_state(d, state=self._state) for d in data]\n\n async def create_webhook(self, *, name: str, avatar: Optional[bytes] = None, reason: Optional[str] = None) -> Webhook:\n \"\"\"|coro|\n\n Creates a webhook for this channel.\n\n You must have :attr:`~.Permissions.manage_webhooks` to do this.\n\n .. versionchanged:: 1.1\n Added the ``reason`` keyword-only parameter.\n\n Parameters\n -------------\n name: :class:`str`\n The webhook's name.\n avatar: Optional[:class:`bytes`]\n A :term:`py:bytes-like object` representing the webhook's default avatar.\n This operates similarly to :meth:`~ClientUser.edit`.\n reason: Optional[:class:`str`]\n The reason for creating this webhook. Shows up in the audit logs.\n\n Raises\n -------\n HTTPException\n Creating the webhook failed.\n Forbidden\n You do not have permissions to create a webhook.\n\n Returns\n --------\n :class:`Webhook`\n The created webhook.\n \"\"\"\n\n from .webhook import Webhook\n\n if avatar is not None:\n avatar = utils._bytes_to_base64_data(avatar) # type: ignore # Silence reassignment error\n\n data = await self._state.http.create_webhook(self.id, name=str(name), avatar=avatar, reason=reason)\n return Webhook.from_state(data, state=self._state)\n\n async def follow(self, *, destination: TextChannel, reason: Optional[str] = None) -> Webhook:\n \"\"\"|coro|\n\n Follows a channel using a webhook.\n\n Only news channels can be followed.\n\n .. note::\n\n The webhook returned will not provide a token to do webhook\n actions, as Discord does not provide it.\n\n .. versionadded:: 1.3\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`TypeError` instead of\n ``InvalidArgument``.\n\n Parameters\n -----------\n destination: :class:`TextChannel`\n The channel you would like to follow from.\n reason: Optional[:class:`str`]\n The reason for following the channel. Shows up on the destination guild's audit log.\n\n .. versionadded:: 1.4\n\n Raises\n -------\n HTTPException\n Following the channel failed.\n Forbidden\n You do not have the permissions to create a webhook.\n ClientException\n The channel is not a news channel.\n TypeError\n The destination channel is not a text channel.\n\n Returns\n --------\n :class:`Webhook`\n The created webhook.\n \"\"\"\n\n if not self.is_news():\n raise ClientException('The channel must be a news channel.')\n\n if not isinstance(destination, TextChannel):\n raise TypeError(f'Expected TextChannel received {destination.__class__.__name__}')\n\n from .webhook import Webhook\n\n data = await self._state.http.follow_webhook(self.id, webhook_channel_id=destination.id, reason=reason)\n return Webhook._as_follower(data, channel=destination, user=self._state.user)\n\n def get_partial_message(self, message_id: int, /) -> PartialMessage:\n \"\"\"Creates a :class:`PartialMessage` from the message ID.\n\n This is useful if you want to work with a message and only have its ID without\n doing an unnecessary API call.\n\n .. versionadded:: 1.6\n\n .. versionchanged:: 2.0\n\n ``message_id`` parameter is now positional-only.\n\n Parameters\n ------------\n message_id: :class:`int`\n The message ID to create a partial message for.\n\n Returns\n ---------\n :class:`PartialMessage`\n The partial message.\n \"\"\"\n\n from .message import PartialMessage\n\n return PartialMessage(channel=self, id=message_id)\n\n def get_thread(self, thread_id: int, /) -> Optional[Thread]:\n \"\"\"Returns a thread with the given ID.\n\n .. note::\n\n This does not always retrieve archived threads, as they are not retained in the internal\n cache. Use :func:`Guild.fetch_channel` instead.\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n thread_id: :class:`int`\n The ID to search for.\n\n Returns\n --------\n Optional[:class:`Thread`]\n The returned thread or ``None`` if not found.\n \"\"\"\n return self.guild.get_thread(thread_id)\n\n async def create_thread(\n self,\n *,\n name: str,\n message: Optional[Snowflake] = None,\n auto_archive_duration: ThreadArchiveDuration = MISSING,\n type: Optional[ChannelType] = None,\n reason: Optional[str] = None,\n invitable: bool = True,\n slowmode_delay: Optional[int] = None,\n ) -> Thread:\n \"\"\"|coro|\n\n Creates a thread in this text channel.\n\n To create a public thread, you must have :attr:`~discord.Permissions.create_public_threads`.\n For a private thread, :attr:`~discord.Permissions.create_private_threads` is needed instead.\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n name: :class:`str`\n The name of the thread.\n message: Optional[:class:`abc.Snowflake`]\n A snowflake representing the message to create the thread with.\n If ``None`` is passed then a private thread is created.\n Defaults to ``None``.\n auto_archive_duration: :class:`int`\n The duration in minutes before a thread is automatically hidden from the channel list.\n If not provided, the channel's default auto archive duration is used.\n\n Must be one of ``60``, ``1440``, ``4320``, or ``10080``, if provided.\n type: Optional[:class:`ChannelType`]\n The type of thread to create. If a ``message`` is passed then this parameter\n is ignored, as a thread created with a message is always a public thread.\n By default this creates a private thread if this is ``None``.\n reason: :class:`str`\n The reason for creating a new thread. Shows up on the audit log.\n invitable: :class:`bool`\n Whether non-moderators can add users to the thread. Only applicable to private threads.\n Defaults to ``True``.\n slowmode_delay: Optional[:class:`int`]\n Specifies the slowmode rate limit for user in this channel, in seconds.\n The maximum value possible is ``21600``. By default no slowmode rate limit\n if this is ``None``.\n\n Raises\n -------\n Forbidden\n You do not have permissions to create a thread.\n HTTPException\n Starting the thread failed.\n\n Returns\n --------\n :class:`Thread`\n The created thread\n \"\"\"\n\n if type is None:\n type = ChannelType.private_thread\n\n if message is None:\n data = await self._state.http.start_thread_without_message(\n self.id,\n name=name,\n auto_archive_duration=auto_archive_duration or self.default_auto_archive_duration,\n type=type.value, # type: ignore # we're assuming that the user is passing a valid variant\n reason=reason,\n invitable=invitable,\n rate_limit_per_user=slowmode_delay,\n )\n else:\n data = await self._state.http.start_thread_with_message(\n self.id,\n message.id,\n name=name,\n auto_archive_duration=auto_archive_duration or self.default_auto_archive_duration,\n reason=reason,\n rate_limit_per_user=slowmode_delay,\n )\n\n return Thread(guild=self.guild, state=self._state, data=data)\n\n async def archived_threads(\n self,\n *,\n private: bool = False,\n joined: bool = False,\n limit: Optional[int] = 100,\n before: Optional[Union[Snowflake, datetime.datetime]] = None,\n ) -> AsyncIterator[Thread]:\n \"\"\"Returns an :term:`asynchronous iterator` that iterates over all archived threads in this text channel,\n in order of decreasing ID for joined threads, and decreasing :attr:`Thread.archive_timestamp` otherwise.\n\n You must have :attr:`~Permissions.read_message_history` to do this. If iterating over private threads\n then :attr:`~Permissions.manage_threads` is also required.\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n limit: Optional[:class:`bool`]\n The number of threads to retrieve.\n If ``None``, retrieves every archived thread in the channel. Note, however,\n that this would make it a slow operation.\n before: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]\n Retrieve archived channels before the given date or ID.\n private: :class:`bool`\n Whether to retrieve private archived threads.\n joined: :class:`bool`\n Whether to retrieve private archived threads that you've joined.\n You cannot set ``joined`` to ``True`` and ``private`` to ``False``.\n\n Raises\n ------\n Forbidden\n You do not have permissions to get archived threads.\n HTTPException\n The request to get the archived threads failed.\n ValueError\n ``joined`` was set to ``True`` and ``private`` was set to ``False``. You cannot retrieve public archived\n threads that you have joined.\n\n Yields\n -------\n :class:`Thread`\n The archived threads.\n \"\"\"\n if joined and not private:\n raise ValueError('Cannot retrieve joined public archived threads')\n\n before_timestamp = None\n\n if isinstance(before, datetime.datetime):\n if joined:\n before_timestamp = str(utils.time_snowflake(before, high=False))\n else:\n before_timestamp = before.isoformat()\n elif before is not None:\n if joined:\n before_timestamp = str(before.id)\n else:\n before_timestamp = utils.snowflake_time(before.id).isoformat()\n\n update_before = lambda data: data['thread_metadata']['archive_timestamp']\n endpoint = self.guild._state.http.get_public_archived_threads\n\n if joined:\n update_before = lambda data: data['id']\n endpoint = self.guild._state.http.get_joined_private_archived_threads\n elif private:\n endpoint = self.guild._state.http.get_private_archived_threads\n\n while True:\n retrieve = 100\n if limit is not None:\n if limit <= 0:\n return\n retrieve = max(2, min(retrieve, limit))\n\n data = await endpoint(self.id, before=before_timestamp, limit=retrieve)\n\n threads = data.get('threads', [])\n for raw_thread in threads:\n yield Thread(guild=self.guild, state=self.guild._state, data=raw_thread)\n # Currently the API doesn't let you request less than 2 threads.\n # Bail out early if we had to retrieve more than what the limit was.\n if limit is not None:\n limit -= 1\n if limit <= 0:\n return\n\n if not data.get('has_more', False):\n return\n\n before_timestamp = update_before(threads[-1])\n\n\nclass VocalGuildChannel(discord.abc.Messageable, discord.abc.Connectable, discord.abc.GuildChannel, Hashable):\n __slots__ = (\n 'name',\n 'id',\n 'guild',\n 'nsfw',\n 'bitrate',\n 'user_limit',\n '_state',\n 'position',\n 'slowmode_delay',\n '_overwrites',\n 'category_id',\n 'rtc_region',\n 'video_quality_mode',\n 'last_message_id',\n )\n\n def __init__(self, *, state: ConnectionState, guild: Guild, data: Union[VoiceChannelPayload, StageChannelPayload]):\n self._state: ConnectionState = state\n self.id: int = int(data['id'])\n self._update(guild, data)\n\n async def _get_channel(self) -> Self:\n return self\n\n def _get_voice_client_key(self) -> Tuple[int, str]:\n return self.guild.id, 'guild_id'\n\n def _get_voice_state_pair(self) -> Tuple[int, int]:\n return self.guild.id, self.id\n\n def _update(self, guild: Guild, data: Union[VoiceChannelPayload, StageChannelPayload]) -> None:\n self.guild: Guild = guild\n self.name: str = data['name']\n self.nsfw: bool = data.get('nsfw', False)\n self.rtc_region: Optional[str] = data.get('rtc_region')\n self.video_quality_mode: VideoQualityMode = try_enum(VideoQualityMode, data.get('video_quality_mode', 1))\n self.category_id: Optional[int] = utils._get_as_snowflake(data, 'parent_id')\n self.last_message_id: Optional[int] = utils._get_as_snowflake(data, 'last_message_id')\n self.position: int = data['position']\n self.slowmode_delay = data.get('rate_limit_per_user', 0)\n self.bitrate: int = data['bitrate']\n self.user_limit: int = data['user_limit']\n self._fill_overwrites(data)\n\n @property\n def _sorting_bucket(self) -> int:\n return ChannelType.voice.value\n\n def is_nsfw(self) -> bool:\n \"\"\":class:`bool`: Checks if the channel is NSFW.\n\n .. versionadded:: 2.0\n \"\"\"\n return self.nsfw\n\n @property\n def members(self) -> List[Member]:\n \"\"\"List[:class:`Member`]: Returns all members that are currently inside this voice channel.\"\"\"\n ret = []\n for user_id, state in self.guild._voice_states.items():\n if state.channel and state.channel.id == self.id:\n member = self.guild.get_member(user_id)\n if member is not None:\n ret.append(member)\n return ret\n\n @property\n def voice_states(self) -> Dict[int, VoiceState]:\n \"\"\"Returns a mapping of member IDs who have voice states in this channel.\n\n .. versionadded:: 1.3\n\n .. note::\n\n This function is intentionally low level to replace :attr:`members`\n when the member cache is unavailable.\n\n Returns\n --------\n Mapping[:class:`int`, :class:`VoiceState`]\n The mapping of member ID to a voice state.\n \"\"\"\n # fmt: off\n return {\n key: value\n for key, value in self.guild._voice_states.items()\n if value.channel and value.channel.id == self.id\n }\n # fmt: on\n\n @property\n def scheduled_events(self) -> List[ScheduledEvent]:\n \"\"\"List[:class:`ScheduledEvent`]: Returns all scheduled events for this channel.\n\n .. versionadded:: 2.0\n \"\"\"\n return [event for event in self.guild.scheduled_events if event.channel_id == self.id]\n\n @utils.copy_doc(discord.abc.GuildChannel.permissions_for)\n def permissions_for(self, obj: Union[Member, Role], /) -> Permissions:\n base = super().permissions_for(obj)\n self._apply_implicit_permissions(base)\n\n # voice channels cannot be edited by people who can't connect to them\n # It also implicitly denies all other voice perms\n if not base.connect:\n denied = Permissions.voice()\n denied.update(manage_channels=True, manage_roles=True)\n base.value &= ~denied.value\n return base\n\n @property\n def last_message(self) -> Optional[Message]:\n \"\"\"Retrieves the last message from this channel in cache.\n\n The message might not be valid or point to an existing message.\n\n .. versionadded:: 2.0\n\n .. admonition:: Reliable Fetching\n :class: helpful\n\n For a slightly more reliable method of fetching the\n last message, consider using either :meth:`history`\n or :meth:`fetch_message` with the :attr:`last_message_id`\n attribute.\n\n Returns\n ---------\n Optional[:class:`Message`]\n The last message in this channel or ``None`` if not found.\n \"\"\"\n return self._state._get_message(self.last_message_id) if self.last_message_id else None\n\n def get_partial_message(self, message_id: int, /) -> PartialMessage:\n \"\"\"Creates a :class:`PartialMessage` from the message ID.\n\n This is useful if you want to work with a message and only have its ID without\n doing an unnecessary API call.\n\n .. versionadded:: 2.0\n\n Parameters\n ------------\n message_id: :class:`int`\n The message ID to create a partial message for.\n\n Returns\n ---------\n :class:`PartialMessage`\n The partial message.\n \"\"\"\n\n from .message import PartialMessage\n\n return PartialMessage(channel=self, id=message_id) # type: ignore # VocalGuildChannel is an impl detail\n\n async def delete_messages(self, messages: Iterable[Snowflake], *, reason: Optional[str] = None) -> None:\n \"\"\"|coro|\n\n Deletes a list of messages. This is similar to :meth:`Message.delete`\n except it bulk deletes multiple messages.\n\n As a special case, if the number of messages is 0, then nothing\n is done. If the number of messages is 1 then single message\n delete is done. If it's more than two, then bulk delete is used.\n\n You cannot bulk delete more than 100 messages or messages that\n are older than 14 days old.\n\n You must have :attr:`~Permissions.manage_messages` to do this.\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n messages: Iterable[:class:`abc.Snowflake`]\n An iterable of messages denoting which ones to bulk delete.\n reason: Optional[:class:`str`]\n The reason for deleting the messages. Shows up on the audit log.\n\n Raises\n ------\n ClientException\n The number of messages to delete was more than 100.\n Forbidden\n You do not have proper permissions to delete the messages.\n NotFound\n If single delete, then the message was already deleted.\n HTTPException\n Deleting the messages failed.\n \"\"\"\n if not isinstance(messages, (list, tuple)):\n messages = list(messages)\n\n if len(messages) == 0:\n return # do nothing\n\n if len(messages) == 1:\n message_id: int = messages[0].id\n await self._state.http.delete_message(self.id, message_id)\n return\n\n if len(messages) > 100:\n raise ClientException('Can only bulk delete messages up to 100 messages')\n\n message_ids: SnowflakeList = [m.id for m in messages]\n await self._state.http.delete_messages(self.id, message_ids, reason=reason)\n\n async def purge(\n self,\n *,\n limit: Optional[int] = 100,\n check: Callable[[Message], bool] = MISSING,\n before: Optional[SnowflakeTime] = None,\n after: Optional[SnowflakeTime] = None,\n around: Optional[SnowflakeTime] = None,\n oldest_first: Optional[bool] = None,\n bulk: bool = True,\n reason: Optional[str] = None,\n ) -> List[Message]:\n \"\"\"|coro|\n\n Purges a list of messages that meet the criteria given by the predicate\n ``check``. If a ``check`` is not provided then all messages are deleted\n without discrimination.\n\n You must have :attr:`~Permissions.manage_messages` to\n delete messages even if they are your own.\n Having :attr:`~Permissions.read_message_history` is\n also needed to retrieve message history.\n\n .. versionadded:: 2.0\n\n Examples\n ---------\n\n Deleting bot's messages ::\n\n def is_me(m):\n return m.author == client.user\n\n deleted = await channel.purge(limit=100, check=is_me)\n await channel.send(f'Deleted {len(deleted)} message(s)')\n\n Parameters\n -----------\n limit: Optional[:class:`int`]\n The number of messages to search through. This is not the number\n of messages that will be deleted, though it can be.\n check: Callable[[:class:`Message`], :class:`bool`]\n The function used to check if a message should be deleted.\n It must take a :class:`Message` as its sole parameter.\n before: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]\n Same as ``before`` in :meth:`history`.\n after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]\n Same as ``after`` in :meth:`history`.\n around: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]\n Same as ``around`` in :meth:`history`.\n oldest_first: Optional[:class:`bool`]\n Same as ``oldest_first`` in :meth:`history`.\n bulk: :class:`bool`\n If ``True``, use bulk delete. Setting this to ``False`` is useful for mass-deleting\n a bot's own messages without :attr:`Permissions.manage_messages`. When ``True``, will\n fall back to single delete if messages are older than two weeks.\n reason: Optional[:class:`str`]\n The reason for purging the messages. Shows up on the audit log.\n\n Raises\n -------\n Forbidden\n You do not have proper permissions to do the actions required.\n HTTPException\n Purging the messages failed.\n\n Returns\n --------\n List[:class:`.Message`]\n The list of messages that were deleted.\n \"\"\"\n\n return await discord.abc._purge_helper(\n self,\n limit=limit,\n check=check,\n before=before,\n after=after,\n around=around,\n oldest_first=oldest_first,\n bulk=bulk,\n reason=reason,\n )\n\n async def webhooks(self) -> List[Webhook]:\n \"\"\"|coro|\n\n Gets the list of webhooks from this channel.\n\n You must have :attr:`~.Permissions.manage_webhooks` to do this.\n\n .. versionadded:: 2.0\n\n Raises\n -------\n Forbidden\n You don't have permissions to get the webhooks.\n\n Returns\n --------\n List[:class:`Webhook`]\n The webhooks for this channel.\n \"\"\"\n\n from .webhook import Webhook\n\n data = await self._state.http.channel_webhooks(self.id)\n return [Webhook.from_state(d, state=self._state) for d in data]\n\n async def create_webhook(self, *, name: str, avatar: Optional[bytes] = None, reason: Optional[str] = None) -> Webhook:\n \"\"\"|coro|\n\n Creates a webhook for this channel.\n\n You must have :attr:`~.Permissions.manage_webhooks` to do this.\n\n .. versionadded:: 2.0\n\n Parameters\n -------------\n name: :class:`str`\n The webhook's name.\n avatar: Optional[:class:`bytes`]\n A :term:`py:bytes-like object` representing the webhook's default avatar.\n This operates similarly to :meth:`~ClientUser.edit`.\n reason: Optional[:class:`str`]\n The reason for creating this webhook. Shows up in the audit logs.\n\n Raises\n -------\n HTTPException\n Creating the webhook failed.\n Forbidden\n You do not have permissions to create a webhook.\n\n Returns\n --------\n :class:`Webhook`\n The created webhook.\n \"\"\"\n\n from .webhook import Webhook\n\n if avatar is not None:\n avatar = utils._bytes_to_base64_data(avatar) # type: ignore # Silence reassignment error\n\n data = await self._state.http.create_webhook(self.id, name=str(name), avatar=avatar, reason=reason)\n return Webhook.from_state(data, state=self._state)\n\n\nclass VoiceChannel(VocalGuildChannel):\n \"\"\"Represents a Discord guild voice channel.\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two channels are equal.\n\n .. describe:: x != y\n\n Checks if two channels are not equal.\n\n .. describe:: hash(x)\n\n Returns the channel's hash.\n\n .. describe:: str(x)\n\n Returns the channel's name.\n\n Attributes\n -----------\n name: :class:`str`\n The channel name.\n guild: :class:`Guild`\n The guild the channel belongs to.\n id: :class:`int`\n The channel ID.\n nsfw: :class:`bool`\n If the channel is marked as \"not safe for work\" or \"age restricted\".\n\n .. versionadded:: 2.0\n category_id: Optional[:class:`int`]\n The category channel ID this channel belongs to, if applicable.\n position: :class:`int`\n The position in the channel list. This is a number that starts at 0. e.g. the\n top channel is position 0.\n bitrate: :class:`int`\n The channel's preferred audio bitrate in bits per second.\n user_limit: :class:`int`\n The channel's limit for number of members that can be in a voice channel.\n rtc_region: Optional[:class:`str`]\n The region for the voice channel's voice communication.\n A value of ``None`` indicates automatic voice region detection.\n\n .. versionadded:: 1.7\n\n .. versionchanged:: 2.0\n The type of this attribute has changed to :class:`str`.\n video_quality_mode: :class:`VideoQualityMode`\n The camera video quality for the voice channel's participants.\n\n .. versionadded:: 2.0\n last_message_id: Optional[:class:`int`]\n The last message ID of the message sent to this channel. It may\n *not* point to an existing or valid message.\n\n .. versionadded:: 2.0\n slowmode_delay: :class:`int`\n The number of seconds a member must wait between sending messages\n in this channel. A value of ``0`` denotes that it is disabled.\n Bots and users with :attr:`~Permissions.manage_channels` or\n :attr:`~Permissions.manage_messages` bypass slowmode.\n\n .. versionadded:: 2.2\n \"\"\"\n\n __slots__ = ()\n\n def __repr__(self) -> str:\n attrs = [\n ('id', self.id),\n ('name', self.name),\n ('rtc_region', self.rtc_region),\n ('position', self.position),\n ('bitrate', self.bitrate),\n ('video_quality_mode', self.video_quality_mode),\n ('user_limit', self.user_limit),\n ('category_id', self.category_id),\n ]\n joined = ' '.join('%s=%r' % t for t in attrs)\n return f'<{self.__class__.__name__} {joined}>'\n\n @property\n def _scheduled_event_entity_type(self) -> Optional[EntityType]:\n return EntityType.voice\n\n @property\n def type(self) -> Literal[ChannelType.voice]:\n \"\"\":class:`ChannelType`: The channel's Discord type.\"\"\"\n return ChannelType.voice\n\n @utils.copy_doc(discord.abc.GuildChannel.clone)\n async def clone(self, *, name: Optional[str] = None, reason: Optional[str] = None) -> VoiceChannel:\n return await self._clone_impl({'bitrate': self.bitrate, 'user_limit': self.user_limit}, name=name, reason=reason)\n\n @overload\n async def edit(self) -> None:\n ...\n\n @overload\n async def edit(self, *, position: int, reason: Optional[str] = ...) -> None:\n ...\n\n @overload\n async def edit(\n self,\n *,\n name: str = ...,\n nsfw: bool = ...,\n bitrate: int = ...,\n user_limit: int = ...,\n position: int = ...,\n sync_permissions: int = ...,\n category: Optional[CategoryChannel] = ...,\n overwrites: Mapping[OverwriteKeyT, PermissionOverwrite] = ...,\n rtc_region: Optional[str] = ...,\n video_quality_mode: VideoQualityMode = ...,\n slowmode_delay: int = ...,\n status: Optional[str] = ...,\n reason: Optional[str] = ...,\n ) -> VoiceChannel:\n ...\n\n async def edit(self, *, reason: Optional[str] = None, **options: Any) -> Optional[VoiceChannel]:\n \"\"\"|coro|\n\n Edits the channel.\n\n You must have :attr:`~Permissions.manage_channels` to do this.\n\n .. versionchanged:: 1.3\n The ``overwrites`` keyword-only parameter was added.\n\n .. versionchanged:: 2.0\n Edits are no longer in-place, the newly edited channel is returned instead.\n\n .. versionchanged:: 2.0\n The ``region`` parameter now accepts :class:`str` instead of an enum.\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`TypeError` instead of\n ``InvalidArgument``.\n\n Parameters\n ----------\n name: :class:`str`\n The new channel's name.\n bitrate: :class:`int`\n The new channel's bitrate.\n nsfw: :class:`bool`\n To mark the channel as NSFW or not.\n user_limit: :class:`int`\n The new channel's user limit.\n position: :class:`int`\n The new channel's position.\n sync_permissions: :class:`bool`\n Whether to sync permissions with the channel's new or pre-existing\n category. Defaults to ``False``.\n category: Optional[:class:`CategoryChannel`]\n The new category for this channel. Can be ``None`` to remove the\n category.\n slowmode_delay: :class:`int`\n Specifies the slowmode rate limit for user in this channel, in seconds.\n A value of ``0`` disables slowmode. The maximum value possible is ``21600``.\n reason: Optional[:class:`str`]\n The reason for editing this channel. Shows up on the audit log.\n overwrites: :class:`Mapping`\n A :class:`Mapping` of target (either a role or a member) to\n :class:`PermissionOverwrite` to apply to the channel.\n rtc_region: Optional[:class:`str`]\n The new region for the voice channel's voice communication.\n A value of ``None`` indicates automatic voice region detection.\n\n .. versionadded:: 1.7\n video_quality_mode: :class:`VideoQualityMode`\n The camera video quality for the voice channel's participants.\n\n .. versionadded:: 2.0\n status: Optional[:class:`str`]\n The new voice channel status. It can be up to 500 characters.\n Can be ``None`` to remove the status.\n\n .. versionadded:: 2.4\n\n Raises\n ------\n TypeError\n If the permission overwrite information is not in proper form.\n Forbidden\n You do not have permissions to edit the channel.\n HTTPException\n Editing the channel failed.\n\n Returns\n --------\n Optional[:class:`.VoiceChannel`]\n The newly edited voice channel. If the edit was only positional\n then ``None`` is returned instead.\n \"\"\"\n payload = await self._edit(options, reason=reason)\n if payload is not None:\n # the payload will always be the proper channel payload\n return self.__class__(state=self._state, guild=self.guild, data=payload) # type: ignore\n\n\nclass StageChannel(VocalGuildChannel):\n \"\"\"Represents a Discord guild stage channel.\n\n .. versionadded:: 1.7\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two channels are equal.\n\n .. describe:: x != y\n\n Checks if two channels are not equal.\n\n .. describe:: hash(x)\n\n Returns the channel's hash.\n\n .. describe:: str(x)\n\n Returns the channel's name.\n\n Attributes\n -----------\n name: :class:`str`\n The channel name.\n guild: :class:`Guild`\n The guild the channel belongs to.\n id: :class:`int`\n The channel ID.\n nsfw: :class:`bool`\n If the channel is marked as \"not safe for work\" or \"age restricted\".\n\n .. versionadded:: 2.0\n topic: Optional[:class:`str`]\n The channel's topic. ``None`` if it isn't set.\n category_id: Optional[:class:`int`]\n The category channel ID this channel belongs to, if applicable.\n position: :class:`int`\n The position in the channel list. This is a number that starts at 0. e.g. the\n top channel is position 0.\n bitrate: :class:`int`\n The channel's preferred audio bitrate in bits per second.\n user_limit: :class:`int`\n The channel's limit for number of members that can be in a stage channel.\n rtc_region: Optional[:class:`str`]\n The region for the stage channel's voice communication.\n A value of ``None`` indicates automatic voice region detection.\n video_quality_mode: :class:`VideoQualityMode`\n The camera video quality for the stage channel's participants.\n\n .. versionadded:: 2.0\n last_message_id: Optional[:class:`int`]\n The last message ID of the message sent to this channel. It may\n *not* point to an existing or valid message.\n\n .. versionadded:: 2.2\n slowmode_delay: :class:`int`\n The number of seconds a member must wait between sending messages\n in this channel. A value of ``0`` denotes that it is disabled.\n Bots and users with :attr:`~Permissions.manage_channels` or\n :attr:`~Permissions.manage_messages` bypass slowmode.\n\n .. versionadded:: 2.2\n \"\"\"\n\n __slots__ = ('topic',)\n\n def __repr__(self) -> str:\n attrs = [\n ('id', self.id),\n ('name', self.name),\n ('topic', self.topic),\n ('rtc_region', self.rtc_region),\n ('position', self.position),\n ('bitrate', self.bitrate),\n ('video_quality_mode', self.video_quality_mode),\n ('user_limit', self.user_limit),\n ('category_id', self.category_id),\n ]\n joined = ' '.join('%s=%r' % t for t in attrs)\n return f'<{self.__class__.__name__} {joined}>'\n\n def _update(self, guild: Guild, data: StageChannelPayload) -> None:\n super()._update(guild, data)\n self.topic: Optional[str] = data.get('topic')\n\n @property\n def _scheduled_event_entity_type(self) -> Optional[EntityType]:\n return EntityType.stage_instance\n\n @property\n def requesting_to_speak(self) -> List[Member]:\n \"\"\"List[:class:`Member`]: A list of members who are requesting to speak in the stage channel.\"\"\"\n return [member for member in self.members if member.voice and member.voice.requested_to_speak_at is not None]\n\n @property\n def speakers(self) -> List[Member]:\n \"\"\"List[:class:`Member`]: A list of members who have been permitted to speak in the stage channel.\n\n .. versionadded:: 2.0\n \"\"\"\n return [\n member\n for member in self.members\n if member.voice and not member.voice.suppress and member.voice.requested_to_speak_at is None\n ]\n\n @property\n def listeners(self) -> List[Member]:\n \"\"\"List[:class:`Member`]: A list of members who are listening in the stage channel.\n\n .. versionadded:: 2.0\n \"\"\"\n return [member for member in self.members if member.voice and member.voice.suppress]\n\n @property\n def moderators(self) -> List[Member]:\n \"\"\"List[:class:`Member`]: A list of members who are moderating the stage channel.\n\n .. versionadded:: 2.0\n \"\"\"\n required_permissions = Permissions.stage_moderator()\n return [member for member in self.members if self.permissions_for(member) >= required_permissions]\n\n @property\n def type(self) -> Literal[ChannelType.stage_voice]:\n \"\"\":class:`ChannelType`: The channel's Discord type.\"\"\"\n return ChannelType.stage_voice\n\n @utils.copy_doc(discord.abc.GuildChannel.clone)\n async def clone(self, *, name: Optional[str] = None, reason: Optional[str] = None) -> StageChannel:\n return await self._clone_impl({}, name=name, reason=reason)\n\n @property\n def instance(self) -> Optional[StageInstance]:\n \"\"\"Optional[:class:`StageInstance`]: The running stage instance of the stage channel.\n\n .. versionadded:: 2.0\n \"\"\"\n return utils.get(self.guild.stage_instances, channel_id=self.id)\n\n async def create_instance(\n self,\n *,\n topic: str,\n privacy_level: PrivacyLevel = MISSING,\n send_start_notification: bool = False,\n scheduled_event: Snowflake = MISSING,\n reason: Optional[str] = None,\n ) -> StageInstance:\n \"\"\"|coro|\n\n Create a stage instance.\n\n You must have :attr:`~Permissions.manage_channels` to do this.\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n topic: :class:`str`\n The stage instance's topic.\n privacy_level: :class:`PrivacyLevel`\n The stage instance's privacy level. Defaults to :attr:`PrivacyLevel.guild_only`.\n send_start_notification: :class:`bool`\n Whether to send a start notification. This sends a push notification to @everyone if ``True``. Defaults to ``False``.\n You must have :attr:`~Permissions.mention_everyone` to do this.\n\n .. versionadded:: 2.3\n scheduled_event: :class:`~discord.abc.Snowflake`\n The guild scheduled event associated with the stage instance.\n\n .. versionadded:: 2.4\n reason: :class:`str`\n The reason the stage instance was created. Shows up on the audit log.\n\n Raises\n ------\n TypeError\n If the ``privacy_level`` parameter is not the proper type.\n Forbidden\n You do not have permissions to create a stage instance.\n HTTPException\n Creating a stage instance failed.\n\n Returns\n --------\n :class:`StageInstance`\n The newly created stage instance.\n \"\"\"\n\n payload: Dict[str, Any] = {'channel_id': self.id, 'topic': topic}\n\n if privacy_level is not MISSING:\n if not isinstance(privacy_level, PrivacyLevel):\n raise TypeError('privacy_level field must be of type PrivacyLevel')\n\n payload['privacy_level'] = privacy_level.value\n\n if scheduled_event is not MISSING:\n payload['guild_scheduled_event_id'] = scheduled_event.id\n\n payload['send_start_notification'] = send_start_notification\n\n data = await self._state.http.create_stage_instance(**payload, reason=reason)\n return StageInstance(guild=self.guild, state=self._state, data=data)\n\n async def fetch_instance(self) -> StageInstance:\n \"\"\"|coro|\n\n Gets the running :class:`StageInstance`.\n\n .. versionadded:: 2.0\n\n Raises\n -------\n NotFound\n The stage instance or channel could not be found.\n HTTPException\n Getting the stage instance failed.\n\n Returns\n --------\n :class:`StageInstance`\n The stage instance.\n \"\"\"\n data = await self._state.http.get_stage_instance(self.id)\n return StageInstance(guild=self.guild, state=self._state, data=data)\n\n @overload\n async def edit(self) -> None:\n ...\n\n @overload\n async def edit(self, *, position: int, reason: Optional[str] = ...) -> None:\n ...\n\n @overload\n async def edit(\n self,\n *,\n name: str = ...,\n nsfw: bool = ...,\n bitrate: int = ...,\n user_limit: int = ...,\n position: int = ...,\n sync_permissions: int = ...,\n category: Optional[CategoryChannel] = ...,\n overwrites: Mapping[OverwriteKeyT, PermissionOverwrite] = ...,\n rtc_region: Optional[str] = ...,\n video_quality_mode: VideoQualityMode = ...,\n slowmode_delay: int = ...,\n reason: Optional[str] = ...,\n ) -> StageChannel:\n ...\n\n async def edit(self, *, reason: Optional[str] = None, **options: Any) -> Optional[StageChannel]:\n \"\"\"|coro|\n\n Edits the channel.\n\n You must have :attr:`~Permissions.manage_channels` to do this.\n\n .. versionchanged:: 2.0\n The ``topic`` parameter must now be set via :attr:`create_instance`.\n\n .. versionchanged:: 2.0\n Edits are no longer in-place, the newly edited channel is returned instead.\n\n .. versionchanged:: 2.0\n The ``region`` parameter now accepts :class:`str` instead of an enum.\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`TypeError` instead of\n ``InvalidArgument``.\n\n Parameters\n ----------\n name: :class:`str`\n The new channel's name.\n bitrate: :class:`int`\n The new channel's bitrate.\n position: :class:`int`\n The new channel's position.\n nsfw: :class:`bool`\n To mark the channel as NSFW or not.\n user_limit: :class:`int`\n The new channel's user limit.\n sync_permissions: :class:`bool`\n Whether to sync permissions with the channel's new or pre-existing\n category. Defaults to ``False``.\n category: Optional[:class:`CategoryChannel`]\n The new category for this channel. Can be ``None`` to remove the\n category.\n slowmode_delay: :class:`int`\n Specifies the slowmode rate limit for user in this channel, in seconds.\n A value of ``0`` disables slowmode. The maximum value possible is ``21600``.\n reason: Optional[:class:`str`]\n The reason for editing this channel. Shows up on the audit log.\n overwrites: :class:`Mapping`\n A :class:`Mapping` of target (either a role or a member) to\n :class:`PermissionOverwrite` to apply to the channel.\n rtc_region: Optional[:class:`str`]\n The new region for the stage channel's voice communication.\n A value of ``None`` indicates automatic voice region detection.\n video_quality_mode: :class:`VideoQualityMode`\n The camera video quality for the stage channel's participants.\n\n .. versionadded:: 2.0\n\n Raises\n ------\n ValueError\n If the permission overwrite information is not in proper form.\n Forbidden\n You do not have permissions to edit the channel.\n HTTPException\n Editing the channel failed.\n\n Returns\n --------\n Optional[:class:`.StageChannel`]\n The newly edited stage channel. If the edit was only positional\n then ``None`` is returned instead.\n \"\"\"\n\n payload = await self._edit(options, reason=reason)\n if payload is not None:\n # the payload will always be the proper channel payload\n return self.__class__(state=self._state, guild=self.guild, data=payload) # type: ignore\n\n\nclass CategoryChannel(discord.abc.GuildChannel, Hashable):\n \"\"\"Represents a Discord channel category.\n\n These are useful to group channels to logical compartments.\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two channels are equal.\n\n .. describe:: x != y\n\n Checks if two channels are not equal.\n\n .. describe:: hash(x)\n\n Returns the category's hash.\n\n .. describe:: str(x)\n\n Returns the category's name.\n\n Attributes\n -----------\n name: :class:`str`\n The category name.\n guild: :class:`Guild`\n The guild the category belongs to.\n id: :class:`int`\n The category channel ID.\n position: :class:`int`\n The position in the category list. This is a number that starts at 0. e.g. the\n top category is position 0.\n nsfw: :class:`bool`\n If the channel is marked as \"not safe for work\".\n\n .. note::\n\n To check if the channel or the guild of that channel are marked as NSFW, consider :meth:`is_nsfw` instead.\n \"\"\"\n\n __slots__ = ('name', 'id', 'guild', 'nsfw', '_state', 'position', '_overwrites', 'category_id')\n\n def __init__(self, *, state: ConnectionState, guild: Guild, data: CategoryChannelPayload):\n self._state: ConnectionState = state\n self.id: int = int(data['id'])\n self._update(guild, data)\n\n def __repr__(self) -> str:\n return f''\n\n def _update(self, guild: Guild, data: CategoryChannelPayload) -> None:\n self.guild: Guild = guild\n self.name: str = data['name']\n self.category_id: Optional[int] = utils._get_as_snowflake(data, 'parent_id')\n self.nsfw: bool = data.get('nsfw', False)\n self.position: int = data['position']\n self._fill_overwrites(data)\n\n @property\n def _sorting_bucket(self) -> int:\n return ChannelType.category.value\n\n @property\n def _scheduled_event_entity_type(self) -> Optional[EntityType]:\n return None\n\n @property\n def type(self) -> Literal[ChannelType.category]:\n \"\"\":class:`ChannelType`: The channel's Discord type.\"\"\"\n return ChannelType.category\n\n def is_nsfw(self) -> bool:\n \"\"\":class:`bool`: Checks if the category is NSFW.\"\"\"\n return self.nsfw\n\n @utils.copy_doc(discord.abc.GuildChannel.clone)\n async def clone(self, *, name: Optional[str] = None, reason: Optional[str] = None) -> CategoryChannel:\n return await self._clone_impl({'nsfw': self.nsfw}, name=name, reason=reason)\n\n @overload\n async def edit(self) -> None:\n ...\n\n @overload\n async def edit(self, *, position: int, reason: Optional[str] = ...) -> None:\n ...\n\n @overload\n async def edit(\n self,\n *,\n name: str = ...,\n position: int = ...,\n nsfw: bool = ...,\n overwrites: Mapping[OverwriteKeyT, PermissionOverwrite] = ...,\n reason: Optional[str] = ...,\n ) -> CategoryChannel:\n ...\n\n async def edit(self, *, reason: Optional[str] = None, **options: Any) -> Optional[CategoryChannel]:\n \"\"\"|coro|\n\n Edits the channel.\n\n You must have :attr:`~Permissions.manage_channels` to do this.\n\n .. versionchanged:: 1.3\n The ``overwrites`` keyword-only parameter was added.\n\n .. versionchanged:: 2.0\n Edits are no longer in-place, the newly edited channel is returned instead.\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`TypeError` or\n :exc:`ValueError` instead of ``InvalidArgument``.\n\n Parameters\n ----------\n name: :class:`str`\n The new category's name.\n position: :class:`int`\n The new category's position.\n nsfw: :class:`bool`\n To mark the category as NSFW or not.\n reason: Optional[:class:`str`]\n The reason for editing this category. Shows up on the audit log.\n overwrites: :class:`Mapping`\n A :class:`Mapping` of target (either a role or a member) to\n :class:`PermissionOverwrite` to apply to the channel.\n\n Raises\n ------\n ValueError\n If position is less than 0 or greater than the number of categories.\n TypeError\n The overwrite information is not in proper form.\n Forbidden\n You do not have permissions to edit the category.\n HTTPException\n Editing the category failed.\n\n Returns\n --------\n Optional[:class:`.CategoryChannel`]\n The newly edited category channel. If the edit was only positional\n then ``None`` is returned instead.\n \"\"\"\n\n payload = await self._edit(options, reason=reason)\n if payload is not None:\n # the payload will always be the proper channel payload\n return self.__class__(state=self._state, guild=self.guild, data=payload) # type: ignore\n\n @utils.copy_doc(discord.abc.GuildChannel.move)\n async def move(self, **kwargs: Any) -> None:\n kwargs.pop('category', None)\n await super().move(**kwargs)\n\n @property\n def channels(self) -> List[GuildChannelType]:\n \"\"\"List[:class:`abc.GuildChannel`]: Returns the channels that are under this category.\n\n These are sorted by the official Discord UI, which places voice channels below the text channels.\n \"\"\"\n\n def comparator(channel):\n return (not isinstance(channel, TextChannel), channel.position)\n\n ret = [c for c in self.guild.channels if c.category_id == self.id]\n ret.sort(key=comparator)\n return ret\n\n @property\n def text_channels(self) -> List[TextChannel]:\n \"\"\"List[:class:`TextChannel`]: Returns the text channels that are under this category.\"\"\"\n ret = [c for c in self.guild.channels if c.category_id == self.id and isinstance(c, TextChannel)]\n ret.sort(key=lambda c: (c.position, c.id))\n return ret\n\n @property\n def voice_channels(self) -> List[VoiceChannel]:\n \"\"\"List[:class:`VoiceChannel`]: Returns the voice channels that are under this category.\"\"\"\n ret = [c for c in self.guild.channels if c.category_id == self.id and isinstance(c, VoiceChannel)]\n ret.sort(key=lambda c: (c.position, c.id))\n return ret\n\n @property\n def stage_channels(self) -> List[StageChannel]:\n \"\"\"List[:class:`StageChannel`]: Returns the stage channels that are under this category.\n\n .. versionadded:: 1.7\n \"\"\"\n ret = [c for c in self.guild.channels if c.category_id == self.id and isinstance(c, StageChannel)]\n ret.sort(key=lambda c: (c.position, c.id))\n return ret\n\n @property\n def forums(self) -> List[ForumChannel]:\n \"\"\"List[:class:`ForumChannel`]: Returns the forum channels that are under this category.\n\n .. versionadded:: 2.4\n \"\"\"\n r = [c for c in self.guild.channels if c.category_id == self.id and isinstance(c, ForumChannel)]\n r.sort(key=lambda c: (c.position, c.id))\n return r\n\n async def create_text_channel(self, name: str, **options: Any) -> TextChannel:\n \"\"\"|coro|\n\n A shortcut method to :meth:`Guild.create_text_channel` to create a :class:`TextChannel` in the category.\n\n Returns\n -------\n :class:`TextChannel`\n The channel that was just created.\n \"\"\"\n return await self.guild.create_text_channel(name, category=self, **options)\n\n async def create_voice_channel(self, name: str, **options: Any) -> VoiceChannel:\n \"\"\"|coro|\n\n A shortcut method to :meth:`Guild.create_voice_channel` to create a :class:`VoiceChannel` in the category.\n\n Returns\n -------\n :class:`VoiceChannel`\n The channel that was just created.\n \"\"\"\n return await self.guild.create_voice_channel(name, category=self, **options)\n\n async def create_stage_channel(self, name: str, **options: Any) -> StageChannel:\n \"\"\"|coro|\n\n A shortcut method to :meth:`Guild.create_stage_channel` to create a :class:`StageChannel` in the category.\n\n .. versionadded:: 1.7\n\n Returns\n -------\n :class:`StageChannel`\n The channel that was just created.\n \"\"\"\n return await self.guild.create_stage_channel(name, category=self, **options)\n\n async def create_forum(self, name: str, **options: Any) -> ForumChannel:\n \"\"\"|coro|\n\n A shortcut method to :meth:`Guild.create_forum` to create a :class:`ForumChannel` in the category.\n\n .. versionadded:: 2.0\n\n Returns\n --------\n :class:`ForumChannel`\n The channel that was just created.\n \"\"\"\n return await self.guild.create_forum(name, category=self, **options)\n\n\nclass ForumTag(Hashable):\n \"\"\"Represents a forum tag that can be applied to a thread within a :class:`ForumChannel`.\n\n .. versionadded:: 2.1\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two forum tags are equal.\n\n .. describe:: x != y\n\n Checks if two forum tags are not equal.\n\n .. describe:: hash(x)\n\n Returns the forum tag's hash.\n\n .. describe:: str(x)\n\n Returns the forum tag's name.\n\n\n Attributes\n -----------\n id: :class:`int`\n The ID of the tag. If this was manually created then the ID will be ``0``.\n name: :class:`str`\n The name of the tag. Can only be up to 20 characters.\n moderated: :class:`bool`\n Whether this tag can only be added or removed by a moderator with\n the :attr:`~Permissions.manage_threads` permission.\n emoji: Optional[:class:`PartialEmoji`]\n The emoji that is used to represent this tag.\n Note that if the emoji is a custom emoji, it will *not* have name information.\n \"\"\"\n\n __slots__ = ('name', 'id', 'moderated', 'emoji')\n\n def __init__(self, *, name: str, emoji: Optional[EmojiInputType] = None, moderated: bool = False) -> None:\n self.name: str = name\n self.id: int = 0\n self.moderated: bool = moderated\n self.emoji: Optional[PartialEmoji] = None\n if isinstance(emoji, _EmojiTag):\n self.emoji = emoji._to_partial()\n elif isinstance(emoji, str):\n self.emoji = PartialEmoji.from_str(emoji)\n elif emoji is not None:\n raise TypeError(f'emoji must be a Emoji, PartialEmoji, str or None not {emoji.__class__.__name__}')\n\n @classmethod\n def from_data(cls, *, state: ConnectionState, data: ForumTagPayload) -> Self:\n self = cls.__new__(cls)\n self.name = data['name']\n self.id = int(data['id'])\n self.moderated = data.get('moderated', False)\n\n emoji_name = data['emoji_name'] or ''\n emoji_id = utils._get_as_snowflake(data, 'emoji_id') or None # Coerce 0 -> None\n if not emoji_name and not emoji_id:\n self.emoji = None\n else:\n self.emoji = PartialEmoji.with_state(state=state, name=emoji_name, id=emoji_id)\n return self\n\n def to_dict(self) -> Dict[str, Any]:\n payload: Dict[str, Any] = {\n 'name': self.name,\n 'moderated': self.moderated,\n }\n if self.emoji is not None:\n payload.update(self.emoji._to_forum_tag_payload())\n else:\n payload.update(emoji_id=None, emoji_name=None)\n\n if self.id:\n payload['id'] = self.id\n\n return payload\n\n def __repr__(self) -> str:\n return f''\n\n def __str__(self) -> str:\n return self.name\n\n\nclass ForumChannel(discord.abc.GuildChannel, Hashable):\n \"\"\"Represents a Discord guild forum channel.\n\n .. versionadded:: 2.0\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two forums are equal.\n\n .. describe:: x != y\n\n Checks if two forums are not equal.\n\n .. describe:: hash(x)\n\n Returns the forum's hash.\n\n .. describe:: str(x)\n\n Returns the forum's name.\n\n Attributes\n -----------\n name: :class:`str`\n The forum name.\n guild: :class:`Guild`\n The guild the forum belongs to.\n id: :class:`int`\n The forum ID.\n category_id: Optional[:class:`int`]\n The category channel ID this forum belongs to, if applicable.\n topic: Optional[:class:`str`]\n The forum's topic. ``None`` if it doesn't exist. Called \"Guidelines\" in the UI.\n Can be up to 4096 characters long.\n position: :class:`int`\n The position in the channel list. This is a number that starts at 0. e.g. the\n top channel is position 0.\n last_message_id: Optional[:class:`int`]\n The last thread ID that was created on this forum. This technically also\n coincides with the message ID that started the thread that was created.\n It may *not* point to an existing or valid thread or message.\n slowmode_delay: :class:`int`\n The number of seconds a member must wait between creating threads\n in this forum. A value of ``0`` denotes that it is disabled.\n Bots and users with :attr:`~Permissions.manage_channels` or\n :attr:`~Permissions.manage_messages` bypass slowmode.\n nsfw: :class:`bool`\n If the forum is marked as \"not safe for work\" or \"age restricted\".\n default_auto_archive_duration: :class:`int`\n The default auto archive duration in minutes for threads created in this forum.\n default_thread_slowmode_delay: :class:`int`\n The default slowmode delay in seconds for threads created in this forum.\n\n .. versionadded:: 2.1\n default_reaction_emoji: Optional[:class:`PartialEmoji`]\n The default reaction emoji for threads created in this forum to show in the\n add reaction button.\n\n .. versionadded:: 2.1\n default_layout: :class:`ForumLayoutType`\n The default layout for posts in this forum channel.\n Defaults to :attr:`ForumLayoutType.not_set`.\n\n .. versionadded:: 2.2\n default_sort_order: Optional[:class:`ForumOrderType`]\n The default sort order for posts in this forum channel.\n\n .. versionadded:: 2.3\n \"\"\"\n\n __slots__ = (\n 'name',\n 'id',\n 'guild',\n 'topic',\n '_state',\n '_flags',\n '_type',\n 'nsfw',\n 'category_id',\n 'position',\n 'slowmode_delay',\n '_overwrites',\n 'last_message_id',\n 'default_auto_archive_duration',\n 'default_thread_slowmode_delay',\n 'default_reaction_emoji',\n 'default_layout',\n 'default_sort_order',\n '_available_tags',\n '_flags',\n )\n\n def __init__(self, *, state: ConnectionState, guild: Guild, data: Union[ForumChannelPayload, MediaChannelPayload]):\n self._state: ConnectionState = state\n self.id: int = int(data['id'])\n self._type: Literal[15, 16] = data['type']\n self._update(guild, data)\n\n def __repr__(self) -> str:\n attrs = [\n ('id', self.id),\n ('name', self.name),\n ('position', self.position),\n ('nsfw', self.nsfw),\n ('category_id', self.category_id),\n ]\n joined = ' '.join('%s=%r' % t for t in attrs)\n return f'<{self.__class__.__name__} {joined}>'\n\n def _update(self, guild: Guild, data: Union[ForumChannelPayload, MediaChannelPayload]) -> None:\n self.guild: Guild = guild\n self.name: str = data['name']\n self.category_id: Optional[int] = utils._get_as_snowflake(data, 'parent_id')\n self.topic: Optional[str] = data.get('topic')\n self.position: int = data['position']\n self.nsfw: bool = data.get('nsfw', False)\n self.slowmode_delay: int = data.get('rate_limit_per_user', 0)\n self.default_auto_archive_duration: ThreadArchiveDuration = data.get('default_auto_archive_duration', 1440)\n self.last_message_id: Optional[int] = utils._get_as_snowflake(data, 'last_message_id')\n # This takes advantage of the fact that dicts are ordered since Python 3.7\n tags = [ForumTag.from_data(state=self._state, data=tag) for tag in data.get('available_tags', [])]\n self.default_thread_slowmode_delay: int = data.get('default_thread_rate_limit_per_user', 0)\n self.default_layout: ForumLayoutType = try_enum(ForumLayoutType, data.get('default_forum_layout', 0))\n self._available_tags: Dict[int, ForumTag] = {tag.id: tag for tag in tags}\n\n self.default_reaction_emoji: Optional[PartialEmoji] = None\n default_reaction_emoji = data.get('default_reaction_emoji')\n if default_reaction_emoji:\n self.default_reaction_emoji = PartialEmoji.with_state(\n state=self._state,\n id=utils._get_as_snowflake(default_reaction_emoji, 'emoji_id') or None, # Coerce 0 -> None\n name=default_reaction_emoji.get('emoji_name') or '',\n )\n\n self.default_sort_order: Optional[ForumOrderType] = None\n default_sort_order = data.get('default_sort_order')\n if default_sort_order is not None:\n self.default_sort_order = try_enum(ForumOrderType, default_sort_order)\n\n self._flags: int = data.get('flags', 0)\n self._fill_overwrites(data)\n\n @property\n def type(self) -> Literal[ChannelType.forum, ChannelType.media]:\n \"\"\":class:`ChannelType`: The channel's Discord type.\"\"\"\n if self._type == 16:\n return ChannelType.media\n return ChannelType.forum\n\n @property\n def _sorting_bucket(self) -> int:\n return ChannelType.text.value\n\n @property\n def _scheduled_event_entity_type(self) -> Optional[EntityType]:\n return None\n\n @utils.copy_doc(discord.abc.GuildChannel.permissions_for)\n def permissions_for(self, obj: Union[Member, Role], /) -> Permissions:\n base = super().permissions_for(obj)\n self._apply_implicit_permissions(base)\n\n # text channels do not have voice related permissions\n denied = Permissions.voice()\n base.value &= ~denied.value\n return base\n\n def get_thread(self, thread_id: int, /) -> Optional[Thread]:\n \"\"\"Returns a thread with the given ID.\n\n .. note::\n\n This does not always retrieve archived threads, as they are not retained in the internal\n cache. Use :func:`Guild.fetch_channel` instead.\n\n .. versionadded:: 2.2\n\n Parameters\n -----------\n thread_id: :class:`int`\n The ID to search for.\n\n Returns\n --------\n Optional[:class:`Thread`]\n The returned thread or ``None`` if not found.\n \"\"\"\n thread = self.guild.get_thread(thread_id)\n if thread is not None and thread.parent_id == self.id:\n return thread\n return None\n\n @property\n def threads(self) -> List[Thread]:\n \"\"\"List[:class:`Thread`]: Returns all the threads that you can see.\"\"\"\n return [thread for thread in self.guild._threads.values() if thread.parent_id == self.id]\n\n @property\n def flags(self) -> ChannelFlags:\n \"\"\":class:`ChannelFlags`: The flags associated with this thread.\n\n .. versionadded:: 2.1\n \"\"\"\n return ChannelFlags._from_value(self._flags)\n\n @property\n def available_tags(self) -> Sequence[ForumTag]:\n \"\"\"Sequence[:class:`ForumTag`]: Returns all the available tags for this forum.\n\n .. versionadded:: 2.1\n \"\"\"\n return utils.SequenceProxy(self._available_tags.values())\n\n def get_tag(self, tag_id: int, /) -> Optional[ForumTag]:\n \"\"\"Returns the tag with the given ID.\n\n .. versionadded:: 2.1\n\n Parameters\n ----------\n tag_id: :class:`int`\n The ID to search for.\n\n Returns\n -------\n Optional[:class:`ForumTag`]\n The tag with the given ID, or ``None`` if not found.\n \"\"\"\n return self._available_tags.get(tag_id)\n\n def is_nsfw(self) -> bool:\n \"\"\":class:`bool`: Checks if the forum is NSFW.\"\"\"\n return self.nsfw\n\n def is_media(self) -> bool:\n \"\"\":class:`bool`: Checks if the channel is a media channel.\n\n .. versionadded:: 2.4\n \"\"\"\n return self._type == ChannelType.media.value\n\n @utils.copy_doc(discord.abc.GuildChannel.clone)\n async def clone(self, *, name: Optional[str] = None, reason: Optional[str] = None) -> ForumChannel:\n return await self._clone_impl(\n {'topic': self.topic, 'nsfw': self.nsfw, 'rate_limit_per_user': self.slowmode_delay}, name=name, reason=reason\n )\n\n @overload\n async def edit(self) -> None:\n ...\n\n @overload\n async def edit(self, *, position: int, reason: Optional[str] = ...) -> None:\n ...\n\n @overload\n async def edit(\n self,\n *,\n reason: Optional[str] = ...,\n name: str = ...,\n topic: str = ...,\n position: int = ...,\n nsfw: bool = ...,\n sync_permissions: bool = ...,\n category: Optional[CategoryChannel] = ...,\n slowmode_delay: int = ...,\n default_auto_archive_duration: ThreadArchiveDuration = ...,\n type: ChannelType = ...,\n overwrites: Mapping[OverwriteKeyT, PermissionOverwrite] = ...,\n available_tags: Sequence[ForumTag] = ...,\n default_thread_slowmode_delay: int = ...,\n default_reaction_emoji: Optional[EmojiInputType] = ...,\n default_layout: ForumLayoutType = ...,\n default_sort_order: ForumOrderType = ...,\n require_tag: bool = ...,\n ) -> ForumChannel:\n ...\n\n async def edit(self, *, reason: Optional[str] = None, **options: Any) -> Optional[ForumChannel]:\n \"\"\"|coro|\n\n Edits the forum.\n\n You must have :attr:`~Permissions.manage_channels` to do this.\n\n Parameters\n ----------\n name: :class:`str`\n The new forum name.\n topic: :class:`str`\n The new forum's topic.\n position: :class:`int`\n The new forum's position.\n nsfw: :class:`bool`\n To mark the forum as NSFW or not.\n sync_permissions: :class:`bool`\n Whether to sync permissions with the forum's new or pre-existing\n category. Defaults to ``False``.\n category: Optional[:class:`CategoryChannel`]\n The new category for this forum. Can be ``None`` to remove the\n category.\n slowmode_delay: :class:`int`\n Specifies the slowmode rate limit for user in this forum, in seconds.\n A value of ``0`` disables slowmode. The maximum value possible is ``21600``.\n type: :class:`ChannelType`\n Change the type of this text forum. Currently, only conversion between\n :attr:`ChannelType.text` and :attr:`ChannelType.news` is supported. This\n is only available to guilds that contain ``NEWS`` in :attr:`Guild.features`.\n reason: Optional[:class:`str`]\n The reason for editing this forum. Shows up on the audit log.\n overwrites: :class:`Mapping`\n A :class:`Mapping` of target (either a role or a member) to\n :class:`PermissionOverwrite` to apply to the forum.\n default_auto_archive_duration: :class:`int`\n The new default auto archive duration in minutes for threads created in this channel.\n Must be one of ``60``, ``1440``, ``4320``, or ``10080``.\n available_tags: Sequence[:class:`ForumTag`]\n The new available tags for this forum.\n\n .. versionadded:: 2.1\n default_thread_slowmode_delay: :class:`int`\n The new default slowmode delay for threads in this channel.\n\n .. versionadded:: 2.1\n default_reaction_emoji: Optional[Union[:class:`Emoji`, :class:`PartialEmoji`, :class:`str`]]\n The new default reaction emoji for threads in this channel.\n\n .. versionadded:: 2.1\n default_layout: :class:`ForumLayoutType`\n The new default layout for posts in this forum.\n\n .. versionadded:: 2.2\n default_sort_order: Optional[:class:`ForumOrderType`]\n The new default sort order for posts in this forum.\n\n .. versionadded:: 2.3\n require_tag: :class:`bool`\n Whether to require a tag for threads in this channel or not.\n\n .. versionadded:: 2.1\n\n Raises\n ------\n ValueError\n The new ``position`` is less than 0 or greater than the number of channels.\n TypeError\n The permission overwrite information is not in proper form or a type\n is not the expected type.\n Forbidden\n You do not have permissions to edit the forum.\n HTTPException\n Editing the forum failed.\n\n Returns\n --------\n Optional[:class:`.ForumChannel`]\n The newly edited forum channel. If the edit was only positional\n then ``None`` is returned instead.\n \"\"\"\n\n try:\n tags: Sequence[ForumTag] = options.pop('available_tags')\n except KeyError:\n pass\n else:\n options['available_tags'] = [tag.to_dict() for tag in tags]\n\n try:\n default_reaction_emoji: Optional[EmojiInputType] = options.pop('default_reaction_emoji')\n except KeyError:\n pass\n else:\n if default_reaction_emoji is None:\n options['default_reaction_emoji'] = None\n elif isinstance(default_reaction_emoji, _EmojiTag):\n options['default_reaction_emoji'] = default_reaction_emoji._to_partial()._to_forum_tag_payload()\n elif isinstance(default_reaction_emoji, str):\n options['default_reaction_emoji'] = PartialEmoji.from_str(default_reaction_emoji)._to_forum_tag_payload()\n\n try:\n require_tag = options.pop('require_tag')\n except KeyError:\n pass\n else:\n flags = self.flags\n flags.require_tag = require_tag\n options['flags'] = flags.value\n\n try:\n layout = options.pop('default_layout')\n except KeyError:\n pass\n else:\n if not isinstance(layout, ForumLayoutType):\n raise TypeError(f'default_layout parameter must be a ForumLayoutType not {layout.__class__.__name__}')\n\n options['default_forum_layout'] = layout.value\n\n try:\n sort_order = options.pop('default_sort_order')\n except KeyError:\n pass\n else:\n if sort_order is None:\n options['default_sort_order'] = None\n else:\n if not isinstance(sort_order, ForumOrderType):\n raise TypeError(\n f'default_sort_order parameter must be a ForumOrderType not {sort_order.__class__.__name__}'\n )\n\n options['default_sort_order'] = sort_order.value\n\n payload = await self._edit(options, reason=reason)\n if payload is not None:\n # the payload will always be the proper channel payload\n return self.__class__(state=self._state, guild=self.guild, data=payload) # type: ignore\n\n async def create_tag(\n self,\n *,\n name: str,\n emoji: Optional[PartialEmoji] = None,\n moderated: bool = False,\n reason: Optional[str] = None,\n ) -> ForumTag:\n \"\"\"|coro|\n\n Creates a new tag in this forum.\n\n You must have :attr:`~Permissions.manage_channels` to do this.\n\n Parameters\n ----------\n name: :class:`str`\n The name of the tag. Can only be up to 20 characters.\n emoji: Optional[Union[:class:`str`, :class:`PartialEmoji`]]\n The emoji to use for the tag.\n moderated: :class:`bool`\n Whether the tag can only be applied by moderators.\n reason: Optional[:class:`str`]\n The reason for creating this tag. Shows up on the audit log.\n\n Raises\n ------\n Forbidden\n You do not have permissions to create a tag in this forum.\n HTTPException\n Creating the tag failed.\n\n Returns\n -------\n :class:`ForumTag`\n The newly created tag.\n \"\"\"\n\n prior = list(self._available_tags.values())\n result = ForumTag(name=name, emoji=emoji, moderated=moderated)\n prior.append(result)\n payload = await self._state.http.edit_channel(\n self.id, reason=reason, available_tags=[tag.to_dict() for tag in prior]\n )\n try:\n result.id = int(payload['available_tags'][-1]['id']) # type: ignore\n except (KeyError, IndexError, ValueError):\n pass\n\n return result\n\n async def create_thread(\n self,\n *,\n name: str,\n auto_archive_duration: ThreadArchiveDuration = MISSING,\n slowmode_delay: Optional[int] = None,\n content: Optional[str] = None,\n tts: bool = False,\n embed: Embed = MISSING,\n embeds: Sequence[Embed] = MISSING,\n file: File = MISSING,\n files: Sequence[File] = MISSING,\n stickers: Sequence[Union[GuildSticker, StickerItem]] = MISSING,\n allowed_mentions: AllowedMentions = MISSING,\n mention_author: bool = MISSING,\n applied_tags: Sequence[ForumTag] = MISSING,\n view: View = MISSING,\n suppress_embeds: bool = False,\n reason: Optional[str] = None,\n ) -> ThreadWithMessage:\n \"\"\"|coro|\n\n Creates a thread in this forum.\n\n This thread is a public thread with the initial message given. Currently in order\n to start a thread in this forum, the user needs :attr:`~discord.Permissions.send_messages`.\n\n You must send at least one of ``content``, ``embed``, ``embeds``, ``file``, ``files``,\n or ``view`` to create a thread in a forum, since forum channels must have a starter message.\n\n Parameters\n -----------\n name: :class:`str`\n The name of the thread.\n auto_archive_duration: :class:`int`\n The duration in minutes before a thread is automatically hidden from the channel list.\n If not provided, the channel's default auto archive duration is used.\n\n Must be one of ``60``, ``1440``, ``4320``, or ``10080``, if provided.\n slowmode_delay: Optional[:class:`int`]\n Specifies the slowmode rate limit for user in this channel, in seconds.\n The maximum value possible is ``21600``. By default no slowmode rate limit\n if this is ``None``.\n content: Optional[:class:`str`]\n The content of the message to send with the thread.\n tts: :class:`bool`\n Indicates if the message should be sent using text-to-speech.\n embed: :class:`~discord.Embed`\n The rich embed for the content.\n embeds: List[:class:`~discord.Embed`]\n A list of embeds to upload. Must be a maximum of 10.\n file: :class:`~discord.File`\n The file to upload.\n files: List[:class:`~discord.File`]\n A list of files to upload. Must be a maximum of 10.\n allowed_mentions: :class:`~discord.AllowedMentions`\n Controls the mentions being processed in this message. If this is\n passed, then the object is merged with :attr:`~discord.Client.allowed_mentions`.\n The merging behaviour only overrides attributes that have been explicitly passed\n to the object, otherwise it uses the attributes set in :attr:`~discord.Client.allowed_mentions`.\n If no object is passed at all then the defaults given by :attr:`~discord.Client.allowed_mentions`\n are used instead.\n mention_author: :class:`bool`\n If set, overrides the :attr:`~discord.AllowedMentions.replied_user` attribute of ``allowed_mentions``.\n applied_tags: List[:class:`discord.ForumTag`]\n A list of tags to apply to the thread.\n view: :class:`discord.ui.View`\n A Discord UI View to add to the message.\n stickers: Sequence[Union[:class:`~discord.GuildSticker`, :class:`~discord.StickerItem`]]\n A list of stickers to upload. Must be a maximum of 3.\n suppress_embeds: :class:`bool`\n Whether to suppress embeds for the message. This sends the message without any embeds if set to ``True``.\n reason: :class:`str`\n The reason for creating a new thread. Shows up on the audit log.\n\n Raises\n -------\n Forbidden\n You do not have permissions to create a thread.\n HTTPException\n Starting the thread failed.\n ValueError\n The ``files`` or ``embeds`` list is not of the appropriate size.\n TypeError\n You specified both ``file`` and ``files``,\n or you specified both ``embed`` and ``embeds``.\n\n Returns\n --------\n Tuple[:class:`Thread`, :class:`Message`]\n The created thread with the created message.\n This is also accessible as a namedtuple with ``thread`` and ``message`` fields.\n \"\"\"\n\n state = self._state\n previous_allowed_mention = state.allowed_mentions\n if stickers is MISSING:\n sticker_ids = MISSING\n else:\n sticker_ids: SnowflakeList = [s.id for s in stickers]\n\n if view and not hasattr(view, '__discord_ui_view__'):\n raise TypeError(f'view parameter must be View not {view.__class__.__name__}')\n\n if suppress_embeds:\n from .message import MessageFlags # circular import\n\n flags = MessageFlags._from_value(4)\n else:\n flags = MISSING\n\n content = str(content) if content else MISSING\n\n channel_payload = {\n 'name': name,\n 'auto_archive_duration': auto_archive_duration or self.default_auto_archive_duration,\n 'rate_limit_per_user': slowmode_delay,\n 'type': 11, # Private threads don't seem to be allowed\n }\n\n if applied_tags is not MISSING:\n channel_payload['applied_tags'] = [str(tag.id) for tag in applied_tags]\n\n with handle_message_parameters(\n content=content,\n tts=tts,\n file=file,\n files=files,\n embed=embed,\n embeds=embeds,\n allowed_mentions=allowed_mentions,\n previous_allowed_mentions=previous_allowed_mention,\n mention_author=None if mention_author is MISSING else mention_author,\n stickers=sticker_ids,\n view=view,\n flags=flags,\n channel_payload=channel_payload,\n ) as params:\n # Circular import\n from .message import Message\n\n data = await state.http.start_thread_in_forum(self.id, params=params, reason=reason)\n thread = Thread(guild=self.guild, state=self._state, data=data)\n message = Message(state=self._state, channel=thread, data=data['message'])\n if view and not view.is_finished():\n self._state.store_view(view, message.id)\n\n return ThreadWithMessage(thread=thread, message=message)\n\n async def webhooks(self) -> List[Webhook]:\n \"\"\"|coro|\n\n Gets the list of webhooks from this channel.\n\n You must have :attr:`~.Permissions.manage_webhooks` to do this.\n\n Raises\n -------\n Forbidden\n You don't have permissions to get the webhooks.\n\n Returns\n --------\n List[:class:`Webhook`]\n The webhooks for this channel.\n \"\"\"\n\n from .webhook import Webhook\n\n data = await self._state.http.channel_webhooks(self.id)\n return [Webhook.from_state(d, state=self._state) for d in data]\n\n async def create_webhook(self, *, name: str, avatar: Optional[bytes] = None, reason: Optional[str] = None) -> Webhook:\n \"\"\"|coro|\n\n Creates a webhook for this channel.\n\n You must have :attr:`~.Permissions.manage_webhooks` to do this.\n\n Parameters\n -------------\n name: :class:`str`\n The webhook's name.\n avatar: Optional[:class:`bytes`]\n A :term:`py:bytes-like object` representing the webhook's default avatar.\n This operates similarly to :meth:`~ClientUser.edit`.\n reason: Optional[:class:`str`]\n The reason for creating this webhook. Shows up in the audit logs.\n\n Raises\n -------\n HTTPException\n Creating the webhook failed.\n Forbidden\n You do not have permissions to create a webhook.\n\n Returns\n --------\n :class:`Webhook`\n The created webhook.\n \"\"\"\n\n from .webhook import Webhook\n\n if avatar is not None:\n avatar = utils._bytes_to_base64_data(avatar) # type: ignore # Silence reassignment error\n\n data = await self._state.http.create_webhook(self.id, name=str(name), avatar=avatar, reason=reason)\n return Webhook.from_state(data, state=self._state)\n\n async def archived_threads(\n self,\n *,\n limit: Optional[int] = 100,\n before: Optional[Union[Snowflake, datetime.datetime]] = None,\n ) -> AsyncIterator[Thread]:\n \"\"\"Returns an :term:`asynchronous iterator` that iterates over all archived threads in this forum\n in order of decreasing :attr:`Thread.archive_timestamp`.\n\n You must have :attr:`~Permissions.read_message_history` to do this.\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n limit: Optional[:class:`bool`]\n The number of threads to retrieve.\n If ``None``, retrieves every archived thread in the channel. Note, however,\n that this would make it a slow operation.\n before: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]\n Retrieve archived channels before the given date or ID.\n\n Raises\n ------\n Forbidden\n You do not have permissions to get archived threads.\n HTTPException\n The request to get the archived threads failed.\n\n Yields\n -------\n :class:`Thread`\n The archived threads.\n \"\"\"\n before_timestamp = None\n\n if isinstance(before, datetime.datetime):\n before_timestamp = before.isoformat()\n elif before is not None:\n before_timestamp = utils.snowflake_time(before.id).isoformat()\n\n update_before = lambda data: data['thread_metadata']['archive_timestamp']\n\n while True:\n retrieve = 100\n if limit is not None:\n if limit <= 0:\n return\n retrieve = max(2, min(retrieve, limit))\n\n data = await self.guild._state.http.get_public_archived_threads(self.id, before=before_timestamp, limit=retrieve)\n\n threads = data.get('threads', [])\n for raw_thread in threads:\n yield Thread(guild=self.guild, state=self.guild._state, data=raw_thread)\n # Currently the API doesn't let you request less than 2 threads.\n # Bail out early if we had to retrieve more than what the limit was.\n if limit is not None:\n limit -= 1\n if limit <= 0:\n return\n\n if not data.get('has_more', False):\n return\n\n before_timestamp = update_before(threads[-1])\n\n\nclass DMChannel(discord.abc.Messageable, discord.abc.PrivateChannel, Hashable):\n \"\"\"Represents a Discord direct message channel.\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two channels are equal.\n\n .. describe:: x != y\n\n Checks if two channels are not equal.\n\n .. describe:: hash(x)\n\n Returns the channel's hash.\n\n .. describe:: str(x)\n\n Returns a string representation of the channel\n\n Attributes\n ----------\n recipient: Optional[:class:`User`]\n The user you are participating with in the direct message channel.\n If this channel is received through the gateway, the recipient information\n may not be always available.\n recipients: List[:class:`User`]\n The users you are participating with in the DM channel.\n\n .. versionadded:: 2.4\n me: :class:`ClientUser`\n The user presenting yourself.\n id: :class:`int`\n The direct message channel ID.\n \"\"\"\n\n __slots__ = ('id', 'recipients', 'me', '_state')\n\n def __init__(self, *, me: ClientUser, state: ConnectionState, data: DMChannelPayload):\n self._state: ConnectionState = state\n self.recipients: List[User] = [state.store_user(u) for u in data.get('recipients', [])]\n self.me: ClientUser = me\n self.id: int = int(data['id'])\n\n async def _get_channel(self) -> Self:\n return self\n\n def __str__(self) -> str:\n if self.recipient:\n return f'Direct Message with {self.recipient}'\n return 'Direct Message with Unknown User'\n\n def __repr__(self) -> str:\n return f''\n\n @classmethod\n def _from_message(cls, state: ConnectionState, channel_id: int) -> Self:\n self = cls.__new__(cls)\n self._state = state\n self.id = channel_id\n self.recipients = []\n # state.user won't be None here\n self.me = state.user # type: ignore\n return self\n\n @property\n def recipient(self) -> Optional[User]:\n if self.recipients:\n return self.recipients[0]\n return None\n\n @property\n def type(self) -> Literal[ChannelType.private]:\n \"\"\":class:`ChannelType`: The channel's Discord type.\"\"\"\n return ChannelType.private\n\n @property\n def guild(self) -> Optional[Guild]:\n \"\"\"Optional[:class:`Guild`]: The guild this DM channel belongs to. Always ``None``.\n\n This is mainly provided for compatibility purposes in duck typing.\n\n .. versionadded:: 2.0\n \"\"\"\n return None\n\n @property\n def jump_url(self) -> str:\n \"\"\":class:`str`: Returns a URL that allows the client to jump to the channel.\n\n .. versionadded:: 2.0\n \"\"\"\n return f'https://discord.com/channels/@me/{self.id}'\n\n @property\n def created_at(self) -> datetime.datetime:\n \"\"\":class:`datetime.datetime`: Returns the direct message channel's creation time in UTC.\"\"\"\n return utils.snowflake_time(self.id)\n\n def permissions_for(self, obj: Any = None, /) -> Permissions:\n \"\"\"Handles permission resolution for a :class:`User`.\n\n This function is there for compatibility with other channel types.\n\n Actual direct messages do not really have the concept of permissions.\n\n This returns all the Text related permissions set to ``True`` except:\n\n - :attr:`~Permissions.send_tts_messages`: You cannot send TTS messages in a DM.\n - :attr:`~Permissions.manage_messages`: You cannot delete others messages in a DM.\n - :attr:`~Permissions.create_private_threads`: There are no threads in a DM.\n - :attr:`~Permissions.create_public_threads`: There are no threads in a DM.\n - :attr:`~Permissions.manage_threads`: There are no threads in a DM.\n - :attr:`~Permissions.send_messages_in_threads`: There are no threads in a DM.\n\n .. versionchanged:: 2.0\n\n ``obj`` parameter is now positional-only.\n\n .. versionchanged:: 2.1\n\n Thread related permissions are now set to ``False``.\n\n Parameters\n -----------\n obj: :class:`User`\n The user to check permissions for. This parameter is ignored\n but kept for compatibility with other ``permissions_for`` methods.\n\n Returns\n --------\n :class:`Permissions`\n The resolved permissions.\n \"\"\"\n return Permissions._dm_permissions()\n\n def get_partial_message(self, message_id: int, /) -> PartialMessage:\n \"\"\"Creates a :class:`PartialMessage` from the message ID.\n\n This is useful if you want to work with a message and only have its ID without\n doing an unnecessary API call.\n\n .. versionadded:: 1.6\n\n .. versionchanged:: 2.0\n\n ``message_id`` parameter is now positional-only.\n\n Parameters\n ------------\n message_id: :class:`int`\n The message ID to create a partial message for.\n\n Returns\n ---------\n :class:`PartialMessage`\n The partial message.\n \"\"\"\n\n from .message import PartialMessage\n\n return PartialMessage(channel=self, id=message_id)\n\n\nclass GroupChannel(discord.abc.Messageable, discord.abc.PrivateChannel, Hashable):\n \"\"\"Represents a Discord group channel.\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two channels are equal.\n\n .. describe:: x != y\n\n Checks if two channels are not equal.\n\n .. describe:: hash(x)\n\n Returns the channel's hash.\n\n .. describe:: str(x)\n\n Returns a string representation of the channel\n\n Attributes\n ----------\n recipients: List[:class:`User`]\n The users you are participating with in the group channel.\n me: :class:`ClientUser`\n The user presenting yourself.\n id: :class:`int`\n The group channel ID.\n owner: Optional[:class:`User`]\n The user that owns the group channel.\n owner_id: :class:`int`\n The owner ID that owns the group channel.\n\n .. versionadded:: 2.0\n name: Optional[:class:`str`]\n The group channel's name if provided.\n \"\"\"\n\n __slots__ = ('id', 'recipients', 'owner_id', 'owner', '_icon', 'name', 'me', '_state')\n\n def __init__(self, *, me: ClientUser, state: ConnectionState, data: GroupChannelPayload):\n self._state: ConnectionState = state\n self.id: int = int(data['id'])\n self.me: ClientUser = me\n self._update_group(data)\n\n def _update_group(self, data: GroupChannelPayload) -> None:\n self.owner_id: Optional[int] = utils._get_as_snowflake(data, 'owner_id')\n self._icon: Optional[str] = data.get('icon')\n self.name: Optional[str] = data.get('name')\n self.recipients: List[User] = [self._state.store_user(u) for u in data.get('recipients', [])]\n\n self.owner: Optional[BaseUser]\n if self.owner_id == self.me.id:\n self.owner = self.me\n else:\n self.owner = utils.find(lambda u: u.id == self.owner_id, self.recipients)\n\n async def _get_channel(self) -> Self:\n return self\n\n def __str__(self) -> str:\n if self.name:\n return self.name\n\n if len(self.recipients) == 0:\n return 'Unnamed'\n\n return ', '.join(map(lambda x: x.name, self.recipients))\n\n def __repr__(self) -> str:\n return f''\n\n @property\n def type(self) -> Literal[ChannelType.group]:\n \"\"\":class:`ChannelType`: The channel's Discord type.\"\"\"\n return ChannelType.group\n\n @property\n def guild(self) -> Optional[Guild]:\n \"\"\"Optional[:class:`Guild`]: The guild this group channel belongs to. Always ``None``.\n\n This is mainly provided for compatibility purposes in duck typing.\n\n .. versionadded:: 2.0\n \"\"\"\n return None\n\n @property\n def icon(self) -> Optional[Asset]:\n \"\"\"Optional[:class:`Asset`]: Returns the channel's icon asset if available.\"\"\"\n if self._icon is None:\n return None\n return Asset._from_icon(self._state, self.id, self._icon, path='channel')\n\n @property\n def created_at(self) -> datetime.datetime:\n \"\"\":class:`datetime.datetime`: Returns the channel's creation time in UTC.\"\"\"\n return utils.snowflake_time(self.id)\n\n @property\n def jump_url(self) -> str:\n \"\"\":class:`str`: Returns a URL that allows the client to jump to the channel.\n\n .. versionadded:: 2.0\n \"\"\"\n return f'https://discord.com/channels/@me/{self.id}'\n\n def permissions_for(self, obj: Snowflake, /) -> Permissions:\n \"\"\"Handles permission resolution for a :class:`User`.\n\n This function is there for compatibility with other channel types.\n\n Actual direct messages do not really have the concept of permissions.\n\n This returns all the Text related permissions set to ``True`` except:\n\n - :attr:`~Permissions.send_tts_messages`: You cannot send TTS messages in a DM.\n - :attr:`~Permissions.manage_messages`: You cannot delete others messages in a DM.\n - :attr:`~Permissions.create_private_threads`: There are no threads in a DM.\n - :attr:`~Permissions.create_public_threads`: There are no threads in a DM.\n - :attr:`~Permissions.manage_threads`: There are no threads in a DM.\n - :attr:`~Permissions.send_messages_in_threads`: There are no threads in a DM.\n\n This also checks the kick_members permission if the user is the owner.\n\n .. versionchanged:: 2.0\n\n ``obj`` parameter is now positional-only.\n\n .. versionchanged:: 2.1\n\n Thread related permissions are now set to ``False``.\n\n Parameters\n -----------\n obj: :class:`~discord.abc.Snowflake`\n The user to check permissions for.\n\n Returns\n --------\n :class:`Permissions`\n The resolved permissions for the user.\n \"\"\"\n\n base = Permissions._dm_permissions()\n base.mention_everyone = True\n\n if obj.id == self.owner_id:\n base.kick_members = True\n\n return base\n\n async def leave(self) -> None:\n \"\"\"|coro|\n\n Leave the group.\n\n If you are the only one in the group, this deletes it as well.\n\n Raises\n -------\n HTTPException\n Leaving the group failed.\n \"\"\"\n\n await self._state.http.leave_group(self.id)\n\n\nclass PartialMessageable(discord.abc.Messageable, Hashable):\n \"\"\"Represents a partial messageable to aid with working messageable channels when\n only a channel ID is present.\n\n The only way to construct this class is through :meth:`Client.get_partial_messageable`.\n\n Note that this class is trimmed down and has no rich attributes.\n\n .. versionadded:: 2.0\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two partial messageables are equal.\n\n .. describe:: x != y\n\n Checks if two partial messageables are not equal.\n\n .. describe:: hash(x)\n\n Returns the partial messageable's hash.\n\n Attributes\n -----------\n id: :class:`int`\n The channel ID associated with this partial messageable.\n guild_id: Optional[:class:`int`]\n The guild ID associated with this partial messageable.\n type: Optional[:class:`ChannelType`]\n The channel type associated with this partial messageable, if given.\n \"\"\"\n\n def __init__(self, state: ConnectionState, id: int, guild_id: Optional[int] = None, type: Optional[ChannelType] = None):\n self._state: ConnectionState = state\n self.id: int = id\n self.guild_id: Optional[int] = guild_id\n self.type: Optional[ChannelType] = type\n\n def __repr__(self) -> str:\n return f'<{self.__class__.__name__} id={self.id} type={self.type!r}>'\n\n async def _get_channel(self) -> PartialMessageable:\n return self\n\n @property\n def guild(self) -> Optional[Guild]:\n \"\"\"Optional[:class:`Guild`]: The guild this partial messageable is in.\"\"\"\n return self._state._get_guild(self.guild_id)\n\n @property\n def jump_url(self) -> str:\n \"\"\":class:`str`: Returns a URL that allows the client to jump to the channel.\"\"\"\n if self.guild_id is None:\n return f'https://discord.com/channels/@me/{self.id}'\n return f'https://discord.com/channels/{self.guild_id}/{self.id}'\n\n @property\n def created_at(self) -> datetime.datetime:\n \"\"\":class:`datetime.datetime`: Returns the channel's creation time in UTC.\"\"\"\n return utils.snowflake_time(self.id)\n\n def permissions_for(self, obj: Any = None, /) -> Permissions:\n \"\"\"Handles permission resolution for a :class:`User`.\n\n This function is there for compatibility with other channel types.\n\n Since partial messageables cannot reasonably have the concept of\n permissions, this will always return :meth:`Permissions.none`.\n\n Parameters\n -----------\n obj: :class:`User`\n The user to check permissions for. This parameter is ignored\n but kept for compatibility with other ``permissions_for`` methods.\n\n Returns\n --------\n :class:`Permissions`\n The resolved permissions.\n \"\"\"\n\n return Permissions.none()\n\n def get_partial_message(self, message_id: int, /) -> PartialMessage:\n \"\"\"Creates a :class:`PartialMessage` from the message ID.\n\n This is useful if you want to work with a message and only have its ID without\n doing an unnecessary API call.\n\n Parameters\n ------------\n message_id: :class:`int`\n The message ID to create a partial message for.\n\n Returns\n ---------\n :class:`PartialMessage`\n The partial message.\n \"\"\"\n\n from .message import PartialMessage\n\n return PartialMessage(channel=self, id=message_id)\n\n\ndef _guild_channel_factory(channel_type: int):\n value = try_enum(ChannelType, channel_type)\n if value is ChannelType.text:\n return TextChannel, value\n elif value is ChannelType.voice:\n return VoiceChannel, value\n elif value is ChannelType.category:\n return CategoryChannel, value\n elif value is ChannelType.news:\n return TextChannel, value\n elif value is ChannelType.stage_voice:\n return StageChannel, value\n elif value is ChannelType.forum:\n return ForumChannel, value\n elif value is ChannelType.media:\n return ForumChannel, value\n else:\n return None, value\n\n\ndef _channel_factory(channel_type: int):\n cls, value = _guild_channel_factory(channel_type)\n if value is ChannelType.private:\n return DMChannel, value\n elif value is ChannelType.group:\n return GroupChannel, value\n else:\n return cls, value\n\n\ndef _threaded_channel_factory(channel_type: int):\n cls, value = _channel_factory(channel_type)\n if value in (ChannelType.private_thread, ChannelType.public_thread, ChannelType.news_thread):\n return Thread, value\n return cls, value\n\n\ndef _threaded_guild_channel_factory(channel_type: int):\n cls, value = _guild_channel_factory(channel_type)\n if value in (ChannelType.private_thread, ChannelType.public_thread, ChannelType.news_thread):\n return Thread, value\n return cls, value\n" }, { "path": "discord/client.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport datetime\nimport logging\nfrom typing import (\n TYPE_CHECKING,\n Any,\n AsyncIterator,\n Callable,\n Coroutine,\n Dict,\n Generator,\n List,\n Literal,\n Optional,\n Sequence,\n Tuple,\n Type,\n TypeVar,\n Union,\n overload,\n)\n\nimport aiohttp\n\nfrom .sku import SKU, Entitlement\nfrom .user import User, ClientUser\nfrom .invite import Invite\nfrom .template import Template\nfrom .widget import Widget\nfrom .guild import Guild\nfrom .emoji import Emoji\nfrom .channel import _threaded_channel_factory, PartialMessageable\nfrom .enums import ChannelType, EntitlementOwnerType\nfrom .mentions import AllowedMentions\nfrom .errors import *\nfrom .enums import Status\nfrom .flags import ApplicationFlags, Intents\nfrom .gateway import *\nfrom .activity import ActivityTypes, BaseActivity, create_activity\nfrom .voice_client import VoiceClient\nfrom .http import HTTPClient\nfrom .state import ConnectionState\nfrom . import utils\nfrom .utils import MISSING, time_snowflake\nfrom .object import Object\nfrom .backoff import ExponentialBackoff\nfrom .webhook import Webhook\nfrom .appinfo import AppInfo\nfrom .ui.view import View\nfrom .ui.dynamic import DynamicItem\nfrom .stage_instance import StageInstance\nfrom .threads import Thread\nfrom .sticker import GuildSticker, StandardSticker, StickerPack, _sticker_factory\n\nif TYPE_CHECKING:\n from types import TracebackType\n\n from typing_extensions import Self\n\n from .abc import Messageable, PrivateChannel, Snowflake, SnowflakeTime\n from .app_commands import Command, ContextMenu, MissingApplicationID\n from .automod import AutoModAction, AutoModRule\n from .channel import DMChannel, GroupChannel\n from .ext.commands import AutoShardedBot, Bot, Context, CommandError\n from .guild import GuildChannel\n from .integrations import Integration\n from .interactions import Interaction\n from .member import Member, VoiceState\n from .message import Message\n from .raw_models import (\n RawAppCommandPermissionsUpdateEvent,\n RawBulkMessageDeleteEvent,\n RawIntegrationDeleteEvent,\n RawMemberRemoveEvent,\n RawMessageDeleteEvent,\n RawMessageUpdateEvent,\n RawReactionActionEvent,\n RawReactionClearEmojiEvent,\n RawReactionClearEvent,\n RawThreadDeleteEvent,\n RawThreadMembersUpdate,\n RawThreadUpdateEvent,\n RawTypingEvent,\n RawPollVoteActionEvent,\n )\n from .reaction import Reaction\n from .role import Role\n from .scheduled_event import ScheduledEvent\n from .threads import ThreadMember\n from .types.guild import Guild as GuildPayload\n from .ui.item import Item\n from .voice_client import VoiceProtocol\n from .audit_logs import AuditLogEntry\n from .poll import PollAnswer\n\n\n# fmt: off\n__all__ = (\n 'Client',\n)\n# fmt: on\n\nT = TypeVar('T')\nCoro = Coroutine[Any, Any, T]\nCoroT = TypeVar('CoroT', bound=Callable[..., Coro[Any]])\n\n_log = logging.getLogger(__name__)\n\n\nclass _LoopSentinel:\n __slots__ = ()\n\n def __getattr__(self, attr: str) -> None:\n msg = (\n 'loop attribute cannot be accessed in non-async contexts. '\n 'Consider using either an asynchronous main function and passing it to asyncio.run or '\n 'using asynchronous initialisation hooks such as Client.setup_hook'\n )\n raise AttributeError(msg)\n\n\n_loop: Any = _LoopSentinel()\n\n\nclass Client:\n r\"\"\"Represents a client connection that connects to Discord.\n This class is used to interact with the Discord WebSocket and API.\n\n .. container:: operations\n\n .. describe:: async with x\n\n Asynchronously initialises the client and automatically cleans up.\n\n .. versionadded:: 2.0\n\n A number of options can be passed to the :class:`Client`.\n\n Parameters\n -----------\n max_messages: Optional[:class:`int`]\n The maximum number of messages to store in the internal message cache.\n This defaults to ``1000``. Passing in ``None`` disables the message cache.\n\n .. versionchanged:: 1.3\n Allow disabling the message cache and change the default size to ``1000``.\n proxy: Optional[:class:`str`]\n Proxy URL.\n proxy_auth: Optional[:class:`aiohttp.BasicAuth`]\n An object that represents proxy HTTP Basic Authorization.\n shard_id: Optional[:class:`int`]\n Integer starting at ``0`` and less than :attr:`.shard_count`.\n shard_count: Optional[:class:`int`]\n The total number of shards.\n application_id: :class:`int`\n The client's application ID.\n intents: :class:`Intents`\n The intents that you want to enable for the session. This is a way of\n disabling and enabling certain gateway events from triggering and being sent.\n\n .. versionadded:: 1.5\n\n .. versionchanged:: 2.0\n Parameter is now required.\n member_cache_flags: :class:`MemberCacheFlags`\n Allows for finer control over how the library caches members.\n If not given, defaults to cache as much as possible with the\n currently selected intents.\n\n .. versionadded:: 1.5\n chunk_guilds_at_startup: :class:`bool`\n Indicates if :func:`.on_ready` should be delayed to chunk all guilds\n at start-up if necessary. This operation is incredibly slow for large\n amounts of guilds. The default is ``True`` if :attr:`Intents.members`\n is ``True``.\n\n .. versionadded:: 1.5\n status: Optional[:class:`.Status`]\n A status to start your presence with upon logging on to Discord.\n activity: Optional[:class:`.BaseActivity`]\n An activity to start your presence with upon logging on to Discord.\n allowed_mentions: Optional[:class:`AllowedMentions`]\n Control how the client handles mentions by default on every message sent.\n\n .. versionadded:: 1.4\n heartbeat_timeout: :class:`float`\n The maximum numbers of seconds before timing out and restarting the\n WebSocket in the case of not receiving a HEARTBEAT_ACK. Useful if\n processing the initial packets take too long to the point of disconnecting\n you. The default timeout is 60 seconds.\n guild_ready_timeout: :class:`float`\n The maximum number of seconds to wait for the GUILD_CREATE stream to end before\n preparing the member cache and firing READY. The default timeout is 2 seconds.\n\n .. versionadded:: 1.4\n assume_unsync_clock: :class:`bool`\n Whether to assume the system clock is unsynced. This applies to the ratelimit handling\n code. If this is set to ``True``, the default, then the library uses the time to reset\n a rate limit bucket given by Discord. If this is ``False`` then your system clock is\n used to calculate how long to sleep for. If this is set to ``False`` it is recommended to\n sync your system clock to Google's NTP server.\n\n .. versionadded:: 1.3\n enable_debug_events: :class:`bool`\n Whether to enable events that are useful only for debugging gateway related information.\n\n Right now this involves :func:`on_socket_raw_receive` and :func:`on_socket_raw_send`. If\n this is ``False`` then those events will not be dispatched (due to performance considerations).\n To enable these events, this must be set to ``True``. Defaults to ``False``.\n\n .. versionadded:: 2.0\n http_trace: :class:`aiohttp.TraceConfig`\n The trace configuration to use for tracking HTTP requests the library does using ``aiohttp``.\n This allows you to check requests the library is using. For more information, check the\n `aiohttp documentation `_.\n\n .. versionadded:: 2.0\n max_ratelimit_timeout: Optional[:class:`float`]\n The maximum number of seconds to wait when a non-global rate limit is encountered.\n If a request requires sleeping for more than the seconds passed in, then\n :exc:`~discord.RateLimited` will be raised. By default, there is no timeout limit.\n In order to prevent misuse and unnecessary bans, the minimum value this can be\n set to is ``30.0`` seconds.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n ws\n The websocket gateway the client is currently connected to. Could be ``None``.\n \"\"\"\n\n def __init__(self, *, intents: Intents, **options: Any) -> None:\n self.loop: asyncio.AbstractEventLoop = _loop\n # self.ws is set in the connect method\n self.ws: DiscordWebSocket = None # type: ignore\n self._listeners: Dict[str, List[Tuple[asyncio.Future, Callable[..., bool]]]] = {}\n self.shard_id: Optional[int] = options.get('shard_id')\n self.shard_count: Optional[int] = options.get('shard_count')\n\n proxy: Optional[str] = options.pop('proxy', None)\n proxy_auth: Optional[aiohttp.BasicAuth] = options.pop('proxy_auth', None)\n unsync_clock: bool = options.pop('assume_unsync_clock', True)\n http_trace: Optional[aiohttp.TraceConfig] = options.pop('http_trace', None)\n max_ratelimit_timeout: Optional[float] = options.pop('max_ratelimit_timeout', None)\n self.http: HTTPClient = HTTPClient(\n self.loop,\n proxy=proxy,\n proxy_auth=proxy_auth,\n unsync_clock=unsync_clock,\n http_trace=http_trace,\n max_ratelimit_timeout=max_ratelimit_timeout,\n )\n\n self._handlers: Dict[str, Callable[..., None]] = {\n 'ready': self._handle_ready,\n }\n\n self._hooks: Dict[str, Callable[..., Coroutine[Any, Any, Any]]] = {\n 'before_identify': self._call_before_identify_hook,\n }\n\n self._enable_debug_events: bool = options.pop('enable_debug_events', False)\n self._connection: ConnectionState[Self] = self._get_state(intents=intents, **options)\n self._connection.shard_count = self.shard_count\n self._closing_task: Optional[asyncio.Task[None]] = None\n self._ready: asyncio.Event = MISSING\n self._application: Optional[AppInfo] = None\n self._connection._get_websocket = self._get_websocket\n self._connection._get_client = lambda: self\n\n if VoiceClient.warn_nacl:\n VoiceClient.warn_nacl = False\n _log.warning(\"PyNaCl is not installed, voice will NOT be supported\")\n\n async def __aenter__(self) -> Self:\n await self._async_setup_hook()\n return self\n\n async def __aexit__(\n self,\n exc_type: Optional[Type[BaseException]],\n exc_value: Optional[BaseException],\n traceback: Optional[TracebackType],\n ) -> None:\n # This avoids double-calling a user-provided .close()\n if self._closing_task:\n await self._closing_task\n else:\n await self.close()\n\n # internals\n\n def _get_websocket(self, guild_id: Optional[int] = None, *, shard_id: Optional[int] = None) -> DiscordWebSocket:\n return self.ws\n\n def _get_state(self, **options: Any) -> ConnectionState[Self]:\n return ConnectionState(dispatch=self.dispatch, handlers=self._handlers, hooks=self._hooks, http=self.http, **options)\n\n def _handle_ready(self) -> None:\n self._ready.set()\n\n @property\n def latency(self) -> float:\n \"\"\":class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.\n\n This could be referred to as the Discord WebSocket protocol latency.\n \"\"\"\n ws = self.ws\n return float('nan') if not ws else ws.latency\n\n def is_ws_ratelimited(self) -> bool:\n \"\"\":class:`bool`: Whether the websocket is currently rate limited.\n\n This can be useful to know when deciding whether you should query members\n using HTTP or via the gateway.\n\n .. versionadded:: 1.6\n \"\"\"\n if self.ws:\n return self.ws.is_ratelimited()\n return False\n\n @property\n def user(self) -> Optional[ClientUser]:\n \"\"\"Optional[:class:`.ClientUser`]: Represents the connected client. ``None`` if not logged in.\"\"\"\n return self._connection.user\n\n @property\n def guilds(self) -> Sequence[Guild]:\n \"\"\"Sequence[:class:`.Guild`]: The guilds that the connected client is a member of.\"\"\"\n return self._connection.guilds\n\n @property\n def emojis(self) -> Sequence[Emoji]:\n \"\"\"Sequence[:class:`.Emoji`]: The emojis that the connected client has.\"\"\"\n return self._connection.emojis\n\n @property\n def stickers(self) -> Sequence[GuildSticker]:\n \"\"\"Sequence[:class:`.GuildSticker`]: The stickers that the connected client has.\n\n .. versionadded:: 2.0\n \"\"\"\n return self._connection.stickers\n\n @property\n def cached_messages(self) -> Sequence[Message]:\n \"\"\"Sequence[:class:`.Message`]: Read-only list of messages the connected client has cached.\n\n .. versionadded:: 1.1\n \"\"\"\n return utils.SequenceProxy(self._connection._messages or [])\n\n @property\n def private_channels(self) -> Sequence[PrivateChannel]:\n \"\"\"Sequence[:class:`.abc.PrivateChannel`]: The private channels that the connected client is participating on.\n\n .. note::\n\n This returns only up to 128 most recent private channels due to an internal working\n on how Discord deals with private channels.\n \"\"\"\n return self._connection.private_channels\n\n @property\n def voice_clients(self) -> List[VoiceProtocol]:\n \"\"\"List[:class:`.VoiceProtocol`]: Represents a list of voice connections.\n\n These are usually :class:`.VoiceClient` instances.\n \"\"\"\n return self._connection.voice_clients\n\n @property\n def application_id(self) -> Optional[int]:\n \"\"\"Optional[:class:`int`]: The client's application ID.\n\n If this is not passed via ``__init__`` then this is retrieved\n through the gateway when an event contains the data or after a call\n to :meth:`~discord.Client.login`. Usually after :func:`~discord.on_connect`\n is called.\n\n .. versionadded:: 2.0\n \"\"\"\n return self._connection.application_id\n\n @property\n def application_flags(self) -> ApplicationFlags:\n \"\"\":class:`~discord.ApplicationFlags`: The client's application flags.\n\n .. versionadded:: 2.0\n \"\"\"\n return self._connection.application_flags\n\n @property\n def application(self) -> Optional[AppInfo]:\n \"\"\"Optional[:class:`~discord.AppInfo`]: The client's application info.\n\n This is retrieved on :meth:`~discord.Client.login` and is not updated\n afterwards. This allows populating the application_id without requiring a\n gateway connection.\n\n This is ``None`` if accessed before :meth:`~discord.Client.login` is called.\n\n .. seealso:: The :meth:`~discord.Client.application_info` API call\n\n .. versionadded:: 2.0\n \"\"\"\n return self._application\n\n def is_ready(self) -> bool:\n \"\"\":class:`bool`: Specifies if the client's internal cache is ready for use.\"\"\"\n return self._ready is not MISSING and self._ready.is_set()\n\n async def _run_event(\n self,\n coro: Callable[..., Coroutine[Any, Any, Any]],\n event_name: str,\n *args: Any,\n **kwargs: Any,\n ) -> None:\n try:\n await coro(*args, **kwargs)\n except asyncio.CancelledError:\n pass\n except Exception:\n try:\n await self.on_error(event_name, *args, **kwargs)\n except asyncio.CancelledError:\n pass\n\n def _schedule_event(\n self,\n coro: Callable[..., Coroutine[Any, Any, Any]],\n event_name: str,\n *args: Any,\n **kwargs: Any,\n ) -> asyncio.Task:\n wrapped = self._run_event(coro, event_name, *args, **kwargs)\n # Schedules the task\n return self.loop.create_task(wrapped, name=f'discord.py: {event_name}')\n\n def dispatch(self, event: str, /, *args: Any, **kwargs: Any) -> None:\n _log.debug('Dispatching event %s', event)\n method = 'on_' + event\n\n listeners = self._listeners.get(event)\n if listeners:\n removed = []\n for i, (future, condition) in enumerate(listeners):\n if future.cancelled():\n removed.append(i)\n continue\n\n try:\n result = condition(*args)\n except Exception as exc:\n future.set_exception(exc)\n removed.append(i)\n else:\n if result:\n if len(args) == 0:\n future.set_result(None)\n elif len(args) == 1:\n future.set_result(args[0])\n else:\n future.set_result(args)\n removed.append(i)\n\n if len(removed) == len(listeners):\n self._listeners.pop(event)\n else:\n for idx in reversed(removed):\n del listeners[idx]\n\n try:\n coro = getattr(self, method)\n except AttributeError:\n pass\n else:\n self._schedule_event(coro, method, *args, **kwargs)\n\n async def on_error(self, event_method: str, /, *args: Any, **kwargs: Any) -> None:\n \"\"\"|coro|\n\n The default error handler provided by the client.\n\n By default this logs to the library logger however it could be\n overridden to have a different implementation.\n Check :func:`~discord.on_error` for more details.\n\n .. versionchanged:: 2.0\n\n ``event_method`` parameter is now positional-only\n and instead of writing to ``sys.stderr`` it logs instead.\n \"\"\"\n _log.exception('Ignoring exception in %s', event_method)\n\n # hooks\n\n async def _call_before_identify_hook(self, shard_id: Optional[int], *, initial: bool = False) -> None:\n # This hook is an internal hook that actually calls the public one.\n # It allows the library to have its own hook without stepping on the\n # toes of those who need to override their own hook.\n await self.before_identify_hook(shard_id, initial=initial)\n\n async def before_identify_hook(self, shard_id: Optional[int], *, initial: bool = False) -> None:\n \"\"\"|coro|\n\n A hook that is called before IDENTIFYing a session. This is useful\n if you wish to have more control over the synchronization of multiple\n IDENTIFYing clients.\n\n The default implementation sleeps for 5 seconds.\n\n .. versionadded:: 1.4\n\n Parameters\n ------------\n shard_id: :class:`int`\n The shard ID that requested being IDENTIFY'd\n initial: :class:`bool`\n Whether this IDENTIFY is the first initial IDENTIFY.\n \"\"\"\n\n if not initial:\n await asyncio.sleep(5.0)\n\n async def _async_setup_hook(self) -> None:\n # Called whenever the client needs to initialise asyncio objects with a running loop\n loop = asyncio.get_running_loop()\n self.loop = loop\n self.http.loop = loop\n self._connection.loop = loop\n\n self._ready = asyncio.Event()\n\n async def setup_hook(self) -> None:\n \"\"\"|coro|\n\n A coroutine to be called to setup the bot, by default this is blank.\n\n To perform asynchronous setup after the bot is logged in but before\n it has connected to the Websocket, overwrite this coroutine.\n\n This is only called once, in :meth:`login`, and will be called before\n any events are dispatched, making it a better solution than doing such\n setup in the :func:`~discord.on_ready` event.\n\n .. warning::\n\n Since this is called *before* the websocket connection is made therefore\n anything that waits for the websocket will deadlock, this includes things\n like :meth:`wait_for` and :meth:`wait_until_ready`.\n\n .. versionadded:: 2.0\n \"\"\"\n pass\n\n # login state management\n\n async def login(self, token: str) -> None:\n \"\"\"|coro|\n\n Logs in the client with the specified credentials and\n calls the :meth:`setup_hook`.\n\n\n Parameters\n -----------\n token: :class:`str`\n The authentication token. Do not prefix this token with\n anything as the library will do it for you.\n\n Raises\n ------\n LoginFailure\n The wrong credentials are passed.\n HTTPException\n An unknown HTTP related error occurred,\n usually when it isn't 200 or the known incorrect credentials\n passing status code.\n \"\"\"\n\n _log.info('logging in using static token')\n\n if self.loop is _loop:\n await self._async_setup_hook()\n\n if not isinstance(token, str):\n raise TypeError(f'expected token to be a str, received {token.__class__.__name__} instead')\n token = token.strip()\n\n data = await self.http.static_login(token)\n self._connection.user = ClientUser(state=self._connection, data=data)\n self._application = await self.application_info()\n if self._connection.application_id is None:\n self._connection.application_id = self._application.id\n\n if not self._connection.application_flags:\n self._connection.application_flags = self._application.flags\n\n await self.setup_hook()\n\n async def connect(self, *, reconnect: bool = True) -> None:\n \"\"\"|coro|\n\n Creates a websocket connection and lets the websocket listen\n to messages from Discord. This is a loop that runs the entire\n event system and miscellaneous aspects of the library. Control\n is not resumed until the WebSocket connection is terminated.\n\n Parameters\n -----------\n reconnect: :class:`bool`\n If we should attempt reconnecting, either due to internet\n failure or a specific failure on Discord's part. Certain\n disconnects that lead to bad state will not be handled (such as\n invalid sharding payloads or bad tokens).\n\n Raises\n -------\n GatewayNotFound\n If the gateway to connect to Discord is not found. Usually if this\n is thrown then there is a Discord API outage.\n ConnectionClosed\n The websocket connection has been terminated.\n \"\"\"\n\n backoff = ExponentialBackoff()\n ws_params = {\n 'initial': True,\n 'shard_id': self.shard_id,\n }\n while not self.is_closed():\n try:\n coro = DiscordWebSocket.from_client(self, **ws_params)\n self.ws = await asyncio.wait_for(coro, timeout=60.0)\n ws_params['initial'] = False\n while True:\n await self.ws.poll_event()\n except ReconnectWebSocket as e:\n _log.debug('Got a request to %s the websocket.', e.op)\n self.dispatch('disconnect')\n ws_params.update(sequence=self.ws.sequence, resume=e.resume, session=self.ws.session_id)\n if e.resume:\n ws_params['gateway'] = self.ws.gateway\n continue\n except (\n OSError,\n HTTPException,\n GatewayNotFound,\n ConnectionClosed,\n aiohttp.ClientError,\n asyncio.TimeoutError,\n ) as exc:\n self.dispatch('disconnect')\n if not reconnect:\n await self.close()\n if isinstance(exc, ConnectionClosed) and exc.code == 1000:\n # clean close, don't re-raise this\n return\n raise\n\n if self.is_closed():\n return\n\n # If we get connection reset by peer then try to RESUME\n if isinstance(exc, OSError) and exc.errno in (54, 10054):\n ws_params.update(\n sequence=self.ws.sequence,\n gateway=self.ws.gateway,\n initial=False,\n resume=True,\n session=self.ws.session_id,\n )\n continue\n\n # We should only get this when an unhandled close code happens,\n # such as a clean disconnect (1000) or a bad state (bad token, no sharding, etc)\n # sometimes, discord sends us 1000 for unknown reasons so we should reconnect\n # regardless and rely on is_closed instead\n if isinstance(exc, ConnectionClosed):\n if exc.code == 4014:\n raise PrivilegedIntentsRequired(exc.shard_id) from None\n if exc.code != 1000:\n await self.close()\n raise\n\n retry = backoff.delay()\n _log.exception(\"Attempting a reconnect in %.2fs\", retry)\n await asyncio.sleep(retry)\n # Always try to RESUME the connection\n # If the connection is not RESUME-able then the gateway will invalidate the session.\n # This is apparently what the official Discord client does.\n ws_params.update(\n sequence=self.ws.sequence,\n gateway=self.ws.gateway,\n resume=True,\n session=self.ws.session_id,\n )\n\n async def close(self) -> None:\n \"\"\"|coro|\n\n Closes the connection to Discord.\n \"\"\"\n if self._closing_task:\n return await self._closing_task\n\n async def _close():\n await self._connection.close()\n\n if self.ws is not None and self.ws.open:\n await self.ws.close(code=1000)\n\n await self.http.close()\n\n if self._ready is not MISSING:\n self._ready.clear()\n\n self.loop = MISSING\n\n self._closing_task = asyncio.create_task(_close())\n await self._closing_task\n\n def clear(self) -> None:\n \"\"\"Clears the internal state of the bot.\n\n After this, the bot can be considered \"re-opened\", i.e. :meth:`is_closed`\n and :meth:`is_ready` both return ``False`` along with the bot's internal\n cache cleared.\n \"\"\"\n self._closing_task = None\n self._ready.clear()\n self._connection.clear()\n self.http.clear()\n\n async def start(self, token: str, *, reconnect: bool = True) -> None:\n \"\"\"|coro|\n\n A shorthand coroutine for :meth:`login` + :meth:`connect`.\n\n Parameters\n -----------\n token: :class:`str`\n The authentication token. Do not prefix this token with\n anything as the library will do it for you.\n reconnect: :class:`bool`\n If we should attempt reconnecting, either due to internet\n failure or a specific failure on Discord's part. Certain\n disconnects that lead to bad state will not be handled (such as\n invalid sharding payloads or bad tokens).\n\n Raises\n -------\n TypeError\n An unexpected keyword argument was received.\n \"\"\"\n await self.login(token)\n await self.connect(reconnect=reconnect)\n\n def run(\n self,\n token: str,\n *,\n reconnect: bool = True,\n log_handler: Optional[logging.Handler] = MISSING,\n log_formatter: logging.Formatter = MISSING,\n log_level: int = MISSING,\n root_logger: bool = False,\n ) -> None:\n \"\"\"A blocking call that abstracts away the event loop\n initialisation from you.\n\n If you want more control over the event loop then this\n function should not be used. Use :meth:`start` coroutine\n or :meth:`connect` + :meth:`login`.\n\n This function also sets up the logging library to make it easier\n for beginners to know what is going on with the library. For more\n advanced users, this can be disabled by passing ``None`` to\n the ``log_handler`` parameter.\n\n .. warning::\n\n This function must be the last function to call due to the fact that it\n is blocking. That means that registration of events or anything being\n called after this function call will not execute until it returns.\n\n Parameters\n -----------\n token: :class:`str`\n The authentication token. Do not prefix this token with\n anything as the library will do it for you.\n reconnect: :class:`bool`\n If we should attempt reconnecting, either due to internet\n failure or a specific failure on Discord's part. Certain\n disconnects that lead to bad state will not be handled (such as\n invalid sharding payloads or bad tokens).\n log_handler: Optional[:class:`logging.Handler`]\n The log handler to use for the library's logger. If this is ``None``\n then the library will not set up anything logging related. Logging\n will still work if ``None`` is passed, though it is your responsibility\n to set it up.\n\n The default log handler if not provided is :class:`logging.StreamHandler`.\n\n .. versionadded:: 2.0\n log_formatter: :class:`logging.Formatter`\n The formatter to use with the given log handler. If not provided then it\n defaults to a colour based logging formatter (if available).\n\n .. versionadded:: 2.0\n log_level: :class:`int`\n The default log level for the library's logger. This is only applied if the\n ``log_handler`` parameter is not ``None``. Defaults to ``logging.INFO``.\n\n .. versionadded:: 2.0\n root_logger: :class:`bool`\n Whether to set up the root logger rather than the library logger.\n By default, only the library logger (``'discord'``) is set up. If this\n is set to ``True`` then the root logger is set up as well.\n\n Defaults to ``False``.\n\n .. versionadded:: 2.0\n \"\"\"\n\n async def runner():\n async with self:\n await self.start(token, reconnect=reconnect)\n\n if log_handler is not None:\n utils.setup_logging(\n handler=log_handler,\n formatter=log_formatter,\n level=log_level,\n root=root_logger,\n )\n\n try:\n asyncio.run(runner())\n except KeyboardInterrupt:\n # nothing to do here\n # `asyncio.run` handles the loop cleanup\n # and `self.start` closes all sockets and the HTTPClient instance.\n return\n\n # properties\n\n def is_closed(self) -> bool:\n \"\"\":class:`bool`: Indicates if the websocket connection is closed.\"\"\"\n return self._closing_task is not None\n\n @property\n def activity(self) -> Optional[ActivityTypes]:\n \"\"\"Optional[:class:`.BaseActivity`]: The activity being used upon\n logging in.\n \"\"\"\n return create_activity(self._connection._activity, self._connection)\n\n @activity.setter\n def activity(self, value: Optional[ActivityTypes]) -> None:\n if value is None:\n self._connection._activity = None\n elif isinstance(value, BaseActivity):\n # ConnectionState._activity is typehinted as ActivityPayload, we're passing Dict[str, Any]\n self._connection._activity = value.to_dict() # type: ignore\n else:\n raise TypeError('activity must derive from BaseActivity.')\n\n @property\n def status(self) -> Status:\n \"\"\":class:`.Status`:\n The status being used upon logging on to Discord.\n\n .. versionadded: 2.0\n \"\"\"\n if self._connection._status in set(state.value for state in Status):\n return Status(self._connection._status)\n return Status.online\n\n @status.setter\n def status(self, value: Status) -> None:\n if value is Status.offline:\n self._connection._status = 'invisible'\n elif isinstance(value, Status):\n self._connection._status = str(value)\n else:\n raise TypeError('status must derive from Status.')\n\n @property\n def allowed_mentions(self) -> Optional[AllowedMentions]:\n \"\"\"Optional[:class:`~discord.AllowedMentions`]: The allowed mention configuration.\n\n .. versionadded:: 1.4\n \"\"\"\n return self._connection.allowed_mentions\n\n @allowed_mentions.setter\n def allowed_mentions(self, value: Optional[AllowedMentions]) -> None:\n if value is None or isinstance(value, AllowedMentions):\n self._connection.allowed_mentions = value\n else:\n raise TypeError(f'allowed_mentions must be AllowedMentions not {value.__class__.__name__}')\n\n @property\n def intents(self) -> Intents:\n \"\"\":class:`~discord.Intents`: The intents configured for this connection.\n\n .. versionadded:: 1.5\n \"\"\"\n return self._connection.intents\n\n # helpers/getters\n\n @property\n def users(self) -> List[User]:\n \"\"\"List[:class:`~discord.User`]: Returns a list of all the users the bot can see.\"\"\"\n return list(self._connection._users.values())\n\n def get_channel(self, id: int, /) -> Optional[Union[GuildChannel, Thread, PrivateChannel]]:\n \"\"\"Returns a channel or thread with the given ID.\n\n .. versionchanged:: 2.0\n\n ``id`` parameter is now positional-only.\n\n Parameters\n -----------\n id: :class:`int`\n The ID to search for.\n\n Returns\n --------\n Optional[Union[:class:`.abc.GuildChannel`, :class:`.Thread`, :class:`.abc.PrivateChannel`]]\n The returned channel or ``None`` if not found.\n \"\"\"\n return self._connection.get_channel(id) # type: ignore # The cache contains all channel types\n\n def get_partial_messageable(\n self, id: int, *, guild_id: Optional[int] = None, type: Optional[ChannelType] = None\n ) -> PartialMessageable:\n \"\"\"Returns a partial messageable with the given channel ID.\n\n This is useful if you have a channel_id but don't want to do an API call\n to send messages to it.\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n id: :class:`int`\n The channel ID to create a partial messageable for.\n guild_id: Optional[:class:`int`]\n The optional guild ID to create a partial messageable for.\n\n This is not required to actually send messages, but it does allow the\n :meth:`~discord.PartialMessageable.jump_url` and\n :attr:`~discord.PartialMessageable.guild` properties to function properly.\n type: Optional[:class:`.ChannelType`]\n The underlying channel type for the partial messageable.\n\n Returns\n --------\n :class:`.PartialMessageable`\n The partial messageable\n \"\"\"\n return PartialMessageable(state=self._connection, id=id, guild_id=guild_id, type=type)\n\n def get_stage_instance(self, id: int, /) -> Optional[StageInstance]:\n \"\"\"Returns a stage instance with the given stage channel ID.\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n id: :class:`int`\n The ID to search for.\n\n Returns\n --------\n Optional[:class:`.StageInstance`]\n The stage instance or ``None`` if not found.\n \"\"\"\n from .channel import StageChannel\n\n channel = self._connection.get_channel(id)\n\n if isinstance(channel, StageChannel):\n return channel.instance\n\n def get_guild(self, id: int, /) -> Optional[Guild]:\n \"\"\"Returns a guild with the given ID.\n\n .. versionchanged:: 2.0\n\n ``id`` parameter is now positional-only.\n\n Parameters\n -----------\n id: :class:`int`\n The ID to search for.\n\n Returns\n --------\n Optional[:class:`.Guild`]\n The guild or ``None`` if not found.\n \"\"\"\n return self._connection._get_guild(id)\n\n def get_user(self, id: int, /) -> Optional[User]:\n \"\"\"Returns a user with the given ID.\n\n .. versionchanged:: 2.0\n\n ``id`` parameter is now positional-only.\n\n Parameters\n -----------\n id: :class:`int`\n The ID to search for.\n\n Returns\n --------\n Optional[:class:`~discord.User`]\n The user or ``None`` if not found.\n \"\"\"\n return self._connection.get_user(id)\n\n def get_emoji(self, id: int, /) -> Optional[Emoji]:\n \"\"\"Returns an emoji with the given ID.\n\n .. versionchanged:: 2.0\n\n ``id`` parameter is now positional-only.\n\n Parameters\n -----------\n id: :class:`int`\n The ID to search for.\n\n Returns\n --------\n Optional[:class:`.Emoji`]\n The custom emoji or ``None`` if not found.\n \"\"\"\n return self._connection.get_emoji(id)\n\n def get_sticker(self, id: int, /) -> Optional[GuildSticker]:\n \"\"\"Returns a guild sticker with the given ID.\n\n .. versionadded:: 2.0\n\n .. note::\n\n To retrieve standard stickers, use :meth:`.fetch_sticker`.\n or :meth:`.fetch_premium_sticker_packs`.\n\n Returns\n --------\n Optional[:class:`.GuildSticker`]\n The sticker or ``None`` if not found.\n \"\"\"\n return self._connection.get_sticker(id)\n\n def get_all_channels(self) -> Generator[GuildChannel, None, None]:\n \"\"\"A generator that retrieves every :class:`.abc.GuildChannel` the client can 'access'.\n\n This is equivalent to: ::\n\n for guild in client.guilds:\n for channel in guild.channels:\n yield channel\n\n .. note::\n\n Just because you receive a :class:`.abc.GuildChannel` does not mean that\n you can communicate in said channel. :meth:`.abc.GuildChannel.permissions_for` should\n be used for that.\n\n Yields\n ------\n :class:`.abc.GuildChannel`\n A channel the client can 'access'.\n \"\"\"\n\n for guild in self.guilds:\n yield from guild.channels\n\n def get_all_members(self) -> Generator[Member, None, None]:\n \"\"\"Returns a generator with every :class:`.Member` the client can see.\n\n This is equivalent to: ::\n\n for guild in client.guilds:\n for member in guild.members:\n yield member\n\n Yields\n ------\n :class:`.Member`\n A member the client can see.\n \"\"\"\n for guild in self.guilds:\n yield from guild.members\n\n # listeners/waiters\n\n async def wait_until_ready(self) -> None:\n \"\"\"|coro|\n\n Waits until the client's internal cache is all ready.\n\n .. warning::\n\n Calling this inside :meth:`setup_hook` can lead to a deadlock.\n \"\"\"\n if self._ready is not MISSING:\n await self._ready.wait()\n else:\n raise RuntimeError(\n 'Client has not been properly initialised. '\n 'Please use the login method or asynchronous context manager before calling this method'\n )\n\n # App Commands\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_app_command_permissions_update'],\n /,\n *,\n check: Optional[Callable[[RawAppCommandPermissionsUpdateEvent], bool]],\n timeout: Optional[float] = None,\n ) -> RawAppCommandPermissionsUpdateEvent:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['app_command_completion'],\n /,\n *,\n check: Optional[Callable[[Interaction[Self], Union[Command[Any, ..., Any], ContextMenu]], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Interaction[Self], Union[Command[Any, ..., Any], ContextMenu]]:\n ...\n\n # AutoMod\n\n @overload\n async def wait_for(\n self,\n event: Literal['automod_rule_create', 'automod_rule_update', 'automod_rule_delete'],\n /,\n *,\n check: Optional[Callable[[AutoModRule], bool]],\n timeout: Optional[float] = None,\n ) -> AutoModRule:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['automod_action'],\n /,\n *,\n check: Optional[Callable[[AutoModAction], bool]],\n timeout: Optional[float] = None,\n ) -> AutoModAction:\n ...\n\n # Channels\n\n @overload\n async def wait_for(\n self,\n event: Literal['private_channel_update'],\n /,\n *,\n check: Optional[Callable[[GroupChannel, GroupChannel], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[GroupChannel, GroupChannel]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['private_channel_pins_update'],\n /,\n *,\n check: Optional[Callable[[PrivateChannel, datetime.datetime], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[PrivateChannel, datetime.datetime]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['guild_channel_delete', 'guild_channel_create'],\n /,\n *,\n check: Optional[Callable[[GuildChannel], bool]],\n timeout: Optional[float] = None,\n ) -> GuildChannel:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['guild_channel_update'],\n /,\n *,\n check: Optional[Callable[[GuildChannel, GuildChannel], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[GuildChannel, GuildChannel]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['guild_channel_pins_update'],\n /,\n *,\n check: Optional[\n Callable[\n [Union[GuildChannel, Thread], Optional[datetime.datetime]],\n bool,\n ]\n ],\n timeout: Optional[float] = None,\n ) -> Tuple[Union[GuildChannel, Thread], Optional[datetime.datetime]]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['typing'],\n /,\n *,\n check: Optional[Callable[[Messageable, Union[User, Member], datetime.datetime], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Messageable, Union[User, Member], datetime.datetime]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_typing'],\n /,\n *,\n check: Optional[Callable[[RawTypingEvent], bool]],\n timeout: Optional[float] = None,\n ) -> RawTypingEvent:\n ...\n\n # Debug & Gateway events\n\n @overload\n async def wait_for(\n self,\n event: Literal['connect', 'disconnect', 'ready', 'resumed'],\n /,\n *,\n check: Optional[Callable[[], bool]],\n timeout: Optional[float] = None,\n ) -> None:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['shard_connect', 'shard_disconnect', 'shard_ready', 'shard_resumed'],\n /,\n *,\n check: Optional[Callable[[int], bool]],\n timeout: Optional[float] = None,\n ) -> int:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['socket_event_type', 'socket_raw_receive'],\n /,\n *,\n check: Optional[Callable[[str], bool]],\n timeout: Optional[float] = None,\n ) -> str:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['socket_raw_send'],\n /,\n *,\n check: Optional[Callable[[Union[str, bytes]], bool]],\n timeout: Optional[float] = None,\n ) -> Union[str, bytes]:\n ...\n\n # Guilds\n\n @overload\n async def wait_for(\n self,\n event: Literal[\n 'guild_available',\n 'guild_unavailable',\n 'guild_join',\n 'guild_remove',\n ],\n /,\n *,\n check: Optional[Callable[[Guild], bool]],\n timeout: Optional[float] = None,\n ) -> Guild:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['guild_update'],\n /,\n *,\n check: Optional[Callable[[Guild, Guild], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Guild, Guild]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['guild_emojis_update'],\n /,\n *,\n check: Optional[Callable[[Guild, Sequence[Emoji], Sequence[Emoji]], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Guild, Sequence[Emoji], Sequence[Emoji]]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['guild_stickers_update'],\n /,\n *,\n check: Optional[Callable[[Guild, Sequence[GuildSticker], Sequence[GuildSticker]], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Guild, Sequence[GuildSticker], Sequence[GuildSticker]]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['invite_create', 'invite_delete'],\n /,\n *,\n check: Optional[Callable[[Invite], bool]],\n timeout: Optional[float] = None,\n ) -> Invite:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['audit_log_entry_create'],\n /,\n *,\n check: Optional[Callable[[AuditLogEntry], bool]],\n timeout: Optional[float] = None,\n ) -> AuditLogEntry:\n ...\n\n # Integrations\n\n @overload\n async def wait_for(\n self,\n event: Literal['integration_create', 'integration_update'],\n /,\n *,\n check: Optional[Callable[[Integration], bool]],\n timeout: Optional[float] = None,\n ) -> Integration:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['guild_integrations_update'],\n /,\n *,\n check: Optional[Callable[[Guild], bool]],\n timeout: Optional[float] = None,\n ) -> Guild:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['webhooks_update'],\n /,\n *,\n check: Optional[Callable[[GuildChannel], bool]],\n timeout: Optional[float] = None,\n ) -> GuildChannel:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_integration_delete'],\n /,\n *,\n check: Optional[Callable[[RawIntegrationDeleteEvent], bool]],\n timeout: Optional[float] = None,\n ) -> RawIntegrationDeleteEvent:\n ...\n\n # Interactions\n\n @overload\n async def wait_for(\n self,\n event: Literal['interaction'],\n /,\n *,\n check: Optional[Callable[[Interaction[Self]], bool]],\n timeout: Optional[float] = None,\n ) -> Interaction[Self]:\n ...\n\n # Members\n\n @overload\n async def wait_for(\n self,\n event: Literal['member_join', 'member_remove'],\n /,\n *,\n check: Optional[Callable[[Member], bool]],\n timeout: Optional[float] = None,\n ) -> Member:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_member_remove'],\n /,\n *,\n check: Optional[Callable[[RawMemberRemoveEvent], bool]],\n timeout: Optional[float] = None,\n ) -> RawMemberRemoveEvent:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['member_update', 'presence_update'],\n /,\n *,\n check: Optional[Callable[[Member, Member], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Member, Member]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['user_update'],\n /,\n *,\n check: Optional[Callable[[User, User], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[User, User]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['member_ban'],\n /,\n *,\n check: Optional[Callable[[Guild, Union[User, Member]], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Guild, Union[User, Member]]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['member_unban'],\n /,\n *,\n check: Optional[Callable[[Guild, User], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Guild, User]:\n ...\n\n # Messages\n\n @overload\n async def wait_for(\n self,\n event: Literal['message', 'message_delete'],\n /,\n *,\n check: Optional[Callable[[Message], bool]],\n timeout: Optional[float] = None,\n ) -> Message:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['message_edit'],\n /,\n *,\n check: Optional[Callable[[Message, Message], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Message, Message]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['bulk_message_delete'],\n /,\n *,\n check: Optional[Callable[[List[Message]], bool]],\n timeout: Optional[float] = None,\n ) -> List[Message]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_message_edit'],\n /,\n *,\n check: Optional[Callable[[RawMessageUpdateEvent], bool]],\n timeout: Optional[float] = None,\n ) -> RawMessageUpdateEvent:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_message_delete'],\n /,\n *,\n check: Optional[Callable[[RawMessageDeleteEvent], bool]],\n timeout: Optional[float] = None,\n ) -> RawMessageDeleteEvent:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_bulk_message_delete'],\n /,\n *,\n check: Optional[Callable[[RawBulkMessageDeleteEvent], bool]],\n timeout: Optional[float] = None,\n ) -> RawBulkMessageDeleteEvent:\n ...\n\n # Reactions\n\n @overload\n async def wait_for(\n self,\n event: Literal['reaction_add', 'reaction_remove'],\n /,\n *,\n check: Optional[Callable[[Reaction, Union[Member, User]], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Reaction, Union[Member, User]]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['reaction_clear'],\n /,\n *,\n check: Optional[Callable[[Message, List[Reaction]], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Message, List[Reaction]]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['reaction_clear_emoji'],\n /,\n *,\n check: Optional[Callable[[Reaction], bool]],\n timeout: Optional[float] = None,\n ) -> Reaction:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_reaction_add', 'raw_reaction_remove'],\n /,\n *,\n check: Optional[Callable[[RawReactionActionEvent], bool]],\n timeout: Optional[float] = None,\n ) -> RawReactionActionEvent:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_reaction_clear'],\n /,\n *,\n check: Optional[Callable[[RawReactionClearEvent], bool]],\n timeout: Optional[float] = None,\n ) -> RawReactionClearEvent:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_reaction_clear_emoji'],\n /,\n *,\n check: Optional[Callable[[RawReactionClearEmojiEvent], bool]],\n timeout: Optional[float] = None,\n ) -> RawReactionClearEmojiEvent:\n ...\n\n # Roles\n\n @overload\n async def wait_for(\n self,\n event: Literal['guild_role_create', 'guild_role_delete'],\n /,\n *,\n check: Optional[Callable[[Role], bool]],\n timeout: Optional[float] = None,\n ) -> Role:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['guild_role_update'],\n /,\n *,\n check: Optional[Callable[[Role, Role], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Role, Role]:\n ...\n\n # Scheduled Events\n\n @overload\n async def wait_for(\n self,\n event: Literal['scheduled_event_create', 'scheduled_event_delete'],\n /,\n *,\n check: Optional[Callable[[ScheduledEvent], bool]],\n timeout: Optional[float] = None,\n ) -> ScheduledEvent:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['scheduled_event_user_add', 'scheduled_event_user_remove'],\n /,\n *,\n check: Optional[Callable[[ScheduledEvent, User], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[ScheduledEvent, User]:\n ...\n\n # Stages\n\n @overload\n async def wait_for(\n self,\n event: Literal['stage_instance_create', 'stage_instance_delete'],\n /,\n *,\n check: Optional[Callable[[StageInstance], bool]],\n timeout: Optional[float] = None,\n ) -> StageInstance:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['stage_instance_update'],\n /,\n *,\n check: Optional[Callable[[StageInstance, StageInstance], bool]],\n timeout: Optional[float] = None,\n ) -> Coroutine[Any, Any, Tuple[StageInstance, StageInstance]]:\n ...\n\n # Threads\n @overload\n async def wait_for(\n self,\n event: Literal['thread_create', 'thread_join', 'thread_remove', 'thread_delete'],\n /,\n *,\n check: Optional[Callable[[Thread], bool]],\n timeout: Optional[float] = None,\n ) -> Thread:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['thread_update'],\n /,\n *,\n check: Optional[Callable[[Thread, Thread], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Thread, Thread]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_thread_update'],\n /,\n *,\n check: Optional[Callable[[RawThreadUpdateEvent], bool]],\n timeout: Optional[float] = None,\n ) -> RawThreadUpdateEvent:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_thread_delete'],\n /,\n *,\n check: Optional[Callable[[RawThreadDeleteEvent], bool]],\n timeout: Optional[float] = None,\n ) -> RawThreadDeleteEvent:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['thread_member_join', 'thread_member_remove'],\n /,\n *,\n check: Optional[Callable[[ThreadMember], bool]],\n timeout: Optional[float] = None,\n ) -> ThreadMember:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_thread_member_remove'],\n /,\n *,\n check: Optional[Callable[[RawThreadMembersUpdate], bool]],\n timeout: Optional[float] = None,\n ) -> RawThreadMembersUpdate:\n ...\n\n # Voice\n\n @overload\n async def wait_for(\n self,\n event: Literal['voice_state_update'],\n /,\n *,\n check: Optional[Callable[[Member, VoiceState, VoiceState], bool]],\n timeout: Optional[float] = None,\n ) -> Tuple[Member, VoiceState, VoiceState]:\n ...\n\n # Polls\n\n @overload\n async def wait_for(\n self,\n event: Literal['poll_vote_add', 'poll_vote_remove'],\n /,\n *,\n check: Optional[Callable[[Union[User, Member], PollAnswer], bool]] = None,\n timeout: Optional[float] = None,\n ) -> Tuple[Union[User, Member], PollAnswer]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: Literal['raw_poll_vote_add', 'raw_poll_vote_remove'],\n /,\n *,\n check: Optional[Callable[[RawPollVoteActionEvent], bool]] = None,\n timeout: Optional[float] = None,\n ) -> RawPollVoteActionEvent:\n ...\n\n # Commands\n\n @overload\n async def wait_for(\n self: Union[Bot, AutoShardedBot],\n event: Literal[\"command\", \"command_completion\"],\n /,\n *,\n check: Optional[Callable[[Context[Any]], bool]] = None,\n timeout: Optional[float] = None,\n ) -> Context[Any]:\n ...\n\n @overload\n async def wait_for(\n self: Union[Bot, AutoShardedBot],\n event: Literal[\"command_error\"],\n /,\n *,\n check: Optional[Callable[[Context[Any], CommandError], bool]] = None,\n timeout: Optional[float] = None,\n ) -> Tuple[Context[Any], CommandError]:\n ...\n\n @overload\n async def wait_for(\n self,\n event: str,\n /,\n *,\n check: Optional[Callable[..., bool]] = None,\n timeout: Optional[float] = None,\n ) -> Any:\n ...\n\n def wait_for(\n self,\n event: str,\n /,\n *,\n check: Optional[Callable[..., bool]] = None,\n timeout: Optional[float] = None,\n ) -> Coro[Any]:\n \"\"\"|coro|\n\n Waits for a WebSocket event to be dispatched.\n\n This could be used to wait for a user to reply to a message,\n or to react to a message, or to edit a message in a self-contained\n way.\n\n The ``timeout`` parameter is passed onto :func:`asyncio.wait_for`. By default,\n it does not timeout. Note that this does propagate the\n :exc:`asyncio.TimeoutError` for you in case of timeout and is provided for\n ease of use.\n\n In case the event returns multiple arguments, a :class:`tuple` containing those\n arguments is returned instead. Please check the\n :ref:`documentation ` for a list of events and their\n parameters.\n\n This function returns the **first event that meets the requirements**.\n\n Examples\n ---------\n\n Waiting for a user reply: ::\n\n @client.event\n async def on_message(message):\n if message.content.startswith('$greet'):\n channel = message.channel\n await channel.send('Say hello!')\n\n def check(m):\n return m.content == 'hello' and m.channel == channel\n\n msg = await client.wait_for('message', check=check)\n await channel.send(f'Hello {msg.author}!')\n\n Waiting for a thumbs up reaction from the message author: ::\n\n @client.event\n async def on_message(message):\n if message.content.startswith('$thumb'):\n channel = message.channel\n await channel.send('Send me that \\N{THUMBS UP SIGN} reaction, mate')\n\n def check(reaction, user):\n return user == message.author and str(reaction.emoji) == '\\N{THUMBS UP SIGN}'\n\n try:\n reaction, user = await client.wait_for('reaction_add', timeout=60.0, check=check)\n except asyncio.TimeoutError:\n await channel.send('\\N{THUMBS DOWN SIGN}')\n else:\n await channel.send('\\N{THUMBS UP SIGN}')\n\n .. versionchanged:: 2.0\n\n ``event`` parameter is now positional-only.\n\n\n Parameters\n ------------\n event: :class:`str`\n The event name, similar to the :ref:`event reference `,\n but without the ``on_`` prefix, to wait for.\n check: Optional[Callable[..., :class:`bool`]]\n A predicate to check what to wait for. The arguments must meet the\n parameters of the event being waited for.\n timeout: Optional[:class:`float`]\n The number of seconds to wait before timing out and raising\n :exc:`asyncio.TimeoutError`.\n\n Raises\n -------\n asyncio.TimeoutError\n If a timeout is provided and it was reached.\n\n Returns\n --------\n Any\n Returns no arguments, a single argument, or a :class:`tuple` of multiple\n arguments that mirrors the parameters passed in the\n :ref:`event reference `.\n \"\"\"\n\n future = self.loop.create_future()\n if check is None:\n\n def _check(*args):\n return True\n\n check = _check\n\n ev = event.lower()\n try:\n listeners = self._listeners[ev]\n except KeyError:\n listeners = []\n self._listeners[ev] = listeners\n\n listeners.append((future, check))\n return asyncio.wait_for(future, timeout)\n\n # event registration\n\n def event(self, coro: CoroT, /) -> CoroT:\n \"\"\"A decorator that registers an event to listen to.\n\n You can find more info about the events on the :ref:`documentation below `.\n\n The events must be a :ref:`coroutine `, if not, :exc:`TypeError` is raised.\n\n Example\n ---------\n\n .. code-block:: python3\n\n @client.event\n async def on_ready():\n print('Ready!')\n\n .. versionchanged:: 2.0\n\n ``coro`` parameter is now positional-only.\n\n Raises\n --------\n TypeError\n The coroutine passed is not actually a coroutine.\n \"\"\"\n\n if not asyncio.iscoroutinefunction(coro):\n raise TypeError('event registered must be a coroutine function')\n\n setattr(self, coro.__name__, coro)\n _log.debug('%s has successfully been registered as an event', coro.__name__)\n return coro\n\n async def change_presence(\n self,\n *,\n activity: Optional[BaseActivity] = None,\n status: Optional[Status] = None,\n ) -> None:\n \"\"\"|coro|\n\n Changes the client's presence.\n\n Example\n ---------\n\n .. code-block:: python3\n\n game = discord.Game(\"with the API\")\n await client.change_presence(status=discord.Status.idle, activity=game)\n\n .. versionchanged:: 2.0\n Removed the ``afk`` keyword-only parameter.\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`TypeError` instead of\n ``InvalidArgument``.\n\n Parameters\n ----------\n activity: Optional[:class:`.BaseActivity`]\n The activity being done. ``None`` if no currently active activity is done.\n status: Optional[:class:`.Status`]\n Indicates what status to change to. If ``None``, then\n :attr:`.Status.online` is used.\n\n Raises\n ------\n TypeError\n If the ``activity`` parameter is not the proper type.\n \"\"\"\n\n if status is None:\n status_str = 'online'\n status = Status.online\n elif status is Status.offline:\n status_str = 'invisible'\n status = Status.offline\n else:\n status_str = str(status)\n\n await self.ws.change_presence(activity=activity, status=status_str)\n\n for guild in self._connection.guilds:\n me = guild.me\n if me is None:\n continue\n\n if activity is not None:\n me.activities = (activity,) # type: ignore # Type checker does not understand the downcast here\n else:\n me.activities = ()\n\n me.status = status\n\n # Guild stuff\n\n async def fetch_guilds(\n self,\n *,\n limit: Optional[int] = 200,\n before: Optional[SnowflakeTime] = None,\n after: Optional[SnowflakeTime] = None,\n with_counts: bool = True,\n ) -> AsyncIterator[Guild]:\n \"\"\"Retrieves an :term:`asynchronous iterator` that enables receiving your guilds.\n\n .. note::\n\n Using this, you will only receive :attr:`.Guild.owner`, :attr:`.Guild.icon`,\n :attr:`.Guild.id`, :attr:`.Guild.name`, :attr:`.Guild.approximate_member_count`,\n and :attr:`.Guild.approximate_presence_count` per :class:`.Guild`.\n\n .. note::\n\n This method is an API call. For general usage, consider :attr:`guilds` instead.\n\n Examples\n ---------\n\n Usage ::\n\n async for guild in client.fetch_guilds(limit=150):\n print(guild.name)\n\n Flattening into a list ::\n\n guilds = [guild async for guild in client.fetch_guilds(limit=150)]\n # guilds is now a list of Guild...\n\n All parameters are optional.\n\n Parameters\n -----------\n limit: Optional[:class:`int`]\n The number of guilds to retrieve.\n If ``None``, it retrieves every guild you have access to. Note, however,\n that this would make it a slow operation.\n Defaults to ``200``.\n\n .. versionchanged:: 2.0\n\n The default has been changed to 200.\n\n before: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`]\n Retrieves guilds before this date or object.\n If a datetime is provided, it is recommended to use a UTC aware datetime.\n If the datetime is naive, it is assumed to be local time.\n after: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`]\n Retrieve guilds after this date or object.\n If a datetime is provided, it is recommended to use a UTC aware datetime.\n If the datetime is naive, it is assumed to be local time.\n with_counts: :class:`bool`\n Whether to include count information in the guilds. This fills the\n :attr:`.Guild.approximate_member_count` and :attr:`.Guild.approximate_presence_count`\n attributes without needing any privileged intents. Defaults to ``True``.\n\n .. versionadded:: 2.3\n\n Raises\n ------\n HTTPException\n Getting the guilds failed.\n\n Yields\n --------\n :class:`.Guild`\n The guild with the guild data parsed.\n \"\"\"\n\n async def _before_strategy(retrieve: int, before: Optional[Snowflake], limit: Optional[int]):\n before_id = before.id if before else None\n data = await self.http.get_guilds(retrieve, before=before_id, with_counts=with_counts)\n\n if data:\n if limit is not None:\n limit -= len(data)\n\n before = Object(id=int(data[0]['id']))\n\n return data, before, limit\n\n async def _after_strategy(retrieve: int, after: Optional[Snowflake], limit: Optional[int]):\n after_id = after.id if after else None\n data = await self.http.get_guilds(retrieve, after=after_id, with_counts=with_counts)\n\n if data:\n if limit is not None:\n limit -= len(data)\n\n after = Object(id=int(data[-1]['id']))\n\n return data, after, limit\n\n if isinstance(before, datetime.datetime):\n before = Object(id=time_snowflake(before, high=False))\n if isinstance(after, datetime.datetime):\n after = Object(id=time_snowflake(after, high=True))\n\n predicate: Optional[Callable[[GuildPayload], bool]] = None\n strategy, state = _after_strategy, after\n\n if before:\n strategy, state = _before_strategy, before\n\n if before and after:\n predicate = lambda m: int(m['id']) > after.id\n\n while True:\n retrieve = 200 if limit is None else min(limit, 200)\n if retrieve < 1:\n return\n\n data, state, limit = await strategy(retrieve, state, limit)\n\n if predicate:\n data = filter(predicate, data)\n\n count = 0\n\n for count, raw_guild in enumerate(data, 1):\n yield Guild(state=self._connection, data=raw_guild)\n\n if count < 200:\n # There's no data left after this\n break\n\n async def fetch_template(self, code: Union[Template, str]) -> Template:\n \"\"\"|coro|\n\n Gets a :class:`.Template` from a discord.new URL or code.\n\n Parameters\n -----------\n code: Union[:class:`.Template`, :class:`str`]\n The Discord Template Code or URL (must be a discord.new URL).\n\n Raises\n -------\n NotFound\n The template is invalid.\n HTTPException\n Getting the template failed.\n\n Returns\n --------\n :class:`.Template`\n The template from the URL/code.\n \"\"\"\n code = utils.resolve_template(code)\n data = await self.http.get_template(code)\n return Template(data=data, state=self._connection)\n\n async def fetch_guild(self, guild_id: int, /, *, with_counts: bool = True) -> Guild:\n \"\"\"|coro|\n\n Retrieves a :class:`.Guild` from an ID.\n\n .. note::\n\n Using this, you will **not** receive :attr:`.Guild.channels`, :attr:`.Guild.members`,\n :attr:`.Member.activity` and :attr:`.Member.voice` per :class:`.Member`.\n\n .. note::\n\n This method is an API call. For general usage, consider :meth:`get_guild` instead.\n\n .. versionchanged:: 2.0\n\n ``guild_id`` parameter is now positional-only.\n\n\n Parameters\n -----------\n guild_id: :class:`int`\n The guild's ID to fetch from.\n with_counts: :class:`bool`\n Whether to include count information in the guild. This fills the\n :attr:`.Guild.approximate_member_count` and :attr:`.Guild.approximate_presence_count`\n attributes without needing any privileged intents. Defaults to ``True``.\n\n .. versionadded:: 2.0\n\n Raises\n ------\n NotFound\n The guild doesn't exist or you got no access to it.\n HTTPException\n Getting the guild failed.\n\n Returns\n --------\n :class:`.Guild`\n The guild from the ID.\n \"\"\"\n data = await self.http.get_guild(guild_id, with_counts=with_counts)\n return Guild(data=data, state=self._connection)\n\n async def create_guild(\n self,\n *,\n name: str,\n icon: bytes = MISSING,\n code: str = MISSING,\n ) -> Guild:\n \"\"\"|coro|\n\n Creates a :class:`.Guild`.\n\n Bot accounts in more than 10 guilds are not allowed to create guilds.\n\n .. versionchanged:: 2.0\n ``name`` and ``icon`` parameters are now keyword-only. The ``region`` parameter has been removed.\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`ValueError` instead of\n ``InvalidArgument``.\n\n Parameters\n ----------\n name: :class:`str`\n The name of the guild.\n icon: Optional[:class:`bytes`]\n The :term:`py:bytes-like object` representing the icon. See :meth:`.ClientUser.edit`\n for more details on what is expected.\n code: :class:`str`\n The code for a template to create the guild with.\n\n .. versionadded:: 1.4\n\n Raises\n ------\n HTTPException\n Guild creation failed.\n ValueError\n Invalid icon image format given. Must be PNG or JPG.\n\n Returns\n -------\n :class:`.Guild`\n The guild created. This is not the same guild that is\n added to cache.\n \"\"\"\n if icon is not MISSING:\n icon_base64 = utils._bytes_to_base64_data(icon)\n else:\n icon_base64 = None\n\n if code:\n data = await self.http.create_from_template(code, name, icon_base64)\n else:\n data = await self.http.create_guild(name, icon_base64)\n return Guild(data=data, state=self._connection)\n\n async def fetch_stage_instance(self, channel_id: int, /) -> StageInstance:\n \"\"\"|coro|\n\n Gets a :class:`.StageInstance` for a stage channel id.\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n channel_id: :class:`int`\n The stage channel ID.\n\n Raises\n -------\n NotFound\n The stage instance or channel could not be found.\n HTTPException\n Getting the stage instance failed.\n\n Returns\n --------\n :class:`.StageInstance`\n The stage instance from the stage channel ID.\n \"\"\"\n data = await self.http.get_stage_instance(channel_id)\n guild = self.get_guild(int(data['guild_id']))\n # Guild can technically be None here but this is being explicitly silenced right now.\n return StageInstance(guild=guild, state=self._connection, data=data) # type: ignore\n\n # Invite management\n\n async def fetch_invite(\n self,\n url: Union[Invite, str],\n *,\n with_counts: bool = True,\n with_expiration: bool = True,\n scheduled_event_id: Optional[int] = None,\n ) -> Invite:\n \"\"\"|coro|\n\n Gets an :class:`.Invite` from a discord.gg URL or ID.\n\n .. note::\n\n If the invite is for a guild you have not joined, the guild and channel\n attributes of the returned :class:`.Invite` will be :class:`.PartialInviteGuild` and\n :class:`.PartialInviteChannel` respectively.\n\n Parameters\n -----------\n url: Union[:class:`.Invite`, :class:`str`]\n The Discord invite ID or URL (must be a discord.gg URL).\n with_counts: :class:`bool`\n Whether to include count information in the invite. This fills the\n :attr:`.Invite.approximate_member_count` and :attr:`.Invite.approximate_presence_count`\n fields.\n with_expiration: :class:`bool`\n Whether to include the expiration date of the invite. This fills the\n :attr:`.Invite.expires_at` field.\n\n .. versionadded:: 2.0\n scheduled_event_id: Optional[:class:`int`]\n The ID of the scheduled event this invite is for.\n\n .. note::\n\n It is not possible to provide a url that contains an ``event_id`` parameter\n when using this parameter.\n\n .. versionadded:: 2.0\n\n Raises\n -------\n ValueError\n The url contains an ``event_id``, but ``scheduled_event_id`` has also been provided.\n NotFound\n The invite has expired or is invalid.\n HTTPException\n Getting the invite failed.\n\n Returns\n --------\n :class:`.Invite`\n The invite from the URL/ID.\n \"\"\"\n\n resolved = utils.resolve_invite(url)\n\n if scheduled_event_id and resolved.event:\n raise ValueError('Cannot specify scheduled_event_id and contain an event_id in the url.')\n\n scheduled_event_id = scheduled_event_id or resolved.event\n\n data = await self.http.get_invite(\n resolved.code,\n with_counts=with_counts,\n with_expiration=with_expiration,\n guild_scheduled_event_id=scheduled_event_id,\n )\n return Invite.from_incomplete(state=self._connection, data=data)\n\n async def delete_invite(self, invite: Union[Invite, str], /) -> None:\n \"\"\"|coro|\n\n Revokes an :class:`.Invite`, URL, or ID to an invite.\n\n You must have :attr:`~.Permissions.manage_channels` in\n the associated guild to do this.\n\n .. versionchanged:: 2.0\n\n ``invite`` parameter is now positional-only.\n\n Parameters\n ----------\n invite: Union[:class:`.Invite`, :class:`str`]\n The invite to revoke.\n\n Raises\n -------\n Forbidden\n You do not have permissions to revoke invites.\n NotFound\n The invite is invalid or expired.\n HTTPException\n Revoking the invite failed.\n \"\"\"\n\n resolved = utils.resolve_invite(invite)\n await self.http.delete_invite(resolved.code)\n\n # Miscellaneous stuff\n\n async def fetch_widget(self, guild_id: int, /) -> Widget:\n \"\"\"|coro|\n\n Gets a :class:`.Widget` from a guild ID.\n\n .. note::\n\n The guild must have the widget enabled to get this information.\n\n .. versionchanged:: 2.0\n\n ``guild_id`` parameter is now positional-only.\n\n Parameters\n -----------\n guild_id: :class:`int`\n The ID of the guild.\n\n Raises\n -------\n Forbidden\n The widget for this guild is disabled.\n HTTPException\n Retrieving the widget failed.\n\n Returns\n --------\n :class:`.Widget`\n The guild's widget.\n \"\"\"\n data = await self.http.get_widget(guild_id)\n\n return Widget(state=self._connection, data=data)\n\n async def application_info(self) -> AppInfo:\n \"\"\"|coro|\n\n Retrieves the bot's application information.\n\n Raises\n -------\n HTTPException\n Retrieving the information failed somehow.\n\n Returns\n --------\n :class:`.AppInfo`\n The bot's application information.\n \"\"\"\n data = await self.http.application_info()\n return AppInfo(self._connection, data)\n\n async def fetch_user(self, user_id: int, /) -> User:\n \"\"\"|coro|\n\n Retrieves a :class:`~discord.User` based on their ID.\n You do not have to share any guilds with the user to get this information,\n however many operations do require that you do.\n\n .. note::\n\n This method is an API call. If you have :attr:`discord.Intents.members` and member cache enabled, consider :meth:`get_user` instead.\n\n .. versionchanged:: 2.0\n\n ``user_id`` parameter is now positional-only.\n\n Parameters\n -----------\n user_id: :class:`int`\n The user's ID to fetch from.\n\n Raises\n -------\n NotFound\n A user with this ID does not exist.\n HTTPException\n Fetching the user failed.\n\n Returns\n --------\n :class:`~discord.User`\n The user you requested.\n \"\"\"\n data = await self.http.get_user(user_id)\n return User(state=self._connection, data=data)\n\n async def fetch_channel(self, channel_id: int, /) -> Union[GuildChannel, PrivateChannel, Thread]:\n \"\"\"|coro|\n\n Retrieves a :class:`.abc.GuildChannel`, :class:`.abc.PrivateChannel`, or :class:`.Thread` with the specified ID.\n\n .. note::\n\n This method is an API call. For general usage, consider :meth:`get_channel` instead.\n\n .. versionadded:: 1.2\n\n .. versionchanged:: 2.0\n\n ``channel_id`` parameter is now positional-only.\n\n Raises\n -------\n InvalidData\n An unknown channel type was received from Discord.\n HTTPException\n Retrieving the channel failed.\n NotFound\n Invalid Channel ID.\n Forbidden\n You do not have permission to fetch this channel.\n\n Returns\n --------\n Union[:class:`.abc.GuildChannel`, :class:`.abc.PrivateChannel`, :class:`.Thread`]\n The channel from the ID.\n \"\"\"\n data = await self.http.get_channel(channel_id)\n\n factory, ch_type = _threaded_channel_factory(data['type'])\n if factory is None:\n raise InvalidData('Unknown channel type {type} for channel ID {id}.'.format_map(data))\n\n if ch_type in (ChannelType.group, ChannelType.private):\n # the factory will be a DMChannel or GroupChannel here\n channel = factory(me=self.user, data=data, state=self._connection) # type: ignore\n else:\n # the factory can't be a DMChannel or GroupChannel here\n guild_id = int(data['guild_id']) # type: ignore\n guild = self._connection._get_or_create_unavailable_guild(guild_id)\n # the factory should be a GuildChannel or Thread\n channel = factory(guild=guild, state=self._connection, data=data) # type: ignore\n\n return channel\n\n async def fetch_webhook(self, webhook_id: int, /) -> Webhook:\n \"\"\"|coro|\n\n Retrieves a :class:`.Webhook` with the specified ID.\n\n .. versionchanged:: 2.0\n\n ``webhook_id`` parameter is now positional-only.\n\n Raises\n --------\n HTTPException\n Retrieving the webhook failed.\n NotFound\n Invalid webhook ID.\n Forbidden\n You do not have permission to fetch this webhook.\n\n Returns\n ---------\n :class:`.Webhook`\n The webhook you requested.\n \"\"\"\n data = await self.http.get_webhook(webhook_id)\n return Webhook.from_state(data, state=self._connection)\n\n async def fetch_sticker(self, sticker_id: int, /) -> Union[StandardSticker, GuildSticker]:\n \"\"\"|coro|\n\n Retrieves a :class:`.Sticker` with the specified ID.\n\n .. versionadded:: 2.0\n\n Raises\n --------\n HTTPException\n Retrieving the sticker failed.\n NotFound\n Invalid sticker ID.\n\n Returns\n --------\n Union[:class:`.StandardSticker`, :class:`.GuildSticker`]\n The sticker you requested.\n \"\"\"\n data = await self.http.get_sticker(sticker_id)\n cls, _ = _sticker_factory(data['type'])\n # The type checker is not smart enough to figure out the constructor is correct\n return cls(state=self._connection, data=data) # type: ignore\n\n async def fetch_skus(self) -> List[SKU]:\n \"\"\"|coro|\n\n Retrieves the bot's available SKUs.\n\n .. versionadded:: 2.4\n\n Raises\n -------\n MissingApplicationID\n The application ID could not be found.\n HTTPException\n Retrieving the SKUs failed.\n\n Returns\n --------\n List[:class:`.SKU`]\n The bot's available SKUs.\n \"\"\"\n\n if self.application_id is None:\n raise MissingApplicationID\n\n data = await self.http.get_skus(self.application_id)\n return [SKU(state=self._connection, data=sku) for sku in data]\n\n async def fetch_entitlement(self, entitlement_id: int, /) -> Entitlement:\n \"\"\"|coro|\n\n Retrieves a :class:`.Entitlement` with the specified ID.\n\n .. versionadded:: 2.4\n\n Parameters\n -----------\n entitlement_id: :class:`int`\n The entitlement's ID to fetch from.\n\n Raises\n -------\n NotFound\n An entitlement with this ID does not exist.\n MissingApplicationID\n The application ID could not be found.\n HTTPException\n Fetching the entitlement failed.\n\n Returns\n --------\n :class:`.Entitlement`\n The entitlement you requested.\n \"\"\"\n\n if self.application_id is None:\n raise MissingApplicationID\n\n data = await self.http.get_entitlement(self.application_id, entitlement_id)\n return Entitlement(state=self._connection, data=data)\n\n async def entitlements(\n self,\n *,\n limit: Optional[int] = 100,\n before: Optional[SnowflakeTime] = None,\n after: Optional[SnowflakeTime] = None,\n skus: Optional[Sequence[Snowflake]] = None,\n user: Optional[Snowflake] = None,\n guild: Optional[Snowflake] = None,\n exclude_ended: bool = False,\n ) -> AsyncIterator[Entitlement]:\n \"\"\"Retrieves an :term:`asynchronous iterator` of the :class:`.Entitlement` that applications has.\n\n .. versionadded:: 2.4\n\n Examples\n ---------\n\n Usage ::\n\n async for entitlement in client.entitlements(limit=100):\n print(entitlement.user_id, entitlement.ends_at)\n\n Flattening into a list ::\n\n entitlements = [entitlement async for entitlement in client.entitlements(limit=100)]\n # entitlements is now a list of Entitlement...\n\n All parameters are optional.\n\n Parameters\n -----------\n limit: Optional[:class:`int`]\n The number of entitlements to retrieve. If ``None``, it retrieves every entitlement for this application.\n Note, however, that this would make it a slow operation. Defaults to ``100``.\n before: Optional[Union[:class:`~discord.abc.Snowflake`, :class:`datetime.datetime`]]\n Retrieve entitlements before this date or entitlement.\n If a datetime is provided, it is recommended to use a UTC aware datetime.\n If the datetime is naive, it is assumed to be local time.\n after: Optional[Union[:class:`~discord.abc.Snowflake`, :class:`datetime.datetime`]]\n Retrieve entitlements after this date or entitlement.\n If a datetime is provided, it is recommended to use a UTC aware datetime.\n If the datetime is naive, it is assumed to be local time.\n skus: Optional[Sequence[:class:`~discord.abc.Snowflake`]]\n A list of SKUs to filter by.\n user: Optional[:class:`~discord.abc.Snowflake`]\n The user to filter by.\n guild: Optional[:class:`~discord.abc.Snowflake`]\n The guild to filter by.\n exclude_ended: :class:`bool`\n Whether to exclude ended entitlements. Defaults to ``False``.\n\n Raises\n -------\n MissingApplicationID\n The application ID could not be found.\n HTTPException\n Fetching the entitlements failed.\n TypeError\n Both ``after`` and ``before`` were provided, as Discord does not\n support this type of pagination.\n\n Yields\n --------\n :class:`.Entitlement`\n The entitlement with the application.\n \"\"\"\n\n if self.application_id is None:\n raise MissingApplicationID\n\n if before is not None and after is not None:\n raise TypeError('entitlements pagination does not support both before and after')\n\n # This endpoint paginates in ascending order.\n endpoint = self.http.get_entitlements\n\n async def _before_strategy(retrieve: int, before: Optional[Snowflake], limit: Optional[int]):\n before_id = before.id if before else None\n data = await endpoint(\n self.application_id, # type: ignore # We already check for None above\n limit=retrieve,\n before=before_id,\n sku_ids=[sku.id for sku in skus] if skus else None,\n user_id=user.id if user else None,\n guild_id=guild.id if guild else None,\n exclude_ended=exclude_ended,\n )\n\n if data:\n if limit is not None:\n limit -= len(data)\n\n before = Object(id=int(data[0]['id']))\n\n return data, before, limit\n\n async def _after_strategy(retrieve: int, after: Optional[Snowflake], limit: Optional[int]):\n after_id = after.id if after else None\n data = await endpoint(\n self.application_id, # type: ignore # We already check for None above\n limit=retrieve,\n after=after_id,\n sku_ids=[sku.id for sku in skus] if skus else None,\n user_id=user.id if user else None,\n guild_id=guild.id if guild else None,\n exclude_ended=exclude_ended,\n )\n\n if data:\n if limit is not None:\n limit -= len(data)\n\n after = Object(id=int(data[-1]['id']))\n\n return data, after, limit\n\n if isinstance(before, datetime.datetime):\n before = Object(id=utils.time_snowflake(before, high=False))\n if isinstance(after, datetime.datetime):\n after = Object(id=utils.time_snowflake(after, high=True))\n\n if before:\n strategy, state = _before_strategy, before\n else:\n strategy, state = _after_strategy, after\n\n while True:\n retrieve = 100 if limit is None else min(limit, 100)\n if retrieve < 1:\n return\n\n data, state, limit = await strategy(retrieve, state, limit)\n\n # Terminate loop on next iteration; there's no data left after this\n if len(data) < 1000:\n limit = 0\n\n for e in data:\n yield Entitlement(self._connection, e)\n\n async def create_entitlement(\n self,\n sku: Snowflake,\n owner: Snowflake,\n owner_type: EntitlementOwnerType,\n ) -> None:\n \"\"\"|coro|\n\n Creates a test :class:`.Entitlement` for the application.\n\n .. versionadded:: 2.4\n\n Parameters\n -----------\n sku: :class:`~discord.abc.Snowflake`\n The SKU to create the entitlement for.\n owner: :class:`~discord.abc.Snowflake`\n The ID of the owner.\n owner_type: :class:`.EntitlementOwnerType`\n The type of the owner.\n\n Raises\n -------\n MissingApplicationID\n The application ID could not be found.\n NotFound\n The SKU or owner could not be found.\n HTTPException\n Creating the entitlement failed.\n \"\"\"\n\n if self.application_id is None:\n raise MissingApplicationID\n\n await self.http.create_entitlement(self.application_id, sku.id, owner.id, owner_type.value)\n\n async def fetch_premium_sticker_packs(self) -> List[StickerPack]:\n \"\"\"|coro|\n\n Retrieves all available premium sticker packs.\n\n .. versionadded:: 2.0\n\n Raises\n -------\n HTTPException\n Retrieving the sticker packs failed.\n\n Returns\n ---------\n List[:class:`.StickerPack`]\n All available premium sticker packs.\n \"\"\"\n data = await self.http.list_premium_sticker_packs()\n return [StickerPack(state=self._connection, data=pack) for pack in data['sticker_packs']]\n\n async def create_dm(self, user: Snowflake) -> DMChannel:\n \"\"\"|coro|\n\n Creates a :class:`.DMChannel` with this user.\n\n This should be rarely called, as this is done transparently for most\n people.\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n user: :class:`~discord.abc.Snowflake`\n The user to create a DM with.\n\n Returns\n -------\n :class:`.DMChannel`\n The channel that was created.\n \"\"\"\n state = self._connection\n found = state._get_private_channel_by_user(user.id)\n if found:\n return found\n\n data = await state.http.start_private_message(user.id)\n return state.add_dm_channel(data)\n\n def add_dynamic_items(self, *items: Type[DynamicItem[Item[Any]]]) -> None:\n r\"\"\"Registers :class:`~discord.ui.DynamicItem` classes for persistent listening.\n\n This method accepts *class types* rather than instances.\n\n .. versionadded:: 2.4\n\n Parameters\n -----------\n \\*items: Type[:class:`~discord.ui.DynamicItem`]\n The classes of dynamic items to add.\n\n Raises\n -------\n TypeError\n A class is not a subclass of :class:`~discord.ui.DynamicItem`.\n \"\"\"\n\n for item in items:\n if not issubclass(item, DynamicItem):\n raise TypeError(f'expected subclass of DynamicItem not {item.__name__}')\n\n self._connection.store_dynamic_items(*items)\n\n def remove_dynamic_items(self, *items: Type[DynamicItem[Item[Any]]]) -> None:\n r\"\"\"Removes :class:`~discord.ui.DynamicItem` classes from persistent listening.\n\n This method accepts *class types* rather than instances.\n\n .. versionadded:: 2.4\n\n Parameters\n -----------\n \\*items: Type[:class:`~discord.ui.DynamicItem`]\n The classes of dynamic items to remove.\n\n Raises\n -------\n TypeError\n A class is not a subclass of :class:`~discord.ui.DynamicItem`.\n \"\"\"\n\n for item in items:\n if not issubclass(item, DynamicItem):\n raise TypeError(f'expected subclass of DynamicItem not {item.__name__}')\n\n self._connection.remove_dynamic_items(*items)\n\n def add_view(self, view: View, *, message_id: Optional[int] = None) -> None:\n \"\"\"Registers a :class:`~discord.ui.View` for persistent listening.\n\n This method should be used for when a view is comprised of components\n that last longer than the lifecycle of the program.\n\n .. versionadded:: 2.0\n\n Parameters\n ------------\n view: :class:`discord.ui.View`\n The view to register for dispatching.\n message_id: Optional[:class:`int`]\n The message ID that the view is attached to. This is currently used to\n refresh the view's state during message update events. If not given\n then message update events are not propagated for the view.\n\n Raises\n -------\n TypeError\n A view was not passed.\n ValueError\n The view is not persistent or is already finished. A persistent view has no timeout\n and all their components have an explicitly provided custom_id.\n \"\"\"\n\n if not isinstance(view, View):\n raise TypeError(f'expected an instance of View not {view.__class__.__name__}')\n\n if not view.is_persistent():\n raise ValueError('View is not persistent. Items need to have a custom_id set and View must have no timeout')\n\n if view.is_finished():\n raise ValueError('View is already finished.')\n\n self._connection.store_view(view, message_id)\n\n @property\n def persistent_views(self) -> Sequence[View]:\n \"\"\"Sequence[:class:`.View`]: A sequence of persistent views added to the client.\n\n .. versionadded:: 2.0\n \"\"\"\n return self._connection.persistent_views\n" }, { "path": "discord/colour.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\nfrom __future__ import annotations\n\nimport colorsys\nimport random\nimport re\n\nfrom typing import TYPE_CHECKING, Optional, Tuple, Union\n\nif TYPE_CHECKING:\n from typing_extensions import Self\n\n__all__ = (\n 'Colour',\n 'Color',\n)\n\nRGB_REGEX = re.compile(r'rgb\\s*\\((?P[0-9.]+%?)\\s*,\\s*(?P[0-9.]+%?)\\s*,\\s*(?P[0-9.]+%?)\\s*\\)')\n\n\ndef parse_hex_number(argument: str) -> Colour:\n arg = ''.join(i * 2 for i in argument) if len(argument) == 3 else argument\n try:\n value = int(arg, base=16)\n if not (0 <= value <= 0xFFFFFF):\n raise ValueError('hex number out of range for 24-bit colour')\n except ValueError:\n raise ValueError('invalid hex digit given') from None\n else:\n return Color(value=value)\n\n\ndef parse_rgb_number(number: str) -> int:\n if number[-1] == '%':\n value = float(number[:-1])\n if not (0 <= value <= 100):\n raise ValueError('rgb percentage can only be between 0 to 100')\n return round(255 * (value / 100))\n\n value = int(number)\n if not (0 <= value <= 255):\n raise ValueError('rgb number can only be between 0 to 255')\n return value\n\n\ndef parse_rgb(argument: str, *, regex: re.Pattern[str] = RGB_REGEX) -> Colour:\n match = regex.match(argument)\n if match is None:\n raise ValueError('invalid rgb syntax found')\n\n red = parse_rgb_number(match.group('r'))\n green = parse_rgb_number(match.group('g'))\n blue = parse_rgb_number(match.group('b'))\n return Color.from_rgb(red, green, blue)\n\n\nclass Colour:\n \"\"\"Represents a Discord role colour. This class is similar\n to a (red, green, blue) :class:`tuple`.\n\n There is an alias for this called Color.\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two colours are equal.\n\n .. describe:: x != y\n\n Checks if two colours are not equal.\n\n .. describe:: hash(x)\n\n Return the colour's hash.\n\n .. describe:: str(x)\n\n Returns the hex format for the colour.\n\n .. describe:: int(x)\n\n Returns the raw colour value.\n\n .. note::\n\n The colour values in the classmethods are mostly provided as-is and can change between\n versions should the Discord client's representation of that colour also change.\n\n Attributes\n ------------\n value: :class:`int`\n The raw integer colour value.\n \"\"\"\n\n __slots__ = ('value',)\n\n def __init__(self, value: int):\n if not isinstance(value, int):\n raise TypeError(f'Expected int parameter, received {value.__class__.__name__} instead.')\n\n self.value: int = value\n\n def _get_byte(self, byte: int) -> int:\n return (self.value >> (8 * byte)) & 0xFF\n\n def __eq__(self, other: object) -> bool:\n return isinstance(other, Colour) and self.value == other.value\n\n def __ne__(self, other: object) -> bool:\n return not self.__eq__(other)\n\n def __str__(self) -> str:\n return f'#{self.value:0>6x}'\n\n def __int__(self) -> int:\n return self.value\n\n def __repr__(self) -> str:\n return f''\n\n def __hash__(self) -> int:\n return hash(self.value)\n\n @property\n def r(self) -> int:\n \"\"\":class:`int`: Returns the red component of the colour.\"\"\"\n return self._get_byte(2)\n\n @property\n def g(self) -> int:\n \"\"\":class:`int`: Returns the green component of the colour.\"\"\"\n return self._get_byte(1)\n\n @property\n def b(self) -> int:\n \"\"\":class:`int`: Returns the blue component of the colour.\"\"\"\n return self._get_byte(0)\n\n def to_rgb(self) -> Tuple[int, int, int]:\n \"\"\"Tuple[:class:`int`, :class:`int`, :class:`int`]: Returns an (r, g, b) tuple representing the colour.\"\"\"\n return (self.r, self.g, self.b)\n\n @classmethod\n def from_rgb(cls, r: int, g: int, b: int) -> Self:\n \"\"\"Constructs a :class:`Colour` from an RGB tuple.\"\"\"\n return cls((r << 16) + (g << 8) + b)\n\n @classmethod\n def from_hsv(cls, h: float, s: float, v: float) -> Self:\n \"\"\"Constructs a :class:`Colour` from an HSV tuple.\"\"\"\n rgb = colorsys.hsv_to_rgb(h, s, v)\n return cls.from_rgb(*(int(x * 255) for x in rgb))\n\n @classmethod\n def from_str(cls, value: str) -> Colour:\n \"\"\"Constructs a :class:`Colour` from a string.\n\n The following formats are accepted:\n\n - ``0x``\n - ``#``\n - ``0x#``\n - ``rgb(, , )``\n\n Like CSS, ```` can be either 0-255 or 0-100% and ```` can be\n either a 6 digit hex number or a 3 digit hex shortcut (e.g. #FFF).\n\n .. versionadded:: 2.0\n\n Raises\n -------\n ValueError\n The string could not be converted into a colour.\n \"\"\"\n\n if not value:\n raise ValueError('unknown colour format given')\n\n if value[0] == '#':\n return parse_hex_number(value[1:])\n\n if value[0:2] == '0x':\n rest = value[2:]\n # Legacy backwards compatible syntax\n if rest.startswith('#'):\n return parse_hex_number(rest[1:])\n return parse_hex_number(rest)\n\n arg = value.lower()\n if arg[0:3] == 'rgb':\n return parse_rgb(arg)\n\n raise ValueError('unknown colour format given')\n\n @classmethod\n def default(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0``.\n\n .. colour:: #000000\n \"\"\"\n return cls(0)\n\n @classmethod\n def random(cls, *, seed: Optional[Union[int, str, float, bytes, bytearray]] = None) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a random hue.\n\n .. note::\n\n The random algorithm works by choosing a colour with a random hue but\n with maxed out saturation and value.\n\n .. versionadded:: 1.6\n\n Parameters\n ------------\n seed: Optional[Union[:class:`int`, :class:`str`, :class:`float`, :class:`bytes`, :class:`bytearray`]]\n The seed to initialize the RNG with. If ``None`` is passed the default RNG is used.\n\n .. versionadded:: 1.7\n \"\"\"\n rand = random if seed is None else random.Random(seed)\n return cls.from_hsv(rand.random(), 1, 1)\n\n @classmethod\n def teal(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x1ABC9C``.\n\n .. colour:: #1ABC9C\n \"\"\"\n return cls(0x1ABC9C)\n\n @classmethod\n def dark_teal(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x11806A``.\n\n .. colour:: #11806A\n \"\"\"\n return cls(0x11806A)\n\n @classmethod\n def brand_green(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x57F287``.\n\n .. colour:: #57F287\n\n\n .. versionadded:: 2.0\n \"\"\"\n return cls(0x57F287)\n\n @classmethod\n def green(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x2ECC71``.\n\n .. colour:: #2ECC71\n \"\"\"\n return cls(0x2ECC71)\n\n @classmethod\n def dark_green(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x1F8B4C``.\n\n .. colour:: #1F8B4C\n \"\"\"\n return cls(0x1F8B4C)\n\n @classmethod\n def blue(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x3498DB``.\n\n .. colour:: #3498DB\n \"\"\"\n return cls(0x3498DB)\n\n @classmethod\n def dark_blue(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x206694``.\n\n .. colour:: #206694\n \"\"\"\n return cls(0x206694)\n\n @classmethod\n def purple(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x9B59B6``.\n\n .. colour:: #9B59B6\n \"\"\"\n return cls(0x9B59B6)\n\n @classmethod\n def dark_purple(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x71368A``.\n\n .. colour:: #71368A\n \"\"\"\n return cls(0x71368A)\n\n @classmethod\n def magenta(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0xE91E63``.\n\n .. colour:: #E91E63\n \"\"\"\n return cls(0xE91E63)\n\n @classmethod\n def dark_magenta(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0xAD1457``.\n\n .. colour:: #AD1457\n \"\"\"\n return cls(0xAD1457)\n\n @classmethod\n def gold(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0xF1C40F``.\n\n .. colour:: #F1C40F\n \"\"\"\n return cls(0xF1C40F)\n\n @classmethod\n def dark_gold(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0xC27C0E``.\n\n .. colour:: #C27C0E\n \"\"\"\n return cls(0xC27C0E)\n\n @classmethod\n def orange(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0xE67E22``.\n\n .. colour:: #E67E22\n \"\"\"\n return cls(0xE67E22)\n\n @classmethod\n def dark_orange(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0xA84300``.\n\n .. colour:: #A84300\n \"\"\"\n return cls(0xA84300)\n\n @classmethod\n def brand_red(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0xED4245``.\n\n .. colour:: #ED4245\n\n .. versionadded:: 2.0\n \"\"\"\n return cls(0xED4245)\n\n @classmethod\n def red(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0xE74C3C``.\n\n .. colour:: #E74C3C\n \"\"\"\n return cls(0xE74C3C)\n\n @classmethod\n def dark_red(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x992D22``.\n\n .. colour:: #992D22\n \"\"\"\n return cls(0x992D22)\n\n @classmethod\n def lighter_grey(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x95A5A6``.\n\n .. colour:: #95A5A6\n \"\"\"\n return cls(0x95A5A6)\n\n lighter_gray = lighter_grey\n\n @classmethod\n def dark_grey(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x607d8b``.\n\n .. colour:: #607d8b\n \"\"\"\n return cls(0x607D8B)\n\n dark_gray = dark_grey\n\n @classmethod\n def light_grey(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x979C9F``.\n\n .. colour:: #979C9F\n \"\"\"\n return cls(0x979C9F)\n\n light_gray = light_grey\n\n @classmethod\n def darker_grey(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x546E7A``.\n\n .. colour:: #546E7A\n \"\"\"\n return cls(0x546E7A)\n\n darker_gray = darker_grey\n\n @classmethod\n def og_blurple(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x7289DA``.\n\n .. colour:: #7289DA\n \"\"\"\n return cls(0x7289DA)\n\n @classmethod\n def blurple(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x5865F2``.\n\n .. colour:: #5865F2\n \"\"\"\n return cls(0x5865F2)\n\n @classmethod\n def greyple(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x99AAB5``.\n\n .. colour:: #99AAB5\n \"\"\"\n return cls(0x99AAB5)\n\n @classmethod\n def dark_theme(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x313338``.\n\n This will appear transparent on Discord's dark theme.\n\n .. colour:: #313338\n\n .. versionadded:: 1.5\n\n .. versionchanged:: 2.2\n Updated colour from previous ``0x36393F`` to reflect discord theme changes.\n \"\"\"\n return cls(0x313338)\n\n @classmethod\n def fuchsia(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0xEB459E``.\n\n .. colour:: #EB459E\n\n .. versionadded:: 2.0\n \"\"\"\n return cls(0xEB459E)\n\n @classmethod\n def yellow(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0xFEE75C``.\n\n .. colour:: #FEE75C\n\n .. versionadded:: 2.0\n \"\"\"\n return cls(0xFEE75C)\n\n @classmethod\n def dark_embed(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0x2B2D31``.\n\n .. colour:: #2B2D31\n\n .. versionadded:: 2.2\n \"\"\"\n return cls(0x2B2D31)\n\n @classmethod\n def light_embed(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0xEEEFF1``.\n\n .. colour:: #EEEFF1\n\n .. versionadded:: 2.2\n \"\"\"\n return cls(0xEEEFF1)\n\n @classmethod\n def pink(cls) -> Self:\n \"\"\"A factory method that returns a :class:`Colour` with a value of ``0xEB459F``.\n\n .. colour:: #EB459F\n\n .. versionadded:: 2.3\n \"\"\"\n return cls(0xEB459F)\n\n\nColor = Colour\n" }, { "path": "discord/components.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import ClassVar, List, Literal, Optional, TYPE_CHECKING, Tuple, Union, overload\nfrom .enums import try_enum, ComponentType, ButtonStyle, TextStyle, ChannelType, SelectDefaultValueType\nfrom .utils import get_slots, MISSING\nfrom .partial_emoji import PartialEmoji, _EmojiTag\n\nif TYPE_CHECKING:\n from typing_extensions import Self\n\n from .types.components import (\n Component as ComponentPayload,\n ButtonComponent as ButtonComponentPayload,\n SelectMenu as SelectMenuPayload,\n SelectOption as SelectOptionPayload,\n ActionRow as ActionRowPayload,\n TextInput as TextInputPayload,\n ActionRowChildComponent as ActionRowChildComponentPayload,\n SelectDefaultValues as SelectDefaultValuesPayload,\n )\n from .emoji import Emoji\n from .abc import Snowflake\n\n ActionRowChildComponentType = Union['Button', 'SelectMenu', 'TextInput']\n\n\n__all__ = (\n 'Component',\n 'ActionRow',\n 'Button',\n 'SelectMenu',\n 'SelectOption',\n 'TextInput',\n 'SelectDefaultValue',\n)\n\n\nclass Component:\n \"\"\"Represents a Discord Bot UI Kit Component.\n\n Currently, the only components supported by Discord are:\n\n - :class:`ActionRow`\n - :class:`Button`\n - :class:`SelectMenu`\n - :class:`TextInput`\n\n This class is abstract and cannot be instantiated.\n\n .. versionadded:: 2.0\n \"\"\"\n\n __slots__: Tuple[str, ...] = ()\n\n __repr_info__: ClassVar[Tuple[str, ...]]\n\n def __repr__(self) -> str:\n attrs = ' '.join(f'{key}={getattr(self, key)!r}' for key in self.__repr_info__)\n return f'<{self.__class__.__name__} {attrs}>'\n\n @property\n def type(self) -> ComponentType:\n \"\"\":class:`ComponentType`: The type of component.\"\"\"\n raise NotImplementedError\n\n @classmethod\n def _raw_construct(cls, **kwargs) -> Self:\n self = cls.__new__(cls)\n for slot in get_slots(cls):\n try:\n value = kwargs[slot]\n except KeyError:\n pass\n else:\n setattr(self, slot, value)\n return self\n\n def to_dict(self) -> ComponentPayload:\n raise NotImplementedError\n\n\nclass ActionRow(Component):\n \"\"\"Represents a Discord Bot UI Kit Action Row.\n\n This is a component that holds up to 5 children components in a row.\n\n This inherits from :class:`Component`.\n\n .. versionadded:: 2.0\n\n Attributes\n ------------\n children: List[Union[:class:`Button`, :class:`SelectMenu`, :class:`TextInput`]]\n The children components that this holds, if any.\n \"\"\"\n\n __slots__: Tuple[str, ...] = ('children',)\n\n __repr_info__: ClassVar[Tuple[str, ...]] = __slots__\n\n def __init__(self, data: ActionRowPayload, /) -> None:\n self.children: List[ActionRowChildComponentType] = []\n\n for component_data in data.get('components', []):\n component = _component_factory(component_data)\n\n if component is not None:\n self.children.append(component)\n\n @property\n def type(self) -> Literal[ComponentType.action_row]:\n \"\"\":class:`ComponentType`: The type of component.\"\"\"\n return ComponentType.action_row\n\n def to_dict(self) -> ActionRowPayload:\n return {\n 'type': self.type.value,\n 'components': [child.to_dict() for child in self.children],\n }\n\n\nclass Button(Component):\n \"\"\"Represents a button from the Discord Bot UI Kit.\n\n This inherits from :class:`Component`.\n\n .. note::\n\n The user constructible and usable type to create a button is :class:`discord.ui.Button`\n not this one.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n style: :class:`.ButtonStyle`\n The style of the button.\n custom_id: Optional[:class:`str`]\n The ID of the button that gets received during an interaction.\n If this button is for a URL, it does not have a custom ID.\n url: Optional[:class:`str`]\n The URL this button sends you to.\n disabled: :class:`bool`\n Whether the button is disabled or not.\n label: Optional[:class:`str`]\n The label of the button, if any.\n emoji: Optional[:class:`PartialEmoji`]\n The emoji of the button, if available.\n sku_id: Optional[:class:`int`]\n The SKU ID this button sends you to, if available.\n\n .. versionadded:: 2.4\n \"\"\"\n\n __slots__: Tuple[str, ...] = (\n 'style',\n 'custom_id',\n 'url',\n 'disabled',\n 'label',\n 'emoji',\n 'sku_id',\n )\n\n __repr_info__: ClassVar[Tuple[str, ...]] = __slots__\n\n def __init__(self, data: ButtonComponentPayload, /) -> None:\n self.style: ButtonStyle = try_enum(ButtonStyle, data['style'])\n self.custom_id: Optional[str] = data.get('custom_id')\n self.url: Optional[str] = data.get('url')\n self.disabled: bool = data.get('disabled', False)\n self.label: Optional[str] = data.get('label')\n self.emoji: Optional[PartialEmoji]\n try:\n self.emoji = PartialEmoji.from_dict(data['emoji'])\n except KeyError:\n self.emoji = None\n\n try:\n self.sku_id: Optional[int] = int(data['sku_id'])\n except KeyError:\n self.sku_id = None\n\n @property\n def type(self) -> Literal[ComponentType.button]:\n \"\"\":class:`ComponentType`: The type of component.\"\"\"\n return ComponentType.button\n\n def to_dict(self) -> ButtonComponentPayload:\n payload: ButtonComponentPayload = {\n 'type': 2,\n 'style': self.style.value,\n 'disabled': self.disabled,\n }\n\n if self.sku_id:\n payload['sku_id'] = str(self.sku_id)\n\n if self.label:\n payload['label'] = self.label\n\n if self.custom_id:\n payload['custom_id'] = self.custom_id\n\n if self.url:\n payload['url'] = self.url\n\n if self.emoji:\n payload['emoji'] = self.emoji.to_dict()\n\n return payload\n\n\nclass SelectMenu(Component):\n \"\"\"Represents a select menu from the Discord Bot UI Kit.\n\n A select menu is functionally the same as a dropdown, however\n on mobile it renders a bit differently.\n\n .. note::\n\n The user constructible and usable type to create a select menu is\n :class:`discord.ui.Select` not this one.\n\n .. versionadded:: 2.0\n\n Attributes\n ------------\n type: :class:`ComponentType`\n The type of component.\n custom_id: Optional[:class:`str`]\n The ID of the select menu that gets received during an interaction.\n placeholder: Optional[:class:`str`]\n The placeholder text that is shown if nothing is selected, if any.\n min_values: :class:`int`\n The minimum number of items that must be chosen for this select menu.\n Defaults to 1 and must be between 0 and 25.\n max_values: :class:`int`\n The maximum number of items that must be chosen for this select menu.\n Defaults to 1 and must be between 1 and 25.\n options: List[:class:`SelectOption`]\n A list of options that can be selected in this menu.\n disabled: :class:`bool`\n Whether the select is disabled or not.\n channel_types: List[:class:`.ChannelType`]\n A list of channel types that are allowed to be chosen in this select menu.\n \"\"\"\n\n __slots__: Tuple[str, ...] = (\n 'type',\n 'custom_id',\n 'placeholder',\n 'min_values',\n 'max_values',\n 'options',\n 'disabled',\n 'channel_types',\n 'default_values',\n )\n\n __repr_info__: ClassVar[Tuple[str, ...]] = __slots__\n\n def __init__(self, data: SelectMenuPayload, /) -> None:\n self.type: ComponentType = try_enum(ComponentType, data['type'])\n self.custom_id: str = data['custom_id']\n self.placeholder: Optional[str] = data.get('placeholder')\n self.min_values: int = data.get('min_values', 1)\n self.max_values: int = data.get('max_values', 1)\n self.options: List[SelectOption] = [SelectOption.from_dict(option) for option in data.get('options', [])]\n self.disabled: bool = data.get('disabled', False)\n self.channel_types: List[ChannelType] = [try_enum(ChannelType, t) for t in data.get('channel_types', [])]\n self.default_values: List[SelectDefaultValue] = [\n SelectDefaultValue.from_dict(d) for d in data.get('default_values', [])\n ]\n\n def to_dict(self) -> SelectMenuPayload:\n payload: SelectMenuPayload = {\n 'type': self.type.value, # type: ignore # we know this is a select menu.\n 'custom_id': self.custom_id,\n 'min_values': self.min_values,\n 'max_values': self.max_values,\n 'disabled': self.disabled,\n }\n if self.placeholder:\n payload['placeholder'] = self.placeholder\n if self.options:\n payload['options'] = [op.to_dict() for op in self.options]\n if self.channel_types:\n payload['channel_types'] = [t.value for t in self.channel_types]\n if self.default_values:\n payload[\"default_values\"] = [v.to_dict() for v in self.default_values]\n\n return payload\n\n\nclass SelectOption:\n \"\"\"Represents a select menu's option.\n\n These can be created by users.\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n label: :class:`str`\n The label of the option. This is displayed to users.\n Can only be up to 100 characters.\n value: :class:`str`\n The value of the option. This is not displayed to users.\n If not provided when constructed then it defaults to the label.\n Can only be up to 100 characters.\n description: Optional[:class:`str`]\n An additional description of the option, if any.\n Can only be up to 100 characters.\n emoji: Optional[Union[:class:`str`, :class:`Emoji`, :class:`PartialEmoji`]]\n The emoji of the option, if available.\n default: :class:`bool`\n Whether this option is selected by default.\n\n Attributes\n -----------\n label: :class:`str`\n The label of the option. This is displayed to users.\n value: :class:`str`\n The value of the option. This is not displayed to users.\n If not provided when constructed then it defaults to the\n label.\n description: Optional[:class:`str`]\n An additional description of the option, if any.\n default: :class:`bool`\n Whether this option is selected by default.\n \"\"\"\n\n __slots__: Tuple[str, ...] = (\n 'label',\n 'value',\n 'description',\n '_emoji',\n 'default',\n )\n\n def __init__(\n self,\n *,\n label: str,\n value: str = MISSING,\n description: Optional[str] = None,\n emoji: Optional[Union[str, Emoji, PartialEmoji]] = None,\n default: bool = False,\n ) -> None:\n self.label: str = label\n self.value: str = label if value is MISSING else value\n self.description: Optional[str] = description\n\n self.emoji = emoji\n self.default: bool = default\n\n def __repr__(self) -> str:\n return (\n f''\n )\n\n def __str__(self) -> str:\n if self.emoji:\n base = f'{self.emoji} {self.label}'\n else:\n base = self.label\n\n if self.description:\n return f'{base}\\n{self.description}'\n return base\n\n @property\n def emoji(self) -> Optional[PartialEmoji]:\n \"\"\"Optional[:class:`.PartialEmoji`]: The emoji of the option, if available.\"\"\"\n return self._emoji\n\n @emoji.setter\n def emoji(self, value: Optional[Union[str, Emoji, PartialEmoji]]) -> None:\n if value is not None:\n if isinstance(value, str):\n self._emoji = PartialEmoji.from_str(value)\n elif isinstance(value, _EmojiTag):\n self._emoji = value._to_partial()\n else:\n raise TypeError(f'expected str, Emoji, or PartialEmoji, received {value.__class__.__name__} instead')\n else:\n self._emoji = None\n\n @classmethod\n def from_dict(cls, data: SelectOptionPayload) -> SelectOption:\n try:\n emoji = PartialEmoji.from_dict(data['emoji'])\n except KeyError:\n emoji = None\n\n return cls(\n label=data['label'],\n value=data['value'],\n description=data.get('description'),\n emoji=emoji,\n default=data.get('default', False),\n )\n\n def to_dict(self) -> SelectOptionPayload:\n payload: SelectOptionPayload = {\n 'label': self.label,\n 'value': self.value,\n 'default': self.default,\n }\n\n if self.emoji:\n payload['emoji'] = self.emoji.to_dict()\n\n if self.description:\n payload['description'] = self.description\n\n return payload\n\n\nclass TextInput(Component):\n \"\"\"Represents a text input from the Discord Bot UI Kit.\n\n .. note::\n The user constructible and usable type to create a text input is\n :class:`discord.ui.TextInput` not this one.\n\n .. versionadded:: 2.0\n\n Attributes\n ------------\n custom_id: Optional[:class:`str`]\n The ID of the text input that gets received during an interaction.\n label: :class:`str`\n The label to display above the text input.\n style: :class:`TextStyle`\n The style of the text input.\n placeholder: Optional[:class:`str`]\n The placeholder text to display when the text input is empty.\n value: Optional[:class:`str`]\n The default value of the text input.\n required: :class:`bool`\n Whether the text input is required.\n min_length: Optional[:class:`int`]\n The minimum length of the text input.\n max_length: Optional[:class:`int`]\n The maximum length of the text input.\n \"\"\"\n\n __slots__: Tuple[str, ...] = (\n 'style',\n 'label',\n 'custom_id',\n 'placeholder',\n 'value',\n 'required',\n 'min_length',\n 'max_length',\n )\n\n __repr_info__: ClassVar[Tuple[str, ...]] = __slots__\n\n def __init__(self, data: TextInputPayload, /) -> None:\n self.style: TextStyle = try_enum(TextStyle, data['style'])\n self.label: str = data['label']\n self.custom_id: str = data['custom_id']\n self.placeholder: Optional[str] = data.get('placeholder')\n self.value: Optional[str] = data.get('value')\n self.required: bool = data.get('required', True)\n self.min_length: Optional[int] = data.get('min_length')\n self.max_length: Optional[int] = data.get('max_length')\n\n @property\n def type(self) -> Literal[ComponentType.text_input]:\n \"\"\":class:`ComponentType`: The type of component.\"\"\"\n return ComponentType.text_input\n\n def to_dict(self) -> TextInputPayload:\n payload: TextInputPayload = {\n 'type': self.type.value,\n 'style': self.style.value,\n 'label': self.label,\n 'custom_id': self.custom_id,\n 'required': self.required,\n }\n\n if self.placeholder:\n payload['placeholder'] = self.placeholder\n\n if self.value:\n payload['value'] = self.value\n\n if self.min_length:\n payload['min_length'] = self.min_length\n\n if self.max_length:\n payload['max_length'] = self.max_length\n\n return payload\n\n @property\n def default(self) -> Optional[str]:\n \"\"\"Optional[:class:`str`]: The default value of the text input.\n\n This is an alias to :attr:`value`.\n \"\"\"\n return self.value\n\n\nclass SelectDefaultValue:\n \"\"\"Represents a select menu's default value.\n\n These can be created by users.\n\n .. versionadded:: 2.4\n\n Parameters\n -----------\n id: :class:`int`\n The id of a role, user, or channel.\n type: :class:`SelectDefaultValueType`\n The type of value that ``id`` represents.\n \"\"\"\n\n def __init__(\n self,\n *,\n id: int,\n type: SelectDefaultValueType,\n ) -> None:\n self.id: int = id\n self._type: SelectDefaultValueType = type\n\n @property\n def type(self) -> SelectDefaultValueType:\n \"\"\":class:`SelectDefaultValueType`: The type of value that ``id`` represents.\"\"\"\n return self._type\n\n @type.setter\n def type(self, value: SelectDefaultValueType) -> None:\n if not isinstance(value, SelectDefaultValueType):\n raise TypeError(f'expected SelectDefaultValueType, received {value.__class__.__name__} instead')\n\n self._type = value\n\n def __repr__(self) -> str:\n return f''\n\n @classmethod\n def from_dict(cls, data: SelectDefaultValuesPayload) -> SelectDefaultValue:\n return cls(\n id=data['id'],\n type=try_enum(SelectDefaultValueType, data['type']),\n )\n\n def to_dict(self) -> SelectDefaultValuesPayload:\n return {\n 'id': self.id,\n 'type': self._type.value,\n }\n\n @classmethod\n def from_channel(cls, channel: Snowflake, /) -> Self:\n \"\"\"Creates a :class:`SelectDefaultValue` with the type set to :attr:`~SelectDefaultValueType.channel`.\n\n Parameters\n -----------\n channel: :class:`~discord.abc.Snowflake`\n The channel to create the default value for.\n\n Returns\n --------\n :class:`SelectDefaultValue`\n The default value created with the channel.\n \"\"\"\n return cls(\n id=channel.id,\n type=SelectDefaultValueType.channel,\n )\n\n @classmethod\n def from_role(cls, role: Snowflake, /) -> Self:\n \"\"\"Creates a :class:`SelectDefaultValue` with the type set to :attr:`~SelectDefaultValueType.role`.\n\n Parameters\n -----------\n role: :class:`~discord.abc.Snowflake`\n The role to create the default value for.\n\n Returns\n --------\n :class:`SelectDefaultValue`\n The default value created with the role.\n \"\"\"\n return cls(\n id=role.id,\n type=SelectDefaultValueType.role,\n )\n\n @classmethod\n def from_user(cls, user: Snowflake, /) -> Self:\n \"\"\"Creates a :class:`SelectDefaultValue` with the type set to :attr:`~SelectDefaultValueType.user`.\n\n Parameters\n -----------\n user: :class:`~discord.abc.Snowflake`\n The user to create the default value for.\n\n Returns\n --------\n :class:`SelectDefaultValue`\n The default value created with the user.\n \"\"\"\n return cls(\n id=user.id,\n type=SelectDefaultValueType.user,\n )\n\n\n@overload\ndef _component_factory(data: ActionRowChildComponentPayload) -> Optional[ActionRowChildComponentType]:\n ...\n\n\n@overload\ndef _component_factory(data: ComponentPayload) -> Optional[Union[ActionRow, ActionRowChildComponentType]]:\n ...\n\n\ndef _component_factory(data: ComponentPayload) -> Optional[Union[ActionRow, ActionRowChildComponentType]]:\n if data['type'] == 1:\n return ActionRow(data)\n elif data['type'] == 2:\n return Button(data)\n elif data['type'] == 4:\n return TextInput(data)\n elif data['type'] in (3, 5, 6, 7, 8):\n return SelectMenu(data)\n" }, { "path": "discord/context_managers.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nfrom typing import TYPE_CHECKING, Generator, Optional, Type, TypeVar\n\nif TYPE_CHECKING:\n from .abc import Messageable, MessageableChannel\n\n from types import TracebackType\n\n BE = TypeVar('BE', bound=BaseException)\n\n# fmt: off\n__all__ = (\n 'Typing',\n)\n# fmt: on\n\n\ndef _typing_done_callback(fut: asyncio.Future) -> None:\n # just retrieve any exception and call it a day\n try:\n fut.exception()\n except (asyncio.CancelledError, Exception):\n pass\n\n\nclass Typing:\n def __init__(self, messageable: Messageable) -> None:\n self.loop: asyncio.AbstractEventLoop = messageable._state.loop\n self.messageable: Messageable = messageable\n self.channel: Optional[MessageableChannel] = None\n\n async def _get_channel(self) -> MessageableChannel:\n if self.channel:\n return self.channel\n\n self.channel = channel = await self.messageable._get_channel()\n return channel\n\n async def wrapped_typer(self) -> None:\n channel = await self._get_channel()\n await channel._state.http.send_typing(channel.id)\n\n def __await__(self) -> Generator[None, None, None]:\n return self.wrapped_typer().__await__()\n\n async def do_typing(self) -> None:\n channel = await self._get_channel()\n typing = channel._state.http.send_typing\n\n while True:\n await asyncio.sleep(5)\n await typing(channel.id)\n\n async def __aenter__(self) -> None:\n channel = await self._get_channel()\n await channel._state.http.send_typing(channel.id)\n self.task: asyncio.Task[None] = self.loop.create_task(self.do_typing())\n self.task.add_done_callback(_typing_done_callback)\n\n async def __aexit__(\n self,\n exc_type: Optional[Type[BE]],\n exc: Optional[BE],\n traceback: Optional[TracebackType],\n ) -> None:\n self.task.cancel()\n" }, { "path": "discord/embeds.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport datetime\nfrom typing import Any, Dict, List, Mapping, Optional, Protocol, TYPE_CHECKING, TypeVar, Union\n\nfrom . import utils\nfrom .colour import Colour\n\n# fmt: off\n__all__ = (\n 'Embed',\n)\n# fmt: on\n\n\nclass EmbedProxy:\n def __init__(self, layer: Dict[str, Any]):\n self.__dict__.update(layer)\n\n def __len__(self) -> int:\n return len(self.__dict__)\n\n def __repr__(self) -> str:\n inner = ', '.join((f'{k}={v!r}' for k, v in self.__dict__.items() if not k.startswith('_')))\n return f'EmbedProxy({inner})'\n\n def __getattr__(self, attr: str) -> None:\n return None\n\n def __eq__(self, other: object) -> bool:\n return isinstance(other, EmbedProxy) and self.__dict__ == other.__dict__\n\n\nif TYPE_CHECKING:\n from typing_extensions import Self\n\n from .types.embed import Embed as EmbedData, EmbedType\n\n T = TypeVar('T')\n\n class _EmbedFooterProxy(Protocol):\n text: Optional[str]\n icon_url: Optional[str]\n\n class _EmbedFieldProxy(Protocol):\n name: Optional[str]\n value: Optional[str]\n inline: bool\n\n class _EmbedMediaProxy(Protocol):\n url: Optional[str]\n proxy_url: Optional[str]\n height: Optional[int]\n width: Optional[int]\n\n class _EmbedVideoProxy(Protocol):\n url: Optional[str]\n height: Optional[int]\n width: Optional[int]\n\n class _EmbedProviderProxy(Protocol):\n name: Optional[str]\n url: Optional[str]\n\n class _EmbedAuthorProxy(Protocol):\n name: Optional[str]\n url: Optional[str]\n icon_url: Optional[str]\n proxy_icon_url: Optional[str]\n\n\nclass Embed:\n \"\"\"Represents a Discord embed.\n\n .. container:: operations\n\n .. describe:: len(x)\n\n Returns the total size of the embed.\n Useful for checking if it's within the 6000 character limit.\n\n .. describe:: bool(b)\n\n Returns whether the embed has any data set.\n\n .. versionadded:: 2.0\n\n .. describe:: x == y\n\n Checks if two embeds are equal.\n\n .. versionadded:: 2.0\n\n For ease of use, all parameters that expect a :class:`str` are implicitly\n casted to :class:`str` for you.\n\n .. versionchanged:: 2.0\n ``Embed.Empty`` has been removed in favour of ``None``.\n\n Attributes\n -----------\n title: Optional[:class:`str`]\n The title of the embed.\n This can be set during initialisation.\n Can only be up to 256 characters.\n type: :class:`str`\n The type of embed. Usually \"rich\".\n This can be set during initialisation.\n Possible strings for embed types can be found on discord's\n :ddocs:`api docs `\n description: Optional[:class:`str`]\n The description of the embed.\n This can be set during initialisation.\n Can only be up to 4096 characters.\n url: Optional[:class:`str`]\n The URL of the embed.\n This can be set during initialisation.\n timestamp: Optional[:class:`datetime.datetime`]\n The timestamp of the embed content. This is an aware datetime.\n If a naive datetime is passed, it is converted to an aware\n datetime with the local timezone.\n colour: Optional[Union[:class:`Colour`, :class:`int`]]\n The colour code of the embed. Aliased to ``color`` as well.\n This can be set during initialisation.\n \"\"\"\n\n __slots__ = (\n 'title',\n 'url',\n 'type',\n '_timestamp',\n '_colour',\n '_footer',\n '_image',\n '_thumbnail',\n '_video',\n '_provider',\n '_author',\n '_fields',\n 'description',\n )\n\n def __init__(\n self,\n *,\n colour: Optional[Union[int, Colour]] = None,\n color: Optional[Union[int, Colour]] = None,\n title: Optional[Any] = None,\n type: EmbedType = 'rich',\n url: Optional[Any] = None,\n description: Optional[Any] = None,\n timestamp: Optional[datetime.datetime] = None,\n ):\n\n self.colour = colour if colour is not None else color\n self.title: Optional[str] = title\n self.type: EmbedType = type\n self.url: Optional[str] = url\n self.description: Optional[str] = description\n\n if self.title is not None:\n self.title = str(self.title)\n\n if self.description is not None:\n self.description = str(self.description)\n\n if self.url is not None:\n self.url = str(self.url)\n\n if timestamp is not None:\n self.timestamp = timestamp\n\n @classmethod\n def from_dict(cls, data: Mapping[str, Any]) -> Self:\n \"\"\"Converts a :class:`dict` to a :class:`Embed` provided it is in the\n format that Discord expects it to be in.\n\n You can find out about this format in the :ddocs:`official Discord documentation `.\n\n Parameters\n -----------\n data: :class:`dict`\n The dictionary to convert into an embed.\n \"\"\"\n # we are bypassing __init__ here since it doesn't apply here\n self = cls.__new__(cls)\n\n # fill in the basic fields\n\n self.title = data.get('title', None)\n self.type = data.get('type', None)\n self.description = data.get('description', None)\n self.url = data.get('url', None)\n\n if self.title is not None:\n self.title = str(self.title)\n\n if self.description is not None:\n self.description = str(self.description)\n\n if self.url is not None:\n self.url = str(self.url)\n\n # try to fill in the more rich fields\n\n try:\n self._colour = Colour(value=data['color'])\n except KeyError:\n pass\n\n try:\n self._timestamp = utils.parse_time(data['timestamp'])\n except KeyError:\n pass\n\n for attr in ('thumbnail', 'video', 'provider', 'author', 'fields', 'image', 'footer'):\n try:\n value = data[attr]\n except KeyError:\n continue\n else:\n setattr(self, '_' + attr, value)\n\n return self\n\n def copy(self) -> Self:\n \"\"\"Returns a shallow copy of the embed.\"\"\"\n return self.__class__.from_dict(self.to_dict())\n\n def __len__(self) -> int:\n total = len(self.title or '') + len(self.description or '')\n for field in getattr(self, '_fields', []):\n total += len(field['name']) + len(field['value'])\n\n try:\n footer_text = self._footer['text']\n except (AttributeError, KeyError):\n pass\n else:\n total += len(footer_text)\n\n try:\n author = self._author\n except AttributeError:\n pass\n else:\n total += len(author['name'])\n\n return total\n\n def __bool__(self) -> bool:\n return any(\n (\n self.title,\n self.url,\n self.description,\n self.colour,\n self.fields,\n self.timestamp,\n self.author,\n self.thumbnail,\n self.footer,\n self.image,\n self.provider,\n self.video,\n )\n )\n\n def __eq__(self, other: Embed) -> bool:\n return isinstance(other, Embed) and (\n self.type == other.type\n and self.title == other.title\n and self.url == other.url\n and self.description == other.description\n and self.colour == other.colour\n and self.fields == other.fields\n and self.timestamp == other.timestamp\n and self.author == other.author\n and self.thumbnail == other.thumbnail\n and self.footer == other.footer\n and self.image == other.image\n and self.provider == other.provider\n and self.video == other.video\n )\n\n @property\n def colour(self) -> Optional[Colour]:\n return getattr(self, '_colour', None)\n\n @colour.setter\n def colour(self, value: Optional[Union[int, Colour]]) -> None:\n if value is None:\n self._colour = None\n elif isinstance(value, Colour):\n self._colour = value\n elif isinstance(value, int):\n self._colour = Colour(value=value)\n else:\n raise TypeError(f'Expected discord.Colour, int, or None but received {value.__class__.__name__} instead.')\n\n color = colour\n\n @property\n def timestamp(self) -> Optional[datetime.datetime]:\n return getattr(self, '_timestamp', None)\n\n @timestamp.setter\n def timestamp(self, value: Optional[datetime.datetime]) -> None:\n if isinstance(value, datetime.datetime):\n if value.tzinfo is None:\n value = value.astimezone()\n self._timestamp = value\n elif value is None:\n self._timestamp = None\n else:\n raise TypeError(f\"Expected datetime.datetime or None received {value.__class__.__name__} instead\")\n\n @property\n def footer(self) -> _EmbedFooterProxy:\n \"\"\"Returns an ``EmbedProxy`` denoting the footer contents.\n\n See :meth:`set_footer` for possible values you can access.\n\n If the attribute has no value then ``None`` is returned.\n \"\"\"\n # Lying to the type checker for better developer UX.\n return EmbedProxy(getattr(self, '_footer', {})) # type: ignore\n\n def set_footer(self, *, text: Optional[Any] = None, icon_url: Optional[Any] = None) -> Self:\n \"\"\"Sets the footer for the embed content.\n\n This function returns the class instance to allow for fluent-style\n chaining.\n\n Parameters\n -----------\n text: :class:`str`\n The footer text. Can only be up to 2048 characters.\n icon_url: :class:`str`\n The URL of the footer icon. Only HTTP(S) is supported.\n Inline attachment URLs are also supported, see :ref:`local_image`.\n \"\"\"\n\n self._footer = {}\n if text is not None:\n self._footer['text'] = str(text)\n\n if icon_url is not None:\n self._footer['icon_url'] = str(icon_url)\n\n return self\n\n def remove_footer(self) -> Self:\n \"\"\"Clears embed's footer information.\n\n This function returns the class instance to allow for fluent-style\n chaining.\n\n .. versionadded:: 2.0\n \"\"\"\n try:\n del self._footer\n except AttributeError:\n pass\n\n return self\n\n @property\n def image(self) -> _EmbedMediaProxy:\n \"\"\"Returns an ``EmbedProxy`` denoting the image contents.\n\n Possible attributes you can access are:\n\n - ``url``\n - ``proxy_url``\n - ``width``\n - ``height``\n\n If the attribute has no value then ``None`` is returned.\n \"\"\"\n # Lying to the type checker for better developer UX.\n return EmbedProxy(getattr(self, '_image', {})) # type: ignore\n\n def set_image(self, *, url: Optional[Any]) -> Self:\n \"\"\"Sets the image for the embed content.\n\n This function returns the class instance to allow for fluent-style\n chaining.\n\n Parameters\n -----------\n url: :class:`str`\n The source URL for the image. Only HTTP(S) is supported.\n Inline attachment URLs are also supported, see :ref:`local_image`.\n \"\"\"\n\n if url is None:\n try:\n del self._image\n except AttributeError:\n pass\n else:\n self._image = {\n 'url': str(url),\n }\n\n return self\n\n @property\n def thumbnail(self) -> _EmbedMediaProxy:\n \"\"\"Returns an ``EmbedProxy`` denoting the thumbnail contents.\n\n Possible attributes you can access are:\n\n - ``url``\n - ``proxy_url``\n - ``width``\n - ``height``\n\n If the attribute has no value then ``None`` is returned.\n \"\"\"\n # Lying to the type checker for better developer UX.\n return EmbedProxy(getattr(self, '_thumbnail', {})) # type: ignore\n\n def set_thumbnail(self, *, url: Optional[Any]) -> Self:\n \"\"\"Sets the thumbnail for the embed content.\n\n This function returns the class instance to allow for fluent-style\n chaining.\n\n .. versionchanged:: 1.4\n Passing ``None`` removes the thumbnail.\n\n Parameters\n -----------\n url: :class:`str`\n The source URL for the thumbnail. Only HTTP(S) is supported.\n Inline attachment URLs are also supported, see :ref:`local_image`.\n \"\"\"\n\n if url is None:\n try:\n del self._thumbnail\n except AttributeError:\n pass\n else:\n self._thumbnail = {\n 'url': str(url),\n }\n\n return self\n\n @property\n def video(self) -> _EmbedVideoProxy:\n \"\"\"Returns an ``EmbedProxy`` denoting the video contents.\n\n Possible attributes include:\n\n - ``url`` for the video URL.\n - ``height`` for the video height.\n - ``width`` for the video width.\n\n If the attribute has no value then ``None`` is returned.\n \"\"\"\n # Lying to the type checker for better developer UX.\n return EmbedProxy(getattr(self, '_video', {})) # type: ignore\n\n @property\n def provider(self) -> _EmbedProviderProxy:\n \"\"\"Returns an ``EmbedProxy`` denoting the provider contents.\n\n The only attributes that might be accessed are ``name`` and ``url``.\n\n If the attribute has no value then ``None`` is returned.\n \"\"\"\n # Lying to the type checker for better developer UX.\n return EmbedProxy(getattr(self, '_provider', {})) # type: ignore\n\n @property\n def author(self) -> _EmbedAuthorProxy:\n \"\"\"Returns an ``EmbedProxy`` denoting the author contents.\n\n See :meth:`set_author` for possible values you can access.\n\n If the attribute has no value then ``None`` is returned.\n \"\"\"\n # Lying to the type checker for better developer UX.\n return EmbedProxy(getattr(self, '_author', {})) # type: ignore\n\n def set_author(self, *, name: Any, url: Optional[Any] = None, icon_url: Optional[Any] = None) -> Self:\n \"\"\"Sets the author for the embed content.\n\n This function returns the class instance to allow for fluent-style\n chaining.\n\n Parameters\n -----------\n name: :class:`str`\n The name of the author. Can only be up to 256 characters.\n url: :class:`str`\n The URL for the author.\n icon_url: :class:`str`\n The URL of the author icon. Only HTTP(S) is supported.\n Inline attachment URLs are also supported, see :ref:`local_image`.\n \"\"\"\n\n self._author = {\n 'name': str(name),\n }\n\n if url is not None:\n self._author['url'] = str(url)\n\n if icon_url is not None:\n self._author['icon_url'] = str(icon_url)\n\n return self\n\n def remove_author(self) -> Self:\n \"\"\"Clears embed's author information.\n\n This function returns the class instance to allow for fluent-style\n chaining.\n\n .. versionadded:: 1.4\n \"\"\"\n try:\n del self._author\n except AttributeError:\n pass\n\n return self\n\n @property\n def fields(self) -> List[_EmbedFieldProxy]:\n \"\"\"List[``EmbedProxy``]: Returns a :class:`list` of ``EmbedProxy`` denoting the field contents.\n\n See :meth:`add_field` for possible values you can access.\n\n If the attribute has no value then ``None`` is returned.\n \"\"\"\n # Lying to the type checker for better developer UX.\n return [EmbedProxy(d) for d in getattr(self, '_fields', [])] # type: ignore\n\n def add_field(self, *, name: Any, value: Any, inline: bool = True) -> Self:\n \"\"\"Adds a field to the embed object.\n\n This function returns the class instance to allow for fluent-style\n chaining. Can only be up to 25 fields.\n\n Parameters\n -----------\n name: :class:`str`\n The name of the field. Can only be up to 256 characters.\n value: :class:`str`\n The value of the field. Can only be up to 1024 characters.\n inline: :class:`bool`\n Whether the field should be displayed inline.\n \"\"\"\n\n field = {\n 'inline': inline,\n 'name': str(name),\n 'value': str(value),\n }\n\n try:\n self._fields.append(field)\n except AttributeError:\n self._fields = [field]\n\n return self\n\n def insert_field_at(self, index: int, *, name: Any, value: Any, inline: bool = True) -> Self:\n \"\"\"Inserts a field before a specified index to the embed.\n\n This function returns the class instance to allow for fluent-style\n chaining. Can only be up to 25 fields.\n\n .. versionadded:: 1.2\n\n Parameters\n -----------\n index: :class:`int`\n The index of where to insert the field.\n name: :class:`str`\n The name of the field. Can only be up to 256 characters.\n value: :class:`str`\n The value of the field. Can only be up to 1024 characters.\n inline: :class:`bool`\n Whether the field should be displayed inline.\n \"\"\"\n\n field = {\n 'inline': inline,\n 'name': str(name),\n 'value': str(value),\n }\n\n try:\n self._fields.insert(index, field)\n except AttributeError:\n self._fields = [field]\n\n return self\n\n def clear_fields(self) -> Self:\n \"\"\"Removes all fields from this embed.\n\n This function returns the class instance to allow for fluent-style\n chaining.\n\n .. versionchanged:: 2.0\n This function now returns the class instance.\n \"\"\"\n try:\n self._fields.clear()\n except AttributeError:\n self._fields = []\n\n return self\n\n def remove_field(self, index: int) -> Self:\n \"\"\"Removes a field at a specified index.\n\n If the index is invalid or out of bounds then the error is\n silently swallowed.\n\n This function returns the class instance to allow for fluent-style\n chaining.\n\n .. note::\n\n When deleting a field by index, the index of the other fields\n shift to fill the gap just like a regular list.\n\n .. versionchanged:: 2.0\n This function now returns the class instance.\n\n Parameters\n -----------\n index: :class:`int`\n The index of the field to remove.\n \"\"\"\n try:\n del self._fields[index]\n except (AttributeError, IndexError):\n pass\n\n return self\n\n def set_field_at(self, index: int, *, name: Any, value: Any, inline: bool = True) -> Self:\n \"\"\"Modifies a field to the embed object.\n\n The index must point to a valid pre-existing field. Can only be up to 25 fields.\n\n This function returns the class instance to allow for fluent-style\n chaining.\n\n Parameters\n -----------\n index: :class:`int`\n The index of the field to modify.\n name: :class:`str`\n The name of the field. Can only be up to 256 characters.\n value: :class:`str`\n The value of the field. Can only be up to 1024 characters.\n inline: :class:`bool`\n Whether the field should be displayed inline.\n\n Raises\n -------\n IndexError\n An invalid index was provided.\n \"\"\"\n\n try:\n field = self._fields[index]\n except (TypeError, IndexError, AttributeError):\n raise IndexError('field index out of range')\n\n field['name'] = str(name)\n field['value'] = str(value)\n field['inline'] = inline\n return self\n\n def to_dict(self) -> EmbedData:\n \"\"\"Converts this embed object into a dict.\"\"\"\n\n # add in the raw data into the dict\n # fmt: off\n result = {\n key[1:]: getattr(self, key)\n for key in self.__slots__\n if key[0] == '_' and hasattr(self, key)\n }\n # fmt: on\n\n # deal with basic convenience wrappers\n\n try:\n colour = result.pop('colour')\n except KeyError:\n pass\n else:\n if colour:\n result['color'] = colour.value\n\n try:\n timestamp = result.pop('timestamp')\n except KeyError:\n pass\n else:\n if timestamp:\n if timestamp.tzinfo:\n result['timestamp'] = timestamp.astimezone(tz=datetime.timezone.utc).isoformat()\n else:\n result['timestamp'] = timestamp.replace(tzinfo=datetime.timezone.utc).isoformat()\n\n # add in the non raw attribute ones\n if self.type:\n result['type'] = self.type\n\n if self.description:\n result['description'] = self.description\n\n if self.url:\n result['url'] = self.url\n\n if self.title:\n result['title'] = self.title\n\n return result # type: ignore # This payload is equivalent to the EmbedData type\n" }, { "path": "discord/emoji.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import Any, Collection, Iterator, List, Optional, TYPE_CHECKING, Tuple\n\nfrom .asset import Asset, AssetMixin\nfrom .utils import SnowflakeList, snowflake_time, MISSING\nfrom .partial_emoji import _EmojiTag, PartialEmoji\nfrom .user import User\n\n# fmt: off\n__all__ = (\n 'Emoji',\n)\n# fmt: on\n\nif TYPE_CHECKING:\n from .types.emoji import Emoji as EmojiPayload\n from .guild import Guild\n from .state import ConnectionState\n from .abc import Snowflake\n from .role import Role\n from datetime import datetime\n\n\nclass Emoji(_EmojiTag, AssetMixin):\n \"\"\"Represents a custom emoji.\n\n Depending on the way this object was created, some of the attributes can\n have a value of ``None``.\n\n .. container:: operations\n\n .. describe:: x == y\n\n Checks if two emoji are the same.\n\n .. describe:: x != y\n\n Checks if two emoji are not the same.\n\n .. describe:: hash(x)\n\n Return the emoji's hash.\n\n .. describe:: iter(x)\n\n Returns an iterator of ``(field, value)`` pairs. This allows this class\n to be used as an iterable in list/dict/etc constructions.\n\n .. describe:: str(x)\n\n Returns the emoji rendered for discord.\n\n Attributes\n -----------\n name: :class:`str`\n The name of the emoji.\n id: :class:`int`\n The emoji's ID.\n require_colons: :class:`bool`\n If colons are required to use this emoji in the client (:PJSalt: vs PJSalt).\n animated: :class:`bool`\n Whether an emoji is animated or not.\n managed: :class:`bool`\n If this emoji is managed by a Twitch integration.\n guild_id: :class:`int`\n The guild ID the emoji belongs to.\n available: :class:`bool`\n Whether the emoji is available for use.\n user: Optional[:class:`User`]\n The user that created the emoji. This can only be retrieved using :meth:`Guild.fetch_emoji` and\n having :attr:`~Permissions.manage_emojis`.\n \"\"\"\n\n __slots__: Tuple[str, ...] = (\n 'require_colons',\n 'animated',\n 'managed',\n 'id',\n 'name',\n '_roles',\n 'guild_id',\n '_state',\n 'user',\n 'available',\n )\n\n def __init__(self, *, guild: Guild, state: ConnectionState, data: EmojiPayload) -> None:\n self.guild_id: int = guild.id\n self._state: ConnectionState = state\n self._from_data(data)\n\n def _from_data(self, emoji: EmojiPayload) -> None:\n self.require_colons: bool = emoji.get('require_colons', False)\n self.managed: bool = emoji.get('managed', False)\n self.id: int = int(emoji['id']) # type: ignore # This won't be None for full emoji objects.\n self.name: str = emoji['name'] # type: ignore # This won't be None for full emoji objects.\n self.animated: bool = emoji.get('animated', False)\n self.available: bool = emoji.get('available', True)\n self._roles: SnowflakeList = SnowflakeList(map(int, emoji.get('roles', [])))\n user = emoji.get('user')\n self.user: Optional[User] = User(state=self._state, data=user) if user else None\n\n def _to_partial(self) -> PartialEmoji:\n return PartialEmoji(name=self.name, animated=self.animated, id=self.id)\n\n def __iter__(self) -> Iterator[Tuple[str, Any]]:\n for attr in self.__slots__:\n if attr[0] != '_':\n value = getattr(self, attr, None)\n if value is not None:\n yield (attr, value)\n\n def __str__(self) -> str:\n if self.animated:\n return f''\n return f'<:{self.name}:{self.id}>'\n\n def __repr__(self) -> str:\n return f''\n\n def __eq__(self, other: object) -> bool:\n return isinstance(other, _EmojiTag) and self.id == other.id\n\n def __ne__(self, other: object) -> bool:\n return not self.__eq__(other)\n\n def __hash__(self) -> int:\n return self.id >> 22\n\n @property\n def created_at(self) -> datetime:\n \"\"\":class:`datetime.datetime`: Returns the emoji's creation time in UTC.\"\"\"\n return snowflake_time(self.id)\n\n @property\n def url(self) -> str:\n \"\"\":class:`str`: Returns the URL of the emoji.\"\"\"\n fmt = 'gif' if self.animated else 'png'\n return f'{Asset.BASE}/emojis/{self.id}.{fmt}'\n\n @property\n def roles(self) -> List[Role]:\n \"\"\"List[:class:`Role`]: A :class:`list` of roles that is allowed to use this emoji.\n\n If roles is empty, the emoji is unrestricted.\n \"\"\"\n guild = self.guild\n if guild is None:\n return []\n\n return [role for role in guild.roles if self._roles.has(role.id)]\n\n @property\n def guild(self) -> Optional[Guild]:\n \"\"\":class:`Guild`: The guild this emoji belongs to.\"\"\"\n return self._state._get_guild(self.guild_id)\n\n def is_usable(self) -> bool:\n \"\"\":class:`bool`: Whether the bot can use this emoji.\n\n .. versionadded:: 1.3\n \"\"\"\n if not self.available or not self.guild or self.guild.unavailable:\n return False\n if not self._roles:\n return True\n emoji_roles, my_roles = self._roles, self.guild.me._roles\n return any(my_roles.has(role_id) for role_id in emoji_roles)\n\n async def delete(self, *, reason: Optional[str] = None) -> None:\n \"\"\"|coro|\n\n Deletes the custom emoji.\n\n You must have :attr:`~Permissions.manage_emojis` to do this.\n\n Parameters\n -----------\n reason: Optional[:class:`str`]\n The reason for deleting this emoji. Shows up on the audit log.\n\n Raises\n -------\n Forbidden\n You are not allowed to delete emojis.\n HTTPException\n An error occurred deleting the emoji.\n \"\"\"\n\n await self._state.http.delete_custom_emoji(self.guild_id, self.id, reason=reason)\n\n async def edit(\n self, *, name: str = MISSING, roles: Collection[Snowflake] = MISSING, reason: Optional[str] = None\n ) -> Emoji:\n r\"\"\"|coro|\n\n Edits the custom emoji.\n\n You must have :attr:`~Permissions.manage_emojis` to do this.\n\n .. versionchanged:: 2.0\n The newly updated emoji is returned.\n\n Parameters\n -----------\n name: :class:`str`\n The new emoji name.\n roles: List[:class:`~discord.abc.Snowflake`]\n A list of roles that can use this emoji. An empty list can be passed to make it available to everyone.\n reason: Optional[:class:`str`]\n The reason for editing this emoji. Shows up on the audit log.\n\n Raises\n -------\n Forbidden\n You are not allowed to edit emojis.\n HTTPException\n An error occurred editing the emoji.\n\n Returns\n --------\n :class:`Emoji`\n The newly updated emoji.\n \"\"\"\n\n payload = {}\n if name is not MISSING:\n payload['name'] = name\n if roles is not MISSING:\n payload['roles'] = [role.id for role in roles]\n\n data = await self._state.http.edit_custom_emoji(self.guild_id, self.id, payload=payload, reason=reason)\n return Emoji(guild=self.guild, data=data, state=self._state) # type: ignore # if guild is None, the http request would have failed\n" }, { "path": "discord/enums.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\nfrom __future__ import annotations\n\nimport types\nfrom collections import namedtuple\nfrom typing import Any, ClassVar, Dict, List, Optional, TYPE_CHECKING, Tuple, Type, TypeVar, Iterator, Mapping\n\n__all__ = (\n 'Enum',\n 'ChannelType',\n 'MessageType',\n 'SpeakingState',\n 'VerificationLevel',\n 'ContentFilter',\n 'Status',\n 'DefaultAvatar',\n 'AuditLogAction',\n 'AuditLogActionCategory',\n 'UserFlags',\n 'ActivityType',\n 'NotificationLevel',\n 'TeamMembershipState',\n 'TeamMemberRole',\n 'WebhookType',\n 'ExpireBehaviour',\n 'ExpireBehavior',\n 'StickerType',\n 'StickerFormatType',\n 'InviteTarget',\n 'VideoQualityMode',\n 'ComponentType',\n 'ButtonStyle',\n 'TextStyle',\n 'PrivacyLevel',\n 'InteractionType',\n 'InteractionResponseType',\n 'NSFWLevel',\n 'MFALevel',\n 'Locale',\n 'EntityType',\n 'EventStatus',\n 'AppCommandType',\n 'AppCommandOptionType',\n 'AppCommandPermissionType',\n 'AutoModRuleTriggerType',\n 'AutoModRuleEventType',\n 'AutoModRuleActionType',\n 'ForumLayoutType',\n 'ForumOrderType',\n 'SelectDefaultValueType',\n 'SKUType',\n 'EntitlementType',\n 'EntitlementOwnerType',\n 'PollLayoutType',\n)\n\n\ndef _create_value_cls(name: str, comparable: bool):\n # All the type ignores here are due to the type checker being unable to recognise\n # Runtime type creation without exploding.\n cls = namedtuple('_EnumValue_' + name, 'name value')\n cls.__repr__ = lambda self: f'<{name}.{self.name}: {self.value!r}>' # type: ignore\n cls.__str__ = lambda self: f'{name}.{self.name}' # type: ignore\n if comparable:\n cls.__le__ = lambda self, other: isinstance(other, self.__class__) and self.value <= other.value # type: ignore\n cls.__ge__ = lambda self, other: isinstance(other, self.__class__) and self.value >= other.value # type: ignore\n cls.__lt__ = lambda self, other: isinstance(other, self.__class__) and self.value < other.value # type: ignore\n cls.__gt__ = lambda self, other: isinstance(other, self.__class__) and self.value > other.value # type: ignore\n return cls\n\n\ndef _is_descriptor(obj):\n return hasattr(obj, '__get__') or hasattr(obj, '__set__') or hasattr(obj, '__delete__')\n\n\nclass EnumMeta(type):\n if TYPE_CHECKING:\n __name__: ClassVar[str]\n _enum_member_names_: ClassVar[List[str]]\n _enum_member_map_: ClassVar[Dict[str, Any]]\n _enum_value_map_: ClassVar[Dict[Any, Any]]\n\n def __new__(\n cls,\n name: str,\n bases: Tuple[type, ...],\n attrs: Dict[str, Any],\n *,\n comparable: bool = False,\n ) -> EnumMeta:\n value_mapping = {}\n member_mapping = {}\n member_names = []\n\n value_cls = _create_value_cls(name, comparable)\n for key, value in list(attrs.items()):\n is_descriptor = _is_descriptor(value)\n if key[0] == '_' and not is_descriptor:\n continue\n\n # Special case classmethod to just pass through\n if isinstance(value, classmethod):\n continue\n\n if is_descriptor:\n setattr(value_cls, key, value)\n del attrs[key]\n continue\n\n try:\n new_value = value_mapping[value]\n except KeyError:\n new_value = value_cls(name=key, value=value)\n value_mapping[value] = new_value\n member_names.append(key)\n\n member_mapping[key] = new_value\n attrs[key] = new_value\n\n attrs['_enum_value_map_'] = value_mapping\n attrs['_enum_member_map_'] = member_mapping\n attrs['_enum_member_names_'] = member_names\n attrs['_enum_value_cls_'] = value_cls\n actual_cls = super().__new__(cls, name, bases, attrs)\n value_cls._actual_enum_cls_ = actual_cls # type: ignore # Runtime attribute isn't understood\n return actual_cls\n\n def __iter__(cls) -> Iterator[Any]:\n return (cls._enum_member_map_[name] for name in cls._enum_member_names_)\n\n def __reversed__(cls) -> Iterator[Any]:\n return (cls._enum_member_map_[name] for name in reversed(cls._enum_member_names_))\n\n def __len__(cls) -> int:\n return len(cls._enum_member_names_)\n\n def __repr__(cls) -> str:\n return f''\n\n @property\n def __members__(cls) -> Mapping[str, Any]:\n return types.MappingProxyType(cls._enum_member_map_)\n\n def __call__(cls, value: str) -> Any:\n try:\n return cls._enum_value_map_[value]\n except (KeyError, TypeError):\n raise ValueError(f\"{value!r} is not a valid {cls.__name__}\")\n\n def __getitem__(cls, key: str) -> Any:\n return cls._enum_member_map_[key]\n\n def __setattr__(cls, name: str, value: Any) -> None:\n raise TypeError('Enums are immutable.')\n\n def __delattr__(cls, attr: str) -> None:\n raise TypeError('Enums are immutable')\n\n def __instancecheck__(self, instance: Any) -> bool:\n # isinstance(x, Y)\n # -> __instancecheck__(Y, x)\n try:\n return instance._actual_enum_cls_ is self\n except AttributeError:\n return False\n\n\nif TYPE_CHECKING:\n from enum import Enum\nelse:\n\n class Enum(metaclass=EnumMeta):\n @classmethod\n def try_value(cls, value):\n try:\n return cls._enum_value_map_[value]\n except (KeyError, TypeError):\n return value\n\n\nclass ChannelType(Enum):\n text = 0\n private = 1\n voice = 2\n group = 3\n category = 4\n news = 5\n news_thread = 10\n public_thread = 11\n private_thread = 12\n stage_voice = 13\n forum = 15\n media = 16\n\n def __str__(self) -> str:\n return self.name\n\n\nclass MessageType(Enum):\n default = 0\n recipient_add = 1\n recipient_remove = 2\n call = 3\n channel_name_change = 4\n channel_icon_change = 5\n pins_add = 6\n new_member = 7\n premium_guild_subscription = 8\n premium_guild_tier_1 = 9\n premium_guild_tier_2 = 10\n premium_guild_tier_3 = 11\n channel_follow_add = 12\n guild_stream = 13\n guild_discovery_disqualified = 14\n guild_discovery_requalified = 15\n guild_discovery_grace_period_initial_warning = 16\n guild_discovery_grace_period_final_warning = 17\n thread_created = 18\n reply = 19\n chat_input_command = 20\n thread_starter_message = 21\n guild_invite_reminder = 22\n context_menu_command = 23\n auto_moderation_action = 24\n role_subscription_purchase = 25\n interaction_premium_upsell = 26\n stage_start = 27\n stage_end = 28\n stage_speaker = 29\n stage_raise_hand = 30\n stage_topic = 31\n guild_application_premium_subscription = 32\n guild_incident_alert_mode_enabled = 36\n guild_incident_alert_mode_disabled = 37\n guild_incident_report_raid = 38\n guild_incident_report_false_alarm = 39\n\n\nclass SpeakingState(Enum):\n none = 0\n voice = 1\n soundshare = 2\n priority = 4\n\n def __str__(self) -> str:\n return self.name\n\n def __int__(self) -> int:\n return self.value\n\n\nclass VerificationLevel(Enum, comparable=True):\n none = 0\n low = 1\n medium = 2\n high = 3\n highest = 4\n\n def __str__(self) -> str:\n return self.name\n\n\nclass ContentFilter(Enum, comparable=True):\n disabled = 0\n no_role = 1\n all_members = 2\n\n def __str__(self) -> str:\n return self.name\n\n\nclass Status(Enum):\n online = 'online'\n offline = 'offline'\n idle = 'idle'\n dnd = 'dnd'\n do_not_disturb = 'dnd'\n invisible = 'invisible'\n\n def __str__(self) -> str:\n return self.value\n\n\nclass DefaultAvatar(Enum):\n blurple = 0\n grey = 1\n gray = 1\n green = 2\n orange = 3\n red = 4\n pink = 5\n\n def __str__(self) -> str:\n return self.name\n\n\nclass NotificationLevel(Enum, comparable=True):\n all_messages = 0\n only_mentions = 1\n\n\nclass AuditLogActionCategory(Enum):\n create = 1\n delete = 2\n update = 3\n\n\nclass AuditLogAction(Enum):\n # fmt: off\n guild_update = 1\n channel_create = 10\n channel_update = 11\n channel_delete = 12\n overwrite_create = 13\n overwrite_update = 14\n overwrite_delete = 15\n kick = 20\n member_prune = 21\n ban = 22\n unban = 23\n member_update = 24\n member_role_update = 25\n member_move = 26\n member_disconnect = 27\n bot_add = 28\n role_create = 30\n role_update = 31\n role_delete = 32\n invite_create = 40\n invite_update = 41\n invite_delete = 42\n webhook_create = 50\n webhook_update = 51\n webhook_delete = 52\n emoji_create = 60\n emoji_update = 61\n emoji_delete = 62\n message_delete = 72\n message_bulk_delete = 73\n message_pin = 74\n message_unpin = 75\n integration_create = 80\n integration_update = 81\n integration_delete = 82\n stage_instance_create = 83\n stage_instance_update = 84\n stage_instance_delete = 85\n sticker_create = 90\n sticker_update = 91\n sticker_delete = 92\n scheduled_event_create = 100\n scheduled_event_update = 101\n scheduled_event_delete = 102\n thread_create = 110\n thread_update = 111\n thread_delete = 112\n app_command_permission_update = 121\n automod_rule_create = 140\n automod_rule_update = 141\n automod_rule_delete = 142\n automod_block_message = 143\n automod_flag_message = 144\n automod_timeout_member = 145\n creator_monetization_request_created = 150\n creator_monetization_terms_accepted = 151\n # fmt: on\n\n @property\n def category(self) -> Optional[AuditLogActionCategory]:\n # fmt: off\n lookup: Dict[AuditLogAction, Optional[AuditLogActionCategory]] = {\n AuditLogAction.guild_update: AuditLogActionCategory.update,\n AuditLogAction.channel_create: AuditLogActionCategory.create,\n AuditLogAction.channel_update: AuditLogActionCategory.update,\n AuditLogAction.channel_delete: AuditLogActionCategory.delete,\n AuditLogAction.overwrite_create: AuditLogActionCategory.create,\n AuditLogAction.overwrite_update: AuditLogActionCategory.update,\n AuditLogAction.overwrite_delete: AuditLogActionCategory.delete,\n AuditLogAction.kick: None,\n AuditLogAction.member_prune: None,\n AuditLogAction.ban: None,\n AuditLogAction.unban: None,\n AuditLogAction.member_update: AuditLogActionCategory.update,\n AuditLogAction.member_role_update: AuditLogActionCategory.update,\n AuditLogAction.member_move: None,\n AuditLogAction.member_disconnect: None,\n AuditLogAction.bot_add: None,\n AuditLogAction.role_create: AuditLogActionCategory.create,\n AuditLogAction.role_update: AuditLogActionCategory.update,\n AuditLogAction.role_delete: AuditLogActionCategory.delete,\n AuditLogAction.invite_create: AuditLogActionCategory.create,\n AuditLogAction.invite_update: AuditLogActionCategory.update,\n AuditLogAction.invite_delete: AuditLogActionCategory.delete,\n AuditLogAction.webhook_create: AuditLogActionCategory.create,\n AuditLogAction.webhook_update: AuditLogActionCategory.update,\n AuditLogAction.webhook_delete: AuditLogActionCategory.delete,\n AuditLogAction.emoji_create: AuditLogActionCategory.create,\n AuditLogAction.emoji_update: AuditLogActionCategory.update,\n AuditLogAction.emoji_delete: AuditLogActionCategory.delete,\n AuditLogAction.message_delete: AuditLogActionCategory.delete,\n AuditLogAction.message_bulk_delete: AuditLogActionCategory.delete,\n AuditLogAction.message_pin: None,\n AuditLogAction.message_unpin: None,\n AuditLogAction.integration_create: AuditLogActionCategory.create,\n AuditLogAction.integration_update: AuditLogActionCategory.update,\n AuditLogAction.integration_delete: AuditLogActionCategory.delete,\n AuditLogAction.stage_instance_create: AuditLogActionCategory.create,\n AuditLogAction.stage_instance_update: AuditLogActionCategory.update,\n AuditLogAction.stage_instance_delete: AuditLogActionCategory.delete,\n AuditLogAction.sticker_create: AuditLogActionCategory.create,\n AuditLogAction.sticker_update: AuditLogActionCategory.update,\n AuditLogAction.sticker_delete: AuditLogActionCategory.delete,\n AuditLogAction.scheduled_event_create: AuditLogActionCategory.create,\n AuditLogAction.scheduled_event_update: AuditLogActionCategory.update,\n AuditLogAction.scheduled_event_delete: AuditLogActionCategory.delete,\n AuditLogAction.thread_create: AuditLogActionCategory.create,\n AuditLogAction.thread_delete: AuditLogActionCategory.delete,\n AuditLogAction.thread_update: AuditLogActionCategory.update,\n AuditLogAction.app_command_permission_update: AuditLogActionCategory.update,\n AuditLogAction.automod_rule_create: AuditLogActionCategory.create,\n AuditLogAction.automod_rule_update: AuditLogActionCategory.update,\n AuditLogAction.automod_rule_delete: AuditLogActionCategory.delete,\n AuditLogAction.automod_block_message: None,\n AuditLogAction.automod_flag_message: None,\n AuditLogAction.automod_timeout_member: None,\n AuditLogAction.creator_monetization_request_created: None,\n AuditLogAction.creator_monetization_terms_accepted: None,\n }\n # fmt: on\n return lookup[self]\n\n @property\n def target_type(self) -> Optional[str]:\n v = self.value\n if v == -1:\n return 'all'\n elif v < 10:\n return 'guild'\n elif v < 20:\n return 'channel'\n elif v < 30:\n return 'user'\n elif v < 40:\n return 'role'\n elif v < 50:\n return 'invite'\n elif v < 60:\n return 'webhook'\n elif v < 70:\n return 'emoji'\n elif v == 73:\n return 'channel'\n elif v < 80:\n return 'message'\n elif v < 83:\n return 'integration'\n elif v < 90:\n return 'stage_instance'\n elif v < 93:\n return 'sticker'\n elif v < 103:\n return 'guild_scheduled_event'\n elif v < 113:\n return 'thread'\n elif v < 122:\n return 'integration_or_app_command'\n elif 139 < v < 143:\n return 'auto_moderation'\n elif v < 146:\n return 'user'\n elif v < 152:\n return 'creator_monetization'\n\n\nclass UserFlags(Enum):\n staff = 1\n partner = 2\n hypesquad = 4\n bug_hunter = 8\n mfa_sms = 16\n premium_promo_dismissed = 32\n hypesquad_bravery = 64\n hypesquad_brilliance = 128\n hypesquad_balance = 256\n early_supporter = 512\n team_user = 1024\n system = 4096\n has_unread_urgent_messages = 8192\n bug_hunter_level_2 = 16384\n verified_bot = 65536\n verified_bot_developer = 131072\n discord_certified_moderator = 262144\n bot_http_interactions = 524288\n spammer = 1048576\n active_developer = 4194304\n\n\nclass ActivityType(Enum):\n unknown = -1\n playing = 0\n streaming = 1\n listening = 2\n watching = 3\n custom = 4\n competing = 5\n\n def __int__(self) -> int:\n return self.value\n\n\nclass TeamMembershipState(Enum):\n invited = 1\n accepted = 2\n\n\nclass TeamMemberRole(Enum):\n admin = 'admin'\n developer = 'developer'\n read_only = 'read_only'\n\n\nclass WebhookType(Enum):\n incoming = 1\n channel_follower = 2\n application = 3\n\n\nclass ExpireBehaviour(Enum):\n remove_role = 0\n kick = 1\n\n\nExpireBehavior = ExpireBehaviour\n\n\nclass StickerType(Enum):\n standard = 1\n guild = 2\n\n\nclass StickerFormatType(Enum):\n png = 1\n apng = 2\n lottie = 3\n gif = 4\n\n @property\n def file_extension(self) -> str:\n # fmt: off\n lookup: Dict[StickerFormatType, str] = {\n StickerFormatType.png: 'png',\n StickerFormatType.apng: 'png',\n StickerFormatType.lottie: 'json',\n StickerFormatType.gif: 'gif',\n }\n # fmt: on\n return lookup.get(self, 'png')\n\n\nclass InviteTarget(Enum):\n unknown = 0\n stream = 1\n embedded_application = 2\n\n\nclass InteractionType(Enum):\n ping = 1\n application_command = 2\n component = 3\n autocomplete = 4\n modal_submit = 5\n\n\nclass InteractionResponseType(Enum):\n pong = 1\n # ack = 2 (deprecated)\n # channel_message = 3 (deprecated)\n channel_message = 4 # (with source)\n deferred_channel_message = 5 # (with source)\n deferred_message_update = 6 # for components\n message_update = 7 # for components\n autocomplete_result = 8\n modal = 9 # for modals\n # premium_required = 10 (deprecated)\n\n\nclass VideoQualityMode(Enum):\n auto = 1\n full = 2\n\n def __int__(self) -> int:\n return self.value\n\n\nclass ComponentType(Enum):\n action_row = 1\n button = 2\n select = 3\n string_select = 3\n text_input = 4\n user_select = 5\n role_select = 6\n mentionable_select = 7\n channel_select = 8\n\n def __int__(self) -> int:\n return self.value\n\n\nclass ButtonStyle(Enum):\n primary = 1\n secondary = 2\n success = 3\n danger = 4\n link = 5\n premium = 6\n\n # Aliases\n blurple = 1\n grey = 2\n gray = 2\n green = 3\n red = 4\n url = 5\n\n def __int__(self) -> int:\n return self.value\n\n\nclass TextStyle(Enum):\n short = 1\n paragraph = 2\n\n # Aliases\n long = 2\n\n def __int__(self) -> int:\n return self.value\n\n\nclass PrivacyLevel(Enum):\n guild_only = 2\n\n\nclass NSFWLevel(Enum, comparable=True):\n default = 0\n explicit = 1\n safe = 2\n age_restricted = 3\n\n\nclass MFALevel(Enum, comparable=True):\n disabled = 0\n require_2fa = 1\n\n\nclass Locale(Enum):\n american_english = 'en-US'\n british_english = 'en-GB'\n bulgarian = 'bg'\n chinese = 'zh-CN'\n taiwan_chinese = 'zh-TW'\n croatian = 'hr'\n czech = 'cs'\n indonesian = 'id'\n danish = 'da'\n dutch = 'nl'\n finnish = 'fi'\n french = 'fr'\n german = 'de'\n greek = 'el'\n hindi = 'hi'\n hungarian = 'hu'\n italian = 'it'\n japanese = 'ja'\n korean = 'ko'\n latin_american_spanish = 'es-419'\n lithuanian = 'lt'\n norwegian = 'no'\n polish = 'pl'\n brazil_portuguese = 'pt-BR'\n romanian = 'ro'\n russian = 'ru'\n spain_spanish = 'es-ES'\n swedish = 'sv-SE'\n thai = 'th'\n turkish = 'tr'\n ukrainian = 'uk'\n vietnamese = 'vi'\n\n def __str__(self) -> str:\n return self.value\n\n\nE = TypeVar('E', bound='Enum')\n\n\nclass EntityType(Enum):\n stage_instance = 1\n voice = 2\n external = 3\n\n\nclass EventStatus(Enum):\n scheduled = 1\n active = 2\n completed = 3\n canceled = 4\n\n ended = 3\n cancelled = 4\n\n\nclass AppCommandOptionType(Enum):\n subcommand = 1\n subcommand_group = 2\n string = 3\n integer = 4\n boolean = 5\n user = 6\n channel = 7\n role = 8\n mentionable = 9\n number = 10\n attachment = 11\n\n\nclass AppCommandType(Enum):\n chat_input = 1\n user = 2\n message = 3\n\n\nclass AppCommandPermissionType(Enum):\n role = 1\n user = 2\n channel = 3\n\n\nclass AutoModRuleTriggerType(Enum):\n keyword = 1\n harmful_link = 2\n spam = 3\n keyword_preset = 4\n mention_spam = 5\n member_profile = 6\n\n\nclass AutoModRuleEventType(Enum):\n message_send = 1\n member_update = 2\n\n\nclass AutoModRuleActionType(Enum):\n block_message = 1\n send_alert_message = 2\n timeout = 3\n block_member_interactions = 4\n\n\nclass ForumLayoutType(Enum):\n not_set = 0\n list_view = 1\n gallery_view = 2\n\n\nclass ForumOrderType(Enum):\n latest_activity = 0\n creation_date = 1\n\n\nclass SelectDefaultValueType(Enum):\n user = 'user'\n role = 'role'\n channel = 'channel'\n\n\nclass SKUType(Enum):\n durable = 2\n consumable = 3\n subscription = 5\n subscription_group = 6\n\n\nclass EntitlementType(Enum):\n purchase = 1\n premium_subscription = 2\n developer_gift = 3\n test_mode_purchase = 4\n free_purchase = 5\n user_gift = 6\n premium_purchase = 7\n application_subscription = 8\n\n\nclass EntitlementOwnerType(Enum):\n guild = 1\n user = 2\n\n\nclass PollLayoutType(Enum):\n default = 1\n\n\nclass InviteType(Enum):\n guild = 0\n group_dm = 1\n friend = 2\n\n\nclass ReactionType(Enum):\n normal = 0\n burst = 1\n\n\ndef create_unknown_value(cls: Type[E], val: Any) -> E:\n value_cls = cls._enum_value_cls_ # type: ignore # This is narrowed below\n name = f'unknown_{val}'\n return value_cls(name=name, value=val)\n\n\ndef try_enum(cls: Type[E], val: Any) -> E:\n \"\"\"A function that tries to turn the value into enum ``cls``.\n\n If it fails it returns a proxy invalid value instead.\n \"\"\"\n\n try:\n return cls._enum_value_map_[val] # type: ignore # All errors are caught below\n except (KeyError, TypeError, AttributeError):\n return create_unknown_value(cls, val)\n" }, { "path": "discord/errors.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\nfrom typing import Dict, List, Optional, TYPE_CHECKING, Any, Tuple, Union\n\nif TYPE_CHECKING:\n from aiohttp import ClientResponse, ClientWebSocketResponse\n from requests import Response\n\n _ResponseType = Union[ClientResponse, Response]\n\n from .interactions import Interaction\n\n__all__ = (\n 'DiscordException',\n 'ClientException',\n 'GatewayNotFound',\n 'HTTPException',\n 'RateLimited',\n 'Forbidden',\n 'NotFound',\n 'DiscordServerError',\n 'InvalidData',\n 'LoginFailure',\n 'ConnectionClosed',\n 'PrivilegedIntentsRequired',\n 'InteractionResponded',\n)\n\n\nclass DiscordException(Exception):\n \"\"\"Base exception class for discord.py\n\n Ideally speaking, this could be caught to handle any exceptions raised from this library.\n \"\"\"\n\n pass\n\n\nclass ClientException(DiscordException):\n \"\"\"Exception that's raised when an operation in the :class:`Client` fails.\n\n These are usually for exceptions that happened due to user input.\n \"\"\"\n\n pass\n\n\nclass GatewayNotFound(DiscordException):\n \"\"\"An exception that is raised when the gateway for Discord could not be found\"\"\"\n\n def __init__(self):\n message = 'The gateway to connect to discord was not found.'\n super().__init__(message)\n\n\ndef _flatten_error_dict(d: Dict[str, Any], key: str = '') -> Dict[str, str]:\n items: List[Tuple[str, str]] = []\n for k, v in d.items():\n new_key = key + '.' + k if key else k\n\n if isinstance(v, dict):\n try:\n _errors: List[Dict[str, Any]] = v['_errors']\n except KeyError:\n items.extend(_flatten_error_dict(v, new_key).items())\n else:\n items.append((new_key, ' '.join(x.get('message', '') for x in _errors)))\n else:\n items.append((new_key, v))\n\n return dict(items)\n\n\nclass HTTPException(DiscordException):\n \"\"\"Exception that's raised when an HTTP request operation fails.\n\n Attributes\n ------------\n response: :class:`aiohttp.ClientResponse`\n The response of the failed HTTP request. This is an\n instance of :class:`aiohttp.ClientResponse`. In some cases\n this could also be a :class:`requests.Response`.\n\n text: :class:`str`\n The text of the error. Could be an empty string.\n status: :class:`int`\n The status code of the HTTP request.\n code: :class:`int`\n The Discord specific error code for the failure.\n \"\"\"\n\n def __init__(self, response: _ResponseType, message: Optional[Union[str, Dict[str, Any]]]):\n self.response: _ResponseType = response\n self.status: int = response.status # type: ignore # This attribute is filled by the library even if using requests\n self.code: int\n self.text: str\n if isinstance(message, dict):\n self.code = message.get('code', 0)\n base = message.get('message', '')\n errors = message.get('errors')\n self._errors: Optional[Dict[str, Any]] = errors\n if errors:\n errors = _flatten_error_dict(errors)\n helpful = '\\n'.join('In %s: %s' % t for t in errors.items())\n self.text = base + '\\n' + helpful\n else:\n self.text = base\n else:\n self.text = message or ''\n self.code = 0\n\n fmt = '{0.status} {0.reason} (error code: {1})'\n if len(self.text):\n fmt += ': {2}'\n\n super().__init__(fmt.format(self.response, self.code, self.text))\n\n\nclass RateLimited(DiscordException):\n \"\"\"Exception that's raised for when status code 429 occurs\n and the timeout is greater than the configured maximum using\n the ``max_ratelimit_timeout`` parameter in :class:`Client`.\n\n This is not raised during global ratelimits.\n\n Since sometimes requests are halted pre-emptively before they're\n even made, this **does not** subclass :exc:`HTTPException`.\n\n .. versionadded:: 2.0\n\n Attributes\n ------------\n retry_after: :class:`float`\n The amount of seconds that the client should wait before retrying\n the request.\n \"\"\"\n\n def __init__(self, retry_after: float):\n self.retry_after = retry_after\n super().__init__(f'Too many requests. Retry in {retry_after:.2f} seconds.')\n\n\nclass Forbidden(HTTPException):\n \"\"\"Exception that's raised for when status code 403 occurs.\n\n Subclass of :exc:`HTTPException`\n \"\"\"\n\n pass\n\n\nclass NotFound(HTTPException):\n \"\"\"Exception that's raised for when status code 404 occurs.\n\n Subclass of :exc:`HTTPException`\n \"\"\"\n\n pass\n\n\nclass DiscordServerError(HTTPException):\n \"\"\"Exception that's raised for when a 500 range status code occurs.\n\n Subclass of :exc:`HTTPException`.\n\n .. versionadded:: 1.5\n \"\"\"\n\n pass\n\n\nclass InvalidData(ClientException):\n \"\"\"Exception that's raised when the library encounters unknown\n or invalid data from Discord.\n \"\"\"\n\n pass\n\n\nclass LoginFailure(ClientException):\n \"\"\"Exception that's raised when the :meth:`Client.login` function\n fails to log you in from improper credentials or some other misc.\n failure.\n \"\"\"\n\n pass\n\n\nclass ConnectionClosed(ClientException):\n \"\"\"Exception that's raised when the gateway connection is\n closed for reasons that could not be handled internally.\n\n Attributes\n -----------\n code: :class:`int`\n The close code of the websocket.\n reason: :class:`str`\n The reason provided for the closure.\n shard_id: Optional[:class:`int`]\n The shard ID that got closed if applicable.\n \"\"\"\n\n def __init__(self, socket: ClientWebSocketResponse, *, shard_id: Optional[int], code: Optional[int] = None):\n # This exception is just the same exception except\n # reconfigured to subclass ClientException for users\n self.code: int = code or socket.close_code or -1\n # aiohttp doesn't seem to consistently provide close reason\n self.reason: str = ''\n self.shard_id: Optional[int] = shard_id\n super().__init__(f'Shard ID {self.shard_id} WebSocket closed with {self.code}')\n\n\nclass PrivilegedIntentsRequired(ClientException):\n \"\"\"Exception that's raised when the gateway is requesting privileged intents\n but they're not ticked in the developer page yet.\n\n Go to https://discord.com/developers/applications/ and enable the intents\n that are required. Currently these are as follows:\n\n - :attr:`Intents.members`\n - :attr:`Intents.presences`\n - :attr:`Intents.message_content`\n\n Attributes\n -----------\n shard_id: Optional[:class:`int`]\n The shard ID that got closed if applicable.\n \"\"\"\n\n def __init__(self, shard_id: Optional[int]):\n self.shard_id: Optional[int] = shard_id\n msg = (\n 'Shard ID %s is requesting privileged intents that have not been explicitly enabled in the '\n 'developer portal. It is recommended to go to https://discord.com/developers/applications/ '\n 'and explicitly enable the privileged intents within your application\\'s page. If this is not '\n 'possible, then consider disabling the privileged intents instead.'\n )\n super().__init__(msg % shard_id)\n\n\nclass InteractionResponded(ClientException):\n \"\"\"Exception that's raised when sending another interaction response using\n :class:`InteractionResponse` when one has already been done before.\n\n An interaction can only respond once.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n interaction: :class:`Interaction`\n The interaction that's already been responded to.\n \"\"\"\n\n def __init__(self, interaction: Interaction):\n self.interaction: Interaction = interaction\n super().__init__('This interaction has already been responded to before')\n" }, { "path": "discord/ext/commands/__init__.py", "content": "\"\"\"\ndiscord.ext.commands\n~~~~~~~~~~~~~~~~~~~~~\n\nAn extension module to facilitate creation of bot commands.\n\n:copyright: (c) 2015-present Rapptz\n:license: MIT, see LICENSE for more details.\n\"\"\"\n\nfrom .bot import *\nfrom .cog import *\nfrom .context import *\nfrom .converter import *\nfrom .cooldowns import *\nfrom .core import *\nfrom .errors import *\nfrom .flags import *\nfrom .help import *\nfrom .parameters import *\nfrom .hybrid import *\n" }, { "path": "discord/ext/commands/_types.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\n\nfrom typing import Any, Awaitable, Callable, Coroutine, TYPE_CHECKING, Protocol, TypeVar, Union, Tuple, Optional\n\n\nT = TypeVar('T')\n\nif TYPE_CHECKING:\n from typing_extensions import ParamSpec\n\n from .bot import Bot, AutoShardedBot\n from .context import Context\n from .cog import Cog\n from .errors import CommandError\n\n P = ParamSpec('P')\n MaybeAwaitableFunc = Callable[P, 'MaybeAwaitable[T]']\nelse:\n P = TypeVar('P')\n MaybeAwaitableFunc = Tuple[P, T]\n\n_Bot = Union['Bot', 'AutoShardedBot']\nCoro = Coroutine[Any, Any, T]\nCoroFunc = Callable[..., Coro[Any]]\nMaybeCoro = Union[T, Coro[T]]\nMaybeAwaitable = Union[T, Awaitable[T]]\n\nCogT = TypeVar('CogT', bound='Optional[Cog]')\nUserCheck = Callable[[\"ContextT\"], MaybeCoro[bool]]\nHook = Union[Callable[[\"CogT\", \"ContextT\"], Coro[Any]], Callable[[\"ContextT\"], Coro[Any]]]\nError = Union[Callable[[\"CogT\", \"ContextT\", \"CommandError\"], Coro[Any]], Callable[[\"ContextT\", \"CommandError\"], Coro[Any]]]\n\nContextT = TypeVar('ContextT', bound='Context[Any]')\nBotT = TypeVar('BotT', bound=_Bot, covariant=True)\n\nContextT_co = TypeVar('ContextT_co', bound='Context[Any]', covariant=True)\n\n\nclass Check(Protocol[ContextT_co]): # type: ignore # TypeVar is expected to be invariant\n\n predicate: Callable[[ContextT_co], Coroutine[Any, Any, bool]]\n\n def __call__(self, coro_or_commands: T) -> T:\n ...\n\n\n# This is merely a tag type to avoid circular import issues.\n# Yes, this is a terrible solution but ultimately it is the only solution.\nclass _BaseCommand:\n __slots__ = ()\n" }, { "path": "discord/ext/commands/bot.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\n\nimport asyncio\nimport collections\nimport collections.abc\nimport inspect\nimport importlib.util\nimport sys\nimport logging\nimport types\nfrom typing import (\n Any,\n Callable,\n Mapping,\n List,\n Dict,\n TYPE_CHECKING,\n Optional,\n Sequence,\n TypeVar,\n Type,\n Union,\n Iterable,\n Collection,\n overload,\n)\n\nimport discord\nfrom discord import app_commands\nfrom discord.app_commands.tree import _retrieve_guild_ids\nfrom discord.utils import MISSING, _is_submodule\n\nfrom .core import GroupMixin\nfrom .view import StringView\nfrom .context import Context\nfrom . import errors\nfrom .help import HelpCommand, DefaultHelpCommand\nfrom .cog import Cog\nfrom .hybrid import hybrid_command, hybrid_group, HybridCommand, HybridGroup\n\nif TYPE_CHECKING:\n from typing_extensions import Self\n\n import importlib.machinery\n\n from discord.message import Message\n from discord.interactions import Interaction\n from discord.abc import User, Snowflake\n from ._types import (\n _Bot,\n BotT,\n UserCheck,\n CoroFunc,\n ContextT,\n MaybeAwaitableFunc,\n )\n from .core import Command\n from .hybrid import CommandCallback, ContextT, P\n\n _Prefix = Union[Iterable[str], str]\n _PrefixCallable = MaybeAwaitableFunc[[BotT, Message], _Prefix]\n PrefixType = Union[_Prefix, _PrefixCallable[BotT]]\n\n__all__ = (\n 'when_mentioned',\n 'when_mentioned_or',\n 'Bot',\n 'AutoShardedBot',\n)\n\nT = TypeVar('T')\nCFT = TypeVar('CFT', bound='CoroFunc')\n\n_log = logging.getLogger(__name__)\n\n\ndef when_mentioned(bot: _Bot, msg: Message, /) -> List[str]:\n \"\"\"A callable that implements a command prefix equivalent to being mentioned.\n\n These are meant to be passed into the :attr:`.Bot.command_prefix` attribute.\n\n .. versionchanged:: 2.0\n\n ``bot`` and ``msg`` parameters are now positional-only.\n \"\"\"\n # bot.user will never be None when this is called\n return [f'<@{bot.user.id}> ', f'<@!{bot.user.id}> '] # type: ignore\n\n\ndef when_mentioned_or(*prefixes: str) -> Callable[[_Bot, Message], List[str]]:\n \"\"\"A callable that implements when mentioned or other prefixes provided.\n\n These are meant to be passed into the :attr:`.Bot.command_prefix` attribute.\n\n Example\n --------\n\n .. code-block:: python3\n\n bot = commands.Bot(command_prefix=commands.when_mentioned_or('!'))\n\n\n .. note::\n\n This callable returns another callable, so if this is done inside a custom\n callable, you must call the returned callable, for example:\n\n .. code-block:: python3\n\n async def get_prefix(bot, message):\n extras = await prefixes_for(message.guild) # returns a list\n return commands.when_mentioned_or(*extras)(bot, message)\n\n\n See Also\n ----------\n :func:`.when_mentioned`\n \"\"\"\n\n def inner(bot, msg):\n r = list(prefixes)\n r = when_mentioned(bot, msg) + r\n return r\n\n return inner\n\n\nclass _DefaultRepr:\n def __repr__(self):\n return ''\n\n\n_default: Any = _DefaultRepr()\n\n\nclass BotBase(GroupMixin[None]):\n def __init__(\n self,\n command_prefix: PrefixType[BotT],\n *,\n help_command: Optional[HelpCommand] = _default,\n tree_cls: Type[app_commands.CommandTree[Any]] = app_commands.CommandTree,\n description: Optional[str] = None,\n allowed_contexts: app_commands.AppCommandContext = MISSING,\n allowed_installs: app_commands.AppInstallationType = MISSING,\n intents: discord.Intents,\n **options: Any,\n ) -> None:\n super().__init__(intents=intents, **options)\n self.command_prefix: PrefixType[BotT] = command_prefix\n self.extra_events: Dict[str, List[CoroFunc]] = {}\n # Self doesn't have the ClientT bound, but since this is a mixin it technically does\n self.__tree: app_commands.CommandTree[Self] = tree_cls(self) # type: ignore\n if allowed_contexts is not MISSING:\n self.__tree.allowed_contexts = allowed_contexts\n if allowed_installs is not MISSING:\n self.__tree.allowed_installs = allowed_installs\n\n self.__cogs: Dict[str, Cog] = {}\n self.__extensions: Dict[str, types.ModuleType] = {}\n self._checks: List[UserCheck] = []\n self._check_once: List[UserCheck] = []\n self._before_invoke: Optional[CoroFunc] = None\n self._after_invoke: Optional[CoroFunc] = None\n self._help_command: Optional[HelpCommand] = None\n self.description: str = inspect.cleandoc(description) if description else ''\n self.owner_id: Optional[int] = options.get('owner_id')\n self.owner_ids: Optional[Collection[int]] = options.get('owner_ids', set())\n self.strip_after_prefix: bool = options.get('strip_after_prefix', False)\n\n if self.owner_id and self.owner_ids:\n raise TypeError('Both owner_id and owner_ids are set.')\n\n if self.owner_ids and not isinstance(self.owner_ids, collections.abc.Collection):\n raise TypeError(f'owner_ids must be a collection not {self.owner_ids.__class__.__name__}')\n\n if help_command is _default:\n self.help_command = DefaultHelpCommand()\n else:\n self.help_command = help_command\n\n # internal helpers\n\n async def _async_setup_hook(self) -> None:\n # self/super() resolves to Client/AutoShardedClient\n await super()._async_setup_hook() # type: ignore\n prefix = self.command_prefix\n\n # This has to be here because for the default logging set up to capture\n # the logging calls, they have to come after the `Client.run` call.\n # The best place to do this is in an async init scenario\n if not self.intents.message_content: # type: ignore\n trigger_warning = (\n (callable(prefix) and prefix is not when_mentioned)\n or isinstance(prefix, str)\n or (isinstance(prefix, collections.abc.Iterable) and len(list(prefix)) >= 1)\n )\n if trigger_warning:\n _log.warning('Privileged message content intent is missing, commands may not work as expected.')\n\n def dispatch(self, event_name: str, /, *args: Any, **kwargs: Any) -> None:\n # super() will resolve to Client\n super().dispatch(event_name, *args, **kwargs) # type: ignore\n ev = 'on_' + event_name\n for event in self.extra_events.get(ev, []):\n self._schedule_event(event, ev, *args, **kwargs) # type: ignore\n\n @discord.utils.copy_doc(discord.Client.close)\n async def close(self) -> None:\n for extension in tuple(self.__extensions):\n try:\n await self.unload_extension(extension)\n except Exception:\n pass\n\n for cog in tuple(self.__cogs):\n try:\n await self.remove_cog(cog)\n except Exception:\n pass\n\n await super().close() # type: ignore\n\n # GroupMixin overrides\n\n @discord.utils.copy_doc(GroupMixin.add_command)\n def add_command(self, command: Command[Any, ..., Any], /) -> None:\n super().add_command(command)\n if isinstance(command, (HybridCommand, HybridGroup)) and command.app_command:\n # If a cog is also inheriting from app_commands.Group then it'll also\n # add the hybrid commands as text commands, which would recursively add the\n # hybrid commands as slash commands. This check just terminates that recursion\n # from happening\n if command.cog is None or not command.cog.__cog_is_app_commands_group__:\n self.tree.add_command(command.app_command)\n\n @discord.utils.copy_doc(GroupMixin.remove_command)\n def remove_command(self, name: str, /) -> Optional[Command[Any, ..., Any]]:\n cmd: Optional[Command[Any, ..., Any]] = super().remove_command(name)\n if isinstance(cmd, (HybridCommand, HybridGroup)) and cmd.app_command:\n # See above\n if cmd.cog is not None and cmd.cog.__cog_is_app_commands_group__:\n return cmd\n\n guild_ids: Optional[List[int]] = cmd.app_command._guild_ids\n if guild_ids is None:\n self.__tree.remove_command(name)\n else:\n for guild_id in guild_ids:\n self.__tree.remove_command(name, guild=discord.Object(id=guild_id))\n\n return cmd\n\n def hybrid_command(\n self,\n name: Union[str, app_commands.locale_str] = MISSING,\n with_app_command: bool = True,\n *args: Any,\n **kwargs: Any,\n ) -> Callable[[CommandCallback[Any, ContextT, P, T]], HybridCommand[Any, P, T]]:\n \"\"\"A shortcut decorator that invokes :func:`~discord.ext.commands.hybrid_command` and adds it to\n the internal command list via :meth:`add_command`.\n\n Returns\n --------\n Callable[..., :class:`HybridCommand`]\n A decorator that converts the provided method into a Command, adds it to the bot, then returns it.\n \"\"\"\n\n def decorator(func: CommandCallback[Any, ContextT, P, T]):\n kwargs.setdefault('parent', self)\n result = hybrid_command(name=name, *args, with_app_command=with_app_command, **kwargs)(func)\n self.add_command(result)\n return result\n\n return decorator\n\n def hybrid_group(\n self,\n name: Union[str, app_commands.locale_str] = MISSING,\n with_app_command: bool = True,\n *args: Any,\n **kwargs: Any,\n ) -> Callable[[CommandCallback[Any, ContextT, P, T]], HybridGroup[Any, P, T]]:\n \"\"\"A shortcut decorator that invokes :func:`~discord.ext.commands.hybrid_group` and adds it to\n the internal command list via :meth:`add_command`.\n\n Returns\n --------\n Callable[..., :class:`HybridGroup`]\n A decorator that converts the provided method into a Group, adds it to the bot, then returns it.\n \"\"\"\n\n def decorator(func: CommandCallback[Any, ContextT, P, T]):\n kwargs.setdefault('parent', self)\n result = hybrid_group(name=name, *args, with_app_command=with_app_command, **kwargs)(func)\n self.add_command(result)\n return result\n\n return decorator\n\n # Error handler\n\n async def on_command_error(self, context: Context[BotT], exception: errors.CommandError, /) -> None:\n \"\"\"|coro|\n\n The default command error handler provided by the bot.\n\n By default this logs to the library logger, however it could be\n overridden to have a different implementation.\n\n This only fires if you do not specify any listeners for command error.\n\n .. versionchanged:: 2.0\n\n ``context`` and ``exception`` parameters are now positional-only.\n Instead of writing to ``sys.stderr`` this now uses the library logger.\n \"\"\"\n if self.extra_events.get('on_command_error', None):\n return\n\n command = context.command\n if command and command.has_error_handler():\n return\n\n cog = context.cog\n if cog and cog.has_error_handler():\n return\n\n _log.error('Ignoring exception in command %s', command, exc_info=exception)\n\n # global check registration\n\n def check(self, func: T, /) -> T:\n r\"\"\"A decorator that adds a global check to the bot.\n\n A global check is similar to a :func:`.check` that is applied\n on a per command basis except it is run before any command checks\n have been verified and applies to every command the bot has.\n\n .. note::\n\n This function can either be a regular function or a coroutine.\n\n Similar to a command :func:`.check`\\, this takes a single parameter\n of type :class:`.Context` and can only raise exceptions inherited from\n :exc:`.CommandError`.\n\n Example\n ---------\n\n .. code-block:: python3\n\n @bot.check\n def check_commands(ctx):\n return ctx.command.qualified_name in allowed_commands\n\n .. versionchanged:: 2.0\n\n ``func`` parameter is now positional-only.\n \"\"\"\n # T was used instead of Check to ensure the type matches on return\n self.add_check(func) # type: ignore\n return func\n\n def add_check(self, func: UserCheck[ContextT], /, *, call_once: bool = False) -> None:\n \"\"\"Adds a global check to the bot.\n\n This is the non-decorator interface to :meth:`.check`\n and :meth:`.check_once`.\n\n .. versionchanged:: 2.0\n\n ``func`` parameter is now positional-only.\n\n .. seealso:: The :func:`~discord.ext.commands.check` decorator\n\n Parameters\n -----------\n func\n The function that was used as a global check.\n call_once: :class:`bool`\n If the function should only be called once per\n :meth:`.invoke` call.\n \"\"\"\n\n if call_once:\n self._check_once.append(func)\n else:\n self._checks.append(func)\n\n def remove_check(self, func: UserCheck[ContextT], /, *, call_once: bool = False) -> None:\n \"\"\"Removes a global check from the bot.\n\n This function is idempotent and will not raise an exception\n if the function is not in the global checks.\n\n .. versionchanged:: 2.0\n\n ``func`` parameter is now positional-only.\n\n Parameters\n -----------\n func\n The function to remove from the global checks.\n call_once: :class:`bool`\n If the function was added with ``call_once=True`` in\n the :meth:`.Bot.add_check` call or using :meth:`.check_once`.\n \"\"\"\n l = self._check_once if call_once else self._checks\n\n try:\n l.remove(func)\n except ValueError:\n pass\n\n def check_once(self, func: CFT, /) -> CFT:\n r\"\"\"A decorator that adds a \"call once\" global check to the bot.\n\n Unlike regular global checks, this one is called only once\n per :meth:`.invoke` call.\n\n Regular global checks are called whenever a command is called\n or :meth:`.Command.can_run` is called. This type of check\n bypasses that and ensures that it's called only once, even inside\n the default help command.\n\n .. note::\n\n When using this function the :class:`.Context` sent to a group subcommand\n may only parse the parent command and not the subcommands due to it\n being invoked once per :meth:`.Bot.invoke` call.\n\n .. note::\n\n This function can either be a regular function or a coroutine.\n\n Similar to a command :func:`.check`\\, this takes a single parameter\n of type :class:`.Context` and can only raise exceptions inherited from\n :exc:`.CommandError`.\n\n Example\n ---------\n\n .. code-block:: python3\n\n @bot.check_once\n def whitelist(ctx):\n return ctx.message.author.id in my_whitelist\n\n .. versionchanged:: 2.0\n\n ``func`` parameter is now positional-only.\n\n \"\"\"\n self.add_check(func, call_once=True)\n return func\n\n async def can_run(self, ctx: Context[BotT], /, *, call_once: bool = False) -> bool:\n data = self._check_once if call_once else self._checks\n\n if len(data) == 0:\n return True\n\n return await discord.utils.async_all(f(ctx) for f in data)\n\n async def is_owner(self, user: User, /) -> bool:\n \"\"\"|coro|\n\n Checks if a :class:`~discord.User` or :class:`~discord.Member` is the owner of\n this bot.\n\n If an :attr:`owner_id` is not set, it is fetched automatically\n through the use of :meth:`~.Bot.application_info`.\n\n .. versionchanged:: 1.3\n The function also checks if the application is team-owned if\n :attr:`owner_ids` is not set.\n\n .. versionchanged:: 2.0\n\n ``user`` parameter is now positional-only.\n\n .. versionchanged:: 2.4\n\n This function now respects the team member roles if the bot is team-owned.\n In order to be considered an owner, they must be either an admin or\n a developer.\n\n Parameters\n -----------\n user: :class:`.abc.User`\n The user to check for.\n\n Returns\n --------\n :class:`bool`\n Whether the user is the owner.\n \"\"\"\n\n if self.owner_id:\n return user.id == self.owner_id\n elif self.owner_ids:\n return user.id in self.owner_ids\n else:\n app: discord.AppInfo = await self.application_info() # type: ignore\n if app.team:\n self.owner_ids = ids = {\n m.id\n for m in app.team.members\n if m.role in (discord.TeamMemberRole.admin, discord.TeamMemberRole.developer)\n }\n return user.id in ids\n else:\n self.owner_id = owner_id = app.owner.id\n return user.id == owner_id\n\n def before_invoke(self, coro: CFT, /) -> CFT:\n \"\"\"A decorator that registers a coroutine as a pre-invoke hook.\n\n A pre-invoke hook is called directly before the command is\n called. This makes it a useful function to set up database\n connections or any type of set up required.\n\n This pre-invoke hook takes a sole parameter, a :class:`.Context`.\n\n .. note::\n\n The :meth:`~.Bot.before_invoke` and :meth:`~.Bot.after_invoke` hooks are\n only called if all checks and argument parsing procedures pass\n without error. If any check or argument parsing procedures fail\n then the hooks are not called.\n\n .. versionchanged:: 2.0\n\n ``coro`` parameter is now positional-only.\n\n Parameters\n -----------\n coro: :ref:`coroutine `\n The coroutine to register as the pre-invoke hook.\n\n Raises\n -------\n TypeError\n The coroutine passed is not actually a coroutine.\n \"\"\"\n if not asyncio.iscoroutinefunction(coro):\n raise TypeError('The pre-invoke hook must be a coroutine.')\n\n self._before_invoke = coro\n return coro\n\n def after_invoke(self, coro: CFT, /) -> CFT:\n r\"\"\"A decorator that registers a coroutine as a post-invoke hook.\n\n A post-invoke hook is called directly after the command is\n called. This makes it a useful function to clean-up database\n connections or any type of clean up required.\n\n This post-invoke hook takes a sole parameter, a :class:`.Context`.\n\n .. note::\n\n Similar to :meth:`~.Bot.before_invoke`\\, this is not called unless\n checks and argument parsing procedures succeed. This hook is,\n however, **always** called regardless of the internal command\n callback raising an error (i.e. :exc:`.CommandInvokeError`\\).\n This makes it ideal for clean-up scenarios.\n\n .. versionchanged:: 2.0\n\n ``coro`` parameter is now positional-only.\n\n Parameters\n -----------\n coro: :ref:`coroutine `\n The coroutine to register as the post-invoke hook.\n\n Raises\n -------\n TypeError\n The coroutine passed is not actually a coroutine.\n \"\"\"\n if not asyncio.iscoroutinefunction(coro):\n raise TypeError('The post-invoke hook must be a coroutine.')\n\n self._after_invoke = coro\n return coro\n\n # listener registration\n\n def add_listener(self, func: CoroFunc, /, name: str = MISSING) -> None:\n \"\"\"The non decorator alternative to :meth:`.listen`.\n\n .. versionchanged:: 2.0\n\n ``func`` parameter is now positional-only.\n\n Parameters\n -----------\n func: :ref:`coroutine `\n The function to call.\n name: :class:`str`\n The name of the event to listen for. Defaults to ``func.__name__``.\n\n Example\n --------\n\n .. code-block:: python3\n\n async def on_ready(): pass\n async def my_message(message): pass\n\n bot.add_listener(on_ready)\n bot.add_listener(my_message, 'on_message')\n\n \"\"\"\n name = func.__name__ if name is MISSING else name\n\n if not asyncio.iscoroutinefunction(func):\n raise TypeError('Listeners must be coroutines')\n\n if name in self.extra_events:\n self.extra_events[name].append(func)\n else:\n self.extra_events[name] = [func]\n\n def remove_listener(self, func: CoroFunc, /, name: str = MISSING) -> None:\n \"\"\"Removes a listener from the pool of listeners.\n\n .. versionchanged:: 2.0\n\n ``func`` parameter is now positional-only.\n\n Parameters\n -----------\n func\n The function that was used as a listener to remove.\n name: :class:`str`\n The name of the event we want to remove. Defaults to\n ``func.__name__``.\n \"\"\"\n\n name = func.__name__ if name is MISSING else name\n\n if name in self.extra_events:\n try:\n self.extra_events[name].remove(func)\n except ValueError:\n pass\n\n def listen(self, name: str = MISSING) -> Callable[[CFT], CFT]:\n \"\"\"A decorator that registers another function as an external\n event listener. Basically this allows you to listen to multiple\n events from different places e.g. such as :func:`.on_ready`\n\n The functions being listened to must be a :ref:`coroutine `.\n\n Example\n --------\n\n .. code-block:: python3\n\n @bot.listen()\n async def on_message(message):\n print('one')\n\n # in some other file...\n\n @bot.listen('on_message')\n async def my_message(message):\n print('two')\n\n Would print one and two in an unspecified order.\n\n Raises\n -------\n TypeError\n The function being listened to is not a coroutine.\n \"\"\"\n\n def decorator(func: CFT) -> CFT:\n self.add_listener(func, name)\n return func\n\n return decorator\n\n # cogs\n\n async def add_cog(\n self,\n cog: Cog,\n /,\n *,\n override: bool = False,\n guild: Optional[Snowflake] = MISSING,\n guilds: Sequence[Snowflake] = MISSING,\n ) -> None:\n \"\"\"|coro|\n\n Adds a \"cog\" to the bot.\n\n A cog is a class that has its own event listeners and commands.\n\n If the cog is a :class:`.app_commands.Group` then it is added to\n the bot's :class:`~discord.app_commands.CommandTree` as well.\n\n .. note::\n\n Exceptions raised inside a :class:`.Cog`'s :meth:`~.Cog.cog_load` method will be\n propagated to the caller.\n\n .. versionchanged:: 2.0\n\n :exc:`.ClientException` is raised when a cog with the same name\n is already loaded.\n\n .. versionchanged:: 2.0\n\n ``cog`` parameter is now positional-only.\n\n .. versionchanged:: 2.0\n\n This method is now a :term:`coroutine`.\n\n Parameters\n -----------\n cog: :class:`.Cog`\n The cog to register to the bot.\n override: :class:`bool`\n If a previously loaded cog with the same name should be ejected\n instead of raising an error.\n\n .. versionadded:: 2.0\n guild: Optional[:class:`~discord.abc.Snowflake`]\n If the cog is an application command group, then this would be the\n guild where the cog group would be added to. If not given then\n it becomes a global command instead.\n\n .. versionadded:: 2.0\n guilds: List[:class:`~discord.abc.Snowflake`]\n If the cog is an application command group, then this would be the\n guilds where the cog group would be added to. If not given then\n it becomes a global command instead. Cannot be mixed with\n ``guild``.\n\n .. versionadded:: 2.0\n\n Raises\n -------\n TypeError\n The cog does not inherit from :class:`.Cog`.\n CommandError\n An error happened during loading.\n ClientException\n A cog with the same name is already loaded.\n \"\"\"\n\n if not isinstance(cog, Cog):\n raise TypeError('cogs must derive from Cog')\n\n cog_name = cog.__cog_name__\n existing = self.__cogs.get(cog_name)\n\n if existing is not None:\n if not override:\n raise discord.ClientException(f'Cog named {cog_name!r} already loaded')\n await self.remove_cog(cog_name, guild=guild, guilds=guilds)\n\n if cog.__cog_app_commands_group__:\n self.__tree.add_command(cog.__cog_app_commands_group__, override=override, guild=guild, guilds=guilds)\n\n cog = await cog._inject(self, override=override, guild=guild, guilds=guilds)\n self.__cogs[cog_name] = cog\n\n def get_cog(self, name: str, /) -> Optional[Cog]:\n \"\"\"Gets the cog instance requested.\n\n If the cog is not found, ``None`` is returned instead.\n\n .. versionchanged:: 2.0\n\n ``name`` parameter is now positional-only.\n\n Parameters\n -----------\n name: :class:`str`\n The name of the cog you are requesting.\n This is equivalent to the name passed via keyword\n argument in class creation or the class name if unspecified.\n\n Returns\n --------\n Optional[:class:`Cog`]\n The cog that was requested. If not found, returns ``None``.\n \"\"\"\n return self.__cogs.get(name)\n\n async def remove_cog(\n self,\n name: str,\n /,\n *,\n guild: Optional[Snowflake] = MISSING,\n guilds: Sequence[Snowflake] = MISSING,\n ) -> Optional[Cog]:\n \"\"\"|coro|\n\n Removes a cog from the bot and returns it.\n\n All registered commands and event listeners that the\n cog has registered will be removed as well.\n\n If no cog is found then this method has no effect.\n\n .. versionchanged:: 2.0\n\n ``name`` parameter is now positional-only.\n\n .. versionchanged:: 2.0\n\n This method is now a :term:`coroutine`.\n\n Parameters\n -----------\n name: :class:`str`\n The name of the cog to remove.\n guild: Optional[:class:`~discord.abc.Snowflake`]\n If the cog is an application command group, then this would be the\n guild where the cog group would be removed from. If not given then\n a global command is removed instead instead.\n\n .. versionadded:: 2.0\n guilds: List[:class:`~discord.abc.Snowflake`]\n If the cog is an application command group, then this would be the\n guilds where the cog group would be removed from. If not given then\n a global command is removed instead instead. Cannot be mixed with\n ``guild``.\n\n .. versionadded:: 2.0\n\n Returns\n -------\n Optional[:class:`.Cog`]\n The cog that was removed. ``None`` if not found.\n \"\"\"\n\n cog = self.__cogs.pop(name, None)\n if cog is None:\n return\n\n help_command = self._help_command\n if help_command and help_command.cog is cog:\n help_command.cog = None\n\n guild_ids = _retrieve_guild_ids(cog, guild, guilds)\n if cog.__cog_app_commands_group__:\n if guild_ids is None:\n self.__tree.remove_command(name)\n else:\n for guild_id in guild_ids:\n self.__tree.remove_command(name, guild=discord.Object(guild_id))\n\n await cog._eject(self, guild_ids=guild_ids)\n\n return cog\n\n @property\n def cogs(self) -> Mapping[str, Cog]:\n \"\"\"Mapping[:class:`str`, :class:`Cog`]: A read-only mapping of cog name to cog.\"\"\"\n return types.MappingProxyType(self.__cogs)\n\n # extensions\n\n async def _remove_module_references(self, name: str) -> None:\n # find all references to the module\n # remove the cogs registered from the module\n for cogname, cog in self.__cogs.copy().items():\n if _is_submodule(name, cog.__module__):\n await self.remove_cog(cogname)\n\n # remove all the commands from the module\n for cmd in self.all_commands.copy().values():\n if cmd.module is not None and _is_submodule(name, cmd.module):\n if isinstance(cmd, GroupMixin):\n cmd.recursively_remove_all_commands()\n self.remove_command(cmd.name)\n\n # remove all the listeners from the module\n for event_list in self.extra_events.copy().values():\n remove = []\n for index, event in enumerate(event_list):\n if event.__module__ is not None and _is_submodule(name, event.__module__):\n remove.append(index)\n\n for index in reversed(remove):\n del event_list[index]\n\n # remove all relevant application commands from the tree\n self.__tree._remove_with_module(name)\n\n async def _call_module_finalizers(self, lib: types.ModuleType, key: str) -> None:\n try:\n func = getattr(lib, 'teardown')\n except AttributeError:\n pass\n else:\n try:\n await func(self)\n except Exception:\n pass\n finally:\n self.__extensions.pop(key, None)\n sys.modules.pop(key, None)\n name = lib.__name__\n for module in list(sys.modules.keys()):\n if _is_submodule(name, module):\n del sys.modules[module]\n\n async def _load_from_module_spec(self, spec: importlib.machinery.ModuleSpec, key: str) -> None:\n # precondition: key not in self.__extensions\n lib = importlib.util.module_from_spec(spec)\n sys.modules[key] = lib\n try:\n spec.loader.exec_module(lib) # type: ignore\n except Exception as e:\n del sys.modules[key]\n raise errors.ExtensionFailed(key, e) from e\n\n try:\n setup = getattr(lib, 'setup')\n except AttributeError:\n del sys.modules[key]\n raise errors.NoEntryPointError(key)\n\n try:\n await setup(self)\n except Exception as e:\n del sys.modules[key]\n await self._remove_module_references(lib.__name__)\n await self._call_module_finalizers(lib, key)\n raise errors.ExtensionFailed(key, e) from e\n else:\n self.__extensions[key] = lib\n\n def _resolve_name(self, name: str, package: Optional[str]) -> str:\n try:\n return importlib.util.resolve_name(name, package)\n except ImportError:\n raise errors.ExtensionNotFound(name)\n\n async def load_extension(self, name: str, *, package: Optional[str] = None) -> None:\n \"\"\"|coro|\n\n Loads an extension.\n\n An extension is a python module that contains commands, cogs, or\n listeners.\n\n An extension must have a global function, ``setup`` defined as\n the entry point on what to do when the extension is loaded. This entry\n point must have a single argument, the ``bot``.\n\n .. versionchanged:: 2.0\n\n This method is now a :term:`coroutine`.\n\n Parameters\n ------------\n name: :class:`str`\n The extension name to load. It must be dot separated like\n regular Python imports if accessing a sub-module. e.g.\n ``foo.test`` if you want to import ``foo/test.py``.\n package: Optional[:class:`str`]\n The package name to resolve relative imports with.\n This is required when loading an extension using a relative path, e.g ``.foo.test``.\n Defaults to ``None``.\n\n .. versionadded:: 1.7\n\n Raises\n --------\n ExtensionNotFound\n The extension could not be imported.\n This is also raised if the name of the extension could not\n be resolved using the provided ``package`` parameter.\n ExtensionAlreadyLoaded\n The extension is already loaded.\n NoEntryPointError\n The extension does not have a setup function.\n ExtensionFailed\n The extension or its setup function had an execution error.\n \"\"\"\n\n name = self._resolve_name(name, package)\n if name in self.__extensions:\n raise errors.ExtensionAlreadyLoaded(name)\n\n spec = importlib.util.find_spec(name)\n if spec is None:\n raise errors.ExtensionNotFound(name)\n\n await self._load_from_module_spec(spec, name)\n\n async def unload_extension(self, name: str, *, package: Optional[str] = None) -> None:\n \"\"\"|coro|\n\n Unloads an extension.\n\n When the extension is unloaded, all commands, listeners, and cogs are\n removed from the bot and the module is un-imported.\n\n The extension can provide an optional global function, ``teardown``,\n to do miscellaneous clean-up if necessary. This function takes a single\n parameter, the ``bot``, similar to ``setup`` from\n :meth:`~.Bot.load_extension`.\n\n .. versionchanged:: 2.0\n\n This method is now a :term:`coroutine`.\n\n Parameters\n ------------\n name: :class:`str`\n The extension name to unload. It must be dot separated like\n regular Python imports if accessing a sub-module. e.g.\n ``foo.test`` if you want to import ``foo/test.py``.\n package: Optional[:class:`str`]\n The package name to resolve relative imports with.\n This is required when unloading an extension using a relative path, e.g ``.foo.test``.\n Defaults to ``None``.\n\n .. versionadded:: 1.7\n\n Raises\n -------\n ExtensionNotFound\n The name of the extension could not\n be resolved using the provided ``package`` parameter.\n ExtensionNotLoaded\n The extension was not loaded.\n \"\"\"\n\n name = self._resolve_name(name, package)\n lib = self.__extensions.get(name)\n if lib is None:\n raise errors.ExtensionNotLoaded(name)\n\n await self._remove_module_references(lib.__name__)\n await self._call_module_finalizers(lib, name)\n\n async def reload_extension(self, name: str, *, package: Optional[str] = None) -> None:\n \"\"\"|coro|\n\n Atomically reloads an extension.\n\n This replaces the extension with the same extension, only refreshed. This is\n equivalent to a :meth:`unload_extension` followed by a :meth:`load_extension`\n except done in an atomic way. That is, if an operation fails mid-reload then\n the bot will roll-back to the prior working state.\n\n Parameters\n ------------\n name: :class:`str`\n The extension name to reload. It must be dot separated like\n regular Python imports if accessing a sub-module. e.g.\n ``foo.test`` if you want to import ``foo/test.py``.\n package: Optional[:class:`str`]\n The package name to resolve relative imports with.\n This is required when reloading an extension using a relative path, e.g ``.foo.test``.\n Defaults to ``None``.\n\n .. versionadded:: 1.7\n\n Raises\n -------\n ExtensionNotLoaded\n The extension was not loaded.\n ExtensionNotFound\n The extension could not be imported.\n This is also raised if the name of the extension could not\n be resolved using the provided ``package`` parameter.\n NoEntryPointError\n The extension does not have a setup function.\n ExtensionFailed\n The extension setup function had an execution error.\n \"\"\"\n\n name = self._resolve_name(name, package)\n lib = self.__extensions.get(name)\n if lib is None:\n raise errors.ExtensionNotLoaded(name)\n\n # get the previous module states from sys modules\n # fmt: off\n modules = {\n name: module\n for name, module in sys.modules.items()\n if _is_submodule(lib.__name__, name)\n }\n # fmt: on\n\n try:\n # Unload and then load the module...\n await self._remove_module_references(lib.__name__)\n await self._call_module_finalizers(lib, name)\n await self.load_extension(name)\n except Exception:\n # if the load failed, the remnants should have been\n # cleaned from the load_extension function call\n # so let's load it from our old compiled library.\n await lib.setup(self)\n self.__extensions[name] = lib\n\n # revert sys.modules back to normal and raise back to caller\n sys.modules.update(modules)\n raise\n\n @property\n def extensions(self) -> Mapping[str, types.ModuleType]:\n \"\"\"Mapping[:class:`str`, :class:`py:types.ModuleType`]: A read-only mapping of extension name to extension.\"\"\"\n return types.MappingProxyType(self.__extensions)\n\n # help command stuff\n\n @property\n def help_command(self) -> Optional[HelpCommand]:\n return self._help_command\n\n @help_command.setter\n def help_command(self, value: Optional[HelpCommand]) -> None:\n if value is not None:\n if not isinstance(value, HelpCommand):\n raise TypeError('help_command must be a subclass of HelpCommand')\n if self._help_command is not None:\n self._help_command._remove_from_bot(self)\n self._help_command = value\n value._add_to_bot(self)\n elif self._help_command is not None:\n self._help_command._remove_from_bot(self)\n self._help_command = None\n else:\n self._help_command = None\n\n # application command interop\n\n # As mentioned above, this is a mixin so the Self type hint fails here.\n # However, since the only classes that can use this are subclasses of Client\n # anyway, then this is sound.\n @property\n def tree(self) -> app_commands.CommandTree[Self]: # type: ignore\n \"\"\":class:`~discord.app_commands.CommandTree`: The command tree responsible for handling the application commands\n in this bot.\n\n .. versionadded:: 2.0\n \"\"\"\n return self.__tree\n\n # command processing\n\n async def get_prefix(self, message: Message, /) -> Union[List[str], str]:\n \"\"\"|coro|\n\n Retrieves the prefix the bot is listening to\n with the message as a context.\n\n .. versionchanged:: 2.0\n\n ``message`` parameter is now positional-only.\n\n Parameters\n -----------\n message: :class:`discord.Message`\n The message context to get the prefix of.\n\n Returns\n --------\n Union[List[:class:`str`], :class:`str`]\n A list of prefixes or a single prefix that the bot is\n listening for.\n \"\"\"\n prefix = ret = self.command_prefix\n\n if callable(prefix):\n # self will be a Bot or AutoShardedBot\n ret = await discord.utils.maybe_coroutine(prefix, self, message) # type: ignore\n\n if not isinstance(ret, str):\n try:\n ret = list(ret) # type: ignore\n except TypeError:\n # It's possible that a generator raised this exception. Don't\n # replace it with our own error if that's the case.\n if isinstance(ret, collections.abc.Iterable):\n raise\n\n raise TypeError(\n \"command_prefix must be plain string, iterable of strings, or callable \"\n f\"returning either of these, not {ret.__class__.__name__}\"\n )\n\n return ret\n\n @overload\n async def get_context(\n self,\n origin: Union[Message, Interaction],\n /,\n ) -> Context[Self]: # type: ignore\n ...\n\n @overload\n async def get_context(\n self,\n origin: Union[Message, Interaction],\n /,\n *,\n cls: Type[ContextT],\n ) -> ContextT:\n ...\n\n async def get_context(\n self,\n origin: Union[Message, Interaction],\n /,\n *,\n cls: Type[ContextT] = MISSING,\n ) -> Any:\n r\"\"\"|coro|\n\n Returns the invocation context from the message or interaction.\n\n This is a more low-level counter-part for :meth:`.process_commands`\n to allow users more fine grained control over the processing.\n\n The returned context is not guaranteed to be a valid invocation\n context, :attr:`.Context.valid` must be checked to make sure it is.\n If the context is not valid then it is not a valid candidate to be\n invoked under :meth:`~.Bot.invoke`.\n\n .. note::\n\n In order for the custom context to be used inside an interaction-based\n context (such as :class:`HybridCommand`) then this method must be\n overridden to return that class.\n\n .. versionchanged:: 2.0\n\n ``message`` parameter is now positional-only and renamed to ``origin``.\n\n Parameters\n -----------\n origin: Union[:class:`discord.Message`, :class:`discord.Interaction`]\n The message or interaction to get the invocation context from.\n cls\n The factory class that will be used to create the context.\n By default, this is :class:`.Context`. Should a custom\n class be provided, it must be similar enough to :class:`.Context`\\'s\n interface.\n\n Returns\n --------\n :class:`.Context`\n The invocation context. The type of this can change via the\n ``cls`` parameter.\n \"\"\"\n if cls is MISSING:\n cls = Context # type: ignore\n\n if isinstance(origin, discord.Interaction):\n return await cls.from_interaction(origin)\n\n view = StringView(origin.content)\n ctx = cls(prefix=None, view=view, bot=self, message=origin)\n\n if origin.author.id == self.user.id: # type: ignore\n return ctx\n\n prefix = await self.get_prefix(origin)\n invoked_prefix = prefix\n\n if isinstance(prefix, str):\n if not view.skip_string(prefix):\n return ctx\n else:\n try:\n # if the context class' __init__ consumes something from the view this\n # will be wrong. That seems unreasonable though.\n if origin.content.startswith(tuple(prefix)):\n invoked_prefix = discord.utils.find(view.skip_string, prefix)\n else:\n return ctx\n\n except TypeError:\n if not isinstance(prefix, list):\n raise TypeError(\n \"get_prefix must return either a string or a list of string, \" f\"not {prefix.__class__.__name__}\"\n )\n\n # It's possible a bad command_prefix got us here.\n for value in prefix:\n if not isinstance(value, str):\n raise TypeError(\n \"Iterable command_prefix or list returned from get_prefix must \"\n f\"contain only strings, not {value.__class__.__name__}\"\n )\n\n # Getting here shouldn't happen\n raise\n\n if self.strip_after_prefix:\n view.skip_ws()\n\n invoker = view.get_word()\n ctx.invoked_with = invoker\n # type-checker fails to narrow invoked_prefix type.\n ctx.prefix = invoked_prefix # type: ignore\n ctx.command = self.all_commands.get(invoker)\n return ctx\n\n async def invoke(self, ctx: Context[BotT], /) -> None:\n \"\"\"|coro|\n\n Invokes the command given under the invocation context and\n handles all the internal event dispatch mechanisms.\n\n .. versionchanged:: 2.0\n\n ``ctx`` parameter is now positional-only.\n\n Parameters\n -----------\n ctx: :class:`.Context`\n The invocation context to invoke.\n \"\"\"\n if ctx.command is not None:\n self.dispatch('command', ctx)\n try:\n if await self.can_run(ctx, call_once=True):\n await ctx.command.invoke(ctx)\n else:\n raise errors.CheckFailure('The global check once functions failed.')\n except errors.CommandError as exc:\n await ctx.command.dispatch_error(ctx, exc)\n else:\n self.dispatch('command_completion', ctx)\n elif ctx.invoked_with:\n exc = errors.CommandNotFound(f'Command \"{ctx.invoked_with}\" is not found')\n self.dispatch('command_error', ctx, exc)\n\n async def process_commands(self, message: Message, /) -> None:\n \"\"\"|coro|\n\n This function processes the commands that have been registered\n to the bot and other groups. Without this coroutine, none of the\n commands will be triggered.\n\n By default, this coroutine is called inside the :func:`.on_message`\n event. If you choose to override the :func:`.on_message` event, then\n you should invoke this coroutine as well.\n\n This is built using other low level tools, and is equivalent to a\n call to :meth:`~.Bot.get_context` followed by a call to :meth:`~.Bot.invoke`.\n\n This also checks if the message's author is a bot and doesn't\n call :meth:`~.Bot.get_context` or :meth:`~.Bot.invoke` if so.\n\n .. versionchanged:: 2.0\n\n ``message`` parameter is now positional-only.\n\n Parameters\n -----------\n message: :class:`discord.Message`\n The message to process commands for.\n \"\"\"\n if message.author.bot:\n return\n\n ctx = await self.get_context(message)\n # the type of the invocation context's bot attribute will be correct\n await self.invoke(ctx) # type: ignore\n\n async def on_message(self, message: Message, /) -> None:\n await self.process_commands(message)\n\n\nclass Bot(BotBase, discord.Client):\n \"\"\"Represents a Discord bot.\n\n This class is a subclass of :class:`discord.Client` and as a result\n anything that you can do with a :class:`discord.Client` you can do with\n this bot.\n\n This class also subclasses :class:`.GroupMixin` to provide the functionality\n to manage commands.\n\n Unlike :class:`discord.Client`, this class does not require manually setting\n a :class:`~discord.app_commands.CommandTree` and is automatically set upon\n instantiating the class.\n\n .. container:: operations\n\n .. describe:: async with x\n\n Asynchronously initialises the bot and automatically cleans up.\n\n .. versionadded:: 2.0\n\n Attributes\n -----------\n command_prefix\n The command prefix is what the message content must contain initially\n to have a command invoked. This prefix could either be a string to\n indicate what the prefix should be, or a callable that takes in the bot\n as its first parameter and :class:`discord.Message` as its second\n parameter and returns the prefix. This is to facilitate \"dynamic\"\n command prefixes. This callable can be either a regular function or\n a coroutine.\n\n An empty string as the prefix always matches, enabling prefix-less\n command invocation. While this may be useful in DMs it should be avoided\n in servers, as it's likely to cause performance issues and unintended\n command invocations.\n\n The command prefix could also be an iterable of strings indicating that\n multiple checks for the prefix should be used and the first one to\n match will be the invocation prefix. You can get this prefix via\n :attr:`.Context.prefix`.\n\n .. note::\n\n When passing multiple prefixes be careful to not pass a prefix\n that matches a longer prefix occurring later in the sequence. For\n example, if the command prefix is ``('!', '!?')`` the ``'!?'``\n prefix will never be matched to any message as the previous one\n matches messages starting with ``!?``. This is especially important\n when passing an empty string, it should always be last as no prefix\n after it will be matched.\n case_insensitive: :class:`bool`\n Whether the commands should be case insensitive. Defaults to ``False``. This\n attribute does not carry over to groups. You must set it to every group if\n you require group commands to be case insensitive as well.\n description: :class:`str`\n The content prefixed into the default help message.\n help_command: Optional[:class:`.HelpCommand`]\n The help command implementation to use. This can be dynamically\n set at runtime. To remove the help command pass ``None``. For more\n information on implementing a help command, see :ref:`ext_commands_help_command`.\n owner_id: Optional[:class:`int`]\n The user ID that owns the bot. If this is not set and is then queried via\n :meth:`.is_owner` then it is fetched automatically using\n :meth:`~.Bot.application_info`.\n owner_ids: Optional[Collection[:class:`int`]]\n The user IDs that owns the bot. This is similar to :attr:`owner_id`.\n If this is not set and the application is team based, then it is\n fetched automatically using :meth:`~.Bot.application_info`.\n For performance reasons it is recommended to use a :class:`set`\n for the collection. You cannot set both ``owner_id`` and ``owner_ids``.\n\n .. versionadded:: 1.3\n strip_after_prefix: :class:`bool`\n Whether to strip whitespace characters after encountering the command\n prefix. This allows for ``! hello`` and ``!hello`` to both work if\n the ``command_prefix`` is set to ``!``. Defaults to ``False``.\n\n .. versionadded:: 1.7\n tree_cls: Type[:class:`~discord.app_commands.CommandTree`]\n The type of application command tree to use. Defaults to :class:`~discord.app_commands.CommandTree`.\n\n .. versionadded:: 2.0\n allowed_contexts: :class:`~discord.app_commands.AppCommandContext`\n The default allowed contexts that applies to all application commands\n in the application command tree.\n\n Note that you can override this on a per command basis.\n\n .. versionadded:: 2.4\n allowed_installs: :class:`~discord.app_commands.AppInstallationType`\n The default allowed install locations that apply to all application commands\n in the application command tree.\n\n Note that you can override this on a per command basis.\n\n .. versionadded:: 2.4\n \"\"\"\n\n pass\n\n\nclass AutoShardedBot(BotBase, discord.AutoShardedClient):\n \"\"\"This is similar to :class:`.Bot` except that it is inherited from\n :class:`discord.AutoShardedClient` instead.\n\n .. container:: operations\n\n .. describe:: async with x\n\n Asynchronously initialises the bot and automatically cleans.\n\n .. versionadded:: 2.0\n \"\"\"\n\n pass\n" }, { "path": "discord/ext/commands/cog.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\nfrom __future__ import annotations\n\nimport inspect\nimport discord\nimport logging\nfrom discord import app_commands\nfrom discord.utils import maybe_coroutine, _to_kebab_case\n\nfrom typing import (\n Any,\n Callable,\n ClassVar,\n Coroutine,\n Dict,\n Generator,\n Iterable,\n List,\n Optional,\n TYPE_CHECKING,\n Sequence,\n Tuple,\n TypeVar,\n Union,\n)\n\nfrom ._types import _BaseCommand, BotT\n\nif TYPE_CHECKING:\n from typing_extensions import Self\n from discord.abc import Snowflake\n from discord._types import ClientT\n\n from .bot import BotBase\n from .context import Context\n from .core import Command\n\n__all__ = (\n 'CogMeta',\n 'Cog',\n 'GroupCog',\n)\n\nFuncT = TypeVar('FuncT', bound=Callable[..., Any])\n\nMISSING: Any = discord.utils.MISSING\n_log = logging.getLogger(__name__)\n\n\nclass CogMeta(type):\n \"\"\"A metaclass for defining a cog.\n\n Note that you should probably not use this directly. It is exposed\n purely for documentation purposes along with making custom metaclasses to intermix\n with other metaclasses such as the :class:`abc.ABCMeta` metaclass.\n\n For example, to create an abstract cog mixin class, the following would be done.\n\n .. code-block:: python3\n\n import abc\n\n class CogABCMeta(commands.CogMeta, abc.ABCMeta):\n pass\n\n class SomeMixin(metaclass=abc.ABCMeta):\n pass\n\n class SomeCogMixin(SomeMixin, commands.Cog, metaclass=CogABCMeta):\n pass\n\n .. note::\n\n When passing an attribute of a metaclass that is documented below, note\n that you must pass it as a keyword-only argument to the class creation\n like the following example:\n\n .. code-block:: python3\n\n class MyCog(commands.Cog, name='My Cog'):\n pass\n\n Attributes\n -----------\n name: :class:`str`\n The cog name. By default, it is the name of the class with no modification.\n description: :class:`str`\n The cog description. By default, it is the cleaned docstring of the class.\n\n .. versionadded:: 1.6\n\n command_attrs: :class:`dict`\n A list of attributes to apply to every command inside this cog. The dictionary\n is passed into the :class:`Command` options at ``__init__``.\n If you specify attributes inside the command attribute in the class, it will\n override the one specified inside this attribute. For example:\n\n .. code-block:: python3\n\n class MyCog(commands.Cog, command_attrs=dict(hidden=True)):\n @commands.command()\n async def foo(self, ctx):\n pass # hidden -> True\n\n @commands.command(hidden=False)\n async def bar(self, ctx):\n pass # hidden -> False\n\n group_name: Union[:class:`str`, :class:`~discord.app_commands.locale_str`]\n The group name of a cog. This is only applicable for :class:`GroupCog` instances.\n By default, it's the same value as :attr:`name`.\n\n .. versionadded:: 2.0\n group_description: Union[:class:`str`, :class:`~discord.app_commands.locale_str`]\n The group description of a cog. This is only applicable for :class:`GroupCog` instances.\n By default, it's the same value as :attr:`description`.\n\n .. versionadded:: 2.0\n group_nsfw: :class:`bool`\n Whether the application command group is NSFW. This is only applicable for :class:`GroupCog` instances.\n By default, it's ``False``.\n\n .. versionadded:: 2.0\n group_auto_locale_strings: :class:`bool`\n If this is set to ``True``, then all translatable strings will implicitly\n be wrapped into :class:`~discord.app_commands.locale_str` rather\n than :class:`str`. Defaults to ``True``.\n\n .. versionadded:: 2.0\n group_extras: :class:`dict`\n A dictionary that can be used to store extraneous data.\n This is only applicable for :class:`GroupCog` instances.\n The library will not touch any values or keys within this dictionary.\n\n .. versionadded:: 2.1\n \"\"\"\n\n __cog_name__: str\n __cog_description__: str\n __cog_group_name__: Union[str, app_commands.locale_str]\n __cog_group_description__: Union[str, app_commands.locale_str]\n __cog_group_nsfw__: bool\n __cog_group_auto_locale_strings__: bool\n __cog_group_extras__: Dict[Any, Any]\n __cog_settings__: Dict[str, Any]\n __cog_commands__: List[Command[Any, ..., Any]]\n __cog_app_commands__: List[Union[app_commands.Group, app_commands.Command[Any, ..., Any]]]\n __cog_listeners__: List[Tuple[str, str]]\n\n def __new__(cls, *args: Any, **kwargs: Any) -> CogMeta:\n name, bases, attrs = args\n if any(issubclass(base, app_commands.Group) for base in bases):\n raise TypeError(\n 'Cannot inherit from app_commands.Group with commands.Cog, consider using commands.GroupCog instead'\n )\n\n # If name='...' is given but not group_name='...' then name='...' is used for both.\n # If neither is given then cog name is the class name but group name is kebab case\n try:\n cog_name = kwargs.pop('name')\n except KeyError:\n cog_name = name\n try:\n group_name = kwargs.pop('group_name')\n except KeyError:\n group_name = _to_kebab_case(name)\n else:\n group_name = kwargs.pop('group_name', cog_name)\n\n attrs['__cog_settings__'] = kwargs.pop('command_attrs', {})\n attrs['__cog_name__'] = cog_name\n attrs['__cog_group_name__'] = group_name\n attrs['__cog_group_nsfw__'] = kwargs.pop('group_nsfw', False)\n attrs['__cog_group_auto_locale_strings__'] = kwargs.pop('group_auto_locale_strings', True)\n attrs['__cog_group_extras__'] = kwargs.pop('group_extras', {})\n\n description = kwargs.pop('description', None)\n if description is None:\n description = inspect.cleandoc(attrs.get('__doc__', ''))\n\n attrs['__cog_description__'] = description\n attrs['__cog_group_description__'] = kwargs.pop('group_description', description or '\\u2026')\n\n commands = {}\n cog_app_commands = {}\n listeners = {}\n no_bot_cog = 'Commands or listeners must not start with cog_ or bot_ (in method {0.__name__}.{1})'\n\n new_cls = super().__new__(cls, name, bases, attrs, **kwargs)\n for base in reversed(new_cls.__mro__):\n for elem, value in base.__dict__.items():\n if elem in commands:\n del commands[elem]\n if elem in listeners:\n del listeners[elem]\n\n is_static_method = isinstance(value, staticmethod)\n if is_static_method:\n value = value.__func__\n if isinstance(value, _BaseCommand):\n if is_static_method:\n raise TypeError(f'Command in method {base}.{elem!r} must not be staticmethod.')\n if elem.startswith(('cog_', 'bot_')):\n raise TypeError(no_bot_cog.format(base, elem))\n commands[elem] = value\n elif isinstance(value, (app_commands.Group, app_commands.Command)) and value.parent is None:\n if is_static_method:\n raise TypeError(f'Command in method {base}.{elem!r} must not be staticmethod.')\n if elem.startswith(('cog_', 'bot_')):\n raise TypeError(no_bot_cog.format(base, elem))\n cog_app_commands[elem] = value\n elif inspect.iscoroutinefunction(value):\n try:\n getattr(value, '__cog_listener__')\n except AttributeError:\n continue\n else:\n if elem.startswith(('cog_', 'bot_')):\n raise TypeError(no_bot_cog.format(base, elem))\n listeners[elem] = value\n\n new_cls.__cog_commands__ = list(commands.values()) # this will be copied in Cog.__new__\n new_cls.__cog_app_commands__ = list(cog_app_commands.values())\n\n listeners_as_list = []\n for listener in listeners.values():\n for listener_name in listener.__cog_listener_names__:\n # I use __name__ instead of just storing the value so I can inject\n # the self attribute when the time comes to add them to the bot\n listeners_as_list.append((listener_name, listener.__name__))\n\n new_cls.__cog_listeners__ = listeners_as_list\n return new_cls\n\n def __init__(self, *args: Any, **kwargs: Any) -> None:\n super().__init__(*args)\n\n @classmethod\n def qualified_name(cls) -> str:\n return cls.__cog_name__\n\n\ndef _cog_special_method(func: FuncT) -> FuncT:\n func.__cog_special_method__ = None\n return func\n\n\nclass Cog(metaclass=CogMeta):\n \"\"\"The base class that all cogs must inherit from.\n\n A cog is a collection of commands, listeners, and optional state to\n help group commands together. More information on them can be found on\n the :ref:`ext_commands_cogs` page.\n\n When inheriting from this class, the options shown in :class:`CogMeta`\n are equally valid here.\n \"\"\"\n\n __cog_name__: str\n __cog_description__: str\n __cog_group_name__: Union[str, app_commands.locale_str]\n __cog_group_description__: Union[str, app_commands.locale_str]\n __cog_settings__: Dict[str, Any]\n __cog_commands__: List[Command[Self, ..., Any]]\n __cog_app_commands__: List[Union[app_commands.Group, app_commands.Command[Self, ..., Any]]]\n __cog_listeners__: List[Tuple[str, str]]\n __cog_is_app_commands_group__: ClassVar[bool] = False\n __cog_app_commands_group__: Optional[app_commands.Group]\n __discord_app_commands_error_handler__: Optional[\n Callable[[discord.Interaction, app_commands.AppCommandError], Coroutine[Any, Any, None]]\n ]\n\n def __new__(cls, *args: Any, **kwargs: Any) -> Self:\n # For issue 426, we need to store a copy of the command objects\n # since we modify them to inject `self` to them.\n # To do this, we need to interfere with the Cog creation process.\n self = super().__new__(cls)\n cmd_attrs = cls.__cog_settings__\n\n # Either update the command with the cog provided defaults or copy it.\n # r.e type ignore, type-checker complains about overriding a ClassVar\n self.__cog_commands__ = tuple(c._update_copy(cmd_attrs) for c in cls.__cog_commands__) # type: ignore\n\n lookup = {cmd.qualified_name: cmd for cmd in self.__cog_commands__}\n\n # Register the application commands\n children: List[Union[app_commands.Group, app_commands.Command[Self, ..., Any]]] = []\n app_command_refs: Dict[str, Union[app_commands.Group, app_commands.Command[Self, ..., Any]]] = {}\n\n if cls.__cog_is_app_commands_group__:\n group = app_commands.Group(\n name=cls.__cog_group_name__,\n description=cls.__cog_group_description__,\n nsfw=cls.__cog_group_nsfw__,\n auto_locale_strings=cls.__cog_group_auto_locale_strings__,\n parent=None,\n guild_ids=getattr(cls, '__discord_app_commands_default_guilds__', None),\n guild_only=getattr(cls, '__discord_app_commands_guild_only__', False),\n allowed_contexts=getattr(cls, '__discord_app_commands_contexts__', None),\n allowed_installs=getattr(cls, '__discord_app_commands_installation_types__', None),\n default_permissions=getattr(cls, '__discord_app_commands_default_permissions__', None),\n extras=cls.__cog_group_extras__,\n )\n else:\n group = None\n\n self.__cog_app_commands_group__ = group\n\n # Update the Command instances dynamically as well\n for command in self.__cog_commands__:\n setattr(self, command.callback.__name__, command)\n parent = command.parent\n if parent is not None:\n # Get the latest parent reference\n parent = lookup[parent.qualified_name] # type: ignore\n\n # Hybrid commands already deal with updating the reference\n # Due to the copy below, so we need to handle them specially\n if hasattr(parent, '__commands_is_hybrid__') and hasattr(command, '__commands_is_hybrid__'):\n current: Optional[Union[app_commands.Group, app_commands.Command[Self, ..., Any]]] = getattr(\n command, 'app_command', None\n )\n updated = app_command_refs.get(command.qualified_name)\n if current and updated:\n command.app_command = updated # type: ignore # Safe attribute access\n\n # Update our parent's reference to our self\n parent.remove_command(command.name) # type: ignore\n parent.add_command(command) # type: ignore\n\n if hasattr(command, '__commands_is_hybrid__') and parent is None:\n app_command: Optional[Union[app_commands.Group, app_commands.Command[Self, ..., Any]]] = getattr(\n command, 'app_command', None\n )\n if app_command:\n group_parent = self.__cog_app_commands_group__\n app_command = app_command._copy_with(parent=group_parent, binding=self)\n # The type checker does not see the app_command attribute even though it exists\n command.app_command = app_command # type: ignore\n\n # Update all the references to point to the new copy\n if isinstance(app_command, app_commands.Group):\n for child in app_command.walk_commands():\n app_command_refs[child.qualified_name] = child\n if hasattr(child, '__commands_is_hybrid_app_command__') and child.qualified_name in lookup:\n child.wrapped = lookup[child.qualified_name] # type: ignore\n\n if self.__cog_app_commands_group__:\n children.append(app_command)\n\n if Cog._get_overridden_method(self.cog_app_command_error) is not None:\n error_handler = self.cog_app_command_error\n else:\n error_handler = None\n\n self.__discord_app_commands_error_handler__ = error_handler\n\n for command in cls.__cog_app_commands__:\n copy = command._copy_with(parent=self.__cog_app_commands_group__, binding=self)\n\n # Update set bindings\n if copy._attr:\n setattr(self, copy._attr, copy)\n\n if isinstance(copy, app_commands.Group):\n copy.__discord_app_commands_error_handler__ = error_handler\n for command in copy._children.values():\n if isinstance(command, app_commands.Group):\n command.__discord_app_commands_error_handler__ = error_handler\n\n children.append(copy)\n\n self.__cog_app_commands__ = children\n if self.__cog_app_commands_group__:\n self.__cog_app_commands_group__.module = cls.__module__\n mapping = {cmd.name: cmd for cmd in children}\n if len(mapping) > 25:\n raise TypeError('maximum number of application command children exceeded')\n\n self.__cog_app_commands_group__._children = mapping\n\n return self\n\n def get_commands(self) -> List[Command[Self, ..., Any]]:\n r\"\"\"Returns the commands that are defined inside this cog.\n\n This does *not* include :class:`discord.app_commands.Command` or :class:`discord.app_commands.Group`\n instances.\n\n Returns\n --------\n List[:class:`.Command`]\n A :class:`list` of :class:`.Command`\\s that are\n defined inside this cog, not including subcommands.\n \"\"\"\n return [c for c in self.__cog_commands__ if c.parent is None]\n\n def get_app_commands(self) -> List[Union[app_commands.Command[Self, ..., Any], app_commands.Group]]:\n r\"\"\"Returns the app commands that are defined inside this cog.\n\n Returns\n --------\n List[Union[:class:`discord.app_commands.Command`, :class:`discord.app_commands.Group`]]\n A :class:`list` of :class:`discord.app_commands.Command`\\s and :class:`discord.app_commands.Group`\\s that are\n defined inside this cog, not including subcommands.\n \"\"\"\n return [c for c in self.__cog_app_commands__ if c.parent is None]\n\n @property\n def qualified_name(self) -> str:\n \"\"\":class:`str`: Returns the cog's specified name, not the class name.\"\"\"\n return self.__cog_name__\n\n @property\n def description(self) -> str:\n \"\"\":class:`str`: Returns the cog's description, typically the cleaned docstring.\"\"\"\n return self.__cog_description__\n\n @description.setter\n def description(self, description: str) -> None:\n self.__cog_description__ = description\n\n def walk_commands(self) -> Generator[Command[Self, ..., Any], None, None]:\n \"\"\"An iterator that recursively walks through this cog's commands and subcommands.\n\n Yields\n ------\n Union[:class:`.Command`, :class:`.Group`]\n A command or group from the cog.\n \"\"\"\n from .core import GroupMixin\n\n for command in self.__cog_commands__:\n if command.parent is None:\n yield command\n if isinstance(command, GroupMixin):\n yield from command.walk_commands()\n\n def walk_app_commands(self) -> Generator[Union[app_commands.Command[Self, ..., Any], app_commands.Group], None, None]:\n \"\"\"An iterator that recursively walks through this cog's app commands and subcommands.\n\n Yields\n ------\n Union[:class:`discord.app_commands.Command`, :class:`discord.app_commands.Group`]\n An app command or group from the cog.\n \"\"\"\n for command in self.__cog_app_commands__:\n yield command\n if isinstance(command, app_commands.Group):\n yield from command.walk_commands()\n\n @property\n def app_command(self) -> Optional[app_commands.Group]:\n \"\"\"Optional[:class:`discord.app_commands.Group`]: Returns the associated group with this cog.\n\n This is only available if inheriting from :class:`GroupCog`.\n \"\"\"\n return self.__cog_app_commands_group__\n\n def get_listeners(self) -> List[Tuple[str, Callable[..., Any]]]:\n \"\"\"Returns a :class:`list` of (name, function) listener pairs that are defined in this cog.\n\n Returns\n --------\n List[Tuple[:class:`str`, :ref:`coroutine `]]\n The listeners defined in this cog.\n \"\"\"\n return [(name, getattr(self, method_name)) for name, method_name in self.__cog_listeners__]\n\n @classmethod\n def _get_overridden_method(cls, method: FuncT) -> Optional[FuncT]:\n \"\"\"Return None if the method is not overridden. Otherwise returns the overridden method.\"\"\"\n return getattr(method.__func__, '__cog_special_method__', method)\n\n @classmethod\n def listener(cls, name: str = MISSING) -> Callable[[FuncT], FuncT]:\n \"\"\"A decorator that marks a function as a listener.\n\n This is the cog equivalent of :meth:`.Bot.listen`.\n\n Parameters\n ------------\n name: :class:`str`\n The name of the event being listened to. If not provided, it\n defaults to the function's name.\n\n Raises\n --------\n TypeError\n The function is not a coroutine function or a string was not passed as\n the name.\n \"\"\"\n\n if name is not MISSING and not isinstance(name, str):\n raise TypeError(f'Cog.listener expected str but received {name.__class__.__name__} instead.')\n\n def decorator(func: FuncT) -> FuncT:\n actual = func\n if isinstance(actual, staticmethod):\n actual = actual.__func__\n if not inspect.iscoroutinefunction(actual):\n raise TypeError('Listener function must be a coroutine function.')\n actual.__cog_listener__ = True\n to_assign = name or actual.__name__\n try:\n actual.__cog_listener_names__.append(to_assign)\n except AttributeError:\n actual.__cog_listener_names__ = [to_assign]\n # we have to return `func` instead of `actual` because\n # we need the type to be `staticmethod` for the metaclass\n # to pick it up but the metaclass unfurls the function and\n # thus the assignments need to be on the actual function\n return func\n\n return decorator\n\n def has_error_handler(self) -> bool:\n \"\"\":class:`bool`: Checks whether the cog has an error handler.\n\n .. versionadded:: 1.7\n \"\"\"\n return not hasattr(self.cog_command_error.__func__, '__cog_special_method__')\n\n def has_app_command_error_handler(self) -> bool:\n \"\"\":class:`bool`: Checks whether the cog has an app error handler.\n\n .. versionadded:: 2.1\n \"\"\"\n return not hasattr(self.cog_app_command_error.__func__, '__cog_special_method__')\n\n @_cog_special_method\n async def cog_load(self) -> None:\n \"\"\"|maybecoro|\n\n A special method that is called when the cog gets loaded.\n\n Subclasses must replace this if they want special asynchronous loading behaviour.\n Note that the ``__init__`` special method does not allow asynchronous code to run\n inside it, thus this is helpful for setting up code that needs to be asynchronous.\n\n .. versionadded:: 2.0\n \"\"\"\n pass\n\n @_cog_special_method\n async def cog_unload(self) -> None:\n \"\"\"|maybecoro|\n\n A special method that is called when the cog gets removed.\n\n Subclasses must replace this if they want special unloading behaviour.\n\n Exceptions raised in this method are ignored during extension unloading.\n\n .. versionchanged:: 2.0\n\n This method can now be a :term:`coroutine`.\n \"\"\"\n pass\n\n @_cog_special_method\n def bot_check_once(self, ctx: Context[BotT]) -> bool:\n \"\"\"A special method that registers as a :meth:`.Bot.check_once`\n check.\n\n This function **can** be a coroutine and must take a sole parameter,\n ``ctx``, to represent the :class:`.Context`.\n \"\"\"\n return True\n\n @_cog_special_method\n def bot_check(self, ctx: Context[BotT]) -> bool:\n \"\"\"A special method that registers as a :meth:`.Bot.check`\n check.\n\n This function **can** be a coroutine and must take a sole parameter,\n ``ctx``, to represent the :class:`.Context`.\n \"\"\"\n return True\n\n @_cog_special_method\n def cog_check(self, ctx: Context[BotT]) -> bool:\n \"\"\"A special method that registers as a :func:`~discord.ext.commands.check`\n for every command and subcommand in this cog.\n\n This function **can** be a coroutine and must take a sole parameter,\n ``ctx``, to represent the :class:`.Context`.\n \"\"\"\n return True\n\n @_cog_special_method\n def interaction_check(self, interaction: discord.Interaction[ClientT], /) -> bool:\n \"\"\"A special method that registers as a :func:`discord.app_commands.check`\n for every app command and subcommand in this cog.\n\n This function **can** be a coroutine and must take a sole parameter,\n ``interaction``, to represent the :class:`~discord.Interaction`.\n\n .. versionadded:: 2.0\n \"\"\"\n return True\n\n @_cog_special_method\n async def cog_command_error(self, ctx: Context[BotT], error: Exception) -> None:\n \"\"\"|coro|\n\n A special method that is called whenever an error\n is dispatched inside this cog.\n\n This is similar to :func:`.on_command_error` except only applying\n to the commands inside this cog.\n\n This **must** be a coroutine.\n\n Parameters\n -----------\n ctx: :class:`.Context`\n The invocation context where the error happened.\n error: :class:`CommandError`\n The error that happened.\n \"\"\"\n pass\n\n @_cog_special_method\n async def cog_app_command_error(self, interaction: discord.Interaction, error: app_commands.AppCommandError) -> None:\n \"\"\"|coro|\n\n A special method that is called whenever an error within\n an application command is dispatched inside this cog.\n\n This is similar to :func:`discord.app_commands.CommandTree.on_error` except\n only applying to the application commands inside this cog.\n\n This **must** be a coroutine.\n\n Parameters\n -----------\n interaction: :class:`~discord.Interaction`\n The interaction that is being handled.\n error: :exc:`~discord.app_commands.AppCommandError`\n The exception that was raised.\n \"\"\"\n pass\n\n @_cog_special_method\n async def cog_before_invoke(self, ctx: Context[BotT]) -> None:\n \"\"\"|coro|\n\n A special method that acts as a cog local pre-invoke hook.\n\n This is similar to :meth:`.Command.before_invoke`.\n\n This **must** be a coroutine.\n\n Parameters\n -----------\n ctx: :class:`.Context`\n The invocation context.\n \"\"\"\n pass\n\n @_cog_special_method\n async def cog_after_invoke(self, ctx: Context[BotT]) -> None:\n \"\"\"|coro|\n\n A special method that acts as a cog local post-invoke hook.\n\n This is similar to :meth:`.Command.after_invoke`.\n\n This **must** be a coroutine.\n\n Parameters\n -----------\n ctx: :class:`.Context`\n The invocation context.\n \"\"\"\n pass\n\n async def _inject(self, bot: BotBase, override: bool, guild: Optional[Snowflake], guilds: Sequence[Snowflake]) -> Self:\n cls = self.__class__\n\n # we'll call this first so that errors can propagate without\n # having to worry about undoing anything\n await maybe_coroutine(self.cog_load)\n\n # realistically, the only thing that can cause loading errors\n # is essentially just the command loading, which raises if there are\n # duplicates. When this condition is met, we want to undo all what\n # we've added so far for some form of atomic loading.\n for index, command in enumerate(self.__cog_commands__):\n command.cog = self\n if command.parent is None:\n try:\n bot.add_command(command)\n except Exception as e:\n # undo our additions\n for to_undo in self.__cog_commands__[:index]:\n if to_undo.parent is None:\n bot.remove_command(to_undo.name)\n try:\n await maybe_coroutine(self.cog_unload)\n finally:\n raise e\n\n # check if we're overriding the default\n if cls.bot_check is not Cog.bot_check:\n bot.add_check(self.bot_check)\n\n if cls.bot_check_once is not Cog.bot_check_once:\n bot.add_check(self.bot_check_once, call_once=True)\n\n # while Bot.add_listener can raise if it's not a coroutine,\n # this precondition is already met by the listener decorator\n # already, thus this should never raise.\n # Outside of, memory errors and the like...\n for name, method_name in self.__cog_listeners__:\n bot.add_listener(getattr(self, method_name), name)\n\n # Only do this if these are \"top level\" commands\n if not self.__cog_app_commands_group__:\n for command in self.__cog_app_commands__:\n # This is already atomic\n bot.tree.add_command(command, override=override, guild=guild, guilds=guilds)\n\n return self\n\n async def _eject(self, bot: BotBase, guild_ids: Optional[Iterable[int]]) -> None:\n cls = self.__class__\n\n try:\n for command in self.__cog_commands__:\n if command.parent is None:\n bot.remove_command(command.name)\n\n if not self.__cog_app_commands_group__:\n for command in self.__cog_app_commands__:\n guild_ids = guild_ids or command._guild_ids\n if guild_ids is None:\n bot.tree.remove_command(command.name)\n else:\n for guild_id in guild_ids:\n bot.tree.remove_command(command.name, guild=discord.Object(id=guild_id))\n\n for name, method_name in self.__cog_listeners__:\n bot.remove_listener(getattr(self, method_name), name)\n\n if cls.bot_check is not Cog.bot_check:\n bot.remove_check(self.bot_check)\n\n if cls.bot_check_once is not Cog.bot_check_once:\n bot.remove_check(self.bot_check_once, call_once=True)\n finally:\n try:\n await maybe_coroutine(self.cog_unload)\n except Exception:\n _log.exception('Ignoring exception in cog unload for Cog %r (%r)', cls, self.qualified_name)\n\n\nclass GroupCog(Cog):\n \"\"\"Represents a cog that also doubles as a parent :class:`discord.app_commands.Group` for\n the application commands defined within it.\n\n This inherits from :class:`Cog` and the options in :class:`CogMeta` also apply to this.\n See the :class:`Cog` documentation for methods.\n\n Decorators such as :func:`~discord.app_commands.guild_only`, :func:`~discord.app_commands.guilds`,\n and :func:`~discord.app_commands.default_permissions` will apply to the group if used on top of the\n cog.\n\n Hybrid commands will also be added to the Group, giving the ability to categorize slash commands into\n groups, while keeping the prefix-style command as a root-level command.\n\n For example:\n\n .. code-block:: python3\n\n from discord import app_commands\n from discord.ext import commands\n\n @app_commands.guild_only()\n class MyCog(commands.GroupCog, group_name='my-cog'):\n pass\n\n .. versionadded:: 2.0\n \"\"\"\n\n __cog_is_app_commands_group__: ClassVar[bool] = True\n" }, { "path": "discord/ext/commands/context.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\nfrom __future__ import annotations\n\nimport re\nfrom typing import TYPE_CHECKING, Any, Dict, Generator, Generic, List, Optional, TypeVar, Union, Sequence, Type, overload\n\nimport discord.abc\nimport discord.utils\nfrom discord import Interaction, Message, Attachment, MessageType, User, PartialMessageable, Permissions, ChannelType, Thread\nfrom discord.context_managers import Typing\nfrom .view import StringView\n\nfrom ._types import BotT\n\nif TYPE_CHECKING:\n from typing_extensions import Self, ParamSpec, TypeGuard\n\n from discord.abc import MessageableChannel\n from discord.guild import Guild\n from discord.member import Member\n from discord.state import ConnectionState\n from discord.user import ClientUser\n from discord.voice_client import VoiceProtocol\n from discord.embeds import Embed\n from discord.file import File\n from discord.mentions import AllowedMentions\n from discord.sticker import GuildSticker, StickerItem\n from discord.message import MessageReference, PartialMessage\n from discord.ui import View\n from discord.types.interactions import ApplicationCommandInteractionData\n from discord.poll import Poll\n\n from .cog import Cog\n from .core import Command\n from .parameters import Parameter\n\n from types import TracebackType\n\n BE = TypeVar('BE', bound=BaseException)\n\n# fmt: off\n__all__ = (\n 'Context',\n)\n# fmt: on\n\nMISSING: Any = discord.utils.MISSING\n\n\nT = TypeVar('T')\nCogT = TypeVar('CogT', bound=\"Cog\")\n\nif TYPE_CHECKING:\n P = ParamSpec('P')\nelse:\n P = TypeVar('P')\n\n\ndef is_cog(obj: Any) -> TypeGuard[Cog]:\n return hasattr(obj, '__cog_commands__')\n\n\nclass DeferTyping:\n def __init__(self, ctx: Context[BotT], *, ephemeral: bool):\n self.ctx: Context[BotT] = ctx\n self.ephemeral: bool = ephemeral\n\n def __await__(self) -> Generator[Any, None, None]:\n return self.ctx.defer(ephemeral=self.ephemeral).__await__()\n\n async def __aenter__(self) -> None:\n await self.ctx.defer(ephemeral=self.ephemeral)\n\n async def __aexit__(\n self,\n exc_type: Optional[Type[BE]],\n exc: Optional[BE],\n traceback: Optional[TracebackType],\n ) -> None:\n pass\n\n\nclass Context(discord.abc.Messageable, Generic[BotT]):\n r\"\"\"Represents the context in which a command is being invoked under.\n\n This class contains a lot of meta data to help you understand more about\n the invocation context. This class is not created manually and is instead\n passed around to commands as the first parameter.\n\n This class implements the :class:`~discord.abc.Messageable` ABC.\n\n Attributes\n -----------\n message: :class:`.Message`\n The message that triggered the command being executed.\n\n .. note::\n\n In the case of an interaction based context, this message is \"synthetic\"\n and does not actually exist. Therefore, the ID on it is invalid similar\n to ephemeral messages.\n bot: :class:`.Bot`\n The bot that contains the command being executed.\n args: :class:`list`\n The list of transformed arguments that were passed into the command.\n If this is accessed during the :func:`.on_command_error` event\n then this list could be incomplete.\n kwargs: :class:`dict`\n A dictionary of transformed arguments that were passed into the command.\n Similar to :attr:`args`\\, if this is accessed in the\n :func:`.on_command_error` event then this dict could be incomplete.\n current_parameter: Optional[:class:`Parameter`]\n The parameter that is currently being inspected and converted.\n This is only of use for within converters.\n\n .. versionadded:: 2.0\n current_argument: Optional[:class:`str`]\n The argument string of the :attr:`current_parameter` that is currently being converted.\n This is only of use for within converters.\n\n .. versionadded:: 2.0\n interaction: Optional[:class:`~discord.Interaction`]\n The interaction associated with this context.\n\n .. versionadded:: 2.0\n prefix: Optional[:class:`str`]\n The prefix that was used to invoke the command. For interaction based contexts,\n this is ``/`` for slash commands and ``\\u200b`` for context menu commands.\n command: Optional[:class:`Command`]\n The command that is being invoked currently.\n invoked_with: Optional[:class:`str`]\n The command name that triggered this invocation. Useful for finding out\n which alias called the command.\n invoked_parents: List[:class:`str`]\n The command names of the parents that triggered this invocation. Useful for\n finding out which aliases called the command.\n\n For example in commands ``?a b c test``, the invoked parents are ``['a', 'b', 'c']``.\n\n .. versionadded:: 1.7\n\n invoked_subcommand: Optional[:class:`Command`]\n The subcommand that was invoked.\n If no valid subcommand was invoked then this is equal to ``None``.\n subcommand_passed: Optional[:class:`str`]\n The string that was attempted to call a subcommand. This does not have\n to point to a valid registered subcommand and could just point to a\n nonsense string. If nothing was passed to attempt a call to a\n subcommand then this is set to ``None``.\n command_failed: :class:`bool`\n A boolean that indicates if the command failed to be parsed, checked,\n or invoked.\n \"\"\"\n\n def __init__(\n self,\n *,\n message: Message,\n bot: BotT,\n view: StringView,\n args: List[Any] = MISSING,\n kwargs: Dict[str, Any] = MISSING,\n prefix: Optional[str] = None,\n command: Optional[Command[Any, ..., Any]] = None,\n invoked_with: Optional[str] = None,\n invoked_parents: List[str] = MISSING,\n invoked_subcommand: Optional[Command[Any, ..., Any]] = None,\n subcommand_passed: Optional[str] = None,\n command_failed: bool = False,\n current_parameter: Optional[Parameter] = None,\n current_argument: Optional[str] = None,\n interaction: Optional[Interaction[BotT]] = None,\n ):\n self.message: Message = message\n self.bot: BotT = bot\n self.args: List[Any] = args or []\n self.kwargs: Dict[str, Any] = kwargs or {}\n self.prefix: Optional[str] = prefix\n self.command: Optional[Command[Any, ..., Any]] = command\n self.view: StringView = view\n self.invoked_with: Optional[str] = invoked_with\n self.invoked_parents: List[str] = invoked_parents or []\n self.invoked_subcommand: Optional[Command[Any, ..., Any]] = invoked_subcommand\n self.subcommand_passed: Optional[str] = subcommand_passed\n self.command_failed: bool = command_failed\n self.current_parameter: Optional[Parameter] = current_parameter\n self.current_argument: Optional[str] = current_argument\n self.interaction: Optional[Interaction[BotT]] = interaction\n self._state: ConnectionState = self.message._state\n\n @classmethod\n async def from_interaction(cls, interaction: Interaction[BotT], /) -> Self:\n \"\"\"|coro|\n\n Creates a context from a :class:`discord.Interaction`. This only\n works on application command based interactions, such as slash commands\n or context menus.\n\n On slash command based interactions this creates a synthetic :class:`~discord.Message`\n that points to an ephemeral message that the command invoker has executed. This means\n that :attr:`Context.author` returns the member that invoked the command.\n\n In a message context menu based interaction, the :attr:`Context.message` attribute\n is the message that the command is being executed on. This means that :attr:`Context.author`\n returns the author of the message being targetted. To get the member that invoked\n the command then :attr:`discord.Interaction.user` should be used instead.\n\n .. versionadded:: 2.0\n\n Parameters\n -----------\n interaction: :class:`discord.Interaction`\n The interaction to create a context with.\n\n Raises\n -------\n ValueError\n The interaction does not have a valid command.\n TypeError\n The interaction client is not derived from :class:`Bot` or :class:`AutoShardedBot`.\n \"\"\"\n\n # Circular import\n from .bot import BotBase\n\n if not isinstance(interaction.client, BotBase):\n raise TypeError('Interaction client is not derived from commands.Bot or commands.AutoShardedBot')\n\n command = interaction.command\n if command is None:\n raise ValueError('interaction does not have command data')\n\n bot: BotT = interaction.client\n data: ApplicationCommandInteractionData = interaction.data # type: ignore\n if interaction.message is None:\n synthetic_payload = {\n 'id': interaction.id,\n 'reactions': [],\n 'embeds': [],\n 'mention_everyone': False,\n 'tts': False,\n 'pinned': False,\n 'edited_timestamp': None,\n 'type': MessageType.chat_input_command if data.get('type', 1) == 1 else MessageType.context_menu_command,\n 'flags': 64,\n 'content': '',\n 'mentions': [],\n 'mention_roles': [],\n 'attachments': [],\n }\n\n if interaction.channel_id is None:\n raise RuntimeError('interaction channel ID is null, this is probably a Discord bug')\n\n channel = interaction.channel or PartialMessageable(\n state=interaction._state, guild_id=interaction.guild_id, id=interaction.channel_id\n )\n message = Message(state=interaction._state, channel=channel, data=synthetic_payload) # type: ignore\n message.author = interaction.user\n message.attachments = [a for _, a in interaction.namespace if isinstance(a, Attachment)]\n else:\n message = interaction.message\n\n prefix = '/' if data.get('type', 1) == 1 else '\\u200b' # Mock the prefix\n ctx = cls(\n message=message,\n bot=bot,\n view=StringView(''),\n args=[],\n kwargs={},\n prefix=prefix,\n interaction=interaction,\n invoked_with=command.name,\n command=command, # type: ignore # this will be a hybrid command, technically\n )\n interaction._baton = ctx\n ctx.command_failed = interaction.command_failed\n return ctx\n\n async def invoke(self, command: Command[CogT, P, T], /, *args: P.args, **kwargs: P.kwargs) -> T:\n r\"\"\"|coro|\n\n Calls a command with the arguments given.\n\n This is useful if you want to just call the callback that a\n :class:`.Command` holds internally.\n\n .. note::\n\n This does not handle converters, checks, cooldowns, pre-invoke,\n or after-invoke hooks in any matter. It calls the internal callback\n directly as-if it was a regular function.\n\n You must take care in passing the proper arguments when\n using this function.\n\n .. versionchanged:: 2.0\n\n ``command`` parameter is now positional-only.\n\n Parameters\n -----------\n command: :class:`.Command`\n The command that is going to be called.\n \\*args\n The arguments to use.\n \\*\\*kwargs\n The keyword arguments to use.\n\n Raises\n -------\n TypeError\n The command argument to invoke is missing.\n \"\"\"\n return await command(self, *args, **kwargs)\n\n async def reinvoke(self, *, call_hooks: bool = False, restart: bool = True) -> None:\n \"\"\"|coro|\n\n Calls the command again.\n\n This is similar to :meth:`~.Context.invoke` except that it bypasses\n checks, cooldowns, and error handlers.\n\n .. note::\n\n If you want to bypass :exc:`.UserInputError` derived exceptions,\n it is recommended to use the regular :meth:`~.Context.invoke`\n as it will work more naturally. After all, this will end up\n using the old arguments the user has used and will thus just\n fail again.\n\n Parameters\n ------------\n call_hooks: :class:`bool`\n Whether to call the before and after invoke hooks.\n restart: :class:`bool`\n Whether to start the call chain from the very beginning\n or where we left off (i.e. the command that caused the error).\n The default is to start where we left off.\n\n Raises\n -------\n ValueError\n The context to reinvoke is not valid.\n \"\"\"\n cmd = self.command\n view = self.view\n if cmd is None:\n raise ValueError('This context is not valid.')\n\n # some state to revert to when we're done\n index, previous = view.index, view.previous\n invoked_with = self.invoked_with\n invoked_subcommand = self.invoked_subcommand\n invoked_parents = self.invoked_parents\n subcommand_passed = self.subcommand_passed\n\n if restart:\n to_call = cmd.root_parent or cmd\n view.index = len(self.prefix or '')\n view.previous = 0\n self.invoked_parents = []\n self.invoked_with = view.get_word() # advance to get the root command\n else:\n to_call = cmd\n\n try:\n await to_call.reinvoke(self, call_hooks=call_hooks)\n finally:\n self.command = cmd\n view.index = index\n view.previous = previous\n self.invoked_with = invoked_with\n self.invoked_subcommand = invoked_subcommand\n self.invoked_parents = invoked_parents\n self.subcommand_passed = subcommand_passed\n\n @property\n def valid(self) -> bool:\n \"\"\":class:`bool`: Checks if the invocation context is valid to be invoked with.\"\"\"\n return self.prefix is not None and self.command is not None\n\n async def _get_channel(self) -> discord.abc.Messageable:\n return self.channel\n\n @property\n def clean_prefix(self) -> str:\n \"\"\":class:`str`: The cleaned up invoke prefix. i.e. mentions are ``@name`` instead of ``<@id>``.\n\n .. versionadded:: 2.0\n \"\"\"\n if self.prefix is None:\n return ''\n\n user = self.me\n # this breaks if the prefix mention is not the bot itself but I\n # consider this to be an *incredibly* strange use case. I'd rather go\n # for this common use case rather than waste performance for the\n # odd one.\n pattern = re.compile(r\"<@!?%s>\" % user.id)\n return pattern.sub(\"@%s\" % user.display_name.replace('\\\\', r'\\\\'), self.prefix)\n\n @property\n def cog(self) -> Optional[Cog]:\n \"\"\"Optional[:class:`.Cog`]: Returns the cog associated with this context's command. None if it does not exist.\"\"\"\n\n if self.command is None:\n return None\n return self.command.cog\n\n @property\n def filesize_limit(self) -> int:\n \"\"\":class:`int`: Returns the maximum number of bytes files can have when uploaded to this guild or DM channel associated with this context.\n\n .. versionadded:: 2.3\n \"\"\"\n return self.guild.filesize_limit if self.guild is not None else discord.utils.DEFAULT_FILE_SIZE_LIMIT_BYTES\n\n @discord.utils.cached_property\n def guild(self) -> Optional[Guild]:\n \"\"\"Optional[:class:`.Guild`]: Returns the guild associated with this context's command. None if not available.\"\"\"\n return self.message.guild\n\n @discord.utils.cached_property\n def channel(self) -> MessageableChannel:\n \"\"\"Union[:class:`.abc.Messageable`]: Returns the channel associated with this context's command.\n Shorthand for :attr:`.Message.channel`.\n \"\"\"\n return self.message.channel\n\n @discord.utils.cached_property\n def author(self) -> Union[User, Member]:\n \"\"\"Union[:class:`~discord.User`, :class:`.Member`]:\n Returns the author associated with this context's command. Shorthand for :attr:`.Message.author`\n \"\"\"\n return self.message.author\n\n @discord.utils.cached_property\n def me(self) -> Union[Member, ClientUser]:\n \"\"\"Union[:class:`.Member`, :class:`.ClientUser`]:\n Similar to :attr:`.Guild.me` except it may return the :class:`.ClientUser` in private message contexts.\n \"\"\"\n # bot.user will never be None at this point.\n return self.guild.me if self.guild is not None else self.bot.user # type: ignore\n\n @discord.utils.cached_property\n def permissions(self) -> Permissions:\n \"\"\":class:`.Permissions`: Returns the resolved permissions for the invoking user in this channel.\n Shorthand for :meth:`.abc.GuildChannel.permissions_for` or :attr:`.Interaction.permissions`.\n\n .. versionadded:: 2.0\n \"\"\"\n if self.interaction is None and self.channel.type is ChannelType.private:\n return Permissions._dm_permissions()\n if not self.interaction:\n # channel and author will always match relevant types here\n return self.channel.permissions_for(self.author) # type: ignore\n base = self.interaction.permissions\n if self.channel.type in (ChannelType.voice, ChannelType.stage_voice):\n if not base.connect:\n # voice channels cannot be edited by people who can't connect to them\n # It also implicitly denies all other voice perms\n denied = Permissions.voice()\n denied.update(manage_channels=True, manage_roles=True)\n base.value &= ~denied.value\n else:\n # text channels do not have voice related permissions\n denied = Permissions.voice()\n base.value &= ~denied.value\n return base\n\n @discord.utils.cached_property\n def bot_permissions(self) -> Permissions:\n \"\"\":class:`.Permissions`: Returns the resolved permissions for the bot in this channel.\n Shorthand for :meth:`.abc.GuildChannel.permissions_for` or :attr:`.Interaction.app_permissions`.\n\n For interaction-based commands, this will reflect the effective permissions\n for :class:`Context` calls, which may differ from calls through\n other :class:`.abc.Messageable` endpoints, like :attr:`channel`.\n\n Notably, sending messages, embedding links, and attaching files are always\n permitted, while reading messages might not be.\n\n .. versionadded:: 2.0\n \"\"\"\n channel = self.channel\n if self.interaction is None and channel.type == ChannelType.private:\n return Permissions._dm_permissions()\n if not self.interaction:\n # channel and me will always match relevant types here\n return channel.permissions_for(self.me) # type: ignore\n guild = channel.guild\n base = self.interaction.app_permissions\n if self.channel.type in (ChannelType.voice, ChannelType.stage_voice):\n if not base.connect:\n # voice channels cannot be edited by people who can't connect to them\n # It also implicitly denies all other voice perms\n denied = Permissions.voice()\n denied.update(manage_channels=True, manage_roles=True)\n base.value &= ~denied.value\n else:\n # text channels do not have voice related permissions\n denied = Permissions.voice()\n base.value &= ~denied.value\n base.update(\n embed_links=True,\n attach_files=True,\n send_tts_messages=False,\n )\n if isinstance(channel, Thread):\n base.send_messages_in_threads = True\n else:\n base.send_messages = True\n return base\n\n @property\n def voice_client(self) -> Optional[VoiceProtocol]:\n r\"\"\"Optional[:class:`.VoiceProtocol`]: A shortcut to :attr:`.Guild.voice_client`\\, if applicable.\"\"\"\n g = self.guild\n return g.voice_client if g else None\n\n async def send_help(self, *args: Any) -> Any:\n \"\"\"send_help(entity=)\n\n |coro|\n\n Shows the help command for the specified entity if given.\n The entity can be a command or a cog.\n\n If no entity is given, then it'll show help for the\n entire bot.\n\n If the entity is a string, then it looks up whether it's a\n :class:`Cog` or a :class:`Command`.\n\n .. note::\n\n Due to the way this function works, instead of returning\n something similar to :meth:`~.commands.HelpCommand.command_not_found`\n this returns ``None`` on bad input or no help command.\n\n Parameters\n ------------\n entity: Optional[Union[:class:`Command`, :class:`Cog`, :class:`str`]]\n The entity to show help for.\n\n Returns\n --------\n Any\n The result of the help command, if any.\n \"\"\"\n from .core import Command, Group, wrap_callback\n from .errors import CommandError\n\n bot = self.bot\n cmd = bot.help_command\n\n if cmd is None:\n return None\n\n cmd = cmd.copy()\n cmd.context = self\n\n if len(args) == 0:\n await cmd.prepare_help_command(self, None)\n mapping = cmd.get_bot_mapping()\n injected = wrap_callback(cmd.send_bot_help)\n try:\n return await injected(mapping)\n except CommandError as e:\n await cmd.on_help_command_error(self, e)\n return None\n\n entity = args[0]\n if isinstance(entity, str):\n entity = bot.get_cog(entity) or bot.get_command(entity)\n\n if entity is None:\n return None\n\n try:\n entity.qualified_name\n except AttributeError:\n # if we're here then it's not a cog, group, or command.\n return None\n\n await cmd.prepare_help_command(self, entity.qualified_name)\n\n try:\n if is_cog(entity):\n injected = wrap_callback(cmd.send_cog_help)\n return await injected(entity)\n elif isinstance(entity, Group):\n injected = wrap_callback(cmd.send_group_help)\n return await injected(entity)\n elif isinstance(entity, Command):\n injected = wrap_callback(cmd.send_command_help)\n return await injected(entity)\n else:\n return None\n except CommandError as e:\n await cmd.on_help_command_error(self, e)\n\n @overload\n async def reply(\n self,\n content: Optional[str] = ...,\n *,\n tts: bool = ...,\n embed: Embed = ...,\n file: File = ...,\n stickers: Sequence[Union[GuildSticker, StickerItem]] = ...,\n delete_after: float = ...,\n nonce: Union[str, int] = ...,\n allowed_mentions: AllowedMentions = ...,\n reference: Union[Message, MessageReference, PartialMessage] = ...,\n mention_author: bool = ...,\n view: View = ...,\n suppress_embeds: bool = ...,\n ephemeral: bool = ...,\n silent: bool = ...,\n poll: Poll = ...,\n ) -> Message:\n ...\n\n @overload\n async def reply(\n self,\n content: Optional[str] = ...,\n *,\n tts: bool = ...,\n embed: Embed = ...,\n files: Sequence[File] = ...,\n stickers: Sequence[Union[GuildSticker, StickerItem]] = ...,\n delete_after: float = ...,\n nonce: Union[str, int] = ...,\n allowed_mentions: AllowedMentions = ...,\n reference: Union[Message, MessageReference, PartialMessage] = ...,\n mention_author: bool = ...,\n view: View = ...,\n suppress_embeds: bool = ...,\n ephemeral: bool = ...,\n silent: bool = ...,\n poll: Poll = ...,\n ) -> Message:\n ...\n\n @overload\n async def reply(\n self,\n content: Optional[str] = ...,\n *,\n tts: bool = ...,\n embeds: Sequence[Embed] = ...,\n file: File = ...,\n stickers: Sequence[Union[GuildSticker, StickerItem]] = ...,\n delete_after: float = ...,\n nonce: Union[str, int] = ...,\n allowed_mentions: AllowedMentions = ...,\n reference: Union[Message, MessageReference, PartialMessage] = ...,\n mention_author: bool = ...,\n view: View = ...,\n suppress_embeds: bool = ...,\n ephemeral: bool = ...,\n silent: bool = ...,\n poll: Poll = ...,\n ) -> Message:\n ...\n\n @overload\n async def reply(\n self,\n content: Optional[str] = ...,\n *,\n tts: bool = ...,\n embeds: Sequence[Embed] = ...,\n files: Sequence[File] = ...,\n stickers: Sequence[Union[GuildSticker, StickerItem]] = ...,\n delete_after: float = ...,\n nonce: Union[str, int] = ...,\n allowed_mentions: AllowedMentions = ...,\n reference: Union[Message, MessageReference, PartialMessage] = ...,\n mention_author: bool = ...,\n view: View = ...,\n suppress_embeds: bool = ...,\n ephemeral: bool = ...,\n silent: bool = ...,\n poll: Poll = ...,\n ) -> Message:\n ...\n\n async def reply(self, content: Optional[str] = None, **kwargs: Any) -> Message:\n \"\"\"|coro|\n\n A shortcut method to :meth:`send` to reply to the\n :class:`~discord.Message` referenced by this context.\n\n For interaction based contexts, this is the same as :meth:`send`.\n\n .. versionadded:: 1.6\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`TypeError` or\n :exc:`ValueError` instead of ``InvalidArgument``.\n\n Raises\n --------\n ~discord.HTTPException\n Sending the message failed.\n ~discord.Forbidden\n You do not have the proper permissions to send the message.\n ValueError\n The ``files`` list is not of the appropriate size\n TypeError\n You specified both ``file`` and ``files``.\n\n Returns\n ---------\n :class:`~discord.Message`\n The message that was sent.\n \"\"\"\n if self.interaction is None:\n return await self.send(content, reference=self.message, **kwargs)\n else:\n return await self.send(content, **kwargs)\n\n def typing(self, *, ephemeral: bool = False) -> Union[Typing, DeferTyping]:\n \"\"\"Returns an asynchronous context manager that allows you to send a typing indicator to\n the destination for an indefinite period of time, or 10 seconds if the context manager\n is called using ``await``.\n\n In an interaction based context, this is equivalent to a :meth:`defer` call and\n does not do any typing calls.\n\n Example Usage: ::\n\n async with channel.typing():\n # simulate something heavy\n await asyncio.sleep(20)\n\n await channel.send('Done!')\n\n Example Usage: ::\n\n await channel.typing()\n # Do some computational magic for about 10 seconds\n await channel.send('Done!')\n\n .. versionchanged:: 2.0\n This no longer works with the ``with`` syntax, ``async with`` must be used instead.\n\n .. versionchanged:: 2.0\n Added functionality to ``await`` the context manager to send a typing indicator for 10 seconds.\n\n Parameters\n -----------\n ephemeral: :class:`bool`\n Indicates whether the deferred message will eventually be ephemeral.\n Only valid for interaction based contexts.\n\n .. versionadded:: 2.0\n \"\"\"\n if self.interaction is None:\n return Typing(self)\n return DeferTyping(self, ephemeral=ephemeral)\n\n async def defer(self, *, ephemeral: bool = False) -> None:\n \"\"\"|coro|\n\n Defers the interaction based contexts.\n\n This is typically used when the interaction is acknowledged\n and a secondary action will be done later.\n\n If this isn't an interaction based context then it does nothing.\n\n Parameters\n -----------\n ephemeral: :class:`bool`\n Indicates whether the deferred message will eventually be ephemeral.\n\n Raises\n -------\n HTTPException\n Deferring the interaction failed.\n InteractionResponded\n This interaction has already been responded to before.\n \"\"\"\n\n if self.interaction:\n await self.interaction.response.defer(ephemeral=ephemeral)\n\n @overload\n async def send(\n self,\n content: Optional[str] = ...,\n *,\n tts: bool = ...,\n embed: Embed = ...,\n file: File = ...,\n stickers: Sequence[Union[GuildSticker, StickerItem]] = ...,\n delete_after: float = ...,\n nonce: Union[str, int] = ...,\n allowed_mentions: AllowedMentions = ...,\n reference: Union[Message, MessageReference, PartialMessage] = ...,\n mention_author: bool = ...,\n view: View = ...,\n suppress_embeds: bool = ...,\n ephemeral: bool = ...,\n silent: bool = ...,\n poll: Poll = ...,\n ) -> Message:\n ...\n\n @overload\n async def send(\n self,\n content: Optional[str] = ...,\n *,\n tts: bool = ...,\n embed: Embed = ...,\n files: Sequence[File] = ...,\n stickers: Sequence[Union[GuildSticker, StickerItem]] = ...,\n delete_after: float = ...,\n nonce: Union[str, int] = ...,\n allowed_mentions: AllowedMentions = ...,\n reference: Union[Message, MessageReference, PartialMessage] = ...,\n mention_author: bool = ...,\n view: View = ...,\n suppress_embeds: bool = ...,\n ephemeral: bool = ...,\n silent: bool = ...,\n poll: Poll = ...,\n ) -> Message:\n ...\n\n @overload\n async def send(\n self,\n content: Optional[str] = ...,\n *,\n tts: bool = ...,\n embeds: Sequence[Embed] = ...,\n file: File = ...,\n stickers: Sequence[Union[GuildSticker, StickerItem]] = ...,\n delete_after: float = ...,\n nonce: Union[str, int] = ...,\n allowed_mentions: AllowedMentions = ...,\n reference: Union[Message, MessageReference, PartialMessage] = ...,\n mention_author: bool = ...,\n view: View = ...,\n suppress_embeds: bool = ...,\n ephemeral: bool = ...,\n silent: bool = ...,\n poll: Poll = ...,\n ) -> Message:\n ...\n\n @overload\n async def send(\n self,\n content: Optional[str] = ...,\n *,\n tts: bool = ...,\n embeds: Sequence[Embed] = ...,\n files: Sequence[File] = ...,\n stickers: Sequence[Union[GuildSticker, StickerItem]] = ...,\n delete_after: float = ...,\n nonce: Union[str, int] = ...,\n allowed_mentions: AllowedMentions = ...,\n reference: Union[Message, MessageReference, PartialMessage] = ...,\n mention_author: bool = ...,\n view: View = ...,\n suppress_embeds: bool = ...,\n ephemeral: bool = ...,\n silent: bool = ...,\n poll: Poll = ...,\n ) -> Message:\n ...\n\n async def send(\n self,\n content: Optional[str] = None,\n *,\n tts: bool = False,\n embed: Optional[Embed] = None,\n embeds: Optional[Sequence[Embed]] = None,\n file: Optional[File] = None,\n files: Optional[Sequence[File]] = None,\n stickers: Optional[Sequence[Union[GuildSticker, StickerItem]]] = None,\n delete_after: Optional[float] = None,\n nonce: Optional[Union[str, int]] = None,\n allowed_mentions: Optional[AllowedMentions] = None,\n reference: Optional[Union[Message, MessageReference, PartialMessage]] = None,\n mention_author: Optional[bool] = None,\n view: Optional[View] = None,\n suppress_embeds: bool = False,\n ephemeral: bool = False,\n silent: bool = False,\n poll: Poll = MISSING,\n ) -> Message:\n \"\"\"|coro|\n\n Sends a message to the destination with the content given.\n\n This works similarly to :meth:`~discord.abc.Messageable.send` for non-interaction contexts.\n\n For interaction based contexts this does one of the following:\n\n - :meth:`discord.InteractionResponse.send_message` if no response has been given.\n - A followup message if a response has been given.\n - Regular send if the interaction has expired\n\n .. versionchanged:: 2.0\n This function will now raise :exc:`TypeError` or\n :exc:`ValueError` instead of ``InvalidArgument``.\n\n Parameters\n ------------\n content: Optional[:class:`str`]\n The content of the message to send.\n tts: :class:`bool`\n Indicates if the message should be sent using text-to-speech.\n embed: :class:`~discord.Embed`\n The rich embed for the content.\n file: :class:`~discord.File`\n The file to upload.\n files: List[:class:`~discord.File`]\n A list of files to upload. Must be a maximum of 10.\n nonce: :class:`int`\n The nonce to use for sending this message. If the message was successfully sent,\n then the message will have a nonce with this value.\n delete_after: :class:`float`\n If provided, the number of seconds to wait in the background\n before deleting the message we just sent. If the deletion fails,\n then it is silently ignored.\n allowed_mentions: :class:`~discord.AllowedMentions`\n Controls the mentions being processed in this message. If this is\n passed, then the object is merged with :attr:`~discord.Client.allowed_mentions`.\n The merging behaviour only overrides attributes that have been explicitly passed\n to the object, otherwise it uses the attributes set in :attr:`~discord.Client.allowed_mentions`.\n If no object is passed at all then the defaults given by :attr:`~discord.Client.allowed_mentions`\n are used instead.\n\n .. versionadded:: 1.4\n\n reference: Union[:class:`~discord.Message`, :class:`~discord.MessageReference`, :class:`~discord.PartialMessage`]\n A reference to the :class:`~discord.Message` to which you are replying, this can be created using\n :meth:`~discord.Message.to_reference` or passed directly as a :class:`~discord.Message`. You can control\n whether this mentions the author of the referenced message using the :attr:`~discord.AllowedMentions.replied_user`\n attribute of ``allowed_mentions`` or by setting ``mention_author``.\n\n This is ignored for interaction based contexts.\n\n .. versionadded:: 1.6\n\n mention_author: Optional[:class:`bool`]\n If set, overrides the :attr:`~discord.AllowedMentions.replied_user` attribute of ``allowed_mentions``.\n This is ignored for interaction based contexts.\n\n .. versionadded:: 1.6\n view: :class:`discord.ui.View`\n A Discord UI View to add to the message.\n\n .. versionadded:: 2.0\n embeds: List[:class:`~discord.Embed`]\n A list of embeds to upload. Must be a maximum of 10.\n\n .. versionadded:: 2.0\n stickers: Sequence[Union[:class:`~discord.GuildSticker`, :class:`~discord.StickerItem`]]\n A list of stickers to upload. Must be a maximum of 3. This is ignored for interaction based contexts.\n\n .. versionadded:: 2.0\n suppress_embeds: :class:`bool`\n Whether to suppress embeds for the message. This sends the message without any embeds if set to ``True``.\n\n .. versionadded:: 2.0\n ephemeral: :class:`bool`\n Indicates if the message should only be visible to the user who started the interaction.\n If a view is sent with an ephemeral message and it has no timeout set then the timeout\n is set to 15 minutes. **This is only applicable in contexts with an interaction**.\n\n .. versionadded:: 2.0\n silent: :class:`bool`\n Whether to suppress push and desktop notifications for the message. This will increment the mention counter\n in the UI, but will not actually send a notification.\n\n .. versionadded:: 2.2\n\n poll: :class:`~discord.Poll`\n The poll to send with this message.\n\n .. versionadded:: 2.4\n\n Raises\n --------\n ~discord.HTTPException\n Sending the message failed.\n ~discord.Forbidden\n You do not have the proper permissions to send the message.\n ValueError\n The ``files`` list is not of the appropriate size.\n TypeError\n You specified both ``file`` and ``files``,\n or you specified both ``embed`` and ``embeds``,\n or the ``reference`` object is not a :class:`~discord.Message`,\n :class:`~discord.MessageReference` or :class:`~discord.PartialMessage`.\n\n Returns\n ---------\n :class:`~discord.Message`\n The message that was sent.\n \"\"\"\n\n if self.interaction is None or self.interaction.is_expired():\n return await super().send(\n content=content,\n tts=tts,\n embed=embed,\n embeds=embeds,\n file=file,\n files=files,\n stickers=stickers,\n delete_after=delete_after,\n nonce=nonce,\n allowed_mentions=allowed_mentions,\n reference=reference,\n mention_author=mention_author,\n view=view,\n suppress_embeds=suppress_embeds,\n silent=silent,\n poll=poll,\n ) # type: ignore # The overloads don't support Optional but the implementation does\n\n # Convert the kwargs from None to MISSING to appease the remaining implementations\n kwargs = {\n 'content': content,\n 'tts': tts,\n 'embed': MISSING if embed is None else embed,\n 'embeds': MISSING if embeds is None else embeds,\n 'file': MISSING if file is None else file,\n 'files': MISSING if files is None else files,\n 'allowed_mentions': MISSING if allowed_mentions is None else allowed_mentions,\n 'view': MISSING if view is None else view,\n 'suppress_embeds': suppress_embeds,\n 'ephemeral': ephemeral,\n 'silent': silent,\n 'poll': poll,\n }\n\n if self.interaction.response.is_done():\n msg = await self.interaction.followup.send(**kwargs, wait=True)\n else:\n await self.interaction.response.send_message(**kwargs)\n msg = await self.interaction.original_response()\n\n if delete_after is not None:\n await msg.delete(delay=delete_after)\n return msg\n" }, { "path": "discord/ext/commands/converter.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport inspect\nimport re\nfrom typing import (\n TYPE_CHECKING,\n Any,\n Dict,\n Generic,\n Iterable,\n List,\n Literal,\n Optional,\n overload,\n Protocol,\n Tuple,\n Type,\n TypeVar,\n Union,\n runtime_checkable,\n)\nimport types\n\nimport discord\n\nfrom .errors import *\n\nif TYPE_CHECKING:\n from discord.state import Channel\n from discord.threads import Thread\n\n from .parameters import Parameter\n from ._types import BotT, _Bot\n from .context import Context\n\n__all__ = (\n 'Converter',\n 'ObjectConverter',\n 'MemberConverter',\n 'UserConverter',\n 'MessageConverter',\n 'PartialMessageConverter',\n 'TextChannelConverter',\n 'InviteConverter',\n 'GuildConverter',\n 'RoleConverter',\n 'GameConverter',\n 'ColourConverter',\n 'ColorConverter',\n 'VoiceChannelConverter',\n 'StageChannelConverter',\n 'EmojiConverter',\n 'PartialEmojiConverter',\n 'CategoryChannelConverter',\n 'ForumChannelConverter',\n 'IDConverter',\n 'ThreadConverter',\n 'GuildChannelConverter',\n 'GuildStickerConverter',\n 'ScheduledEventConverter',\n 'clean_content',\n 'Greedy',\n 'Range',\n 'run_converters',\n)\n\n\ndef _get_from_guilds(bot: _Bot, getter: str, argument: Any) -> Any:\n result = None\n for guild in bot.guilds:\n result = getattr(guild, getter)(argument)\n if result:\n return result\n return result\n\n\n_utils_get = discord.utils.get\nT = TypeVar('T')\nT_co = TypeVar('T_co', covariant=True)\nCT = TypeVar('CT', bound=discord.abc.GuildChannel)\nTT = TypeVar('TT', bound=discord.Thread)\n\n\n@runtime_checkable\nclass Converter(Protocol[T_co]):\n \"\"\"The base class of custom converters that require the :class:`.Context`\n to be passed to be useful.\n\n This allows you to implement converters that function similar to the\n special cased ``discord`` classes.\n\n Classes that derive from this should override the :meth:`~.Converter.convert`\n method to do its conversion logic. This method must be a :ref:`coroutine `.\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> T_co:\n \"\"\"|coro|\n\n The method to override to do conversion logic.\n\n If an error is found while converting, it is recommended to\n raise a :exc:`.CommandError` derived exception as it will\n properly propagate to the error handlers.\n\n Note that if this method is called manually, :exc:`Exception`\n should be caught to handle the cases where a subclass does\n not explicitly inherit from :exc:`.CommandError`.\n\n Parameters\n -----------\n ctx: :class:`.Context`\n The invocation context that the argument is being used in.\n argument: :class:`str`\n The argument that is being converted.\n\n Raises\n -------\n CommandError\n A generic exception occurred when converting the argument.\n BadArgument\n The converter failed to convert the argument.\n \"\"\"\n raise NotImplementedError('Derived classes need to implement this.')\n\n\n_ID_REGEX = re.compile(r'([0-9]{15,20})$')\n\n\nclass IDConverter(Converter[T_co]):\n @staticmethod\n def _get_id_match(argument):\n return _ID_REGEX.match(argument)\n\n\nclass ObjectConverter(IDConverter[discord.Object]):\n \"\"\"Converts to a :class:`~discord.Object`.\n\n The argument must follow the valid ID or mention formats (e.g. ``<@80088516616269824>``).\n\n .. versionadded:: 2.0\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by member, role, or channel mention.\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.Object:\n match = self._get_id_match(argument) or re.match(r'<(?:@(?:!|&)?|#)([0-9]{15,20})>$', argument)\n\n if match is None:\n raise ObjectNotFound(argument)\n\n result = int(match.group(1))\n\n return discord.Object(id=result)\n\n\nclass MemberConverter(IDConverter[discord.Member]):\n \"\"\"Converts to a :class:`~discord.Member`.\n\n All lookups are via the local guild. If in a DM context, then the lookup\n is done by the global cache.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by mention.\n 3. Lookup by username#discriminator (deprecated).\n 4. Lookup by username#0 (deprecated, only gets users that migrated from their discriminator).\n 5. Lookup by user name.\n 6. Lookup by global name.\n 7. Lookup by guild nickname.\n\n .. versionchanged:: 1.5\n Raise :exc:`.MemberNotFound` instead of generic :exc:`.BadArgument`\n\n .. versionchanged:: 1.5.1\n This converter now lazily fetches members from the gateway and HTTP APIs,\n optionally caching the result if :attr:`.MemberCacheFlags.joined` is enabled.\n\n .. deprecated:: 2.3\n Looking up users by discriminator will be removed in a future version due to\n the removal of discriminators in an API change.\n \"\"\"\n\n async def query_member_named(self, guild: discord.Guild, argument: str) -> Optional[discord.Member]:\n cache = guild._state.member_cache_flags.joined\n username, _, discriminator = argument.rpartition('#')\n\n # If # isn't found then \"discriminator\" actually has the username\n if not username:\n discriminator, username = username, discriminator\n\n if discriminator == '0' or (len(discriminator) == 4 and discriminator.isdigit()):\n lookup = username\n predicate = lambda m: m.name == username and m.discriminator == discriminator\n else:\n lookup = argument\n predicate = lambda m: m.name == argument or m.global_name == argument or m.nick == argument\n\n members = await guild.query_members(lookup, limit=100, cache=cache)\n return discord.utils.find(predicate, members)\n\n async def query_member_by_id(self, bot: _Bot, guild: discord.Guild, user_id: int) -> Optional[discord.Member]:\n ws = bot._get_websocket(shard_id=guild.shard_id)\n cache = guild._state.member_cache_flags.joined\n if ws.is_ratelimited():\n # If we're being rate limited on the WS, then fall back to using the HTTP API\n # So we don't have to wait ~60 seconds for the query to finish\n try:\n member = await guild.fetch_member(user_id)\n except discord.HTTPException:\n return None\n\n if cache:\n guild._add_member(member)\n return member\n\n # If we're not being rate limited then we can use the websocket to actually query\n members = await guild.query_members(limit=1, user_ids=[user_id], cache=cache)\n if not members:\n return None\n return members[0]\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.Member:\n bot = ctx.bot\n match = self._get_id_match(argument) or re.match(r'<@!?([0-9]{15,20})>$', argument)\n guild = ctx.guild\n result = None\n user_id = None\n\n if match is None:\n # not a mention...\n if guild:\n result = guild.get_member_named(argument)\n else:\n result = _get_from_guilds(bot, 'get_member_named', argument)\n else:\n user_id = int(match.group(1))\n if guild:\n result = guild.get_member(user_id) or _utils_get(ctx.message.mentions, id=user_id)\n else:\n result = _get_from_guilds(bot, 'get_member', user_id)\n\n if not isinstance(result, discord.Member):\n if guild is None:\n raise MemberNotFound(argument)\n\n if user_id is not None:\n result = await self.query_member_by_id(bot, guild, user_id)\n else:\n result = await self.query_member_named(guild, argument)\n\n if not result:\n raise MemberNotFound(argument)\n\n return result\n\n\nclass UserConverter(IDConverter[discord.User]):\n \"\"\"Converts to a :class:`~discord.User`.\n\n All lookups are via the global user cache.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by mention.\n 3. Lookup by username#discriminator (deprecated).\n 4. Lookup by username#0 (deprecated, only gets users that migrated from their discriminator).\n 5. Lookup by user name.\n 6. Lookup by global name.\n\n .. versionchanged:: 1.5\n Raise :exc:`.UserNotFound` instead of generic :exc:`.BadArgument`\n\n .. versionchanged:: 1.6\n This converter now lazily fetches users from the HTTP APIs if an ID is passed\n and it's not available in cache.\n\n .. deprecated:: 2.3\n Looking up users by discriminator will be removed in a future version due to\n the removal of discriminators in an API change.\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.User:\n match = self._get_id_match(argument) or re.match(r'<@!?([0-9]{15,20})>$', argument)\n result = None\n state = ctx._state\n\n if match is not None:\n user_id = int(match.group(1))\n result = ctx.bot.get_user(user_id) or _utils_get(ctx.message.mentions, id=user_id)\n if result is None:\n try:\n result = await ctx.bot.fetch_user(user_id)\n except discord.HTTPException:\n raise UserNotFound(argument) from None\n\n return result # type: ignore\n\n username, _, discriminator = argument.rpartition('#')\n\n # If # isn't found then \"discriminator\" actually has the username\n if not username:\n discriminator, username = username, discriminator\n\n if discriminator == '0' or (len(discriminator) == 4 and discriminator.isdigit()):\n predicate = lambda u: u.name == username and u.discriminator == discriminator\n else:\n predicate = lambda u: u.name == argument or u.global_name == argument\n\n result = discord.utils.find(predicate, state._users.values())\n if result is None:\n raise UserNotFound(argument)\n\n return result\n\n\nclass PartialMessageConverter(Converter[discord.PartialMessage]):\n \"\"\"Converts to a :class:`discord.PartialMessage`.\n\n .. versionadded:: 1.7\n\n The creation strategy is as follows (in order):\n\n 1. By \"{channel ID}-{message ID}\" (retrieved by shift-clicking on \"Copy ID\")\n 2. By message ID (The message is assumed to be in the context channel.)\n 3. By message URL\n \"\"\"\n\n @staticmethod\n def _get_id_matches(ctx: Context[BotT], argument: str) -> Tuple[Optional[int], int, int]:\n id_regex = re.compile(r'(?:(?P[0-9]{15,20})-)?(?P[0-9]{15,20})$')\n link_regex = re.compile(\n r'https?://(?:(ptb|canary|www)\\.)?discord(?:app)?\\.com/channels/'\n r'(?P[0-9]{15,20}|@me)'\n r'/(?P[0-9]{15,20})/(?P[0-9]{15,20})/?$'\n )\n match = id_regex.match(argument) or link_regex.match(argument)\n if not match:\n raise MessageNotFound(argument)\n data = match.groupdict()\n channel_id = discord.utils._get_as_snowflake(data, 'channel_id') or ctx.channel.id\n message_id = int(data['message_id'])\n guild_id = data.get('guild_id')\n if guild_id is None:\n guild_id = ctx.guild and ctx.guild.id\n elif guild_id == '@me':\n guild_id = None\n else:\n guild_id = int(guild_id)\n return guild_id, message_id, channel_id\n\n @staticmethod\n def _resolve_channel(\n ctx: Context[BotT], guild_id: Optional[int], channel_id: Optional[int]\n ) -> Optional[Union[Channel, Thread]]:\n if channel_id is None:\n # we were passed just a message id so we can assume the channel is the current context channel\n return ctx.channel\n\n if guild_id is not None:\n guild = ctx.bot.get_guild(guild_id)\n if guild is None:\n return None\n return guild._resolve_channel(channel_id)\n\n return ctx.bot.get_channel(channel_id)\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.PartialMessage:\n guild_id, message_id, channel_id = self._get_id_matches(ctx, argument)\n channel = self._resolve_channel(ctx, guild_id, channel_id)\n if not channel or not isinstance(channel, discord.abc.Messageable):\n raise ChannelNotFound(channel_id)\n return discord.PartialMessage(channel=channel, id=message_id)\n\n\nclass MessageConverter(IDConverter[discord.Message]):\n \"\"\"Converts to a :class:`discord.Message`.\n\n .. versionadded:: 1.1\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by \"{channel ID}-{message ID}\" (retrieved by shift-clicking on \"Copy ID\")\n 2. Lookup by message ID (the message **must** be in the context channel)\n 3. Lookup by message URL\n\n .. versionchanged:: 1.5\n Raise :exc:`.ChannelNotFound`, :exc:`.MessageNotFound` or :exc:`.ChannelNotReadable` instead of generic :exc:`.BadArgument`\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.Message:\n guild_id, message_id, channel_id = PartialMessageConverter._get_id_matches(ctx, argument)\n message = ctx.bot._connection._get_message(message_id)\n if message:\n return message\n channel = PartialMessageConverter._resolve_channel(ctx, guild_id, channel_id)\n if not channel or not isinstance(channel, discord.abc.Messageable):\n raise ChannelNotFound(channel_id)\n try:\n return await channel.fetch_message(message_id)\n except discord.NotFound:\n raise MessageNotFound(argument)\n except discord.Forbidden:\n raise ChannelNotReadable(channel) # type: ignore # type-checker thinks channel could be a DMChannel at this point\n\n\nclass GuildChannelConverter(IDConverter[discord.abc.GuildChannel]):\n \"\"\"Converts to a :class:`~discord.abc.GuildChannel`.\n\n All lookups are via the local guild. If in a DM context, then the lookup\n is done by the global cache.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by mention.\n 3. Lookup by channel URL.\n 4. Lookup by name.\n\n .. versionadded:: 2.0\n\n .. versionchanged:: 2.4\n Add lookup by channel URL, accessed via \"Copy Link\" in the Discord client within channels.\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.abc.GuildChannel:\n return self._resolve_channel(ctx, argument, 'channels', discord.abc.GuildChannel)\n\n @staticmethod\n def _parse_from_url(argument: str) -> Optional[re.Match[str]]:\n link_regex = re.compile(\n r'https?://(?:(?:ptb|canary|www)\\.)?discord(?:app)?\\.com/channels/'\n r'(?:[0-9]{15,20}|@me)'\n r'/([0-9]{15,20})(?:/(?:[0-9]{15,20})/?)?$'\n )\n return link_regex.match(argument)\n\n @staticmethod\n def _resolve_channel(ctx: Context[BotT], argument: str, attribute: str, type: Type[CT]) -> CT:\n bot = ctx.bot\n\n match = (\n IDConverter._get_id_match(argument)\n or re.match(r'<#([0-9]{15,20})>$', argument)\n or GuildChannelConverter._parse_from_url(argument)\n )\n result = None\n guild = ctx.guild\n\n if match is None:\n # not a mention\n if guild:\n iterable: Iterable[CT] = getattr(guild, attribute)\n result: Optional[CT] = discord.utils.get(iterable, name=argument)\n else:\n\n def check(c):\n return isinstance(c, type) and c.name == argument\n\n result = discord.utils.find(check, bot.get_all_channels()) # type: ignore\n else:\n channel_id = int(match.group(1))\n if guild:\n # guild.get_channel returns an explicit union instead of the base class\n result = guild.get_channel(channel_id) # type: ignore\n else:\n result = _get_from_guilds(bot, 'get_channel', channel_id)\n\n if not isinstance(result, type):\n raise ChannelNotFound(argument)\n\n return result\n\n @staticmethod\n def _resolve_thread(ctx: Context[BotT], argument: str, attribute: str, type: Type[TT]) -> TT:\n match = (\n IDConverter._get_id_match(argument)\n or re.match(r'<#([0-9]{15,20})>$', argument)\n or GuildChannelConverter._parse_from_url(argument)\n )\n result = None\n guild = ctx.guild\n\n if match is None:\n # not a mention\n if guild:\n iterable: Iterable[TT] = getattr(guild, attribute)\n result: Optional[TT] = discord.utils.get(iterable, name=argument)\n else:\n thread_id = int(match.group(1))\n if guild:\n result = guild.get_thread(thread_id) # type: ignore\n\n if not result or not isinstance(result, type):\n raise ThreadNotFound(argument)\n\n return result\n\n\nclass TextChannelConverter(IDConverter[discord.TextChannel]):\n \"\"\"Converts to a :class:`~discord.TextChannel`.\n\n All lookups are via the local guild. If in a DM context, then the lookup\n is done by the global cache.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by mention.\n 3. Lookup by channel URL.\n 4. Lookup by name\n\n .. versionchanged:: 1.5\n Raise :exc:`.ChannelNotFound` instead of generic :exc:`.BadArgument`\n\n .. versionchanged:: 2.4\n Add lookup by channel URL, accessed via \"Copy Link\" in the Discord client within channels.\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.TextChannel:\n return GuildChannelConverter._resolve_channel(ctx, argument, 'text_channels', discord.TextChannel)\n\n\nclass VoiceChannelConverter(IDConverter[discord.VoiceChannel]):\n \"\"\"Converts to a :class:`~discord.VoiceChannel`.\n\n All lookups are via the local guild. If in a DM context, then the lookup\n is done by the global cache.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by mention.\n 3. Lookup by channel URL.\n 4. Lookup by name\n\n .. versionchanged:: 1.5\n Raise :exc:`.ChannelNotFound` instead of generic :exc:`.BadArgument`\n\n .. versionchanged:: 2.4\n Add lookup by channel URL, accessed via \"Copy Link\" in the Discord client within channels.\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.VoiceChannel:\n return GuildChannelConverter._resolve_channel(ctx, argument, 'voice_channels', discord.VoiceChannel)\n\n\nclass StageChannelConverter(IDConverter[discord.StageChannel]):\n \"\"\"Converts to a :class:`~discord.StageChannel`.\n\n .. versionadded:: 1.7\n\n All lookups are via the local guild. If in a DM context, then the lookup\n is done by the global cache.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by mention.\n 3. Lookup by channel URL.\n 4. Lookup by name\n\n .. versionchanged:: 2.4\n Add lookup by channel URL, accessed via \"Copy Link\" in the Discord client within channels.\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.StageChannel:\n return GuildChannelConverter._resolve_channel(ctx, argument, 'stage_channels', discord.StageChannel)\n\n\nclass CategoryChannelConverter(IDConverter[discord.CategoryChannel]):\n \"\"\"Converts to a :class:`~discord.CategoryChannel`.\n\n All lookups are via the local guild. If in a DM context, then the lookup\n is done by the global cache.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by mention.\n 3. Lookup by channel URL.\n 4. Lookup by name\n\n .. versionchanged:: 2.4\n Add lookup by channel URL, accessed via \"Copy Link\" in the Discord client within channels.\n\n .. versionchanged:: 1.5\n Raise :exc:`.ChannelNotFound` instead of generic :exc:`.BadArgument`\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.CategoryChannel:\n return GuildChannelConverter._resolve_channel(ctx, argument, 'categories', discord.CategoryChannel)\n\n\nclass ThreadConverter(IDConverter[discord.Thread]):\n \"\"\"Converts to a :class:`~discord.Thread`.\n\n All lookups are via the local guild.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by mention.\n 3. Lookup by channel URL.\n 4. Lookup by name.\n\n .. versionadded: 2.0\n\n .. versionchanged:: 2.4\n Add lookup by channel URL, accessed via \"Copy Link\" in the Discord client within channels.\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.Thread:\n return GuildChannelConverter._resolve_thread(ctx, argument, 'threads', discord.Thread)\n\n\nclass ForumChannelConverter(IDConverter[discord.ForumChannel]):\n \"\"\"Converts to a :class:`~discord.ForumChannel`.\n\n All lookups are via the local guild. If in a DM context, then the lookup\n is done by the global cache.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by mention.\n 3. Lookup by channel URL.\n 4. Lookup by name\n\n .. versionadded:: 2.0\n\n .. versionchanged:: 2.4\n Add lookup by channel URL, accessed via \"Copy Link\" in the Discord client within channels.\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.ForumChannel:\n return GuildChannelConverter._resolve_channel(ctx, argument, 'forums', discord.ForumChannel)\n\n\nclass ColourConverter(Converter[discord.Colour]):\n \"\"\"Converts to a :class:`~discord.Colour`.\n\n .. versionchanged:: 1.5\n Add an alias named ColorConverter\n\n The following formats are accepted:\n\n - ``0x``\n - ``#``\n - ``0x#``\n - ``rgb(, , )``\n - Any of the ``classmethod`` in :class:`~discord.Colour`\n\n - The ``_`` in the name can be optionally replaced with spaces.\n\n Like CSS, ```` can be either 0-255 or 0-100% and ```` can be\n either a 6 digit hex number or a 3 digit hex shortcut (e.g. #fff).\n\n .. versionchanged:: 1.5\n Raise :exc:`.BadColourArgument` instead of generic :exc:`.BadArgument`\n\n .. versionchanged:: 1.7\n Added support for ``rgb`` function and 3-digit hex shortcuts\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.Colour:\n try:\n return discord.Colour.from_str(argument)\n except ValueError:\n arg = argument.lower().replace(' ', '_')\n method = getattr(discord.Colour, arg, None)\n if arg.startswith('from_') or method is None or not inspect.ismethod(method):\n raise BadColourArgument(arg)\n return method()\n\n\nColorConverter = ColourConverter\n\n\nclass RoleConverter(IDConverter[discord.Role]):\n \"\"\"Converts to a :class:`~discord.Role`.\n\n All lookups are via the local guild. If in a DM context, the converter raises\n :exc:`.NoPrivateMessage` exception.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by mention.\n 3. Lookup by name\n\n .. versionchanged:: 1.5\n Raise :exc:`.RoleNotFound` instead of generic :exc:`.BadArgument`\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.Role:\n guild = ctx.guild\n if not guild:\n raise NoPrivateMessage()\n\n match = self._get_id_match(argument) or re.match(r'<@&([0-9]{15,20})>$', argument)\n if match:\n result = guild.get_role(int(match.group(1)))\n else:\n result = discord.utils.get(guild._roles.values(), name=argument)\n\n if result is None:\n raise RoleNotFound(argument)\n return result\n\n\nclass GameConverter(Converter[discord.Game]):\n \"\"\"Converts to a :class:`~discord.Game`.\"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.Game:\n return discord.Game(name=argument)\n\n\nclass InviteConverter(Converter[discord.Invite]):\n \"\"\"Converts to a :class:`~discord.Invite`.\n\n This is done via an HTTP request using :meth:`.Bot.fetch_invite`.\n\n .. versionchanged:: 1.5\n Raise :exc:`.BadInviteArgument` instead of generic :exc:`.BadArgument`\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.Invite:\n try:\n invite = await ctx.bot.fetch_invite(argument)\n return invite\n except Exception as exc:\n raise BadInviteArgument(argument) from exc\n\n\nclass GuildConverter(IDConverter[discord.Guild]):\n \"\"\"Converts to a :class:`~discord.Guild`.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by name. (There is no disambiguation for Guilds with multiple matching names).\n\n .. versionadded:: 1.7\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.Guild:\n match = self._get_id_match(argument)\n result = None\n\n if match is not None:\n guild_id = int(match.group(1))\n result = ctx.bot.get_guild(guild_id)\n\n if result is None:\n result = discord.utils.get(ctx.bot.guilds, name=argument)\n\n if result is None:\n raise GuildNotFound(argument)\n return result\n\n\nclass EmojiConverter(IDConverter[discord.Emoji]):\n \"\"\"Converts to a :class:`~discord.Emoji`.\n\n All lookups are done for the local guild first, if available. If that lookup\n fails, then it checks the client's global cache.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by extracting ID from the emoji.\n 3. Lookup by name\n\n .. versionchanged:: 1.5\n Raise :exc:`.EmojiNotFound` instead of generic :exc:`.BadArgument`\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.Emoji:\n match = self._get_id_match(argument) or re.match(r'$', argument)\n result = None\n bot = ctx.bot\n guild = ctx.guild\n\n if match is None:\n # Try to get the emoji by name. Try local guild first.\n if guild:\n result = discord.utils.get(guild.emojis, name=argument)\n\n if result is None:\n result = discord.utils.get(bot.emojis, name=argument)\n else:\n emoji_id = int(match.group(1))\n\n # Try to look up emoji by id.\n result = bot.get_emoji(emoji_id)\n\n if result is None:\n raise EmojiNotFound(argument)\n\n return result\n\n\nclass PartialEmojiConverter(Converter[discord.PartialEmoji]):\n \"\"\"Converts to a :class:`~discord.PartialEmoji`.\n\n This is done by extracting the animated flag, name and ID from the emoji.\n\n .. versionchanged:: 1.5\n Raise :exc:`.PartialEmojiConversionFailure` instead of generic :exc:`.BadArgument`\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.PartialEmoji:\n match = re.match(r'<(a?):([a-zA-Z0-9\\_]{1,32}):([0-9]{15,20})>$', argument)\n\n if match:\n emoji_animated = bool(match.group(1))\n emoji_name = match.group(2)\n emoji_id = int(match.group(3))\n\n return discord.PartialEmoji.with_state(\n ctx.bot._connection, animated=emoji_animated, name=emoji_name, id=emoji_id\n )\n\n raise PartialEmojiConversionFailure(argument)\n\n\nclass GuildStickerConverter(IDConverter[discord.GuildSticker]):\n \"\"\"Converts to a :class:`~discord.GuildSticker`.\n\n All lookups are done for the local guild first, if available. If that lookup\n fails, then it checks the client's global cache.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by name.\n\n .. versionadded:: 2.0\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.GuildSticker:\n match = self._get_id_match(argument)\n result = None\n bot = ctx.bot\n guild = ctx.guild\n\n if match is None:\n # Try to get the sticker by name. Try local guild first.\n if guild:\n result = discord.utils.get(guild.stickers, name=argument)\n\n if result is None:\n result = discord.utils.get(bot.stickers, name=argument)\n else:\n sticker_id = int(match.group(1))\n\n # Try to look up sticker by id.\n result = bot.get_sticker(sticker_id)\n\n if result is None:\n raise GuildStickerNotFound(argument)\n\n return result\n\n\nclass ScheduledEventConverter(IDConverter[discord.ScheduledEvent]):\n \"\"\"Converts to a :class:`~discord.ScheduledEvent`.\n\n Lookups are done for the local guild if available. Otherwise, for a DM context,\n lookup is done by the global cache.\n\n The lookup strategy is as follows (in order):\n\n 1. Lookup by ID.\n 2. Lookup by url.\n 3. Lookup by name.\n\n .. versionadded:: 2.0\n \"\"\"\n\n async def convert(self, ctx: Context[BotT], argument: str) -> discord.ScheduledEvent:\n guild = ctx.guild\n match = self._get_id_match(argument)\n result = None\n\n if match:\n # ID match\n event_id = int(match.group(1))\n if guild:\n result = guild.get_scheduled_event(event_id)\n else:\n for guild in ctx.bot.guilds:\n result = guild.get_scheduled_event(event_id)\n if result:\n break\n else:\n pattern = (\n r'https?://(?:(ptb|canary|www)\\.)?discord\\.com/events/'\n r'(?P[0-9]{15,20})/'\n r'(?P[0-9]{15,20})$'\n )\n match = re.match(pattern, argument, flags=re.I)\n if match:\n # URL match\n guild = ctx.bot.get_guild(int(match.group('guild_id')))\n\n if guild:\n event_id = int(match.group('event_id'))\n result = guild.get_scheduled_event(event_id)\n else:\n # lookup by name\n if guild:\n result = discord.utils.get(guild.scheduled_events, name=argument)\n else:\n for guild in ctx.bot.guilds:\n result = discord.utils.get(guild.scheduled_events, name=argument)\n if result:\n break\n if result is None:\n raise ScheduledEventNotFound(argument)\n\n return result\n\n\nclass clean_content(Converter[str]):\n \"\"\"Converts the argument to mention scrubbed version of\n said content.\n\n This behaves similarly to :attr:`~discord.Message.clean_content`.\n\n Attributes\n ------------\n fix_channel_mentions: :class:`bool`\n Whether to clean channel mentions.\n use_nicknames: :class:`bool`\n Whether to use nicknames when transforming mentions.\n escape_markdown: :class:`bool`\n Whether to also escape special markdown characters.\n remove_markdown: :class:`bool`\n Whether to also remove special markdown characters. This option is not supported with ``escape_markdown``\n\n .. versionadded:: 1.7\n \"\"\"\n\n def __init__(\n self,\n *,\n fix_channel_mentions: bool = False,\n use_nicknames: bool = True,\n escape_markdown: bool = False,\n remove_markdown: bool = False,\n ) -> None:\n self.fix_channel_mentions = fix_channel_mentions\n self.use_nicknames = use_nicknames\n self.escape_markdown = escape_markdown\n self.remove_markdown = remove_markdown\n\n async def convert(self, ctx: Context[BotT], argument: str) -> str:\n msg = ctx.message\n\n if ctx.guild:\n\n def resolve_member(id: int) -> str:\n m = _utils_get(msg.mentions, id=id) or ctx.guild.get_member(id) # type: ignore\n return f'@{m.display_name if self.use_nicknames else m.name}' if m else '@deleted-user'\n\n def resolve_role(id: int) -> str:\n r = _utils_get(msg.role_mentions, id=id) or ctx.guild.get_role(id) # type: ignore\n return f'@{r.name}' if r else '@deleted-role'\n\n else:\n\n def resolve_member(id: int) -> str:\n m = _utils_get(msg.mentions, id=id) or ctx.bot.get_user(id)\n return f'@{m.display_name}' if m else '@deleted-user'\n\n def resolve_role(id: int) -> str:\n return '@deleted-role'\n\n if self.fix_channel_mentions and ctx.guild:\n\n def resolve_channel(id: int) -> str:\n c = ctx.guild._resolve_channel(id) # type: ignore\n return f'#{c.name}' if c else '#deleted-channel'\n\n else:\n\n def resolve_channel(id: int) -> str:\n return f'<#{id}>'\n\n transforms = {\n '@': resolve_member,\n '@!': resolve_member,\n '#': resolve_channel,\n '@&': resolve_role,\n }\n\n def repl(match: re.Match) -> str:\n type = match[1]\n id = int(match[2])\n transformed = transforms[type](id)\n return transformed\n\n result = re.sub(r'<(@[!&]?|#)([0-9]{15,20})>', repl, argument)\n if self.escape_markdown:\n result = discord.utils.escape_markdown(result)\n elif self.remove_markdown:\n result = discord.utils.remove_markdown(result)\n\n # Completely ensure no mentions escape:\n return discord.utils.escape_mentions(result)\n\n\nclass Greedy(List[T]):\n r\"\"\"A special converter that greedily consumes arguments until it can't.\n As a consequence of this behaviour, most input errors are silently discarded,\n since it is used as an indicator of when to stop parsing.\n\n When a parser error is met the greedy converter stops converting, undoes the\n internal string parsing routine, and continues parsing regularly.\n\n For example, in the following code:\n\n .. code-block:: python3\n\n @commands.command()\n async def test(ctx, numbers: Greedy[int], reason: str):\n await ctx.send(\"numbers: {}, reason: {}\".format(numbers, reason))\n\n An invocation of ``[p]test 1 2 3 4 5 6 hello`` would pass ``numbers`` with\n ``[1, 2, 3, 4, 5, 6]`` and ``reason`` with ``hello``\\.\n\n For more information, check :ref:`ext_commands_special_converters`.\n\n .. note::\n\n For interaction based contexts the conversion error is propagated\n rather than swallowed due to the difference in user experience with\n application commands.\n \"\"\"\n\n __slots__ = ('converter',)\n\n def __init__(self, *, converter: T) -> None:\n self.converter: T = converter\n\n def __repr__(self) -> str:\n converter = getattr(self.converter, '__name__', repr(self.converter))\n return f'Greedy[{converter}]'\n\n def __class_getitem__(cls, params: Union[Tuple[T], T]) -> Greedy[T]:\n if not isinstance(params, tuple):\n params = (params,)\n if len(params) != 1:\n raise TypeError('Greedy[...] only takes a single argument')\n converter = params[0]\n\n args = getattr(converter, '__args__', ())\n if discord.utils.PY_310 and converter.__class__ is types.UnionType: # type: ignore\n converter = Union[args] # type: ignore\n\n origin = getattr(converter, '__origin__', None)\n\n if not (callable(converter) or isinstance(converter, Converter) or origin is not None):\n raise TypeError('Greedy[...] expects a type or a Converter instance.')\n\n if converter in (str, type(None)) or origin is Greedy:\n raise TypeError(f'Greedy[{converter.__name__}] is invalid.') # type: ignore\n\n if origin is Union and type(None) in args:\n raise TypeError(f'Greedy[{converter!r}] is invalid.')\n\n return cls(converter=converter)\n\n @property\n def constructed_converter(self) -> Any:\n # Only construct a converter once in order to maintain state between convert calls\n if (\n inspect.isclass(self.converter)\n and issubclass(self.converter, Converter)\n and not inspect.ismethod(self.converter.convert)\n ):\n return self.converter()\n return self.converter\n\n\nif TYPE_CHECKING:\n from typing_extensions import Annotated as Range\nelse:\n\n class Range:\n \"\"\"A special converter that can be applied to a parameter to require a numeric\n or string type to fit within the range provided.\n\n During type checking time this is equivalent to :obj:`typing.Annotated` so type checkers understand\n the intent of the code.\n\n Some example ranges:\n\n - ``Range[int, 10]`` means the minimum is 10 with no maximum.\n - ``Range[int, None, 10]`` means the maximum is 10 with no minimum.\n - ``Range[int, 1, 10]`` means the minimum is 1 and the maximum is 10.\n - ``Range[float, 1.0, 5.0]`` means the minimum is 1.0 and the maximum is 5.0.\n - ``Range[str, 1, 10]`` means the minimum length is 1 and the maximum length is 10.\n\n Inside a :class:`HybridCommand` this functions equivalently to :class:`discord.app_commands.Range`.\n\n If the value cannot be converted to the provided type or is outside the given range,\n :class:`~.ext.commands.BadArgument` or :class:`~.ext.commands.RangeError` is raised to\n the appropriate error handlers respectively.\n\n .. versionadded:: 2.0\n\n Examples\n ----------\n\n .. code-block:: python3\n\n @bot.command()\n async def range(ctx: commands.Context, value: commands.Range[int, 10, 12]):\n await ctx.send(f'Your value is {value}')\n \"\"\"\n\n def __init__(\n self,\n *,\n annotation: Any,\n min: Optional[Union[int, float]] = None,\n max: Optional[Union[int, float]] = None,\n ) -> None:\n self.annotation: Any = annotation\n self.min: Optional[Union[int, float]] = min\n self.max: Optional[Union[int, float]] = max\n\n if min and max and min > max:\n raise TypeError('minimum cannot be larger than maximum')\n\n async def convert(self, ctx: Context[BotT], value: str) -> Union[int, float]:\n try:\n count = converted = self.annotation(value)\n except ValueError:\n raise BadArgument(\n f'Converting to \"{self.annotation.__name__}\" failed for parameter \"{ctx.current_parameter.name}\".'\n )\n\n if self.annotation is str:\n count = len(value)\n\n if (self.min is not None and count < self.min) or (self.max is not None and count > self.max):\n raise RangeError(converted, minimum=self.min, maximum=self.max)\n\n return converted\n\n def __call__(self) -> None:\n # Trick to allow it inside typing.Union\n pass\n\n def __or__(self, rhs) -> Any:\n return Union[self, rhs]\n\n def __repr__(self) -> str:\n return f'{self.__class__.__name__}[{self.annotation.__name__}, {self.min}, {self.max}]'\n\n def __class_getitem__(cls, obj) -> Range:\n if not isinstance(obj, tuple):\n raise TypeError(f'expected tuple for arguments, received {obj.__class__.__name__} instead')\n\n if len(obj) == 2:\n obj = (*obj, None)\n elif len(obj) != 3:\n raise TypeError('Range accepts either two or three arguments with the first being the type of range.')\n\n annotation, min, max = obj\n\n if min is None and max is None:\n raise TypeError('Range must not be empty')\n\n if min is not None and max is not None:\n # At this point max and min are both not none\n if type(min) != type(max):\n raise TypeError('Both min and max in Range must be the same type')\n\n if annotation not in (int, float, str):\n raise TypeError(f'expected int, float, or str as range type, received {annotation!r} instead')\n\n if annotation in (str, int):\n cast = int\n else:\n cast = float\n\n return cls(\n annotation=annotation,\n min=cast(min) if min is not None else None,\n max=cast(max) if max is not None else None,\n )\n\n\ndef _convert_to_bool(argument: str) -> bool:\n lowered = argument.lower()\n if lowered in ('yes', 'y', 'true', 't', '1', 'enable', 'on'):\n return True\n elif lowered in ('no', 'n', 'false', 'f', '0', 'disable', 'off'):\n return False\n else:\n raise BadBoolArgument(lowered)\n\n\n_GenericAlias = type(List[T]) # type: ignore\n\n\ndef is_generic_type(tp: Any, *, _GenericAlias: type = _GenericAlias) -> bool:\n return isinstance(tp, type) and issubclass(tp, Generic) or isinstance(tp, _GenericAlias)\n\n\nCONVERTER_MAPPING: Dict[type, Any] = {\n discord.Object: ObjectConverter,\n discord.Member: MemberConverter,\n discord.User: UserConverter,\n discord.Message: MessageConverter,\n discord.PartialMessage: PartialMessageConverter,\n discord.TextChannel: TextChannelConverter,\n discord.Invite: InviteConverter,\n discord.Guild: GuildConverter,\n discord.Role: RoleConverter,\n discord.Game: GameConverter,\n discord.Colour: ColourConverter,\n discord.VoiceChannel: VoiceChannelConverter,\n discord.StageChannel: StageChannelConverter,\n discord.Emoji: EmojiConverter,\n discord.PartialEmoji: PartialEmojiConverter,\n discord.CategoryChannel: CategoryChannelConverter,\n discord.Thread: ThreadConverter,\n discord.abc.GuildChannel: GuildChannelConverter,\n discord.GuildSticker: GuildStickerConverter,\n discord.ScheduledEvent: ScheduledEventConverter,\n discord.ForumChannel: ForumChannelConverter,\n}\n\n\nasync def _actual_conversion(ctx: Context[BotT], converter: Any, argument: str, param: inspect.Parameter):\n if converter is bool:\n return _convert_to_bool(argument)\n\n try:\n module = converter.__module__\n except AttributeError:\n pass\n else:\n if module is not None and (module.startswith('discord.') and not module.endswith('converter')):\n converter = CONVERTER_MAPPING.get(converter, converter)\n\n try:\n if inspect.isclass(converter) and issubclass(converter, Converter):\n if inspect.ismethod(converter.convert):\n return await converter.convert(ctx, argument)\n else:\n return await converter().convert(ctx, argument)\n elif isinstance(converter, Converter):\n return await converter.convert(ctx, argument) # type: ignore\n except CommandError:\n raise\n except Exception as exc:\n raise ConversionError(converter, exc) from exc # type: ignore\n\n try:\n return converter(argument)\n except CommandError:\n raise\n except Exception as exc:\n try:\n name = converter.__name__\n except AttributeError:\n name = converter.__class__.__name__\n\n raise BadArgument(f'Converting to \"{name}\" failed for parameter \"{param.name}\".') from exc\n\n\n@overload\nasync def run_converters(\n ctx: Context[BotT], converter: Union[Type[Converter[T]], Converter[T]], argument: str, param: Parameter\n) -> T:\n ...\n\n\n@overload\nasync def run_converters(ctx: Context[BotT], converter: Any, argument: str, param: Parameter) -> Any:\n ...\n\n\nasync def run_converters(ctx: Context[BotT], converter: Any, argument: str, param: Parameter) -> Any:\n \"\"\"|coro|\n\n Runs converters for a given converter, argument, and parameter.\n\n This function does the same work that the library does under the hood.\n\n .. versionadded:: 2.0\n\n Parameters\n ------------\n ctx: :class:`Context`\n The invocation context to run the converters under.\n converter: Any\n The converter to run, this corresponds to the annotation in the function.\n argument: :class:`str`\n The argument to convert to.\n param: :class:`Parameter`\n The parameter being converted. This is mainly for error reporting.\n\n Raises\n -------\n CommandError\n The converter failed to convert.\n\n Returns\n --------\n Any\n The resulting conversion.\n \"\"\"\n origin = getattr(converter, '__origin__', None)\n\n if origin is Union:\n errors = []\n _NoneType = type(None)\n union_args = converter.__args__\n for conv in union_args:\n # if we got to this part in the code, then the previous conversions have failed\n # so we should just undo the view, return the default, and allow parsing to continue\n # with the other parameters\n if conv is _NoneType and param.kind != param.VAR_POSITIONAL:\n ctx.view.undo()\n return None if param.required else await param.get_default(ctx)\n\n try:\n value = await run_converters(ctx, conv, argument, param)\n except CommandError as exc:\n errors.append(exc)\n else:\n return value\n\n # if we're here, then we failed all the converters\n raise BadUnionArgument(param, union_args, errors)\n\n if origin is Literal:\n errors = []\n conversions = {}\n literal_args = converter.__args__\n for literal in literal_args:\n literal_type = type(literal)\n try:\n value = conversions[literal_type]\n except KeyError:\n try:\n value = await _actual_conversion(ctx, literal_type, argument, param)\n except CommandError as exc:\n errors.append(exc)\n conversions[literal_type] = object()\n continue\n else:\n conversions[literal_type] = value\n\n if value == literal:\n return value\n\n # if we're here, then we failed to match all the literals\n raise BadLiteralArgument(param, literal_args, errors, argument)\n\n # This must be the last if-clause in the chain of origin checking\n # Nearly every type is a generic type within the typing library\n # So care must be taken to make sure a more specialised origin handle\n # isn't overwritten by the widest if clause\n if origin is not None and is_generic_type(converter):\n converter = origin\n\n return await _actual_conversion(ctx, converter, argument, param)\n" }, { "path": "discord/ext/commands/cooldowns.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\n\nfrom __future__ import annotations\n\n\nfrom typing import Any, Callable, Deque, Dict, Optional, Union, Generic, TypeVar, TYPE_CHECKING\nfrom discord.enums import Enum\nfrom discord.abc import PrivateChannel\nimport time\nimport asyncio\nfrom collections import deque\n\nfrom .errors import MaxConcurrencyReached\nfrom .context import Context\nfrom discord.app_commands import Cooldown as Cooldown\n\nif TYPE_CHECKING:\n from typing_extensions import Self\n\n from ...message import Message\n\n__all__ = (\n 'BucketType',\n 'Cooldown',\n 'CooldownMapping',\n 'DynamicCooldownMapping',\n 'MaxConcurrency',\n)\n\nT_contra = TypeVar('T_contra', contravariant=True)\n\n\nclass BucketType(Enum):\n default = 0\n user = 1\n guild = 2\n channel = 3\n member = 4\n category = 5\n role = 6\n\n def get_key(self, msg: Union[Message, Context[Any]]) -> Any:\n if self is BucketType.user:\n return msg.author.id\n elif self is BucketType.guild:\n return (msg.guild or msg.author).id\n elif self is BucketType.channel:\n return msg.channel.id\n elif self is BucketType.member:\n return ((msg.guild and msg.guild.id), msg.author.id)\n elif self is BucketType.category:\n return (msg.channel.category or msg.channel).id # type: ignore\n elif self is BucketType.role:\n # we return the channel id of a private-channel as there are only roles in guilds\n # and that yields the same result as for a guild with only the @everyone role\n # NOTE: PrivateChannel doesn't actually have an id attribute but we assume we are\n # receiving a DMChannel or GroupChannel which inherit from PrivateChannel and do\n return (msg.channel if isinstance(msg.channel, PrivateChannel) else msg.author.top_role).id # type: ignore\n\n def __call__(self, msg: Union[Message, Context[Any]]) -> Any:\n return self.get_key(msg)\n\n\nclass CooldownMapping(Generic[T_contra]):\n def __init__(\n self,\n original: Optional[Cooldown],\n type: Callable[[T_contra], Any],\n ) -> None:\n if not callable(type):\n raise TypeError('Cooldown type must be a BucketType or callable')\n\n self._cache: Dict[Any, Cooldown] = {}\n self._cooldown: Optional[Cooldown] = original\n self._type: Callable[[T_contra], Any] = type\n\n def copy(self) -> CooldownMapping[T_contra]:\n ret = CooldownMapping(self._cooldown, self._type)\n ret._cache = self._cache.copy()\n return ret\n\n @property\n def valid(self) -> bool:\n return self._cooldown is not None\n\n @property\n def type(self) -> Callable[[T_contra], Any]:\n return self._type\n\n @classmethod\n def from_cooldown(cls, rate: float, per: float, type: Callable[[T_contra], Any]) -> Self:\n return cls(Cooldown(rate, per), type)\n\n def _bucket_key(self, msg: T_contra) -> Any:\n return self._type(msg)\n\n def _verify_cache_integrity(self, current: Optional[float] = None) -> None:\n # we want to delete all cache objects that haven't been used\n # in a cooldown window. e.g. if we have a command that has a\n # cooldown of 60s and it has not been used in 60s then that key should be deleted\n current = current or time.time()\n dead_keys = [k for k, v in self._cache.items() if current > v._last + v.per]\n for k in dead_keys:\n del self._cache[k]\n\n def create_bucket(self, message: T_contra) -> Cooldown:\n return self._cooldown.copy() # type: ignore\n\n def get_bucket(self, message: T_contra, current: Optional[float] = None) -> Optional[Cooldown]:\n if self._type is BucketType.default:\n return self._cooldown\n\n self._verify_cache_integrity(current)\n key = self._bucket_key(message)\n if key not in self._cache:\n bucket = self.create_bucket(message)\n if bucket is not None:\n self._cache[key] = bucket\n else:\n bucket = self._cache[key]\n\n return bucket\n\n def update_rate_limit(self, message: T_contra, current: Optional[float] = None, tokens: int = 1) -> Optional[float]:\n bucket = self.get_bucket(message, current)\n if bucket is None:\n return None\n return bucket.update_rate_limit(current, tokens=tokens)\n\n\nclass DynamicCooldownMapping(CooldownMapping[T_contra]):\n def __init__(\n self,\n factory: Callable[[T_contra], Optional[Cooldown]],\n type: Callable[[T_contra], Any],\n ) -> None:\n super().__init__(None, type)\n self._factory: Callable[[T_contra], Optional[Cooldown]] = factory\n\n def copy(self) -> DynamicCooldownMapping[T_contra]:\n ret = DynamicCooldownMapping(self._factory, self._type)\n ret._cache = self._cache.copy()\n return ret\n\n @property\n def valid(self) -> bool:\n return True\n\n def create_bucket(self, message: T_contra) -> Optional[Cooldown]:\n return self._factory(message)\n\n\nclass _Semaphore:\n \"\"\"This class is a version of a semaphore.\n\n If you're wondering why asyncio.Semaphore isn't being used,\n it's because it doesn't expose the internal value. This internal\n value is necessary because I need to support both `wait=True` and\n `wait=False`.\n\n An asyncio.Queue could have been used to do this as well -- but it is\n not as inefficient since internally that uses two queues and is a bit\n overkill for what is basically a counter.\n \"\"\"\n\n __slots__ = ('value', 'loop', '_waiters')\n\n def __init__(self, number: int) -> None:\n self.value: int = number\n self.loop: asyncio.AbstractEventLoop = asyncio.get_running_loop()\n self._waiters: Deque[asyncio.Future] = deque()\n\n def __repr__(self) -> str:\n return f'<_Semaphore value={self.value} waiters={len(self._waiters)}>'\n\n def locked(self) -> bool:\n return self.value == 0\n\n def is_active(self) -> bool:\n return len(self._waiters) > 0\n\n def wake_up(self) -> None:\n while self._waiters:\n future = self._waiters.popleft()\n if not future.done():\n future.set_result(None)\n return\n\n async def acquire(self, *, wait: bool = False) -> bool:\n if not wait and self.value <= 0:\n # signal that we're not acquiring\n return False\n\n while self.value <= 0:\n future = self.loop.create_future()\n self._waiters.append(future)\n try:\n await future\n except:\n future.cancel()\n if self.value > 0 and not future.cancelled():\n self.wake_up()\n raise\n\n self.value -= 1\n return True\n\n def release(self) -> None:\n self.value += 1\n self.wake_up()\n\n\nclass MaxConcurrency:\n __slots__ = ('number', 'per', 'wait', '_mapping')\n\n def __init__(self, number: int, *, per: BucketType, wait: bool) -> None:\n self._mapping: Dict[Any, _Semaphore] = {}\n self.per: BucketType = per\n self.number: int = number\n self.wait: bool = wait\n\n if number <= 0:\n raise ValueError('max_concurrency \\'number\\' cannot be less than 1')\n\n if not isinstance(per, BucketType):\n raise TypeError(f'max_concurrency \\'per\\' must be of type BucketType not {type(per)!r}')\n\n def copy(self) -> Self:\n return self.__class__(self.number, per=self.per, wait=self.wait)\n\n def __repr__(self) -> str:\n return f''\n\n def get_key(self, message: Union[Message, Context[Any]]) -> Any:\n return self.per.get_key(message)\n\n async def acquire(self, message: Union[Message, Context[Any]]) -> None:\n key = self.get_key(message)\n\n try:\n sem = self._mapping[key]\n except KeyError:\n self._mapping[key] = sem = _Semaphore(self.number)\n\n acquired = await sem.acquire(wait=self.wait)\n if not acquired:\n raise MaxConcurrencyReached(self.number, self.per)\n\n async def release(self, message: Union[Message, Context[Any]]) -> None:\n # Technically there's no reason for this function to be async\n # But it might be more useful in the future\n key = self.get_key(message)\n\n try:\n sem = self._mapping[key]\n except KeyError:\n # ...? peculiar\n return\n else:\n sem.release()\n\n if sem.value >= self.number and not sem.is_active():\n del self._mapping[key]\n" }, { "path": "discord/ext/commands/core.py", "content": "\"\"\"\nThe MIT License (MIT)\n\nCopyright (c) 2015-present Rapptz\n\nPermission is hereby granted, free of charge, to any person obtaining a\ncopy of this software and associated documentation files (the \"Software\"),\nto deal in the Software without restriction, including without limitation\nthe rights to use, copy, modify, merge, publish, distribute, sublicense,\nand/or sell copies of the Software, and to permit persons to whom the\nSoftware is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS\nOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\nDEALINGS IN THE SOFTWARE.\n\"\"\"\nfrom __future__ import annotations\n\nimport asyncio\nimport datetime\nimport functools\nimport inspect\nfrom typing import (\n TYPE_CHECKING,\n Any,\n Callable,\n Dict,\n Generator,\n Generic,\n List,\n Literal,\n Optional,\n Set,\n Tuple,\n Type,\n TypeVar,\n Union,\n overload,\n)\nimport re\n\nimport discord\n\nfrom ._types import _BaseCommand, CogT\nfrom .cog import Cog\nfrom .context import Context\nfrom .converter import Greedy, run_converters\nfrom .cooldowns import BucketType, Cooldown, CooldownMapping, DynamicCooldownMapping, MaxConcurrency\nfrom .errors import *\nfrom .parameters import Parameter, Signature\nfrom discord.app_commands.commands import NUMPY_DOCSTRING_ARG_REGEX\n\nif TYPE_CHECKING:\n from typing_extensions import Concatenate, ParamSpec, Self\n\n from ._types import BotT, Check, ContextT, Coro, CoroFunc, Error, Hook, UserCheck\n\n\n__all__ = (\n 'Command',\n 'Group',\n 'GroupMixin',\n 'command',\n 'group',\n 'has_role',\n 'has_permissions',\n 'has_any_role',\n 'check',\n 'check_any',\n 'before_invoke',\n 'after_invoke',\n 'bot_has_role',\n 'bot_has_permissions',\n 'bot_has_any_role',\n 'cooldown',\n 'dynamic_cooldown',\n 'max_concurrency',\n 'dm_only',\n 'guild_only',\n 'is_owner',\n 'is_nsfw',\n 'has_guild_permissions',\n 'bot_has_guild_permissions',\n)\n\nMISSING: Any = discord.utils.MISSING\n\nT = TypeVar('T')\nCommandT = TypeVar('CommandT', bound='Command[Any, ..., Any]')\n# CHT = TypeVar('CHT', bound='Check')\nGroupT = TypeVar('GroupT', bound='Group[Any, ..., Any]')\n\nif TYPE_CHECKING:\n P = ParamSpec('P')\nelse:\n P = TypeVar('P')\n\n\ndef unwrap_function(function: Callable[..., Any], /) -> Callable[..., Any]:\n partial = functools.partial\n while True:\n if hasattr(function, '__wrapped__'):\n function = function.__wrapped__\n elif isinstance(function, partial):\n function = function.func\n else:\n return function\n\n\ndef get_signature_parameters(\n function: Callable[..., Any],\n globalns: Dict[str, Any],\n /,\n *,\n skip_parameters: Optional[int] = None,\n) -> Dict[str, Parameter]:\n signature = Signature.from_callable(function)\n params: Dict[str, Parameter] = {}\n cache: Dict[str, Any] = {}\n eval_annotation = discord.utils.evaluate_annotation\n required_params = discord.utils.is_inside_class(function) + 1 if skip_parameters is None else skip_parameters\n if len(signature.parameters) < required_params:\n raise TypeError(f'Command signature requires at least {required_params - 1} parameter(s)')\n\n iterator = iter(signature.parameters.items())\n for _ in range(0, required_params):\n next(iterator)\n\n for name, parameter in iterator:\n default = parameter.default\n if isinstance(default, Parameter): # update from the default\n if default.annotation is not Parameter.empty:\n # There are a few cases to care about here.\n # x: TextChannel = commands.CurrentChannel\n # x = commands.CurrentChannel\n # In both of these cases, the default parameter has an explicit annotation\n # but in the second case it's only used as the fallback.\n if default._fallback:\n if parameter.annotation is Parameter.empty:\n parameter._annotation = default.annotation\n else:\n parameter._annotation = default.annotation\n\n parameter._default = default.default\n parameter._description = default._description\n parameter._displayed_default = default._displayed_default\n parameter._displayed_name = default._displayed_name\n\n annotation = parameter.annotation\n\n if annotation is None:\n params[name] = parameter.replace(annotation=type(None))\n continue\n\n annotation = eval_annotation(annotation, globalns, globalns, cache)\n if annotation is Greedy:\n raise TypeError('Unparameterized Greedy[...] is disallowed in signature.')\n\n params[name] = parameter.replace(annotation=annotation)\n\n return params\n\n\nPARAMETER_HEADING_REGEX = re.compile(r'Parameters?\\n---+\\n', re.I)\n\n\ndef _fold_text(input: str) -> str:\n \"\"\"Turns a single newline into a space, and multiple newlines into a newline.\"\"\"\n\n def replacer(m: re.Match[str]) -> str:\n if len(m.group()) <= 1:\n return ' '\n return '\\n'\n\n return re.sub(r'\\n+', replacer, inspect.cleandoc(input))\n\n\ndef extract_descriptions_from_docstring(function: Callable[..., Any], params: Dict[str, Parameter], /) -> Optional[str]:\n docstring = inspect.getdoc(function)\n\n if docstring is None:\n return None\n\n divide = PARAMETER_HEADING_REGEX.split(docstring, 1)\n if len(divide) == 1:\n return docstring\n\n description, param_docstring = divide\n for match in NUMPY_DOCSTRING_ARG_REGEX.finditer(param_docstring):\n name = match.group('name')\n\n if name not in params:\n is_display_name = discord.utils.get(params.values(), displayed_name=name)\n if is_display_name:\n name = is_display_name.name\n else:\n continue\n\n param = params[name]\n if param.description is None:\n param._description = _fold_text(match.group('description'))\n\n return _fold_text(description.strip())\n\n\ndef wrap_callback(coro: Callable[P, Coro[T]], /) -> Callable[P, Coro[Optional[T]]]:\n @functools.wraps(coro)\n async def wrapped(*args: P.args, **kwargs: P.kwargs) -> Optional[T]:\n try:\n ret = await coro(*args, **kwargs)\n except CommandError:\n raise\n except asyncio.CancelledError:\n return\n except Exception as exc:\n raise CommandInvokeError(exc) from exc\n return ret\n\n return wrapped\n\n\ndef hooked_wrapped_callback(\n command: Command[Any, ..., Any], ctx: Context[BotT], coro: Callable[P, Coro[T]], /\n) -> Callable[P, Coro[Optional[T]]]:\n @functools.wraps(coro)\n async def wrapped(*args: P.args, **kwargs: P.kwargs) -> Optional[T]:\n try:\n ret = await coro(*args, **kwargs)\n except CommandError:\n ctx.command_failed = True\n raise\n except asyncio.CancelledError:\n ctx.command_failed = True\n return\n except Exception as exc:\n ctx.command_failed = True\n raise CommandInvokeError(exc) from exc\n finally:\n if command._max_concurrency is not None:\n await command._max_concurrency.release(ctx.message)\n\n await command.call_after_hooks(ctx)\n return ret\n\n return wrapped\n\n\nclass _CaseInsensitiveDict(dict):\n def __contains__(self, k):\n return super().__contains__(k.casefold())\n\n def __delitem__(self, k):\n return super().__delitem__(k.casefold())\n\n def __getitem__(self, k):\n return super().__getitem__(k.casefold())\n\n def get(self, k, default=None):\n return super().get(k.casefold(), default)\n\n def pop(self, k, default=None):\n return super().pop(k.casefold(), default)\n\n def __setitem__(self, k, v):\n super().__setitem__(k.casefold(), v)\n\n\nclass _AttachmentIterator:\n def __init__(self, data: List[discord.Attachment]):\n self.data: List[discord.Attachment] = data\n self.index: int = 0\n\n def __iter__(self) -> Self:\n return self\n\n def __next__(self) -> discord.Attachment:\n try:\n value = self.data[self.index]\n except IndexError:\n raise StopIteration\n else:\n self.index += 1\n return value\n\n def is_empty(self) -> bool:\n return self.index >= len(self.data)\n\n\nclass Command(_BaseCommand, Generic[CogT, P, T]):\n r\"\"\"A class that implements the protocol for a bot text command.\n\n These are not created manually, instead they are created via the\n decorator or functional interface.\n\n Attributes\n -----------\n name: :class:`str`\n The name of the command.\n callback: :ref:`coroutine `\n The coroutine that is executed when the command is called.\n help: Optional[:class:`str`]\n The long help text for the command.\n brief: Optional[:class:`str`]\n The short help text for the command.\n usage: Optional[:class:`str`]\n A replacement for arguments in the default help text.\n aliases: Union[List[:class:`str`], Tuple[:class:`str`]]\n The list of aliases the command can be invoked under.\n enabled: :class:`bool`\n A boolean that indicates if the command is currently enabled.\n If the command is invoked while it is disabled, then\n :exc:`.DisabledCommand` is raised to the :func:`.on_command_error`\n event. Defaults to ``True``.\n parent: Optional[:class:`Group`]\n The parent group that this command belongs to. ``None`` if there\n isn't one.\n cog: Optional[:class:`Cog`]\n The cog that this command belongs to. ``None`` if there isn't one.\n checks: List[Callable[[:class:`.Context`], :class:`bool`]]\n A list of predicates that verifies if the command could be executed\n with the given :class:`.Context` as the sole parameter. If an exception\n is necessary to be thrown to signal failure, then one inherited from\n :exc:`.CommandError` should be used. Note that if the checks fail then\n :exc:`.CheckFailure` exception is raised to the :func:`.on_command_error`\n event.\n description: :class:`str`\n The message prefixed into the default help command.\n hidden: :class:`bool`\n If ``True``\\, the default help command does not show this in the\n help output.\n rest_is_raw: :class:`bool`\n If ``False`` and a keyword-only argument is provided then the keyword\n only argument is stripped and handled as if it was a regular argument\n that handles :exc:`.MissingRequiredArgument` and default values in a\n regular matter rather than passing the rest completely raw. If ``True``\n then the keyword-only argument will pass in the rest of the arguments\n in a completely raw matter. Defaults to ``False``.\n invoked_subcommand: Optional[:class:`Command`]\n The subcommand that was invoked, if any.\n require_var_positional: :class:`bool`\n If ``True`` and a variadic positional argument is specified, requires\n the user to specify at least one argument. Defaults to ``False``.\n\n .. versionadded:: 1.5\n\n ignore_extra: :class:`bool`\n If ``True``\\, ignores extraneous strings passed to a command if all its\n requirements are met (e.g. ``?foo a b c`` when only expecting ``a``\n and ``b``). Otherwise :func:`.on_command_error` and local error handlers\n are called with :exc:`.TooManyArguments`. Defaults to ``True``.\n cooldown_after_parsing: :class:`bool`\n If ``True``\\, cooldown processing is done after argument parsing,\n which calls converters. If ``False`` then cooldown processing is done\n first and then the converters are called second. Defaults to ``False``.\n extras: :class:`dict`\n A dict of user provided extras to attach to the Command.\n\n .. note::\n This object may be copied by the library.\n\n\n .. versionadded:: 2.0\n \"\"\"\n __original_kwargs__: Dict[str, Any]\n\n def __new__(cls, *args: Any, **kwargs: Any) -> Self:\n # if you're wondering why this is done, it's because we need to ensure\n # we have a complete original copy of **kwargs even for classes that\n # mess with it by popping before delegating to the subclass __init__.\n # In order to do this, we need to control the instance creation and\n # inject the original kwargs through __new__ rather than doing it\n # inside __init__.\n self = super().__new__(cls)\n\n # we do a shallow copy because it's probably the most common use case.\n # this could potentially break if someone modifies a list or something\n # while it's in movement, but for now this is the cheapest and\n # fastest way to do what we want.\n self.__original_kwargs__ = kwargs.copy()\n return self\n\n def __init__(\n self,\n func: Union[\n Callable[Concatenate[CogT, Context[Any], P], Coro[T]],\n Callable[Concatenate[Context[Any], P], Coro[T]],\n ],\n /,\n **kwargs: Any,\n ) -> None:\n if not asyncio.iscoroutinefunction(func):\n raise TypeError('Callback must be a coroutine.')\n\n name = kwargs.get('name') or func.__name__\n if not isinstance(name, str):\n raise TypeError('Name of a command must be a string.')\n self.name: str = name\n\n self.callback = func\n self.enabled: bool = kwargs.get('enabled', True)\n\n help_doc = kwargs.get('help')\n if help_doc is not None:\n help_doc = inspect.cleandoc(help_doc)\n else:\n help_doc = extract_descriptions_from_docstring(func, self.params)\n\n self.help: Optional[str] = help_doc\n\n self.brief: Optional[str] = kwargs.get('brief')\n self.usage: Optional[str] = kwargs.get('usage')\n self.rest_is_raw: bool = kwargs.get('rest_is_raw', False)\n self.aliases: Union[List[str], Tuple[str]] = kwargs.get('aliases', [])\n self.extras: Dict[Any, Any] = kwargs.get('extras', {})\n\n if not isinstance(self.aliases, (list, tuple)):\n raise TypeError(\"Aliases of a command must be a list or a tuple of strings.\")\n\n self.description: str = inspect.cleandoc(kwargs.get('description', ''))\n self.hidden: bool = kwargs.get('hidden', False)\n\n try:\n checks = func.__commands_checks__\n checks.reverse()\n except AttributeError:\n checks = kwargs.get('checks', [])\n\n self.checks: List[UserCheck[Context[Any]]] = checks\n\n try:\n cooldown = func.__commands_cooldown__\n except AttributeError:\n cooldown = kwargs.get('cooldown')\n\n if cooldown is None:\n buckets = CooldownMapping(cooldown, BucketType.default)\n elif isinstance(cooldown, CooldownMapping):\n buckets: CooldownMapping[Context[Any]] = cooldown\n else:\n raise TypeError(\"Cooldown must be an instance of CooldownMapping or None.\")\n self._buckets: CooldownMapping[Context[Any]] = buckets\n\n try:\n max_concurrency = func.__commands_max_concurrency__\n except AttributeError:\n max_concurrency = kwargs.get('max_concurrency')\n\n self._max_concurrency: Optional[MaxConcurrency] = max_concurrency\n\n self.require_var_positional: bool = kwargs.get('require_var_positional', False)\n self.ignore_extra: bool = kwargs.get('ignore_extra', True)\n self.cooldown_after_parsing: bool = kwargs.get('cooldown_after_parsing', False)\n self._cog: CogT = None # type: ignore # This breaks every other pyright release\n\n # bandaid for the fact that sometimes parent can be the bot instance\n parent: Optional[GroupMixin[Any]] = kwargs.get('parent')\n self.parent: Optional[GroupMixin[Any]] = parent if isinstance(parent, _BaseCommand) else None\n\n self._before_invoke: Optional[Hook] = None\n try:\n before_invoke = func.__before_invoke__\n except AttributeError:\n pass\n else:\n self.before_invoke(before_invoke)\n\n self._after_invoke: Optional[Hook] = None\n try:\n after_invoke = func.__after_invoke__\n except AttributeError:\n pass\n else:\n self.after_invoke(after_invoke)\n\n @property\n def cog(self) -> CogT:\n return self._cog\n\n @cog.setter\n def cog(self, value: CogT) -> None:\n self._cog = value\n\n @property\n def callback(\n self,\n ) -> Union[Callable[Concatenate[CogT, Context[Any], P], Coro[T]], Callable[Concatenate[Context[Any], P], Coro[T]],]:\n return self._callback\n\n @callback.setter\n def callback(\n self,\n function: Union[\n Callable[Concatenate[CogT, Context[Any], P], Coro[T]],\n Callable[Concatenate[Context[Any], P], Coro[T]],\n ],\n ) -> None:\n self._callback = function\n unwrap = unwrap_function(function)\n self.module: str = unwrap.__module__\n\n try:\n globalns = unwrap.__globals__\n except AttributeError:\n globalns = {}\n\n self.params: Dict[str, Parameter] = get_signature_parameters(function, globalns)\n\n def add_check(self, func: UserCheck[Context[Any]], /) -> None:\n \"\"\"Adds a check to the command.\n\n This is the non-decorator interface to :func:`.check`.\n\n .. versionadded:: 1.3\n\n .. versionchanged:: 2.0\n\n ``func`` parameter is now positional-only.\n\n .. seealso:: The :func:`~discord.ext.commands.check` decorator\n\n Parameters\n -----------\n func\n The function that will be used as a check.\n \"\"\"\n\n self.checks.append(func)\n\n def remove_check(self, func: UserCheck[Context[Any]], /) -> None:\n \"\"\"Removes a check from the command.\n\n This function is idempotent and will not raise an exception\n if the function is not in the command's checks.\n\n .. versionadded:: 1.3\n\n .. versionchanged:: 2.0\n\n ``func`` parameter is now positional-only.\n\n Parameters\n -----------\n func\n The function to remove from the checks.\n \"\"\"\n\n try:\n self.checks.remove(func)\n except ValueError:\n pass\n\n def update(self, **kwargs: Any) -> None:\n \"\"\"Updates :class:`Command` instance with updated attribute.\n\n This works similarly to the :func:`~discord.ext.commands.command` decorator in terms\n of parameters in that they are passed to the :class:`Command` or\n subclass constructors, sans the name and callback.\n \"\"\"\n cog = self.cog\n self.__init__(self.callback, **dict(self.__original_kwargs__, **kwargs))\n self.cog = cog\n\n async def __call__(self, context: Context[BotT], /, *args: P.args, **kwargs: P.kwargs) -> T:\n \"\"\"|coro|\n\n Calls the internal callback that the command holds.\n\n .. note::\n\n This bypasses all mechanisms -- including checks, converters,\n invoke hooks, cooldowns, etc. You must take care to pass\n the proper arguments and types to this function.\n\n .. versionadded:: 1.3\n\n .. versionchanged:: 2.0\n\n ``context`` parameter is now positional-only.\n \"\"\"\n if self.cog is not None:\n return await self.callback(self.cog, context, *args, **kwargs) # type: ignore\n else:\n return await self.callback(context, *args, **kwargs) # type: ignore\n\n def _ensure_assignment_on_copy(self, other: Self) -> Self:\n other._before_invoke = self._before_invoke\n other._after_invoke = self._after_invoke\n other.extras = self.extras\n if self.checks != other.checks:\n other.checks = self.checks.copy()\n if self._buckets.valid and not other._buckets.valid:\n other._buckets = self._buckets.copy()\n if self._max_concurrency and self._max_concurrency != other._max_concurrency:\n other._max_concurrency = self._max_concurrency.copy()\n\n try:\n other.on_error = self.on_error\n except AttributeError:\n pass\n return other\n\n def copy(self) -> Self:\n \"\"\"Creates a copy of this command.\n\n Returns\n --------\n :class:`Command`\n A new instance of this command.\n \"\"\"\n ret = self.__class__(self.callback, **self.__original_kwargs__)\n return self._ensure_assignment_on_copy(ret)\n\n def _update_copy(self, kwargs: Dict[str, Any]) -> Self:\n if kwargs:\n kw = kwargs.copy()\n kw.update(self.__original_kwargs__)\n copy = self.__class__(self.callback, **kw)\n return self._ensure_assignment_on_copy(copy)\n else:\n return self.copy()\n\n async def dispatch_error(self, ctx: Context[BotT], error: CommandError, /) -> None:\n ctx.command_failed = True\n cog = self.cog\n try:\n coro = self.on_error\n except AttributeError:\n pass\n else:\n injected = wrap_callback(coro) # type: ignore\n if cog is not None:\n await injected(cog, ctx, error)\n else:\n await injected(ctx, error) # type: ignore\n\n try:\n if cog is not None:\n local = Cog._get_overridden_method(cog.cog_command_error)\n if local is not None:\n wrapped = wrap_callback(local)\n await wrapped(ctx, error)\n finally:\n ctx.bot.dispatch('command_error', ctx, error)\n\n async def transform(self, ctx: Context[BotT], param: Parameter, attachments: _AttachmentIterator, /) -> Any:\n converter = param.converter\n consume_rest_is_special = param.kind == param.KEYWORD_ONLY and not self.rest_is_raw\n view = ctx.view\n view.skip_ws()\n\n # The greedy converter is simple -- it keeps going until it fails in which case,\n # it undos the view ready for the next parameter to use instead\n if isinstance(converter, Greedy):\n # Special case for Greedy[discord.Attachment] to consume the attachments iterator\n if converter.converter is discord.Attachment:\n return list(attachments)\n\n if param.kind in (param.POSITIONAL_OR_KEYWORD, param.POSITIONAL_ONLY):\n return await self._transform_greedy_pos(ctx, param, param.required, converter.constructed_converter)\n elif param.kind == param.VAR_POSITIONAL:\n return await self._transform_greedy_var_pos(ctx, param, converter.constructed_converter)\n else:\n # if we're here, then it's a KEYWORD_ONLY param type\n # since this is mostly useless, we'll helpfully transform Greedy[X]\n # into just X and do the parsing that way.\n converter = converter.constructed_converter\n\n # Try to detect Optional[discord.Attachment] or discord.Attachment special converter\n if converter is discord.Attachment:\n try:\n return next(attachments)\n except StopIteration:\n raise MissingRequiredAttachment(param)\n\n if self._is_typing_optional(param.annotation) and param.annotation.__args__[0] is discord.Attachment:\n if attachments.is_empty():\n # I have no idea who would be doing Optional[discord.Attachment] = 1\n # but for those cases then 1 should be returned instead of None\n return None if param.default is param.empty else param.default\n return next(attachments)\n\n if view.eof:\n if param.kind == param.VAR_POSITIONAL:\n raise RuntimeError() # break the loop\n if param.required:\n if self._is_typing_optional(param.annotation):\n return None\n if hasattr(converter, '__commands_is_flag__') and converter._can_be_constructible():\n return await converter._construct_default(ctx)\n raise MissingRequiredArgument(param)\n return await param.get_default(ctx)\n\n previous = view.index\n if consume_rest_is_special:\n ctx.current_argument = argument = view.read_rest().strip()\n else:\n try:\n ctx.current_argument = argument = view.get_quoted_word()\n except ArgumentParsingError as exc:\n if self._is_typing_optional(param.annotation):\n view.index = previous\n return None if param.required else await param.get_default(ctx)\n else:\n raise exc\n view.previous = previous\n\n # type-checker fails to narrow argument\n return await run_converters(ctx, converter, argument, param) # type: ignore\n\n async def _transform_greedy_pos(self, ctx: Context[BotT], param: Parameter, required: bool, converter: Any) -> Any:\n view = ctx.view\n result = []\n while not view.eof:\n # for use with a manual undo\n previous = view.index\n\n view.skip_ws()\n try:\n ctx.current_argument = argument = view.get_quoted_word()\n value = await run_converters(ctx, converter, argument, param) # type: ignore\n except (CommandError, ArgumentParsingError):\n view.index = previous\n break\n else:\n result.append(value)\n\n if not result and not required:\n return await param.get_default(ctx)\n return result\n\n async def _transform_greedy_var_pos(self, ctx: Context[BotT], param: Parameter, converter: Any) -> Any:\n view = ctx.view\n previous = view.index\n try:\n ctx.current_argument = argument = view.get_quoted_word()\n value = await run_converters(ctx, converter, argument, param) # type: ignore\n except (CommandError, ArgumentParsingError):\n view.index = previous\n raise RuntimeError() from None # break loop\n else:\n return value\n\n @property\n def clean_params(self) -> Dict[str, Parameter]:\n \"\"\"Dict[:class:`str`, :class:`Parameter`]:\n Retrieves the parameter dictionary without the context or self parameters.\n\n Useful for inspecting signature.\n \"\"\"\n return self.params.copy()\n\n @property\n def cooldown(self) -> Optional[Cooldown]:\n \"\"\"Optional[:class:`~discord.app_commands.Cooldown`]: The cooldown of a command when invoked\n or ``None`` if the command doesn't have a registered cooldown.\n\n .. versionadded:: 2.0\n \"\"\"\n return self._buckets._cooldown\n\n @property\n def full_parent_name(self) -> str:\n \"\"\":class:`str`: Retrieves the fully qualified parent command name.\n\n This the base command name required to execute it. For example,\n in ``?one two three`` the parent name would be ``one two``.\n \"\"\"\n entries = []\n command = self\n # command.parent is type-hinted as GroupMixin some attributes are resolved via MRO\n while command.parent is not None: # type: ignore\n command = command.parent # type: ignore\n entries.append(command.name) # type: ignore\n\n return ' '.join(reversed(entries))\n\n @property\n def parents(self) -> List[Group[Any, ..., Any]]:\n \"\"\"List[:class:`Group`]: Retrieves the parents of this command.\n\n If the command has no parents then it returns an empty :class:`list`.\n\n For example in commands ``?a b c test``, the parents are ``[c, b, a]``.\n\n .. versionadded:: 1.1\n \"\"\"\n entries = []\n command = self\n while command.parent is not None: # type: ignore\n command = command.parent # type: ignore\n entries.append(command)\n\n return entries\n\n @property\n def root_parent(self) -> Optional[Group[Any, ..., Any]]:\n \"\"\"Optional[:class:`Group`]: Retrieves the root parent of this command.\n\n If the command has no parents then it returns ``None``.\n\n For example in commands ``?a b c test``, the root parent is ``a``.\n \"\"\"\n if not self.parent:\n return None\n return self.parents[-1]\n\n @property\n def qualified_name(self) -> str:\n \"\"\":class:`str`: Retrieves the fully qualified command name.\n\n This is the full parent name with the command name as well.\n For example, in ``?one two three`` the qualified name would be\n ``one two three``.\n \"\"\"\n\n parent = self.full_parent_name\n if parent:\n return parent + ' ' + self.name\n else:\n return self.name\n\n def __str__(self) -> str:\n return self.qualified_name\n\n async def _parse_arguments(self, ctx: Context[BotT]) -> None:\n ctx.args = [ctx] if self.cog is None else [self.cog, ctx]\n ctx.kwargs = {}\n args = ctx.args\n kwargs = ctx.kwargs\n attachments = _AttachmentIterator(ctx.message.attachments)\n\n view = ctx.view\n iterator = iter(self.params.items())\n\n for name, param in iterator:\n ctx.current_parameter = param\n if param.kind in (param.POSITIONAL_OR_KEYWORD, param.POSITIONAL_ONLY):\n transformed = await self.transform(ctx, param, attachments)\n args.append(transformed)\n elif param.kind == param.KEYWORD_ONLY:\n # kwarg only param denotes \"consume rest\" semantics\n if self.rest_is_raw:\n ctx.current_argument = argument = view.read_rest()\n kwargs[name] = await run_converters(ctx, param.converter, argument, param)\n else:\n kwargs[name] = await self.transform(ctx, param, attachments)\n break\n elif param.kind == param.VAR_POSITIONAL:\n if view.eof and self.require_var_positional:\n raise MissingRequiredArgument(param)\n while not view.eof:\n try:\n transformed = await self.transform(ctx, param, attachments)\n args.append(transformed)\n except RuntimeError:\n break\n\n if not self.ignore_extra and not view.eof:\n raise TooManyArguments('Too many arguments passed to ' + self.qualified_name)\n\n async def call_before_hooks(self, ctx: Context[BotT], /) -> None:\n # now that we're done preparing we can call the pre-command hooks\n # first, call the command local hook:\n cog = self.cog\n if self._before_invoke is not None:\n # should be cog if @commands.before_invoke is used\n instance = getattr(self._before_invoke, '__self__', cog)\n # __self__ only exists for methods, not functions\n # however, if @command.before_invoke is used, it will be a function\n if instance:\n await self._before_invoke(instance, ctx) # type: ignore\n else:\n await self._before_invoke(ctx) # type: ignore\n\n # call the cog local hook if applicable:\n if cog is not None:\n hook = Cog._get_overridden_method(cog.cog_before_invoke)\n if hook is not None:\n await hook(ctx)\n\n # call the bot global hook if necessary\n hook = ctx.bot._before_invoke\n if hook is not None:\n await hook(ctx)\n\n async def call_after_hooks(self, ctx: Context[BotT], /) -> None:\n cog = self.cog\n if self._after_invoke is not None:\n instance = getattr(self._after_invoke, '__self__', cog)\n if instance:\n await self._after_invoke(instance, ctx) # type: ignore\n else:\n await self._after_invoke(ctx) # type: ignore\n\n # call the cog local hook if applicable:\n if cog is not None:\n hook = Cog._get_overridden_method(cog.cog_after_invoke)\n if hook is not None:\n await hook(ctx)\n\n hook = ctx.bot._after_invoke\n if hook is not None:\n await hook(ctx)\n\n def _prepare_cooldowns(self, ctx: Context[BotT]) -> None:\n if self._buckets.valid:\n dt = ctx.message.edited_at or ctx.message.created_at\n current = dt.replace(tzinfo=datetime.timezone.utc).timestamp()\n bucket = self._buckets.get_bucket(ctx, current)\n if bucket is not None:\n retry_after = bucket.update_rate_limit(current)\n if retry_after:\n raise CommandOnCooldown(bucket, retry_after, self._buckets.type) # type: ignore\n\n async def prepare(self, ctx: Context[BotT], /) -> None:\n ctx.command = self\n\n if not await self.can_run(ctx):\n raise CheckFailure(f'The check functions for command {self.qualified_name} failed.')\n\n if self._max_concurrency is not None:\n # For this application, context can be duck-typed as a Message\n await self._max_concurrency.acquire(ctx)\n\n try:\n if self.cooldown_after_parsing:\n await self._parse_arguments(ctx)\n self._prepare_cooldowns(ctx)\n else:\n self._prepare_cooldowns(ctx)\n await self._parse_arguments(ctx)\n\n await self.call_before_hooks(ctx)\n except:\n if self._max_concurrency is not None:\n await self._max_concurrency.release(ctx)\n raise\n\n def is_on_cooldown(self, ctx: Context[BotT], /) -> bool:\n \"\"\"Checks whether the command is currently on cooldown.\n\n .. versionchanged:: 2.0\n\n ``ctx`` parameter is now positional-only.\n\n Parameters\n -----------\n ctx: :class:`.Context`\n The invocation context to use when checking the commands cooldown status.\n\n Returns\n --------\n :class:`bool`\n A boolean indicating if the command is on cooldown.\n \"\"\"\n if not self._buckets.valid:\n return False\n\n bucket = self._buckets.get_bucket(ctx)\n if bucket is None:\n return False\n dt = ctx.message.edited_at or ctx.message.created_at\n current = dt.replace(tzinfo=datetime.timezone.utc).timestamp()\n return bucket.get_tokens(current) == 0\n\n def reset_cooldown(self, ctx: Context[BotT], /) -> None:\n \"\"\"Resets the cooldown on this command.\n\n .. versionchanged:: 2.0\n\n ``ctx`` parameter is now positional-only.\n\n Parameters\n -----------\n ctx: :class:`.Context`\n The invocation context to reset the cooldown under.\n \"\"\"\n if self._buckets.valid:\n bucket = self._buckets.get_bucket(ctx)\n if bucket is not None:\n bucket.reset()\n\n def get_cooldown_retry_after(self, ctx: Context[BotT], /) -> float:\n \"\"\"Retrieves the amount of seconds before this command can be tried again.\n\n .. versionadded:: 1.4\n\n .. versionchanged:: 2.0\n\n ``ctx`` parameter is now positional-only.\n\n Parameters\n -----------\n ctx: :class:`.Context`\n The invocation context to retrieve the cooldown from.\n\n Returns\n --------\n :class:`float`\n The amount of time left on this command's cooldown in seconds.\n If this is ``0.0`` then the command isn't on cooldown.\n \"\"\"\n if self._buckets.valid:\n bucket = self._buckets.get_bucket(ctx)\n if bucket is None:\n return 0.0\n dt = ctx.message.edited_at or ctx.message.created_at\n current = dt.replace(tzinfo=datetime.timezone.utc).timestamp()\n return bucket.get_retry_after(current)\n\n return 0.0\n\n async def invoke(self, ctx: Context[BotT], /) -> None:\n await self.prepare(ctx)\n\n # terminate the invoked_subcommand chain.\n # since we're in a regular command (and not a group) then\n # the invoked subcommand is None.\n ctx.invoked_subcommand = None\n ctx.subcommand_passed = None\n injected = hooked_wrapped_callback(self, ctx, self.callback) # type: ignore\n await injected(*ctx.args, **ctx.kwargs) # type: ignore\n\n async def reinvoke(self, ctx: Context[BotT], /, *, call_hooks: bool = False) -> None:\n ctx.command = self\n await self._parse_arguments(ctx)\n\n if call_hooks:\n await self.call_before_hooks(ctx)\n\n ctx.invoked_subcommand = None\n try:\n await self.callback(*ctx.args, **ctx.kwargs) # type: ignore\n except:\n ctx.command_failed = True\n raise\n finally:\n if call_hooks:\n await self.call_after_hooks(ctx)\n\n def error(self, coro: Error[CogT, ContextT], /) -> Error[CogT, ContextT]:\n \"\"\"A decorator that registers a coroutine as a local error handler.\n\n A local error handler is an :func:`.on_command_error` event limited to\n a single command. However, the :func:`.on_command_error` is still\n invoked afterwards as the catch-all.\n\n .. versionchanged:: 2.0\n\n ``coro`` parameter is now positional-only.\n\n Parameters\n -----------\n coro: :ref:`coroutine `\n The coroutine to register as the local error handler.\n\n Raises\n -------\n TypeError\n The coroutine passed is not actually a coroutine.\n \"\"\"\n\n if not asyncio.iscoroutinefunction(coro):\n raise TypeError('The error handler must be a coroutine.')\n\n self.on_error: Error[CogT, Any] = coro\n return coro\n\n def has_error_handler(self) -> bool:\n \"\"\":class:`bool`: Checks whether the command has an error handler registered.\n\n .. versionadded:: 1.7\n \"\"\"\n return hasattr(self, 'on_error')\n\n def before_invoke(self, coro: Hook[CogT, ContextT], /) -> Hook[CogT, ContextT]:\n \"\"\"A decorator that registers a coroutine as a pre-invoke hook.\n\n A pre-invoke hook is called directly before the command is\n called. This makes it a useful function to set up database\n connections or any type of set up required.\n\n This pre-invoke hook takes a sole parameter, a :class:`.Context`.\n\n See :meth:`.Bot.before_invoke` for more info.\n\n .. versionchanged:: 2.0\n\n ``coro`` parameter is now positional-only.\n\n Parameters\n -----------\n coro: :ref:`coroutine `\n The coroutine to register as the pre-invoke hook.\n\n Raises\n -------\n TypeError\n The coroutine passed is not actually a coroutine.\n \"\"\"\n if not asyncio.iscoroutinefunction(coro):\n raise TypeError('The pre-invoke hook must be a coroutine.')\n\n self._before_invoke = coro\n return coro\n\n def after_invoke(self, coro: Hook[CogT, ContextT], /) -> Hook[CogT, ContextT]:\n \"\"\"A decorator that registers a coroutine as a post-invoke hook.\n\n A post-invoke hook is called directly after the command is\n called. This makes it a useful function to clean-up database\n connections or any type of clean up required.\n\n This post-invoke hook takes a sole parameter, a :class:`.Context`.\n\n See :meth:`.Bot.after_invoke` for more info.\n\n .. versionchanged:: 2.0\n\n ``coro`` parameter is now positional-only.\n\n Parameters\n -----------\n coro: :ref:`coroutine `\n The coroutine to register as the post-invoke hook.\n\n Raises\n -------\n TypeError\n The coroutine passed is not actually a coroutine.\n \"\"\"\n if not asyncio.iscoroutinefunction(coro):\n raise TypeError('The post-invoke hook must be a coroutine.')\n\n self._after_invoke = coro\n return coro\n\n @property\n def cog_name(self) -> Optional[str]:\n \"\"\"Optional[:class:`str`]: The name of the cog this command belongs to, if any.\"\"\"\n return type(self.cog).__cog_name__ if self.cog is not None else None\n\n @property\n def short_doc(self) -> str:\n \"\"\":class:`str`: Gets the \"short\" documentation of a command.\n\n By default, this is the :attr:`.brief` attribute.\n If that lookup leads to an empty string then the first line of the\n :attr:`.help` attribute is used instead.\n \"\"\"\n if self.brief is not None:\n return self.brief\n if self.help is not None:\n return self.help.split('\\n', 1)[0]\n return ''\n\n def _is_typing_optional(self, annotation: Union[T, Optional[T]]) -> bool:\n return getattr(annotation, '__origin__', None) is Union and type(None) in annotation.__args__ # type: ignore\n\n @property\n def signature(self) -> str:\n \"\"\":class:`str`: Returns a POSIX-like signature useful for help command output.\"\"\"\n if self.usage is not None:\n return self.usage\n\n params = self.clean_params\n if not params:\n return ''\n\n result = []\n for param in params.values():\n name = param.displayed_name or param.name\n\n greedy = isinstance(param.converter, Greedy)\n optional = False # postpone evaluation of if it's an optional argument\n\n annotation: Any = param.converter.converter if greedy else param.converter\n origin = getattr(annotation, '__origin__', None)\n if not greedy and origin is Union:\n none_cls = type(None)\n union_args = annotation.__args__\n optional = union_args[-1] is none_cls\n if len(union_args) == 2 and optional:\n annotation = union_args[0]\n origin = getattr(annotation, '__origin__', None)\n\n if annotation is discord.Attachment:\n # For discord.Attachment we need to signal to the user that it's an attachment\n # It's not exactly pretty but it's enough to differentiate\n if optional:\n result.append(f'[{name} (upload a file)]')\n elif greedy:\n result.append(f'[{name} (upload files)]...')\n else:\n result.append(f'<{name} (upload a file)>')\n continue\n\n # for typing.Literal[...], typing.Optional[typing.Literal[...]], and Greedy[typing.Literal[...]], the\n # parameter signature is a literal list of it's values\n if origin is Literal:\n name = '|'.join(f'\"{v}\"' if isinstance(v, str) else str(v) for v in annotation.__args__)\n if not param.required:\n # We don't want None or '' to trigger the [name=value] case and instead it should\n # do [name] since [name=None] or [name=] are not exactly useful for the user.\n if param.displayed_default:\n result.append(\n f'[{name}={param.displayed_default}]' if not greedy else f'[{name}={param.displayed_default}]...'\n )\n continue\n else:\n result.append(f'[{name}]')\n\n elif param.kind == param.VAR_POSITIONAL:\n if self.require_var_positional:\n result.append(f'<{name}...>')\n else:\n result.append(f'[{name}...]')\n elif greedy:\n result.append(f'[{name}]...')\n elif optional:\n result.append(f'[{name}]')\n else:\n result.append(f'<{name}>')\n\n return ' '.join(result)\n\n async def can_run(self, ctx: Context[BotT], /) -> bool:\n \"\"\"|coro|\n\n Checks if the command can be executed by checking all the predicates\n inside the :attr:`~Command.checks` attribute. This also checks whether the\n command is disabled.\n\n .. versionchanged:: 1.3\n Checks whether the command is disabled or not\n\n .. versionchanged:: 2.0\n\n ``ctx`` parameter is now positional-only.\n\n Parameters\n -----------\n ctx: :class:`.Context`\n The ctx of the command currently being invoked.\n\n Raises\n -------\n :class:`CommandError`\n Any command error that was raised during a check call will be propagated\n by this function.\n\n Returns\n --------\n :class:`bool`\n A boolean indicating if the command can be invoked.\n \"\"\"\n\n if not self.enabled:\n raise DisabledCommand(f'{self.name} command is disabled')\n\n original = ctx.command\n ctx.command = self\n\n try:\n if not await ctx.bot.can_run(ctx):\n raise CheckFailure(f'The global check functions for command {self.qualified_name} failed.')\n\n cog = self.cog\n if cog is not None:\n local_check = Cog._get_overridden_method(cog.cog_check)\n if local_check is not None:\n ret = await discord.utils.maybe_coroutine(local_check, ctx)\n if not ret:\n return False\n\n predicates = self.checks\n if not predicates:\n # since we have no checks, then we just return True.\n return True\n\n return await discord.utils.async_all(predicate(ctx) for predicate in predicates)\n finally:\n ctx.command = original\n\n\nclass GroupMixin(Generic[CogT]):\n \"\"\"A mixin that implements common functionality for classes that behave\n similar to :class:`.Group` and are allowed to register commands.\n\n Attributes\n -----------\n all_commands: :class:`dict`\n A mapping of command name to :class:`.Command`\n objects.\n case_insensitive: :class:`bool`\n Whether the commands should be case insensitive. Defaults to ``False``.\n \"\"\"\n\n def __init__(self, *args: Any, **kwargs: Any) -> None:\n case_insensitive = kwargs.get('case_insensitive', False)\n self.all_commands: Dict[str, Command[CogT, ..., Any]] = _CaseInsensitiveDict() if case_insensitive else {}\n self.case_insensitive: bool = case_insensitive\n super().__init__(*args, **kwargs)\n\n @property\n def commands(self) -> Set[Command[CogT, ..., Any]]:\n \"\"\"Set[:class:`.Command`]: A unique set of commands without aliases that are registered.\"\"\"\n return set(self.all_commands.values())\n\n def recursively_remove_all_commands(self) -> None:\n for command in self.all_commands.copy().values():\n if isinstance(command, GroupMixin):\n command.recursively_remove_all_commands()\n self.remove_command(command.name)\n\n def add_command(self, command: Command[CogT, ..., Any], /) -> None:\n \"\"\"Adds a :class:`.Command` into the internal list of commands.\n\n This is usually not called, instead the :meth:`~.GroupMixin.command` or\n :meth:`~.GroupMixin.group` shortcut decorators are used instead.\n\n .. versionchanged:: 1.4\n Raise :exc:`.CommandRegistrationError` instead of generic :exc:`.ClientException`\n\n .. versionchanged:: 2.0\n\n ``command`` parameter is now positional-only.\n\n Parameters\n -----------\n command: :class:`Command`\n The command to add.\n\n Raises\n -------\n CommandRegistrationError\n If the command or its alias is already registered by different command.\n TypeError\n If the command passed is not a subclass of :class:`.Command`.\n \"\"\"\n\n if not isinstance(command, Command):\n raise TypeError('The command passed must be a subclass of Command')\n\n if isinstance(self, Command):\n command.parent = self\n\n if command.name in self.all_commands:\n raise CommandRegistrationError(command.name)\n\n self.all_commands[command.name] = command\n for alias in command.aliases:\n if alias in self.all_commands:\n self.remove_command(command.name)\n raise CommandRegistrationError(alias, alias_conflict=True)\n self.all_commands[alias] = command\n\n def remove_command(self, name: str, /) -> Optional[Command[CogT, ..., Any]]:\n \"\"\"Remove a :class:`.Command` from the internal list\n of commands.\n\n This could also be used as a way to remove aliases.\n\n .. versionchanged:: 2.0\n\n ``name`` parameter is now positional-only.\n\n Parameters\n -----------\n name: :class:`str`\n The name of the command to remove.\n\n Returns\n --------\n Optional[:class:`.Command`]\n The command that was removed. If the name is not valid then\n ``None`` is returned instead.\n \"\"\"\n command = self.all_commands.pop(name, None)\n\n # does not exist\n if command is None:\n return None\n\n if name in command.aliases:\n # we're removing an alias so we don't want to remove the rest\n return command\n\n # we're not removing the alias so let's delete the rest of them.\n for alias in command.aliases:\n cmd = self.all_commands.pop(alias, None)\n # in the case of a CommandRegistrationError, an alias might conflict\n # with an already existing command. If this is the case, we want to\n # make sure the pre-existing command is not removed.\n if cmd is not None and cmd != command:\n self.all_commands[alias] = cmd\n return command\n\n def walk_commands(self) -> Generator[Command[CogT, ..., Any], None, None]:\n \"\"\"An iterator that recursively walks through all commands and subcommands.\n\n .. versionchanged:: 1.4\n Duplicates due to aliases are no longer returned\n\n Yields\n ------\n Union[:class:`.Command`, :class:`.Group`]\n A command or group from the internal list of commands.\n \"\"\"\n for command in self.commands:\n yield command\n if isinstance(command, GroupMixin):\n yield from command.walk_commands()\n\n def get_command(self, name: str, /) -> Optional[Command[CogT, ..., Any]]:\n \"\"\"Get a :class:`.Command` from the internal list\n of commands.\n\n This could also be used as a way to get aliases.\n\n The name could be fully qualified (e.g. ``'foo bar'``) will get\n the subcommand ``bar`` of the group command ``foo``. If a\n subcommand is not found then ``None`` is returned just as usual.\n\n .. versionchanged:: 2.0\n\n ``name`` parameter is now positional-only.\n\n Parameters\n -----------\n name: :class:`str`\n The name of the command to get.\n\n Returns\n --------\n Optional[:class:`Command`]\n The command that was requested. If not found, returns ``None``.\n \"\"\"\n\n # fast path, no space in name.\n if ' ' not in name:\n return self.all_commands.get(name)\n\n names = name.split()\n if not names:\n return None\n obj = self.all_commands.get(names[0])\n if not isinstance(obj, GroupMixin):\n return obj\n\n for name in names[1:]:\n try:\n obj = obj.all_commands[name] # type: ignore\n except (AttributeError, KeyError):\n return None\n\n return obj\n\n @overload\n def command(\n self: GroupMixin[CogT],\n name: str = ...,\n *args: Any,\n **kwargs: Any,\n ) -> Callable[\n [\n Union[\n Callable[Concatenate[CogT, ContextT, P], Coro[T]],\n Callable[Concatenate[ContextT, P], Coro[T]],\n ]\n ],\n Command[CogT, P, T],\n ]:\n ...\n\n @overload\n def command(\n self: GroupMixin[CogT],\n name: str = ...,\n cls: Type[CommandT] = ..., # type: ignore # previous overload handles case where cls is not set\n *args: Any,\n **kwargs: Any,\n ) -> Callable[\n [\n Union[\n Callable[Concatenate[CogT, ContextT, P], Coro[T]],\n Callable[Concatenate[ContextT, P], Coro[T]],\n ]\n ],\n CommandT,\n ]:\n ...\n\n def command(\n self,\n name: str = MISSING,\n cls: Type[Command[Any, ..., Any]] = MISSING,\n *args: Any,\n **kwargs: Any,\n ) -> Any:\n \"\"\"A shortcut decorator that invokes :func:`~discord.ext.commands.command` and adds it to\n the internal command list via :meth:`~.GroupMixin.add_command`.\n\n Returns\n --------\n Callable[..., :class:`Command`]\n A decorator that converts the provided method into a Command, adds it to the bot, then returns it.\n \"\"\"\n\n def decorator(func):\n\n kwargs.setdefault('parent', self)\n result = command(name=name, cls=cls, *args, **kwargs)(func)\n self.add_command(result)\n return result\n\n return decorator\n\n @overload\n def group(\n self: GroupMixin[CogT],\n name: str = ...,\n *args: Any,\n **kwargs: Any,\n ) -> Callable[\n [\n Union[\n Callable[Concatenate[CogT, ContextT, P], Coro[T]],\n Callable[Concatenate[ContextT, P], Coro[T]],\n ]\n ],\n Group[CogT, P, T],\n ]:\n ...\n\n @overload\n def group(\n self: GroupMixin[CogT],\n name: str = ...,\n cls: Type[GroupT] = ..., # type: ignore # previous overload handles case where cls is not set\n *args: Any,\n **kwargs: Any,\n ) -> Callable[\n [\n Union[\n Callable[Concatenate[CogT, ContextT, P], Coro[T]],\n Callable[Concatenate[ContextT, P], Coro[T]],\n ]\n ],\n GroupT,\n ]:\n ...\n\n def group(\n self,\n name: str = MISSING,\n cls: Type[Group[Any, ..., Any]] = MISSING,\n *args: Any,\n **kwargs: Any,\n ) -> Any:\n \"\"\"A shortcut decorator that invokes :func:`.group` and adds it to\n the internal command list via :meth:`~.GroupMixin.add_command`.\n\n Returns\n --------\n Callable[..., :class:`Group`]\n A decorator that converts the provided method into a Group, adds it to the bot, then returns it.\n \"\"\"\n\n def decorator(func):\n kwargs.setdefault('parent', self)\n result = group(name=name, cls=cls, *args, **kwargs)(func)\n self.add_command(result)\n return result\n\n return decorator\n\n\nclass Group(GroupMixin[CogT], Command[CogT, P, T]):\n \"\"\"A class that implements a grouping protocol for commands to be\n executed as subcommands.\n\n This class is a subclass of :class:`.Command` and thus all options\n valid in :class:`.Command` are valid in here as well.\n\n Attributes\n -----------\n invoke_without_command: :class:`bool`\n Indicates if the group callback should begin parsing and\n invocation only if no subcommand was found. Useful for\n making it an error handling function to tell the user that\n no subcommand was found or to have different functionality\n in case no subcommand was found. If this is ``False``, then\n the group callback will always be invoked first. This means\n that the checks and the parsing dictated by its parameters\n will be executed. Defaults to ``False``.\n case_insensitive: :class:`bool`\n Indicates if the group's commands should be case insensitive.\n Defaults to ``False``.\n \"\"\"\n\n def __init__(self, *args: Any, **attrs: Any) -> None:\n self.invoke_without_command: bool = attrs.pop('invoke_without_command', False)\n super().__init__(*args, **attrs)\n\n def copy(self) -> Self:\n \"\"\"Creates a copy of this :class:`Group`.\n\n Returns\n --------\n :class:`Group`\n A new instance of this group.\n \"\"\"\n ret = super().copy()\n for cmd in self.commands:\n ret.add_command(cmd.copy())\n return ret\n\n async def invoke(self, ctx: Context[BotT], /) -> None:\n ctx.invoked_subcommand = None\n ctx.subcommand_passed = None\n early_invoke = not self.invoke_without_command\n if early_invoke:\n await self.prepare(ctx)\n\n view = ctx.view\n previous = view.index\n view.skip_ws()\n trigger = view.get_word()\n\n if trigger:\n ctx.subcommand_passed = trigger\n ctx.invoked_subcommand = self.all_commands.get(trigger, None)\n\n if early_invoke:\n injected = hooked_wrapped_callback(self, ctx, self.callback) # type: ignore\n await injected(*ctx.args, **ctx.kwargs) # type: ignore\n\n ctx.invoked_parents.append(ctx.invoked_with) # type: ignore\n\n if trigger and ctx.invoked_subcommand:\n ctx.invoked_with = trigger\n await ctx.invoked_subcommand.invoke(ctx)\n elif not early_invoke:\n # undo the trigger parsing\n view.index = previous\n view.previous = previous\n await super().invoke(ctx)\n\n async def reinvoke(self, ctx: Context[BotT], /, *, call_hooks: bool = False) -> None:\n ctx.invoked_subcommand = None\n early_invoke = not self.invoke_without_command\n if early_invoke:\n ctx.command = self\n await self._parse_arguments(ctx)\n\n if call_hooks:\n await self.call_before_hooks(ctx)\n\n view = ctx.view\n previous = view.index\n view.skip_ws()\n trigger = view.get_word()\n\n if trigger:\n ctx.subcommand_passed = trigger\n ctx.invoked_subcommand = self.all_commands.get(trigger, None)\n\n if early_invoke:\n try:\n await self.callback(*ctx.args, **ctx.kwargs) # type: ignore\n except:\n ctx.command_failed = True\n raise\n finally:\n if call_hooks:\n await self.call_after_hooks(ctx)\n\n ctx.invoked_parents.append(ctx.invoked_with) # type: ignore\n\n if trigger and ctx.invoked_subcommand:\n ctx.invoked_with = trigger\n await ctx.invoked_subcommand.reinvoke(ctx, call_hooks=call_hooks)\n elif not early_invoke:\n # undo the trigger parsing\n view.index = previous\n view.previous = previous\n await super().reinvoke(ctx, call_hooks=call_hooks)\n\n\n# Decorators\n\nif TYPE_CHECKING:\n # Using a class to emulate a function allows for overloading the inner function in the decorator.\n\n class _CommandDecorator:\n @overload\n def __call__(self, func: Callable[Concatenate[CogT, ContextT, P], Coro[T]], /) -> Command[CogT, P, T]:\n ...\n\n @overload\n def __call__(self, func: Callable[Concatenate[ContextT, P], Coro[T]], /) -> Command[None, P, T]:\n ...\n\n def __call__(self, func: Callable[..., Coro[T]], /) -> Any:\n ...\n\n class _GroupDecorator:\n @overload\n def __call__(self, func: Callable[Concatenate[CogT, ContextT, P], Coro[T]], /) -> Group[CogT, P, T]:\n ...\n\n @overload\n def __call__(self, func: Callable[Concatenate[ContextT, P], Coro[T]], /) -> Group[None, P, T]:\n ...\n\n def __call__(self, func: Callable[..., Coro[T]], /) -> Any:\n ...\n\n\n@overload\ndef command(\n name: str = ...,\n **attrs: Any,\n) -> _CommandDecorator:\n ...\n\n\n@overload\ndef command(\n name: str = ...,\n cls: Type[CommandT] = ..., # type: ignore # previous overload handles case where cls is not set\n **attrs: Any,\n) -> Callable[\n [\n Union[\n Callable[Concatenate[ContextT, P], Coro[Any]],\n Callable[Concatenate[CogT, ContextT, P], Coro[Any]], # type: ignore # CogT is used here to allow covariance\n ]\n ],\n CommandT,\n]:\n ...\n\n\ndef command(\n name: str = MISSING,\n cls: Type[Command[Any, ..., Any]] = MISSING,\n **attrs: Any,\n) -> Any:\n \"\"\"A decorator that transforms a function into a :class:`.Command`\n or if called with :func:`.group`, :class:`.Group`.\n\n By default the ``help`` attribute is received automatically from the\n docstring of the function and is cleaned up with the use of\n ``inspect.cleandoc``. If the docstring is ``bytes``, then it is decoded\n into :class:`str` using utf-8 encoding.\n\n All checks added using the :func:`.check` & co. decorators are added into\n the function. There is no way to supply your own checks through this\n decorator.\n\n Parameters\n -----------\n name: :class:`str`\n The name to create the command with. By default this uses the\n function name unchanged.\n cls\n The class to construct with. By default this is :class:`.Command`.\n You usually do not change this.\n attrs\n Keyword arguments to pass into the construction of the class denoted\n by ``cls``.\n\n Raises\n -------\n TypeError\n If the function is not a coroutine or is already a command.\n \"\"\"\n if cls is MISSING:\n cls = Command\n\n def decorator(func):\n if isinstance(func, Command):\n raise TypeError('Callback is already a command.')\n return cls(func, name=name, **attrs)\n\n return decorator\n\n\n@overload\ndef group(\n name: str = ...,\n **attrs: Any,\n) -> _GroupDecorator:\n ...\n\n\n@overload\ndef group(\n name: str = ...,\n cls: Type[GroupT] = ..., # type: ignore # previous overload handles case where cls is not set\n **attrs: Any,\n) -> Callable[\n [\n Union[\n Callable[Concatenate[CogT, ContextT, P], Coro[Any]], # type: ignore # CogT is used here to allow covariance\n Callable[Concatenate[ContextT, P], Coro[Any]],\n ]\n ],\n GroupT,\n]:\n ...\n\n\ndef group(\n name: str = MISSING,\n cls: Type[Group[Any, ..., Any]] = MISSING,\n **attrs: Any,\n) -> Any:\n \"\"\"A decorator that transforms a function into a :class:`.Group`.\n\n This is similar to the :func:`~discord.ext.commands.command` decorator but the ``cls``\n parameter is set to :class:`Group` by default.\n\n .. versionchanged:: 1.1\n The ``cls`` parameter can now be passed.\n \"\"\"\n if cls is MISSING:\n cls = Group\n\n return command(name=name, cls=cls, **attrs)\n\n\ndef check(predicate: UserCheck[ContextT], /) -> Check[ContextT]:\n r\"\"\"A decorator that adds a check to the :class:`.Command` or its\n subclasses. These checks could be accessed via :attr:`.Command.checks`.\n\n These checks should be predicates that take in a single parameter taking\n a :class:`.Context`. If the check returns a ``False``\\-like value then\n during invocation a :exc:`.CheckFailure` exception is raised and sent to\n the :func:`.on_command_error` event.\n\n If an exception should be thrown in the predicate then it should be a\n subclass of :exc:`.CommandError`. Any exception not subclassed from it\n will be propagated while those subclassed will be sent to\n :func:`.on_command_error`.\n\n A special attribute named ``predicate`` is bound to the value\n returned by this decorator to retrieve the predicate passed to the\n decorator. This allows the following introspection and chaining to be done:\n\n .. code-block:: python3\n\n def owner_or_permissions(**perms):\n original = commands.has_permissions(**perms).predicate\n async def extended_check(ctx):\n if ctx.guild is None:\n return False\n return ctx.guild.owner_id == ctx.author.id or await original(ctx)\n return commands.check(extended_check)\n\n .. note::\n\n The function returned by ``predicate`` is **always** a coroutine,\n even if the original function was not a coroutine.\n\n .. versionchanged:: 1.3\n The ``predicate`` attribute was added.\n\n Examples\n ---------\n\n Creating a basic check to see if the command invoker is you.\n\n .. code-block:: python3\n\n def check_if_it_is_me(ctx):\n return ctx.message.author.id == 85309593344815104\n\n @bot.command()\n @commands.check(check_if_it_is_me)\n async def only_for_me(ctx):\n await ctx.send('I know you!')\n\n Transforming common checks into its own decorator:\n\n .. code-block:: python3\n\n def is_me():\n def predicate(ctx):\n return ctx.message.author.id == 85309593344815104\n return commands.check(predicate)\n\n @bot.command()\n @is_me()\n async def only_me(ctx):\n await ctx.send('Only you!')\n\n .. versionchanged:: 2.0\n\n ``predicate`` parameter is now positional-only.\n\n Parameters\n -----------\n predicate: Callable[[:class:`Context`], :class:`bool`]\n The predicate to check if the command should be invoked.\n \"\"\"\n\n def decorator(func: Union[Command[Any, ..., Any], CoroFunc]) -> Union[Command[Any, ..., Any], CoroFunc]:\n if isinstance(func, Command):\n func.checks.append(predicate) # type: ignore\n else:\n if not hasattr(func, '__commands_checks__'):\n func.__commands_checks__ = []\n\n func.__commands_checks__.append(predicate)\n\n return func\n\n if inspect.iscoroutinefunction(predicate):\n decorator.predicate = predicate\n else:\n\n @functools.wraps(predicate)\n async def wrapper(ctx: ContextT):\n return predicate(ctx)\n\n decorator.predicate = wrapper\n\n return decorator # type: ignore\n\n\ndef check_any(*checks: Check[ContextT]) -> Check[ContextT]:\n r\"\"\"A :func:`check` that is added that checks if any of the checks passed\n will pass, i.e. using logical OR.\n\n If all checks fail then :exc:`.CheckAnyFailure` is raised to signal the failure.\n It inherits from :exc:`.CheckFailure`.\n\n .. note::\n\n The ``predicate`` attribute for this function **is** a coroutine.\n\n .. versionadded:: 1.3\n\n Parameters\n ------------\n \\*checks: Callable[[:class:`Context`], :class:`bool`]\n An argument list of checks that have been decorated with\n the :func:`check` decorator.\n\n Raises\n -------\n TypeError\n A check passed has not been decorated with the :func:`check`\n decorator.\n\n Examples\n ---------\n\n Creating a basic check to see if it's the bot owner or\n the server owner:\n\n .. code-block:: python3\n\n def is_guild_owner():\n def predicate(ctx):\n return ctx.guild is not None and ctx.guild.owner_id == ctx.author.id\n return commands.check(predicate)\n\n @bot.command()\n @commands.check_any(commands.is_owner(), is_guild_owner())\n async def only_for_owners(ctx):\n await ctx.send('Hello mister owner!')\n \"\"\"\n\n unwrapped = []\n for wrapped in checks:\n try:\n pred = wrapped.predicate\n except AttributeError:\n raise TypeError(f'{wrapped!r} must be wrapped by commands.check decorator') from None\n else:\n unwrapped.append(pred)\n\n async def predicate(ctx: Context[BotT]) -> bool:\n errors = []\n for func in unwrapped:\n try:\n value = await func(ctx)\n except CheckFailure as e:\n errors.append(e)\n else:\n if value:\n return True\n # if we're here, all checks failed\n raise CheckAnyFailure(unwrapped, errors)\n\n return check(predicate)\n\n\ndef has_role(item: Union[int, str], /) -> Check[Any]:\n \"\"\"A :func:`.check` that is added that checks if the member invoking the\n command has the role specified via the name or ID specified.\n\n If a string is specified, you must give the exact name of the role, including\n caps and spelling.\n\n If an integer is specified, you must give the exact snowflake ID of the role.\n\n If the message is invoked in a private message context then the check will\n return ``False``.\n\n This check raises one of two special exceptions, :exc:`.MissingRole` if the user\n is missing a role, or :exc:`.NoPrivateMessage` if it is used in a private message.\n Both inherit from :exc:`.CheckFailure`.\n\n .. versionchanged:: 1.1\n\n Raise :exc:`.MissingRole` or :exc:`.NoPrivateMessage`\n instead of generic :exc:`.CheckFailure`\n\n .. versionchanged:: 2.0\n\n ``item`` parameter is now positional-only.\n\n Parameters\n -----------\n item: Union[:class:`int`, :class:`str`]\n The name or ID of the role to check.\n \"\"\"\n\n def predicate(ctx: Context[BotT]) -> bool:\n if ctx.guild is None:\n raise NoPrivateMessage()\n\n # ctx.guild is None doesn't narrow ctx.author to Member\n if isinstance(item, int):\n role = ctx.author.get_role(item) # type: ignore\n else:\n role = discord.utils.get(ctx.author.roles, name=item) # type: ignore\n if role is None:\n raise MissingRole(item)\n return True\n\n return check(predicate)\n\n\ndef has_any_role(*items: Union[int, str]) -> Callable[[T], T]:\n r\"\"\"A :func:`.check` that is added that checks if the member invoking the\n command has **any** of the roles specified. This means that if they have\n one out of the three roles specified, then this check will return ``True``.\n\n Similar to :func:`.has_role`\\, the names or IDs passed in must be exact.\n\n This check raises one of two special exceptions, :exc:`.MissingAnyRole` if the user\n is missing all roles, or :exc:`.NoPrivateMessage` if it is used in a private message.\n Both inherit from :exc:`.CheckFailure`.\n\n .. versionchanged:: 1.1\n\n Raise :exc:`.MissingAnyRole` or :exc:`.NoPrivateMessage`\n instead of generic :exc:`.CheckFailure`\n\n Parameters\n -----------\n items: List[Union[:class:`str`, :class:`int`]]\n An argument list of names or IDs to check that the member has roles wise.\n\n Example\n --------\n\n .. code-block:: python3\n\n @bot.command()\n @commands.has_any_role('Library Devs', 'Moderators', 492212595072434186)\n async def cool(ctx):\n await ctx.send('You are cool indeed')\n \"\"\"\n\n def predicate(ctx):\n if ctx.guild is None:\n raise NoPrivateMessage()\n\n # ctx.guild is None doesn't narrow ctx.author to Member\n if any(\n ctx.author.get_role(item) is not None\n if isinstance(item, int)\n else discord.utils.get(ctx.author.roles, name=item) is not None\n for item in items\n ):\n return True\n raise MissingAnyRole(list(items))\n\n return check(predicate)\n\n\ndef bot_has_role(item: int, /) -> Callable[[T], T]:\n \"\"\"Similar to :func:`.has_role` except checks if the bot itself has the\n role.\n\n This check raises one of two special exceptions, :exc:`.BotMissingRole` if the bot\n is missing the role, or :exc:`.NoPrivateMessage` if it is used in a private message.\n Both inherit from :exc:`.CheckFailure`.\n\n .. versionchanged:: 1.1\n\n Raise :exc:`.BotMissingRole` or :exc:`.NoPrivateMessage`\n instead of generic :exc:`.CheckFailure`\n\n .. versionchanged:: 2.0\n\n ``item`` parameter is now positional-only.\n \"\"\"\n\n def predicate(ctx):\n if ctx.guild is None:\n raise NoPrivateMessage()\n\n if isinstance(item, int):\n role = ctx.me.get_role(item)\n else:\n role = discord.utils.get(ctx.me.roles, name=item)\n if role is None:\n raise BotMissingRole(item)\n return True\n\n return check(predicate)\n\n\ndef bot_has_any_role(*items: int) -> Callable[[T], T]:\n \"\"\"Similar to :func:`.has_any_role` except checks if the bot itself has\n any of the roles listed.\n\n This check raises one of two special exceptions, :exc:`.BotMissingAnyRole` if the bot\n is missing all roles, or :exc:`.NoPrivateMessage` if it is used in a private message.\n Both inherit from :exc:`.CheckFailure`.\n\n .. versionchanged:: 1.1\n\n Raise :exc:`.BotMissingAnyRole` or :exc:`.NoPrivateMessage`\n instead of generic checkfailure\n \"\"\"\n\n def predicate(ctx):\n if ctx.guild is None:\n raise NoPrivateMessage()\n\n me = ctx.me\n if any(\n me.get_role(item) is not None if isinstance(item, int) else discord.utils.get(me.roles, name=item) is not None\n for item in items\n ):\n return True\n raise BotMissingAnyRole(list(items))\n\n return check(predicate)\n\n\ndef has_permissions(**perms: bool) -> Check[Any]:\n \"\"\"A :func:`.check` that is added that checks if the member has all of\n the permissions necessary.\n\n Note that this check operates on the current channel permissions, not the\n guild wide permissions.\n\n The permissions passed in must be exactly like the properties shown under\n :class:`.discord.Permissions`.\n\n This check raises a special exception, :exc:`.MissingPermissions`\n that is inherited from :exc:`.CheckFailure`.\n\n Parameters\n ------------\n perms\n An argument list of permissions to check for.\n\n Example\n ---------\n\n .. code-block:: python3\n\n @bot.command()\n @commands.has_permissions(manage_messages=True)\n async def test(ctx):\n await ctx.send('You can manage messages.')\n\n \"\"\"\n\n invalid = set(perms) - set(discord.Permissions.VALID_FLAGS)\n if invalid:\n raise TypeError(f\"Invalid permission(s): {', '.join(invalid)}\")\n\n def predicate(ctx: Context[BotT]) -> bool:\n permissions = ctx.permissions\n\n missing = [perm for perm, value in perms.items() if getattr(permissions, perm) != value]\n\n if not missing:\n return True\n\n raise MissingPermissions(missing)\n\n return check(predicate)\n\n\ndef bot_has_permissions(**perms: bool) -> Check[Any]:\n \"\"\"Similar to :func:`.has_permissions` except checks if the bot itself has\n the permissions listed.\n\n This check raises a special exception, :exc:`.BotMissingPermissions`\n that is inherited from :exc:`.CheckFailure`.\n \"\"\"\n\n invalid = set(perms) - set(discord.Permissions.VALID_FLAGS)\n if invalid:\n raise TypeError(f\"Invalid permission(s): {', '.join(invalid)}\")\n\n def predicate(ctx: Context[BotT]) -> bool:\n permissions = ctx.bot_permissions\n\n missing = [perm for perm, value in perms.items() if getattr(permissions, perm) != value]\n\n if not missing:\n return True\n\n raise BotMissingPermissions(missing)\n\n return check(predicate)\n\n\ndef has_guild_permissions(**perms: bool) -> Check[Any]:\n \"\"\"Similar to :func:`.has_permissions`, but operates on guild wide\n permissions instead of the current channel permissions.\n\n If this check is called in a DM context, it will raise an\n exception, :exc:`.NoPrivateMessage`.\n\n .. versionadded:: 1.3\n \"\"\"\n\n invalid = set(perms) - set(discord.Permissions.VALID_FLAGS)\n if invalid:\n raise TypeError(f\"Invalid permission(s): {', '.join(invalid)}\")\n\n def predicate(ctx: Context[BotT]) -> bool:\n if not ctx.guild:\n raise NoPrivateMessage\n\n permissions = ctx.author.guild_permissions # type: ignore\n missing = [perm for perm, value in perms.items() if getattr(permissions, perm) != value]\n\n if not missing:\n return True\n\n raise MissingPermissions(missing)\n\n return check(predicate)\n\n\ndef bot_has_guild_permissions(**perms: bool) -> Check[Any]:\n \"\"\"Similar to :func:`.has_guild_permissions`, but checks the bot\n members guild permissions.\n\n .. versionadded:: 1.3\n \"\"\"\n\n invalid = set(perms) - set(discord.Permissions.VALID_FLAGS)\n if invalid:\n raise TypeError(f\"Invalid permission(s): {', '.join(invalid)}\")\n\n def predicate(ctx: Context[BotT]) -> bool:\n if not ctx.guild:\n raise NoPrivateMessage\n\n permissions = ctx.me.guild_permissions # type: ignore\n missing = [perm for perm, value in perms.items() if getattr(permissions, perm) != value]\n\n if not missing:\n return True\n\n raise BotMissingPermissions(missing)\n\n return check(predicate)\n\n\ndef dm_only() -> Check[Any]:\n \"\"\"A :func:`.check` that indicates this command must only be used in a\n DM context. Only private messages are allowed when\n using the command.\n\n This check raises a special exception, :exc:`.PrivateMessageOnly`\n that is inherited from :exc:`.CheckFailure`.\n\n .. versionadded:: 1.1\n \"\"\"\n\n def predicate(ctx: Context[BotT]) -> bool:\n if ctx.guild is not None:\n raise PrivateMessageOnly()\n return True\n\n return check(predicate)\n\n\ndef guild_only() -> Check[Any]:\n \"\"\"A :func:`.check` that indicates this command must only be used in a\n guild context only. Basically, no private messages are allowed when\n using the command.\n\n This check raises a special exception, :exc:`.NoPrivateMessage`\n that is inherited from :exc:`.CheckFailure`.\n\n If used on hybrid commands, this will be equivalent to the\n :func:`discord.app_commands.guild_only` decorator. In an unsupported\n context, such as a subcommand, this will still fallback to applying the\n check.\n \"\"\"\n\n # Due to implementation quirks, this check has to be re-implemented completely\n # to work with both app_commands and the command framework.\n\n def predicate(ctx: Context[BotT]) -> bool:\n if ctx.guild is None:\n raise NoPrivateMessage()\n return True\n\n def decorator(func: Union[Command, CoroFunc]) -> Union[Command, CoroFunc]:\n if isinstance(func, Command):\n func.checks.append(predicate)\n if hasattr(func, '__commands_is_hybrid__'):\n app_command = getattr(func, 'app_command', None)\n if app_command:\n app_command.guild_only = True\n else:\n if not hasattr(func, '__commands_checks__'):\n func.__commands_checks__ = []\n\n func.__commands_checks__.append(predicate)\n func.__discord_app_commands_guild_only__ = True\n\n return func\n\n if inspect.iscoroutinefunction(predicate):\n decorator.predicate = predicate\n else:\n\n @functools.wraps(predicate)\n async def wrapper(ctx: Context[BotT]):\n return predicate(ctx)\n\n decorator.predicate = wrapper\n\n return decorator # type: ignore\n\n\ndef is_owner() -> Check[Any]:\n \"\"\"A :func:`.check` that checks if the person invoking this command is the\n owner of the bot.\n\n This is powered by :meth:`.Bot.is_owner`.\n\n This check raises a special exception, :exc:`.NotOwner` that is derived\n from :exc:`.CheckFailure`.\n \"\"\"\n\n async def predicate(ctx: Context[BotT]) -> bool:\n if not await ctx.bot.is_owner(ctx.author):\n raise NotOwner('You do not own this bot.')\n return True\n\n return check(predicate)\n\n\ndef is_nsfw() -> Check[Any]:\n \"\"\"A :func:`.check` that checks if the channel is a NSFW channel.\n\n This check raises a special exception, :exc:`.NSFWChannelRequired`\n that is derived from :exc:`.CheckFailure`.\n\n If used on hybrid commands, this will be equivalent to setting the\n application command's ``nsfw`` attribute to ``True``. In an unsupported\n context, such as a subcommand, this will still fallback to applying the\n check.\n\n .. versionchanged:: 1.1\n\n Raise :exc:`.NSFWChannelRequired` instead of generic :exc:`.CheckFailure`.\n DM channels will also now pass this check.\n \"\"\"\n\n # Due to implementation quirks, this check has to be re-implemented completely\n # to work with both app_commands and the command framework.\n\n def predicate(ctx: Context[BotT]) -> bool:\n ch = ctx.channel\n if ctx.guild is None or (\n isinstance(ch, (discord.TextChannel, discord.Thread, discord.VoiceChannel)) and ch.is_nsfw()\n ):\n return True\n raise NSFWChannelRequired(ch) # type: ignore\n\n def decorator(func: Union[Command, CoroFunc]) -> Union[Command, CoroFunc]:\n if isinstance(func, Command):\n func.checks.append(predicate)\n if hasattr(func, '__commands_is_hybrid__'):\n app_command = getattr(func, 'app_command', None)\n if app_command:\n app_command.nsfw = True\n else:\n if not hasattr(func, '__commands_checks__'):\n func.__commands_checks__ = []\n\n func.__commands_checks__.append(predicate)\n func.__discord_app_commands_is_nsfw__ = True\n\n return func\n\n if inspect.iscoroutinefunction(predicate):\n decorator.predicate = predicate\n else:\n\n @functools.wraps(predicate)\n async def wrapper(ctx: Context[BotT]):\n return predicate(ctx)\n\n decorator.predicate = wrapper\n\n return decorator # type: ignore\n\n\ndef cooldown(\n rate: int,\n per: float,\n type: Union[BucketType, Callable[[Context[Any]], Any]] = BucketType.default,\n) -> Callable[[T], T]:\n \"\"\"A decorator that adds a cooldown to a :class:`.Command`\n\n A cooldown allows a command to only be used a specific amount\n of times in a specific time frame. These cooldowns can be based\n either on a per-guild, per-channel, per-user, per-role or global basis.\n Denoted by the third argument of ``type`` which must be of enum\n type :class:`.BucketType`.\n\n If a cooldown is triggered, then :exc:`.CommandOnCooldown` is triggered in\n :func:`.on_command_error` and the local error handler.\n\n A command can only have a single cooldown.\n\n Parameters\n ------------\n rate: :class:`int`\n The number of times a command can be used before triggering a cooldown.\n per: :class:`float`\n The amount of seconds to wait for a cooldown when it's been triggered.\n type: Union[:class:`.BucketType`, Callable[[:class:`.Context`], Any]]\n The type of cooldown to have. If callable, should return a key for the mapping.\n\n .. versionchanged:: 1.7\n Callables are now supported for custom bucket types.\n\n .. versionchanged:: 2.0\n When passing a callable, it now needs to accept :class:`.Context`\n rather than :class:`~discord.Message` as its only argument.\n \"\"\"\n\n def decorator(func: Union[Command, CoroFunc]) -> Union[Command, CoroFunc]:\n if isinstance(func, Command):\n func._buckets = CooldownMapping(Cooldown(rate, per), type)\n else:\n func.__commands_cooldown__ = CooldownMapping(Cooldown(rate, per), type)\n return func\n\n return decorator # type: ignore\n\n\ndef dynamic_cooldown(\n cooldown: Callable[[Context[Any]], Optional[Cooldown]],\n type: Union[BucketType, Callable[[Context[Any]], Any]],\n) -> Callable[[T], T]:\n \"\"\"A decorator that adds a dynamic cooldown to a :class:`.Command`\n\n This differs from :func:`.cooldown` in that it takes a function that\n accepts a single parameter of type :class:`.Context` and must\n return a :class:`~discord.app_commands.Cooldown` or ``None``.\n If ``None`` is returned then that cooldown is effectively bypassed.\n\n A cooldown allows a command to only be used a specific amount\n of times in a specific time frame. These cooldowns can be based\n either on a per-guild, per-channel, per-user, per-role or global basis.\n Denoted by the third argument of ``type`` which must be of enum\n type :class:`.BucketType`.\n\n If a cooldown is triggered, then :exc:`.CommandOnCooldown` is triggered in\n :func:`.on_command_error` and the local error handler.\n\n A command can only have a single cooldown.\n\n .. versionadded:: 2.0\n\n Parameters\n ------------\n cooldown: Callable[[:class:`.Context`], Optional[:class:`~discord.app_commands.Cooldown`]]\n A function that takes a message and returns a cooldown that will\n apply to this invocation or ``None`` if the cooldown should be bypassed.\n type: :class:`.BucketType`\n The type of cooldown to have.\n \"\"\"\n if not callable(cooldown):\n raise TypeError(\"A callable must be provided\")\n\n if type is BucketType.default:\n raise ValueError('BucketType.default cannot be used in dynamic cooldowns')\n\n def decorator(func: Union[Command, CoroFunc]) -> Union[Command, CoroFunc]:\n if isinstance(func, Command):\n func._buckets = DynamicCooldownMapping(cooldown, type)\n else:\n func.__commands_cooldown__ = DynamicCooldownMapping(cooldown, type)\n return func\n\n return decorator # type: ignore\n\n\ndef max_concurrency(number: int, per: BucketType = BucketType.default, *, wait: bool = False) -> Callable[[T], T]:\n \"\"\"A decorator that adds a maximum concurrency to a :class:`.Command` or its subclasses.\n\n This enables you to only allow a certain number of command invocations at the same time,\n for example if a command takes too long or if only one user can use it at a time. This\n differs from a cooldown in that there is no set waiting period or token bucket -- only\n a set number of people can run the command.\n\n .. versionadded:: 1.3\n\n Parameters\n -------------\n number: :class:`int`\n The maximum number of invocations of this command that can be running at the same time.\n per: :class:`.BucketType`\n The bucket that this concurrency is based on, e.g. ``BucketType.guild`` would allow\n it to be used up to ``number`` times per guild.\n wait: :class:`bool`\n Whether the command should wait for the queue to be over. If this is set to ``False``\n then instead of waiting until the command can run again, the command raises\n :exc:`.MaxConcurrencyReached` to its error handler. If this is set to ``True``\n then the command waits until it can be executed.\n \"\"\"\n\n def decorator(func: Union[Command, CoroFunc]) -> Union[Command, CoroFunc]:\n value = MaxConcurrency(number, per=per, wait=wait)\n if isinstance(func, Command):\n func._max_concurrency = value\n else:\n func.__commands_max_concurrency__ = value\n return func\n\n return decorator # type: ignore\n\n\ndef before_invoke(coro: Hook[CogT, ContextT], /) -> Callable[[T], T]:\n \"\"\"A decorator that registers a coroutine as a pre-invoke hook.\n\n This allows you to refer to one before invoke hook for several commands that\n do not have to be within the same cog.\n\n .. versionadded:: 1.4\n\n .. versionchanged:: 2.0\n\n ``coro`` parameter is now positional-only.\n\n Example\n ---------\n\n .. code-block:: python3\n\n async def record_usage(ctx):\n print(ctx.author, 'used', ctx.command, 'at', ctx.message.created_at)\n\n @bot.command()\n @commands.before_invoke(record_usage)\n async def who(ctx): # Output: used who at