Metadata-Version: 2.4
Name: color-kiss
Version: 0.1.3
Summary: A lightweight, zero-dependency ANSI color library for terminal output — no bloat, just colors
Requires-Python: >=3.0
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# color-kiss — A lightweight, zero-dependency ANSI color library for terminal output

[![Python](https://img.shields.io/badge/python-3.0+-blue.svg)](https://python.org)
[![PyPI](https://img.shields.io/pypi/v/color-kiss.svg)](https://pypi.org/project/color-kiss/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey)]()

No bloat, no dependencies — just ANSI escape codes and a single helper function. Uses only Python's built-in string formatting.

## ✨ Features

- **Zero Dependencies** — Uses only Python standard library
- **Full ANSI Spectrum** — 8 regular + 8 bright foreground colors
- **Background Colors** — 8 regular + 8 bright background colors
- **Text Styles** — Bold, dim, italic, underline, blink, reverse, hidden, strikethrough
- **Auto-reset Helper** — `styled()` applies styles and resets automatically
- **Convenience Aliases** — `GRAY` and `BG_GRAY` for readability
- **Cross-platform** — Works anywhere ANSI is supported (Linux, macOS, Windows Terminal)

## 🚀 Quick Start

### Prerequisites
- Python 3.0+

### Installation

#### Via pip (recommended)
```bash
pip install color-kiss
```

#### Via uv
```bash
uv pip install color-kiss
```

#### Via pipx (isolated environment)
```bash
pipx install color-kiss
```

#### From source (development)

```bash
git clone https://github.com/yourusername/color-kiss.git && cd color-kiss
```

**pip**
```bash
pip install .
```

**uv**
```bash
uv pip install .
```
**pipx**
```bash
pipx install .
```

### Usage
```python
from color_kiss import RED, GREEN, BOLD, styled

# Manual color codes
print(f"{RED}Error:{RESET} Something went wrong")
print(f"{GREEN}Success:{RESET} Operation completed")

# Auto-reset helper
print(styled("Hello, World!", BOLD, GREEN))
print(styled("Warning!", BOLD, YELLOW, BG_BLACK))
```

## 📋 Reference

### Text Styles
```python
from color_kiss import BOLD, DIM, ITALIC, UNDERLINE, BLINK, REVERSE, HIDDEN, STRIKETHROUGH

print(f"{BOLD}Bold{RESET} {DIM}Dim{RESET} {ITALIC}Italic{RESET}")
print(f"{UNDERLINE}Underline{RESET} {BLINK}Blink{RESET}")
print(f"{REVERSE}Reverse{RESET} {HIDDEN}Hidden{RESET} {STRIKETHROUGH}Strikethrough{RESET}")
```

| Code | ANSI | Effect |
|------|------|--------|
| `BOLD` | `\033[1m` | Bold text |
| `DIM` | `\033[2m` | Dim/faint text |
| `ITALIC` | `\033[3m` | Italic text |
| `UNDERLINE` | `\033[4m` | Underlined text |
| `BLINK` | `\033[5m` | Blinking text |
| `REVERSE` | `\033[7m` | Swapped fg/bg |
| `HIDDEN` | `\033[8m` | Hidden text |
| `STRIKETHROUGH` | `\033[9m` | Strikethrough text |

### Foreground Colors
```python
from color_kiss import BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE

# Regular colors
print(f"{RED}Red{RESET} {GREEN}Green{RESET} {BLUE}Blue{RESET}")
print(f"{YELLOW}Yellow{RESET} {MAGENTA}Magenta{RESET} {CYAN}Cyan{RESET}")
print(f"{BLACK}Black{RESET} {WHITE}White{RESET}")
```

| Code | ANSI | Preview |
|------|------|---------|
| `BLACK` | `\033[30m` | Black |
| `RED` | `\033[31m` | Red |
| `GREEN` | `\033[32m` | Green |
| `YELLOW` | `\033[33m` | Yellow |
| `BLUE` | `\033[34m` | Blue |
| `MAGENTA` | `\033[35m` | Magenta |
| `CYAN` | `\033[36m` | Cyan |
| `WHITE` | `\033[37m` | White |

### Bright Foreground Colors
```python
from color_kiss import BRIGHT_RED, BRIGHT_GREEN, BRIGHT_BLUE, GRAY

# Bright colors + aliases
print(f"{BRIGHT_RED}Bright Red{RESET} {BRIGHT_GREEN}Bright Green{RESET}")
print(f"{GRAY}Gray (alias for BRIGHT_BLACK){RESET}")
```

| Code | ANSI | Preview |
|------|------|---------|
| `BRIGHT_BLACK` | `\033[90m` | Bright Black |
| `BRIGHT_RED` | `\033[91m` | Bright Red |
| `BRIGHT_GREEN` | `\033[92m` | Bright Green |
| `BRIGHT_YELLOW` | `\033[93m` | Bright Yellow |
| `BRIGHT_BLUE` | `\033[94m` | Bright Blue |
| `BRIGHT_MAGENTA` | `\033[95m` | Bright Magenta |
| `BRIGHT_CYAN` | `\033[96m` | Bright Cyan |
| `BRIGHT_WHITE` | `\033[97m` | Bright White |
| `GRAY` | *alias* | → `BRIGHT_BLACK` |

### Background Colors
```python
from color_kiss import BG_RED, BG_GREEN, BG_BLUE, BG_YELLOW

# Regular backgrounds
print(f"{BG_RED} Red Background {RESET}")
print(f"{BG_GREEN} Green Background {RESET}")
print(f"{BG_YELLOW}{BLACK} Yellow BG + Black Text {RESET}")
```

| Code | ANSI | Preview |
|------|------|---------|
| `BG_BLACK` | `\033[40m` | Black background |
| `BG_RED` | `\033[41m` | Red background |
| `BG_GREEN` | `\033[42m` | Green background |
| `BG_YELLOW` | `\033[43m` | Yellow background |
| `BG_BLUE` | `\033[44m` | Blue background |
| `BG_MAGENTA` | `\033[45m` | Magenta background |
| `BG_CYAN` | `\033[46m` | Cyan background |
| `BG_WHITE` | `\033[47m` | White background |

### Bright Background Colors
```python
from color_kiss import BG_BRIGHT_RED, BG_BRIGHT_GREEN, BG_GRAY

# Bright backgrounds + aliases
print(f"{BG_BRIGHT_RED} Bright Red BG {RESET}")
print(f"{BG_GRAY} Gray BG (alias for BG_BRIGHT_BLACK) {RESET}")
```

| Code | ANSI | Preview |
|------|------|---------|
| `BG_BRIGHT_BLACK` | `\033[100m` | Bright black BG |
| `BG_BRIGHT_RED` | `\033[101m` | Bright red BG |
| `BG_BRIGHT_GREEN` | `\033[102m` | Bright green BG |
| `BG_BRIGHT_YELLOW` | `\033[103m` | Bright yellow BG |
| `BG_BRIGHT_BLUE` | `\033[104m` | Bright blue BG |
| `BG_BRIGHT_MAGENTA` | `\033[105m` | Bright magenta BG |
| `BG_BRIGHT_CYAN` | `\033[106m` | Bright cyan BG |
| `BG_BRIGHT_WHITE` | `\033[107m` | Bright white BG |
| `BG_GRAY` | *alias* | → `BG_BRIGHT_BLACK` |

### Helper Function
```python
from color_kiss import styled, RED, BOLD, BG_YELLOW

# Apply multiple styles at once
print(styled("Error!", RED, BOLD))
print(styled("Warning!", BG_YELLOW, BLACK, BOLD))

# Returns plain string — safe for logging, formatting, etc.
msg = styled("Done", GREEN, BOLD)
print(f"[{msg}] Operation complete")
```

| Function | Description |
|----------|-------------|
| `styled(text, *styles)` | Apply any number of styles to `text`, auto-append `RESET` |

## 📖 Examples

### Basic Error Messages
```python
from color_kiss import RED, BOLD, styled

# Simple error
print(f"{RED}✗{RESET} File not found")

# With styled()
print(styled("✗ Fatal error: disk full", RED, BOLD))
```

### Status Output
```python
from color_kiss import GREEN, YELLOW, CYAN, styled

print(styled("✓ Build successful", GREEN))
print(styled("⚠ Low disk space", YELLOW))
print(styled("ℹ Processing file 3/10...", CYAN))
```

### Highlighted Warnings
```python
from color_kiss import BG_YELLOW, BLACK, BOLD, styled

print(styled(" WARNING: Unsaved changes! ", BG_YELLOW, BLACK, BOLD))
```

### Combining Multiple Styles
```python
from color_kiss import BLUE, UNDERLINE, ITALIC, styled

print(styled("Click here for documentation", BLUE, UNDERLINE, ITALIC))
```

### Logging with Colors
```python
from color_kiss import RED, YELLOW, GREEN, CYAN, styled
import sys

def log(level, msg):
    colors = {
        "ERROR": (RED,),
        "WARN": (YELLOW,),
        "INFO": (GREEN,),
        "DEBUG": (CYAN,),
    }
    print(styled(f"[{level}]", *colors[level]), msg)

log("ERROR", "Connection refused")
log("INFO", "Server started on port 8080")
log("DEBUG", "Request payload: 256 bytes")
```

## 📁 Project Structure
```
color-kiss/
├── color_kiss/
│   ├── __init__.py          # ANSI color constants + styled() helper
├── pyproject.toml           # Project metadata (zero dependencies)
├── README.md                # Project documentation
└── LICENSE                  # MIT License
```

## 🔧 Requirements

| Dependency | Purpose |
|------------|---------|
| **Python 3.0+** | That's it — no external dependencies |

## ❓ FAQ

### Why another color library when rich/colorama exist?

`color-kiss` is for when you want ANSI colors without pulling in a dependency tree. `rich` is a full terminal UI framework (~10+ dependencies). `colorama` handles Windows ANSI compatibility but adds an import. `color-kiss` is **zero bytes beyond Python's stdlib** — it's just string constants.

### Does this work on Windows?

Yes, on any modern Windows terminal that supports ANSI escape codes:
- **Windows Terminal** (recommended) — full support
- **ConEmu, Cmder** — full support
- **PowerShell 5.1+** — full support
- **Legacy `cmd.exe`** — partial support (Windows 10+ with VT100 enabled)

For Windows <10, use `colorama` or enable VT100 mode:
```python
import os
os.system('')  # Enables ANSI processing on Windows
```

### Why call it "color-kiss"?

KISS = **K**eep **I**t **S**imple, **S**tupid. This library does one thing — terminal colors — and nothing else.

### Why use string constants instead of functions?

Constants are:
- **Faster** — no function call overhead
- **Composable** — use with f-strings, `.format()`, `%` formatting
- **Transparent** — you see exactly what's being output
- **Flexible** — mix styles without API constraints

The `styled()` helper is available when you want auto-reset convenience.

### What about 24-bit (True Color) support?

`color-kiss` intentionally sticks to the 16 standard ANSI colors + 16 background colors (32 total) supported by virtually all terminals since the 1990s. For 24-bit color, consider `rich` or write raw escape sequences:
```python
# 24-bit RGB (not supported by color-kiss)
print(f"\033[38;2;255;100;0mOrange text\033[0m")
```

## 🐛 Troubleshooting

| Issue | Solution |
|-------|----------|
| **Colors not showing** | Ensure your terminal supports ANSI (try Windows Terminal, iTerm2, or any Linux terminal) |
| **Styles not working** | Not all terminals support every style — `BOLD` is universally supported, `BLINK` and `ITALIC` less so |
| **Colors bleed into next lines** | Always use `RESET` after colored text, or use `styled()` which does this automatically |

---

### Still stuck?
Verify your terminal supports ANSI:
```bash
# Should display colored text
echo -e "\033[31mRed\033[0m \033[32mGreen\033[0m"
```

Check Python version:
```bash
python --version
```

## 📄 License

MIT License — see [LICENSE](LICENSE) file.

## ⚠️ Disclaimer

This is a straightforward utility library. ANSI escape codes are a decades-old standard — no magic, no hacks, just string constants. Use responsibly in your terminal output.

---

**Author:** [Your Name](https://github.com/yourusername)
**Repository:** [github.com/yourusername/color-kiss](https://github.com/yourusername/color-kiss)
**PyPI:** [pypi.org/project/color-kiss](https://pypi.org/project/color-kiss/)
