Merge branch 'V3/develop' into cog_guide_core

.github/labeler.yml

@@ -1,17 +1,30 @@
 "Category: Admin":
+  # Source
   - redbot/cogs/admin/*
+  # Docs
+  - docs/cog_guides/admin.rst
 "Category: Alias":
+  # Source
   - redbot/cogs/alias/*
+  # Docs
+  - docs/cog_guides/alias.rst
 "Category: Audio Cog":
   - any:
       - redbot/cogs/audio/**/*
     all:
       - "!redbot/cogs/audio/**/locales/*"
 "Category: Bank API":
+  # Source
   - redbot/core/bank.py
+  # Docs
+  - docs/framework_bank.rst
 "Category: Bank Cog":
+  # Source
   - redbot/cogs/bank/*
+  # Docs
+  - docs/cog_guides/bank.rst
 "Category: Bot Core":
+  # Source
   - redbot/*
   - redbot/core/__init__.py
   - redbot/core/_sharedlibdeprecation.py
@@ -25,39 +38,80 @@
   - redbot/core/events.py
   - redbot/core/global_checks.py
   - redbot/core/settings_caches.py
+  # Docs
+  - docs/framework_apikeys.rst
+  - docs/framework_bot.rst
+  - docs/framework_cogmanager.rst
+  - docs/framework_datamanager.rst
+  - docs/framework_events.rst
+  - docs/cog_guides/cog_manager_ui.rst
 "Category: CI":
   - .github/workflows/*
 "Category: Cleanup Cog":
+  # Source
   - redbot/cogs/cleanup/*
+  # Docs
+  - docs/cog_guides/cleanup.rst
 "Category: Command Module":
+  # Source
   - any:
+      # Source
       - redbot/core/commands/*
+      # Docs
+      - docs/framework_checks.rst
+      - docs/framework_commands.rst
     all:
       - "!redbot/core/commands/help.py"
 "Category: Config":
+  # Source
   - redbot/core/drivers/*
   - redbot/core/config.py
+  # Docs
+  - docs/framework_config.rst
 "Category: CustomCom":
+  # Source
   - redbot/cogs/customcom/*
+  # Docs
+  - docs/cog_customcom.rst
+  - docs/cog_guides/customcommands.rst
 "Category: Dev Cog":
   - redbot/core/dev_commands.py
 "Category: Docs":
   - docs/**/*
 "Category: Downloader":
+  # Source
   - redbot/cogs/downloader/*
+  # Docs
+  - docs/cog_guides/downloader.rst
 "Category: Economy Cog":
+  # Source
   - redbot/cogs/economy/*
+  # Docs
+  - docs/cog_guides/economy.rst
 "Category: Filter":
+  # Source
   - redbot/cogs/filter/*
+  # Docs
+  - docs/cog_guides/filter.rst
 "Category: General Cog":
+  # Source
   - redbot/cogs/general/*
+  # Docs
+  - docs/cog_guides/general.rst
 "Category: Help":
   - redbot/core/commands/help.py
 "Category: i18n":
+  # Source
   - redbot/core/i18n.py
+  # Locale files
   - redbot/**/locales/*
+  # Docs
+  - docs/framework_i18n.rst
 "Category: Image":
+  # Source
   - redbot/cogs/image/*
+  # Docs
+  - docs/cog_guides/image.rst
 "Category: Meta":
   - ./*
   - .github/*
@@ -68,28 +122,46 @@
 "Category: Mod Cog":
   - redbot/cogs/mod/*
 "Category: Modlog API":
+  # Source
   - redbot/core/generic_casetypes.py
   - redbot/core/modlog.py
+  # Docs
+  - docs/framework_modlog.rst
 "Category: Modlog Cog":
   - redbot/cogs/modlog/*
 "Category: Mutes Cog":
   - redbot/cogs/mutes/*
 "Category: Permissions":
+  # Source
   - redbot/cogs/permissions/*
+  # Docs
+  - docs/cog_permissions.rst
 "Category: Reports Cog":
   - redbot/cogs/reports/*
 "Category: RPC/ZMQ API":
+  # Source
   - redbot/core/rpc.py
+  # Docs
+  - docs/framework_rpc.rst
 "Category: Streams":
+  # Source
   - redbot/cogs/streams/*
+  # Docs
+  - docs/cog_guides/streams.rst
 "Category: Tests":
   - redbot/pytest/*
   - tests/**/*
 "Category: Trivia Cog":
