Metadata-Version: 2.4
Name: larzcolor
Version: 0.1.0
Summary: Terminal color and style that auto-disables on non-TTY/NO_COLOR, so escape codes never leak into pipes or logs. Pure Python, zero dependencies.
Author: larz-scripter
License: MIT
Project-URL: Homepage, https://github.com/larz-scripter/larzcolor
Project-URL: Repository, https://github.com/larz-scripter/larzcolor
Project-URL: Documentation, https://github.com/larz-scripter/larzcolor#readme
Project-URL: Issues, https://github.com/larz-scripter/larzcolor/issues
Keywords: color,colour,terminal,ansi,console,styling,tty,no-color,cli,zero-dependency,pure-python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Terminals
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# larzcolor

**Terminal colour that knows when to stay quiet. Pure Python, zero dependencies.**

Colour and style for the terminal, with the thing most helpers get wrong handled
for you: it **auto-disables when the output isn't a terminal** (or `NO_COLOR` is
set, or `TERM=dumb`) — so your logs and piped output never fill up with
`\x1b[31m` escape-code garbage.

```python
from larzcolor import red, green, bold, style

print(red("error"))            # coloured in a terminal, plain when piped to a file
print(bold(green("ok")))       # styles nest correctly
print(style("hi", fg="cyan", bg="white", underline=True))
print(style("warn", fg=(255, 165, 0)))   # truecolor RGB
```

## What makes it different

- **Respects the environment automatically.** Colour is emitted only when stdout
  is a TTY, `NO_COLOR` isn't set, and `TERM` isn't `dumb` — with `FORCE_COLOR` to
  override. Pipe your program into a file or `grep` and the output is clean text,
  no manual `if sys.stdout.isatty()` dance.
- **Nesting just works.** `bold(red(x))` re-applies the outer style after the
  inner reset, so combinations don't fall apart.
- **All the colour depths.** Basic + bright named colours, 256-colour (`fg=39`),
  and truecolor (`fg=(r, g, b)`), foreground and background.
- **Zero dependencies.** No `colorama`, no `rich`.

## Install

```bash
pip install larzcolor
```

## Usage

```python
from larzcolor import style, red, green, yellow, bold, underline, strip, cprint

red("err"); green("ok"); yellow("warn")
bold("strong"); underline("link")
style("text", fg="magenta", bg="black", bold=True, italic=True)
style("x", fg=196)              # 256-colour
style("x", fg=(0, 200, 120))    # truecolor

cprint("styled print", fg="cyan", bold=True)
strip("\x1b[31mred\x1b[0m")     # 'red'  — remove ANSI from any string
```

Force behaviour when you need to (tests, `--color=always`):

```python
from larzcolor import set_enabled
set_enabled(True)    # or False, or None for auto
```

## Tests

```bash
python -m unittest discover -s tests -v   # 17 tests incl. detection + no-leak guarantee
```

## The Larz stack

Pure-Python, zero-dependency building blocks: **[larz](https://github.com/larz-scripter/larz)** · **[larzchain](https://github.com/larz-scripter/larzchain)** · **[larzmoney](https://github.com/larz-scripter/larzmoney)** · **[larzcrypt](https://github.com/larz-scripter/larzcrypt)** · **[larzdb](https://github.com/larz-scripter/larzdb)** · **[larzagent](https://github.com/larz-scripter/larzagent)** · **[larzchart](https://github.com/larz-scripter/larzchart)** · **[larzmark](https://github.com/larz-scripter/larzmark)** · **[larztask](https://github.com/larz-scripter/larztask)** · **[larzvault](https://github.com/larz-scripter/larzvault)** · **[larzvm](https://github.com/larz-scripter/larzvm)** · **[larzcache](https://github.com/larz-scripter/larzcache)** · **[larzvalidate](https://github.com/larz-scripter/larzvalidate)** · **[larzid](https://github.com/larz-scripter/larzid)** · **[larzrpc](https://github.com/larz-scripter/larzrpc)** · **[larzstate](https://github.com/larz-scripter/larzstate)** · **[larzhttp](https://github.com/larz-scripter/larzhttp)** · **[larzconf](https://github.com/larz-scripter/larzconf)** · **[larzcron](https://github.com/larz-scripter/larzcron)** · **[larzlimit](https://github.com/larz-scripter/larzlimit)** · **[larzlog](https://github.com/larz-scripter/larzlog)** · **[larzcli](https://github.com/larz-scripter/larzcli)** · **[larzretry](https://github.com/larz-scripter/larzretry)** · **[larztime](https://github.com/larz-scripter/larztime)** · **[larzpdf](https://github.com/larz-scripter/larzpdf)** · **[larzpack](https://github.com/larz-scripter/larzpack)** · **[larztemplate](https://github.com/larz-scripter/larztemplate)** · **larzcolor**

## License

MIT © larz-scripter
