Deprecate BaseRGBColor.clamped_rgb_{r,g,b} property in favor BaseRGBC…

…olor.clamped()

colormath/color_objects.py

@@ -635,37 +635,53 @@ def __init__(self, rgb_r, rgb_g, rgb_b, is_upscaled=_DO_NOT_USE):
         self.rgb_g = float(rgb_g)
         self.rgb_b = float(rgb_b)
 
-    def _clamp_rgb_coordinate(self, coord):
-        """
-        Clamps an RGB coordinate, taking into account whether or not the
-        color is upscaled or not.
-
-        :param float coord: The coordinate value.
-        :rtype: float
-        :returns: The clamped value.
-        """
-        return min(max(coord, 0.0), 1.0)
-
     @property
     def clamped_rgb_r(self):
         """
         The clamped (0.0-1.0) R value.
         """
-        return self._clamp_rgb_coordinate(self.rgb_r)
+        warnings.warn(
+            "color.clamped_rgb_r is deprecated, use color.clamped().rgb_r instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.clamped().rgb_r
 
     @property
     def clamped_rgb_g(self):
         """
         The clamped (0.0-1.0) G value.
         """
-        return self._clamp_rgb_coordinate(self.rgb_g)
+        warnings.warn(
+            "color.clamped_rgb_g is deprecated, use color.clamped().rgb_g instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.clamped().rgb_g
 
     @property
     def clamped_rgb_b(self):
         """
         The clamped (0.0-1.0) B value.
         """
-        return self._clamp_rgb_coordinate(self.rgb_b)
+        warnings.warn(
+            "color.clamped_rgb_b is deprecated, use color.clamped().rgb_b instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.clamped().rgb_b
+
+    def clamped(self):
+        """
+        Return copy of this color with coordinates clipped to fit in 0.0-1.0 range.
+
+        :rtype: sRGBColor
+        """
+        return type(self)(
+            min(max(0.0, self.rgb_r), 1.0),
+            min(max(0.0, self.rgb_g), 1.0),
+            min(max(0.0, self.rgb_b), 1.0),
+        )
 
     def get_upscaled_value_tuple(self):
         """
@@ -684,7 +700,7 @@ def get_rgb_hex(self):
 
         :rtype: str
         """
-        rgb_r, rgb_g, rgb_b = self.get_upscaled_value_tuple()
+        rgb_r, rgb_g, rgb_b = self.clamped().get_upscaled_value_tuple()
         return "#%02x%02x%02x" % (rgb_r, rgb_g, rgb_b)
 
     @classmethod

doc_src/conversions.rst

@@ -85,13 +85,9 @@ RGB conversions and out-of-gamut coordinates
 
 RGB spaces tend to have a smaller gamut than some of the CIE color spaces.
 When converting to RGB, this can cause some of the coordinates to end up
-being out of the acceptable range (0.0-1.0 or 0-255, depending on whether
-your RGB color is upscaled).
+being out of the acceptable range (0.0-1.0).
 
 Rather than clamp these for you, we leave them as-is. This allows for more
 accurate conversions back to the CIE color spaces. If you require the clamped
-(0.0-1.0 or 0-255) values, use the following properties on any RGB color:
-
-* ``clamped_rgb_r``
-* ``clamped_rgb_g``
-* ``clamped_rgb_b``
+values, call ``clamped()`` from any RGB color to get copy of this color with
+coordinates clipped to fit in 0.0-1.0 range.

tests/test_color_objects.py

@@ -305,6 +305,23 @@ def test_channel_clamping(self):
         self.assertEqual(low_b.clamped_rgb_g, low_b.rgb_g)
         self.assertEqual(low_b.clamped_rgb_b, 0.0)
 
+    def test_clamped(self):
+        for (r, g, b), expected in [
+            ((-.482, -.784, -.196), (0., 0., 0.)),
+            ((1.482, -.784, -.196), (1., 0., 0.)),
+            ((-.482, 1.784, -.196), (0., 1., 0.)),
+            ((1.482, 1.784, -.196), (1., 1., 0.)),
+            ((-.482, -.784, 1.196), (0., 0., 1.)),
+            ((1.482, -.784, 1.196), (1., 0., 1.)),
+            ((-.482, 1.784, 1.196), (0., 1., 1.)),
+            ((1.482, 1.784, 1.196), (1., 1., 1.)),
+            ((0.482, 0.784, 0.196), (0.482, 0.784, 0.196)),
+        ]:
+            self.assertEqual(
+                sRGBColor(r, g, b).clamped().get_value_tuple(),
+                expected,
+            )
+
     def test_to_xyz_and_back(self):
         xyz = convert_color(self.color, XYZColor)
         rgb = convert_color(xyz, sRGBColor)