Color Class

The ColorClass is the core class of the bycolors package, providing a rich interface for color manipulation and transformation.

Constructor

ColorClass(palette: Union[str, Tuple[float, float, float], Dict], background_color: Optional[Tuple[float, float, float]] = None)

Parameters

• palette: The color value. Can be:

  • A hex string (e.g., "#FF0000")
  • An RGB/RGBA tuple (e.g., (1, 0, 0) or (1, 0, 0, 1))
  • A dictionary with 'main', 'dark', and 'light' variants

• background_color: Optional RGB tuple for alpha compositing. Defaults to white (1, 1, 1)

Properties

Color Variants

• .dark: Get a darker variant of the color (35% brightness if not specified in palette)
• .light: Get a lighter variant of the color (65% brightness if not specified in palette)
• .main: Get the main color instance
• .transparent: Get a fully transparent version of the color

Color Formats

• .rgb: Get RGB values (0-1 range)
• .rgba: Get RGBA values (0-1 range)
• .hex: Get hexadecimal color string

Methods

Opacity Control

.opacity(opacity: float, background_color: Optional[Tuple[float, float, float]] = None)
.alpha(alpha: float, background_color: Optional[Tuple[float, float, float]] = None)  # alias for opacity

Control the transparency of the color. Values range from 0 (transparent) to 1 (opaque).

Brightness Control

.brightness(brightness: float)  # Relative brightness change
.absolute_brightness(brightness: float)  # Absolute brightness value

Adjust the color brightness: - brightness(): Values < 0.5 darken, > 0.5 lighten - absolute_brightness(): Set exact brightness (0 = black, 1 = white)

Examples

# Create a color
blue = ColorClass("#0000FF")

# Get variants
dark_blue = blue.dark
light_blue = blue.light

# Modify opacity
semi_transparent = blue.opacity(0.5)
semi_transparent_on_black = blue.opacity(0.5, background_color=(0, 0, 0))

# Adjust brightness
darker = blue.brightness(0.3)
specific_brightness = blue.absolute_brightness(0.7)

# Get color values
rgb = blue.rgb        # (0, 0, 1)
rgba = blue.rgba      # (0, 0, 1, 1)
hex_color = blue.hex  # "#0000FF"

bycolors.color_class.ColorClass

Bases: tuple

A class representing a color with various manipulation capabilities.

The ColorClass extends tuple to represent colors in RGB or RGBA format while providing methods for color manipulation like brightness adjustment, opacity changes, and color variant access (dark/light).

Parameters:

Name	Type	Description	Default
palette	_PALETTE_TYPE | str | tuple[int, int, int] | tuple[int, int, int, int] | None	The color value, can be a hex string, RGB/RGBA tuple, or a palette dictionary with 'main', 'dark', and 'light' variants.	None
background_color	_RGB_TYPE | None	The background color used for alpha compositing. Defaults to white (1, 1, 1).	None

Examples:

>>> blue = ColorClass("#0000FF")
>>> semi_transparent = blue.opacity(0.5)
>>> darker_blue = blue.brightness(0.35)
>>> rgb_values = blue.rgb  # (0, 0, 1)

Source code in python/bycolors/color_class.py

