Skip to content

ColorPair

Module: terminaltexteffects.utils.graphics

Basic Usage

ColorPair objects are immutable foreground/background color pairs. The canonical fields are fg and bg; either field may be None to leave that channel unset.

Usage

import terminaltexteffects as tte

color_pair = tte.ColorPair(fg=tte.Color("#FF0000"), bg=tte.Color("#00FF00"))

Foreground-Only and Background-Only Pairs

import terminaltexteffects as tte

foreground_only = tte.ColorPair(fg=tte.Color("#FF0000"))
background_only = tte.ColorPair(bg=tte.Color("#0000FF"))

assert foreground_only.bg is None
assert background_only.fg is None

Automatic Color Conversion

Colors can be specified using strings or integers. Color objects will be created automatically.

import terminaltexteffects as tte

foreground_only = tte.ColorPair(fg="#FF0000")
background_only = tte.ColorPair(bg=21)
color_pair = tte.ColorPair("#FF0000", "#00FF00")

Strings and integers are converted to Color objects. Both arguments are optional and default to None; invalid color values raise the same ValueError as direct Color construction.

Printing ColorPairs

ColorPair objects can be printed to see the resulting colors.

Printed ColorPair objects showing foreground and background colors

ColorPair Reference

Represents a pair of colors to specify a character's foreground and background colors.

fg and bg are the immutable fields. On init, Color instances are preserved, non-Color non-None values are converted to Color, and None values remain unset.

Attributes:

Name Type Description
fg Color | None

The foreground color. None if no foreground color is specified.
bg Color | None

The background color. None if no background color is specified.
Source code in terminaltexteffects/utils/graphics.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
@dataclass(frozen=True, init=False)
class ColorPair:
    """Represents a pair of colors to specify a character's foreground and background colors.

    `fg` and `bg` are the immutable fields. On init, `Color` instances are preserved, non-`Color` non-`None` values
    are converted to `Color`, and `None` values remain unset.

    Attributes:
        fg (Color | None): The foreground color. None if no foreground color is specified.
        bg (Color | None): The background color. None if no background color is specified.

    """

    fg: Color | None
    bg: Color | None
    __match_args__: typing.ClassVar[tuple[str, str]] = ("fg", "bg")

    def __init__(
        self,
        fg: Color | str | int | None = None,
        bg: Color | str | int | None = None,
    ) -> None:
        """Initialize and normalize the foreground and background values.

        `Color` instances are preserved, non-`Color` non-`None` values are converted to
        `Color`, and `None` values remain unset.
        """
        object.__setattr__(self, "fg", Color(fg) if fg is not None and not isinstance(fg, Color) else fg)
        object.__setattr__(self, "bg", Color(bg) if bg is not None and not isinstance(bg, Color) else bg)

    def __str__(self) -> str:
        """Return a string representation of the ColorPair object."""
        color_block = (
            f"{colorterm.fg(self.fg.rgb_color) if self.fg else ''}"
            f"{colorterm.bg(self.bg.rgb_color) if self.bg else ''}####{ansitools.reset_all()}"
        )
        return (
            f"Foreground Color Code: {self.fg.rgb_color if self.fg else ''}"
            f"{f' | Foreground XTerm Color: {self.fg.xterm_color}' if self.fg and self.fg.xterm_color is not None else ''}\n"  # noqa: E501
            f"Background Color Code: {self.bg.rgb_color if self.bg else ''}"
            f"{f' | Background XTerm Color: {self.bg.xterm_color}' if self.bg and self.bg.xterm_color is not None else ''}"  # noqa: E501
            f"\nColor Appearance: {color_block}"
        )

__init__(fg=None, bg=None)

Initialize and normalize the foreground and background values.

Color instances are preserved, non-Color non-None values are converted to Color, and None values remain unset.

Source code in terminaltexteffects/utils/graphics.py 
157
158
159
160
161
162
163
164
165
166
167
168
def __init__(
    self,
    fg: Color | str | int | None = None,
    bg: Color | str | int | None = None,
) -> None:
    """Initialize and normalize the foreground and background values.

    `Color` instances are preserved, non-`Color` non-`None` values are converted to
    `Color`, and `None` values remain unset.
    """
    object.__setattr__(self, "fg", Color(fg) if fg is not None and not isinstance(fg, Color) else fg)
    object.__setattr__(self, "bg", Color(bg) if bg is not None and not isinstance(bg, Color) else bg)

__str__()

Return a string representation of the ColorPair object.

Source code in terminaltexteffects/utils/graphics.py 
170
171
172
173
174
175
176
177
178
179
180
181
182
def __str__(self) -> str:
    """Return a string representation of the ColorPair object."""
    color_block = (
        f"{colorterm.fg(self.fg.rgb_color) if self.fg else ''}"
        f"{colorterm.bg(self.bg.rgb_color) if self.bg else ''}####{ansitools.reset_all()}"
    )
    return (
        f"Foreground Color Code: {self.fg.rgb_color if self.fg else ''}"
        f"{f' | Foreground XTerm Color: {self.fg.xterm_color}' if self.fg and self.fg.xterm_color is not None else ''}\n"  # noqa: E501
        f"Background Color Code: {self.bg.rgb_color if self.bg else ''}"
        f"{f' | Background XTerm Color: {self.bg.xterm_color}' if self.bg and self.bg.xterm_color is not None else ''}"  # noqa: E501
        f"\nColor Appearance: {color_block}"
    )