or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-crayons

Simple and elegant wrapper for colorama providing terminal text coloring functionality

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/crayons@0.4.x

To install, run

npx @tessl/cli install tessl/pypi-crayons@0.4.0

index.mddocs/

Crayons

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.

Package Information

  • Package Name: crayons
  • Language: Python
  • Installation: pip install crayons
  • Dependencies: colorama

Core Imports

import crayons

Individual color functions and utilities:

from crayons import red, green, blue, yellow, magenta, cyan, white, black, normal
from crayons import clean, disable, enable, random, replace_colors, reset_replace_colors
from crayons import ColoredString

Or import all:

from crayons import *

Basic Usage

import crayons

# Basic colored text
print(crayons.red('This text is red'))
print(crayons.green('This text is green'))
print(crayons.blue('This text is blue'))

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

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

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

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

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

# Clean ANSI codes from strings
colored_text = crayons.red('colored')
clean_text = crayons.clean(str(colored_text))
print(clean_text)  # Prints without color codes

Capabilities

Color Functions

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

def red(s, always=False, bold=False):
    """
    Create red colored text.
    
    Parameters:
    - s: str or any object convertible to string, text to color
    - always: bool, force color output even when not in TTY (default: False)  
    - bold: bool, make text bold (default: False)
    
    Returns:
    ColoredString object with red foreground color
    """

def green(s, always=False, bold=False):
    """
    Create green colored text.
    
    Parameters:
    - s: str or any object convertible to string, text to color
    - always: bool, force color output even when not in TTY (default: False)
    - bold: bool, make text bold (default: False)
    
    Returns:
    ColoredString object with green foreground color
    """

def yellow(s, always=False, bold=False):
    """
    Create yellow colored text.
    
    Parameters:
    - s: str or any object convertible to string, text to color
    - always: bool, force color output even when not in TTY (default: False)
    - bold: bool, make text bold (default: False)
    
    Returns:
    ColoredString object with yellow foreground color
    """

def blue(s, always=False, bold=False):
    """
    Create blue colored text.
    
    Parameters:
    - s: str or any object convertible to string, text to color
    - always: bool, force color output even when not in TTY (default: False)
    - bold: bool, make text bold (default: False)
    
    Returns:
    ColoredString object with blue foreground color
    """

def black(s, always=False, bold=False):
    """
    Create black colored text.
    
    Parameters:
    - s: str or any object convertible to string, text to color
    - always: bool, force color output even when not in TTY (default: False)
    - bold: bool, make text bold (default: False)
    
    Returns:
    ColoredString object with black foreground color
    """

def magenta(s, always=False, bold=False):
    """
    Create magenta colored text.
    
    Parameters:
    - s: str or any object convertible to string, text to color
    - always: bool, force color output even when not in TTY (default: False)
    - bold: bool, make text bold (default: False)
    
    Returns:
    ColoredString object with magenta foreground color
    """

def cyan(s, always=False, bold=False):
    """
    Create cyan colored text.
    
    Parameters:
    - s: str or any object convertible to string, text to color
    - always: bool, force color output even when not in TTY (default: False)
    - bold: bool, make text bold (default: False)
    
    Returns:
    ColoredString object with cyan foreground color
    """

def white(s, always=False, bold=False):
    """
    Create white colored text.
    
    Parameters:
    - s: str or any object convertible to string, text to color
    - always: bool, force color output even when not in TTY (default: False)
    - bold: bool, make text bold (default: False)
    
    Returns:
    ColoredString object with white foreground color
    """

def normal(s, always=False, bold=False):
    """
    Create text with normal/reset color (default terminal foreground color).
    
    Parameters:
    - s: str or any object convertible to string, text to color
    - always: bool, force color output even when not in TTY (default: False)
    - bold: bool, make text bold (default: False)
    
    Returns:
    ColoredString object with reset/normal foreground color
    """

Utility Functions

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

def clean(s):
    """
    Remove ANSI color codes from a string.
    
    Parameters:
    - s: str, string potentially containing ANSI color codes
    
    Returns:
    str with all ANSI escape sequences removed
    """

