Metadata-Version: 2.1
Name: chroma_term_console
Version: 0.1.3
Summary: 轻量级 Python ANSI 终端色彩库，支持 4/8/256 色、24 位真 RGB 色彩与文本样式
Home-page: 
Author: zhenzi0322
Author-email: zhenzi0322 <82131529@qq.com>
License: MIT
Requires-Python: >=3.8
description-content-type: text/markdown
Description:
 
 <p align="center">
   <h1>chroma-term-console</h1>
   <a href="https://pypi.org/project/chroma-term-console/"><img src="https://img.shields.io/pypi/v/chroma-term-console.svg" alt="PyPI version"></a>
   <a href="https://pypi.org/project/chroma-term-console/"><img src="https://img.shields.io/badge/Python-3.8~3.14-3776AB?logo=python&logoColor=white" alt="Python"></a>
   <a href="https://github.com/zhenzi0322-package/chroma-term-console/blob/master/LICENSE"><img src="https://img.shields.io/pypi/l/chroma-term-console.svg" alt="License"></a>
   <a href="https://tool.long920.cn/chroma-term-console"><img src="https://app.readthedocs.org/projects/zhenzi0322-tool/badge/?version=latest" alt="Documentation Status"></a>
 </p>
 
 > 轻量级 `Python ANSI` 终端色彩库，支持 `4/8/256` 色、`24` 位真 `RGB` 色彩与文本样式，用于控制台文本美化。
 
 ## 安装
 
 ```bash
 pip install chroma-term-console
 ```
 
 ## 快速开始
 
 ### Chroma 类（推荐）
 
 最直观的方式，直接 `Chroma.颜色名('文本')` 即可看到彩色输出：
 
 ```python
 from chroma_term_console import Chroma
 
 # 前景色
 print(Chroma.red('错误'))
 print(Chroma.green('成功'))
 print(Chroma.yellow('警告'))
 print(Chroma.blue('信息'))
 print(Chroma.magenta('紫红色'))
 print(Chroma.cyan('青蓝色'))
 
 # 高亮前景色
 print(Chroma.bright_red('高亮红'))
 print(Chroma.bright_green('高亮绿'))
 
 # 背景色
 print(Chroma.bg_red('红色背景'))
 print(Chroma.bg_green('绿色背景'))
 print(Chroma.bg_yellow('黄色背景'))
 
 # 显示方式
 print(Chroma.bold('粗体'))
 print(Chroma.underline('下划线'))
 print(Chroma.blink('闪烁'))
 print(Chroma.reverse('反显'))
 
 # 组合样式
 print(Chroma.bold_red('高亮红色'))
 print(Chroma.bold_green('高亮绿色'))
 print(Chroma.underline_cyan('下划线青蓝'))
 
 # 256 色
 print(Chroma.c256('橙色', fg=208))
 print(Chroma.c256('粉色', fg=213))
 
 # 24 位真彩 RGB
 print(Chroma.rgb('自定义粉', fg=(255, 121, 198)))
 print(Chroma.rgb('暗底亮字', fg=(255, 255, 255), bg=(40, 42, 54)))
 ```
 
 ### 快捷函数
 
 ```python
 from chroma_term_console import fg, bg, style, bold, underline, italic
 
 # 前景色 / 背景色
 print(fg('red', '红色文字'))
 print(bg('blue', '蓝色背景'))
 
 # 文本样式
 print(bold('粗体'))
 print(underline('下划线'))
 print(italic('斜体'))
 
 # 多样式组合
 print(style('重要通知', fg='yellow', bold=True, underline=True))
 ```
 
 ### color 函数（原始 ANSI 码封装）
 
 直接对应 `\033[显示方式;前景色;背景色m***\033[0m` 语法：
 
 ```python
 from chroma_term_console import color, color256, color_rgb
 
 # 基本 4/8 色
 print(color('红色文字', fg=31))
 print(color('高亮绿色', fg=32, mode=1))
 print(color('红字黄底', fg=31, bg=43))
 print(color('高亮蓝字白底', fg=34, bg=47, mode=1))
 
 # 256 色
 print(color256('橙色', fg=208))
 
 # 24 位真彩 RGB
 print(color_rgb('粉色', fg=(255, 121, 198)))
 ```
 
 ### 链式调用（Chroma 语法糖）
 
 `Chroma.样式名('文本')` 返回 `ChromaText` 对象，可直接链式叠加任意颜色与样式，无需嵌套：
 
 ```python
 from chroma_term_console import Chroma
 
 # 样式 + 颜色
 print(Chroma.bold('粗体').red())           # 粗体 + 红色
 print(Chroma.underline('下划线').bg_blue()) # 下划线 + 蓝色背景
 
 # 多重叠加
 print(Chroma.bold('警告').red().blink())    # 粗体 + 红色 + 闪烁
 print(Chroma.italic('提示').cyan().dim())   # 斜体 + 青色 + 暗色
 
 # 链式 + 256 色 / RGB
 print(Chroma.bold('橙色').c256(fg=208))
 print(Chroma.underline('自定义').rgb(fg=(255, 128, 0)))
 
 # 兼容 print / f-string / 字符串拼接
 msg = Chroma.bold('错误').red()
 print(f"结果: {msg}")
 print("前缀 " + msg + " 后缀")
 
 # 获取原始文本
 print(Chroma.bold('hello').red().text)  # 'hello'
 ```
 
 > `ChromaText` 实现了 `__str__` / `__format__` / `__repr__`，可直接用于 `print()`、f-string 和字符串拼接，无需手动转换。
 
 **自动输出**：当表达式结果未被赋值时，`ChromaText` 对象在语句结束后自动打印到终端，无需 `print()`：
 
 ```python
 # 无需 print()，直接自动输出
 Chroma.bold('粗体').red()
 Chroma.italic('提示').cyan().dim()
 
 # 赋值给变量则不自动输出，需手动 print()
 msg = Chroma.bold('粗体').red()
 print(msg)
 ```
 
 ### 链式调用（Styled 类）
 
 ```python
 from chroma_term_console import Styled
 
 s = Styled()
 print(s.fg('green').bold('成功'))
 print(s.fg('#ff79c6').bg('#282a36').italic('Dracula 主题'))
 print(s.fg(196).bold('256色红'))
 print(s.fg((255, 128, 0)).underline('RGB 橙色'))
 ```
 
 ## API 参考
 
 ### Chroma 类方法
 
 | 方法 | 效果 |
 |------|------|
 | `Chroma.black/red/green/yellow/blue/magenta/cyan/white` | 基本 8 色前景 |
 | `Chroma.bright_red/...` | 高亮 8 色前景 |
 | `Chroma.bg_red/...` | 背景色 |
 | `Chroma.bold/underline/blink/reverse/hidden` | 显示方式（返回 `ChromaText`，可链式调用） |
 | `Chroma.bold_red/...` | 高亮 + 颜色组合 |
 | `Chroma.underline_red/...` | 下划线 + 颜色组合 |
 | `Chroma.c256(text, fg=N, bg=N)` | 256 色 |
 | `Chroma.rgb(text, fg=(R,G,B), bg=(R,G,B))` | 24 位真彩 |
 
 ### 颜色码对照表
 
 | 前景色 | 背景色 | 颜色 |
 |--------|--------|------|
 | 30 | 40 | 黑色 |
 | 31 | 41 | 红色 |
 | 32 | 42 | 绿色 |
 | 33 | 43 | 黄色 |
 | 34 | 44 | 蓝色 |
 | 35 | 45 | 紫红色 |
 | 36 | 46 | 青蓝色 |
 | 37 | 47 | 白色 |
 | 90-97 | 100-107 | 高亮色 |
 
 ### 显示方式码
 
 | 码 | 效果 |
 |----|------|
 | 0 | 默认值 |
 | 1 | 高亮/粗体 |
 | 4 | 下划线 |
 | 5 | 闪烁 |
 | 7 | 反显 |
 | 8 | 不可见 |
 
 ## 工具函数
 
 ```python
 from chroma_term_console import strip_ansi, supports_color, detect_color_level
 
 # 移除 ANSI 转义序列
 plain = strip_ansi('\033[31m红色\033[0m')  # '红色'
 
 # 检测终端色彩支持
 level = detect_color_level()  # ColorLevel.NONE / BASIC / EXTENDED / TRUECOLOR
 has_color = supports_color()  # True / False
 ```
 
 ## 终端兼容性
 
 - 自动检测终端色彩能力（真彩 / 256色 / 基本色）
 - 支持 `NO_COLOR` 协议（设置 `NO_COLOR` 环境变量禁用颜色）
 - 支持 `FORCE_COLOR` 环境变量强制启用
 - Windows 10+ / Windows Terminal / ConEmu / ANSICON 自动启用 VT 处理
 - VS Code 集成终端自动启用（VT 优先，失败时回退为 ANSI→Win32 转换）
 - 非 TTY 环境（管道/重定向）自动禁用颜色
 

