Skip to content

formatters

Color formatting utilities for terminal output with auto-detection.

_colorize(text, color)

Apply color to text if colors are enabled.

Parameters:

Name Type Description Default
text str

Text to colorize

 required
color str

ANSI color code

 required

Returns:

Type Description
str

Colorized text if colors enabled, otherwise plain text
Source code in src/sparkwheel/errors/formatters.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
def _colorize(text: str, color: str) -> str:
    """Apply color to text if colors are enabled.

    Args:
        text: Text to colorize
        color: ANSI color code

    Returns:
        Colorized text if colors enabled, otherwise plain text
    """
    if _get_colors_enabled():
        return f"{color}{text}{RESET}"
    return text

_get_colors_enabled()

Get current color enable status, initializing if needed.

Source code in src/sparkwheel/errors/formatters.py 
 94
 95
 96
 97
 98
 99
100
101
def _get_colors_enabled() -> bool:
    """Get current color enable status, initializing if needed."""
    global _COLORS_ENABLED

    if _COLORS_ENABLED is None:
        enable_colors()  # Auto-detect

    return _COLORS_ENABLED  # type: ignore[return-value]

_supports_color()

Auto-detect if the terminal supports colors.

Follows industry standards for color detection: 1. NO_COLOR environment variable disables colors (https://no-color.org/) 2. SPARKWHEEL_NO_COLOR environment variable disables colors (sparkwheel-specific) 3. FORCE_COLOR environment variable enables colors (https://force-color.org/) 4. stdout TTY detection (auto-detect) 5. Default: disable colors

Returns:

Type Description
bool

True if colors should be enabled, False otherwise
Source code in src/sparkwheel/errors/formatters.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def _supports_color() -> bool:
    """Auto-detect if the terminal supports colors.

    Follows industry standards for color detection:
    1. NO_COLOR environment variable disables colors (https://no-color.org/)
    2. SPARKWHEEL_NO_COLOR environment variable disables colors (sparkwheel-specific)
    3. FORCE_COLOR environment variable enables colors (https://force-color.org/)
    4. stdout TTY detection (auto-detect)
    5. Default: disable colors

    Returns:
        True if colors should be enabled, False otherwise
    """
    # Check NO_COLOR environment variable (https://no-color.org/)
    # Highest priority - explicit user preference to disable
    if os.environ.get("NO_COLOR"):
        return False

    # Check sparkwheel-specific disable flag
    if os.environ.get("SPARKWHEEL_NO_COLOR"):
        return False

    # Check FORCE_COLOR environment variable (https://force-color.org/)
    # Explicit enable for CI environments, piping, etc.
    if os.environ.get("FORCE_COLOR"):
        return True

    # Auto-detect: Check if stdout is a TTY
    if hasattr(sys.stdout, "isatty") and sys.stdout.isatty():
        return True

    # Default: disable colors
    return False

enable_colors(enabled=None)

Enable or disable color output.

Parameters:

Name Type Description Default
enabled bool | None

True to enable, False to disable, None for auto-detection

 None

Returns:

Type Description
bool

Current color enable status

Examples:

>>> enable_colors(False)  # Disable colors
False
>>> enable_colors(True)   # Force enable colors
True
>>> enable_colors()       # Auto-detect
True  # (if terminal supports it)
Source code in src/sparkwheel/errors/formatters.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
def enable_colors(enabled: bool | None = None) -> bool:
    """Enable or disable color output.

    Args:
        enabled: True to enable, False to disable, None for auto-detection

    Returns:
        Current color enable status

    Examples:
        >>> enable_colors(False)  # Disable colors
        False
        >>> enable_colors(True)   # Force enable colors
        True
        >>> enable_colors()       # Auto-detect
        True  # (if terminal supports it)
    """
    global _COLORS_ENABLED

    if enabled is None:
        _COLORS_ENABLED = _supports_color()
    else:
        _COLORS_ENABLED = enabled

    return _COLORS_ENABLED

format_bold(text)

Format text as bold.

Parameters:

Name Type Description Default
text str

Text to format

 required

Returns:

Type Description
str

Formatted text
Source code in src/sparkwheel/errors/formatters.py 
185
186
187
188
189
190
191
192
193
194
195
196
def format_bold(text: str) -> str:
    """Format text as bold.

    Args:
        text: Text to format

    Returns:
        Formatted text
    """
    if _get_colors_enabled():
        return f"{BOLD}{text}{RESET}"
    return text

format_code(text)

Format text as code/metadata (blue).

Parameters:

Name Type Description Default
text str

Text to format

 required

Returns:

Type Description
str

Formatted text
Source code in src/sparkwheel/errors/formatters.py 
161
162
163
164
165
166
167
168
169
170
def format_code(text: str) -> str:
    """Format text as code/metadata (blue).

    Args:
        text: Text to format

    Returns:
        Formatted text
    """
    return _colorize(text, BLUE)

format_context(text)

Format text as context (gray).

Parameters:

Name Type Description Default
text str

Text to format

 required

Returns:

Type Description
str

Formatted text
Source code in src/sparkwheel/errors/formatters.py 
173
174
175
176
177
178
179
180
181
182
def format_context(text: str) -> str:
    """Format text as context (gray).

    Args:
        text: Text to format

    Returns:
        Formatted text
    """
    return _colorize(text, GRAY)

format_error(text)

Format text as an error (red).

Parameters:

Name Type Description Default
text str

Text to format

 required

Returns:

Type Description
str

Formatted text

Examples:

>>> format_error("Error message")
'Error message'  # With colors enabled
>>> format_error("Error message")
'Error message'  # With colors disabled
Source code in src/sparkwheel/errors/formatters.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def format_error(text: str) -> str:
    """Format text as an error (red).

    Args:
        text: Text to format

    Returns:
        Formatted text

    Examples:
        >>> format_error("Error message")
        '\x1b[31mError message\x1b[0m'  # With colors enabled
        >>> format_error("Error message")
        'Error message'  # With colors disabled
    """
    return _colorize(text, RED)

format_success(text)

Format text as success/correct (green).

Parameters:

Name Type Description Default
text str

Text to format

 required

Returns:

Type Description
str

Formatted text
Source code in src/sparkwheel/errors/formatters.py 
149
150
151
152
153
154
155
156
157
158
def format_success(text: str) -> str:
    """Format text as success/correct (green).

    Args:
        text: Text to format

    Returns:
        Formatted text
    """
    return _colorize(text, GREEN)

format_suggestion(text)

Format text as a suggestion (yellow).

Parameters:

Name Type Description Default
text str

Text to format

 required

Returns:

Type Description
str

Formatted text
Source code in src/sparkwheel/errors/formatters.py 
137
138
139
140
141
142
143
144
145
146
def format_suggestion(text: str) -> str:
    """Format text as a suggestion (yellow).

    Args:
        text: Text to format

    Returns:
        Formatted text
    """
    return _colorize(text, YELLOW)