paintcan 0.1.0__tar.gz

paintcan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 B.T. Franklin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paintcan-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.1
+Name: paintcan
+Version: 0.1.0
+Summary: A Pythonic library for creating beautiful, algorithmic color schemes.
+Author-Email: "B.T. Franklin" <brandon.franklin@gmail.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Multimedia :: Graphics
+Project-URL: Homepage, https://github.com/btfranklin/paintcan
+Project-URL: Issues, https://github.com/btfranklin/paintcan/issues
+Project-URL: Repository, https://github.com/btfranklin/paintcan.git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# PaintCan
+
+![PaintCan Social Preview](.github/social%20preview/paintcan_social_preview.jpg)
+
+**PaintCan** is a high-quality, Pythonic library for working with HSBA colors and generating beautiful, algorithmic color schemes. It provides robust tools for color manipulation and harmony generation.
+
+## Features
+
+- **HSBAColor**: A value-type representation of color using Hue, Saturation, Brightness, and Alpha (0.0 - 1.0).
+  - Cyclic Hue adjustment (wrapping).
+  - Clamping and Overflow support for Saturation and Brightness.
+  - Pythonic unpacking: `h, s, b, a = color`.
+- **ColorScheme**: A collection of colors generated by color theory rules.
+  - Supports the Sequence protocol (`len(scheme)`, `scheme[0]`, iteration).
+  - 8 factory methods for generating harmonious schemes:
+    - Analogous
+    - Accented Analogous
+    - Complementary
+    - Compound
+    - Monochromatic
+    - Shades
+    - Split Complementary
+    - Triadic
+
+## Installation
+
+Using PDM:
+```bash
+pdm add paintcan
+```
+
+Using pip:
+```bash
+pip install paintcan
+```
+
+## Usage
+
+### Working with HSBAColor
+
+```python
+from paintcan import HSBAColor
+
+# Create a color (Red)
+red = HSBAColor(hue=0.0, saturation=1.0, brightness=1.0, alpha=1.0)
+
+# Adjust Hue (wraps around)
+orange = red.adjust_hue(0.08)
+
+# Get the complement (Cyan-ish)
+cyan = red.complement()
+
+# Pythonic Unpacking
+h, s, b, a = cyan
+print(f"Hue: {h}, Saturation: {s}")
+```
+
+### Generating Color Schemes
+
+```python
+from paintcan import HSBAColor, ColorScheme
+
+# Start with a base color
+base = HSBAColor(0.5, 0.8, 0.9, 1.0) # Cyan-ish
+
+# Generate a Split Complementary scheme
+scheme = ColorScheme.from_split_complementary(base)
+
+# Access colors (behaves like a tuple)
+print(f"Scheme has {len(scheme)} colors.")
+theme = scheme.theme_color # First color is always the theme color
+
+for color in scheme:
+    print(color)
+```
+
+## Demo
+
+To see the color schemes in action in your terminal (using ANSI colors):
+
+```bash
+# If installed via PDM/Dev
+pdm run python -m paintcan
+
+# If installed in your environment
+python -m paintcan
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

paintcan-0.1.0/README.md

@@ -0,0 +1,91 @@
+# PaintCan
+
+![PaintCan Social Preview](.github/social%20preview/paintcan_social_preview.jpg)
+
+**PaintCan** is a high-quality, Pythonic library for working with HSBA colors and generating beautiful, algorithmic color schemes. It provides robust tools for color manipulation and harmony generation.
+
+## Features
+
+- **HSBAColor**: A value-type representation of color using Hue, Saturation, Brightness, and Alpha (0.0 - 1.0).
+  - Cyclic Hue adjustment (wrapping).
+  - Clamping and Overflow support for Saturation and Brightness.
+  - Pythonic unpacking: `h, s, b, a = color`.
+- **ColorScheme**: A collection of colors generated by color theory rules.
+  - Supports the Sequence protocol (`len(scheme)`, `scheme[0]`, iteration).
+  - 8 factory methods for generating harmonious schemes:
+    - Analogous
+    - Accented Analogous
+    - Complementary
+    - Compound
+    - Monochromatic
+    - Shades
+    - Split Complementary
+    - Triadic
+
+## Installation
+
+Using PDM:
+```bash
+pdm add paintcan
+```
+
+Using pip:
+```bash
+pip install paintcan
+```
+
+## Usage
+
+### Working with HSBAColor
+
+```python
+from paintcan import HSBAColor
+
+# Create a color (Red)
+red = HSBAColor(hue=0.0, saturation=1.0, brightness=1.0, alpha=1.0)
+
+# Adjust Hue (wraps around)
+orange = red.adjust_hue(0.08)
+
+# Get the complement (Cyan-ish)
+cyan = red.complement()
+
+# Pythonic Unpacking
+h, s, b, a = cyan
+print(f"Hue: {h}, Saturation: {s}")
+```
+
+### Generating Color Schemes
+
+```python
+from paintcan import HSBAColor, ColorScheme
+
+# Start with a base color
+base = HSBAColor(0.5, 0.8, 0.9, 1.0) # Cyan-ish
+
+# Generate a Split Complementary scheme
+scheme = ColorScheme.from_split_complementary(base)
+
+# Access colors (behaves like a tuple)
+print(f"Scheme has {len(scheme)} colors.")
+theme = scheme.theme_color # First color is always the theme color
+
+for color in scheme:
+    print(color)
+```
+
+## Demo
+
+To see the color schemes in action in your terminal (using ANSI colors):
+
+```bash
+# If installed via PDM/Dev
+pdm run python -m paintcan
+
+# If installed in your environment
+python -m paintcan
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

