katzo

Лёгкая Python-библиотека для цветного вывода в терминале: работа с цветами, градиентный текст, ASCII-изображения и цветной логгер.

Требования: Python 3.10+

Лицензия: Apache License 2.0

Установка

pip install katzo

Для отображения изображений в терминале установите опциональную зависимость Pillow:

pip install katzo[tui]

Быстрый старт

from katzo.color import RED, BLUE, Fade
from katzo.tui import gradient_text, centralize, clear
from katzo.logger import Logger

clear()

fade = Fade(RED, BLUE, RED).generate(20)
print(centralize(gradient_text("Hello, katzo!", fade)))

log = Logger(show_time=True)
log.success("Ready")

---

katzo.color

Модуль для создания и преобразования цветов.

Color

Создание цвета из HEX, RGB или HSV:

from katzo.color import Color

Color(hex="#ff0000")
Color(hex="f00")              # короткая запись
Color(rgb=(255, 128, 0))
Color(hsv=(0.0, 1.0, 1.0))    # h, s, v в диапазоне 0.0–1.0

Методы:

Метод	Описание	Пример результата
hex()	HEX-строка	"#ff0000"
rgb()	Кортеж RGB	(255, 0, 0)
hsv()	Кортеж HSV	(0.0, 1.0, 1.0)
append(canal, value)	Изменить канал на месте	—
append_multi(canals, value)	Изменить несколько каналов	—
use(canal, func)	Применить функцию к каналу	—

color = Color(hex="#808080")
color.append(0, 20)           # увеличить красный канал
color.use(1, lambda x: x // 2)

Fade

Генерация плавного перехода между цветами:

from katzo.color import Fade, RED, GREEN, BLUE

fade = Fade(RED, GREEN, BLUE)
colors = fade.generate(15)    # список из 15 объектов Color

darker(color, value)

Возвращает новый более тёмный цвет, не изменяя исходный:

from katzo.color import RED, darker

dark_red = darker(RED, 50)
RED.rgb()       # (255, 0, 0) — не изменился
dark_red.rgb()  # (205, 0, 0)

Предустановленные цвета

from katzo.color import (
    WHITE, BLACK, RED, GREEN, BLUE,
    YELLOW, ORANGE, PINK, PURPLE, HOT_PINK, AQUA,
)

PINK2 — устаревший алиас для HOT_PINK.

---

katzo.tui

Утилиты для работы с терминалом. Используют 24-bit ANSI-цвета (\033[38;2;...).

colorize_onecolor(text, color)

Раскрашивает строку одним цветом:

from katzo.tui import colorize_onecolor
from katzo.color import GREEN

print(colorize_onecolor("Success!", GREEN))

gradient_text(text, fade_colors, skip_spaces=False)

Градиентный текст. Принимает список объектов Color (например, из Fade.generate()):

from katzo.tui import gradient_text
from katzo.color import Fade, RED, BLUE

fade = Fade(RED, BLUE).generate(len("Hello"))
print(gradient_text("Hello", fade))

# Пробелы без раскраски:
print(gradient_text("a b c", fade, skip_spaces=True))

centralize(text, text_length=None)

Центрирует текст по ширине терминала. Учитывает ANSI-коды при подсчёте длины:

from katzo.tui import centralize, colorize_onecolor
from katzo.color import RED

line = colorize_onecolor("Title", RED)
print(centralize(line))

clear()

Очищает экран терминала (кроссплатформенно через ANSI).

hline(symbol="█")

Печатает горизонтальную линию на всю ширину терминала:

from katzo.tui import hline

hline()           # ████████████████████
hline(symbol="-") # --------------------

split — устаревший алиас для hline.

Cursor

Скрытие и показ курсора. Работает на Windows и POSIX:

from katzo.tui import Cursor

cursor = Cursor()
cursor.hide()
# ... анимация или отрисовка ...
cursor.show()

---

katzo.logger

Цветной логгер для CLI-приложений. Выводит сообщения в терминал и опционально дублирует в стандартный модуль logging.

Logger(logger=None, show_time=False)

Параметр	Описание
logger	Объект logging.Logger для записи в файл/журнал
show_time	Добавлять время [HH:MM:SS] к каждой строке

from katzo.logger import Logger

log = Logger(show_time=True)

log.info("Starting application")
log.success("Connection established")
log.notice("Configuration loaded")
log.warning("Deprecated option used")
log.error("File not found")
log.critical("Database unavailable")
log.fatal("Unrecoverable error")
log.debug("Variable x = 42")

Интеграция с logging

import logging
from katzo.logger import Logger

backend = logging.getLogger("myapp")
backend.setLevel(logging.DEBUG)
backend.addHandler(logging.FileHandler("app.log"))

log = Logger(logger=backend, show_time=True)
log.error("This appears in terminal and in app.log")

LogType

Перечисление типов сообщений с привязкой к цвету и уровню logging:

from katzo.logger import Logger, LogType

log = Logger()
log.log(LogType.NOTICE, "Custom notice")

Тип	Цвет	Уровень logging
INFO	синий	INFO
SUCCESS	зелёный	INFO
NOTICE	голубой	INFO
WARNING	жёлтый	WARNING
ERROR	красный	ERROR
CRITICAL	тёмно-красный	CRITICAL
FATAL	очень тёмно-красный	CRITICAL
DEBUG	белый	DEBUG

---

katzo.tui.ascii_image

Отображение изображений в терминале цветными блоками █.

Требует: pip install katzo[tui] (Pillow)

AsciiImage(img, size=None, *, resizes=None)

Параметр	Описание
img	Путь к файлу изображения
size	Кортеж (ширина, высота) в символах
resizes	Устаревший алиас для size

from katzo.tui.ascii_image import AsciiImage

img = AsciiImage("photo.png", size=(80, 40))
print(img.draw())

# Чёрные пиксели как пробелы:
print(img.draw(ignore_black=True))

---

Структура пакета

katzo/
├── __init__.py          # __version__
├── color.py             # Color, Fade, presets
├── logger.py            # Logger, LogType
└── tui/
    ├── __init__.py      # gradient_text, clear, Cursor, ...
    └── ascii_image.py   # AsciiImage (Pillow)

Версия

import katzo
print(katzo.__version__)  # "0.1.0"

Лицензия

Copyright 2026 northkatz

Licensed under the Apache License, Version 2.0. See LICENSE for details.