class ColorClass(tuple):
    """A class representing a color with various manipulation capabilities.

    The ColorClass extends tuple to represent colors in RGB or RGBA format while providing
    methods for color manipulation like brightness adjustment, opacity changes, and color
    variant access (dark/light).

    Args:
        palette (_PALETTE_TYPE | str | tuple[int, int, int] | tuple[int, int, int, int] | None):
            The color value, can be a hex string, RGB/RGBA tuple, or a palette dictionary
            with 'main', 'dark', and 'light' variants.
        background_color (_RGB_TYPE | None): The background color used for alpha compositing.
            Defaults to white (1, 1, 1).

    Examples:
        >>> blue = ColorClass("#0000FF")
        >>> semi_transparent = blue.opacity(0.5)
        >>> darker_blue = blue.brightness(0.35)
        >>> rgb_values = blue.rgb  # (0, 0, 1)
    """

    def __new__(cls, palette: _POSSIBLE_COLOR_INIT_TYPES | None = None, **kwargs):
        main_color = convert_to_rgb(palette)
        return super().__new__(cls, main_color)

    def __init__(
        self,
        palette: _POSSIBLE_COLOR_INIT_TYPES | None = None,
        background_color: _RGB_TYPE | None = None,
    ):
        self.palette = convert_to_palette(palette)
        self.main_color = self.palette["main"]
        self._background_color = (
            convert_to_rgb(background_color) if background_color else (1, 1, 1)
        )

    @property
    def dark(self):
        """Returns a darker variant of the color.

        If a dark variant is defined in the palette, returns that.
        Otherwise, returns a color with 35% brightness of the original.

        Returns:
            ColorClass: A new color instance with darker values.
        """
        if "dark" in self.palette:
            return self._new_color(self.palette["dark"])
        else:
            return self.brightness(0.35)

    @property
    def light(self):
        """Returns a lighter variant of the color.

        If a light variant is defined in the palette, returns that.
        Otherwise, returns a color with 65% brightness of the original.

        Returns:
            ColorClass: A new color instance with lighter values.
        """
        if "light" in self.palette:
            return self._new_color(self.palette["light"])
        else:
            return self.brightness(0.65)

    @property
    def main(self):
        """Returns the main color instance.

        Returns:
            ColorClass: The current color instance.
        """
        return self

    @property
    def hex(self):
        """Returns the color in hexadecimal format.

        Returns:
            str: Color in hex format (e.g., "#FF0000" for red).
        """
        return rgb_to_hex(self.rgb)

    @property
    def rgba(self):
        """Returns the color as RGBA values.

        Returns:
            tuple[float, float, float, float]: Color as RGBA values between 0 and 1.
        """
        return rgb_to_rgba(self.main_color)

    @property
    def rgb(self):
        """Returns the color as RGB values, handling alpha compositing if needed.

        If the color has alpha < 1, performs alpha compositing with the background color.

        Returns:
            tuple[float, float, float]: Color as RGB values between 0 and 1.
        """
        if len(self.main_color) > 3 and self.main_color[3] < 1.0:
            alpha = self.main_color[3]
            rgb = self.main_color[:3]
            return tuple(
                c * alpha + (1 - alpha) * self._background_color[i]
                for i, c in enumerate(rgb)
            )
        return self.main_color[:3]

    def alpha(self, alpha: float, background_color: _RGB_TYPE | None = None):
        """Alias for opacity method.

        Args:
            alpha (float): Alpha value between 0 and 1.
            background_color (_RGB_TYPE | None): Optional background color for compositing.

        Returns:
            ColorClass: New color instance with modified alpha.
        """
        return self.opacity(alpha, background_color)

    def opacity(self, opacity: float, background_color: _RGB_TYPE | None = None):
        """Creates a new color with modified opacity.

        Args:
            opacity (float): Opacity value between 0 and 1.
            background_color (_RGB_TYPE | None): Optional background color for compositing.

        Returns:
            ColorClass: New color instance with modified opacity.
        """
        return self._new_color(
            change_alpha(self.main_color, opacity), background_color=background_color
        )

    def brightness(self, brightness: float):
        """Changes the brightness of the color relatively.

        Args:
            brightness (float): Target brightness between 0 and 1.
                Values < 0.5 darken the color, values > 0.5 lighten it.

        Returns:
            ColorClass: New color instance with modified brightness.
        """
        return self._new_color(
            change_brightness_relatively(self.main_color, brightness)
        )

    def absolute_brightness(self, brightness: float):
        """Changes the brightness of the color to an absolute value.

        Args:
            brightness (float): Target brightness between 0 and 1.
                0 is black, 1 is white.

        Returns:
            ColorClass: New color instance with modified brightness.
        """
        return self._new_color(
            change_brightness_absolutely(self.main_color, brightness)
        )

    @property
    def transparent(self):
        """Returns a fully transparent version of the color.

        Returns:
            ColorClass: New color instance with zero opacity.
        """
        return self._new_color(change_alpha(self.main_color, 0))

    def _new_color(self, color: _RGB_TYPE, background_color: _RGB_TYPE | None = None):
        """Creates a new color instance with the same configuration.

        Args:
            color (_RGB_TYPE): The new color values.
            background_color (_RGB_TYPE | None): Optional background color for compositing.

        Returns:
            ColorClass: New color instance.
        """
        if background_color is None:
            background_color = self._background_color
        return self.__class__(color, background_color=background_color)

