hbutils.color.model

Color model utilities for RGB/HSV/HLS conversion and CSS3 name handling.

This module provides a high-level Color class that represents colors in RGB space and offers convenient conversions to HSV and HLS color models. It supports construction from CSS3 color names, hex strings, RGB tuples, or other Color instances, and optionally manages alpha (transparency) values.

The module is designed to keep component values within valid ranges:

RGB, HSV, HLS components are clamped to [0.0, 1.0].
Hue values are wrapped (cyclic) to [0.0, 1.0].
Alpha values are clamped to [0.0, 1.0].

Main components:

Color - Color representation with RGB/HSV/HLS conversion support.

Note

The RGB/HSV/HLS component proxies returned by Color.rgb, Color.hsv, and Color.hls allow in-place modifications of the underlying color instance.

Example:

>>> from hbutils.color import Color
>>> c = Color('red')
>>> str(c)
'#ff0000'
>>> c.rgb.red
1.0
>>> c.hsv.hue
0.0
>>> c.alpha is None
True
>>> c.alpha = 0.5
>>> str(c)
'#ff000080'

all

hbutils.color.model.__all__ = ['Color']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

GetSetProxy

class hbutils.color.model.GetSetProxy(getter: Callable, setter: Callable | None = None)[source]

A lightweight getter/setter proxy.

This class provides a unified interface to a getter callable and an optional setter callable. If no setter is provided, attempting to set will raise NotImplementedError.

Parameters:

getter (Callable) – Function to retrieve the value.
setter (Optional[Callable]) – Optional function to update the value.

__init__(getter: Callable, setter: Callable | None = None)[source]

Initialize the GetSetProxy.

Parameters:

getter (Callable) – Function to get the value.
setter (Optional[Callable]) – Optional function to set the value. If None, the setter raises NotImplementedError.

get() → Any[source]

Get the value using the getter function.

Returns:: The retrieved value.
Return type:: Any

set(value: Any) → Any[source]

Set the value using the setter function.

Parameters:: value (Any) – Value to set.
Returns:: Result of the setter function.
Return type:: Any

RGBColorProxy

class hbutils.color.model.RGBColorProxy(this: Color, r: GetSetProxy, g: GetSetProxy, b: GetSetProxy)[source]

RGB color component proxy for Color.

Instances of this class are returned by Color.rgb and provide readable and writable access to the RGB components.

Parameters:

this (Color) – Original color object.
r (GetSetProxy) – Get-set proxy for red.
g (GetSetProxy) – Get-set proxy for green.
b (GetSetProxy) – Get-set proxy for blue.

__init__(this: Color, r: GetSetProxy, g: GetSetProxy, b: GetSetProxy)[source]

Constructor of RGBColorProxy.

Parameters:

this (Color) – Original color object.
r (GetSetProxy) – Get-set proxy for red.
g (GetSetProxy) – Get-set proxy for green.
b (GetSetProxy) – Get-set proxy for blue.

__iter__() → Iterator[float][source]

Iterator for this proxy.

Returns:: Iterator yielding red, green, and blue values.
Return type:: Iterator[float]

Examples:

>>> from hbutils.color import Color
>>>
>>> c = Color('green')
>>> r, g, b = c.rgb
>>> print(r, g, b)
0.0 0.5019607843137255 0.0

__repr__() → str[source]

Representation format.

Returns:: String representation of the RGB color proxy.
Return type:: str

Examples:

>>> from hbutils.color import Color
>>>
>>> c = Color('green')
>>> c.rgb
<RGBColorProxy red: 0.000, green: 0.502, blue: 0.000>

property blue: float

Blue value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Blue component value.
Return type:: float

property blue: float

Blue value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Blue component value.
Return type:: float

property green: float

Green value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Green component value.
Return type:: float

property green: float

Green value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Green component value.
Return type:: float

property red: float

Red value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Red component value.
Return type:: float

property red: float

Red value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Red component value.
Return type:: float

HSVColorProxy

class hbutils.color.model.HSVColorProxy(this: Color, h: GetSetProxy, s: GetSetProxy, v: GetSetProxy)[source]

HSV color component proxy for Color.

Instances of this class are returned by Color.hsv and provide readable and writable access to HSV components.

Parameters:

this (Color) – Original color object.
h (GetSetProxy) – Get-set proxy for hue.
s (GetSetProxy) – Get-set proxy for saturation.
v (GetSetProxy) – Get-set proxy for value.

__init__(this: Color, h: GetSetProxy, s: GetSetProxy, v: GetSetProxy)[source]

Constructor of HSVColorProxy.

Parameters:

this (Color) – Original color object.
h (GetSetProxy) – Get-set proxy for hue.
s (GetSetProxy) – Get-set proxy for saturation.
v (GetSetProxy) – Get-set proxy for value.

