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

.github/labeler.yml

@@ -156,8 +156,8 @@
 "Category: Core - API - Config":
   # Source
   - any:
-      - redbot/core/drivers/**/*
+      - redbot/core/_drivers/**/*
-      - "!redbot/core/drivers/**/locales/*"
+      - "!redbot/core/_drivers/**/locales/*"
   - redbot/core/config.py
   # Docs
   - docs/framework_config.rst
@@ -167,16 +167,13 @@
   # Source
   - redbot/__init__.py
   - redbot/core/__init__.py
-  - redbot/core/cog_manager.py  # TODO: privatize cog manager module
   - redbot/core/data_manager.py
   - redbot/core/errors.py
   - redbot/core/tree.py
   # Docs
-  - docs/framework_cogmanager.rst  # TODO: privatize cog manager module
   - docs/framework_datamanager.rst
   - docs/framework_tree.rst
   # Tests
-  - redbot/pytest/cog_manager.py  # TODO: privatize cog manager module
   - redbot/pytest/data_manager.py
   - tests/core/test_cog_manager.py
   - tests/core/test_data_manager.py
@@ -207,8 +204,8 @@
 "Category: Core - Command-line Interfaces":
   - redbot/__main__.py
   - redbot/logging.py
+  - redbot/core/_cli.py
   - redbot/core/_debuginfo.py
-  - redbot/core/cli.py
   - redbot/setup.py
 "Category: Core - Help":
   - redbot/core/commands/help.py
@@ -227,18 +224,20 @@
   - docs/framework_modlog.rst
 "Category: Core - Other Internals":
   # Source
+  - redbot/core/_cog_manager.py
+  - redbot/core/_events.py
+  - redbot/core/_global_checks.py
+  - redbot/core/_settings_caches.py
   - redbot/core/_sharedlibdeprecation.py
-  - redbot/core/events.py
-  - redbot/core/global_checks.py
-  - redbot/core/settings_caches.py
   - redbot/core/utils/_internal_utils.py
   # Tests
   - redbot/pytest/__init__.py
+  - redbot/pytest/cog_manager.py
   - redbot/pytest/core.py
   - tests/core/test_installation.py
 "Category: Core - RPC/ZMQ":
   # Source
-  - redbot/core/rpc.py
+  - redbot/core/_rpc.py
   # Docs
   - docs/framework_rpc.rst
   # Tests
@@ -304,9 +303,6 @@
   - docs/_templates/**/*
   # empty file
   - redbot/cogs/__init__.py
-  # can't go more meta than that :)
-  # TODO: remove this useless file
-  - redbot/meta.py
   # py.typed file
   - redbot/py.typed
   # requirements files

MANIFEST.in

@@ -21,7 +21,7 @@ recursive-include redbot *.export
 recursive-include redbot py.typed
 
 # include *.sql files from postgres driver
-recursive-include redbot/core/drivers/postgres *.sql
+recursive-include redbot/core/_drivers/postgres *.sql
 
 # include tests
 graft tests

docs/framework_cogmanager.rst

@@ -1,8 +0,0 @@
-.. cog manager docs
-
-===========
-Cog Manager
-===========
-
-.. automodule:: redbot.core.cog_manager
-    :members:

docs/framework_config.rst

@@ -540,30 +540,14 @@ Value
     :members:
     :special-members: __call__
 
+IdentifierData
+^^^^^^^^^^^^^^
 
-****************
+.. autoclass:: IdentifierData
-Driver Reference
-****************
-
-.. autofunction:: redbot.core.drivers.get_driver
-
-.. autoclass:: redbot.core.drivers.BackendType
     :members:
 
-.. autoclass:: redbot.core.drivers.ConfigCategory
+ConfigCategory
-    :members:
+^^^^^^^^^^^^^^
 
-Base Driver
+.. autoclass:: ConfigCategory
-^^^^^^^^^^^
-.. autoclass:: redbot.core.drivers.BaseDriver
-    :members:
-
-JSON Driver
-^^^^^^^^^^^
-.. autoclass:: redbot.core.drivers.JsonDriver
-    :members:
-
-Postgres Driver
-^^^^^^^^^^^^^^^
-.. autoclass:: redbot.core.drivers.PostgresDriver
     :members:

docs/index.rst

@@ -69,7 +69,6 @@ Welcome to Red - Discord Bot's documentation!
     framework_bank
     framework_bot
     framework_checks
-    framework_cogmanager
     framework_commands
     framework_config
     framework_datamanager

docs/version_guarantees.rst

@@ -87,8 +87,17 @@ Ubuntu 22.10                       x86-64, aarch64           2023-07-31 (`End of
 Developer Guarantees
 ====================
 
-Anything in the ``redbot.core`` module or any of its submodules 
+Any name (function, class, attribute) listed in the ``__all__`` attribute of
-which is not private (even if not documented) should not break without notice.
+the ``redbot`` module (excluding its submodules), ``redbot.core`` package,
+or any of its public submodules (modules that do not start with "_")
+is considered a public API and should not break without notice.
+
+Methods of public classes are considered public if they do not start with "_"
+or are dunder methods (e.g. ``method()`` and ``__getattr__()`` are public but ``_method()`` isn't).
+
+Any other name (function, class, attribute) in the ``redbot`` package is considered private,
+even if it doesn't start with "_".
+Lack of ``__all__`` in the module means that all of its names are considered private APIs.
 
 Anything in the ``redbot.cogs`` and ``redbot.vendored`` modules or any of their submodules is specifically
 excluded from being guaranteed.
@@ -100,6 +109,9 @@ This allows us to add certain optional features non-breakingly without a name co
 
 Any RPC method exposed by Red may break without notice.
 
+Any exclusion from these guarantees should be noted in the documentation of
+the affected attribute, function, class, or method.
+
 If you would like something in here to be guaranteed,
 open an issue making a case for it to be moved.
 

redbot/__init__.py

@@ -13,16 +13,13 @@ from typing import (
     Union as _Union,
 )
 
-
+__all__ = (
-MIN_PYTHON_VERSION = (3, 8, 1)
-
-__all__ = [
-    "MIN_PYTHON_VERSION",
     "__version__",
     "version_info",
     "VersionInfo",
-    "_update_event_loop_policy",
+)
-]
+
+MIN_PYTHON_VERSION = (3, 8, 1)
 if _sys.version_info < MIN_PYTHON_VERSION:
     print(
         f"Python {'.'.join(map(str, MIN_PYTHON_VERSION))} is required to run Red, but you have "

redbot/__main__.py

@@ -25,9 +25,9 @@ import rich
 import redbot.logging
 from redbot import __version__
 from redbot.core.bot import Red, ExitCodes, _NoOwnerSet
-from redbot.core.cli import interactive_config, confirm, parse_cli_flags
+from redbot.core._cli import interactive_config, confirm, parse_cli_flags
 from redbot.setup import get_data_dir, get_name, save_config
-from redbot.core import data_manager, drivers
+from redbot.core import data_manager, _drivers
 from redbot.core._debuginfo import DebugInfo
 from redbot.core._sharedlibdeprecation import SharedLibImportWarner
 
@@ -281,7 +281,7 @@ def early_exit_runner(
 
         data_manager.load_basic_configuration(cli_flags.instance_name)
         red = Red(cli_flags=cli_flags, description="Red V3", dm_help=None)
-        driver_cls = drivers.get_driver_class()
+        driver_cls = _drivers.get_driver_class()
         loop.run_until_complete(driver_cls.initialize(**data_manager.storage_details()))
         loop.run_until_complete(func(red, cli_flags))
         loop.run_until_complete(driver_cls.teardown())
@@ -307,7 +307,7 @@ async def run_bot(red: Red, cli_flags: Namespace) -> None:
     need additional handling in this function.
     """
 
-    driver_cls = drivers.get_driver_class()
+    driver_cls = _drivers.get_driver_class()
 
     await driver_cls.initialize(**data_manager.storage_details())
 

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",
+    "cost",
-    "is_owner_if_bank_global",
+)
-]
 
 _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 . import Config, i18n, app_commands, commands, errors, _drivers, modlog, bank
-from .cli import ExitCodes
+from ._cli import ExitCodes
-from .cog_manager import CogManager, CogManagerUI
+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 ._events import init_events
-from .global_checks import init_global_checks
+from ._global_checks import init_global_checks
-from .settings_caches import (
+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()