colorclass

colorclass is a Python library for producing colored terminal text on Linux, macOS, and Windows without manually managing raw ANSI escape codes. It subclasses str, so colored strings behave like normal strings everywhere — concatenation, slicing, and length all work as expected, with color codes stripped out of len() calculations.

Colors are applied using curly-bracket tags such as {red}Red{/red}, and the library provides special ‘auto colors’ (autored, autoblue, etc.) that automatically pick a readable shade depending on whether the terminal has a light or dark background, toggled via set_light_background()/set_dark_background(). Windows support is enabled with a single Windows.enable() call, and text can also be piped through python -m colorclass on the command line to colorize or strip ANSI codes in shell pipelines.

What You Get

• A Color class (str subclass) supporting curly-bracket color tags like {red}...{/red}
• ‘Auto color’ tags (autored, autoblue, etc.) that adapt to light or dark terminal backgrounds
• One-line Windows console color support via Windows.enable()
• A CLI entry point (python -m colorclass) for colorizing or stripping ANSI codes in shell pipelines
• Environment-variable overrides (COLOR_ENABLE, COLOR_DISABLE, COLOR_LIGHT, COLOR_DARK) for CI and non-TTY contexts

Common Use Cases

• Adding colored status output (success/error/warning) to a Python CLI tool that must also run correctly on Windows
• Building terminal dashboards or progress displays that adapt automatically to the user’s light or dark terminal theme
• Piping colorized or de-colorized text through shell scripts via the python -m colorclass command
• Toggling color output on/off based on whether stdout is a TTY or is being redirected to a file

Under The Hood

Architecture - The library is organized into focused modules: codes.py defines the ANSI escape-code tables and tag names, parse.py translates curly-bracket tags into raw ANSI sequences (and strips them back out), color.py defines the Color class that subclasses str and overrides length/formatting behavior to account for invisible escape codes, toggles.py manages the light/dark ‘auto color’ state, and windows.py wraps the Win32 console API calls needed to enable ANSI rendering on legacy Windows terminals. __main__.py provides the piped CLI entry point. Tech Stack - Pure Python with no runtime dependencies; uses Poetry for packaging and targets Python 3.8+ on Linux, macOS, and Windows (including PyPy). Windows support layers on top of the ctypes-based Win32 console APIs rather than a third-party dependency. Code Quality - The tests/ directory has dedicated test modules mirroring each source file (test_codes.py, test_color.py, test_parse.py, etc.) plus a tests_fragile/ directory for platform-sensitive screenshot-based Windows tests, indicating deliberate separation of stable vs. environment-dependent coverage. The README notes this is now a community-maintained fork (the original maintainer removed collaborators), so recent activity is limited despite the mature, well-tested core. API Design - The tag-based syntax ({red}text{/red}) is approachable for anyone familiar with template markup, and because Color subclasses str, colored values compose naturally with existing string-handling code rather than requiring a special print function or wrapper API.