[pull] V3/develop from Cog-Creators:V3/develop

.github/labeler.yml

@@ -162,6 +162,7 @@
   - any:
       - redbot/core/_drivers/**/*
       - "!redbot/core/_drivers/**/locales/*"
+  - redbot/core/_config.py
   - redbot/core/config.py
   # Docs
   - docs/framework_config.rst
@@ -215,6 +216,7 @@
   - redbot/core/commands/help.py
 "Category: Core - i18n":
   # Source
+  - redbot/core/_i18n.py
   - redbot/core/i18n.py
   # Locale files
   - redbot/**/locales/*

.readthedocs.yml

@@ -4,6 +4,12 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.8"
+  jobs:
+    install:
+      - pip install .[doc]
+
+sphinx:
+  configuration: docs/conf.py
 
 python:
   install:

redbot/cogs/audio/core/commands/llset.py

@@ -10,10 +10,11 @@
 from redbot.core import commands
 from redbot.core.data_manager import cog_data_path
 from redbot.core.i18n import Translator
-from redbot.core.utils.chat_formatting import box, inline
+from redbot.core.utils.chat_formatting import box, humanize_list, inline
 
 from ..abc import MixinMeta
 from ..cog_utils import CompositeMetaClass
+from ...managed_node import version_pins
 from ...utils import (
     MAX_JAVA_RAM,
     DEFAULT_LAVALINK_YAML,
@@ -29,6 +30,16 @@
 _ = Translator("Audio", Path(__file__))
 
 
+class LavalinkSetupJavaCommand(commands.Command):
+    def format_text_for_context(self, ctx: commands.Context, text: str) -> str:
+        text = super().format_text_for_context(ctx, text)
+        return text.format(
+            supported_java_versions=humanize_list(
+                list(map(str, version_pins.SUPPORTED_JAVA_VERSIONS))
+            ),
+        )
+
+
 class LavalinkSetupCommands(MixinMeta, metaclass=CompositeMetaClass):
     @commands.group(name="llset")
     @commands.is_owner()
@@ -43,15 +54,15 @@ async def command_llset(self, ctx: commands.Context):
         All the commands in here have the potential to break the Audio cog.
         """
 
-    @command_llset.command(name="java")
+    @command_llset.command(name="java", cls=LavalinkSetupJavaCommand)
     @has_managed_server()
     async def command_llset_java(self, ctx: commands.Context, *, java_path: str = "java"):
         """Change your Java executable path.
 
         This command shouldn't need to be used most of the time, and is only useful if the host machine has conflicting Java versions.
 
         If changing this make sure that the Java executable you set is supported by Audio.
-        The current supported versions are Java 17 and 11.
+        The current supported versions are Java {supported_java_versions}.
 
         Enter nothing or "java" to reset it back to default.
         """

redbot/cogs/audio/core/events/dpy.py

@@ -23,6 +23,7 @@
 from redbot.core.utils.chat_formatting import box, humanize_list, underline, bold
 
 from ...errors import TrackEnqueueError, AudioError
+from ...managed_node import version_pins
 from ..abc import MixinMeta
 from ..cog_utils import CompositeMetaClass
 
@@ -87,7 +88,7 @@
         "This command will change the executable path of Java, "
         "this is useful if you have multiple installations of Java and the default one is causing issues. "
         "Please don't change this unless you are certain that the Java version you are specifying is supported by Red. "
-        "The default and supported versions are currently Java 17 and 11."
+        "The supported versions are currently Java {supported_java_versions}."
     ),
     "command_llset_heapsize": _(
         "This command will change the maximum RAM allocation for the managed Lavalink node, "
@@ -279,7 +280,11 @@ async def cog_before_invoke(self, ctx: commands.Context) -> None:
                     "If you wish to continue, enter this case sensitive token without spaces as your next message."
                     "\n\n{confirm_token}"
                 ).format(
-                    template=_(DANGEROUS_COMMANDS[ctx.command.callback.__name__]),
+                    template=_(DANGEROUS_COMMANDS[ctx.command.callback.__name__]).format(
+                        supported_java_versions=humanize_list(
+                            list(map(str, version_pins.SUPPORTED_JAVA_VERSIONS))
+                        ),
+                    ),
                     confirm_token=box(confirm_token, lang="py"),
                 )
                 sent = await ctx.send(message)

redbot/cogs/audio/managed_node/__init__.py

@@ -3,14 +3,13 @@
 
 from .ll_server_config import generate_server_config, get_default_server_config
 from .ll_version import LAVALINK_BUILD_LINE, LavalinkOldVersion, LavalinkVersion
-from .version_pins import JAR_VERSION, YT_PLUGIN_VERSION
+from . import version_pins
 
 __all__ = (
     "generate_server_config",
     "get_default_server_config",
     "LAVALINK_BUILD_LINE",
     "LavalinkOldVersion",
     "LavalinkVersion",
-    "JAR_VERSION",
-    "YT_PLUGIN_VERSION",
+    "version_pins",
 )

redbot/cogs/audio/managed_node/version_pins.py

@@ -1,9 +1,19 @@
-from typing import Final
+from typing import Final, Tuple
 
 from .ll_version import LavalinkVersion
 
-__all__ = ("JAR_VERSION", "YT_PLUGIN_VERSION")
+__all__ = (
+    "JAR_VERSION",
+    "YT_PLUGIN_VERSION",
+    "SUPPORTED_JAVA_VERSIONS",
+    "LATEST_SUPPORTED_JAVA_VERSION",
+    "OLDER_SUPPORTED_JAVA_VERSIONS",
+)
 
 
 JAR_VERSION: Final[LavalinkVersion] = LavalinkVersion(3, 7, 12, red=1)
 YT_PLUGIN_VERSION: Final[str] = "1.11.2"
+# keep this sorted from oldest to latest
+SUPPORTED_JAVA_VERSIONS: Final[Tuple[int, ...]] = (11, 17)
+LATEST_SUPPORTED_JAVA_VERSION: Final = SUPPORTED_JAVA_VERSIONS[-1]
+OLDER_SUPPORTED_JAVA_VERSIONS: Final[Tuple[int, ...]] = SUPPORTED_JAVA_VERSIONS[:-1]

redbot/cogs/audio/manager.py

@@ -21,6 +21,7 @@
 
 from redbot.core import data_manager, Config
 from redbot.core.i18n import Translator
+from redbot.core.utils.chat_formatting import humanize_list
 
 from . import managed_node
 from .errors import (
@@ -36,6 +37,7 @@
     NoProcessFound,
     NodeUnhealthy,
 )
+from .managed_node import version_pins
 from .managed_node.ll_version import LAVALINK_BUILD_LINE, LavalinkVersion, LavalinkOldVersion
 from .utils import (
     get_max_allocation_size,
@@ -109,7 +111,7 @@
 class ServerManager:
     LAVALINK_DOWNLOAD_URL: Final[str] = (
         "https://github.com/Cog-Creators/Lavalink-Jars/releases/download/"
-        f"{managed_node.JAR_VERSION}/"
+        f"{version_pins.JAR_VERSION}/"
         "Lavalink.jar"
     )
 
@@ -254,15 +256,29 @@ async def _get_jar_args(self) -> Tuple[List[str], Optional[str]]:
             if self._java_version is None:
                 extras = ""
             else:
-                extras = f" however you have version {self._java_version} (executable: {self._java_exc})"
+                version = ".".join(map(str, self._java_version))
+                extras = f" however you have version {version} (executable: {self._java_exc})"
+            supported_versions = humanize_list(
+                list(map(str, version_pins.SUPPORTED_JAVA_VERSIONS)),
+                locale="en-US",
+                style="or-short",
+            )
+            latest_version = str(version_pins.LATEST_SUPPORTED_JAVA_VERSION)
+            older_versions = humanize_list(
+                list(map(str, reversed(version_pins.OLDER_SUPPORTED_JAVA_VERSIONS))),
+                locale="en-US",
+                style="or-short",
+            )
             raise UnsupportedJavaException(
                 await replace_p_with_prefix(
                     self.cog.bot,
-                    f"The managed Lavalink node requires Java 17 or 11 to run{extras};\n"
-                    "Either install version 17 (or 11) and restart the bot or connect to an external Lavalink node "
-                    "(https://docs.discord.red/en/stable/install_guides/index.html)\n"
-                    "If you already have Java 17 or 11 installed then then you will need to specify the executable path, "
-                    "use '[p]llset java' to set the correct Java 17 or 11 executable.",
+                    f"The managed Lavalink node requires Java {supported_versions} to run{extras};\n"
+                    f"Either install version {latest_version} (or {older_versions})"
+                    " and restart the bot or connect to an external Lavalink node"
+                    " (https://docs.discord.red/en/stable/install_guides/index.html)\n"
+                    f"If you already have Java {supported_versions} installed"
+                    " then you will need to specify the executable path,"
+                    f" use '[p]llset java' to set the correct Java {supported_versions} executable.",
                 )  # TODO: Replace with Audio docs when they are out
             )
         java_xms, java_xmx = list((await self._config.java.all()).values())
@@ -300,7 +316,7 @@ async def _has_java(self) -> Tuple[bool, Optional[Tuple[int, int]]]:
             self._java_version = None
         else:
             self._java_version = await self._get_java_version()
-            self._java_available = self._java_version[0] in (11, 17)
+            self._java_available = self._java_version[0] in version_pins.SUPPORTED_JAVA_VERSIONS
             self._java_exc = java_exec
         return self._java_available, self._java_version
 
@@ -386,7 +402,7 @@ async def _download_jar(self) -> None:
                     # A 404 means our LAVALINK_DOWNLOAD_URL is invalid, so likely the jar version
                     # hasn't been published yet
                     raise LavalinkDownloadFailed(
-                        f"Lavalink jar version {managed_node.JAR_VERSION}"
+                        f"Lavalink jar version {version_pins.JAR_VERSION}"
                         " hasn't been published yet",
                         response=response,
                         should_retry=False,
@@ -474,7 +490,7 @@ async def _is_up_to_date(self):
         self._jvm = java["jvm"].decode()
         self._lavaplayer = lavaplayer["lavaplayer"].decode()
         self._buildtime = date
-        self._up_to_date = self._lavalink_version >= managed_node.JAR_VERSION
+        self._up_to_date = self._lavalink_version >= version_pins.JAR_VERSION
         return self._up_to_date
 
     async def maybe_download_jar(self):
@@ -494,7 +510,7 @@ async def maybe_download_jar(self):
             log.info(
                 "Lavalink version outdated, triggering update from %s to %s...",
                 self._lavalink_version,
-                managed_node.JAR_VERSION,
+                version_pins.JAR_VERSION,
             )
             await self._download_jar()
         else:

redbot/core/_config.py

@@ -0,0 +1,26 @@
+import weakref
+from typing import Tuple, Type
+
+from redbot.core.config import Config, _config_cache
+from redbot.core._drivers import BaseDriver
+
+__all__ = ("get_latest_confs", "migrate")
+
+_retrieved = weakref.WeakSet()
+
+
+def get_latest_confs() -> Tuple[Config, ...]:
+    global _retrieved
+    ret = set(_config_cache.values()) - set(_retrieved)
+    _retrieved |= ret
+    return tuple(ret)
+
+
+async def migrate(cur_driver_cls: Type[BaseDriver], new_driver_cls: Type[BaseDriver]) -> None:
+    """Migrate from one driver type to another."""
+    # Get custom group data
+    core_conf = Config.get_core_conf(allow_old=True)
+    core_conf.init_custom("CUSTOM_GROUPS", 2)
+    all_custom_group_data = await core_conf.custom("CUSTOM_GROUPS").all()
+
+    await cur_driver_cls.migrate_to(new_driver_cls, all_custom_group_data)

redbot/core/_drivers/__init__.py

@@ -8,6 +8,8 @@
 
 __all__ = [
     "get_driver",
+    "get_driver_class",
+    "get_driver_class_include_old",
     "ConfigCategory",
     "IdentifierData",
     "BaseDriver",
@@ -32,7 +34,7 @@ class BackendType(enum.Enum):
 _DRIVER_CLASSES = {BackendType.JSON: JsonDriver, BackendType.POSTGRES: PostgresDriver}
 
 
-def _get_driver_class_include_old(storage_type: Optional[BackendType] = None) -> Type[BaseDriver]:
+def get_driver_class_include_old(storage_type: Optional[BackendType] = None) -> Type[BaseDriver]:
     """
     ONLY for use in CLI for moving data away from a no longer supported backend
     """
@@ -115,7 +117,7 @@ def get_driver(
         if not allow_old:
             driver_cls: Type[BaseDriver] = get_driver_class(storage_type)
         else:
-            driver_cls: Type[BaseDriver] = _get_driver_class_include_old(storage_type)
+            driver_cls: Type[BaseDriver] = get_driver_class_include_old(storage_type)
     except ValueError:
         if storage_type in (BackendType.MONGOV1, BackendType.MONGO):
             raise RuntimeError(

redbot/core/_drivers/_mongo.py

@@ -18,7 +18,7 @@
     pymongo = None
 
 from .. import errors
-from .base import BaseDriver, IdentifierData
+from .base import BaseDriver, IdentifierData, MissingExtraRequirements
 
 __all__ = ["MongoDriver"]
 
@@ -33,7 +33,7 @@ class MongoDriver(BaseDriver):
     @classmethod
     async def initialize(cls, **storage_details) -> None:
         if motor is None:
-            raise errors.MissingExtraRequirements(
+            raise MissingExtraRequirements(
                 "Red must be installed with the [mongo] extra to use the MongoDB driver"
             )
         uri = storage_details.get("URI", "mongodb")

redbot/core/_drivers/base.py

@@ -6,7 +6,11 @@
 
 from redbot.core.utils._internal_utils import RichIndefiniteBarColumn
 
-__all__ = ["BaseDriver", "IdentifierData", "ConfigCategory"]
+__all__ = ("BaseDriver", "IdentifierData", "ConfigCategory", "MissingExtraRequirements")
+
+
+class MissingExtraRequirements(Exception):
+    """Raised when an extra requirement is missing but required."""
 
 
 class ConfigCategory(str, enum.Enum):

redbot/core/_drivers/postgres/postgres.py

@@ -11,7 +11,7 @@
     asyncpg = None
 
 from ... import data_manager, errors
-from ..base import BaseDriver, IdentifierData, ConfigCategory
+from ..base import BaseDriver, IdentifierData, ConfigCategory, MissingExtraRequirements
 from ..log import log
 
 __all__ = ["PostgresDriver"]
@@ -41,7 +41,7 @@ class PostgresDriver(BaseDriver):
     @classmethod
     async def initialize(cls, **storage_details) -> None:
         if asyncpg is None:
-            raise errors.MissingExtraRequirements(
+            raise MissingExtraRequirements(
                 "Red must be installed with the [postgres] extra to use the PostgreSQL driver"
             )
         cls._pool = await asyncpg.create_pool(**storage_details)

redbot/core/_events.py

@@ -21,7 +21,7 @@
 )
 from .. import __version__ as red_version, version_info as red_version_info
 from . import commands
-from .config import get_latest_confs
+from ._config import get_latest_confs
 from .utils._internal_utils import (
     fuzzy_command_search,
     format_fuzzy_results,