update: 3.0.0

- Replaced existing GitHub Actions workflows (, ) with a new  for cross-platform wheel building and testing.
- Configured  to build wheels for Linux, macOS, and Windows, and to run tests using ============================= test session starts ==============================
platform linux -- Python 3.13.11, pytest-8.3.5, pluggy-1.6.0
rootdir: /home/tdynamos/materialyoucolor-python
plugins: timeout-2.3.1, anyio-3.7.1, Faker-33.3.1, cov-6.1.1, asyncio-0.26.0, typeguard-4.4.4
asyncio: mode=Mode.STRICT, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function
collected 0 items

============================ no tests ran in 3.53s ============================= for both Pillow and C++ image processing methods.
- Modified  to ensure  is always defined as a list, improving compatibility with .
- Added  to  to support RAM usage tracking in .
- Implemented peak RAM usage measurement in  for image generation using both Pillow and C++ methods.

Author: T-Dynamos

.github/workflows/cibuildwheel.yml

@@ -0,0 +1,87 @@
+name: Build and Test Wheels
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: recursive
+
+    - name: Install Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x' # cibuildwheel will use its own Python versions
+
+    - name: Install cibuildwheel
+      run: python -m pip install cibuildwheel==2.17.0
+
+    - name: Download test image file
+      run: |
+        # Photo by Dillon Hunt (https://unsplash.com/@dillon_hunt) on https://unsplash.com/photos/an-aerial-view-of-the-ocean-and-rocks-zQLd8RXbenw 
+        curl -L -o test_image.jpg "https://unsplash.com/photos/zQLd8RXbenw/download?ixid=M3wxMjA3fDB8MXx0b3BpY3x8NnNNVmpUTFNrZVF8fHx8fDJ8fDE3MzY0MDA3NTd8&force=true&w=2400"
+      # This step needs to be available for the test command
+      # For Windows, use PowerShell equivalent
+      shell: bash
+
+    - name: Build wheels
+      run: python -m cibuildwheel --output-dir wheelhouse
+      env:
+        CIBW_BUILD_VERBOSITY: 1
+        CIBW_SKIP: "cp37-* pp*" # Skip Python 3.7 and PyPy as per existing workflows
+        CIBW_ARCHS_MACOS: "x86_64 arm64" # Build for both architectures on macOS
+        CIBW_TEST_COMMAND: >
+          pip install psutil &&
+          pip install pillow &&
+          python -m pytest {project}/tests/test_all.py --image test_image.jpg --method pillow &&
+          python -m pytest {project}/tests/test_all.py --image test_image.jpg --method cpp
+        CIBW_BEFORE_BUILD: >
+          pip install setuptools wheel rich requests pillow
+        CIBW_ENVIRONMENT: >
+          PATH="$PATH:/opt/python/cp39-cp39/bin" # Example for manylinux, adjust as needed
+          PATH="$PATH:/opt/python/cp310-cp310/bin"
+          PATH="$PATH:/opt/python/cp311-cp311/bin"
+          PATH="$PATH:/opt/python/cp312-cp312/bin"
+          PATH="$PATH:/opt/python/cp313-cp313/bin"
+          PATH="$PATH:/opt/python/cp314-cp314/bin"
+          # Ensure PURE_PYTHON is not set for C++ extension builds
+          PURE_PYTHON=False
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: cibuildwheel-wheels-${{ matrix.os }}
+        path: wheelhouse/*.whl
+
+  deploy:
+    name: Publish to PyPI
+    needs: build_wheels
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Download all wheels
+      uses: actions/download-artifact@v4
+      with:
+        path: dist
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}
+        packages_dir: dist

.github/workflows/default.yml

@@ -1 +1 @@
-__version__ = "2.0.10"
+__version__ = "3.0.0"

.github/workflows/linux.yml

@@ -1 +0,0 @@
-from .blend import Blend

materialyoucolor/__init__.py

@@ -1,16 +1,25 @@
-from materialyoucolor.hct import Hct
 from materialyoucolor.hct.cam16 import Cam16
+from materialyoucolor.hct.hct import Hct
+from materialyoucolor.utils.color_utils import lstar_from_argb
 from materialyoucolor.utils.math_utils import (
-    sanitize_degrees_double,
     difference_degrees,
     rotation_direction,
+    sanitize_degrees_double,
 )
-from materialyoucolor.utils.color_utils import lstar_from_argb
 
 
 class Blend:
+    """
+    Functions for blending in HCT and CAM16.
+    """
+
     @staticmethod
     def harmonize(design_color: int, source_color: int) -> int:
+        """
+        Blend the design color's HCT hue towards the key color's HCT
+        hue, in a way that leaves the original color recognizable and
+        recognizably shifted towards the key color.
+        """
         from_hct = Hct.from_int(design_color)
         to_hct = Hct.from_int(source_color)
         difference_degrees_ = difference_degrees(from_hct.hue, to_hct.hue)
@@ -22,17 +31,24 @@ def harmonize(design_color: int, source_color: int) -> int:
         return Hct.from_hct(output_hue, from_hct.chroma, from_hct.tone).to_int()
 
     @staticmethod
-    def hct_hue(from_: int, to: int, amount: int) -> int:
-        ucs = Blend.cam16_ucs(from_, to, amount)
+    def hct_hue(from_argb: int, to_argb: int, amount: float) -> int:
+        """
+        Blends hue from one color into another. The chroma and tone of
+        the original color are maintained.
+        """
+        ucs = Blend.cam16_ucs(from_argb, to_argb, amount)
         ucs_cam = Cam16.from_int(ucs)
-        from_cam = Cam16.from_int(from_)
-        blended = Hct.from_hct(ucs_cam.hue, from_cam.chroma, lstar_from_argb(from_))
+        from_cam = Cam16.from_int(from_argb)
+        blended = Hct.from_hct(ucs_cam.hue, from_cam.chroma, lstar_from_argb(from_argb))
         return blended.to_int()
 
     @staticmethod
-    def cam16_ucs(from_: int, to: int, amount: float) -> int:
-        from_cam = Cam16.from_int(from_)
-        to_cam = Cam16.from_int(to)
+    def cam16_ucs(from_argb: int, to_argb: int, amount: float) -> int:
+        """
+        Blend in CAM16-UCS space.
+        """
+        from_cam = Cam16.from_int(from_argb)
+        to_cam = Cam16.from_int(to_argb)
         from_j = from_cam.jstar
         from_a = from_cam.astar
         from_b = from_cam.bstar

materialyoucolor/blend/__init__.py

@@ -1 +0,0 @@
-from .contrast import Contrast

materialyoucolor/blend/blend.py

@@ -1,5 +1,5 @@
+from materialyoucolor.utils.color_utils import lstar_from_y, y_from_lstar
 from materialyoucolor.utils.math_utils import clamp_double
-from materialyoucolor.utils.color_utils import y_from_lstar, lstar_from_y
 
 
 class Contrast:
@@ -11,7 +11,7 @@ def ratio_of_tones(tone_a: float, tone_b: float) -> float:
 
     @staticmethod
     def ratio_of_ys(y1: float, y2: float) -> float:
-        lighter = y1 if y1 > y2 else y2
+        lighter = max(y1, y2)
         darker = y1 if lighter == y2 else y2
         return (lighter + 5.0) / (darker + 5.0)
 
@@ -25,11 +25,12 @@ def lighter(tone: float, ratio: float) -> float:
         real_contrast = Contrast.ratio_of_ys(light_y, dark_y)
         delta = abs(real_contrast - ratio)
         if real_contrast < ratio and delta > 0.04:
-            return -1
+            return -1.0
 
         return_value = lstar_from_y(light_y) + 0.4
         if return_value < 0 or return_value > 100:
             return -1.0
+
         return return_value
 
     @staticmethod
@@ -38,24 +39,25 @@ def darker(tone: float, ratio: float) -> float:
             return -1.0
 
         light_y = y_from_lstar(tone)
-        dark_y = (light_y + 5.0) / ratio - 5.0
+        dark_y = ((light_y + 5.0) / ratio) - 5.0
         real_contrast = Contrast.ratio_of_ys(light_y, dark_y)
 
         delta = abs(real_contrast - ratio)
         if real_contrast < ratio and delta > 0.04:
-            return -1
+            return -1.0
 
         return_value = lstar_from_y(dark_y) - 0.4
-        if return_value < 0 or return_value > 100:
-            return -1
+        if return_value < 0.0 or return_value > 100.0:
+            return -1.0
+
         return return_value
 
     @staticmethod
-    def lighter_unsafe(tone, ratio):
+    def lighter_unsafe(tone: float, ratio: float) -> float:
         lighter_safe = Contrast.lighter(tone, ratio)
         return 100.0 if lighter_safe < 0.0 else lighter_safe
 
     @staticmethod
-    def darker_unsafe(tone, ratio):
+    def darker_unsafe(tone: float, ratio: float) -> float:
         darker_safe = Contrast.darker(tone, ratio)
         return 0.0 if darker_safe < 0.0 else darker_safe

materialyoucolor/contrast/__init__.py

@@ -1,16 +1,41 @@
-from materialyoucolor.hct import Hct
+from materialyoucolor.hct.hct import Hct
 
 
 class DislikeAnalyzer:
+    """
+    Check and/or fix universally disliked colors.
+    Color science studies of color preference indicate universal distaste for
+    dark yellow-greens, and also show this is correlated to distate for
+    biological waste and rotting food.
+
+    See Palmer and Schloss, 2010 or Schloss and Palmer's Chapter 21 in Handbook
+    of Color Psychology (2015).
+    """
+
     @staticmethod
     def is_disliked(hct: Hct) -> bool:
+        """
+        Returns true if a color is disliked.
+
+        :param hct: A color to be judged.
+        :return: Whether the color is disliked.
+
+        Disliked is defined as a dark yellow-green that is not neutral.
+        """
         hue_passes = round(hct.hue) >= 90.0 and round(hct.hue) <= 111.0
         chroma_passes = round(hct.chroma) > 16.0
         tone_passes = round(hct.tone) < 65.0
         return hue_passes and chroma_passes and tone_passes
 
     @staticmethod
     def fix_if_disliked(hct: Hct) -> Hct:
+        """
+        If a color is disliked, lighten it to make it likable.
+
+        :param hct: A color to be judged.
+        :return: A new color if the original color is disliked, or the original
+          color if it is acceptable.
+        """
         if DislikeAnalyzer.is_disliked(hct):
             return Hct.from_hct(
                 hct.hue,