__iter__() → Iterator[float][source]

Iterator for this proxy.

Returns:: Iterator yielding hue, saturation, and value.
Return type:: Iterator[float]

Examples:

>>> from hbutils.color import Color
>>>
>>> c = Color('green')
>>> h, s, v = c.hsv
>>> print(h, s, v)
0.3333333333333333 1.0 0.5019607843137255

__repr__() → str[source]

Representation format.

Returns:: String representation of the HSV color proxy.
Return type:: str

Examples:

>>> from hbutils.color import Color
>>>
>>> c = Color('green')
>>> c.hsv
<HSVColorProxy hue: 0.333, saturation: 1.000, value: 0.502>

property brightness: float

Alias for value.

Returns:: Brightness (value) component value.
Return type:: float

property brightness: float

Alias for value.

Returns:: Brightness (value) component value.
Return type:: float

property hue: float

Hue value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Hue component value.
Return type:: float

property hue: float

Hue value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Hue component value.
Return type:: float

property saturation: float

Saturation value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Saturation component value.
Return type:: float

property saturation: float

Saturation value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Saturation component value.
Return type:: float

property value: float

Value (brightness) value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Value (brightness) component value.
Return type:: float

property value: float

Value (brightness) value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Value (brightness) component value.
Return type:: float

HLSColorProxy

class hbutils.color.model.HLSColorProxy(this: Color, h: GetSetProxy, l: GetSetProxy, s: GetSetProxy)[source]

HLS color component proxy for Color.

Instances of this class are returned by Color.hls and provide readable and writable access to HLS components.

Parameters:

this (Color) – Original color object.
h (GetSetProxy) – Get-set proxy for hue.
l (GetSetProxy) – Get-set proxy for lightness.
s (GetSetProxy) – Get-set proxy for saturation.

__init__(this: Color, h: GetSetProxy, l: GetSetProxy, s: GetSetProxy)[source]

Constructor of HLSColorProxy.

Parameters:

this (Color) – Original color object.
h (GetSetProxy) – Get-set proxy for hue.
l (GetSetProxy) – Get-set proxy for lightness.
s (GetSetProxy) – Get-set proxy for saturation.

__iter__() → Iterator[float][source]

Iterator for this proxy.

Returns:: Iterator yielding hue, lightness, and saturation.
Return type:: Iterator[float]

Examples:

>>> from hbutils.color import Color
>>>
>>> c = Color('green')
>>> h, l, s = c.hls
>>> print(h, l, s)
0.3333333333333333 0.25098039215686274 1.0

__repr__() → str[source]

Representation format.

Returns:: String representation of the HLS color proxy.
Return type:: str

Examples:

>>> from hbutils.color import Color
>>>
>>> c = Color('green')
>>> c.hls
<HLSColorProxy hue: 0.333, lightness: 0.251, saturation: 1.000>

property hue: float

Hue value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Hue component value.
Return type:: float

property hue: float

Hue value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Hue component value.
Return type:: float

property lightness: float

Lightness value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Lightness component value.
Return type:: float

property lightness: float

Lightness value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Lightness component value.
Return type:: float

property saturation: float

Saturation value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Saturation component value.
Return type:: float

property saturation: float

Saturation value (within \(\left[0.0, 1.0\right]\)).

Note

Setter is available, the change will affect the Color object.

Returns:: Saturation component value.
Return type:: float

Color

class hbutils.color.model.Color(c: str | Tuple[float, float, float] | Color, alpha: float | None = None)[source]

Color utility object supporting RGB/HSV/HLS and CSS3 names.

A Color instance can be created from CSS3 color names, hexadecimal strings, RGB tuples, or another Color object. Component values are normalized to floats in [0.0, 1.0], and optional alpha values are supported.

Examples:

>>> from hbutils.color import Color
>>>
>>> c = Color('red')  # from name
>>> c
<Color red>
>>> str(c)  # hex format
'#ff0000'
>>> (c.rgb.red, c.rgb.green, c.rgb.blue)            # rgb format
(1.0, 0.0, 0.0)
>>> (c.hls.hue, c.hls.lightness, c.hls.saturation)  # hls format
(0.0, 0.5, 1.0)
>>> (c.hsv.hue, c.hsv.saturation, c.hsv.value)      # hsv format
(0.0, 1.0, 1.0)

>>> c1 = Color('#56a3f0')  # from hex
>>> c1
<Color #56a3f0>
>>> str(c1)  # hex format
'#56a3f0'
>>> (c1.rgb.red, c1.rgb.green, c1.rgb.blue)            # rgb format
(0.33725490196078434, 0.6392156862745098, 0.9411764705882353)
>>> (c1.hls.hue, c1.hls.lightness, c1.hls.saturation)  # hls format
(0.5833333333333334, 0.6392156862745098, 0.8369565217391304)
>>> (c1.hsv.hue, c1.hsv.saturation, c1.hsv.value)      # hsv format
(0.5833333333333334, 0.6416666666666666, 0.9411764705882353)