+  # Source
   - redbot/cogs/trivia/*
+  # Docs
+  - docs/cog_guides/trivia.rst
 "Category: Trivia Lists":
   - redbot/cogs/trivia/data/lists/*
 "Category: Utility Functions":
+  # Source
   - redbot/core/utils/*
+  # Docs
+  - docs/framework_utils.rst
 "Category: Warnings":
   - redbot/cogs/warnings/*

.gitignore

@@ -15,6 +15,8 @@ Pipfile.lock
 .idea/
 *.iws
 .vscode/
+*.sublime-project
+*.sublime-workspace
 
 ## Plugin-specific files:
 

CONTRIBUTING.md

@@ -83,7 +83,7 @@ We're using [tox](https://github.com/tox-dev/tox) to run all of our tests. It's
 Currently, tox does the following, creating its own virtual environments for each stage:
 - Runs all of our unit tests with [pytest](https://github.com/pytest-dev/pytest) on python 3.8 (test environment `py38`)
 - Ensures documentation builds without warnings, and all hyperlinks have a valid destination (test environment `docs`)
-- Ensures that the code meets our style guide with [black](https://github.com/ambv/black) (test environment `style`)
+- Ensures that the code meets our style guide with [black](https://github.com/psf/black) (test environment `style`)
 
 To run all of these tests, just run the command `tox` in the project directory.
 
@@ -92,9 +92,9 @@ To run a subset of these tests, use the command `tox -e <env>`, where `<env>` is
 Your PR will not be merged until all of these tests pass.
 
 ### 4.3 Style
-Our style checker of choice, [black](https://github.com/ambv/black), actually happens to be an auto-formatter. The checking functionality simply detects whether or not it would try to reformat something in your code, should you run the formatter on it. For this reason, we recommend using this tool as a formatter, regardless of any disagreements you might have with the style it enforces.
+Our style checker of choice, [black](https://github.com/psf/black), actually happens to be an auto-formatter. The checking functionality simply detects whether or not it would try to reformat something in your code, should you run the formatter on it. For this reason, we recommend using this tool as a formatter, regardless of any disagreements you might have with the style it enforces.
 
-Use the command `black --help` to see how to use this tool. The full style guide is explained in detail on [black's GitHub repository](https://github.com/ambv/black). **There is one exception to this**, however, which is that we set the line length to 99, instead of black's default 88. This is already set in `pyproject.toml` configuration file in the repo so you can simply format code with Black like so: `black <src>`.
+Use the command `black --help` to see how to use this tool. The full style guide is explained in detail on [black's GitHub repository](https://github.com/psf/black). **There is one exception to this**, however, which is that we set the line length to 99, instead of black's default 88. This is already set in `pyproject.toml` configuration file in the repo so you can simply format code with Black like so: `black <src>`.
 
 ### 4.4 Make
 You may have noticed we have a `Makefile` and a `make.bat` in the top-level directory. For now, you can do a few things with them:

README.md

@@ -32,7 +32,7 @@
   <a href="http://red-discordbot.readthedocs.io/en/stable/?badge=stable">
     <img src="https://readthedocs.org/projects/red-discordbot/badge/?version=stable" alt="Red on readthedocs.org">
   </a>
-  <a href="https://github.com/ambv/black">
+  <a href="https://github.com/psf/black">
     <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code Style: Black">
   </a>
   <a href="http://makeapullrequest.com">

docs/getting_started.rst

@@ -92,6 +92,13 @@ parameters.
     Sometimes (especially for the last argument) these double quotes are not
     required.
 
+    Arguments followed by an ellipsis ``...`` means that you may provide
+    multiple arguments for the command.
+
+    For example, the command ``[p]cog install`` in the downloader cog has
+    the syntax ``cog install <repo> <cogs...>``, meaning that you can provide
+    1 or more ``cogs`` to install from the ``repo``.
+
     Arguments followed by ``=value`` means that, if not specified,
     the argument will be equal to ``value``.
 

make.ps1

@@ -46,10 +46,12 @@ function reformat() {
 
 function stylecheck() {
     & $script:venvPython -m black --check $PSScriptRoot
+    Exit $LASTEXITCODE
 }
 
 function stylediff() {
     & $script:venvPython -m black --check --diff $PSScriptRoot
+    Exit $LASTEXITCODE
 }
 
 function newenv() {

pyproject.toml

@@ -2,22 +2,9 @@
     line-length = 99
     target-version = ['py38']
     include = '\.py$'
-    exclude = '''
+    force-exclude = '''
     /(
-          \.eggs
+        redbot\/vendored
-        | \.git
-        | \.hg
-        | \.mypy_cache
-        | \.tox
-        | \.venv
-        | _build
-        | buck-out
-        | build
-        | dist
-        | redbot\/vendored
     )/
     '''
 
-[tool.pytest.ini_options]
-    minversion = "6.0"
-    addopts = "--import-mode=importlib"

redbot/cogs/downloader/repo_manager.py

@@ -476,11 +476,20 @@ class Repo(RepoJSONMixin):
 
         if p.returncode != 0:
             stderr = p.stderr.decode(**DECODE_PARAMS).strip()
-            ambiguous_error = f"error: short SHA1 {rev} is ambiguous\nhint: The candidates are:\n"
+            ambiguous_errors = (
-            if not stderr.startswith(ambiguous_error):
+                # Git 2.31.0-rc0 and newer
+                f"error: short object ID {rev} is ambiguous\nhint: The candidates are:\n",
+                # Git 2.11.0-rc0 and newer
+                f"error: short SHA1 {rev} is ambiguous\nhint: The candidates are:\n",
+            )
+            for substring in ambiguous_errors:
+                if stderr.startswith(substring):
+                    pos = len(substring)
+                    break
+            else:
                 raise errors.UnknownRevision(f"Revision {rev} cannot be found.", git_command)
             candidates = []
-            for match in self.AMBIGUOUS_ERROR_REGEX.finditer(stderr, len(ambiguous_error)):
+            for match in self.AMBIGUOUS_ERROR_REGEX.finditer(stderr, pos):
                 candidates.append(Candidate(match["rev"], match["type"], match["desc"]))
             if candidates:
                 raise errors.AmbiguousRevision(

redbot/cogs/downloader/repos/.gitignore

@@ -1,2 +0,0 @@
-*
-!.gitignore

redbot/cogs/reports/reports.py

@@ -236,12 +236,12 @@ class Reports(commands.Cog):
         )
         return ticket_number
 
-    @commands.group(name="report", invoke_without_command=True)
+    @commands.group(name="report", usage="[text]", invoke_without_command=True)
     async def report(self, ctx: commands.Context, *, _report: str = ""):
         """Send a report.
 
         Use without arguments for interactive reporting, or do
-        `[p]report <text>` to use it non-interactively.
+        `[p]report [text]` to use it non-interactively.
         """
         author = ctx.author
         guild = ctx.guild

redbot/cogs/trivia/data/lists/hockey.yaml

@@ -1803,9 +1803,6 @@ Which fan-favorite Pittsburgh Penguin was selected by the Las Vegas Golden Knigh
 After this Pittsburgh Penguins coach was fired mid-season, Mike Sullivan took the spot and went on to win a Stanley Cup the very same year. Who is the coach that was fired?:
 - Mike Johnston
 - Johnston
-After this Pittsburgh Penguins coach was fired mid-season, Mike Sullivan took the spot and went on to win a Stanley Cup the very same year. Who is the coach that was fired?:
-- Mike Johnston
-- Johnston
 Which Pittsburgh Penguin was the subject of media ridicule after filling the Stanley Cup with hot dogs?:
 - Phil Kessel
 - Kessel
@@ -1935,12 +1932,6 @@ Which team did Bobby Orr end his career with?:
 - Blackhawks
 - Black Hawks
 - Chicago
-Which team did Bobby Orr end his career with?:
-- Chicago
-- Chicago Black Hawks
-- Chicago Blackhawks
-- Blackhawks
-- Black Hawks
 # Blackhawks Trivia by Windy City Hawkey#7814
 Who was the Captain of the 1934 Stanley Cup Champion Blackhawks?:
 - Charlie Gardiner
@@ -2112,23 +2103,6 @@ What team hosted the 2019 NHL Entry Draft?:
 - Vancouver Canucks
 - Vancouver
 - Canucks
-Who was the first player in NHL history to score 100 points in a single season, when he scored 126 total points?:
-- Phil Esposito
-- Esposito
-Who had their Detroit Red Wing number 12 retired in 1995?:
-- Sidney Abel
-- Sid Abel
-- Abel
-Which player was the first in NHL to score a full-strength, power play, short-handed, penalty shot, and open net goal in the same game?:
-- Mario Lemieux
-- Lemieux
-Which NHL player has played in the most regular season wins during his career?:
-- Scott Stevens
-- Stevens
-Which player was the first to win more than two individual trophies in one season?:
-- Stan Mikita won the Art Ross trophy, Lady Byng trophy, and Hart trophy two years in a row with the Chicago Blackhawks in 1966-67 and 1967-68.
-- Stan Mikita
-- Mikita
 What undrafted goalie has the most games played?:
 - Ed Belfour (963)
 - Ed Belfour
@@ -2325,22 +2299,6 @@ Who is the Boston Bruins all time hat trick leader?:
 Who did the Bruins trade to the Toronto Maple Leafs for the rights  of goalie prospect Tuukka Rask?:
 - Andrew Raycroft
 - Raycroft
-# Blackhawks Trivia by The_Notorious_BEN#0475
-When did the Blackhawks first reach the Stanley Cup Final?:
-- 1931
-Who did the Blackhawks play in their first Stanley Cup Final?:
-- Montréal Canadiens
-- Montreal Canadiens
-- Canadiens
-- Montreal
-- Montréal
-- habs
-Who did the Blackhawks defeat by a score of 4-1 in their first-ever game on November 17, 1926 at Chicago Coliseum?:
-- Toronto St. Patricks
-- Toronto St. Pats
-- Toronto
-- St. Patricks
-- St. Pats
 # Toronto Maple Leafs Trivia by Pikaboo#2147
 What goaltender holds the record for wins by a Maple Leafs draftee?:
 - Tukka Rask

redbot/pytest/downloader.py

@@ -10,6 +10,7 @@ from redbot.cogs.downloader.repo_manager import RepoManager, Repo, ProcessFormat
 from redbot.cogs.downloader.installable import Installable, InstalledModule
 
 __all__ = [
+    "GIT_VERSION",
     "repo_manager",
     "repo",
     "bot_repo",
@@ -27,6 +28,17 @@ __all__ = [
 ]
 
 
+def _get_git_version():
+    """Returns version tuple in format: (major, minor)"""
+    raw_version = sp.check_output(("git", "version"), text=True)[12:]
+    # we're only interested in major and minor version if we will ever need micro
+    # there's more handling needed for versions like `2.25.0-rc1` and `2.25.0.windows.1`
+    return tuple(int(n) for n in raw_version.split(".", maxsplit=3)[:2])
+
+
+GIT_VERSION = _get_git_version()
+
+
 async def fake_run_noprint(*args, **kwargs):
     fake_result_tuple = namedtuple("fake_result", "returncode result")
     res = fake_result_tuple(0, (args, kwargs))
@@ -139,6 +151,7 @@ def _init_test_repo(destination: Path):
     git_dirparams = ("git", "-C", str(destination))
     init_commands = (
         (*git_dirparams, "init"),
+        (*git_dirparams, "checkout", "-b", "master"),
         (*git_dirparams, "config", "--local", "user.name", "Cog-Creators"),
         (*git_dirparams, "config", "--local", "user.email", "cog-creators@example.org"),
         (*git_dirparams, "config", "--local", "commit.gpgSign", "false"),

setup.py

@@ -1,8 +1,4 @@
 from setuptools import setup
-import os
 
-if os.getenv("READTHEDOCS", False):
-    setup(python_requires=">=3.7")
-else:
 # Metadata and options defined in setup.cfg
 setup()

tests/cogs/downloader/test_git.py

@@ -5,6 +5,7 @@ import pytest
 
 from redbot.cogs.downloader.repo_manager import ProcessFormatter, Repo
 from redbot.pytest.downloader import (
+    GIT_VERSION,
     cloned_git_repo,
     git_repo,
     git_repo_with_remote,
@@ -314,8 +315,57 @@ async def test_git_get_full_sha1_from_invalid_ref(git_repo):
     assert p.stderr.decode().strip() == "fatal: Needed a single revision"
 
 
+@pytest.mark.skipif(
+    GIT_VERSION < (2, 31), reason="This is test for output from Git 2.31 and newer."
+)
 @pytest.mark.asyncio
 async def test_git_get_full_sha1_from_ambiguous_commits(git_repo):
+    # 2 ambiguous refs:
+    # branch ambiguous_1 - 95da0b576271cb5bee5f3e075074c03ee05fed05
+    # branch ambiguous_2 - 95da0b57a416d9c8ce950554228d1fc195c30b43
+    p = await git_repo._run(
+        ProcessFormatter().format(
+            git_repo.GIT_GET_FULL_SHA1, path=git_repo.folder_path, rev="95da0b57"
+        )
+    )
+    assert p.returncode == 128
+    assert p.stderr.decode().strip() == (
+        "error: short object ID 95da0b57 is ambiguous\n"
+        "hint: The candidates are:\n"
+        "hint:   95da0b576 commit 2019-10-22 - Ambiguous commit 16955\n"
+        "hint:   95da0b57a commit 2019-10-22 - Ambiguous commit 44414\n"
+        "fatal: Needed a single revision"
+    )
+
+
+@pytest.mark.skipif(
+    GIT_VERSION < (2, 31), reason="This is test for output from Git 2.31 and newer."
+)
+@pytest.mark.asyncio
+async def test_git_get_full_sha1_from_ambiguous_tag_and_commit(git_repo):
+    # 2 ambiguous refs:
+    # branch ambiguous_with_tag - c6f0e5ec04d99bdf8c6c78ff20d66d286eecb3ea
+    # tag ambiguous_tag_66387 - c6f0e5ec04d99bdf8c6c78ff20d66d286eecb3ea
+    p = await git_repo._run(
+        ProcessFormatter().format(
+            git_repo.GIT_GET_FULL_SHA1, path=git_repo.folder_path, rev="c6f0"
+        )
+    )
+    assert p.returncode == 128
+    assert p.stderr.decode().strip() == (
+        "error: short object ID c6f0 is ambiguous\n"
+        "hint: The candidates are:\n"
+        "hint:   c6f028f tag ambiguous_tag_66387\n"
+        "hint:   c6f0e5e commit 2019-10-24 - Commit ambiguous with tag.\n"
+        "fatal: Needed a single revision"
+    )
+
+
+@pytest.mark.skipif(
+    GIT_VERSION >= (2, 31), reason="This is test for output from Git older than 2.31."
+)
+@pytest.mark.asyncio
+async def test_git_get_full_sha1_from_ambiguous_commits_pre_2_31(git_repo):
     # 2 ambiguous refs:
     # branch ambiguous_1 - 95da0b576271cb5bee5f3e075074c03ee05fed05
     # branch ambiguous_2 - 95da0b57a416d9c8ce950554228d1fc195c30b43
@@ -334,8 +384,11 @@ async def test_git_get_full_sha1_from_ambiguous_commits(git_repo):
     )
 
 
+@pytest.mark.skipif(
+    GIT_VERSION >= (2, 31), reason="This is test for output from Git older than 2.31."
+)
 @pytest.mark.asyncio
-async def test_git_get_full_sha1_from_ambiguous_tag_and_commit(git_repo):
+async def test_git_get_full_sha1_from_ambiguous_tag_and_commit_pre_2_31(git_repo):
     # 2 ambiguous refs:
     # branch ambiguous_with_tag - c6f0e5ec04d99bdf8c6c78ff20d66d286eecb3ea
     # tag ambiguous_tag_66387 - c6f0e5ec04d99bdf8c6c78ff20d66d286eecb3ea