0.9.0 - color animation interfaces

Author: vkottler

.github/workflows/python-package.yml

@@ -78,7 +78,7 @@ jobs:
 
       - run: |
           mk python-release owner=libre-embedded \
-                            repo=svgen version=0.8.8
+                            repo=svgen version=0.9.0
         if: |
           matrix.python-version == '3.12'
           && matrix.system == 'ubuntu-latest'

README.md

@@ -2,11 +2,11 @@
     =====================================
     generator=datazen
     version=3.2.3
-    hash=4e19b7fd794cee4f663c3486ed81a7ae
+    hash=8900a7ca18bc8f76384982687cb33826
     =====================================
 -->
 
-# svgen ([0.8.8](https://pypi.org/project/svgen/))
+# svgen ([0.9.0](https://pypi.org/project/svgen/))
 
 [![python](https://img.shields.io/pypi/pyversions/svgen.svg)](https://pypi.org/project/svgen/)
 ![Build Status](https://github.com/libre-embedded/svgen/workflows/Python%20Package/badge.svg)

local/variables/package.yaml

@@ -1,5 +1,5 @@
 ---
 major: 0
-minor: 8
-patch: 8
+minor: 9
+patch: 0
 entry: svgen

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta:__legacy__"
 
 [project]
 name = "svgen"
-version = "0.8.8"
+version = "0.9.0"
 description = "A tool for working with scalable vector graphics."
 readme = "README.md"
 requires-python = ">=3.12"

svgen/__init__.py

@@ -1,7 +1,7 @@
 # =====================================
 # generator=datazen
 # version=3.2.3
-# hash=d7ef29596b2bc69d2f78eb6f58e41e51
+# hash=1ced247e5dcefc85302a056ef8fe63cd
 # =====================================
 
 """
@@ -10,4 +10,4 @@
 
 DESCRIPTION = "A tool for working with scalable vector graphics."
 PKG_NAME = "svgen"
-VERSION = "0.8.8"
+VERSION = "0.9.0"

svgen/color/__init__.py

@@ -3,7 +3,7 @@
 """
 
 # built-in
-from typing import NamedTuple, Union
+from typing import NamedTuple, TypeVar, Union
 
 # internal
 from svgen.color.conversion import hsl_to_rgb, rgb_to_hsl
@@ -166,6 +166,7 @@
 CSS_COLORS["slategrey"] = CSS_COLORS["slategray"]
 
 Colorlike = Union[str, Hsl, Rgb, "Color"]
+T = TypeVar("T", bound="Color")
 
 
 class Color(NamedTuple):
@@ -180,17 +181,17 @@ def __eq__(self, other) -> bool:
         return bool(self.rgb == other.rgb or self.hsl == other.hsl)
 
     @classmethod
-    def from_rgb(cls, color: Rgb) -> "Color":
+    def from_rgb(cls: type[T], color: Rgb) -> T:
         """Create a color from an rgb object."""
         return cls(color, rgb_to_hsl(color))
 
     @classmethod
-    def from_hex(cls, value: str) -> "Color":
+    def from_hex(cls: type[T], value: str) -> T:
         """Create a color from a hex value."""
         return cls.from_rgb(Rgb.from_hex(value))
 
     @classmethod
-    def from_hsl(cls, color: Hsl) -> "Color":
+    def from_hsl(cls: type[T], color: Hsl) -> T:
         """Create a color from an hsl object."""
         return cls(hsl_to_rgb(color), color)
 
@@ -199,7 +200,7 @@ def hsl_arc(self, **kwargs) -> "Color":
         return self.from_hsl(self.hsl.arc(**kwargs))
 
     @classmethod
-    def from_ctor(cls, value: str) -> "Color":
+    def from_ctor(cls: type[T], value: str) -> T:
         """Create a color from an hsl or rgb constructor string."""
 
         # Check if this is a canonical color.
@@ -216,16 +217,47 @@ def from_ctor(cls, value: str) -> "Color":
         return cls.from_hex(value)
 
     @classmethod
-    def create(cls, value: Colorlike) -> "Color":
+    def create(cls: type[T], value: Colorlike) -> T:
         """Create a color from a variety of possible sources."""
-        if isinstance(value, Color):
-            return value
+
+        if isinstance(value, (cls, Color)):
+            return value  # type: ignore
         if isinstance(value, Hsl):
             return cls.from_hsl(value)
         if isinstance(value, Rgb):
             return cls.from_rgb(value)
         return cls.from_ctor(value)
 
+    def animate(
+        self: T,
+        hue: int = None,
+        saturation: float = None,
+        lightness: float = None,
+        red: int = None,
+        green: int = None,
+        blue: int = None,
+        alpha: float = None,
+        delta: bool = False,
+    ) -> T:
+        """Animate this color based on HSL properties."""
+
+        if red is not None or blue is not None or green is not None:
+            return self.from_rgb(
+                self.rgb.animate(
+                    red=red, green=green, blue=blue, alpha=alpha, delta=delta
+                )
+            )
+
+        return self.from_hsl(
+            self.hsl.animate(
+                hue=hue,
+                saturation=saturation,
+                lightness=lightness,
+                alpha=alpha,
+                delta=delta,
+            )
+        )
+
     def __str__(self) -> str:
         """Convert this color to a hex string."""
         return str(self.rgb)

svgen/color/hsl.py

@@ -47,6 +47,38 @@ class Hsl(NamedTuple):
     lightness: PercentPrimitive
     alpha: Alpha = DEFAULT
 
+    def animate(
+        self,
+        hue: int = None,
+        saturation: float = None,
+        lightness: float = None,
+        alpha: float = None,
+        delta: bool = False,
+    ) -> "Hsl":
+        """Manipulate this color into a new one."""
+
+        if hue is None:
+            hue = self.hue
+        elif delta:
+            hue = self.hue + hue
+
+        if saturation is None:
+            saturation = self.saturation.ratio
+        elif delta:
+            saturation = self.saturation.ratio + saturation
+
+        if lightness is None:
+            lightness = self.lightness.ratio
+        elif delta:
+            lightness = self.lightness.ratio + lightness
+
+        if alpha is None:
+            alpha = self.alpha
+        elif delta:
+            alpha = self.alpha + alpha
+
+        return hsla(hue, saturation, lightness, alpha)
+
     def arc(
         self,
         hue_count: int = 1,

svgen/color/numbers.py

@@ -37,8 +37,7 @@ def css_number_to_ratio(val: float | int | str) -> float:
         float_val = float(val) / 255.0
 
     # Normalize the result to a ratio between 0.0 and 1.0.
-    float_val = max(float_val, 0.0)
-    return min(float_val, 1.0)
+    return min(max(float_val, 0.0), 1.0)
 
 
 def parse_ctor(

svgen/color/resolve.py

@@ -2,13 +2,27 @@
 A module for resolving colors.
 """
 
+# built-in
+from contextlib import suppress
+
 # internal
 from svgen.color import Color, Colorlike
 from svgen.color.theme.manager import THEMES, ColorThemeManager
 
 
-def get_color(key: Colorlike, manager: ColorThemeManager = None) -> Color:
+def get_color(
+    key: Colorlike = "black", manager: ColorThemeManager = None, **kwargs
+) -> Color:
     """Resolve a color using the theme manager."""
+
     if manager is None:
         manager = THEMES
-    return manager[key].color
+
+    color = manager[kwargs.get("color", key)].color
+    with suppress(KeyError):
+        del kwargs["color"]
+
+    if kwargs:
+        color = color.animate(**kwargs)
+
+    return color

svgen/color/rgb.py

@@ -40,6 +40,38 @@ class Rgb(NamedTuple):
     blue: RgbPrimitive
     alpha: Alpha = DEFAULT
 
+    def animate(
+        self,
+        red: int = None,
+        green: int = None,
+        blue: int = None,
+        alpha: float = None,
+        delta: bool = False,
+    ) -> "Rgb":
+        """Animate a color."""
+
+        if red is None:
+            red = self.red
+        elif delta:
+            red = self.red + red
+
+        if green is None:
+            green = self.green
+        elif delta:
+            green = self.green + green
+
+        if blue is None:
+            blue = self.blue
+        elif delta:
+            blue = self.blue + blue
+
+        if alpha is None:
+            alpha = self.alpha
+        elif delta:
+            alpha = self.alpha + alpha
+
+        return rgba(red, green, blue, alpha)
+
     def __str__(self) -> str:
         """Get this color as a hex string."""