0
# ANSI Styling
1

2
Cross-platform ANSI color and style formatting for terminal output with Windows console support, automatic TTY detection, and comprehensive style options. Provides both formatting functions for styled strings and direct printing with style application.
3

4
## Capabilities
5

6
### String Formatting with Styles
7

8
Format text with ANSI escape sequences for color and styling without printing.
9

10
```python { .api }
11
def sformat(input, *styles, reset=True, apply=True) -> str:
12
    """
13
    Format text with ANSI styles and return styled string.
14
    
15
    Parameters:
16
    - input: Text or object to style (converted to string)
17
    - *styles: Style codes to apply (Style enum values, ints, or strings)
18
    - reset: Append ANSI reset code at end (default: True)
19
    - apply: Apply styling (False returns original text, default: True)
20
    
21
    Returns:
22
    String with ANSI escape sequences for styling
23
    """
24
```
25

26
Usage examples:
27

28
```python
29
from devtools import sformat
30

31
# Basic color formatting
32
red_text = sformat("Error message", sformat.red)
33
print(red_text)  # Prints in red
34

35
# Multiple styles
36
bold_blue = sformat("Important", sformat.bold, sformat.blue)
37
print(bold_blue)  # Prints in bold blue
38

39
# Background colors
40
highlighted = sformat("Warning", sformat.yellow, sformat.bg_red)
41
print(highlighted)  # Yellow text on red background
42

43
# Conditional styling
44
def format_status(status, is_error=False):
45
    if is_error:
46
        return sformat(status, sformat.red, sformat.bold)
47
    else:
48
        return sformat(status, sformat.green)
49

50
print(format_status("Success", False))  # Green
51
print(format_status("Failed", True))    # Bold red
52

53
# No reset (for chaining styles)
54
partial = sformat("Start", sformat.bold, reset=False)
55
complete = partial + sformat(" End", sformat.italic)
56
print(complete)  # "Start" in bold, " End" in bold italic
57
```
58

59
### Direct Styled Printing
60

61
Print text with ANSI styling directly to output stream.
62

63
```python { .api }
64
def sprint(input, *styles, reset=True, flush=True, file=None, **print_kwargs) -> None:
65
    """
66
    Print text with ANSI styling, with automatic TTY detection.
67
    
68
    Parameters:
69
    - input: Text to print
70
    - *styles: Style codes to apply
71
    - reset: Append ANSI reset code (default: True)
72
    - flush: Flush output buffer (default: True)
73
    - file: Output file (default: stdout)
74
    - **print_kwargs: Additional arguments passed to print()
75
    """
76
```
77

78
Usage examples:
79

80
```python
81
from devtools import sprint
82

83
# Basic colored printing
84
sprint("Success!", sprint.green)
85
sprint("Warning", sprint.yellow, sprint.bold)
86
sprint("Error occurred", sprint.red, sprint.bg_white)
87

88
# Print to file
89
with open('log.txt', 'w') as f:
90
    sprint("Log entry", sprint.blue, file=f)
91

92
# Custom print arguments
93
sprint("Multiple", "arguments", sprint.cyan, sep=' | ', end='\n\n')
94

95
# Conditional styling based on TTY
96
import sys
97
if sys.stdout.isatty():
98
    sprint("Terminal output", sprint.green)
99
else:
100
    sprint("File output")  # No styling applied to files
101
```
102

103
### Style Enumeration
104

105
Comprehensive enumeration of ANSI style codes with both individual values and a callable interface.
106

107
```python { .api }
108
class Style(IntEnum):
109
    """
110
    ANSI style codes enum with styling function capability.
111
    """
112
    # Reset and text styles
113
    reset = 0
114
    bold = 1
115
    not_bold = 22
116
    dim = 2
117
    not_dim = 22
118
    italic = 3
119
    not_italic = 23
120
    underline = 4
121
    not_underline = 24
122
    blink = 5
123
    not_blink = 25
124
    reverse = 7
125
    not_reverse = 27
126
    strike_through = 9
127
    not_strike_through = 29
128
    
129
    # Foreground colors
130
    black = 30
131
    red = 31
132
    green = 32
133
    yellow = 33
134
    blue = 34
135
    magenta = 35
136
    cyan = 36
137
    white = 37
138
    
139
    # Background colors
140
    bg_black = 40
141
    bg_red = 41
142
    bg_green = 42
143
    bg_yellow = 43
144
    bg_blue = 44
145
    bg_magenta = 45
146
    bg_cyan = 46
147
    bg_white = 47
148
    
149
    def __call__(self, input, *styles, reset=True, apply=True) -> str:
150
        """
151
        Apply ANSI styles to text (same as sformat function).
152
        
153
        Parameters:
154
        - input: Text to style
155
        - *styles: Additional styles to apply
156
        - reset: Append reset code (default: True)
157
        - apply: Apply styling (default: True)
158
        
159
        Returns:
160
        Styled text string
161
        """
162
    
163
    @property
164
    def styles(self) -> dict[str, Style]:
165
        """
166
        Get mapping of style names to Style enum values.
167
        
168
        Returns:
169
        Dictionary mapping style names to Style values
170
        """
171
```
172

