Merge pull request #3456 from ToniDevStuff/add-Color.from_hex

add Color.from_hex

Author: ankith26

buildconfig/stubs/pygame/color.pyi

@@ -78,6 +78,8 @@ class Color(Collection[int]):
     @overload
     @classmethod
     def from_normalized(cls, r: float, g: float, b: float, a: float, /) -> Color: ...
+    @classmethod
+    def from_hex(cls, hex: str, /) -> Color: ...
     def normalize(self) -> tuple[float, float, float, float]: ...
     def correct_gamma(self, gamma: float, /) -> Color: ...
     @deprecated("since 2.1.3. Use unpacking instead")

docs/reST/ref/color.rst

@@ -292,6 +292,18 @@
 
       .. ## Color.from_normalized ##
 
+   .. classmethod:: from_hex
+
+      | :sl:`Returns a Color object from a Hexadecimal representation`
+      | :sg:`from_hex(hex, /) -> Color`
+
+      Creates a Color object from the given Hexadecimal components. Refer to :attr:`Color.hex`
+      for more information.
+
+      .. versionadded:: 2.5.6
+
+      .. ## Color.from_hex ##
+
    .. method:: normalize
 
       | :sl:`Returns the normalized RGBA values of the Color.`

src_c/color.c

@@ -116,6 +116,7 @@ COLOR_FROM_SPACE(hsla);
 COLOR_FROM_SPACE(cmy);
 COLOR_FROM_SPACE(i1i2i3);
 COLOR_FROM_SPACE(normalized);
+COLOR_FROM_SPACE(hex);
 #undef COLOR_FROM_SPACE
 
 /* Getters/setters */
@@ -240,6 +241,8 @@ static PyMethodDef _color_methods[] = {
      DOC_COLOR_FROMI1I2I3},
     {"from_normalized", (PyCFunction)_color_from_normalized,
      METH_CLASS | METH_VARARGS, DOC_COLOR_FROMNORMALIZED},
+    {"from_hex", (PyCFunction)_color_from_hex, METH_CLASS | METH_VARARGS,
+     DOC_COLOR_FROMHEX},
     {"normalize", (PyCFunction)_color_normalize, METH_NOARGS,
      DOC_COLOR_NORMALIZE},
     {"correct_gamma", (PyCFunction)_color_correct_gamma, METH_VARARGS,
@@ -723,6 +726,9 @@ _color_from_space(char *space, PyObject *args)
     else if (strcmp(space, "normalized") == 0) {
         set_success = _color_set_normalized(color, args, NULL);
     }
+    else if (strcmp(space, "hex") == 0) {
+        set_success = _color_set_hex(color, args, NULL);
+    }
 
     if (set_success != 0) {
         return NULL;

src_c/doc/color_doc.h

@@ -15,6 +15,7 @@
 #define DOC_COLOR_FROMHSLA "from_hsla(object, /) -> Color\nfrom_hsla(h, s, l, a, /) -> Color\nReturns a Color object from an HSLA representation"
 #define DOC_COLOR_FROMI1I2I3 "from_i1i2i3(object, /) -> Color\nfrom_i1i2i3(i1, i2, i3, /) -> Color\nReturns a Color object from a I1I2I3 representation"
 #define DOC_COLOR_FROMNORMALIZED "from_normalized(object, /) -> Color\nfrom_normalized(r, g, b, a /) -> Color\nReturns a Color object from a Normalized representation"
+#define DOC_COLOR_FROMHEX "from_hex(hex, /) -> Color\nReturns a Color object from a Hexadecimal representation"
 #define DOC_COLOR_NORMALIZE "normalize() -> tuple\nReturns the normalized RGBA values of the Color."
 #define DOC_COLOR_CORRECTGAMMA "correct_gamma(gamma, /) -> Color\nApplies a certain gamma value to the Color."
 #define DOC_COLOR_SETLENGTH "set_length(len, /) -> None\nSet the number of elements in the Color to 1,2,3, or 4."

test/color_test.py

@@ -848,6 +848,29 @@ def test_from_normalized(self):
             ValueError, lambda: pygame.Color.from_normalized(1, 1, 1, 1, "lel")
         )
 
+    def test_from_hex(self):
+        color1 = pygame.Color.from_hex("#FFFFFF")  # White
+        color2 = pygame.Color.from_hex("#000000")  # Black
+        color3 = pygame.Color.from_hex("#AAFF00")  # Random
+        color4 = pygame.Color.from_hex("#FF000080")  # Red (50% opacity)
+
+        expected_color1 = (255, 255, 255, 255)
+        expected_color2 = (0, 0, 0, 255)
+        expected_color3 = (170, 255, 0, 255)
+        expected_color4 = (255, 0, 0, 128)
+
+        self.assertEqual(color1, expected_color1)
+        self.assertEqual(color2, expected_color2)
+        self.assertEqual(color3, expected_color3)
+        self.assertEqual(color4, expected_color4)
+
+        self.assertRaises(ValueError, lambda: pygame.Color.from_hex("#FFFFFG"))
+        self.assertRaises(ValueError, lambda: pygame.Color.from_hex("#FFFFFFF"))
+        self.assertRaises(ValueError, lambda: pygame.Color.from_hex("not-a-color"))
+        self.assertRaises(
+            TypeError, lambda: pygame.Color.from_hex("not-a-color", "lel")
+        )
+
     def test_normalize(self):
         c = pygame.Color(204, 38, 194, 55)
         self.assertEqual(c.r, 204)