allowed_by_whitelist_blacklist() - add guild param, deprecate guild_id (#4914)

* allowed_by_whitelist_blacklist() - add guild param, deprecate guild_id

* Add clarification to description of `guild`, `guild_id`, and `role_ids`

* style :|

* Update redbot/core/bot.py

Co-authored-by: TrustyJAID <TrustyJAID@gmail.com>

Co-authored-by: TrustyJAID <TrustyJAID@gmail.com>

redbot/core/bot.py

@@ -50,7 +50,7 @@ from .settings_caches import (
 )
 from .rpc import RPCMixin
 from .utils import common_filters, AsyncIter
-from .utils._internal_utils import send_to_owners_with_prefix_replaced
+from .utils._internal_utils import deprecated_removed, send_to_owners_with_prefix_replaced
 
 CUSTOM_GROUPS = "CUSTOM_GROUPS"
 COMMAND_SCOPE = "COMMAND"
@@ -526,6 +526,7 @@ class RedBase(
         who: Optional[Union[discord.Member, discord.User]] = None,
         *,
         who_id: Optional[int] = None,
+        guild: Optional[discord.Guild] = None,
         guild_id: Optional[int] = None,
         role_ids: Optional[List[int]] = None,
     ) -> bool:
@@ -554,12 +555,24 @@ class RedBase(
         who_id : Optional[int]
             The id of the user or member to check
             If not providing a value for ``who``, this is a required parameter.
-        guild_id : Optional[int]
+        guild : Optional[discord.Guild]
             When used in conjunction with a provided value for ``who_id``, checks
             the lists for the corresponding guild as well.
+            This is ignored when ``who`` is passed.
+        guild_id : Optional[int]
+            When used in conjunction with a provided value for ``who_id``, checks
+            the lists for the corresponding guild as well. This should not be used
+            as it has unfixable bug that can cause it to raise an exception when
+            the guild with the given ID couldn't have been found.
+            This is ignored when ``who`` is passed.
+
+            .. deprecated-removed:: 3.4.8 30
+                Use ``guild`` parameter instead.
+
         role_ids : Optional[List[int]]
             When used with both ``who_id`` and ``guild_id``, checks the role ids provided.
             This is required for accurate checking of members in a guild if providing ids.
+            This is ignored when ``who`` is passed.
 
         Raises
         ------
@@ -575,7 +588,6 @@ class RedBase(
         # All config calls are delayed until needed in this section
         # All changes should be made keeping in mind that this is also used as a global check
 
-        guild = None
         mocked = False  # used for an accurate delayed role id expansion later.
         if not who:
             if not who_id:
@@ -583,7 +595,17 @@ class RedBase(
             mocked = True
             who = discord.Object(id=who_id)
             if guild_id:
-                guild = discord.Object(id=guild_id)
+                deprecated_removed(
+                    "`guild_id` parameter",
+                    "3.4.8",
+                    30,
+                    "Use `guild` parameter instead.",
+                    stacklevel=2,
+                )
+                if guild:
+                    raise ValueError(
+                        "`guild_id` should not be passed when `guild` is already passed."
+                    )
         else:
             guild = getattr(who, "guild", None)
 
@@ -600,6 +622,15 @@ class RedBase(
             if who.id in global_blacklist:
                 return False
 
+        if mocked and guild_id:
+            guild = self.get_guild(guild_id)
+            if guild is None:
+                # this is an AttributeError due to backwards-compatibility concerns
+                raise AttributeError(
+                    "Couldn't get the guild with the given ID. `guild` parameter needs to be used"
+                    " over the deprecated `guild_id` to resolve this."
+                )
+
         if guild:
             if guild.owner_id == who.id:
                 return True