Metadata-Version: 2.4
Name: katzo
Version: 0.1.0
Summary: Utilities for colors and terminal UI
Author: Northkatz
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Northkatz/katzo
Project-URL: Repository, https://github.com/Northkatz/katzo
Project-URL: Issues, https://github.com/Northkatz/katzo/issues
Keywords: terminal,tui,color,ascii,utilities
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: tui
Requires-Dist: Pillow>=9.0; extra == "tui"
Provides-Extra: all
Requires-Dist: Pillow>=9.0; extra == "all"

# katzo

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

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

**Лицензия:** [Apache License 2.0](LICENSE)

## Установка

```bash
pip install katzo
```

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

```bash
pip install katzo[tui]
```

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

```python
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:

```python
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)` | Применить функцию к каналу | — |

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

### `Fade`

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

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

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

### `darker(color, value)`

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

```python
from katzo.color import RED, darker

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

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

```python
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)`

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

```python
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()`):

```python
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-коды при подсчёте длины:

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

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

### `clear()`

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

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

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

```python
from katzo.tui import hline

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

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

### `Cursor`

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

```python
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]` к каждой строке |

```python
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`

```python
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`:

```python
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` |

```python
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)
```

## Версия

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

## Лицензия

Copyright 2026 northkatz

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.