def random(string, always=False, bold=False, colors=COLORS):
    """
    Select a color at random from available colors.
    
    Parameters:
    - string: str or any object convertible to string, text to color
    - always: bool, force color output even when not in TTY (default: False)
    - bold: bool, make text bold (default: False)
    - colors: list of str, color names to choose from (default: all standard colors)
    
    Returns:
    ColoredString object with randomly selected color
    """

def disable():
    """
    Globally disable all color output. All color functions will return plain text.
    
    Returns:
    None
    """

def enable():
    """
    Globally enable color output (default state).
    
    Returns:
    None
    """

def replace_colors(replace_dict):
    """
    Replace color mappings with custom colors for background customization.
    
    Parameters:
    - replace_dict: dict, mapping of original color names to replacement color names
                   (e.g., {'magenta': 'blue', 'red': 'green'})
    
    Returns:
    None
    
    Raises:
    AssertionError: if replace_dict is not a dictionary
    """

def reset_replace_colors():
    """
    Reset any custom color mappings back to defaults.
    
    Returns:
    None
    """

ColoredString Class

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

class ColoredString:
    """
    Enhanced string for colored output with proper __len__ operations.
    
    Supports all standard string methods while preserving color information.
    Automatically handles TTY detection and color output control.
    """
    
    def __init__(self, color, s, always_color=False, bold=False):
        """
        Initialize a colored string.
        
        Parameters:
        - color: str, color name (e.g., 'RED', 'GREEN', 'BLUE')
        - s: str or any object convertible to string, text content
        - always_color: bool, force color output even when not in TTY (default: False)
        - bold: bool, make text bold (default: False)
        """
    
    @property
    def color_str(self):
        """
        Get the colored string with ANSI codes or plain text based on TTY detection.
        
        Returns:
        str with ANSI color codes if in TTY and colors enabled, otherwise plain text
        """
    
    def __len__(self):
        """
        Return length of plain text content without ANSI codes.
        
        Returns:
        int, length of the underlying text string
        """
    
    def __unicode__(self):
        """
        Unicode string representation with color codes if appropriate.
        
        Returns:
        unicode string (Python 2) or str (Python 3) with color codes or plain text
        """
    
    def __str__(self):
        """
        String representation with color codes if appropriate.
        
        Returns:
        str, colored string or plain text based on output context
        """
    
    def __repr__(self):
        """
        Debug representation showing color and content.
        
        Returns:
        str in format "<COLOR-string: 'content'>"
        """
    
    def __add__(self, other):
        """
        Concatenate colored string with another string.
        
        Parameters:
        - other: str or any string-like object
        
        Returns:
        str, concatenated result
        """
    
    def __radd__(self, other):
        """
        Reverse concatenation (other + self).
        
        Parameters:
        - other: str or any string-like object
        
        Returns:
        str, concatenated result
        """
    
    def __mul__(self, other):
        """
        Repeat colored string multiple times.
        
        Parameters:
        - other: int, number of repetitions
        
        Returns:
        str, repeated colored string
        """
    
    def __iter__(self):
        """
        Iterate over characters in the colored string.
        
        Returns:
        iterator over characters in color_str
        """
    
    def __getattr__(self, name):
        """
        Delegate string methods to underlying string while preserving color.
        
        All standard string methods (split, replace, upper, lower, etc.) are available
        and return new ColoredString objects when the result is a string.
        
        Parameters:
        - name: str, name of the string method to call
        
        Returns:
        ColoredString for string results, original return type for non-string results
        """

Constants

COLORS = ('red', 'green', 'yellow', 'blue', 'black', 'magenta', 'cyan', 'white')
"""Tuple of available color names for use with random() function and color replacement."""

Environment Variables

  • CLINT_FORCE_COLOR: Forces color output even when not in TTY
  • TERM: Colors are disabled when set to "dumb"

Key Features

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

Error Handling

The library is designed to be fault-tolerant:

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