dark property

dark

Returns a darker variant of the color.

If a dark variant is defined in the palette, returns that. Otherwise, returns a color with 35% brightness of the original.

Returns:

Name	Type	Description
ColorClass		A new color instance with darker values.

hex property

hex

Returns the color in hexadecimal format.

Returns:

Name	Type	Description
str		Color in hex format (e.g., "#FF0000" for red).

light property

light

Returns a lighter variant of the color.

If a light variant is defined in the palette, returns that. Otherwise, returns a color with 65% brightness of the original.

Returns:

Name	Type	Description
ColorClass		A new color instance with lighter values.

main property

main

Returns the main color instance.

Returns:

Name	Type	Description
ColorClass		The current color instance.

rgb property

rgb

Returns the color as RGB values, handling alpha compositing if needed.

If the color has alpha < 1, performs alpha compositing with the background color.

Returns:

Type	Description
	tuple[float, float, float]: Color as RGB values between 0 and 1.

rgba property

rgba

Returns the color as RGBA values.

Returns:

Type	Description
	tuple[float, float, float, float]: Color as RGBA values between 0 and 1.

transparent property

transparent

Returns a fully transparent version of the color.

Returns:

Name	Type	Description
ColorClass		New color instance with zero opacity.

absolute_brightness

absolute_brightness(brightness)

Changes the brightness of the color to an absolute value.

Parameters:

Name	Type	Description	Default
brightness	float	Target brightness between 0 and 1. 0 is black, 1 is white.	required

Returns:

Name	Type	Description
ColorClass		New color instance with modified brightness.

Source code in python/bycolors/color_class.py

def absolute_brightness(self, brightness: float):
    """Changes the brightness of the color to an absolute value.

    Args:
        brightness (float): Target brightness between 0 and 1.
            0 is black, 1 is white.

    Returns:
        ColorClass: New color instance with modified brightness.
    """
    return self._new_color(
        change_brightness_absolutely(self.main_color, brightness)
    )

alpha

alpha(alpha, background_color=None)

Alias for opacity method.

Parameters:

Name	Type	Description	Default
alpha	float	Alpha value between 0 and 1.	required
background_color	_RGB_TYPE | None	Optional background color for compositing.	None

Returns:

Name	Type	Description
ColorClass		New color instance with modified alpha.

Source code in python/bycolors/color_class.py

def alpha(self, alpha: float, background_color: _RGB_TYPE | None = None):
    """Alias for opacity method.

    Args:
        alpha (float): Alpha value between 0 and 1.
        background_color (_RGB_TYPE | None): Optional background color for compositing.

    Returns:
        ColorClass: New color instance with modified alpha.
    """
    return self.opacity(alpha, background_color)

brightness

brightness(brightness)

Changes the brightness of the color relatively.

Parameters:

Name	Type	Description	Default
brightness	float	Target brightness between 0 and 1. Values < 0.5 darken the color, values > 0.5 lighten it.	required

Returns:

Name	Type	Description
ColorClass		New color instance with modified brightness.

Source code in python/bycolors/color_class.py

def brightness(self, brightness: float):
    """Changes the brightness of the color relatively.

    Args:
        brightness (float): Target brightness between 0 and 1.
            Values < 0.5 darken the color, values > 0.5 lighten it.

    Returns:
        ColorClass: New color instance with modified brightness.
    """
    return self._new_color(
        change_brightness_relatively(self.main_color, brightness)
    )

opacity

opacity(opacity, background_color=None)

Creates a new color with modified opacity.

Parameters:

Name	Type	Description	Default
opacity	float	Opacity value between 0 and 1.	required
background_color	_RGB_TYPE | None	Optional background color for compositing.	None

Returns:

Name	Type	Description
ColorClass		New color instance with modified opacity.

Source code in python/bycolors/color_class.py

def opacity(self, opacity: float, background_color: _RGB_TYPE | None = None):
    """Creates a new color with modified opacity.

    Args:
        opacity (float): Opacity value between 0 and 1.
        background_color (_RGB_TYPE | None): Optional background color for compositing.

    Returns:
        ColorClass: New color instance with modified opacity.
    """
    return self._new_color(
        change_alpha(self.main_color, opacity), background_color=background_color
    )