More intent related documentation

discord/flags.py

@@ -103,7 +103,7 @@ class BaseFlags:
         for name, value in self.__class__.__dict__.items():
             if isinstance(value, alias_flag_value):
                 continue
-            
+
             if isinstance(value, flag_value):
                 yield (name, self._has_flag(value.flag))
 
@@ -339,7 +339,7 @@ class PublicUserFlags(BaseFlags):
     def verified_bot_developer(self):
         """:class:`bool`: Returns ``True`` if the user is an Early Verified Bot Developer."""
         return UserFlags.verified_bot_developer.value
-    
+
     @alias_flag_value
     def early_verified_bot_developer(self):
         """:class:`bool`: An alias for :attr:`verified_bot_developer`.
@@ -785,8 +785,8 @@ class MemberCacheFlags(BaseFlags):
     """Controls the library's cache policy when it comes to members.
 
     This allows for finer grained control over what members are cached.
-    For more information, check :attr:`Client.member_cache_flags`. Note
-    that the bot's own member is always cached.
+    Note that the bot's own member is always cached. This class is passed
+    to the ``member_cache_flags`` parameter in :class:`Client`.
 
     Due to a quirk in how Discord works, in order to ensure proper cleanup
     of cache resources it is recommended to have :attr:`Intents.members`

docs/intents.rst

@@ -84,6 +84,8 @@ Member Intent
 - Whether you want to request the guild member list through :meth:`Guild.chunk` or :meth:`Guild.fetch_members`.
 - Whether you want high accuracy member cache under :attr:`Guild.members`.
 
+.. _intents_member_cache:
+
 Member Cache
 -------------
 
@@ -100,3 +102,64 @@ It should be noted that certain things do not need a member cache since Discord
 - The reaction removal events do not have the member information. This is a Discord limitation.
 
 Other events that take a :class:`Member` will require the use of the member cache. If absolute accuracy over the member cache is desirable, then it is advisable to have the :attr:`Intents.members` intent enabled.
+
+.. _retrieving_members:
+
+Retrieving Members
+--------------------
+
+If cache is disabled or you disable chunking guilds at startup, we might still need a way to load members. The library offers a few ways to do this:
+
+- :meth:`Guild.query_members`
+    - Used to query members by a prefix matching nickname or username.
+    - This can also be used to query members by their user ID.
+    - This uses the gateway and not the HTTP.
+- :meth:`Guild.chunk`
+    - This can be used to fetch the entire member list through the gateway.
+- :meth:`Guild.fetch_member`
+    - Used to fetch a member by ID through the HTTP API.
+- :meth:`Guild.fetch_members`
+    - used to fetch a large number of members through the HTTP API.
+
+It should be noted that the gateway has a strict rate limit of 120 requests per 60 seconds.
+
+Troubleshooting
+------------------
+
+Some common issues relating to the mandatory intent change.
+
+Where'd my members go?
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Due to an :ref:`API change <intents_member_cache>` Discord is now forcing developers who want member caching to explicitly opt-in to it. This is a Discord mandated change and there is no way to bypass it. In order to get members back you have to explicitly enable the :ref:`members privileged intent <privileged_intents>` and change the :attr:`Intents.members` attribute to true.
+
+For example:
+
+.. code-block:: python3
+
+    import discord
+    intents = discord.Intents()
+    intents.members = True
+
+    # Somewhere else:
+    # client = discord.Client(intents=intents)
+    # or
+    # from discord.ext import commands
+    # bot = commands.Bot(intents=intents)
+
+Why does ``on_ready`` take so long to fire?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As part of the API change regarding intents, Discord also changed how members are loaded in the beginning. Originally the library could request 75 guilds at once and only request members from guilds that have the :attr:`Guild.large` attribute set to ``True``. With the new intent changes, Discord mandates that we can only send 1 guild per request. This causes a 75x slowdown which is further compounded by the fact that *all* guilds, not just large guilds are being requested.
+
+There are a few solutions to fix this.
+
+The first solution is to request the privileged presences intent along with the privileged members intent and enable both of them. This allows the initial member list to contain online members just like the old gateway. Note that we're still limited to 1 guild per request but the number of guilds we request is significantly reduced.
+
+The second solution is to disable member chunking by setting ``chunk_guilds_at_startup`` to ``False`` when constructing a client. Then, when chunking for a guild is necessary you can use the various techniques to :ref:`retrieve members <retrieving_members>`.
+
+To illustrate the slowdown caused the API change, take a bot who is in 840 guilds and 95 of these guilds are "large" (over 250 members).
+
+Under the original system this would result in 2 requests to fetch the member list (75 guilds, 20 guilds) roughly taking 60 seconds. With :attr:`Intents.members` but not :attr:`Intents.presences` this requires 840 requests, with a rate limit of 120 requests per 60 seconds means that due to waiting for the rate limit it totals to around 7 minutes of waiting for the rate limit to fetch all the members. With both :attr:`Intents.members` and :attr:`Intents.presences` we mostly get the old behaviour so we're only required to request for the 95 guilds that are large, this is slightly less than our rate limit so it's close to the original timing to fetch the member list.
+
+Unfortunately due to this change being required from Discord there is nothing that the library can do to mitigate this.