paintcan-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "paintcan"
+version = "0.1.0"
+description = "A Pythonic library for creating beautiful, algorithmic color schemes."
+authors = [
+    { name = "B.T. Franklin", email = "brandon.franklin@gmail.com" },
+]
+dependencies = []
+requires-python = ">=3.11"
+readme = "README.md"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Multimedia :: Graphics",
+]
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+Homepage = "https://github.com/btfranklin/paintcan"
+Issues = "https://github.com/btfranklin/paintcan/issues"
+Repository = "https://github.com/btfranklin/paintcan.git"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.build]
+excludes = [
+    "tests/**",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "flake8>=7.3.0",
+]

paintcan-0.1.0/src/paintcan/__init__.py

@@ -0,0 +1,2 @@
+from .hsba_color import HSBAColor
+from .color_scheme import ColorScheme

paintcan-0.1.0/src/paintcan/__init__.pyi

@@ -0,0 +1,2 @@
+from .color_scheme import ColorScheme as ColorScheme
+from .hsba_color import HSBAColor as HSBAColor

paintcan-0.1.0/src/paintcan/__main__.py

@@ -0,0 +1,62 @@
+from .hsba_color import HSBAColor
+from .color_scheme import ColorScheme
+
+def print_color(color: HSBAColor, text: str = "  "):
+    # Simple HSBA to RGB conversion for demo purposes
+    # Source: https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB
+    h = color.hue * 360
+    s = color.saturation
+    v = color.brightness
+    
+    c = v * s
+    x = c * (1 - abs((h / 60) % 2 - 1))
+    m = v - c
+    
+    if 0 <= h < 60:
+        r, g, b = c, x, 0
+    elif 60 <= h < 120:
+        r, g, b = x, c, 0
+    elif 120 <= h < 180:
+        r, g, b = 0, c, x
+    elif 180 <= h < 240:
+        r, g, b = 0, x, c
+    elif 240 <= h < 300:
+        r, g, b = x, 0, c
+    else:
+        r, g, b = c, 0, x
+        
+    r = int((r + m) * 255)
+    g = int((g + m) * 255)
+    b = int((b + m) * 255)
+    
+    # ANSI escape code for background color
+    print(f"\033[48;2;{r};{g};{b}m{text}\033[0m", end=" ")
+
+def print_scheme(name: str, scheme: ColorScheme):
+    print(f"{name:<15}: ", end="")
+    for color in scheme:
+        print_color(color, "      ")
+    print(f"  (Theme Hue: {scheme.theme_color.hue:.2f})")
+
+def main():
+    # Start with a random bright color
+    print("Generating random base color...")
+    base = HSBAColor.random(saturation_range=(0.7, 1.0), brightness_range=(0.8, 1.0))
+    
+    print("\nBetterColors Demo")
+    print("=================")
+    print(f"{'Base Color':<15}: ", end="")
+    print_color(base, "      ")
+    print("\n")
+    
+    print_scheme("Analogous", ColorScheme.from_analogous(base))
+    print_scheme("Complementary", ColorScheme.from_complementary(base))
+    print_scheme("Triadic", ColorScheme.from_triadic(base))
+    print_scheme("Split Compl.", ColorScheme.from_split_complementary(base))
+    print_scheme("Monochromatic", ColorScheme.from_monochromatic(base))
+    print_scheme("Compound", ColorScheme.from_compound(base))
+    print_scheme("Shades", ColorScheme.from_shades(base))
+    print_scheme("Accented Analog", ColorScheme.from_accented_analogous(base))
+
+if __name__ == "__main__":
+    main()

paintcan-0.1.0/src/paintcan/__main__.pyi

@@ -0,0 +1,6 @@
+from .color_scheme import ColorScheme as ColorScheme
+from .hsba_color import HSBAColor as HSBAColor
+
+def print_color(color: HSBAColor, text: str = '  '): ...
+def print_scheme(name: str, scheme: ColorScheme): ...
+def main() -> None: ...

paintcan-0.1.0/src/paintcan/color_scheme.py

@@ -0,0 +1,229 @@
+from dataclasses import dataclass
+from typing import Tuple, Self, Iterator
+from .hsba_color import HSBAColor
+
+@dataclass(frozen=True)
+class ColorScheme:
+    """
+    A collection of colors comprising a color scheme.
+    Behaves like a read-only sequence of HSBAColor.
+    """
+    colors: Tuple[HSBAColor, ...]
+
+    def __post_init__(self):
+        if not self.colors:
+            raise ValueError("ColorScheme colors cannot be empty")
+
+    def __len__(self) -> int:
+        return len(self.colors)
+
+    def __getitem__(self, index: int) -> HSBAColor:
+        return self.colors[index]
+
+    def __iter__(self) -> Iterator[HSBAColor]:
+        return iter(self.colors)
+
+    @property
+    def theme_color(self) -> HSBAColor:
+        return self.colors[0]
+
+    @classmethod
+    def from_analogous(cls, theme_color: HSBAColor, spacing: float = 0.05) -> Self:
+        if not (0.0 <= spacing < 0.2):
+             raise ValueError("Spacing must be between 0 and 0.2")
+
+        colors = []
+        colors.append(theme_color)
+        
+        # Color 2
+        colors.append(theme_color
+                      .adjust_saturation(-0.05, floor=0.10)
+                      .adjust_hue(spacing)
+                      .adjust_brightness(-0.05, floor=0.20))
+        
+        # Color 3
+        colors.append(theme_color
+                      .adjust_saturation(-0.05, floor=0.10)
+                      .adjust_hue(spacing * 2)
+                      .adjust_brightness(0, floor=0.20))
+        
+        # Color 4
+        colors.append(theme_color
+                      .adjust_saturation(-0.05, floor=0.10)
+                      .adjust_hue(-spacing)
+                      .adjust_brightness(-0.05, floor=0.20))
+
+        # Color 5
+        colors.append(theme_color
+                      .adjust_saturation(-0.05, floor=0.10)
+                      .adjust_hue(-(spacing * 2))
+                      .adjust_brightness(0, floor=0.20))
+        
+        return cls(tuple(colors))
+
+    @classmethod
+    def from_accented_analogous(cls, theme_color: HSBAColor, spacing: float = 0.05) -> Self:
+        if not (0.0 <= spacing < 0.2):
+             raise ValueError("Spacing must be between 0 and 0.2")
+
+        colors = []
+        colors.append(theme_color)
+
+        # Color 2
+        colors.append(theme_color
+                      .adjust_saturation(-0.05, floor=0.10)
+                      .adjust_hue(spacing)
+                      .adjust_brightness(-0.05, floor=0.20))
+        
+        # Color 3
+        colors.append(theme_color
+                      .adjust_saturation(-0.05, floor=0.10)
+                      .adjust_hue(-spacing)
+                      .adjust_brightness(-0.05, floor=0.20))
+        
+        # Accent 1
+        colors.append(theme_color
+                      .adjust_saturation(-0.05, floor=0.10)
+                      .adjust_hue(spacing * 2)
+                      .complement()
+                      .adjust_brightness(0, floor=0.20))
+
+        # Accent 2
+        colors.append(theme_color
+                      .adjust_saturation(-0.05, floor=0.10)
+                      .adjust_hue(-(spacing * 2))
+                      .complement()
+                      .adjust_brightness(0, floor=0.20))
+
+        return cls(tuple(colors))
+
+    @classmethod
+    def from_complementary(cls, theme_color: HSBAColor) -> Self:
+        colors = []
+        colors.append(theme_color)
+        
+        colors.append(theme_color
+                      .adjust_saturation(0.10)
+                      .adjust_brightness(-0.30, floor=0.20, overflow=True))
+        
+        colors.append(theme_color
+                      .adjust_saturation(-0.10)
+                      .adjust_brightness(0.30))
+        
+        colors.append(theme_color
+                      .complement()
+                      .adjust_saturation(0.20)
+                      .adjust_brightness(-0.30, floor=0.20, overflow=True))
+        
+        colors.append(theme_color.complement())
+        
+        return cls(tuple(colors))
+
+    @classmethod
+    def from_compound(cls, theme_color: HSBAColor) -> Self:
+        colors = []
+        colors.append(theme_color)
+        
+        colors.append(theme_color
+                      .adjust_hue(0.1)
+                      .adjust_saturation(-0.10, floor=0.10)
+                      .adjust_brightness(-0.20, floor=0.20))
+        
+        colors.append(theme_color
+                      .adjust_hue(0.1)
+                      .adjust_saturation(-0.40, floor=0.10, ceiling=0.90)
+                      .adjust_brightness(-0.40, floor=0.20))
+        
+        colors.append(theme_color
+                      .adjust_hue(-0.05)
+                      .complement()
+                      .adjust_saturation(-0.25, floor=0.10)
+                      .adjust_brightness(0.05, floor=0.20))
+        
+        colors.append(theme_color
+                      .adjust_hue(-0.1)
+                      .complement()
+                      .adjust_saturation(0.10, ceiling=0.90)
+                      .adjust_brightness(-0.20, floor=0.20))
+        
+        return cls(tuple(colors))
+
+    @classmethod
+    def from_monochromatic(cls, theme_color: HSBAColor) -> Self:
+        colors = []
+        colors.append(theme_color)
+        
+        colors.append(theme_color
+                      .adjust_brightness(-0.50, floor=0.20, overflow=True))
+        
+        colors.append(theme_color
+                      .adjust_saturation(-0.30, floor=0.10, ceiling=0.70, overflow=True))
+        
+        colors.append(theme_color
+                      .adjust_brightness(-0.50, floor=0.20, overflow=True)
+                      .adjust_saturation(-0.3, floor=0.10, ceiling=0.70, overflow=True))
+        
+        colors.append(theme_color
+                      .adjust_brightness(-0.20, floor=0.20, overflow=True))
+
+        return cls(tuple(colors))
+
+    @classmethod
+    def from_shades(cls, theme_color: HSBAColor) -> Self:
+        colors = []
+        colors.append(theme_color)
+        
+        colors.append(theme_color.adjust_brightness(-0.25, floor=0.20, overflow=True))
+        colors.append(theme_color.adjust_brightness(-0.50, floor=0.20, overflow=True))
+        colors.append(theme_color.adjust_brightness(-0.75, floor=0.20, overflow=True))
+        colors.append(theme_color.adjust_brightness(-0.10, floor=0.20))
+
+        return cls(tuple(colors))
+
+    @classmethod
+    def from_split_complementary(cls, theme_color: HSBAColor, spacing: float = 0.05) -> Self:
+        colors = []
+        colors.append(theme_color)
+        
+        colors.append(theme_color
+                      .adjust_saturation(0.10)
+                      .adjust_brightness(-0.30, floor=0.20, overflow=True))
+        
+        colors.append(theme_color
+                      .adjust_saturation(-0.10)
+                      .adjust_brightness(0.30))
+        
+        colors.append(theme_color
+                      .complement()
+                      .adjust_hue(spacing))
+        
+        colors.append(theme_color
+                      .complement()
+                      .adjust_hue(-spacing))
+
+        return cls(tuple(colors))
+
+    @classmethod
+    def from_triadic(cls, theme_color: HSBAColor) -> Self:
+        colors = []
+        colors.append(theme_color)
+        
+        colors.append(theme_color
+                      .adjust_saturation(0.10)
+                      .adjust_brightness(-0.30, floor=0.20, overflow=True))
+        
+        colors.append(theme_color
+                      .adjust_hue(0.33)
+                      .adjust_saturation(-0.10))
+        
+        colors.append(theme_color
+                      .adjust_hue(0.66)
+                      .adjust_saturation(-0.10)
+                      .adjust_brightness(-0.20))
+        
+        colors.append(theme_color
+                      .adjust_hue(0.66)
+                      .adjust_saturation(-0.05)
+                      .adjust_brightness(-0.30, floor=0.40, overflow=True))
+
+        return cls(tuple(colors))

paintcan-0.1.0/src/paintcan/color_scheme.pyi

@@ -0,0 +1,29 @@
+from .hsba_color import HSBAColor as HSBAColor
+from dataclasses import dataclass
+from typing import Iterator, Self
+
+@dataclass(frozen=True)
+class ColorScheme:
+    colors: tuple[HSBAColor, ...]
+    def __post_init__(self) -> None: ...
+    def __len__(self) -> int: ...
+    def __getitem__(self, index: int) -> HSBAColor: ...
+    def __iter__(self) -> Iterator[HSBAColor]: ...
+    @property
+    def theme_color(self) -> HSBAColor: ...
+    @classmethod
+    def from_analogous(cls, theme_color: HSBAColor, spacing: float = 0.05) -> Self: ...
+    @classmethod
+    def from_accented_analogous(cls, theme_color: HSBAColor, spacing: float = 0.05) -> Self: ...
+    @classmethod
+    def from_complementary(cls, theme_color: HSBAColor) -> Self: ...
+    @classmethod
+    def from_compound(cls, theme_color: HSBAColor) -> Self: ...
+    @classmethod
+    def from_monochromatic(cls, theme_color: HSBAColor) -> Self: ...
+    @classmethod
+    def from_shades(cls, theme_color: HSBAColor) -> Self: ...
+    @classmethod
+    def from_split_complementary(cls, theme_color: HSBAColor, spacing: float = 0.05) -> Self: ...
+    @classmethod
+    def from_triadic(cls, theme_color: HSBAColor) -> Self: ...

