Deprecate is_upscaled flag in favor BaseRGBColor.new_from_upscaled()

Author: ZipFile

colormath/color_objects.py

@@ -5,6 +5,7 @@
 
 import logging
 import math
+import warnings
 
 import numpy
 
@@ -499,6 +500,9 @@ def __init__(self, xyy_x, xyy_y, xyy_Y, observer='2', illuminant='d50'):
         self.set_illuminant(illuminant)
 
 
+_DO_NOT_USE = object()
+
+
 class BaseRGBColor(ColorBase):
     """
     Base class for all RGB color spaces.
@@ -508,24 +512,35 @@ class BaseRGBColor(ColorBase):
 
     VALUES = ['rgb_r', 'rgb_g', 'rgb_b']
 
-    def __init__(self, rgb_r, rgb_g, rgb_b, is_upscaled=False):
-        """
-        :param float rgb_r: R coordinate. 0.0-1.0, or 0-255 if is_upscaled=True.
-        :param float rgb_g: G coordinate. 0.0-1.0, or 0-255 if is_upscaled=True.
-        :param float rgb_b: B coordinate. 0.0-1.0, or 0-255 if is_upscaled=True.
-        :keyword bool is_upscaled: If False, RGB coordinate values are
-            beteween 0.0 and 1.0. If True, RGB values are between 0 and 255.
-        """
+    def __new__(cls, rgb_r, rgb_g, rgb_b, is_upscaled=_DO_NOT_USE):
+        if is_upscaled is not _DO_NOT_USE:
+            warnings.warn(
+                (
+                    "is_upscaled flag is deprecated, use %s.new_from_upscaled"
+                    "(rgb_r, rgb_g, rgb_b) instead"
+                ) % cls.__name__,
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if is_upscaled:
+                # __init__ will be called twice here
+                return cls.new_from_upscaled(rgb_r, rgb_g, rgb_b)
+        return super(BaseRGBColor, cls).__new__(cls)
+
+    def __init__(self, rgb_r, rgb_g, rgb_b, is_upscaled=_DO_NOT_USE):
+        """
+        :param float rgb_r: R coordinate.
+        :param float rgb_g: G coordinate.
+        :param float rgb_b: B coordinate.
+        :keyword is_upscaled: deprecated.
+        """
+        if is_upscaled is not _DO_NOT_USE:
+            # avoid second __init__ call
+            return
         super(BaseRGBColor, self).__init__()
-        if is_upscaled:
-            self.rgb_r = rgb_r / 255.0
-            self.rgb_g = rgb_g / 255.0
-            self.rgb_b = rgb_b / 255.0
-        else:
-            self.rgb_r = float(rgb_r)
-            self.rgb_g = float(rgb_g)
-            self.rgb_b = float(rgb_b)
-        self.is_upscaled = is_upscaled
+        self.rgb_r = float(rgb_r)
+        self.rgb_g = float(rgb_g)
+        self.rgb_b = float(rgb_b)
 
     def _clamp_rgb_coordinate(self, coord):
         """
@@ -536,10 +551,7 @@ def _clamp_rgb_coordinate(self, coord):
         :rtype: float
         :returns: The clamped value.
         """
-        if not self.is_upscaled:
-            return min(max(coord, 0.0), 1.0)
-        else:
-            return min(max(coord, 0.0), 255.0)
+        return min(max(coord, 0.0), 1.0)
 
     @property
     def clamped_rgb_r(self):
@@ -595,25 +607,26 @@ def new_from_rgb_hex(cls, hex_str):
             colorstring = colorstring[1:]
         if len(colorstring) != 6:
             raise ValueError("input #%s is not in #RRGGBB format" % colorstring)
-        r, g, b = colorstring[:2], colorstring[2:4], colorstring[4:]
-        r, g, b = [int(n, 16) / 255.0 for n in (r, g, b)]
-        return cls(r, g, b)
+        return cls.new_from_upscaled(
+            int(colorstring[:2], 16),
+            int(colorstring[2:4], 16),
+            int(colorstring[4:], 16),
+        )
+
+    @classmethod
+    def new_from_upscaled(cls, r, g, b):
+        """Create new RGB color from coordinates in range 0-255."""
+        return cls(r / 255.0, g / 255.0, b / 255.0)
 
 
 # noinspection PyPep8Naming
 class sRGBColor(BaseRGBColor):
     """
     Represents an sRGB color.
 
-    .. note:: If you pass in upscaled values, we automatically scale them
-        down to 0.0-1.0. If you need the old upscaled values, you can
-        retrieve them with :py:meth:`get_upscaled_value_tuple`.
-
     :ivar float rgb_r: R coordinate
     :ivar float rgb_g: G coordinate
     :ivar float rgb_b: B coordinate
-    :ivar bool is_upscaled: If True, RGB values are between 0-255. If False,
-        0.0-1.0.
     """
 
     #: RGB space's gamma constant.
@@ -638,15 +651,9 @@ class BT2020Color(BaseRGBColor):
     """
     Represents a ITU-R BT.2020 color.
 
-    .. note:: If you pass in upscaled values, we automatically scale them
-        down to 0.0-1.0. If you need the old upscaled values, you can
-        retrieve them with :py:meth:`get_upscaled_value_tuple`.
-
     :ivar float rgb_r: R coordinate
     :ivar float rgb_g: G coordinate
     :ivar float rgb_b: B coordinate
-    :ivar bool is_upscaled: If True, RGB values are between 0-255. If False,
-        0.0-1.0.
     """
 
     #: RGB space's gamma constant.
@@ -671,15 +678,9 @@ class AdobeRGBColor(BaseRGBColor):
     """
     Represents an Adobe RGB color.
 
-    .. note:: If you pass in upscaled values, we automatically scale them
-        down to 0.0-1.0. If you need the old upscaled values, you can
-        retrieve them with :py:meth:`get_upscaled_value_tuple`.
-
     :ivar float rgb_r: R coordinate
     :ivar float rgb_g: G coordinate
     :ivar float rgb_b: B coordinate
-    :ivar bool is_upscaled: If True, RGB values are between 0-255. If False,
-        0.0-1.0.
     """
 
     #: RGB space's gamma constant.
@@ -704,15 +705,9 @@ class AppleRGBColor(BaseRGBColor):
     """
     Represents an AppleRGB color.
 
-    .. note:: If you pass in upscaled values, we automatically scale them
-        down to 0.0-1.0. If you need the old upscaled values, you can
-        retrieve them with :py:meth:`get_upscaled_value_tuple`.
-
     :ivar float rgb_r: R coordinate
     :ivar float rgb_g: G coordinate
     :ivar float rgb_b: B coordinate
-    :ivar bool is_upscaled: If True, RGB values are between 0-255. If False,
-        0.0-1.0.
     """
 
     #: RGB space's gamma constant.

tests/test_color_objects.py

@@ -270,12 +270,12 @@ def test_to_xyz_and_back(self):
         self.assertColorMatch(rgb, self.color)
 
     def test_conversion_to_hsl_max_r(self):
-        color = sRGBColor(255, 123, 50, is_upscaled=True)
+        color = sRGBColor.new_from_upscaled(255, 123, 50)
         hsl = convert_color(color, HSLColor)
         self.assertColorMatch(hsl, HSLColor(21.366, 1.000, 0.598))
 
     def test_conversion_to_hsl_max_g(self):
-        color = sRGBColor(123, 255, 50, is_upscaled=True)
+        color = sRGBColor.new_from_upscaled(123, 255, 50)
         hsl = convert_color(color, HSLColor)
         self.assertColorMatch(hsl, HSLColor(98.634, 1.000, 0.598))