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.11 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.

Warning: Mixing conflicting attributes such as .underline.double_underline or .blink.rapid_blink has no defined precedence. Their output order may vary between processes. Choose one variant per chain or theme composition.

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.

Warning: Theme names matching built-in fields or methods (for example red or rgb) are inaccessible through attribute lookup. Do not mutate extensions or an extensions= dictionary after creating a builder: derived styles may share it.

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 unless you pass mode=. When stdout is redirected but the handler writes to stderr, choose the mode explicitly:

import sys
from coloredstrings.color_support import detect_color_support

console.setFormatter(ColoredFormatter(
    "%(levelname)s  %(message)s",
    mode=detect_color_support(sys.stderr),
))

Warning: A formatter does not infer the destination of its handler. Sharing one formatter between a terminal handler and a file handler also shares its color mode; use separate formatters with explicit modes.

Warning: Nested styling restores the standalone reset codes emitted by coloredstrings. External strings containing combined resets such as \x1b[0;1m or \x1b[39;1m can interrupt the outer style. This is not a general-purpose ANSI parser.

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

errors = cs.StyleBuilder.for_stream(sys.stderr)
print(errors.red("Permission denied"), file=sys.stderr)

Warning: for_stream() detects the mode when the builder is created. Recreate it if the destination changes. Module-level styles still capture stdout's mode at import time; combining them with later redirection or stderr output can select the wrong mode. Color detection on Windows does not enable VT processing; a console with VT disabled may display escape sequences despite detecting truecolor.

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 make check (lint, formatting, type checks, and tests). Report an issue

Metadata

Release files for coloredstrings 4.0.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 4.0.0
File Size Uploaded Provenance Actions
coloredstrings-4.0.0.tar.gz 21.9 kB Without provenance Details for coloredstrings-4.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 46.9 kB

Release files / coloredstrings-4.0.0.tar.gz

Download URL coloredstrings-4.0.0.tar.gz
Size 21.9 kB
Tags Source
SHA-256 checksum
How to use checksums
e99761679b7ec8dfe58f3a30732fc830015fe696e5b9028d7e96513952edf91f
BLAKE2b-256 checksum
How to use checksums
3005b01b78ad7525b6864dc8e06c50046a4d06c0a402d4b6d50322c281a81999
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-4.0.0-py3-none-any.whl

Download URL coloredstrings-4.0.0-py3-none-any.whl
Size 25.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5c59af54db6a79f70ecfc1a1573afca3030a34c1357d41d17e437f17ef43a30e
BLAKE2b-256 checksum
How to use checksums
1110836c54a6b21d860ccdae5156648bed41cbdf2c4ff8b621b498444c83a253
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 4.0.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