color-kiss 0.1.2

A lightweight, zero-dependency ANSI color library for terminal output — no bloat, just colors

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

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)

pip install color-kiss

Via uv

uv pip install color-kiss

Via pipx (isolated environment)

pipx install color-kiss

From source (development)

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

pip

pip install .

uv

uv pip install .

pipx

pipx install .

Usage

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

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

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

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

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

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

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

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

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

from color_kiss import BG_YELLOW, BLACK, BOLD, styled

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

Combining Multiple Styles

from color_kiss import BLUE, UNDERLINE, ITALIC, styled

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

Logging with Colors

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:

import os
os.system('')  # Enables ANSI processing on Windows

Why call it "color-kiss"?

KISS = Keep It Simple, Stupid. 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:

# 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:

# Should display colored text
echo -e "\033[31mRed\033[0m \033[32mGreen\033[0m"

Check Python version:

python --version

📄 License

MIT License — see 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 Repository: github.com/yourusername/color-kiss PyPI: pypi.org/project/color-kiss