paintcan-0.1.0/src/paintcan/hsba_color.py

@@ -0,0 +1,100 @@
+from dataclasses import dataclass
+import random
+from typing import Self
+
+@dataclass(frozen=True)
+class HSBAColor:
+    """
+    A color represented by Hue, Saturation, Brightness, and Alpha components.
+    All components are floats in the range [0.0, 1.0].
+    """
+    hue: float
+    saturation: float
+    brightness: float
+    alpha: float
+
+    def __iter__(self):
+        """Allows unpacking: h, s, b, a = color"""
+        return iter((self.hue, self.saturation, self.brightness, self.alpha))
+
+    def adjust_hue(self, change: float) -> Self:
+        """
+        Returns a new HSBAColor with the hue adjusted by the given amount.
+        The result is wrapped to the [0.0, 1.0] range cyclically.
+        Param `change` must be between -1.0 and 1.0.
+        """
+        if not (-1.0 <= change <= 1.0):
+             raise ValueError("Hue adjustment must be between -1.0 and 1.0")
+
+        new_hue = self.hue + change
+
+        if new_hue > 1.0:
+            new_hue -= 1.0
+        elif new_hue < 0.0:
+            new_hue += 1.0
+        
+        return HSBAColor(new_hue, self.saturation, self.brightness, self.alpha)
+
+    def complement(self) -> Self:
+        """Returns the complementary color (180 degrees reduced hue)."""
+        return self.adjust_hue(0.5)
+
+    def adjust_saturation(self, change: float, floor: float = 0.0, ceiling: float = 1.0, overflow: bool = False) -> Self:
+        """
+        Returns a new HSBAColor with adjusted saturation.
+        If overflow is True, values outside [floor, ceiling] wrap around.
+        If overflow is False, values are clamped.
+        """
+        new_saturation = self.saturation + change
+        new_saturation = self._apply_bounds(new_saturation, floor, ceiling, overflow)
+        return HSBAColor(self.hue, new_saturation, self.brightness, self.alpha)
+
+    def adjust_brightness(self, change: float, floor: float = 0.0, ceiling: float = 1.0, overflow: bool = False) -> Self:
+        """
+        Returns a new HSBAColor with adjusted brightness.
+        """
+        new_brightness = self.brightness + change
+        new_brightness = self._apply_bounds(new_brightness, floor, ceiling, overflow)
+        return HSBAColor(self.hue, self.saturation, new_brightness, self.alpha)
+
+    def adjust_alpha(self, change: float, floor: float = 0.0, ceiling: float = 1.0) -> Self:
+        """
+        Returns a new HSBAColor with adjusted alpha.
+        Alpha is always clamped, never overflows.
+        """
+        new_alpha = self.alpha + change
+        if new_alpha > ceiling:
+            new_alpha = ceiling
+        elif new_alpha < floor:
+            new_alpha = floor
+        
+        return HSBAColor(self.hue, self.saturation, self.brightness, new_alpha)
+
+    def _apply_bounds(self, value: float, floor: float, ceiling: float, overflow: bool) -> float:
+        """Helper to apply floor/ceiling logic with optional overflow."""
+        if overflow:
+            if value > ceiling:
+                value -= (ceiling - floor)
+            elif value < floor:
+                value += (ceiling - floor)
+        else:
+            if value > ceiling:
+                value = ceiling
+            elif value < floor:
+                value = floor
+        return value
+
+    @classmethod
+    def random(cls, saturation_range: tuple[float, float] = (0.0, 1.0),
+               brightness_range: tuple[float, float] = (0.0, 1.0)) -> Self:
+        """
+        Generates a random HSBAColor.
+        Hue is always random [0.0, 1.0].
+        Alpha is 1.0.
+        """
+        return cls(
+            hue=random.uniform(0.0, 1.0),
+            saturation=random.uniform(*saturation_range),
+            brightness=random.uniform(*brightness_range),
+            alpha=1.0
+        )

paintcan-0.1.0/src/paintcan/hsba_color.pyi

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+from typing import Self
+
+@dataclass(frozen=True)
+class HSBAColor:
+    hue: float
+    saturation: float
+    brightness: float
+    alpha: float
+    def __iter__(self): ...
+    def adjust_hue(self, change: float) -> Self: ...
+    def complement(self) -> Self: ...
+    def adjust_saturation(self, change: float, floor: float = 0.0, ceiling: float = 1.0, overflow: bool = False) -> Self: ...
+    def adjust_brightness(self, change: float, floor: float = 0.0, ceiling: float = 1.0, overflow: bool = False) -> Self: ...
+    def adjust_alpha(self, change: float, floor: float = 0.0, ceiling: float = 1.0) -> Self: ...
+    @classmethod
+    def random(cls, saturation_range: tuple[float, float] = (0.0, 1.0), brightness_range: tuple[float, float] = (0.0, 1.0)) -> Self: ...