refactor: ♻️ Various QOL changes to the Colour class

CHANGELOG.md

@@ -21,6 +21,9 @@ These changes are available on the `master` branch, but have not yet been releas
 
 ### Deprecated
 
+- Deprecated `Colour.dark_theme()` and `Colour.embed_background()`.
+  ([#3043](https://github.com/Pycord-Development/pycord/pull/3043))
+
 ### Removed
 
 ## [2.7.0] - 2025-12-24

discord/colour.py

@@ -27,18 +27,18 @@
 
 import colorsys
 import random
-from typing import Any, TypeVar
+from typing import Any
+
+from typing_extensions import Self, deprecated, override
 
 __all__ = (
     "Colour",
     "Color",
 )
 
-CT = TypeVar("CT", bound="Colour")
-
 
 class Colour:
-    """Represents a Discord role colour. This class is similar
+    """Represents a Colour. This class is similar
     to a (red, green, blue) :class:`tuple`.
 
     There is an alias for this called Color.
@@ -84,18 +84,22 @@ def __init__(self, value: int):
     def _get_byte(self, byte: int) -> int:
         return (self.value >> (8 * byte)) & 0xFF
 
+    @override
     def __eq__(self, other: Any) -> bool:
         return isinstance(other, Colour) and self.value == other.value
 
+    @override
     def __str__(self) -> str:
         return f"#{self.value:0>6x}"
 
     def __int__(self) -> int:
         return self.value
 
+    @override
     def __repr__(self) -> str:
         return f"<Colour value={self.value}>"
 
+    @override
     def __hash__(self) -> int:
         return hash(self.value)
 
@@ -119,27 +123,27 @@ def to_rgb(self) -> tuple[int, int, int]:
         return self.r, self.g, self.b
 
     @classmethod
-    def from_rgb(cls: type[CT], r: int, g: int, b: int) -> CT:
+    def from_rgb(cls: type[Self], r: int, g: int, b: int) -> Self:
         """Constructs a :class:`Colour` from an RGB tuple."""
         return cls((r << 16) + (g << 8) + b)
 
     @classmethod
-    def from_hsv(cls: type[CT], h: float, s: float, v: float) -> CT:
+    def from_hsv(cls: type[Self], h: float, s: float, v: float) -> Self:
         """Constructs a :class:`Colour` from an HSV tuple."""
         rgb = colorsys.hsv_to_rgb(h, s, v)
         return cls.from_rgb(*(int(x * 255) for x in rgb))
 
     @classmethod
-    def default(cls: type[CT]) -> CT:
+    def default(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0``."""
         return cls(0)
 
     @classmethod
     def random(
-        cls: type[CT],
+        cls: type[Self],
         *,
         seed: int | str | float | bytes | bytearray | None = None,
-    ) -> CT:
+    ) -> Self:
         """A factory method that returns a :class:`Colour` with a random hue.
 
         .. note::
@@ -160,146 +164,149 @@ def random(
         return cls.from_hsv(rand.random(), 1, 1)
 
     @classmethod
-    def teal(cls: type[CT]) -> CT:
+    def teal(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x1abc9c``."""
         return cls(0x1ABC9C)
 
     @classmethod
-    def dark_teal(cls: type[CT]) -> CT:
+    def dark_teal(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x11806a``."""
         return cls(0x11806A)
 
     @classmethod
-    def brand_green(cls: type[CT]) -> CT:
+    def brand_green(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x57F287``.
 
         .. versionadded:: 2.0
         """
         return cls(0x57F287)
 
     @classmethod
-    def green(cls: type[CT]) -> CT:
+    def green(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x2ecc71``."""
         return cls(0x2ECC71)
 
     @classmethod
-    def dark_green(cls: type[CT]) -> CT:
+    def dark_green(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x1f8b4c``."""
         return cls(0x1F8B4C)
 
     @classmethod
-    def blue(cls: type[CT]) -> CT:
+    def blue(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x3498db``."""
         return cls(0x3498DB)
 
     @classmethod
-    def dark_blue(cls: type[CT]) -> CT:
+    def dark_blue(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x206694``."""
         return cls(0x206694)
 
     @classmethod
-    def purple(cls: type[CT]) -> CT:
+    def purple(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x9b59b6``."""
         return cls(0x9B59B6)
 
     @classmethod
-    def dark_purple(cls: type[CT]) -> CT:
+    def dark_purple(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x71368a``."""
         return cls(0x71368A)
 
     @classmethod
-    def magenta(cls: type[CT]) -> CT:
+    def magenta(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0xe91e63``."""
         return cls(0xE91E63)
 
     @classmethod
-    def dark_magenta(cls: type[CT]) -> CT:
+    def dark_magenta(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0xad1457``."""
         return cls(0xAD1457)
 
     @classmethod
-    def gold(cls: type[CT]) -> CT:
+    def gold(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0xf1c40f``."""
         return cls(0xF1C40F)
 
     @classmethod
-    def dark_gold(cls: type[CT]) -> CT:
+    def dark_gold(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0xc27c0e``."""
         return cls(0xC27C0E)
 
     @classmethod
-    def orange(cls: type[CT]) -> CT:
+    def orange(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0xe67e22``."""
         return cls(0xE67E22)
 
     @classmethod
-    def dark_orange(cls: type[CT]) -> CT:
+    def dark_orange(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0xa84300``."""
         return cls(0xA84300)
 
     @classmethod
-    def brand_red(cls: type[CT]) -> CT:
+    def brand_red(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0xED4245``.
 
         .. versionadded:: 2.0
         """
         return cls(0xED4245)
 
     @classmethod
-    def red(cls: type[CT]) -> CT:
+    def red(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0xe74c3c``."""
         return cls(0xE74C3C)
 
     @classmethod
-    def dark_red(cls: type[CT]) -> CT:
+    def dark_red(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x992d22``."""
         return cls(0x992D22)
 
     @classmethod
-    def lighter_grey(cls: type[CT]) -> CT:
+    def lighter_grey(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x95a5a6``."""
         return cls(0x95A5A6)
 
     lighter_gray = lighter_grey
 
     @classmethod
-    def dark_grey(cls: type[CT]) -> CT:
+    def dark_grey(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x607d8b``."""
         return cls(0x607D8B)
 
     dark_gray = dark_grey
 
     @classmethod
-    def light_grey(cls: type[CT]) -> CT:
+    def light_grey(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x979c9f``."""
         return cls(0x979C9F)
 
     light_gray = light_grey
 
     @classmethod
-    def darker_grey(cls: type[CT]) -> CT:
+    def darker_grey(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x546e7a``."""
         return cls(0x546E7A)
 
     darker_gray = darker_grey
 
     @classmethod
-    def og_blurple(cls: type[CT]) -> CT:
+    def og_blurple(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x7289da``."""
         return cls(0x7289DA)
 
     @classmethod
-    def blurple(cls: type[CT]) -> CT:
+    def blurple(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x5865F2``."""
         return cls(0x5865F2)
 
     @classmethod
-    def greyple(cls: type[CT]) -> CT:
+    def greyple(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x99aab5``."""
         return cls(0x99AAB5)
 
     @classmethod
-    def dark_theme(cls: type[CT]) -> CT:
+    @deprecated(
+        "Colour.dark_theme is deprecated since version 2.7.1 and will be removed in version 3.0. This is not relevant anymore since Discord provides the custom themes feature."
+    )
+    def dark_theme(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0x36393F``.
         This will appear transparent on Discord's dark theme.
 
@@ -308,31 +315,34 @@ def dark_theme(cls: type[CT]) -> CT:
         return cls(0x36393F)
 
     @classmethod
-    def fuchsia(cls: type[CT]) -> CT:
+    def fuchsia(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0xEB459E``.
 
         .. versionadded:: 2.0
         """
         return cls(0xEB459E)
 
     @classmethod
-    def yellow(cls: type[CT]) -> CT:
+    def yellow(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0xFEE75C``.
 
         .. versionadded:: 2.0
         """
         return cls(0xFEE75C)
 
     @classmethod
-    def nitro_pink(cls: type[CT]) -> CT:
+    def nitro_pink(cls: type[Self]) -> Self:
         """A factory method that returns a :class:`Colour` with a value of ``0xf47fff``.
 
         .. versionadded:: 2.0
         """
         return cls(0xF47FFF)
 
     @classmethod
-    def embed_background(cls: type[CT], theme: str = "dark") -> CT:
+    @deprecated(
+        "Colour.embed_background is deprecated since version 2.7.1 and will be removed in version 3.0. This is not relevant anymore since Discord provides the custom themes feature."
+    )
+    def embed_background(cls: type[Self], theme: str = "dark") -> Self:
         """A factory method that returns a :class:`Colour` corresponding to the
         embed colours on discord clients, with a value of: