DOCSEARCHbyAlgolia
Submit Docs

colorama

repository·master·Indexed 26 days ago

https://github.com/tartley/colorama

A cross-platform Python library that enables ANSI escape character sequences for colored terminal text and cursor positioning to work on MS Windows. It provides a simple API via Fore, Back, and Style for text formatting, and the Cursor class for terminal manipulation. The library includes utility functions like init(), deinit(), and just_fix_windows_console() to manage stream wrapping and Win32 API conversion.

Tokens
3.9K
Snippets
11
Records
34
Agent score
78%

What's inside colorama

  1. Colorama Overview

    master
    Colorama provides a cross-platform way to use ANSI escape sequences for colored terminal text and cursor positioning. On Unix and Mac, it does nothing. On Windows, it intercepts ANSI sequences in stdout, strips them to prevent 'gobbledygook' output, and converts them into appropriate win32 calls to modify the terminal state.

  3. Enable ANSI support on Windows

    master

    Colorama makes ANSI escape character sequences (used for colored text and cursor positioning) work on MS Windows by wrapping stdout.

    To enable this behavior in existing applications or libraries that use ANSI sequences, you can use one of the following methods:

    1. colorama.just_fix_windows_console(): Available since v0.4.6. This is the preferred method for simply enabling ANSI support.
    2. colorama.init(): Available in all versions. Note that this may have other side-effects beyond just fixing the console.

  4. Build and test Colorama distributables

    master

    To prepare a release, you must build the source distribution (sdist) and the wheel, then test them.

    Building the wheel

    Linux/macOS

    make build

    Windows

    .\build.ps1

    Testing the wheel/distributables

    Linux/macOS

    make test-release

    Windows

    .\test-release.ps1

  5. Initialize Colorama for Windows support

    master

    To enable ANSI escape sequence support on Windows, use just_fix_windows_console().

    On modern Windows 10+ systems, this enables built-in ANSI support. On older versions, it wraps sys.stdout and sys.stderr to emulate ANSI via Win32 calls. This function is safe to call multiple times, safe to call on non-Windows platforms (where it does nothing), and safe to call when streams are redirected to files (where it does nothing).

    from colorama import just_fix_windows_console
just_fix_windows_console()

  6. Set up a development environment for Colorama

    master

    To develop Colorama, you need to create and populate a virtual environment. Development requires specific Python packages listed in requirements-dev.txt.

    Use the following commands based on your operating system:

    Linux/macOS

    make bootstrap

    Windows

    .\bootstrap.ps1

  9. Configure init() keyword arguments

    master

    The init() function accepts several keyword arguments to override default behavior:

    • autoreset=True: Automatically sends a reset sequence at the end of every print.
    • strip=True/False: Overrides whether ANSI codes should be stripped from output (default: strips if on Windows or if output is redirected).
    • convert=True/False: Overrides whether to convert ANSI codes into Win32 calls (default: converts if on Windows and output is a tty).
    • wrap=False: Disables the automatic wrapping of sys.stdout and sys.stderr. If disabled, you must manually use AnsiToWin32 to handle streams.
    import sys
from colorama import init, AnsiToWin32

# Example: Disabling automatic wrapping and using AnsiToWin32 manually
init(wrap=False)
stream = AnsiToWin32(sys.stderr).stream
print('blue text on stderr', file=stream)

  10. Use Colorama with other ANSI libraries

    master

    Colorama is designed to act as a compatibility layer. You can use highly capable libraries like termcolor, blessings, or rich to generate ANSI sequences, and use Colorama simply to ensure those sequences work on Windows.

    from colorama import just_fix_windows_console
from termcolor import colored

# use Colorama to make Termcolor work on Windows too
just_fix_windows_console()

# then use Termcolor for all colored text output
print(colored('Hello, World!', 'green', 'on_red'))

  11. Print colored text using Colorama constants

    master

    You can print colored text using Colorama's constant shorthands for foreground, background, and style. Always remember to use Style.RESET_ALL to prevent color bleeding into subsequent print statements.

    from colorama import Fore, Back, Style
print(Fore.RED + 'some red text')
print(Back.GREEN + 'and with a green background')
print(Style.DIM + 'and in dim text')
print(Style.RESET_ALL)
print('back to normal now')

  12. Initialize Colorama with advanced configuration

    master

    The init() function provides a more feature-rich interface but should be used with caution. Unlike just_fix_windows_console(), init() is not safe to call multiple times and can cause broken ANSI support due to multiple layers of wrapping.

    init() also uses a heuristic to decide whether to strip ANSI sequences from output on all platforms. Use deinit() to restore stdout and stderr to their original values, and reinit() to resume Colorama functionality.

    from colorama import init
init()