🌈 shellcolorize

shellcolorize is a lightweight Python library for adding color and style to terminal output using ANSI codes. Zero dependencies, no configuration — just import and use.

✨ Features

• 🎨 Full ANSI palette — 8 standard + 8 bright text colors, same for backgrounds.
• ✍️ Text styles — bold, dim, italic, underline, blink, reverse, strikethrough.
• 🛠 colorize() helper — applies styles and resets automatically, no manual RESET needed.
• 🔇 Smart color detection — plain text when piped to a file, honours NO_COLOR and FORCE_COLOR.
• 🔌 Global on/off switch — Color.auto() / Color.disable() make every f-string plain text in one call.
• 🔗 Open Source — MIT License.

📥 Installation

pip install shellcolorize

🛠 Usage

Using colorize() (recommended)

colorize(text, *styles) applies any combination of colors and styles and resets automatically. It also returns plain text when the output is not a TTY or when the NO_COLOR env var is set.

from shellcolorize import Color, colorize

print(colorize("This is red", Color.RED))
print(colorize("Bold and underlined", Color.BOLD, Color.UNDERLINE))
print(colorize("White on blue background", Color.BG_BLUE, Color.WHITE))
print(colorize("Bright green, bold", Color.BRIGHT_GREEN, Color.BOLD))

Using Color attributes directly

For inline use in f-strings. Remember to close with Color.RESET.

from shellcolorize import Color

print(f"{Color.RED}This is red{Color.RESET}")
print(f"{Color.BG_YELLOW}{Color.BLACK}Black on yellow{Color.RESET}")
print(f"{Color.BOLD}{Color.CYAN}Bold cyan{Color.RESET}")

🎨 Available Colors

Standard text colors

Background colors

Text styles

🔇 Color detection

supports_color() decides whether colors should be used, following common CLI conventions:

colorize() applies this check on every call. For f-strings that use Color attributes directly, call Color.auto() once at start-up and every attribute becomes an empty string when colors are not supported:

from shellcolorize import Color

def main():
    Color.auto()          # respects NO_COLOR / FORCE_COLOR / TTY detection
    print(f"{Color.GREEN}✔ done{Color.RESET}")   # plain "✔ done" when piped

Color.disable() and Color.enable() switch colors off and on explicitly (e.g. for a --no-color flag).

python script.py > output.txt      # plain text in the file
NO_COLOR=1 python script.py        # plain text
FORCE_COLOR=1 python script.py | less -R   # keep colors through a pager

🧪 Development

pip install -e ".[dev]"
ruff check .
pytest

📝 License

MIT — see LICENSE.

💬 Feedback

Open an issue or reach out via GitHub.

🌐 Connect