173
Usage examples:
174

175
```python
176
from devtools import sformat
177

178
# Using Style enum values directly
179
red_bold = sformat("Alert", sformat.red, sformat.bold)
180

181
# Using string names (looked up in styles property)
182
yellow_text = sformat("Warning", "yellow", "underline")
183

184
# Combining foreground and background
185
contrast = sformat("High Contrast", sformat.white, sformat.bg_black)
186

187
# Text decorations
188
fancy_text = sformat("Fancy", sformat.italic, sformat.underline, sformat.cyan)
189

190
# Dim/bright variations
191
subtle = sformat("Subtle text", sformat.dim)
192
prominent = sformat("Prominent text", sformat.bold)
193

194
# Reverse video (swap foreground/background)
195
reversed_text = sformat("Reversed", sformat.reverse)
196
```
197

198
### Cross-Platform Support
199

200
Automatic handling of Windows console ANSI support and TTY detection.
201

202
```python
203
from devtools import sformat, sprint
204

205
# Automatic Windows ANSI activation
206
# On Windows 10+, ANSI codes are automatically enabled
207
# On older Windows, gracefully falls back to plain text
208

209
# TTY detection for appropriate styling
210
sprint("This will be colored in terminal", sformat.green)
211
# When redirected to file: no ANSI codes added
212
# python script.py > output.txt  # output.txt contains plain text
213

214
# Force styling regardless of TTY
215
forced_color = sformat("Always colored", sformat.blue, apply=True)
216

217
# Disable styling regardless of TTY  
218
plain_text = sformat("Never colored", sformat.red, apply=False)
219
```
220

221
### Advanced Styling Patterns
222

223
Complex styling scenarios and best practices.
224

225
```python
226
from devtools import sformat
227

228
# Nested styling with manual reset control
229
def format_log_level(level, message):
230
    level_styles = {
231
        'DEBUG': [sformat.dim],
232
        'INFO': [sformat.blue],
233
        'WARNING': [sformat.yellow, sformat.bold],
234
        'ERROR': [sformat.red, sformat.bold],
235
        'CRITICAL': [sformat.white, sformat.bg_red, sformat.bold]
236
    }
237
    
238
    if level in level_styles:
239
        styled_level = sformat(f"[{level}]", *level_styles[level])
240
        return f"{styled_level} {message}"
241
    return f"[{level}] {message}"
242

243
# Progress indicators with colors
244
def format_progress(current, total):
245
    percentage = (current / total) * 100
246
    bar_length = 20
247
    filled = int(bar_length * current / total)
248
    
249
    bar = sformat('█' * filled, sformat.green) + \
250
          sformat('░' * (bar_length - filled), sformat.dim)
251
    
252
    return f"{bar} {percentage:6.1f}%"
253

254
# Status indicators
255
def format_status(success_count, error_count):
256
    success = sformat(f"✓ {success_count}", sformat.green)
257
    errors = sformat(f"✗ {error_count}", sformat.red) if error_count > 0 else ""
258
    return f"{success} {errors}".strip()
259

260
# Table formatting with alternating row colors
261
def format_table_row(items, row_num):
262
    style = sformat.dim if row_num % 2 == 0 else None
263
    formatted_items = []
264
    
265
    for item in items:
266
        if style:
267
            formatted_items.append(sformat(str(item), style))
268
        else:
269
            formatted_items.append(str(item))
270
    
271
    return " | ".join(formatted_items)
272
```
273

274
### Environment Integration
275

276
Integration with environment variables and terminal capabilities.
277

278
```python
279
import os
280
from devtools import sformat
281

282
# Respect NO_COLOR environment variable
283
def smart_format(text, *styles):
284
    if os.environ.get('NO_COLOR'):
285
        return text
286
    return sformat(text, *styles)
287

288
# Custom color schemes based on terminal
289
def get_theme_color(color_name):
290
    # Adapt colors based on terminal background
291
    dark_theme = {
292
        'primary': sformat.cyan,
293
        'secondary': sformat.yellow,
294
        'success': sformat.green,
295
        'error': sformat.red
296
    }
297
    return dark_theme.get(color_name, sformat.white)
298

299
# Terminal capability detection
300
import sys
301
def supports_color():
302
    """Check if terminal supports color output."""
303
    return (
304
        hasattr(sys.stdout, 'isatty') and 
305
        sys.stdout.isatty() and 
306
        os.environ.get('TERM') != 'dumb'
307
    )
308
```
309

310
## Types
311

312
```python { .api }
313
# Style function instances
314
sformat: Style  # Main formatting function (Style(-1) instance)
315
sprint: StylePrint  # Main printing function
316

317
class StylePrint:
318
    """
319
    Print function with ANSI styling support.
320
    """
321
    def __call__(self, input, *styles, reset=True, flush=True, file=None, **print_kwargs) -> None: ...
322
    def __getattr__(self, item: str) -> str: ...
323
    def __repr__(self) -> str: ...
324

325
# Internal utility functions
326
def _style_as_int(v: Style | int) -> str: ...
327
def _as_ansi(s: str) -> str: ...
328
```