Metadata-Version: 2.4
Name: coloredstrings
Version: 0.1.4
Summary: Colorize Different.
Keywords: ansi,color,colour,crossplatform,terminal,text
Author: samedit66
Author-email: samedit66 <samedit66@yandex.ru>
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Terminals
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: forbiddenfruit>=0.1.4
Maintainer: samedit66
Maintainer-email: samedit66 <samedit66@yandex.ru>
Requires-Python: >=3.9
Project-URL: Bug Tracker, https://github.com/samedit66/coloredstrings/issues
Project-URL: Changelog, https://github.com/samedit66/coloredstrings/releases
Project-URL: Documentation, https://github.com/samedit66/coloredstrings#readme
Project-URL: Homepage, https://github.com/samedit66/coloredstrings
Project-URL: Repository, https://github.com/samedit66/coloredstrings
Description-Content-Type: text/markdown

# coloredstrings [![Python package](https://github.com/samedit66/coloredstrings/actions/workflows/python-package.yml/badge.svg)](https://github.com/samedit66/coloredstrings/actions/workflows/python-package.yml) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/coloredstrings?period=total&units=ABBREVIATION&left_color=BLACK&right_color=MAGENTA&left_text=downloads)](https://pepy.tech/projects/coloredstrings)

**Colorize Different**

A tiny utility that patches Python's built-in str with convenient ANSI color / style helpers so you can write `"hello".red()` instead of juggling escape sequences or long constant concatenations. Inspired by the Rust [text-colorizer](https://crates.io/crates/text-colorizer) crate — ergonomic, expressive, and surprisingly pleasant to type.

---

## Why use this? — Isn't patching `str` un-Pythonic?

Patching builtins is a controversial choice, and at first glance it __may__ look un-Pythonic. Libraries like `colorama` require you to import constants and build strings by concatenation:

```python
# colorama style (typical)
from colorama import Fore, Style
print(Fore.RED + "error: " + Style.RESET_ALL + "something went wrong")
```

That works fine, but it forces you to manage constants and remember to reset, and your code quickly becomes noisy with `+` and `RESET` tokens.

With `coloredstrings` the color becomes a readable method on the string itself:

```python
import coloredstrings
coloredstrings.patch()
print("error:".red(), "something went wrong")
coloredstrings.unpatch()
```

This reads more like natural prose and keeps color usage local to the value being displayed.

---

## Quick start — example usage

To patch globally:

```python
import coloredstrings

# Attach helpers to built-in str
coloredstrings.patch()

print("ok".green())                # green text
print("warn".yellow().bold())      # chained styles (color then bold)
print("bad".red(), "on green".on_green())

# 24-bit RGB:
print("custom".rgb(123, 45, 200))

# 256-color:
print("teal-ish".color256(37))

# When you're done (optional) remove the patched methods:
coloredstrings.unpatch()
```

To patch locally (inside a function or a context):

```python
import coloredstrings

def perror(message: str):
    with coloredstrings.patched():
        print(message.red())

@coloredstrings.patched
def log_info(message: str):
    colored = "INFO".blue()
    print(f"[{colored}]: {message}")

log_info("Downloaded image.")
perror("file not found!")
```
---

## API (high level)

- `patch()` — attach methods to `str`
- `unpatch()` — remove the attached methods
- `patched()` - automatically calls `patch()` and `unpatch()` in a given context

- Color/style methods attached to str (call on any string):
    - Foreground colors: `red()`, `green()`, `yellow()`, `blue()`, `magenta()`, `cyan()`, `white()`, `black()`, `bright_red()`
    - Styles: `bold()`, `dim()`, `italic()`, `underline()`, `inverse()`
    - Background helpers: `on_red()`, `on_green()`
    - 24-bit color: `rgb(r, g, b)`
    - 256-color: `color256(idx)`

---

## Installation

Stable:
```bash
pip install coloredstrings
```

Latest:
```bash
pip install git+https://github.com/samedit66/coloredstrings.git
```

---

## Limitations

Under the hood `coloredstrings` uses `forbiddenfruit` package, as a result it also has the same limitations:

> Forbbiden Fruit is tested on CPython 3.7-3.13.
> Since Forbidden Fruit is fundamentally dependent on the C API, this library won't work on other python implementations, such as Jython, pypy, etc.
