Skip to main content

coloredstrings

Python package PyPI Downloads PyPI version Supported Python versions Licence Code style: Ruff Checked with mypy

cs.white.on.red(" FAIL ") reads about the way it looks. Give that style a name and you can use it anywhere your Python program builds a string.

import coloredstrings as cs

passed = cs.green("PASS")
failed = cs.white.on.red.bold(" FAIL ")

print(passed, "test_read_config")
print(failed, "test_missing_key")
print(cs.dim(f"  expected {cs.yellow('port')} in server.toml"))

Python terminal session showing a green PASS, a white-on-red FAIL, and the missing key port highlighted in yellow

What you get

  • Styles you can keep. Save warning = cs.yellow, then use warning.bold for the heading and warning for the rest.
  • Nested colors. In the example above, port is yellow. You can also put a red word inside a blue sentence, and the rest of the sentence picks up the outer blue again.
  • 16 colors, 256 colors, and truecolor. Use the terminal palette, a hex value, or a name like coral. On terminals with fewer colors, coloredstrings picks a fallback.
  • Plain text when you need it. Respect --no-color at the command line, force a mode in a test, or strip the styling from a string you already have.
  • Named themes, clickable links, and a formatter for Python’s logging module. No runtime dependencies.

Install it and see the colors

We recommend uv. From your project directory, add coloredstrings and run the terminal sampler.

uv add coloredstrings
uv run python -m coloredstrings

With pip, run these commands in your virtual environment.

python -m pip install coloredstrings
python -m coloredstrings

The sampler shows what your terminal theme does with bright_black and whether it draws a double underline. Requires Python 3.9 or later.

Working with styles

Foreground, background, and emphasis

Start with a color or an attribute. Use .on when you want the next color to paint the background.

import coloredstrings as cs

print(cs.red("deleted"))
print(cs.black.on.yellow(" modified "))
print(cs.on.blue.white.bold(" selected "))

Foreground and background are independent. In cs.on.blue.white, blue goes behind the text and white goes in front. If you set the same part twice, the last color wins.

Calling a style works much like print. It converts its arguments to strings and joins them with a space. You get the resulting string back, so you decide where it goes.

from coloredstrings import cyan

issue = cyan("issue", 42, sep="#")
print(f"Changes requested on {issue}")

Choosing a color

If you have… Write
A terminal color cs.red, cs.bright_red, cs.on.red
A palette index cs.color256(208), cs.on.color256(235)
An RGB value cs.rgb(255, 127, 80) or cs.rgb((255, 127, 80))
A hex value cs.rgb("#ff7f50") or cs.rgb("#fc0")
A named color cs.coral or cs.rgb("coral")

The eight base colors are black, red, green, yellow, blue, magenta, cyan, and white. Each has a bright_ variant. Both gray and grey select bright_black.

There’s a reason to keep both cs.red and cs.rgb("red") around. The first uses the red from the reader’s terminal theme. The second asks for #ff0000. Use the former for a conventional error message and the latter when the shade itself matters.

In 3.4, RGB components and palette indices accept integers from 0 to 255 inclusive. An out-of-range value raises ValueError when you build the style, even with colors disabled. Floats and booleans raise TypeError. An RGB tuple takes exactly three components.

Text attributes

Effect Names
Weight and emphasis bold, dim (also faint, dark), italic
Lines underline, double_underline, overline, strike (also strikethrough)
Inversion and concealment inverse (also reverse), hidden (also concealed)
Other terminal effects blink (also slow_blink), rapid_blink, framed, encircle (also circle)

Two helpers are worth calling out. cs.reset() emits an ANSI reset when styling is enabled. cs.visible("● ") gives you a decorative marker that disappears entirely when colors are off. Terminal support varies for effects such as blink and framing.

Give your application its own vocabulary

For a single reusable style, an assignment is enough. When several commands share a palette, extend() lets you name styles after what they mean in your application.

import coloredstrings as cs

diff = cs.extend(added=cs.green, removed=cs.red, hunk="#8a72d6")

print(diff.hunk("@@ -1 +1 @@"))
print(diff.removed("- timeout = 3"))
print(diff.added("+ timeout = 10"))

Theme entries can be styles, color names, hex strings, or RGB tuples. extend() accepts a dictionary as well as keyword arguments. You can still write diff.bold.added, and diff.color_mode(cs.ColorMode.NO_COLOR) gives you a plain-text version of the whole theme.

A terminal that supports OSC 8 hyperlinks can make an issue number clickable. The same label can go into a plain-text report.

import coloredstrings as cs

issue = cs.underline.link("https://github.com/samedit66/coloredstrings/issues")("issues")
print(f"Report a bug under {issue}.")
assert cs.strip_ansi(issue) == "issues"

Color in the console, plain text in the log

