ColorPair API Reference

Complete reference for the ColorPair class.

Overview

ColorPair fixes a single text/background color pair. Use this when you have one color to fix.

For many colors, use Bulk Processing API Reference instead.

Creating a ColorPair

class ColorPair(text_color, bg_color, large_text=False)

Create a color pair to check or fix.

Parameters:

  • text_color – Text (foreground) color. Accepts hex ("#rrggbb"), RGB tuple ((r, g, b)), or CSS name ("red").

  • bg_color – Background color. Same formats as text_color.

  • large_text – Set to True if text is large (24px+ or 19px+ bold). Default is False.

Examples:

from cm_colors import ColorPair

# Hex colors
pair = ColorPair("#777777", "#ffffff")

# RGB tuples
pair = ColorPair((119, 119, 119), (255, 255, 255))

# CSS names
pair = ColorPair("gray", "white")

# Large text (headings, buttons)
pair = ColorPair("#888888", "#ffffff", large_text=True)

Methods

make_readable()

ColorPair.make_readable(mode=1, very_readable=False, show=False, save_report=False)

Fix the text color to make it readable.

Parameters:

  • mode (int) – How strict to be about changes. 0``=Strict (minimal changes), ``1``=Default (balanced), ``2``=Relaxed (prioritize readability). Default is ``1.

  • very_readable (bool) – If True, aim for very readable colors. Default is False.

  • show (bool) – If True, print a before/after preview to console. Default is False.

  • save_report (bool) – If True, generate HTML report (cm_colors_quick_report.html). Default is False.

Returns:

Tuple of (fixed_color, success)

Return type:

tuple

Return values:

  • fixed_color: The readable color in same format as input (hex stays hex, tuple stays tuple)

  • success: True if color is now readable, False otherwise

Examples:

from cm_colors import ColorPair

# Basic usage
pair = ColorPair("#777777", "#ffffff")
fixed, success = pair.make_readable()
# fixed = '#757575', success = True

# Strict mode (minimal changes)
fixed, success = pair.make_readable(mode=0)

# Very readable colors
fixed, success = pair.make_readable(very_readable=True)

# Show preview in console
fixed, success = pair.make_readable(show=True)

# Generate HTML report
fixed, success = pair.make_readable(save_report=True)

Properties

is_readable

ColorPair.is_readable

Check if text is readable on background without fixing.

Returns:

"Very Readable", "Readable", or "Not Readable"

Return type:

str

Example:

from cm_colors import ColorPair

pair = ColorPair("#000000", "#ffffff")
print(pair.is_readable)  # "Very Readable"

pair2 = ColorPair("#cccccc", "#ffffff")
print(pair2.is_readable)  # "Not Readable"

# Use in conditional
if pair.is_readable == "Not Readable":
    fixed, success = pair.make_readable()

is_valid

ColorPair.is_valid

Check if both colors are valid.

Returns:

True if both colors parse correctly, False otherwise

Return type:

bool

Example:

from cm_colors import ColorPair

pair = ColorPair("#777777", "#ffffff")
print(pair.is_valid)  # True

bad_pair = ColorPair("notacolor", "#ffffff")
print(bad_pair.is_valid)  # False

text and bg

ColorPair.text
ColorPair.bg

Access the individual colors as Color objects.

Example:

from cm_colors import ColorPair

pair = ColorPair("#777777", "#ffffff")

# Get hex
print(pair.text.to_hex())  # '#777777'
print(pair.bg.to_hex())    # '#ffffff'

# Get RGB
print(pair.text.rgb)  # (119, 119, 119)
print(pair.bg.rgb)    # (255, 255, 255)

Complete example

from cm_colors import ColorPair

# Check readability first
pair = ColorPair("#999999", "#ffffff")

print(f"Readable? {pair.is_readable}")  # "Not Readable"

if pair.is_readable != "Very Readable":
    # Fix the color
    fixed, success = pair.make_readable(
        mode=1,              # Balanced approach
        very_readable=True,  # Extra readable
        save_report=True     # Generate report
    )

    if success:
        print(f"Use {fixed} instead of #999999")
    else:
        print("Could not fix - too different from original")

See also