feat: implement new role color styles (#1312)

Signed-off-by: Snipy7374 <[email protected]>
Co-authored-by: vi <[email protected]>

Author: Snipy7374

changelog/1311.feature.rst

@@ -0,0 +1 @@
+Add :meth:`Role.primary_colour`, :meth:`Role.secondary_colour`, :meth:`Role.tertiary_colour`, :meth:`Colour.holographic_style`, and aliases, as well as ``primary_colour``, ``secondary_colour``, ``tertiary_colour`` arguments, and aliases, to :meth:`Role.edit` and :meth:`Guild.create_role`.

disnake/colour.py

@@ -319,5 +319,18 @@ def dark_embed(cls) -> Self:
         """
         return cls(0x2B2D31)
 
+    @classmethod
+    def holographic_style(cls) -> Tuple[Self, Self, Self]:
+        """A factory method that returns a tuple of :class:`Colour` with values of
+        ``0xA9C9FF``, ``0xFFBBEC``, ``0xFFC3A0``. This matches the holographic colour style
+        for roles.
+
+        The first value represents the ``colour`` (``primary_color``), the second and the third
+        represents the ``secondary_colour`` and ``tertiary_colour`` respectively.
+
+        .. versionadded:: 2.11
+        """
+        return cls(0xA9C9FF), cls(0xFFBBEC), cls(0xFFC3A0)
+
 
 Color = Colour

disnake/guild.py

@@ -3751,6 +3751,12 @@ async def create_role(
         permissions: Permissions = MISSING,
         color: Union[Colour, int] = MISSING,
         colour: Union[Colour, int] = MISSING,
+        primary_colour: Union[Colour, int] = MISSING,
+        primary_color: Union[Colour, int] = MISSING,
+        secondary_colour: Optional[Union[Colour, int]] = None,
+        secondary_color: Optional[Union[Colour, int]] = None,
+        tertiary_colour: Optional[Union[Colour, int]] = None,
+        tertiary_color: Optional[Union[Colour, int]] = None,
         hoist: bool = MISSING,
         icon: AssetBytes = MISSING,
         emoji: str = MISSING,
@@ -3781,6 +3787,28 @@ async def create_role(
         colour: Union[:class:`Colour`, :class:`int`]
             The colour for the role. Defaults to :meth:`Colour.default`.
             This is aliased to ``color`` as well.
+
+            .. note::
+                This is equivalent to ``primary_colour``.
+        primary_colour: Union[:class:`Colour`, :class:`int`]
+            The primary_colour for the role. Defaults to :meth:`Colour.default`.
+            This is aliased to ``primary_color`` as well.
+
+            .. versionadded:: 2.11
+        secondary_colour: Optional[Union[:class:`Colour`, :class:`int`]]
+            The secondary_colour for the role. Defaults to ``None``.
+            This is aliased to ``secondary_color`` as well.
+
+            .. versionadded:: 2.11
+        tertiary_colour: Optional[Union[:class:`Colour`, :class:`int`]]
+            The tertiary_colour for the role. Defaults to ``None``.
+            This is aliased to ``tertiary_color`` as well.
+
+            .. note::
+                When passing this the only permitted values are the ones returned by
+                :meth:`Colour.holographic_style`, any other color value will get rejected.
+
+            .. versionadded:: 2.11
         hoist: :class:`bool`
             Whether the role should be shown separately in the member list.
             Defaults to ``False``.
@@ -3821,11 +3849,25 @@ async def create_role(
         else:
             fields["permissions"] = "0"
 
-        actual_colour = colour or color or Colour.default()
-        if isinstance(actual_colour, int):
-            fields["color"] = actual_colour
-        else:
-            fields["color"] = actual_colour.value
+        actual_primary_color = colour or color or primary_colour or primary_color
+        actual_secondary_color = secondary_colour or secondary_color
+        actual_tertiary_color = tertiary_colour or tertiary_color
+        if actual_primary_color is MISSING:
+            actual_primary_color = 0
+        elif isinstance(actual_primary_color, Colour):
+            actual_primary_color = actual_primary_color.value
+
+        if isinstance(actual_secondary_color, Colour):
+            actual_secondary_color = actual_secondary_color.value
+
+        if isinstance(actual_tertiary_color, Colour):
+            actual_tertiary_color = actual_tertiary_color.value
+
+        fields["colors"] = {
+            "primary_color": actual_primary_color,
+            "secondary_color": actual_secondary_color,
+            "tertiary_color": actual_tertiary_color,
+        }
 
         if hoist is not MISSING:
             fields["hoist"] = hoist
@@ -5454,9 +5496,9 @@ def add_role(
 
         actual_colour = colour or color or Colour.default()
         if isinstance(actual_colour, int):
-            data["color"] = actual_colour
+            data["color"] = actual_colour  # type: ignore
         else:
-            data["color"] = actual_colour.value
+            data["color"] = actual_colour.value  # type: ignore
 
         if hoist is not MISSING:
             data["hoist"] = hoist

disnake/http.py

@@ -1977,6 +1977,7 @@ def edit_role(
             "name",
             "permissions",
             "color",
+            "colors",
             "hoist",
             "mentionable",
             "icon",

disnake/role.py

@@ -208,7 +208,6 @@ class Role(Hashable):
         "id",
         "name",
         "_permissions",
-        "_colour",
         "position",
         "managed",
         "mentionable",
@@ -219,6 +218,9 @@ class Role(Hashable):
         "tags",
         "_flags",
         "_state",
+        "_primary_color",
+        "_secondary_color",
+        "_tertiary_color",
     )
 
     def __init__(self, *, guild: Guild, state: ConnectionState, data: RolePayload) -> None:
@@ -273,7 +275,10 @@ def _update(self, data: RolePayload) -> None:
         self.name: str = data["name"]
         self._permissions: int = int(data.get("permissions", 0))
         self.position: int = data.get("position", 0)
-        self._colour: int = data.get("color", 0)
+        colors = data["colors"]
+        self._primary_color: int = colors["primary_color"]
+        self._secondary_color: Optional[int] = colors["secondary_color"]
+        self._tertiary_color: Optional[int] = colors["tertiary_color"]
         self.hoist: bool = data.get("hoist", False)
         self._icon: Optional[str] = data.get("icon")
         self._emoji: Optional[str] = data.get("unicode_emoji")
@@ -370,13 +375,75 @@ def permissions(self) -> Permissions:
 
     @property
     def colour(self) -> Colour:
-        """:class:`Colour`: Returns the role colour. An alias exists under ``color``."""
-        return Colour(self._colour)
+        """:class:`Colour`: Returns the role colour. An alias exists under ``color``.
+
+        .. note::
+
+            This is equivalent to :meth:`primary_colour`.
+        """
+        return self.primary_colour
 
     @property
     def color(self) -> Colour:
-        """:class:`Colour`: Returns the role color. An alias exists under ``colour``."""
-        return self.colour
+        """:class:`Colour`: Returns the role color. An alias exists under ``colour``.
+
+        .. note::
+
+            This is equivalent to :meth:`primary_color`.
+        """
+        return self.primary_colour
+
+    @property
+    def primary_colour(self) -> Colour:
+        """:class:`Colour`: Returns the primary colour for the role. An alias exists under ``primary_color``.
+
+        .. versionadded:: 2.11
+        """
+        return Colour(self._primary_color)
+
+    @property
+    def primary_color(self) -> Colour:
+        """:class:`Colour`: Returns the primary color for the role. An alias exists under ``primary_colour``.
+
+        .. versionadded:: 2.11
+        """
+        return self.primary_colour
+
+    @property
+    def secondary_colour(self) -> Optional[Colour]:
+        """Optional[:class:`Colour`]: Returns the secondary colour for the role, if any. An alias exists under ``secondary_color``.
+
+        .. versionadded:: 2.11
+        """
+        if self._secondary_color:
+            return Colour(self._secondary_color)
+        return None
+
+    @property
+    def secondary_color(self) -> Optional[Colour]:
+        """Optional[:class:`Colour`]: Returns the secondary color for the role, if any. An alias exists under ``secondary_colour``.
+
+        .. versionadded:: 2.11
+        """
+        return self.secondary_colour
+
+    @property
+    def tertiary_colour(self) -> Optional[Colour]:
+        """Optional[:class:`Colour`]: Returns the tertiary colour for the role, if any. An alias exists under ``tertiary_color``.
+
+        .. versionadded:: 2.11
+        """
+        if self._tertiary_color:
+            return Colour(self._tertiary_color)
+        return None
+
+    @property
+    def tertiary_color(self) -> Optional[Colour]:
+        """Optional[:class:`Colour`]: Returns the tertiary color for the role, if any. An alias exists under ``tertiary_colour``.
+
+        .. versionadded:: 2.11
+        """
+        return self.tertiary_colour
 
     @property
     def icon(self) -> Optional[Asset]:
@@ -462,6 +529,12 @@ async def edit(
         permissions: Permissions = MISSING,
         colour: Union[Colour, int] = MISSING,
         color: Union[Colour, int] = MISSING,
+        primary_colour: Union[Colour, int] = MISSING,
+        primary_color: Union[Colour, int] = MISSING,
+        secondary_colour: Optional[Union[Colour, int]] = MISSING,
+        secondary_color: Optional[Union[Colour, int]] = MISSING,
+        tertiary_colour: Optional[Union[Colour, int]] = MISSING,
+        tertiary_color: Optional[Union[Colour, int]] = MISSING,
         hoist: bool = MISSING,
         icon: Optional[AssetBytes] = MISSING,
         emoji: Optional[str] = MISSING,
@@ -495,6 +568,25 @@ async def edit(
             The new permissions to change to.
         colour: Union[:class:`Colour`, :class:`int`]
             The new colour to change to. (aliased to ``color`` as well)
+
+            .. note::
+                This is equivalent to ``primary_colour``.
+        primary_colour: Union[:class:`Colour`, :class:`int`]
+            The new primary_colour to change to. (aliased to ``primary_color`` as well)
+
+            .. versionadded:: 2.11
+        secondary_colour: Optional[Union[:class:`Colour`, :class:`int`]]
+            The new secondary_colour to change to. (aliased to ``secondary_color`` as well)
+
+            .. versionadded:: 2.11
+        tertiary_colour: Optional[Union[:class:`Colour`, :class:`int`]]
+            The new tertiary_colour to change to. (aliased to ``tertiary_color`` as well)
+
+            .. note::
+                When passing this the only permitted values are the ones returned by
+                :meth:`Colour.holographic_style`, any other color value will get rejected.
+
+            .. versionadded:: 2.11
         hoist: :class:`bool`
             Indicates if the role should be shown separately in the member list.
         icon: Optional[|resource_type|]
@@ -536,14 +628,52 @@ async def edit(
             await self._move(position, reason=reason)
 
         payload: Dict[str, Any] = {}
+
+        colors: Dict[str, Any] = {
+            "primary_color": self._primary_color,
+            "secondary_color": self._secondary_color,
+            "tertiary_color": self._tertiary_color,
+        }
         if color is not MISSING:
-            colour = color
+            primary_colour = color
+        elif colour is not MISSING:
+            primary_colour = colour
+
+        if primary_color is not MISSING:
+            primary_colour = primary_color
+
+        if primary_colour is not MISSING:
+            if isinstance(primary_colour, int):
+                colors["primary_color"] = primary_colour
+            else:
+                colors["primary_color"] = primary_colour.value
+
+        if secondary_color is not MISSING:
+            secondary_colour = secondary_color
+
+        if secondary_colour is not MISSING:
+            if isinstance(secondary_colour, Colour):
+                colors["secondary_color"] = secondary_colour.value
+            else:
+                colors["secondary_color"] = secondary_colour
+
+        if tertiary_color is not MISSING:
+            tertiary_colour = tertiary_color
 
-        if colour is not MISSING:
-            if isinstance(colour, int):
-                payload["color"] = colour
+        if tertiary_colour is not MISSING:
+            if isinstance(tertiary_colour, Colour):
+                colors["tertiary_color"] = tertiary_colour.value
             else:
-                payload["color"] = colour.value
+                colors["tertiary_color"] = tertiary_colour
+
+        if any(
+            [
+                colors["primary_color"] != self._primary_color,
+                colors["secondary_color"] != self._secondary_color,
+                colors["tertiary_color"] != self._tertiary_color,
+            ]
+        ):
+            payload["colors"] = colors
 
         if name is not MISSING:
             payload["name"] = name

disnake/types/role.py

@@ -13,6 +13,7 @@ class Role(TypedDict):
     id: Snowflake
     name: str
     color: int
+    colors: RoleColors
     hoist: bool
     icon: NotRequired[Optional[str]]
     unicode_emoji: NotRequired[Optional[str]]
@@ -33,10 +34,16 @@ class RoleTags(TypedDict, total=False):
     available_for_purchase: None
 
 
+class RoleColors(TypedDict):
+    primary_color: int
+    secondary_color: Optional[int]
+    tertiary_color: Optional[int]
+
+
 class CreateRole(TypedDict, total=False):
     name: str
     permissions: str
-    color: int
+    colors: RoleColors
     hoist: bool
     icon: Optional[str]
     unicode_emoji: Optional[str]