feat: Guild Builder

discord/__init__.py

@@ -45,6 +45,7 @@
 from .file import *
 from .flags import *
 from .guild import *
+from .guild_builder import *
 from .http import *
 from .integrations import *
 from .interactions import *

discord/client.py

@@ -42,16 +42,23 @@
 from .backoff import ExponentialBackoff
 from .channel import PartialMessageable, _threaded_channel_factory
 from .emoji import AppEmoji, GuildEmoji
-from .enums import ChannelType, Status
+from .enums import (
+    ChannelType,
+    ContentFilter,
+    NotificationLevel,
+    Status,
+    VerificationLevel,
+)
 from .errors import *
 from .flags import ApplicationFlags, Intents
 from .gateway import *
 from .guild import Guild
+from .guild_builder import GuildBuilder
 from .http import HTTPClient
 from .invite import Invite
 from .iterators import EntitlementIterator, GuildIterator
 from .mentions import AllowedMentions
-from .monetization import SKU, Entitlement
+from .monetization import SKU
 from .object import Object
 from .stage_instance import StageInstance
 from .state import ConnectionState
@@ -1597,15 +1604,21 @@ async def create_guild(
         self,
         *,
         name: str,
-        icon: bytes = MISSING,
+        icon: bytes | None = MISSING,
         code: str = MISSING,
+        verification_level: VerificationLevel = MISSING,
+        content_filter: ContentFilter = MISSING,
+        notification_level: NotificationLevel = MISSING,
+        afk_timeout: int = MISSING,
     ) -> Guild:
         """|coro|
 
         Creates a :class:`.Guild`.
 
         Bot accounts in more than 10 guilds are not allowed to create guilds.
 
+        Also see :meth:`.Client.build_guild`.
+
         Parameters
         ----------
         name: :class:`str`
@@ -1617,30 +1630,108 @@ async def create_guild(
             The code for a template to create the guild with.
 
             .. versionadded:: 1.4
+        verification_level: :class:`VerificationLevel`
+            The verification level.
+
+            .. versionadded:: 2.7
+        content_filter: :class:`ContentFilter`
+            The explicit content filter level.
+
+            .. versionadded:: 2.7
+        notification_level: :class:`NotificationLevel`
+            The default message notification level.
+
+            .. versionadded:: 2.7
+        afk_timeout: :class:`int`
+            The afk timeout in seconds.
+
+            .. versionadded:: 2.7
 
         Returns
         -------
         :class:`.Guild`
             The guild created. This is not the same guild that is
             added to cache.
-
-        Raises
-        ------
-        :exc:`HTTPException`
-            Guild creation failed.
-        :exc:`InvalidArgument`
-            Invalid icon image format given. Must be PNG or JPG.
         """
-        if icon is not MISSING:
-            icon_base64 = utils._bytes_to_base64_data(icon)
-        else:
-            icon_base64 = None
+        if code is MISSING:
+            code = None  # type: ignore
 
-        if code:
-            data = await self.http.create_from_template(code, name, icon_base64)
-        else:
-            data = await self.http.create_guild(name, icon_base64)
-        return Guild(data=data, state=self._connection)
+        metadata = {}
+
+        if verification_level is not MISSING:
+            metadata["verification_level"] = verification_level.value
+        if content_filter is not MISSING:
+            metadata["explicit_content_filter"] = content_filter.value
+        if notification_level is not MISSING:
+            metadata["default_message_notifications"] = notification_level.value
+        if afk_timeout is not MISSING:
+            metadata["afk_timeout"] = afk_timeout
+
+        # TODO: remove support of passing ``None`` to ``icon``.
+        if icon is None:
+            icon = MISSING
+
+        builder = GuildBuilder(
+            state=self._connection, name=name, icon=icon, code=code, metadata=metadata  # type: ignore
+        )
+        return await builder
+
+    def build_guild(
+        self,
+        *,
+        name: str,
+        icon: bytes = MISSING,
+        verification_level: VerificationLevel = MISSING,
+        content_filter: ContentFilter = MISSING,
+        notification_level: NotificationLevel = MISSING,
+        afk_timeout: int = MISSING,
+    ) -> GuildBuilder:
+        """Creates a :class:`.GuildBuilder` object to create a guild.
+
+        Also see :meth:`.Client.create_guild`.
+
+        .. versionadded:: 2.7
+
+        Parameters
+        ----------
+        name: :class:`str`
+            The guild name.
+        icon: :class:`bytes`
+            The :term:`py:bytes-like object` representing the icon. See :meth:`.ClientUser.edit`
+            for more details on what is expected.
+        verification_level: :class:`VerificationLevel`
+            The verification level.
+        content_filter: :class:`ContentFilter`
+            The explicit content filter level.
+        notification_level: :class:`NotificationLevel`
+            The defualt message notification level.
+        afk_timeout: :class:`int`
+            The afk timeout in seconds.
+
+        Returns
+        -------
+        :class:`GuildBuilder`
+            The guild builder to create the new guild.
+        """
+
+        metadata = {}
+
+        if verification_level is not MISSING:
+            metadata["verification_level"] = verification_level.value
+        if content_filter is not MISSING:
+            metadata["explicit_content_filter"] = content_filter.value
+        if notification_level is not MISSING:
+            metadata["default_message_notifications"] = notification_level.value
+        if afk_timeout is not MISSING:
+            metadata["afk_timeout"] = afk_timeout
+
+        return GuildBuilder(
+            state=self._connection,
+            name=name,
+            icon=icon,
+            code=None,
+            metadata=metadata,
+        )
 
     async def fetch_stage_instance(self, channel_id: int, /) -> StageInstance:
         """|coro|