Attach ColoredFormatter to the handler that writes to the terminal. By default it colors the level name. Set colorize_msg=True to color the message as well, or colorize_level=False to leave the level name alone.

import logging

from coloredstrings.logger import ColoredFormatter

console = logging.StreamHandler()
console.setFormatter(ColoredFormatter("%(levelname)s  %(message)s"))

log = logging.getLogger("backup")
log.addHandler(console)
log.warning("Skipping locked file %s", "index.db")

A file handler attached to the same logger receives the original record, including its message template and arguments. The formatter uses the color mode detected for standard output when its module is imported.

Who decides whether to use color?

By default, coloredstrings checks standard output at import time. For a command-line program, the overrides below take precedence in the order shown.

Setting Effect
--no-color, --color Disable styling or select 16 colors. --no-color wins if both are present.
FORCE_COLOR 0 disables styling, 1 selects 16 colors, 2 selects 256, and 3 selects truecolor. An empty value or true selects 16 colors. false disables styling.
NO_COLOR A nonempty value disables styling.
CLICOLOR_FORCE Takes the same values as FORCE_COLOR.
CLICOLOR A nonempty value selects 16 colors on a terminal and plain text on a redirected stream.

If you know the destination, you can choose the mode yourself. This is particularly useful when a command writes data to stdout and diagnostics to stderr.

import sys

import coloredstrings as cs
from coloredstrings.color_support import detect_color_support

errors = cs.color_mode(detect_color_support(sys.stderr))
print(errors.red("Permission denied"), file=sys.stderr)

Use color_mode() for a chain or mode= for one call. The available modes are NO_COLOR, ANSI_16, EXTENDED_256, and TRUE_COLOR on cs.ColorMode. For example, a test can assert cs.red("failed", mode=cs.ColorMode.NO_COLOR) == "failed" on any machine.

Coming from another library?

Here’s how each library spells the same small job: a white FAIL label on a red background.

Library What you’d write
coloredstrings cs.white.on.red(" FAIL ")
ansis · JavaScript white.bgRed` FAIL `
yachalk · Python chalk.white.bg_red(" FAIL ")
termcolor · Python colored(" FAIL ", "white", "on_red")
Colorama · Python Fore.WHITE + Back.RED + " FAIL " + Style.RESET_ALL
Rich · Python console.print(" FAIL ", style="white on red")

If you use ansis or yachalk, chains and nested expressions will feel familiar. The spelling to remember here is .on: it works with .red, .color256(208), and .rgb("#ff7f50") alike. termcolor also accepts RGB tuples. In coloredstrings you can give that RGB style a name, add .bold where needed, and use it throughout a command.

How the chain works

cs.red is a callable StyleBuilder. Adding .bold creates a new builder. The original is still useful, which matters when two messages share a color but only one of them needs emphasis.

import coloredstrings as cs

filename = cs.cyan
current_file = filename.bold

print(filename("defaults.toml"))
print(current_file("local.toml"))
print(filename("overrides.toml"))

The ANSI codes are assembled when you call the style. The builder opens the foreground, background, and attributes around your text, then closes them in reverse order. With nested colors, it restores the outer color after the inner one closes. Across a line break, it closes and reopens the style so a background stays with its line. StyleBuilder · ANSI rendering

Working on a rendering bug? Include the smallest expression that shows it and the color mode you used. repr(result) makes a reset code much easier to spot in an issue. To run the suite locally, use uv sync --frozen followed by uv run pytest. Report an issue

Metadata

Release files for coloredstrings 3.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for coloredstrings 3.4.0
File Size Uploaded Provenance Actions
coloredstrings-3.4.0.tar.gz 21.1 kB Without provenance Details for coloredstrings-3.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for coloredstrings 3.4.0
File Interpreter ABI Platform Actions
coloredstrings-3.4.0-py3-none-any.whl Python 3 none any Details for coloredstrings-3.4.0-py3-none-any.whl

Total release size: 45.4 kB

Release files / coloredstrings-3.4.0.tar.gz

Download URL coloredstrings-3.4.0.tar.gz
Size 21.1 kB
Tags Source
SHA-256 checksum
How to use checksums
03f47a4c4f4831c1ee07faa6655093d6b7ef5f93df71172c7b2c619ed4d721f5
BLAKE2b-256 checksum
How to use checksums
03708ed9e89c7d05d4ee1d39744cda9fd32a7282c919623622ebf0f60304bf95
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / coloredstrings-3.4.0-py3-none-any.whl

Download URL coloredstrings-3.4.0-py3-none-any.whl
Size 24.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
445cf792476fb38ce7f97938ab88ea78ca985d0ef83b72cfbc0e4bd898cbb633
BLAKE2b-256 checksum
How to use checksums
673057ba6f30136ae2a5b6614075b5f96b00dca131c321abf306f94b6dee50ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for coloredstrings 3.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page