0
# Crayons
1

2
Simple and elegant wrapper for colorama providing terminal text coloring functionality. Crayons automatically handles foreground color application and state restoration, eliminating manual color management typically required with terminal color libraries.
3

4
## Package Information
5

6
- **Package Name**: crayons
7
- **Language**: Python
8
- **Installation**: `pip install crayons`
9
- **Dependencies**: colorama
10

11
## Core Imports
12

13
```python
14
import crayons
15
```
16

17
Individual color functions and utilities:
18

19
```python
20
from crayons import red, green, blue, yellow, magenta, cyan, white, black, normal
21
from crayons import clean, disable, enable, random, replace_colors, reset_replace_colors
22
from crayons import ColoredString
23
```
24

25
Or import all:
26

27
```python
28
from crayons import *
29
```
30

31
## Basic Usage
32

33
```python
34
import crayons
35

36
# Basic colored text
37
print(crayons.red('This text is red'))
38
print(crayons.green('This text is green'))
39
print(crayons.blue('This text is blue'))
40

41
# Bold text
42
print(crayons.yellow('Bold yellow text', bold=True))
43

44
# Force color output even when piped
45
print(crayons.magenta('Always colored', always=True))
46

47
# Mix colors in output
48
print('{} and {} text'.format(crayons.red('red'), crayons.blue('blue')))
49

50
# Random colors
51
print(crayons.random('This text has a random color'))
52

53
# Global control
54
crayons.disable()  # Turn off all colors
55
print(crayons.red('This will not be colored'))
56
crayons.enable()   # Turn colors back on
57

58
# Clean ANSI codes from strings
59
colored_text = crayons.red('colored')
60
clean_text = crayons.clean(str(colored_text))
61
print(clean_text)  # Prints without color codes
62
```
63

64
## Capabilities
65

66
### Color Functions
67

68
Eight standard color functions that create colored text strings. Each function accepts text and optional formatting parameters.
69

70
```python { .api }
71
def red(s, always=False, bold=False):
72
    """
73
    Create red colored text.
74
    
75
    Parameters:
76
    - s: str or any object convertible to string, text to color
77
    - always: bool, force color output even when not in TTY (default: False)  
78
    - bold: bool, make text bold (default: False)
79
    
80
    Returns:
81
    ColoredString object with red foreground color
82
    """
83

84
def green(s, always=False, bold=False):
85
    """
86
    Create green colored text.
87
    
88
    Parameters:
89
    - s: str or any object convertible to string, text to color
90
    - always: bool, force color output even when not in TTY (default: False)
91
    - bold: bool, make text bold (default: False)
92
    
93
    Returns:
94
    ColoredString object with green foreground color
95
    """
96

97
def yellow(s, always=False, bold=False):
98
    """
99
    Create yellow colored text.
100
    
101
    Parameters:
102
    - s: str or any object convertible to string, text to color
103
    - always: bool, force color output even when not in TTY (default: False)
104
    - bold: bool, make text bold (default: False)
105
    
106
    Returns:
107
    ColoredString object with yellow foreground color
108
    """
109

110
def blue(s, always=False, bold=False):
111
    """
112
    Create blue colored text.
113
    
114
    Parameters:
115
    - s: str or any object convertible to string, text to color
116
    - always: bool, force color output even when not in TTY (default: False)
117
    - bold: bool, make text bold (default: False)
118
    
119
    Returns:
120
    ColoredString object with blue foreground color
121
    """
122

123
def black(s, always=False, bold=False):
124
    """
125
    Create black colored text.
126
    
127
    Parameters:
128
    - s: str or any object convertible to string, text to color
129
    - always: bool, force color output even when not in TTY (default: False)
130
    - bold: bool, make text bold (default: False)
131
    
132
    Returns:
133
    ColoredString object with black foreground color
134
    """
135

136
def magenta(s, always=False, bold=False):
137
    """
138
    Create magenta colored text.
139
    
140
    Parameters:
141
    - s: str or any object convertible to string, text to color
142
    - always: bool, force color output even when not in TTY (default: False)
143
    - bold: bool, make text bold (default: False)
144
    
145
    Returns:
146
    ColoredString object with magenta foreground color
147
    """
148

149
def cyan(s, always=False, bold=False):
150
    """
151
    Create cyan colored text.
152
    
153
    Parameters:
154
    - s: str or any object convertible to string, text to color
155
    - always: bool, force color output even when not in TTY (default: False)
156
    - bold: bool, make text bold (default: False)
157
    
158
    Returns:
159
    ColoredString object with cyan foreground color
160
    """
161

162
def white(s, always=False, bold=False):
163
    """
164
    Create white colored text.
165
    
166
    Parameters:
167
    - s: str or any object convertible to string, text to color
168
    - always: bool, force color output even when not in TTY (default: False)
169
    - bold: bool, make text bold (default: False)
170
    
171
    Returns:
172
    ColoredString object with white foreground color
173
    """
174

175
def normal(s, always=False, bold=False):
176
    """
177
    Create text with normal/reset color (default terminal foreground color).
178
    
179
    Parameters:
180
    - s: str or any object convertible to string, text to color
181
    - always: bool, force color output even when not in TTY (default: False)
182
    - bold: bool, make text bold (default: False)
183
    
184
    Returns:
185
    ColoredString object with reset/normal foreground color
186
    """
187
```
188