>>> c2 = Color('#56a3f077')  # from hex with alpha
>>> c2
<Color #56a3f0, alpha: 0.467>
>>> c2.alpha  # alpha value
0.4666666666666667
>>> str(c2)   # hex format
'#56a3f077'

__eq__(other: object) → bool[source]

Check equality between colors.

Parameters:: other (object) – Another object to compare with.
Returns:: True if equal, False otherwise.
Return type:: bool

__getstate__() → Tuple[float, float, float, float | None][source]

Dump color as a pickle-compatible tuple.

Returns:: Tuple containing (r, g, b, alpha).
Return type:: Tuple[float, float, float, Optional[float]]

__hash__() → int[source]

Get hash value of current object.

Returns:: Hash value of current color.
Return type:: int

__init__(c: str | Tuple[float, float, float] | Color, alpha: float | None = None)[source]

Constructor of Color.

Parameters:

c (Union[str, Tuple[float, float, float], Color]) – Color value; may be a hex string, an RGB tuple, or a Color object.
alpha (Optional[float]) – Alpha value; None means no alpha is stored.

Raises:

TypeError – If c is not a supported color type.
ValueError – If c is a string but not a valid hex or CSS3 color name.

__repr__() → str[source]

Get the string representation of the Color object.

Returns:: String representation.
Return type:: str

__setstate__(v: Tuple[float, float, float, float | None]) → None[source]

Load color from a pickle-compatible tuple.

Parameters:: v (Tuple[float, float, float, Optional[float]]) – Tuple containing (r, g, b, alpha).

__str__() → str[source]

Hex format of this Color object.

Returns:: Hexadecimal color string (includes alpha when present).
Return type:: str

property alpha: float | None

Alpha value (transparent ratio) within \(\left[0.0, 1.0\right]\).

Note

Setter is available.

Returns:: Alpha value, or None if no alpha is set.
Return type:: Optional[float]

property alpha: float | None

Alpha value (transparent ratio) within \(\left[0.0, 1.0\right]\).

Note

Setter is available.

Returns:: Alpha value, or None if no alpha is set.
Return type:: Optional[float]

classmethod from_hex(hex_: str) → Color[source]

Load color from a hexadecimal RGB string.

Parameters:: hex_ (str) – Hexadecimal string, may start with #.
Returns:: Color object.
Return type:: Color

classmethod from_hls(h: float, l: float, s: float, alpha: float | None = None) → Color[source]

Load color from HLS system.

Parameters:

h (float) – Hue value in \(\left[0, 1\right)\).
l (float) – Lightness value in \(\left[0, 1\right]\).
s (float) – Saturation value in \(\left[0, 1\right]\).
alpha (Optional[float]) – Alpha value in \(\left[0, 1\right]\); None means no alpha.

Returns:

Color object.

Return type:

Color

classmethod from_hsv(h: float, s: float, v: float, alpha: float | None = None) → Color[source]

Load color from HSV system.

Parameters:

h (float) – Hue value in \(\left[0, 1\right)\).
s (float) – Saturation value in \(\left[0, 1\right]\).
v (float) – Brightness (value) in \(\left[0, 1\right]\).
alpha (Optional[float]) – Alpha value in \(\left[0, 1\right]\); None means no alpha.

Returns:

Color object.

Return type:

Color

classmethod from_rgb(r: float, g: float, b: float, alpha: float | None = None) → Color[source]

Load color from RGB system.

Parameters:

r (float) – Red value in \(\left[0, 1\right]\).
g (float) – Green value in \(\left[0, 1\right]\).
b (float) – Blue value in \(\left[0, 1\right]\).
alpha (Optional[float]) – Alpha value in \(\left[0, 1\right]\); None means no alpha.

Returns:

Color object.

Return type:

Color

property hls: HLSColorProxy

HLS color proxy.

See HLSColorProxy for component access and mutation.

Returns:: HLS color proxy.
Return type:: HLSColorProxy

property hsv: HSVColorProxy

HSV color proxy.

See HSVColorProxy for component access and mutation.

Returns:: HSV color proxy.
Return type:: HSVColorProxy

property rgb: RGBColorProxy

RGB color proxy.

See RGBColorProxy for component access and mutation.

Returns:: RGB color proxy.
Return type:: RGBColorProxy

hbutils.color.model

__all__

GetSetProxy

RGBColorProxy

HSVColorProxy

HLSColorProxy

Color

all