feat: implement onboarding

changelog/928.feature.rst

@@ -0,0 +1,3 @@
+Implement Onboarding.
+    - Add :class:`Onboarding`, :class:`OnboardingPrompt` and :class:`OnboardingPromptOption`.
+    - Add :meth:`Guild.fetch_onboarding`.

disnake/__init__.py

@@ -52,6 +52,7 @@
 from .mentions import *
 from .message import *
 from .object import *
+from .onboarding import *
 from .partial_emoji import *
 from .permissions import *
 from .player import *

disnake/enums.py

@@ -66,6 +66,7 @@
     "ThreadLayout",
     "Event",
     "ApplicationRoleConnectionMetadataType",
+    "OnboardingPromptType",
 )
 
 
@@ -1294,6 +1295,11 @@ class ApplicationRoleConnectionMetadataType(Enum):
     boolean_not_equal = 8
 
 
+class OnboardingPromptType(Enum):
+    multiple_choice = 0
+    dropdown = 1
+
+
 T = TypeVar("T")
 
 

disnake/guild.py

@@ -66,6 +66,7 @@
 from .iterators import AuditLogIterator, BanIterator, MemberIterator
 from .member import Member, VoiceState
 from .mixins import Hashable
+from .onboarding import Onboarding
 from .partial_emoji import PartialEmoji
 from .permissions import PermissionOverwrite
 from .role import Role
@@ -4632,6 +4633,26 @@ async def create_automod_rule(
         )
         return AutoModRule(data=data, guild=self)
 
+    async def fetch_onboarding(self) -> Onboarding:
+        """|coro|
+
+        Retrieves the guild onboarding data.
+
+        .. versionadded:: 2.9
+
+        Raises
+        ------
+        HTTPException
+            Retrieving the guild onboarding data failed.
+
+        Returns
+        -------
+        :class:`Onboarding`
+            The guild onboarding data.
+        """
+        data = await self._state.http.get_guild_onboarding(self.id)
+        return Onboarding(data=data, guild=self)
+
 
 PlaceholderID = NewType("PlaceholderID", int)
 

disnake/http.py

@@ -68,6 +68,7 @@
         invite,
         member,
         message,
+        onboarding,
         role,
         sticker,
         template,
