# adyghe-latin-utils

[![Версия PyPI](https://img.shields.io/pypi/v/adyghe-latin-utils)](https://pypi.org/project/adyghe-latin-utils/)
[![Python](https://img.shields.io/pypi/pyversions/adyghe-latin-utils)](https://pypi.org/project/adyghe-latin-utils/)
[![Лицензия: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

🌐 [English](https://github.com/showgan/adyghe-latin-utils/blob/main/README.md) | [Türkçe](https://github.com/showgan/adyghe-latin-utils/blob/main/README.tr.md) | **Русский** | [עברית](https://github.com/showgan/adyghe-latin-utils/blob/main/README.he.md)

Утилиты на Python для **адыгейского** (западночеркесского) языка — **конвертация между кириллическим и латинским алфавитами** и **преобразование чисел в слова**.

## Об адыгейском языке

[Адыгейский язык](https://ru.wikipedia.org/wiki/%D0%90%D0%B4%D1%8B%D0%B3%D0%B5%D0%B9%D1%81%D0%BA%D0%B8%D0%B9_%D1%8F%D0%B7%D1%8B%D0%BA) (адыгабзэ / adıǵabze) — северокавказский язык, на котором говорят около 600 000 человек, преимущественно в Республике Адыгея (Россия), Турции, Иордании, Сирии и в диаспорных общинах по всему миру. Код языка по ISO 639-3 — **ady**.

Адыгейский язык традиционно записывается кириллицей (с 1938 года). Также существует официальный латинский адыгейский алфавит. Данный пакет предоставляет инструменты для конвертации между этими двумя официальными алфавитами, а также для преобразования чисел в адыгейские слова.

## Возможности

- **Кириллица → Латиница** — контекстно-зависимая конвертация между официальными кириллическим и латинским адыгейскими алфавитами с обработкой составных символов (гу, гъ, дж, дз, жь, кӀ, ку, шъ и др.)
- **Латиница → Кириллица** — обратная конвертация с правилами вставки гласных и палочки (Ӏ)
- **Числа в слова** — преобразование целых чисел (от 0 до 10¹⁵) в адыгейские слова с использованием **современной десятичной (по основанию 10) системы**
- **Числа в тексте** — обнаружение и преобразование 12 типов числовых шаблонов в смешанном тексте:
  телефонные номера, валюты ($), проценты (%), диапазоны (7-12), десятичные дроби (5.11),
  римские цифры (IV), числа со знаком (+14, -32) и многое другое
- **Регистр символов** — верхний, нижний регистр и капитализация с корректной обработкой
  специальных латинских символов (İ/ı) и кириллической палочки (Ӏ)
- **Определение алфавита** — определение, написан ли текст на кириллическом адыгейском
- **Инструменты CLI** — утилиты командной строки для пакетной конвертации файлов с поддержкой многопроцессорной обработки

## Установка

```bash
pip install adyghe-latin-utils
```

Или с помощью [uv](https://docs.astral.sh/uv/):

```bash
uv add adyghe-latin-utils
```

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

### Конвертация алфавитов

```python
from adyghe_latin_utils import AdigaCharacterUtils

utils = AdigaCharacterUtils()

# Из кириллицы в латиницу
utils.cyrillic_to_latin("гупшысэ")        # → "ǵupşıśé"
utils.cyrillic_to_latin("лъэхъаным")      # → "ĺéḣáním"
utils.cyrillic_to_latin("къещхы")          # → "kéşḣı"

# Из латиницы в кириллицу
utils.latin_to_cyrillic("selam")           # → "сэлам"
utils.latin_to_cyrillic("adıǵe")          # → "адыгэ"

# Определение алфавита
utils.is_cyrillic_adyghe("гупшысэ")       # → True
utils.is_cyrillic_adyghe("ǵupşıśé")      # → False
```

### Числа в слова

Данная библиотека использует **современную десятичную (по основанию 10) систему** для преобразования чисел в слова.
Традиционно в адыгейском языке используется **двадцатеричная (вигезимальная, по основанию 20)** система счисления, аналогичная французской
(например, французское *soixante-douze* = 60 + 12 для числа «72»). В традиционной адыгейской системе
«72» — это *ṫoćişıre ṫure* (примерно «три-двадцатки-и-двенадцать»). Современное употребление
сместилось в сторону более простой **десятичной (по основанию 10)** системы:

| Число | Современная десятичная (эта библиотека) | Традиционная двадцатеричная (не поддерживается) |
|-------|----------------------------------------|-------------------------------------------------|
| 72    | blıć ṫu (7 десятков и 2)               | ṫoćişıre ṫure (3×20 + 12)                      |

```python
from adyghe_latin_utils import AdigaNumberUtils

AdigaNumberUtils.number_to_words(5)        # → "tfı"
AdigaNumberUtils.number_to_words(42)       # → "pĺ'ıć ṫu"
AdigaNumberUtils.number_to_words(100)      # → "şe"
AdigaNumberUtils.number_to_words(1000)     # → "min"
AdigaNumberUtils.number_to_words(2025)     # → "ṫu min ṫuć tfı"
```

### Числа в смешанном тексте

```python
from adyghe_latin_utils import AdigaNumberUtils

AdigaNumberUtils.convert_numbers_in_text("глава 3")
# → "глава şı"

AdigaNumberUtils.convert_numbers_in_text("агент 007")
# → "агент ziy ziy blı"

AdigaNumberUtils.convert_numbers_in_text("год 2025")
# → "год ṫu min ṫuć tfı"
```

### Регистр символов

```python
from adyghe_latin_utils import AdigaCharacterUtils

utils = AdigaCharacterUtils()

# Латинский текст
utils.to_lowercase("ADIGE", is_latin=True, is_cyrillic=False)
utils.to_uppercase("adıǵe", is_latin=True, is_cyrillic=False)
utils.capitalize("adıǵe", is_latin=True, is_cyrillic=False)

# Упрощение специальных латинских символов до базовых английских
utils.special_chars_to_english_chars("ǵupşıśé")  # → "gupsise"
```

## Использование CLI

С пакетом устанавливаются два инструмента командной строки:

### Конвертация алфавитов

```bash
# Из кириллицы в латиницу (файл в файл)
adyghe-char-convert -i input.txt -o output.txt -d c2l

# Из латиницы в кириллицу (файл в stdout)
adyghe-char-convert -i input.txt -d l2c

# Параметры:
#   -i, --input      Путь к входному файлу (обязательно)
#   -o, --output     Путь к выходному файлу (по умолчанию: stdout)
#   -d, --direction  c2l (Кириллица→Латиница) или l2c (Латиница→Кириллица) (обязательно)
```

CLI конвертации алфавитов поддерживает **многопроцессорную обработку** для больших файлов и отображает индикатор прогресса.

### Конвертация чисел

```bash
# Преобразование чисел в текстовой строке
adyghe-num-convert -t "глава 3"

# Преобразование чисел в файле
adyghe-num-convert -i input.txt -o output.txt

# Параметры:
#   -t, --text    Входная текстовая строка (взаимоисключающий с -i)
#   -i, --input   Путь к входному файлу (взаимоисключающий с -t)
#   -o, --output  Путь к выходному файлу (по умолчанию: stdout)
```

## Справочник API

### `AdigaCharacterUtils`

| Метод | Описание |
|-------|----------|
| `cyrillic_to_latin(text: str) -> str` | Конвертация кириллического адыгейского текста в латиницу |
| `latin_to_cyrillic(text: str) -> str` | Конвертация латинского адыгейского текста в кириллицу |
| `is_cyrillic_adyghe(text: str, threshold: float = 0.5) -> bool` | Определение, является ли текст кириллическим адыгейским |
| `to_lowercase(text, is_latin, is_cyrillic) -> str` | Нижний регистр с учётом алфавита |
| `to_uppercase(text, is_latin, is_cyrillic) -> str` | Верхний регистр с учётом алфавита |
| `capitalize(text, is_latin, is_cyrillic) -> str` | Капитализация первого символа |
| `special_chars_to_english_chars(text: str) -> str` | Упрощение диакритических латинских символов до ASCII |
| `cyrillic_extra_chars_to_basic_chars(text: str) -> str` | Нормализация вариантов кириллических символов |

### `AdigaNumberUtils`

| Метод | Описание |
|-------|----------|
| `number_to_words(number: int) -> str` | Преобразование целого числа (0–10¹⁵) в адыгейские слова |
| `convert_numbers_in_text(text: str) -> str` | Поиск и преобразование всех числовых шаблонов в тексте |

## Поддерживаемые числовые шаблоны

`convert_numbers_in_text()` распознаёт и преобразует следующие шаблоны:

| Шаблон | Пример | Описание |
|--------|--------|----------|
| Международный телефон | `+972-58-206-2315` | Цифры читаются по одной |
| Местный телефон | `058-206-2315` | Цифры читаются по одной |
| Префикс-тире | `ya-20` | Число преобразуется, префикс сохраняется |
| Постфикс-тире | `13-re` | Число преобразуется, постфикс сохраняется |
| Сумма в долларах | `$16,918` | Полное преобразование числа |
| Число со знаком | `+14`, `-32` | Знак сохраняется, число преобразуется |
| Диапазон | `1042-1814` | Каждое число преобразуется отдельно |
| Десятичное | `5.11`, `50.06%` | Целая и дробная части преобразуются |
| Через косую | `2010/11` | Каждая часть преобразуется |
| Символ-постфикс | `4%`, `804+` | Число преобразуется, символ сохраняется |
| Римская цифра | `III`, `IV` | Преобразуется в арабскую, затем в слова |
| Простое число | `42`, `1,000,000` | Полное преобразование числа |

## Разработка

```bash
# Клонирование репозитория
git clone https://github.com/showgan/adyghe-latin-utils.git
cd adyghe-latin-utils

# Настройка среды разработки
uv venv
uv pip install -e ".[dev]"

# Запуск тестов
uv run pytest tests/ -v
```

## Лицензия

Этот проект лицензирован под лицензией MIT — подробности см. в файле [LICENSE](LICENSE).