189
### Utility Functions
190

191
Functions for controlling color behavior, cleaning ANSI codes, and selecting random colors.
192

193
```python { .api }
194
def clean(s):
195
    """
196
    Remove ANSI color codes from a string.
197
    
198
    Parameters:
199
    - s: str, string potentially containing ANSI color codes
200
    
201
    Returns:
202
    str with all ANSI escape sequences removed
203
    """
204

205
def random(string, always=False, bold=False, colors=COLORS):
206
    """
207
    Select a color at random from available colors.
208
    
209
    Parameters:
210
    - string: str or any object convertible to string, text to color
211
    - always: bool, force color output even when not in TTY (default: False)
212
    - bold: bool, make text bold (default: False)
213
    - colors: list of str, color names to choose from (default: all standard colors)
214
    
215
    Returns:
216
    ColoredString object with randomly selected color
217
    """
218

219
def disable():
220
    """
221
    Globally disable all color output. All color functions will return plain text.
222
    
223
    Returns:
224
    None
225
    """
226

227
def enable():
228
    """
229
    Globally enable color output (default state).
230
    
231
    Returns:
232
    None
233
    """
234

235
def replace_colors(replace_dict):
236
    """
237
    Replace color mappings with custom colors for background customization.
238
    
239
    Parameters:
240
    - replace_dict: dict, mapping of original color names to replacement color names
241
                   (e.g., {'magenta': 'blue', 'red': 'green'})
242
    
243
    Returns:
244
    None
245
    
246
    Raises:
247
    AssertionError: if replace_dict is not a dictionary
248
    """
249

250
def reset_replace_colors():
251
    """
252
    Reset any custom color mappings back to defaults.
253
    
254
    Returns:
255
    None
256
    """
257
```
258

259
### ColoredString Class
260

261
Enhanced string class that handles colored text output with proper length calculations and string operations.
262

