# coloredstrings
[](https://github.com/samedit66/coloredstrings/actions/workflows/python-package.yml)
[](https://pepy.tech/projects/coloredstrings)
[](https://pypi.org/project/coloredstrings)
[](https://pypi.org/project/coloredstrings)
[](COPYING.txt)
[](https://github.com/astral-sh/ruff)
[](https://mypy-lang.org/)
<div align="center">
<p><em>Do more. Type less. Colorize different.</em></p>
</div>
---
**coloredstrings** is a small utility for expressive terminal colors and text styles.
It exposes a fluent, chainable API for styling strings and can act as a drop-in replacement for similar packages like [yachalk](https://github.com/bluenote10/yachalk).
Designed to be suitable, useful, and "batteries-included".
Example:
```python
import coloredstrings as cs
print(cs.bold.underline.red("Error:"), "Something went wrong.")
print(cs.blue.bold("Info:"), "Everything is OK")
print(cs.italic.green("Success!"))
```
---
## Features🔥
- No dependencies
- Composing styles in a chainable way: `black.on.white.bold("What's up?")`
- Nested colors and no nested styling bug
- Support for 16-color, 256-color, and 24-bit (truecolor / RGB / hex) modes
- Auto-detection of terminal color capabilities
- Automatically fallback to the nearest supported color if the requested color isn't supported
- Friendly autocomplete API
- Call any of [named true colors](https://drafts.csswg.org/css-color/#named-colors) as a method: `aqua`, `pink` and so on
- Extend default styles with user-defined ones
- Strip ANSI escape codes with `strip_ansi`
- Friendly to [CLI arguments](#cli-arguments): `--color` & `--no-color`
- Support for [common envs](#force_color-no_color-clicolor_force-and-clicolor): [`FORCE_COLOR`](https://force-color.org/), [`NO_COLOR`](https://no-color.org/), [`CLICOLOR_FORCE` & `CLICOLOR`](https://bixense.com/clicolors/)
- Curious how **coloredstrings** compares to other libraries? See [Migrating from other libraries](#migrating-from-other-libraries)
---
## Installation
Stable release from PyPI:
```bash
pip install coloredstrings
```
Latest development version:
```bash
pip install git+https://github.com/samedit66/coloredstrings.git
```
---
## Quick start
Run the bundled demo:
```bash
python -m coloredstrings
```
Features:
```python
import coloredstrings as cs
print(cs.bold.underline.red("Error:"), "Something went wrong.")
print(cs.blue.bold("Info:"), "Everything is OK")
print(cs.italic.green("Success!"))
# styles accepts multiple arguments and a `sep` argument like `print`:
print(cs.green("That's", "great!"))
print(cs.blue(1, 3.14, True, sep=", "))
# Nesting and combining styles:
print(cs.red(f"Hello {cs.underline.on.blue('world')}!"))
print(
cs.green(
"I am a green line "
+ cs.blue.underline.bold("with a blue substring")
+ " that becomes green again!"
)
)
# 24-bit RGB / hex and 256-color:
print(cs.rgb(123, 45, 200)("custom"))
print(cs.rgb("#aabbcc")("hex is also supported"))
print(cs.rgb("purple")("as well as named colors too"))
print(cs.rgb((169, 169, 169))("tuples can also be used"))
print(cs.color256(37)("256-color example"))
# Define theme helpers:
error = cs.bold.red
warning = cs.rgb("#FFA500")
print(error("Error!"))
print(warning("Warning!"))
# Or extend with your own styles:
bootstrap = cs.extend(
primary="blue", # may be a color / style name
secondary=(169, 169, 169), # RGB-tuple color
success=cs.green, # or any `StyleBuilder` instance
)
print(bootstrap.primary("Click me!"))
print(bootstrap.italic.secondary("You can combine builtin styles with your own!"))
print(bootstrap.success("Complete."))
```
---
## Usage
Import `coloredstrings` module directly:
```python
from coloredstrings import white, red, blue
print(white.bold("white bold text"))
print(red("just red text"))
print(blue.strikethrough("blue strikethrough text"))
```
Or use only needed styles:
```python
import coloredstrings as cs
print(cs.green.on.pink("green text on pink background"))
```
Chainable API allows you to easily compose styles and use them. When passing final text to a style, you can pass multiple objects which will be turned to strings and joined using an optional `sep` argument (which defaults to a single space):
```python
import coloredstrings as cs
print(cs.orange("text", 1, 1.0, True, sep="-"))
```
### `StyleBuilder`
Although you use `cs` everywhere, the actual work is done by an immutable `StyleBuilder` class under the hood. Because every style object is immutable, creating a new style from an existing one doesn't modify the original. This avoids accidental cross-contamination of styles present in `yachalk`:
```python
from yachalk import chalk
import coloredstrings as cs
# With yachalk
s1 = chalk.italic
s2 = s1.red
print(s1("Chalk, am I red?"))
print(s2("Yes, you are!"))
print("-" * 8)
# With coloredstrings
s3 = cs.italic
s4 = s3.red
print(s3("Style, am I still red?"))
print(s4("Sure not, but I am!"))
```
In this example, `s1/s2` and `s3/s4` behave differently: `s1/s2` are actually the same style, while `s3/s4` are truly independent styles.
### Chaining and gotchas
`coloredstrings` — like `yachalk` and several other libraries — is built around chaining styles. Unlike some libraries, it does not provide separate background helpers such as `bg_blue`. Instead, use the `on` helper to mark that the next color in the chain should be a background color. This gives you explicit control over whether the color you add applies to the foreground or the background.
Example:
```python
import coloredstrings as cs
# Red text on a blue background
print(cs.red.on.blue("Hey!"))
# Don't write code like this - it's hard to read!
# It's equivalent to `cs.white.on.black(...)` but much less clear
print(cs.white.on.on.black("Do not write code like that."))
# Green background with default foreground
print(cs.on.green("Text on a green background"))
```
A few important gotchas:
- If you chain multiple foreground colors, only the last foreground color takes effect:
```python
print(cs.red.green.blue("Blue text")) # result: blue foreground
```
- `on` affects only the next color in the chain. For example:
```python
print(cs.on.magenta.cyan("Cyan text on magenta background"))
```
Here `magenta` becomes the background (because of `on`) and `cyan` is the foreground.
- Repeated calls to `on` without an intervening color are redundant and hurt readability; prefer the simpler, clearer form.
### Supported color modes
`coloredstrings` tries its best to detect terminal color capabilities automatically (see `coloredstrings.color_support.detect_color_support()`), but detection can occasionally miss. You can explicitly set the color mode using the pseudo-style method `color_mode(mode)`.
`mode` is a member of the `coloredstrings.ColorMode` enum with these values:
- `ColorMode.NO_COLORS` - disable styling; no escape sequences are emitted
- `ColorMode.ANSI_16` - 16 basic ANSI colors
- `ColorMode.EXTENDED_256` - 256 color mode
- `ColorMode.TRUE_COLOR` - 24-bit RGB / truecolor support
Example:
```python
from coloredstrings import style, ColorMode
# Notice `style`? It's a default style which does nothing.
# Force no colors
just_text = style.color_mode(ColorMode.NO_COLORS)
print(just_text.red("It isn't red"))
# Force truecolor
rgb_default = style.color_mode(ColorMode.TRUE_COLOR)
print(rgb_default.hex("#ca7e8d")("Hi!"))
```
#### `FORCE_COLOR`, `NO_COLOR`, `CLICOLOR_FORCE` and `CLICOLOR`
With a wide variety of options to force terminal color or not, `coloredstrings` respects common environment conventions (in order of precedence - higher precedence goes first):
- **`FORCE_COLOR`**: if set, this variable can be used to force color output even when detection would otherwise disable it (for example, when output is being piped).
Following values are supported:
- `FORCE_COLOR<=0` - same as `ColorMode.NO_COLOR` or `NO_COLOR` environment variable
- `FORCE_COLOR=1` - same as `ColorMode.ANSI_16`
- `FORCE_COLOR=2` - same as `ColorMode.EXTENDED_256`
- `FORCE_COLOR>=3` - same as `ColorMode.TRUE_COLOR`
- **`NO_COLOR`**: if this environment variable is present (with any value other than an empty string), coloredstrings will avoid emitting color escape sequences. This is the community-standard way for users to opt out of colored output.
- **`CLICOLOR_FORCE`**: same as `FORCE_COLOR`.
- **`CLICOLOR`**: same as `ColorMode.ANSI_16`.
You can still programmatically override detection by calling `style.color_mode(...)` as shown above.
#### CLI arguments
> [!NOTE]
> CLI arguments take precedence over any environment variable.
You can also specify command-line flags like `--no-color` to disable colors and `--color` to enable them.
Example with a file `cool.py`:
```python
import coloredstrings as cs
print(cs.red(f"Hello {style.blue('world')}!"))
```
```bash
# Run with python
python cool.py --no-color
# Run with uv
uv run cool.py --color
```
## Fallback behavior
Many terminals do not support full truecolor (`ColorMode.TRUE_COLOR`). When a requested color cannot be represented in the current color mode, `coloredstrings` automatically maps the requested color into the best available color space and emits the closest supported color. In short: you will still get colored output, though the result may be an approximation of the original color.
## Styles
### Attributes
- `reset` - Reset the current style chain. Widely supported.
- `bold` - Make the text bold (increases weight). Widely supported.
- `dim` (aliases: `faint`, `dark`) - Render the text with lower intensity / brightness. Support varies.
- `italic` - Render text in italic. *Support varies across terminals.*
- `underline` - Draw a horizontal line **below** the text. *Support varies.*
- `double_underline` - Draw a double underline under the text. *Not widely supported.*
- `overline` - Draw a horizontal line **above** the text. *Not widely supported.*
- `inverse` (alias: `reverse`) - Swap foreground and background colors (invert colors).
- `hidden` (alias: `concealed`) - Do not display the text (it is still present in the output stream).
- `strike` (alias: `strikethrough`) - Draw a horizontal line through the center of the text. *Support varies.*
- `blink` (alias: `slow_blink`) - Make the text blink. **Often unsupported** in modern terminals; avoid depending on it.
- `rapid_blink` - Faster blink. **Often unsupported** in modern terminals; avoid depending on it.
- `framed` - Draw a frame around the text. *Rarely supported.*
- `encircle` (alias: `circle`) - Draw a circle/encircle the text. *Rarely supported.*
- `visible` - Show text only when a color mode is enabled (anything other than `ColorMode.NO_COLOR`). Mainly used for cosmetic things.
> **Note on attributes:** Most attributes stack (they combine instead of overriding). Terminal support for many of these attributes is spotty - prefer basic attributes (`bold`, `underline`, `inverse`) for portability.
### Colors (both foreground and background)
- `black`
- `red`
- `green`
- `yellow`
- `blue`
- `magenta`
- `cyan`
- `white`
- `bright_black` (aliases: `gray`, `grey`)
- `bright_red`
- `bright_green`
- `bright_yellow`
- `bright_blue`
- `bright_magenta`
- `bright_cyan`
- `bright_white`
- `color256(index)` - 256 color
- `rgb(r, g, b)`, `rgb(hex)`, `rgb(color_name)` - 24-bit RGB color
When you call `cs` with a method not defined above, it tries to interpret the method name as a [named color](https://drafts.csswg.org/css-color/#named-colors).
This allows having many color methods without the need to define them explicitly:
```python
import coloredstrings as cs
from coloredstrings import purple
print(cs.lavender("`lavender` is not defined internally"))
print(purple("Neither is `purple`."))
```
---
## Migrating from other libraries
If you’ve used other Python color or formatting libraries before, `coloredstrings` will feel familiar but more robust and consistent. Below is a quick comparison of how it differs from popular alternatives:
### **colorama**
- **colorama** provides low-level ANSI control and Windows compatibility but lacks a fluent API.
- `coloredstrings` supports more colors, styles and requires no use of ANSI codes directly.
- Example:
```python
# colorama
from colorama import Fore, Style
print(Fore.RED + 'Error' + Style.RESET_ALL)
# coloredstrings
import coloredstrings as cs
print(cs.red('Error'))
```
### **termcolor**
- **termcolor** focuses on basic named colors but doesn’t support chaining or RGB.
- `coloredstrings` supports truecolor, background colors, attributes, and chaining.
- Example:
```python
# termcolor
from termcolor import colored
print(colored('Warning!', 'yellow', attrs=['bold']))
# coloredstrings
import coloredstrings as cs
print(cs.bold.yellow('Warning!'))
```
- `coloredstrings` lacks nested styling bug presented in **termcolor**:
```python
# termcolor
from termcolor import colored
print(colored('Warning!', 'yellow', attrs=['bold']))
# coloredstrings
import coloredstrings as cs
print(cs.bold.yellow('Warning!'))
```
### **yachalk**
- **yachalk** inspired `coloredstrings`, but its mutable style builders can cause side effects.
- `coloredstrings`’s `StyleBuilder` is **immutable**, ensuring no cross-contamination between styles.
- Chain syntax and API are nearly identical expect that you don't need to remember a separate method for background coloring.
- Example:
```python
# yachalk
from yachalk import chalk
print(chalk.blue.bg_red.bold("Hello world!"))
# coloredstrings
import coloredstrings as cs
print(cs.blue.on.red.blod("Hello world!"))
```
### **rich**
- **rich** is a full-featured library for terminal formatting, tables, markdown, and logging.
- It’s excellent for large applications but too heavy for simple coloring.
- `coloredstrings` aims to be **minimal, dependency-free, and Pythonic** for everyday terminal styling.
- Example:
```python
# rich
from rich.console import Console
Console().print('[bold red]Error[/bold red] Something went wrong')
# coloredstrings
import coloredstrings as cs
print(cs.bold.red('Error:'), 'Something went wrong')
```
In short:
| Library | No dependencies | Chainable | Truecolor | Immutable Styles | No nested styling bug | Focus |
|----------|---------------|------------|-------------|------------------|----|----|
| colorama | ✅ | ❌ | ❌ | ❌ | ✅ | Compatibility |
| termcolor | ✅ | ❌ | ❌ | ❌ | ❌ | Simplicity |
| yachalk | ✅ | ✅ | ✅ | ❌ | ✅ | Modern styling |
| rich | ❌ | ✅ | ✅ | ✅ | ✅ | Full-featured UI |
| **coloredstrings** | ✅ | ✅ | ✅ | ✅ | ✅ | Lightweight styling |
---
## Contributing
I’d love your help to make coloredstrings even better!
- 💡 Got an idea or found a bug? [Open an issue](https://github.com/samedit66/coloredstrings/issues) and let’s talk about it
- 🔧 Want to improve the code? PRs are always welcome! Please include tests for any new behavior.
- ♻️ Try to keep changes backward-compatible where possible
- 🎨 Adding new styles or helpers? Don’t forget to update the README and include tests to ensure ANSI - sequences open and close correctly
- ⭐ If you like this project, consider giving it a star - it really helps others discover it!
Raw data
{
"_id": null,
"home_page": null,
"name": "coloredstrings",
"maintainer": "samedit66",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "samedit66 <samedit66@yandex.ru>",
"keywords": "ansi, color, colour, crossplatform, terminal, text",
"author": "samedit66",
"author_email": "samedit66 <samedit66@yandex.ru>",
"download_url": "https://files.pythonhosted.org/packages/98/1d/b5bace2ca58160b5cd72cec030eefd915ab85bbcfaffff5a53ae6864182b/coloredstrings-3.2.0.tar.gz",
"platform": null,
"description": "# coloredstrings\n\n[](https://github.com/samedit66/coloredstrings/actions/workflows/python-package.yml)\n[](https://pepy.tech/projects/coloredstrings)\n[](https://pypi.org/project/coloredstrings)\n[](https://pypi.org/project/coloredstrings)\n[](COPYING.txt)\n[](https://github.com/astral-sh/ruff)\n[](https://mypy-lang.org/)\n\n<div align=\"center\">\n <p><em>Do more. Type less. Colorize different.</em></p>\n</div>\n\n---\n\n**coloredstrings** is a small utility for expressive terminal colors and text styles.\nIt exposes a fluent, chainable API for styling strings and can act as a drop-in replacement for similar packages like [yachalk](https://github.com/bluenote10/yachalk).\n\nDesigned to be suitable, useful, and \"batteries-included\".\n\nExample:\n\n```python\nimport coloredstrings as cs\n\nprint(cs.bold.underline.red(\"Error:\"), \"Something went wrong.\")\nprint(cs.blue.bold(\"Info:\"), \"Everything is OK\")\nprint(cs.italic.green(\"Success!\"))\n```\n\n\n\n---\n\n## Features\ud83d\udd25\n\n- No dependencies\n- Composing styles in a chainable way: `black.on.white.bold(\"What's up?\")`\n- Nested colors and no nested styling bug\n- Support for 16-color, 256-color, and 24-bit (truecolor / RGB / hex) modes\n- Auto-detection of terminal color capabilities\n- Automatically fallback to the nearest supported color if the requested color isn't supported\n- Friendly autocomplete API\n- Call any of [named true colors](https://drafts.csswg.org/css-color/#named-colors) as a method: `aqua`, `pink` and so on\n- Extend default styles with user-defined ones\n- Strip ANSI escape codes with `strip_ansi`\n- Friendly to [CLI arguments](#cli-arguments): `--color` & `--no-color`\n- Support for [common envs](#force_color-no_color-clicolor_force-and-clicolor): [`FORCE_COLOR`](https://force-color.org/), [`NO_COLOR`](https://no-color.org/), [`CLICOLOR_FORCE` & `CLICOLOR`](https://bixense.com/clicolors/)\n- Curious how **coloredstrings** compares to other libraries? See [Migrating from other libraries](#migrating-from-other-libraries)\n\n---\n\n## Installation\n\nStable release from PyPI:\n\n```bash\npip install coloredstrings\n```\n\nLatest development version:\n\n```bash\npip install git+https://github.com/samedit66/coloredstrings.git\n```\n\n---\n\n## Quick start\n\nRun the bundled demo:\n\n```bash\npython -m coloredstrings\n```\n\nFeatures:\n\n```python\nimport coloredstrings as cs\n\nprint(cs.bold.underline.red(\"Error:\"), \"Something went wrong.\")\nprint(cs.blue.bold(\"Info:\"), \"Everything is OK\")\nprint(cs.italic.green(\"Success!\"))\n\n# styles accepts multiple arguments and a `sep` argument like `print`:\nprint(cs.green(\"That's\", \"great!\"))\nprint(cs.blue(1, 3.14, True, sep=\", \"))\n\n# Nesting and combining styles:\nprint(cs.red(f\"Hello {cs.underline.on.blue('world')}!\"))\nprint(\n cs.green(\n \"I am a green line \"\n + cs.blue.underline.bold(\"with a blue substring\")\n + \" that becomes green again!\"\n )\n)\n\n# 24-bit RGB / hex and 256-color:\nprint(cs.rgb(123, 45, 200)(\"custom\"))\nprint(cs.rgb(\"#aabbcc\")(\"hex is also supported\"))\nprint(cs.rgb(\"purple\")(\"as well as named colors too\"))\nprint(cs.rgb((169, 169, 169))(\"tuples can also be used\"))\nprint(cs.color256(37)(\"256-color example\"))\n\n# Define theme helpers:\nerror = cs.bold.red\nwarning = cs.rgb(\"#FFA500\")\n\nprint(error(\"Error!\"))\nprint(warning(\"Warning!\"))\n\n# Or extend with your own styles:\nbootstrap = cs.extend(\n primary=\"blue\", # may be a color / style name\n secondary=(169, 169, 169), # RGB-tuple color\n success=cs.green, # or any `StyleBuilder` instance\n)\n\nprint(bootstrap.primary(\"Click me!\"))\nprint(bootstrap.italic.secondary(\"You can combine builtin styles with your own!\"))\nprint(bootstrap.success(\"Complete.\"))\n```\n\n---\n\n## Usage\n\nImport `coloredstrings` module directly:\n\n```python\nfrom coloredstrings import white, red, blue\n\nprint(white.bold(\"white bold text\"))\nprint(red(\"just red text\"))\nprint(blue.strikethrough(\"blue strikethrough text\"))\n```\n\nOr use only needed styles:\n\n```python\nimport coloredstrings as cs\n\nprint(cs.green.on.pink(\"green text on pink background\"))\n```\n\nChainable API allows you to easily compose styles and use them. When passing final text to a style, you can pass multiple objects which will be turned to strings and joined using an optional `sep` argument (which defaults to a single space):\n\n```python\nimport coloredstrings as cs\n\nprint(cs.orange(\"text\", 1, 1.0, True, sep=\"-\"))\n```\n\n### `StyleBuilder`\n\nAlthough you use `cs` everywhere, the actual work is done by an immutable `StyleBuilder` class under the hood. Because every style object is immutable, creating a new style from an existing one doesn't modify the original. This avoids accidental cross-contamination of styles present in `yachalk`:\n\n```python\nfrom yachalk import chalk\nimport coloredstrings as cs\n\n# With yachalk\ns1 = chalk.italic\ns2 = s1.red\n\nprint(s1(\"Chalk, am I red?\"))\nprint(s2(\"Yes, you are!\"))\n\nprint(\"-\" * 8)\n\n# With coloredstrings\ns3 = cs.italic\ns4 = s3.red\n\nprint(s3(\"Style, am I still red?\"))\nprint(s4(\"Sure not, but I am!\"))\n```\n\n\n\nIn this example, `s1/s2` and `s3/s4` behave differently: `s1/s2` are actually the same style, while `s3/s4` are truly independent styles.\n\n### Chaining and gotchas\n\n`coloredstrings` \u2014 like `yachalk` and several other libraries \u2014 is built around chaining styles. Unlike some libraries, it does not provide separate background helpers such as `bg_blue`. Instead, use the `on` helper to mark that the next color in the chain should be a background color. This gives you explicit control over whether the color you add applies to the foreground or the background.\n\nExample:\n\n```python\nimport coloredstrings as cs\n\n# Red text on a blue background\nprint(cs.red.on.blue(\"Hey!\"))\n\n# Don't write code like this - it's hard to read!\n# It's equivalent to `cs.white.on.black(...)` but much less clear\nprint(cs.white.on.on.black(\"Do not write code like that.\"))\n\n# Green background with default foreground\nprint(cs.on.green(\"Text on a green background\"))\n```\n\nA few important gotchas:\n\n- If you chain multiple foreground colors, only the last foreground color takes effect:\n\n ```python\n print(cs.red.green.blue(\"Blue text\")) # result: blue foreground\n ```\n\n- `on` affects only the next color in the chain. For example:\n\n ```python\n print(cs.on.magenta.cyan(\"Cyan text on magenta background\"))\n ```\n\n Here `magenta` becomes the background (because of `on`) and `cyan` is the foreground.\n\n- Repeated calls to `on` without an intervening color are redundant and hurt readability; prefer the simpler, clearer form.\n\n### Supported color modes\n\n`coloredstrings` tries its best to detect terminal color capabilities automatically (see `coloredstrings.color_support.detect_color_support()`), but detection can occasionally miss. You can explicitly set the color mode using the pseudo-style method `color_mode(mode)`.\n\n`mode` is a member of the `coloredstrings.ColorMode` enum with these values:\n- `ColorMode.NO_COLORS` - disable styling; no escape sequences are emitted\n- `ColorMode.ANSI_16` - 16 basic ANSI colors\n- `ColorMode.EXTENDED_256` - 256 color mode\n- `ColorMode.TRUE_COLOR` - 24-bit RGB / truecolor support\n\nExample:\n\n```python\nfrom coloredstrings import style, ColorMode\n\n# Notice `style`? It's a default style which does nothing.\n\n# Force no colors\njust_text = style.color_mode(ColorMode.NO_COLORS)\nprint(just_text.red(\"It isn't red\"))\n\n# Force truecolor\nrgb_default = style.color_mode(ColorMode.TRUE_COLOR)\nprint(rgb_default.hex(\"#ca7e8d\")(\"Hi!\"))\n```\n\n#### `FORCE_COLOR`, `NO_COLOR`, `CLICOLOR_FORCE` and `CLICOLOR`\n\nWith a wide variety of options to force terminal color or not, `coloredstrings` respects common environment conventions (in order of precedence - higher precedence goes first):\n\n- **`FORCE_COLOR`**: if set, this variable can be used to force color output even when detection would otherwise disable it (for example, when output is being piped).\nFollowing values are supported:\n - `FORCE_COLOR<=0` - same as `ColorMode.NO_COLOR` or `NO_COLOR` environment variable\n - `FORCE_COLOR=1` - same as `ColorMode.ANSI_16`\n - `FORCE_COLOR=2` - same as `ColorMode.EXTENDED_256`\n - `FORCE_COLOR>=3` - same as `ColorMode.TRUE_COLOR`\n\n- **`NO_COLOR`**: if this environment variable is present (with any value other than an empty string), coloredstrings will avoid emitting color escape sequences. This is the community-standard way for users to opt out of colored output.\n\n- **`CLICOLOR_FORCE`**: same as `FORCE_COLOR`.\n\n- **`CLICOLOR`**: same as `ColorMode.ANSI_16`.\n\nYou can still programmatically override detection by calling `style.color_mode(...)` as shown above.\n\n#### CLI arguments\n\n> [!NOTE]\n> CLI arguments take precedence over any environment variable.\n\nYou can also specify command-line flags like `--no-color` to disable colors and `--color` to enable them.\n\nExample with a file `cool.py`:\n\n```python\nimport coloredstrings as cs\n\nprint(cs.red(f\"Hello {style.blue('world')}!\"))\n```\n\n```bash\n# Run with python\npython cool.py --no-color\n\n# Run with uv\nuv run cool.py --color\n```\n\n## Fallback behavior\n\nMany terminals do not support full truecolor (`ColorMode.TRUE_COLOR`). When a requested color cannot be represented in the current color mode, `coloredstrings` automatically maps the requested color into the best available color space and emits the closest supported color. In short: you will still get colored output, though the result may be an approximation of the original color.\n\n## Styles\n\n### Attributes\n\n- `reset` - Reset the current style chain. Widely supported.\n- `bold` - Make the text bold (increases weight). Widely supported.\n- `dim` (aliases: `faint`, `dark`) - Render the text with lower intensity / brightness. Support varies.\n- `italic` - Render text in italic. *Support varies across terminals.*\n- `underline` - Draw a horizontal line **below** the text. *Support varies.*\n- `double_underline` - Draw a double underline under the text. *Not widely supported.*\n- `overline` - Draw a horizontal line **above** the text. *Not widely supported.*\n- `inverse` (alias: `reverse`) - Swap foreground and background colors (invert colors).\n- `hidden` (alias: `concealed`) - Do not display the text (it is still present in the output stream).\n- `strike` (alias: `strikethrough`) - Draw a horizontal line through the center of the text. *Support varies.*\n- `blink` (alias: `slow_blink`) - Make the text blink. **Often unsupported** in modern terminals; avoid depending on it.\n- `rapid_blink` - Faster blink. **Often unsupported** in modern terminals; avoid depending on it.\n- `framed` - Draw a frame around the text. *Rarely supported.*\n- `encircle` (alias: `circle`) - Draw a circle/encircle the text. *Rarely supported.*\n- `visible` - Show text only when a color mode is enabled (anything other than `ColorMode.NO_COLOR`). Mainly used for cosmetic things.\n\n> **Note on attributes:** Most attributes stack (they combine instead of overriding). Terminal support for many of these attributes is spotty - prefer basic attributes (`bold`, `underline`, `inverse`) for portability.\n\n### Colors (both foreground and background)\n\n- `black`\n- `red`\n- `green`\n- `yellow`\n- `blue`\n- `magenta`\n- `cyan`\n- `white`\n- `bright_black` (aliases: `gray`, `grey`)\n- `bright_red`\n- `bright_green`\n- `bright_yellow`\n- `bright_blue`\n- `bright_magenta`\n- `bright_cyan`\n- `bright_white`\n- `color256(index)` - 256 color\n- `rgb(r, g, b)`, `rgb(hex)`, `rgb(color_name)` - 24-bit RGB color\n\nWhen you call `cs` with a method not defined above, it tries to interpret the method name as a [named color](https://drafts.csswg.org/css-color/#named-colors).\nThis allows having many color methods without the need to define them explicitly:\n\n```python\nimport coloredstrings as cs\nfrom coloredstrings import purple\n\nprint(cs.lavender(\"`lavender` is not defined internally\"))\nprint(purple(\"Neither is `purple`.\"))\n```\n\n---\n\n## Migrating from other libraries\n\nIf you\u2019ve used other Python color or formatting libraries before, `coloredstrings` will feel familiar but more robust and consistent. Below is a quick comparison of how it differs from popular alternatives:\n\n### **colorama**\n- **colorama** provides low-level ANSI control and Windows compatibility but lacks a fluent API.\n- `coloredstrings` supports more colors, styles and requires no use of ANSI codes directly.\n- Example:\n ```python\n # colorama\n from colorama import Fore, Style\n print(Fore.RED + 'Error' + Style.RESET_ALL)\n\n # coloredstrings\n import coloredstrings as cs\n print(cs.red('Error'))\n ```\n\n### **termcolor**\n- **termcolor** focuses on basic named colors but doesn\u2019t support chaining or RGB.\n- `coloredstrings` supports truecolor, background colors, attributes, and chaining.\n- Example:\n ```python\n # termcolor\n from termcolor import colored\n print(colored('Warning!', 'yellow', attrs=['bold']))\n\n # coloredstrings\n import coloredstrings as cs\n print(cs.bold.yellow('Warning!'))\n ```\n- `coloredstrings` lacks nested styling bug presented in **termcolor**:\n ```python\n # termcolor\n from termcolor import colored\n print(colored('Warning!', 'yellow', attrs=['bold']))\n\n # coloredstrings\n import coloredstrings as cs\n print(cs.bold.yellow('Warning!'))\n ```\n\n### **yachalk**\n- **yachalk** inspired `coloredstrings`, but its mutable style builders can cause side effects.\n- `coloredstrings`\u2019s `StyleBuilder` is **immutable**, ensuring no cross-contamination between styles.\n- Chain syntax and API are nearly identical expect that you don't need to remember a separate method for background coloring.\n- Example:\n ```python\n # yachalk\n from yachalk import chalk\n print(chalk.blue.bg_red.bold(\"Hello world!\"))\n\n # coloredstrings\n import coloredstrings as cs\n print(cs.blue.on.red.blod(\"Hello world!\"))\n ```\n\n### **rich**\n- **rich** is a full-featured library for terminal formatting, tables, markdown, and logging.\n- It\u2019s excellent for large applications but too heavy for simple coloring.\n- `coloredstrings` aims to be **minimal, dependency-free, and Pythonic** for everyday terminal styling.\n- Example:\n ```python\n # rich\n from rich.console import Console\n Console().print('[bold red]Error[/bold red] Something went wrong')\n\n # coloredstrings\n import coloredstrings as cs\n print(cs.bold.red('Error:'), 'Something went wrong')\n ```\n\nIn short:\n| Library | No dependencies | Chainable | Truecolor | Immutable Styles | No nested styling bug | Focus |\n|----------|---------------|------------|-------------|------------------|----|----|\n| colorama | \u2705 | \u274c | \u274c | \u274c | \u2705 | Compatibility |\n| termcolor | \u2705 | \u274c | \u274c | \u274c | \u274c | Simplicity |\n| yachalk | \u2705 | \u2705 | \u2705 | \u274c | \u2705 | Modern styling |\n| rich | \u274c | \u2705 | \u2705 | \u2705 | \u2705 | Full-featured UI |\n| **coloredstrings** | \u2705 | \u2705 | \u2705 | \u2705 | \u2705 | Lightweight styling |\n\n---\n\n## Contributing\n\nI\u2019d love your help to make coloredstrings even better!\n\n- \ud83d\udca1 Got an idea or found a bug? [Open an issue](https://github.com/samedit66/coloredstrings/issues) and let\u2019s talk about it\n- \ud83d\udd27 Want to improve the code? PRs are always welcome! Please include tests for any new behavior.\n- \u267b\ufe0f Try to keep changes backward-compatible where possible\n- \ud83c\udfa8 Adding new styles or helpers? Don\u2019t forget to update the README and include tests to ensure ANSI - sequences open and close correctly\n- \u2b50 If you like this project, consider giving it a star - it really helps others discover it!\n",
"bugtrack_url": null,
"license": null,
"summary": "Colorize Different.",
"version": "3.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/samedit66/coloredstrings/issues",
"Changelog": "https://github.com/samedit66/coloredstrings/releases",
"Documentation": "https://github.com/samedit66/coloredstrings#readme",
"Homepage": "https://github.com/samedit66/coloredstrings",
"Repository": "https://github.com/samedit66/coloredstrings"
},
"split_keywords": [
"ansi",
" color",
" colour",
" crossplatform",
" terminal",
" text"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0246b48ee6bf9e5bfe2f075d814ae58d409eb2492953e3a84647615b27b9882d",
"md5": "95f6e0eedc6ea05490edb00efc9ddf29",
"sha256": "c54b8660b6a26de87d8763b81687690a29b74a3881d45beb98cf31609d3e3e48"
},
"downloads": -1,
"filename": "coloredstrings-3.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "95f6e0eedc6ea05490edb00efc9ddf29",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 25242,
"upload_time": "2025-10-11T19:49:50",
"upload_time_iso_8601": "2025-10-11T19:49:50.602066Z",
"url": "https://files.pythonhosted.org/packages/02/46/b48ee6bf9e5bfe2f075d814ae58d409eb2492953e3a84647615b27b9882d/coloredstrings-3.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "981db5bace2ca58160b5cd72cec030eefd915ab85bbcfaffff5a53ae6864182b",
"md5": "79704b1b8ae8a7c2952103cc5d72d5e1",
"sha256": "defdf6414cdfbc384e1bebc87efa24d7097f6d71e6900b76d48a25e04e8e7bfb"
},
"downloads": -1,
"filename": "coloredstrings-3.2.0.tar.gz",
"has_sig": false,
"md5_digest": "79704b1b8ae8a7c2952103cc5d72d5e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 22367,
"upload_time": "2025-10-11T19:49:52",
"upload_time_iso_8601": "2025-10-11T19:49:52.287726Z",
"url": "https://files.pythonhosted.org/packages/98/1d/b5bace2ca58160b5cd72cec030eefd915ab85bbcfaffff5a53ae6864182b/coloredstrings-3.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 19:49:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "samedit66",
"github_project": "coloredstrings",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "coloredstrings"
}
JSON