@@ -2167,6 +2168,8 @@ def edit_guild_welcome_screen(
         r = Route("PATCH", "/guilds/{guild_id}/welcome-screen", guild_id=guild_id)
         return self.request(r, json=payload, reason=reason)
 
+    # Auto moderation
+
     def get_auto_moderation_rules(self, guild_id: Snowflake) -> Response[List[automod.AutoModRule]]:
         return self.request(
             Route("GET", "/guilds/{guild_id}/auto-moderation/rules", guild_id=guild_id)
@@ -2256,6 +2259,11 @@ def delete_auto_moderation_rule(
             reason=reason,
         )
 
+    # Guild Onboarding
+
+    def get_guild_onboarding(self, guild_id: Snowflake) -> Response[onboarding.Onboarding]:
+        return self.request(Route("GET", "/guilds/{guild_id}/onboarding", guild_id=guild_id))
+
     # Application commands (global)
 
     def get_global_commands(

disnake/onboarding.py

@@ -0,0 +1,201 @@
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, FrozenSet, List, Optional, Union
+
+from .enums import OnboardingPromptType, try_enum
+from .mixins import Hashable
+
+if TYPE_CHECKING:
+    from .emoji import Emoji, PartialEmoji
+    from .guild import Guild, GuildChannel
+    from .role import Role
+    from .types.onboarding import (
+        Onboarding as OnboardingPayload,
+        OnboardingPrompt as OnboardingPromptPayload,
+        OnboardingPromptOption as OnboardingPromptOptionPayload,
+    )
+
+__all__ = (
+    "Onboarding",
+    "OnboardingPrompt",
+    "OnboardingPromptOption",
+)
+
+
+class Onboarding:
+    """Represents a guild onboarding object.
+
+    .. versionadded:: 2.9
+
+    Attributes
+    ----------
+    guild: :class:`Guild`
+        The guild this onboarding is part of.
+    prompts: List[:class:`OnboardingPrompt`]
+        The prompts shown during onboarding and in community customization.
+    enabled: :class:`bool`
+        Whether onboarding is enabled.
+    default_channel_ids: FrozenSet[:class:`int`]
+        The IDs of the channels that will automatically be shown to new members.
+    """
+
+    __slots__ = (
+        "guild",
+        "prompts",
+        "enabled",
+        "default_channel_ids",
+    )
+
+    def __init__(self, *, guild: Guild, data: OnboardingPayload) -> None:
+        self.guild: Guild = guild
+        self._from_data(data)
+
+    def _from_data(self, data: OnboardingPayload) -> None:
+        self.prompts: List[OnboardingPrompt] = [
+            OnboardingPrompt(data=prompt, guild=self.guild) for prompt in data["prompts"]
+        ]
+        self.enabled: bool = data["enabled"]
+        self.default_channel_ids: FrozenSet[int] = (
+            frozenset(map(int, exempt_channels))
+            if (exempt_channels := data["default_channel_ids"])
+            else frozenset()
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"<Onboarding guild={self.guild!r} prompts={self.prompts!r} enabled={self.enabled!r}>"
+        )
+
+    @property
+    def default_channels(self) -> List[GuildChannel]:
+        """List[:class:`abc.GuildChannel`]: The list of channels that will be shown to new members by default."""
+        return list(filter(None, map(self.guild.get_channel, self.default_channel_ids)))
+
+
+class OnboardingPrompt(Hashable):
+    """Represents an onboarding prompt.
+
+    .. versionadded:: 2.9
+
+    Attributes
+    ----------
+    id: :class:`int`
+        The onboarding prompt's ID.
+    type: :class:`OnboardingPromptType`
+        The onboarding prompt's type.
+    options: List[:class:`OnboardingPromptOption`]
+        The onboarding prompt's options.
+    title: :class:`str`
+        The onboarding prompt's title.
+    single_select: :class:`bool`
+        Whether users are limited to selecting one option for the prompt.
+    required: :class:`bool`
+        Whether the prompt is required before a user completes the onboarding flow.
+    in_onboarding: :class:`bool`
+        Whether the prompt is present in the onboarding flow.
+        If ``False``, the prompt will only appear in community customization.
+    """
+
+    __slots__ = (
+        "guild",
+        "id",
+        "title",
+        "options",
+        "single_select",
+        "required",
+        "in_onboarding",
+        "type",
+    )
+
+    def __init__(self, *, guild: Guild, data: OnboardingPromptPayload) -> None:
+        self.guild = guild
+
+        self.id: int = int(data["id"])
+        self.title: str = data["title"]
+        self.options: List[OnboardingPromptOption] = [
+            OnboardingPromptOption(data=option, guild=guild) for option in data["options"]
+        ]
+        self.single_select: bool = data["single_select"]
+        self.required: bool = data["required"]
+        self.in_onboarding: bool = data["in_onboarding"]
+        self.type: OnboardingPromptType = try_enum(OnboardingPromptType, data["type"])
+
+    def __str__(self) -> str:
+        return self.title
+
+    def __repr__(self) -> str:
+        return (
+            f"<OnboardingPrompt id={self.id!r} title={self.title!r} options={self.options!r}"
+            f" single_select={self.single_select!r} required={self.required!r}"
+            f" in_onboarding={self.in_onboarding!r} type={self.type!r}>"
+        )
+
+
+class OnboardingPromptOption(Hashable):
+    """Represents an onboarding prompt option.
+
+    .. versionadded:: 2.9
+
+    Attributes
+    ----------
+    id: :class:`int`
+        The prompt option's ID.
+    emoji: Optional[Union[:class:`PartialEmoji`, :class:`Emoji`]]
+        The prompt option's emoji.
+    title: :class:`str`
+        The prompt option's title.
+    description: Optional[:class:`str`]
+        The prompt option's description.
+    role_ids: FrozenSet[:class:`int`]
+        The IDs of the roles that will be added to the user when they select this option.
+    channel_ids: FrozenSet[:class:`int`]
+        The IDs of the channels that will be shown to the user when they select this option.
+    """
+
+    __slots__ = ("id", "title", "description", "emoji", "guild", "role_ids", "channel_ids")
+
+    def __init__(self, *, guild: Guild, data: OnboardingPromptOptionPayload) -> None:
+        # NOTE: The ID may sometimes be a UNIX timestamp since
+        # Onboarding changes are saved locally until you send the API request (that's how it works in client)
+        # so the API needs the timestamp to know what ID it needs to create, should we just add a note about it
+        # or "try" to create the ID ourselves?
+        # I'm not sure if this also happens for OnboardingPrompt
+        self.guild: Guild = guild
+
+        self.id: int = int(data["id"])
+        self.title: str = data["title"]
+        self.description: Optional[str] = data["description"]
+        self.role_ids: FrozenSet[int] = (
+            frozenset(map(int, roles_ids)) if (roles_ids := data.get("role_ids")) else frozenset()
+        )
+        self.channel_ids: FrozenSet[int] = (
+            frozenset(map(int, channels_ids))
+            if (channels_ids := data.get("channel_ids"))
+            else frozenset()
+        )
+
+        self.emoji: Optional[Union[Emoji, PartialEmoji]]
+        if emoji_data := data.get("emoji"):
+            self.emoji = guild._state.get_reaction_emoji(emoji_data)
+        else:
+            self.emoji = None
+
+    def __str__(self) -> str:
+        return self.title
+
+    def __repr__(self) -> str:
+        return (
+            f"<OnboardingPromptOption id={self.id!r} title={self.title!r} "
+            f"description={self.description!r} emoji={self.emoji!r}>"
+        )
+
+    @property
+    def roles(self) -> List[Role]:
+        """List[:class:`Role`]: A list of roles that will be added to the user when they select this option."""
+        return list(filter(None, map(self.guild.get_role, self.role_ids)))
+
+    @property
+    def channels(self) -> List[GuildChannel]:
+        """List[:class:`abc.GuildChannel`]: A list of channels that the user will see when they select this option."""
+        return list(filter(None, map(self.guild.get_channel, self.channel_ids)))

disnake/partial_emoji.py

@@ -271,7 +271,7 @@ def _emoji_to_name_id(
     # utility method for unusual emoji model in forums
     @staticmethod
     def _emoji_from_name_id(
-        name: Optional[str], id: Optional[int], *, state: ConnectionState
+        name: Optional[str], id: Optional[int], animated: bool = False, *, state: ConnectionState
     ) -> Optional[Union[Emoji, PartialEmoji]]:
         if not (name or id):
             return None
@@ -286,6 +286,6 @@ def _emoji_from_name_id(
                 # This may change in a future API version, but for now we'll just have to accept it.
                 name=name or "",
                 id=id,
-                # `animated` is unknown but presumably we already got the (animated) emoji from the guild cache at this point
+                animated=animated,
             )
         return emoji

disnake/types/onboarding.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List, Literal, Optional, TypedDict
+
+from .emoji import Emoji
+from .snowflake import Snowflake, SnowflakeList
+
+OnboardingPromptType = Literal[0, 1]
+
+
+class OnboardingPromptOption(TypedDict):
+    id: Snowflake
+    title: str
+    description: Optional[str]
+    emoji: Emoji
+    role_ids: SnowflakeList
+    channel_ids: SnowflakeList
+
+
+class OnboardingPrompt(TypedDict):
+    id: Snowflake
+    title: str
+    options: List[OnboardingPromptOption]
+    single_select: bool
+    required: bool
+    in_onboarding: bool
+    type: OnboardingPromptType
+
+
+class Onboarding(TypedDict):
+    guild_id: Snowflake
+    prompts: List[OnboardingPrompt]
+    default_channel_ids: SnowflakeList
+    enabled: bool