263
```python { .api }
264
class ColoredString:
265
    """
266
    Enhanced string for colored output with proper __len__ operations.
267
    
268
    Supports all standard string methods while preserving color information.
269
    Automatically handles TTY detection and color output control.
270
    """
271
    
272
    def __init__(self, color, s, always_color=False, bold=False):
273
        """
274
        Initialize a colored string.
275
        
276
        Parameters:
277
        - color: str, color name (e.g., 'RED', 'GREEN', 'BLUE')
278
        - s: str or any object convertible to string, text content
279
        - always_color: bool, force color output even when not in TTY (default: False)
280
        - bold: bool, make text bold (default: False)
281
        """
282
    
283
    @property
284
    def color_str(self):
285
        """
286
        Get the colored string with ANSI codes or plain text based on TTY detection.
287
        
288
        Returns:
289
        str with ANSI color codes if in TTY and colors enabled, otherwise plain text
290
        """
291
    
292
    def __len__(self):
293
        """
294
        Return length of plain text content without ANSI codes.
295
        
296
        Returns:
297
        int, length of the underlying text string
298
        """
299
    
300
    def __unicode__(self):
301
        """
302
        Unicode string representation with color codes if appropriate.
303
        
304
        Returns:
305
        unicode string (Python 2) or str (Python 3) with color codes or plain text
306
        """
307
    
308
    def __str__(self):
309
        """
310
        String representation with color codes if appropriate.
311
        
312
        Returns:
313
        str, colored string or plain text based on output context
314
        """
315
    
316
    def __repr__(self):
317
        """
318
        Debug representation showing color and content.
319
        
320
        Returns:
321
        str in format "<COLOR-string: 'content'>"
322
        """
323
    
324
    def __add__(self, other):
325
        """
326
        Concatenate colored string with another string.
327
        
328
        Parameters:
329
        - other: str or any string-like object
330
        
331
        Returns:
332
        str, concatenated result
333
        """
334
    
335
    def __radd__(self, other):
336
        """
337
        Reverse concatenation (other + self).
338
        
339
        Parameters:
340
        - other: str or any string-like object
341
        
342
        Returns:
343
        str, concatenated result
344
        """
345
    
346
    def __mul__(self, other):
347
        """
348
        Repeat colored string multiple times.
349
        
350
        Parameters:
351
        - other: int, number of repetitions
352
        
353
        Returns:
354
        str, repeated colored string
355
        """
356
    
357
    def __iter__(self):
358
        """
359
        Iterate over characters in the colored string.
360
        
361
        Returns:
362
        iterator over characters in color_str
363
        """
364
    
365
    def __getattr__(self, name):
366
        """
367
        Delegate string methods to underlying string while preserving color.
368
        
369
        All standard string methods (split, replace, upper, lower, etc.) are available
370
        and return new ColoredString objects when the result is a string.
371
        
372
        Parameters:
373
        - name: str, name of the string method to call
374
        
375
        Returns:
376
        ColoredString for string results, original return type for non-string results
377
        """
378
```
379

380
## Constants
381

382
```python { .api }
383
COLORS = ('red', 'green', 'yellow', 'blue', 'black', 'magenta', 'cyan', 'white')
384
"""Tuple of available color names for use with random() function and color replacement."""
385
```
386

387
## Environment Variables
388

389
- **CLINT_FORCE_COLOR**: Forces color output even when not in TTY
390
- **TERM**: Colors are disabled when set to "dumb"
391

392
## Key Features
393

394
- **Automatic TTY Detection**: Colors automatically disabled when output is piped or redirected
395
- **iPython Compatibility**: Colors automatically disabled in iPython environments
396
- **Cross-platform Support**: Built on colorama for Windows, macOS, and Linux compatibility
397
- **Length Calculation**: ColoredString objects return correct length without ANSI codes
398
- **String Operations**: ColoredString supports concatenation, multiplication, and iteration
399
- **Global Control**: Enable/disable all colors globally with simple function calls
400
- **Color Customization**: Replace default colors with custom mappings for different backgrounds
401
- **Bold Text Support**: All color functions support bold text styling
402
- **Random Colors**: Built-in random color selection for dynamic applications
403
- **Python Compatibility**: Supports Python 2.7+ and 3.x
404

405
## Error Handling
406

407
The library is designed to be fault-tolerant:
408

409
- Non-string inputs are automatically converted to strings
410
- Invalid color names in replacement dictionaries are handled gracefully
411
- TTY detection failures fall back to no-color output
412
- Unicode handling works across Python 2 and 3