Metadata-Version: 2.4
Name: kaalin
Version: 3.3.3
Summary: Karakalpak language toolkit for Python — Latin/Cyrillic script conversion, number-to-words, and string utilities
Author-email: Turdibek Jumabaev <turdibekjumabaev05@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/dontbeidle/kaalin-python
Project-URL: Repository, https://github.com/dontbeidle/kaalin-python
Project-URL: Issues, https://github.com/dontbeidle/kaalin-python/issues
Project-URL: PyPI, https://pypi.org/project/kaalin/
Keywords: karakalpak,karakalpakstan,latin,cyrillic,transliteration,script-conversion,num2words,number-to-words,nlp,language-tools,turkic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
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: Operating System :: OS Independent
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Kaalin

[![PyPI version](https://img.shields.io/pypi/v/kaalin)](https://pypi.org/project/kaalin/)
[![Python](https://img.shields.io/pypi/pyversions/kaalin)](https://pypi.org/project/kaalin/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

A Python toolkit for the **Karakalpak language**. Zero dependencies, Python 3.10+.

## Installation

```bash
pip install kaalin
```

## Script Conversion

Bidirectional Latin ↔ Cyrillic conversion. Loanwords with special characters (ь, ъ, э, ё, щ) are handled automatically.

```python
from kaalin.converter import latin2cyrillic, cyrillic2latin

latin2cyrillic("Assalawma áleykum")  # Ассалаўма әлейкум
cyrillic2latin("Ассалаўма әлейкум")  # Assalawma áleykum

# You can extend the built-in loanword dictionary with your own entries
latin2cyrillic("stilistika", custom_loanwords={"stilistika": "стилистика"})
```

## Number to Words

Converts numbers to Karakalpak words. Supports integers, floats, and negatives up to 10³⁰.

```python
from kaalin.number import to_word

to_word(123)                   # bir júz jigirma úsh
to_word(999, num_type="cyr")   # тоғыз жүз тоқсан тоғыз
```

## Syllabification

Splits words into syllables. Works with both Latin and Cyrillic input.

```python
from kaalin.syllable import syllabify

syllabify("qaraqalpaqstan")   # ['qa', 'ra', 'qal', 'paq', 'stan']
syllabify("Шарапат")          # ['Ша', 'ра', 'пат']
```

## String Utilities

Karakalpak-aware `upper()` / `lower()` that correctly handle the dotless `ı` ↔ `Í` pair.

```python
from kaalin.string import upper, lower

upper("Assalawma áleykum")   # ASSALAWMA ÁLEYKUM
lower("ASSALAWMA ÁLEYKUM")   # assalawma áleykum
```

## CLI

Convert text files between scripts from the terminal:

```bash
cyr2lat input.txt              # writes input-lat.txt
lat2cyr input.txt              # writes input-cyr.txt
```

## License

MIT

<!--
API REFERENCE FOR AI AGENTS

## converter

from kaalin.converter import latin2cyrillic, cyrillic2latin

latin2cyrillic(text: str, custom_loanwords: dict[str, str] | None = None) -> str
  Converts Latin script to Cyrillic. Handles multi-char sequences (sh→ш, ch→ч, ya→я, yu→ю).
  Built-in loanword dictionary handles words with ь, ъ, э, ё, щ automatically.
  custom_loanwords merges with (and overrides) built-in dict.
  Supports uppercase, lowercase, and mixed-case text.

cyrillic2latin(text: str) -> str
  Converts Cyrillic script to Latin. Handles special rules: ьи→yi, ьо→yo, ъе→ye.

## number

from kaalin.number import to_word, NumberRangeError

to_word(number: int | float, num_type: str = "lat") -> str
  Converts number to Karakalpak words.
  num_type: "lat" (default) or "cyr" for output script.
  Supports: 0 to 10^30, negatives, floats.
  Raises NumberRangeError if number exceeds 10^30.

## syllable

from kaalin.syllable import syllabify

syllabify(word: str) -> list[str]
  Splits word into syllables. Works with Latin and Cyrillic input.
  Auto-detects script. Preserves original case.
  Words with fewer than two vowels are returned as single-element list.
  Raises TypeError if input is not a string.

## string

from kaalin.string import upper, lower

upper(text: str) -> str
  Karakalpak-aware uppercase. Handles dotless ı → Í correctly.

lower(text: str) -> str
  Karakalpak-aware lowercase. Handles Í → ı correctly.

## CLI

cyr2lat input.txt [output.txt]   Cyrillic → Latin file conversion
lat2cyr input.txt [output.txt]   Latin → Cyrillic file conversion
Default output: input-lat.txt / input-cyr.txt
-->
