Privatize APIs by renaming or removing them from __all__ (#6021)

redbot/core/_cog_manager.py

@@ -18,7 +18,7 @@ from .data_manager import cog_data_path
 
 from .utils.chat_formatting import box, pagify, humanize_list, inline
 
-__all__ = ["CogManager"]
+__all__ = ("CogManager", "CogManagerUI")
 
 
 class NoSuchCog(ImportError):

redbot/core/_rpc.py

@@ -8,11 +8,11 @@ from aiohttp_json_rpc.rpc import JsonRpcMethod
 
 import logging
 
-from redbot.core.cli import ExitCodes
+from redbot.core._cli import ExitCodes
 
 log = logging.getLogger("red.rpc")
 
-__all__ = ["RPC", "RPCMixin", "get_name"]
+__all__ = ("RPC", "RPCMixin", "get_name")
 
 
 def get_name(func, prefix=""):

redbot/core/app_commands/__init__.py

@@ -59,3 +59,57 @@ from discord.app_commands import (
     locale_str as locale_str,
     rename as rename,
 )
+
+__all__ = (
+    "AllChannels",
+    "AppCommand",
+    "AppCommandChannel",
+    "AppCommandError",
+    "AppCommandGroup",
+    "AppCommandPermissions",
+    "AppCommandThread",
+    "Argument",
+    "BotMissingPermissions",
+    "Command",
+    "CommandAlreadyRegistered",
+    "CommandInvokeError",
+    "CommandLimitReached",
+    "CommandNotFound",
+    "CommandOnCooldown",
+    "CommandSignatureMismatch",
+    "CommandSyncFailure",
+    "CommandTree",
+    "ContextMenu",
+    "Cooldown",
+    "Group",
+    "GuildAppCommandPermissions",
+    "MissingAnyRole",
+    "MissingApplicationID",
+    "MissingPermissions",
+    "MissingRole",
+    "Namespace",
+    "NoPrivateMessage",
+    "Parameter",
+    "Range",
+    "Transform",
+    "Transformer",
+    "TransformerError",
+    "TranslationContext",
+    "TranslationContextLocation",
+    "TranslationContextTypes",
+    "TranslationError",
+    "Translator",
+    "autocomplete",
+    "check",
+    "CheckFailure",
+    "Choice",
+    "choices",
+    "command",
+    "context_menu",
+    "default_permissions",
+    "describe",
+    "guild_only",
+    "guilds",
+    "locale_str",
+    "rename",
+)

redbot/core/bank.py

@@ -20,15 +20,19 @@ if TYPE_CHECKING:
 
 _ = Translator("Bank API", __file__)
 
-__all__ = [
+__all__ = (
+    "is_owner_if_bank_global",
     "Account",
     "get_balance",
+    "can_spend",
     "set_balance",
     "withdraw_credits",
     "deposit_credits",
-    "can_spend",
     "transfer_credits",
     "wipe_bank",
+    "bank_prune",
+    "get_leaderboard",
+    "get_leaderboard_position",
     "get_account",
     "is_global",
     "set_global",
@@ -36,15 +40,13 @@ __all__ = [
     "set_bank_name",
     "get_currency_name",
     "set_currency_name",
-    "get_default_balance",
-    "set_default_balance",
     "get_max_balance",
     "set_max_balance",
-    "cost",
+    "get_default_balance",
+    "set_default_balance",
     "AbortPurchase",
-    "bank_prune",
-    "is_owner_if_bank_global",
-]
+    "cost",
+)
 
 _MAX_BALANCE = 2**63 - 1
 

redbot/core/bot.py

@@ -37,15 +37,15 @@ import discord
 from discord.ext import commands as dpy_commands
 from discord.ext.commands import when_mentioned_or
 
-from . import Config, i18n, app_commands, commands, errors, drivers, modlog, bank
-from .cli import ExitCodes
-from .cog_manager import CogManager, CogManagerUI
+from . import Config, i18n, app_commands, commands, errors, _drivers, modlog, bank
+from ._cli import ExitCodes
+from ._cog_manager import CogManager, CogManagerUI
 from .core_commands import Core
 from .data_manager import cog_data_path
 from .dev_commands import Dev
-from .events import init_events
-from .global_checks import init_global_checks
-from .settings_caches import (
+from ._events import init_events
+from ._global_checks import init_global_checks
+from ._settings_caches import (
     PrefixManager,
     IgnoreManager,
     WhitelistBlacklistManager,
@@ -53,7 +53,7 @@ from .settings_caches import (
     I18nManager,
 )
 from .utils.predicates import MessagePredicate
-from .rpc import RPCMixin
+from ._rpc import RPCMixin
 from .tree import RedTree
 from .utils import can_user_send_messages_in, common_filters, AsyncIter
 from .utils.chat_formatting import box, text_to_file
@@ -2161,7 +2161,7 @@ class Red(
     async def close(self):
         """Logs out of Discord and closes all connections."""
         await super().close()
-        await drivers.get_driver_class().teardown()
+        await _drivers.get_driver_class().teardown()
         try:
             if self.rpc_enabled:
                 await self.rpc.close()

redbot/core/commands/__init__.py

@@ -207,3 +207,194 @@ from discord.ext.commands import (
     parameter as parameter,
     HybridCommandError as HybridCommandError,
 )
+
+__all__ = (
+    "Cog",
+    "CogMixin",
+    "CogCommandMixin",
+    "CogGroupMixin",
+    "Command",
+    "Group",
+    "GroupCog",
+    "GroupMixin",
+    "command",
+    "HybridCommand",
+    "HybridGroup",
+    "hybrid_command",
+    "hybrid_group",
+    "group",
+    "RedUnhandledAPI",
+    "RESERVED_COMMAND_NAMES",
+    "Context",
+    "GuildContext",
+    "DMContext",
+    "DictConverter",
+    "RelativedeltaConverter",
+    "TimedeltaConverter",
+    "get_dict_converter",
+    "get_timedelta_converter",
+    "parse_relativedelta",
+    "parse_timedelta",
+    "NoParseOptional",
+    "UserInputOptional",
+    "RawUserIdConverter",
+    "CogConverter",
+    "CommandConverter",
+    "BotMissingPermissions",
+    "UserFeedbackCheckFailure",
+    "ArgParserFailure",
+    "red_help",
+    "RedHelpFormatter",
+    "HelpSettings",
+    "CheckPredicate",
+    "GlobalPermissionModel",
+    "GuildPermissionModel",
+    "PermissionModel",
+    "PrivilegeLevel",
+    "PermState",
+    "Requires",
+    "permissions_check",
+    "bot_has_permissions",
+    "bot_in_a_guild",
+    "bot_can_manage_channel",
+    "bot_can_react",
+    "has_permissions",
+    "can_manage_channel",
+    "has_guild_permissions",
+    "is_owner",
+    "guildowner",
+    "guildowner_or_can_manage_channel",
+    "guildowner_or_permissions",
+    "admin",
+    "admin_or_can_manage_channel",
+    "admin_or_permissions",
+    "mod",
+    "mod_or_can_manage_channel",
+    "mod_or_permissions",
+    "BadArgument",
+    "EmojiConverter",
+    "GuildConverter",
+    "InvalidEndOfQuotedStringError",
+    "MemberConverter",
+    "BotMissingRole",
+    "PrivateMessageOnly",
+    "HelpCommand",
+    "MinimalHelpCommand",
+    "DisabledCommand",
+    "ExtensionFailed",
+    "Bot",
+    "NotOwner",
+    "CategoryChannelConverter",
+    "CogMeta",
+    "ConversionError",
+    "UserInputError",
+    "Converter",
+    "InviteConverter",
+    "ExtensionError",
+    "Cooldown",
+    "CheckFailure",
+    "PartialMessageConverter",
+    "MessageConverter",
+    "MissingPermissions",
+    "BadUnionArgument",
+    "DefaultHelpCommand",
+    "ExtensionNotFound",
+    "UserConverter",
+    "MissingRole",
+    "CommandOnCooldown",
+    "MissingAnyRole",
+    "ExtensionNotLoaded",
+    "clean_content",
+    "CooldownMapping",
+    "ArgumentParsingError",
+    "RoleConverter",
+    "CommandError",
+    "TextChannelConverter",
+    "UnexpectedQuoteError",
+    "Paginator",
+    "BucketType",
+    "NoEntryPointError",
+    "CommandInvokeError",
+    "TooManyArguments",
+    "Greedy",
+    "ExpectedClosingQuoteError",
+    "ColourConverter",
+    "ColorConverter",
+    "VoiceChannelConverter",
+    "StageChannelConverter",
+    "NSFWChannelRequired",
+    "IDConverter",
+    "MissingRequiredArgument",
+    "GameConverter",
+    "CommandNotFound",
+    "BotMissingAnyRole",
+    "NoPrivateMessage",
+    "AutoShardedBot",
+    "ExtensionAlreadyLoaded",
+    "PartialEmojiConverter",
+    "check_any",
+    "max_concurrency",
+    "CheckAnyFailure",
+    "MaxConcurrency",
+    "MaxConcurrencyReached",
+    "bot_has_guild_permissions",
+    "CommandRegistrationError",
+    "GuildNotFound",
+    "MessageNotFound",
+    "MemberNotFound",
+    "UserNotFound",
+    "ChannelNotFound",
+    "ChannelNotReadable",
+    "BadColourArgument",
+    "RoleNotFound",
+    "BadInviteArgument",
+    "EmojiNotFound",
+    "PartialEmojiConversionFailure",
+    "BadBoolArgument",
+    "TooManyFlags",
+    "MissingRequiredFlag",
+    "flag",
+    "FlagError",
+    "ObjectNotFound",
+    "GuildStickerNotFound",
+    "ThreadNotFound",
+    "GuildChannelConverter",
+    "run_converters",
+    "Flag",
+    "BadFlagArgument",
+    "BadColorArgument",
+    "dynamic_cooldown",
+    "BadLiteralArgument",
+    "DynamicCooldownMapping",
+    "ThreadConverter",
+    "GuildStickerConverter",
+    "ObjectConverter",
+    "FlagConverter",
+    "MissingFlagArgument",
+    "ScheduledEventConverter",
+    "ScheduledEventNotFound",
+    "check",
+    "guild_only",
+    "cooldown",
+    "dm_only",
+    "is_nsfw",
+    "has_role",
+    "has_any_role",
+    "bot_has_role",
+    "when_mentioned_or",
+    "when_mentioned",
+    "bot_has_any_role",
+    "before_invoke",
+    "after_invoke",
+    "CurrentChannel",
+    "Author",
+    "param",
+    "MissingRequiredAttachment",
+    "Parameter",
+    "ForumChannelConverter",
+    "CurrentGuild",
+    "Range",
+    "RangeError",
+    "parameter",
+    "HybridCommandError",
+)

redbot/core/commands/commands.py

@@ -68,7 +68,7 @@ else:
     _P = TypeVar("_P")
 
 
-__all__ = [
+__all__ = (
     "Cog",
     "CogMixin",
     "CogCommandMixin",
@@ -77,13 +77,15 @@ __all__ = [
     "Group",
     "GroupCog",
     "GroupMixin",
+    "HybridCommand",
+    "HybridGroup",
     "command",
     "group",
     "hybrid_command",
     "hybrid_group",
     "RESERVED_COMMAND_NAMES",
     "RedUnhandledAPI",
-]
+)
 
 #: The following names are reserved for various reasons
 RESERVED_COMMAND_NAMES = (

redbot/core/commands/errors.py

@@ -4,6 +4,7 @@ import discord
 from discord.ext import commands
 
 __all__ = (
+    "ConversionFailure",
     "BotMissingPermissions",
     "UserFeedbackCheckFailure",
     "ArgParserFailure",

redbot/core/config.py

@@ -19,9 +19,15 @@ from typing import (
 
 import discord
 
-from .drivers import IdentifierData, get_driver, ConfigCategory, BaseDriver
+from ._drivers import BaseDriver, ConfigCategory, IdentifierData, get_driver
 
-__all__ = ["Config", "get_latest_confs", "migrate"]
+__all__ = (
+    "ConfigCategory",
+    "IdentifierData",
+    "Value",
+    "Group",
+    "Config",
+)
 
 log = logging.getLogger("red.config")
 
@@ -122,21 +128,22 @@ class _ValueCtxManager(Awaitable[_T], AsyncContextManager[_T]):  # pylint: disab
 class Value:
     """A singular "value" of data.
 
+    This class should not be instantiated directly - you should get instances of this class
+    through methods and attribute lookup on instances of `Config` and `Group`.
+
     Attributes
     ----------
     identifier_data : IdentifierData
         Information on identifiers for this value.
     default
         The default value for the data element that `identifiers` points at.
-    driver : `redbot.core.drivers.BaseDriver`
-        A reference to `Config.driver`.
 
     """
 
     def __init__(self, identifier_data: IdentifierData, default_value, driver, config: "Config"):
         self.identifier_data = identifier_data
         self.default = default_value
-        self.driver = driver
+        self._driver = driver
         self._config = config
 
     def get_lock(self) -> asyncio.Lock:
@@ -174,7 +181,7 @@ class Value:
 
     async def _get(self, default=...):
         try:
-            ret = await self.driver.get(self.identifier_data)
+            ret = await self._driver.get(self.identifier_data)
         except KeyError:
             return default if default is not ... else self.default
         return ret
@@ -255,13 +262,13 @@ class Value:
         """
         if isinstance(value, dict):
             value = _str_key_dict(value)
-        await self.driver.set(self.identifier_data, value=value)
+        await self._driver.set(self.identifier_data, value=value)
 
     async def clear(self):
         """
         Clears the value from record for the data element pointed to by `identifiers`.
         """
-        await self.driver.clear(self.identifier_data)
+        await self._driver.clear(self.identifier_data)
 
 
 class Group(Value):
@@ -271,14 +278,15 @@ class Group(Value):
     Inherits from `Value` which means that all of the attributes and methods
     available in `Value` are also available when working with a `Group` object.
 
+    This class should not be instantiated directly - you should get instances of this class
+    through methods and attribute lookup on instances of `Config` and `Group`.
+
     Attributes
     ----------
     defaults : `dict`
         All registered default values for this Group.
     force_registration : `bool`
         Same as `Config.force_registration`.
-    driver : `redbot.core.drivers.BaseDriver`
-        A reference to `Config.driver`.
 
     """
 
@@ -292,9 +300,9 @@ class Group(Value):
     ):
         self._defaults = defaults
         self.force_registration = force_registration
-        self.driver = driver
+        self._driver = driver
 
-        super().__init__(identifier_data, {}, self.driver, config)
+        super().__init__(identifier_data, {}, self._driver, config)
 
     @property
     def defaults(self):
@@ -340,7 +348,7 @@ class Group(Value):
             return Group(
                 identifier_data=new_identifiers,
                 defaults=self._defaults[item],
-                driver=self.driver,
+                driver=self._driver,
                 force_registration=self.force_registration,
                 config=self._config,
             )
@@ -348,7 +356,7 @@ class Group(Value):
             return Value(
                 identifier_data=new_identifiers,
                 default_value=self._defaults[item],
-                driver=self.driver,
+                driver=self._driver,
                 config=self._config,
             )
         elif self.force_registration:
@@ -357,7 +365,7 @@ class Group(Value):
             return Value(
                 identifier_data=new_identifiers,
                 default_value=None,
-                driver=self.driver,
+                driver=self._driver,
                 config=self._config,
             )
 
@@ -383,7 +391,7 @@ class Group(Value):
         """
         path = tuple(str(p) for p in nested_path)
         identifier_data = self.identifier_data.get_child(*path)
-        await self.driver.clear(identifier_data)
+        await self._driver.clear(identifier_data)
 
     def is_group(self, item: Any) -> bool:
         """A helper method for `__getattr__`. Most developers will have no need
@@ -502,7 +510,7 @@ class Group(Value):
 
         identifier_data = self.identifier_data.get_child(*path)
         try:
-            raw = await self.driver.get(identifier_data)
+            raw = await self._driver.get(identifier_data)
         except KeyError:
             if default is not ...:
                 return default
@@ -587,7 +595,7 @@ class Group(Value):
         identifier_data = self.identifier_data.get_child(*path)
         if isinstance(value, dict):
             value = _str_key_dict(value)
-        await self.driver.set(identifier_data, value=value)
+        await self._driver.set(identifier_data, value=value)
 
 
 class Config(metaclass=ConfigMeta):
@@ -612,8 +620,6 @@ class Config(metaclass=ConfigMeta):
     unique_identifier : `int`
         Unique identifier provided to differentiate cog data when name
         conflicts occur.
-    driver
-        An instance of a driver that implements `redbot.core.drivers.BaseDriver`.
     force_registration : `bool`
         Determines if Config should throw an error if a cog attempts to access
         an attribute which has not been previously registered.
@@ -644,7 +650,7 @@ class Config(metaclass=ConfigMeta):
         self.cog_name = cog_name
         self.unique_identifier = unique_identifier
 
-        self.driver = driver
+        self._driver = driver
         self.force_registration = force_registration
         self._defaults = defaults or {}
 
@@ -940,7 +946,7 @@ class Config(metaclass=ConfigMeta):
         return Group(
             identifier_data=identifier_data,
             defaults=defaults,
-            driver=self.driver,
+            driver=self._driver,
             force_registration=self.force_registration,
             config=self,
         )
@@ -1184,7 +1190,7 @@ class Config(metaclass=ConfigMeta):
         defaults = self.defaults.get(scope, {})
 
         try:
-            dict_ = await self.driver.get(group.identifier_data)
+            dict_ = await self._driver.get(group.identifier_data)
         except KeyError:
             pass
         else:
@@ -1301,7 +1307,7 @@ class Config(metaclass=ConfigMeta):
         if guild is None:
             group = self._get_base_group(self.MEMBER)
             try:
-                dict_ = await self.driver.get(group.identifier_data)
+                dict_ = await self._driver.get(group.identifier_data)
             except KeyError:
                 pass
             else:
@@ -1310,7 +1316,7 @@ class Config(metaclass=ConfigMeta):
         else:
             group = self._get_base_group(self.MEMBER, str(guild.id))
             try:
-                guild_data = await self.driver.get(group.identifier_data)
+                guild_data = await self._driver.get(group.identifier_data)
             except KeyError:
                 pass
             else:
@@ -1338,7 +1344,7 @@ class Config(metaclass=ConfigMeta):
         if not scopes:
             # noinspection PyTypeChecker
             identifier_data = IdentifierData(self.cog_name, self.unique_identifier, "", (), (), 0)
-            group = Group(identifier_data, defaults={}, driver=self.driver, config=self)
+            group = Group(identifier_data, defaults={}, driver=self._driver, config=self)
         else:
             cat, *scopes = scopes
             group = self._get_base_group(cat, *scopes)

redbot/core/data_manager.py

@@ -9,21 +9,19 @@ from pathlib import Path
 from typing import Any, Dict
 
 import platformdirs
-from discord.utils import deprecated
 
 from . import commands
-from .cli import ExitCodes
+from ._cli import ExitCodes
 
-__all__ = [
-    "create_temp_config",
-    "load_basic_configuration",
+__all__ = (
     "cog_data_path",
     "core_data_path",
-    "load_bundled_data",
     "bundled_data_path",
+    "data_path",
+    "metadata_file",
     "storage_details",
     "storage_type",
-]
+)
 
 log = logging.getLogger("red.data_manager")
 
@@ -197,12 +195,6 @@ def core_data_path() -> Path:
     return core_path.resolve()
 
 
-# noinspection PyUnusedLocal
-@deprecated("bundled_data_path() without calling this function")
-def load_bundled_data(cog_instance, init_location: str):
-    pass
-
-
 def bundled_data_path(cog_instance: commands.Cog) -> Path:
     """
     Get the path to the "data" directory bundled with this cog.
@@ -239,6 +231,28 @@ def bundled_data_path(cog_instance: commands.Cog) -> Path:
     return bundled_path
 
 
+def data_path() -> Path:
+    """Gets the base data path.
+
+    Returns
+    -------
+    str
+        Storage type.
+    """
+    return _base_data_path()
+
+
+def metadata_file() -> Path:
+    """Gets the path of metadata file.
+
+    Returns
+    -------
+    str
+        Storage type.
+    """
+    return config_file
+
+
 def storage_type() -> str:
     """Gets the storage type as a string.
 
@@ -253,14 +267,14 @@ def storage_type() -> str:
         raise RuntimeError("Bot basic config has not been loaded yet.") from e
 
 
-def storage_details() -> dict:
+def storage_details() -> Dict[str, str]:
     """Gets any details necessary for config drivers to load.
 
     These are set on setup.
 
     Returns
     -------
-    dict
+    Dict[str, str]
         Storage details.
     """
-    return basic_config.get("STORAGE_DETAILS", {})
+    return deepcopy(basic_config.get("STORAGE_DETAILS", {}))

redbot/core/errors.py

@@ -7,6 +7,18 @@ from .i18n import Translator
 
 _ = Translator(__name__, __file__)
 
+__all__ = (
+    "RedError",
+    "PackageAlreadyLoaded",
+    "CogLoadError",
+    "BankError",
+    "BalanceTooHigh",
+    "BankPruneError",
+    "ConfigError",
+    "StoredTypeError",
+    "CannotSetSubfield",
+)
+
 
 class RedError(Exception):
     """Base error class for Red-related errors."""

redbot/core/generic_casetypes.py

@@ -3,6 +3,26 @@ Contains generic mod action casetypes for use in Red and 3rd party cogs.
 These do not need to be registered to the modlog, as it is done for you.
 """
 
+__all__ = (
+    "ban",
+    "kick",
+    "hackban",
+    "tempban",
+    "softban",
+    "unban",
+    "voiceban",
+    "voiceunban",
+    "voicemute",
+    "channelmute",
+    "servermute",
+    "voiceunmute",
+    "channelunmute",
+    "serverunmute",
+    "voicekick",
+    "warning",
+    "all_generics",
+)
+
 ban = {"name": "ban", "default_setting": True, "image": "\N{HAMMER}", "case_str": "Ban"}
 
 kick = {"name": "kick", "default_setting": True, "image": "\N{WOMANS BOOTS}", "case_str": "Kick"}

redbot/core/i18n.py

@@ -20,15 +20,14 @@ if TYPE_CHECKING:
 
 __all__ = [
     "get_locale",
-    "set_locale",
-    "reload_locales",
-    "cog_i18n",
-    "Translator",
-    "get_babel_locale",
-    "get_babel_regional_format",
+    "get_regional_format",
     "get_locale_from_guild",
     "get_regional_format_from_guild",
     "set_contextual_locales_from_guild",
+    "Translator",
+    "get_babel_locale",
+    "get_babel_regional_format",
+    "cog_i18n",
 ]
 
 log = logging.getLogger("red.i18n")
@@ -48,6 +47,14 @@ _translators = []
 
 
 def get_locale() -> str:
+    """
+    Get locale in a current context.
+
+    Returns
+    -------
+    str
+        Current locale's language code with country code included, e.g. "en-US".
+    """
     return str(_current_locale.get())
 
 
@@ -63,6 +70,14 @@ def set_contextual_locale(locale: str) -> None:
 
 
 def get_regional_format() -> str:
+    """
+    Get regional format in a current context.
+
+    Returns
+    -------
+    str
+        Current regional format's language code with country code included, e.g. "en-US".
+    """
     if _current_regional_format.get() is None:
         return str(_current_locale.get())
     return str(_current_regional_format.get())
@@ -97,7 +112,7 @@ async def get_locale_from_guild(bot: Red, guild: Optional[discord.Guild]) -> str
     Returns
     -------
     str
-        Guild's locale string.
+        Guild locale's language code with country code included, e.g. "en-US".
     """
     return await bot._i18n_cache.get_locale(guild)
 
@@ -117,7 +132,7 @@ async def get_regional_format_from_guild(bot: Red, guild: Optional[discord.Guild
     Returns
     -------
     str
-        Guild's locale string.
+        Guild regional format's language code with country code included, e.g. "en-US".
     """
     return await bot._i18n_cache.get_regional_format(guild)