uzkit 0.1.0__tar.gz

uzkit-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,21 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  pytest:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest

uzkit-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+build/
+dist/
+.DS_Store

uzkit-0.1.0/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "python-envs.defaultEnvManager": "ms-python.python:system"
+}

uzkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uzkit-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: uzkit
+Version: 0.1.0
+Summary: O'zbek tili va ma'lumotlari uchun Python kutubxonasi: transliteratsiya, raqamlarni so'zga aylantirish, so'm summalari, telefon va avtoraqam validatorlari, viloyatlar.
+Project-URL: Homepage, https://github.com/Mr-Ali-web/Uzkit
+Project-URL: Issues, https://github.com/Mr-Ali-web/Uzkit/issues
+Author: Ali
+License: MIT
+License-File: LICENSE
+Keywords: license-plate,numbers,phone,transliteration,uzbek,uzbekistan,validators
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![tests](https://github.com/Mr-Ali-web/uzkit/actions/workflows/tests.yml/badge.svg)](https://github.com/Mr-Ali-web/uzkit/actions/workflows/tests.yml)
+
+# uzkit
+
+O'zbek tili va ma'lumotlari uchun yordamchi Python kutubxonasi.  
+Small Python library for Uzbek language and data helpers.
+
+## O'rnatish / Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Misollar / Examples
+
+```python
+from uzkit import to_cyrillic, to_latin, number_to_words, money_to_words, format_money, normalize_phone, is_valid_phone, is_valid_plate, ordinal
+
+to_cyrillic("Salom, dunyo!")      # 'Салом, дунё!'
+to_latin("Салом, дунё!")          # 'Salom, dunyo!'
+number_to_words(1250)              # 'bir ming ikki yuz ellik'
+money_to_words(1250)               # 'bir ming ikki yuz ellik soʻm'
+format_money(1250000)              # '1 250 000 soʻm'
+normalize_phone("+998 90 123 45 67")  # '+998901234567'
+is_valid_phone("+998 90 123 45 67")   # True
+is_valid_plate("01A123BC")         # True
+ordinal(3)                         # 'uchinchi'
+```
+
+## Testlar / Tests
+
+```bash
+pytest
+```
+
+## Cheklovlar / Limitations
+
+- Telefon kodlari Wikipedia va operator sahifalariga asoslangan, regulyatorning rasmiy hujjati bilan tekshirilmagan.
+- Faqat mobil raqamlar qo'llab-quvvatlanadi.
+- Viloyatlar ro'yxati Wikipedia/ISO 3166-2:UZ manbalariga asoslangan; rasmiy davlat manbasi bilan to'liq solishtirilmagan.
+
+Operator and region codes are not verified against an official source. Only mobile phone numbers are supported.
+Region list is based on Wikipedia/ISO 3166-2:UZ and has not been fully reconciled with official government sources.# Uzkit

uzkit-0.1.0/README.md

@@ -0,0 +1,43 @@
+[![tests](https://github.com/Mr-Ali-web/uzkit/actions/workflows/tests.yml/badge.svg)](https://github.com/Mr-Ali-web/uzkit/actions/workflows/tests.yml)
+
+# uzkit
+
+O'zbek tili va ma'lumotlari uchun yordamchi Python kutubxonasi.  
+Small Python library for Uzbek language and data helpers.
+
+## O'rnatish / Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Misollar / Examples
+
+```python
+from uzkit import to_cyrillic, to_latin, number_to_words, money_to_words, format_money, normalize_phone, is_valid_phone, is_valid_plate, ordinal
+
+to_cyrillic("Salom, dunyo!")      # 'Салом, дунё!'
+to_latin("Салом, дунё!")          # 'Salom, dunyo!'
+number_to_words(1250)              # 'bir ming ikki yuz ellik'
+money_to_words(1250)               # 'bir ming ikki yuz ellik soʻm'
+format_money(1250000)              # '1 250 000 soʻm'
+normalize_phone("+998 90 123 45 67")  # '+998901234567'
+is_valid_phone("+998 90 123 45 67")   # True
+is_valid_plate("01A123BC")         # True
+ordinal(3)                         # 'uchinchi'
+```
+
+## Testlar / Tests
+
+```bash
+pytest
+```
+
+## Cheklovlar / Limitations
+
+- Telefon kodlari Wikipedia va operator sahifalariga asoslangan, regulyatorning rasmiy hujjati bilan tekshirilmagan.
+- Faqat mobil raqamlar qo'llab-quvvatlanadi.
+- Viloyatlar ro'yxati Wikipedia/ISO 3166-2:UZ manbalariga asoslangan; rasmiy davlat manbasi bilan to'liq solishtirilmagan.
+
+Operator and region codes are not verified against an official source. Only mobile phone numbers are supported.
+Region list is based on Wikipedia/ISO 3166-2:UZ and has not been fully reconciled with official government sources.# Uzkit

uzkit-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "uzkit"
+version = "0.1.0"
+description = "O'zbek tili va ma'lumotlari uchun Python kutubxonasi: transliteratsiya, raqamlarni so'zga aylantirish, so'm summalari, telefon va avtoraqam validatorlari, viloyatlar."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Ali" }]
+keywords = ["uzbekistan", "uzbek", "transliteration", "numbers", "validators", "phone", "license-plate"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Mr-Ali-web/Uzkit"
+Issues = "https://github.com/Mr-Ali-web/Uzkit/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/uzkit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-ra"

uzkit-0.1.0/src/uzkit/__init__.py

@@ -0,0 +1,25 @@
+"""uzkit - O'zbekiston uchun kichik yordamchi vositalar to'plami."""
+
+from uzkit.money import format_money, money_to_words
+from uzkit.numbers import number_to_words, ordinal
+from uzkit.regions import Region, get_region, list_regions
+from uzkit.translit import to_cyrillic, to_latin
+from uzkit.validators import is_valid_phone, is_valid_plate, normalize_phone
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "Region",
+    "format_money",
+    "get_region",
+    "is_valid_phone",
+    "is_valid_plate",
+    "list_regions",
+    "money_to_words",
+    "normalize_phone",
+    "number_to_words",
+    "ordinal",
+    "to_cyrillic",
+    "to_latin",
+]

uzkit-0.1.0/src/uzkit/data/regions.json

@@ -0,0 +1,16 @@
+[
+  {"name": "Andijon viloyati", "name_cyrillic": "Андижон вилояти", "capital": "Andijon", "capital_cyrillic": "Андижон", "plate_code": "60"},
+  {"name": "Buxoro viloyati", "name_cyrillic": "Бухоро вилояти", "capital": "Buxoro", "capital_cyrillic": "Бухоро", "plate_code": "80"},
+  {"name": "Farg'ona viloyati", "name_cyrillic": "Фарғона вилояти", "capital": "Farg'ona", "capital_cyrillic": "Фарғона", "plate_code": "40"},
+  {"name": "Jizzax viloyati", "name_cyrillic": "Жиззах вилояти", "capital": "Jizzax", "capital_cyrillic": "Жиззах", "plate_code": "25"},
+  {"name": "Namangan viloyati", "name_cyrillic": "Наманган вилояти", "capital": "Namangan", "capital_cyrillic": "Наманган", "plate_code": "50"},
+  {"name": "Navoiy viloyati", "name_cyrillic": "Навоий вилояти", "capital": "Navoiy", "capital_cyrillic": "Навоий", "plate_code": "85"},
+  {"name": "Qashqadaryo viloyati", "name_cyrillic": "Қашқадарё вилояти", "capital": "Qarshi", "capital_cyrillic": "Қарши", "plate_code": "70"},
+  {"name": "Qoraqalpog'iston Respublikasi", "name_cyrillic": "Қорақалпоғистон Республикаси", "capital": "Nukus", "capital_cyrillic": "Нукус", "plate_code": "95"},
+  {"name": "Samarqand viloyati", "name_cyrillic": "Самарқанд вилояти", "capital": "Samarqand", "capital_cyrillic": "Самарқанд", "plate_code": "30"},
+  {"name": "Sirdaryo viloyati", "name_cyrillic": "Сирдарё вилояти", "capital": "Guliston", "capital_cyrillic": "Гулистон", "plate_code": "20"},
+  {"name": "Surxondaryo viloyati", "name_cyrillic": "Сурхондарё вилояти", "capital": "Termiz", "capital_cyrillic": "Термиз", "plate_code": "75"},
+  {"name": "Toshkent shahri", "name_cyrillic": "Тошкент шаҳри", "capital": "Toshkent", "capital_cyrillic": "Тошкент", "plate_code": "01"},
+  {"name": "Toshkent viloyati", "name_cyrillic": "Тошкент вилояти", "capital": "Nurafshon", "capital_cyrillic": "Нурафшон", "plate_code": "10"},
+  {"name": "Xorazm viloyati", "name_cyrillic": "Хоразм вилояти", "capital": "Urganch", "capital_cyrillic": "Урганч", "plate_code": "90"}
+]

uzkit-0.1.0/src/uzkit/formatters.py

@@ -0,0 +1 @@
+"""Formatlash yordamchilari (hozircha bo'sh)."""

uzkit-0.1.0/src/uzkit/money.py

@@ -0,0 +1,56 @@
+"""So'm summalarini so'zga aylantirish va formatlash."""
+
+from __future__ import annotations
+
+from decimal import ROUND_HALF_UP, Decimal
+from typing import Union
+
+from uzkit.numbers import number_to_words
+from uzkit.translit import OKINA
+
+SOM = f"so{OKINA}m"
+TIYIN = "tiyin"
+
+Amount = Union[int, float, Decimal, str]
+
+
+def _to_decimal(amount: Amount) -> Decimal:
+    if isinstance(amount, bool) or not isinstance(amount, (int, float, Decimal, str)):
+        raise TypeError(f"Unsupported amount type: {type(amount).__name__}")
+    return Decimal(str(amount)).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+
+
+def money_to_words(amount: Amount, *, with_tiyin: bool = True) -> str:
+    """Summani so'm va tiyinda so'z bilan yozadi.
+
+    >>> money_to_words(1250)
+    'bir ming ikki yuz ellik soʻm'
+    >>> money_to_words("1250.50")
+    'bir ming ikki yuz ellik soʻm ellik tiyin'
+    """
+    value = _to_decimal(amount)
+    sign = "minus " if value < 0 else ""
+    value = abs(value)
+    som = int(value)
+    tiyin = int((value - som) * 100)
+    parts = [number_to_words(som), SOM]
+    if with_tiyin and tiyin:
+        parts += [number_to_words(tiyin), TIYIN]
+    return sign + " ".join(parts)
+
+
+def format_money(amount: Amount) -> str:
+    """Summani o'qishga qulay ko'rinishda yozadi.
+
+    >>> format_money(1250000)
+    '1 250 000 soʻm'
+    """
+    value = _to_decimal(amount)
+    sign = "-" if value < 0 else ""
+    value = abs(value)
+    som = int(value)
+    tiyin = int((value - som) * 100)
+    text = f"{som:,}".replace(",", " ")
+    if tiyin:
+        text += f",{tiyin:02d}"
+    return f"{sign}{text} {SOM}"

uzkit-0.1.0/src/uzkit/numbers.py

@@ -0,0 +1,126 @@
+"""Sonlarni o'zbekcha so'zlar bilan yozish (0 dan 10**12 gacha)."""
+
+from __future__ import annotations
+
+from typing import List
+
+from uzkit.translit import OKINA
+
+__all__ = ["MAX_NUMBER", "number_to_words", "ordinal"]
+
+#: Qo'llab-quvvatlanadigan eng katta son (modul bo'yicha).
+MAX_NUMBER = 10**12
+
+_ONES = (
+    "",
+    "bir",
+    "ikki",
+    "uch",
+    f"to{OKINA}rt",
+    "besh",
+    "olti",
+    "yetti",
+    "sakkiz",
+    f"to{OKINA}qqiz",
+)
+
+_TENS = (
+    "",
+    f"o{OKINA}n",
+    "yigirma",
+    f"o{OKINA}ttiz",
+    "qirq",
+    "ellik",
+    "oltmish",
+    "yetmish",
+    "sakson",
+    f"to{OKINA}qson",
+)
+
+_SCALES = (
+    (10**12, "trillion"),
+    (10**9, "milliard"),
+    (10**6, "million"),
+    (10**3, "ming"),
+)
+
+_VOWELS = frozenset("aeiou")
+
+
+def _validate(n: object) -> None:
+    if isinstance(n, bool) or not isinstance(n, int):
+        raise TypeError(f"n must be int, not {type(n).__name__}")
+    if abs(n) > MAX_NUMBER:
+        raise ValueError(f"n must be within [-{MAX_NUMBER}, {MAX_NUMBER}], got {n}")
+
+
+def _below_thousand(n: int) -> List[str]:
+    """1..999 oralig'idagi sonni so'zlar ro'yxati sifatida qaytaradi."""
+    words: List[str] = []
+    hundreds, rest = divmod(n, 100)
+    if hundreds:
+        words += [_ONES[hundreds], "yuz"]
+    tens, ones = divmod(rest, 10)
+    if tens:
+        words.append(_TENS[tens])
+    if ones:
+        words.append(_ONES[ones])
+    return words
+
+
+def number_to_words(n: int) -> str:
+    """Butun sonni o'zbekcha so'zlar bilan yozadi.
+
+    >>> number_to_words(1250)
+    'bir ming ikki yuz ellik'
+    >>> number_to_words(0)
+    'nol'
+    >>> number_to_words(-5)
+    'minus besh'
+
+    Oraliq: ``-10**12 <= n <= 10**12``. Manfiy sonlar ``minus`` bilan
+    boshlanadi. ``yuz`` va ``ming`` oldidan ``bir`` doim yoziladi
+    (``100`` -> ``bir yuz``).
+
+    ``oʻ`` va ``gʻ`` dagi belgi :data:`uzkit.translit.OKINA` (U+02BB).
+
+    ``int`` bo'lmagan (``bool`` ham) kiritish uchun ``TypeError``, oraliqdan
+    tashqari son uchun ``ValueError`` ko'taradi.
+    """
+    _validate(n)
+    if n == 0:
+        return "nol"
+
+    words: List[str] = ["minus"] if n < 0 else []
+    remainder = abs(n)
+    for value, name in _SCALES:
+        count, remainder = divmod(remainder, value)
+        if count:
+            words += _below_thousand(count) + [name]
+    words += _below_thousand(remainder)
+    return " ".join(words)
+
+
+def ordinal(n: int) -> str:
+    """Tartib sonni yozadi: oxirgi so'zga ``-inchi`` yoki ``-nchi`` qo'shiladi.
+
+    >>> ordinal(3)
+    'uchinchi'
+    >>> ordinal(2)
+    'ikkinchi'
+    >>> ordinal(1250)
+    'bir ming ikki yuz ellikinchi'
+
+    Oxirgi so'z unli bilan tugasa ``-nchi``, undosh bilan tugasa ``-inchi``
+    qo'shiladi. Oraliq: ``0 <= n <= 10**12``.
+
+    ``int`` bo'lmagan kiritish uchun ``TypeError``, manfiy yoki oraliqdan
+    tashqari son uchun ``ValueError`` ko'taradi.
+    """
+    _validate(n)
+    if n < 0:
+        raise ValueError(f"n must be non-negative, got {n}")
+
+    words = number_to_words(n)
+    suffix = "nchi" if words[-1] in _VOWELS else "inchi"
+    return words + suffix

uzkit-0.1.0/src/uzkit/regions.py

@@ -0,0 +1,42 @@
+"""O'zbekiston viloyatlari va tarkibiy birliklari."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+
+__all__ = ["Region", "get_region", "list_regions"]
+
+
+@dataclass(frozen=True)
+class Region:
+    name: str
+    name_cyrillic: str
+    capital: str
+    capital_cyrillic: str
+    plate_code: str
+
+
+@lru_cache(maxsize=1)
+def _regions() -> tuple[Region, ...]:
+    path = Path(__file__).resolve().parent / "data" / "regions.json"
+    with path.open(encoding="utf-8") as file:
+        raw = json.load(file)
+    return tuple(Region(**item) for item in raw)
+
+
+def list_regions() -> list[Region]:
+    return list(_regions())
+
+
+def get_region(name: str) -> Optional[Region]:
+    if not isinstance(name, str) or not name.strip():
+        return None
+    needle = name.casefold()
+    for region in _regions():
+        if region.name.casefold() == needle or region.name_cyrillic.casefold() == needle:
+            return region
+    return None

uzkit-0.1.0/src/uzkit/translit.py

@@ -0,0 +1,105 @@
+"""O'zbek tili uchun Lotin <-> Kirill transliteratsiyasi."""
+
+from __future__ import annotations
+
+OKINA = "\u02bb"  # ʻ  o‘ va g‘ dagi belgi
+TUTUQ = "\u02bc"  # ʼ  tutuq belgisi (ma’no)
+
+_APOSTROPHES = frozenset("'\u2019\u02bb\u2018`\u00b4\u02bc")
+_LAT_VOWELS = frozenset("aeiou")
+_CYR_VOWELS = frozenset("аеёиоуўэюяы")
+
+_LAT2CYR = {
+    "a": "а", "b": "б", "d": "д", "f": "ф", "g": "г", "h": "ҳ",
+    "i": "и", "j": "ж", "k": "к", "l": "л", "m": "м", "n": "н",
+    "o": "о", "p": "п", "q": "қ", "r": "р", "s": "с", "t": "т",
+    "u": "у", "v": "в", "x": "х", "y": "й", "z": "з",
+}
+_Y_COMBOS = {"o": "ё", "u": "ю", "a": "я", "e": "е"}
+
+_CYR2LAT = {
+    "а": "a", "б": "b", "в": "v", "г": "g", "д": "d", "ё": "yo",
+    "ж": "j", "з": "z", "и": "i", "й": "y", "к": "k", "л": "l",
+    "м": "m", "н": "n", "о": "o", "п": "p", "р": "r", "с": "s",
+    "т": "t", "у": "u", "ф": "f", "х": "x", "ц": "ts", "ч": "ch",
+    "ш": "sh", "щ": "shch", "ъ": TUTUQ, "ы": "i", "ь": "", "э": "e",
+    "ю": "yu", "я": "ya", "ў": "o" + OKINA, "қ": "q",
+    "ғ": "g" + OKINA, "ҳ": "h",
+}
+
+
+def to_cyrillic(text: str) -> str:
+    """Lotin yozuvidagi matnni Kirillga o'giradi.
+
+    >>> to_cyrillic("O'zbekiston")
+    'Ўзбекистон'
+    """
+    out: list[str] = []
+    n = len(text)
+    i = 0
+    while i < n:
+        ch = text[i]
+        low = ch.lower()
+        nxt = text[i + 1] if i + 1 < n else ""
+        nlow = nxt.lower()
+        prev = text[i - 1] if i > 0 else ""
+        step = 1
+
+        if low in ("o", "g") and nxt in _APOSTROPHES:
+            res = "ў" if low == "o" else "ғ"
+            step = 2
+        elif low in ("s", "c") and nlow == "h":
+            res = "ш" if low == "s" else "ч"
+            step = 2
+        elif low == "y" and nlow in _Y_COMBOS:
+            res = _Y_COMBOS[nlow]
+            step = 2
+        elif low == "e":
+            at_start = not prev.isalpha() or prev.lower() in _LAT_VOWELS
+            res = "э" if at_start else "е"
+        elif ch in _APOSTROPHES and prev.isalpha() and nxt.isalpha():
+            res = "ъ"
+        elif low in _LAT2CYR:
+            res = _LAT2CYR[low]
+        else:
+            out.append(ch)
+            i += 1
+            continue
+
+        out.append(res.upper() if ch.isupper() else res)
+        i += step
+    return "".join(out)
+
+
+def _has_upper_neighbor(text: str, i: int) -> bool:
+    before = i > 0 and text[i - 1].isupper()
+    after = i + 1 < len(text) and text[i + 1].isupper()
+    return before or after
+
+
+def to_latin(text: str) -> str:
+    """Kirill yozuvidagi matnni Lotinga o'giradi (2023 alifbosi).
+
+    >>> to_latin("Ўзбекистон")
+    'Oʻzbekiston'
+    """
+    out: list[str] = []
+    for i, ch in enumerate(text):
+        low = ch.lower()
+        if low == "е":
+            prev = text[i - 1].lower() if i > 0 else ""
+            ye = not prev.isalpha() or prev in _CYR_VOWELS or prev in "ъь"
+            res = "ye" if ye else "e"
+        elif low in _CYR2LAT:
+            res = _CYR2LAT[low]
+        else:
+            out.append(ch)
+            continue
+
+        if ch.isupper() and res:
+            if len(res) > 1 and not _has_upper_neighbor(text, i):
+                res = res.capitalize()
+            else:
+                res = res.upper()
+        out.append(res)
+    return "".join(out)

uzkit-0.1.0/src/uzkit/utils.py

@@ -0,0 +1 @@
+"""Umumiy yordamchi funksiyalar (hozircha bo'sh)."""

uzkit-0.1.0/src/uzkit/validators.py

@@ -0,0 +1,112 @@
+"""O'zbekiston telefon raqamlari va avtomobil davlat raqamlarini tekshirish."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+__all__ = [
+    "MOBILE_OPERATOR_CODES",
+    "is_valid_phone",
+    "is_valid_plate",
+    "normalize_phone",
+]
+
+COUNTRY_CODE = "998"
+
+#: Mobil operator kodlari (+998 XX ...).
+MOBILE_OPERATOR_CODES = frozenset(
+    {
+        "20",  # Sardor Telecom / OQ
+        "33",  # Humans
+        "50",  # Ucell
+        "55",  # Ucell; VoIP (Uztelecom), mobil emas
+        "77",  # Uzmobile
+        "88",  # Mobiuz / Humans
+        "90",  # Beeline
+        "91",  # Beeline
+        "93",  # Ucell
+        "94",  # Ucell
+        "95",  # Uzmobile
+        "97",  # Mobiuz
+        "98",  # Mobiuz
+        "99",  # Uzmobile
+    }
+)
+
+# Raqamlar orasida ruxsat etilgan ajratuvchilar: bo'shliq, tire, nuqta, qavs.
+_PHONE_SEPARATORS = re.compile(r"[\s\-.()]+")
+_PHONE_BODY = re.compile(r"\+?[0-9]+", re.ASCII)
+
+# 01 A 123 AA (jismoniy shaxs) va 01 123 AAA (yuridik shaxs)
+_PLATE_PERSONAL = re.compile(r"(\d{2}) ?([A-Z]) ?(\d{3}) ?([A-Z]{2})", re.ASCII)
+_PLATE_LEGAL = re.compile(r"(\d{2}) ?(\d{3}) ?([A-Z]{3})", re.ASCII)
+
+
+def normalize_phone(phone: Any) -> Optional[str]:
+    """Telefon raqamini ``+998XXXXXXXXX`` ko'rinishiga keltiradi.
+
+    Qabul qilinadigan kiritishlar (bo'shliq, tire, nuqta va qavslar e'tiborga
+    olinmaydi)::
+
+        +998 90 123-45-67
+        998901234567
+        90 123 45 67        (milliy 9 xonali format)
+
+    Raqam noto'g'ri bo'lsa (yoki ``str`` bo'lmasa) ``None`` qaytariladi.
+    Faqat mobil operator kodlari (:data:`MOBILE_OPERATOR_CODES`) qabul qilinadi.
+    """
+    if not isinstance(phone, str):
+        return None
+
+    cleaned = _PHONE_SEPARATORS.sub("", phone)
+    if not _PHONE_BODY.fullmatch(cleaned):
+        return None
+
+    digits = cleaned[1:] if cleaned.startswith("+") else cleaned
+
+    if len(digits) == 12 and digits.startswith(COUNTRY_CODE):
+        national = digits[len(COUNTRY_CODE):]
+    elif len(digits) == 9 and not cleaned.startswith("+"):
+        national = digits
+    else:
+        return None
+
+    if national[:2] not in MOBILE_OPERATOR_CODES:
+        return None
+
+    return f"+{COUNTRY_CODE}{national}"
+
+
+def is_valid_phone(phone: Any) -> bool:
+    """Telefon raqami O'zbekiston mobil raqami ekanini tekshiradi.
+
+    >>> is_valid_phone("+998 90 123 45 67")
+    True
+    >>> is_valid_phone("+998 10 123 45 67")
+    False
+    """
+    return normalize_phone(phone) is not None
+
+
+def is_valid_plate(plate: Any) -> bool:
+    """Avtomobil davlat raqamini tekshiradi.
+
+    Qo'llab-quvvatlanadigan formatlar::
+
+        01 A 123 AA     (jismoniy shaxslar)
+        01 123 AAA      (yuridik shaxslar)
+
+    Bo'shliqlar ixtiyoriy (``01A123AA``), harflar katta-kichikligi farqlanmaydi.
+    Viloyat kodi 00 dan farqli ikki xonali kod bo'lishi shart (01-99).
+    """
+    if not isinstance(plate, str):
+        return False
+
+    value = plate.strip().upper()
+    match = _PLATE_PERSONAL.fullmatch(value) or _PLATE_LEGAL.fullmatch(value)
+    if match is None:
+        return False
+
+    code = match.group(1)
+    return code != "00" and code.isdigit() and len(code) == 2

uzkit-0.1.0/tests/test_money.py

@@ -0,0 +1,45 @@
+from decimal import Decimal
+
+import pytest
+
+from uzkit import format_money, money_to_words
+from uzkit.translit import OKINA
+
+SOM = f"so{OKINA}m"
+
+
+@pytest.mark.parametrize("amount,expected", [
+    (0, f"nol {SOM}"),
+    (1250, f"bir ming ikki yuz ellik {SOM}"),
+    ("1250.50", f"bir ming ikki yuz ellik {SOM} ellik tiyin"),
+    (Decimal("0.05"), f"nol {SOM} besh tiyin"),
+    (-100, f"minus bir yuz {SOM}"),
+    (1_000_000, f"bir million {SOM}"),
+])
+def test_money_to_words(amount, expected):
+    assert money_to_words(amount) == expected
+
+
+def test_without_tiyin():
+    assert money_to_words(10.75, with_tiyin=False) == f"o{OKINA}n {SOM}"
+
+
+def test_float_precision():
+    assert money_to_words(0.1 + 0.2) == f"nol {SOM} o{OKINA}ttiz tiyin"
+
+
+@pytest.mark.parametrize("bad", [None, True, [1], {}])
+def test_bad_type(bad):
+    with pytest.raises(TypeError):
+        money_to_words(bad)
+
+
+@pytest.mark.parametrize("amount,expected", [
+    (1250000, f"1 250 000 {SOM}"),
+    (999, f"999 {SOM}"),
+    ("1500.5", f"1 500,50 {SOM}"),
+    (-2000, f"-2 000 {SOM}"),
+])
+def test_format_money(amount, expected):
+    assert format_money(amount) == expected
+    

uzkit-0.1.0/tests/test_numbers.py

@@ -0,0 +1,61 @@
+import pytest
+
+from uzkit import number_to_words, ordinal
+from uzkit.translit import OKINA
+
+O = OKINA
+
+CARDINALS = [
+    (0, "nol"),
+    (1, "bir"),
+    (7, "yetti"),
+    (10, f"o{O}n"),
+    (14, f"o{O}n to{O}rt"),
+    (20, "yigirma"),
+    (40, "qirq"),
+    (80, "sakson"),
+    (90, f"to{O}qson"),
+    (100, "bir yuz"),
+    (101, "bir yuz bir"),
+    (1000, "bir ming"),
+    (1250, "bir ming ikki yuz ellik"),
+    (2024, f"ikki ming yigirma to{O}rt"),
+    (1_000_000, "bir million"),
+    (1_000_001, "bir million bir"),
+    (1_000_000_000, "bir milliard"),
+    (
+        12_345_678,
+        f"o{O}n ikki million uch yuz qirq besh ming olti yuz yetmish sakkiz",
+    ),
+]
+
+
+@pytest.mark.parametrize("n,words", CARDINALS)
+def test_number_to_words(n, words):
+    assert number_to_words(n) == words
+
+
+@pytest.mark.parametrize("n", [1, 5, 99, 1000, 123456])
+def test_negative(n):
+    assert number_to_words(-n) == "minus " + number_to_words(n)
+
+
+ORDINALS = [
+    (1, "birinchi"),
+    (2, "ikkinchi"),
+    (3, "uchinchi"),
+    (4, f"to{O}rtinchi"),
+    (5, "beshinchi"),
+    (6, "oltinchi"),
+    (7, "yettinchi"),
+    (8, "sakkizinchi"),
+    (9, f"to{O}qqizinchi"),
+    (10, f"o{O}ninchi"),
+    (20, "yigirmanchi"),
+    (40, "qirqinchi"),
+]
+
+
+@pytest.mark.parametrize("n,words", ORDINALS)
+def test_ordinal(n, words):
+    assert ordinal(n) == words

uzkit-0.1.0/tests/test_regions.py

@@ -0,0 +1,91 @@
+import pytest
+
+from uzkit.regions import Region, get_region, list_regions
+
+
+def test_list_regions_count():
+    assert len(list_regions()) == 14
+
+
+def test_list_regions_returns_region_objects():
+    assert all(isinstance(region, Region) for region in list_regions())
+
+
+def test_get_region_by_latin_name():
+    region = get_region("Toshkent viloyati")
+    assert region is not None
+    assert region.capital == "Nurafshon"
+
+
+def test_get_region_by_cyrillic_name():
+    region = get_region("Тошкент вилояти")
+    assert region is not None
+    assert region.name == "Toshkent viloyati"
+
+
+def test_get_region_case_insensitive():
+    assert get_region("toshkent viloyati") == get_region("TOSHKENT VILOYATI")
+
+
+def test_get_region_unknown_returns_none():
+    assert get_region("Mars") is None
+
+
+def test_get_region_empty_returns_none():
+    assert get_region("") is None
+    assert get_region("   ") is None
+
+
+def test_get_region_non_string_returns_none():
+    assert get_region(None) is None
+    assert get_region(123) is None
+
+
+def test_all_capitals_present():
+    for region in list_regions():
+        assert region.capital
+        assert region.capital_cyrillic
+
+
+def test_plate_codes_match_validator_ranges():
+    codes = {region.plate_code for region in list_regions()}
+    assert codes == {"01", "10", "20", "25", "30", "40", "50", "60", "70", "75", "80", "85", "90", "95"}
+
+
+def test_unique_region_names():
+    names = [region.name for region in list_regions()]
+    assert len(names) == len(set(names))
+
+
+def test_unique_cyrillic_names():
+    names = [region.name_cyrillic for region in list_regions()]
+    assert len(names) == len(set(names))
+
+
+def test_qoraqalpogiston():
+    region = get_region("Qoraqalpog'iston Respublikasi")
+    assert region is not None
+    assert region.capital == "Nukus"
+
+
+def test_toshkent_shahri():
+    region = get_region("Toshkent shahri")
+    assert region is not None
+    assert region.plate_code == "01"
+
+
+def test_get_region_by_capital_not_required():
+    assert get_region("Nukus") is None
+
+
+def test_immutable_region():
+    region = get_region("Xorazm viloyati")
+    with pytest.raises(Exception):
+        region.name = "changed"
+
+
+def test_region_code_mapping():
+    assert get_region("Qashqadaryo viloyati").plate_code == "70"
+    assert get_region("Surxondaryo viloyati").plate_code == "75"
+    assert get_region("Buxoro viloyati").plate_code == "80"
+    assert get_region("Navoiy viloyati").plate_code == "85"

uzkit-0.1.0/tests/test_translit.py

@@ -0,0 +1,43 @@
+import pytest
+
+from uzkit.translit import OKINA, TUTUQ, to_cyrillic, to_latin
+
+PAIRS = [
+    ("Toshkent", "Тошкент"),
+    (f"O{OKINA}zbekiston", "Ўзбекистон"),
+    (f"G{OKINA}ijduvon", "Ғиждувон"),
+    (f"Qo{OKINA}qon", "Қўқон"),
+    ("yaxshi", "яхши"),
+    ("shahar", "шаҳар"),
+    ("chiroyli", "чиройли"),
+    ("yoz", "ёз"),
+    ("Yevropa", "Европа"),
+    ("Elektr", "Электр"),
+    ("aeroport", "аэропорт"),
+    ("SHAHAR", "ШАҲАР"),
+    ("YOSH", "ЁШ"),
+    ("Shahar", "Шаҳар"),
+    (f"ma{TUTUQ}no", "маъно"),
+    ("", ""),
+    ("123, 45!", "123, 45!"),
+]
+
+
+@pytest.mark.parametrize("latin,cyrillic", PAIRS)
+def test_to_cyrillic(latin, cyrillic):
+    assert to_cyrillic(latin) == cyrillic
+
+
+@pytest.mark.parametrize("latin,cyrillic", PAIRS)
+def test_to_latin(latin, cyrillic):
+    assert to_latin(cyrillic) == latin
+
+
+@pytest.mark.parametrize("apos", ["'", "’", "ʻ", "‘", "`"])
+def test_apostrophe_variants(apos):
+    assert to_cyrillic(f"o{apos}zbek") == "ўзбек"
+    assert to_cyrillic(f"ma{apos}no") == "маъно"
+
+
+def test_quotes_at_word_edges_untouched():
+    assert to_cyrillic("'salom'") == "'салом'"

uzkit-0.1.0/tests/test_validators.py

@@ -0,0 +1,154 @@
+import pytest
+
+from uzkit.validators import (
+    MOBILE_OPERATOR_CODES,
+    is_valid_phone,
+    is_valid_plate,
+    normalize_phone,
+)
+
+
+# ---------------------------------------------------------------- telefon
+@pytest.mark.parametrize(
+    "value",
+    [
+        "+998901234567",
+        "+998 90 123 45 67",
+        "+998 (90) 123-45-67",
+        "998901234567",
+        "901234567",
+        "90 123 45 67",
+        "+998.91.123.45.67",
+        "  +998931234567  ",
+    ],
+)
+def test_valid_phone_formats(value):
+    assert is_valid_phone(value) is True
+
+
+@pytest.mark.parametrize("code", sorted(MOBILE_OPERATOR_CODES))
+def test_every_operator_code_is_accepted(code):
+    assert is_valid_phone(f"+998{code}1234567")
+
+
+@pytest.mark.parametrize("code", ["90", "91", "93", "94", "95", "97", "99", "33", "88"])
+def test_required_operator_codes_present(code):
+    assert code in MOBILE_OPERATOR_CODES
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "",
+        "   ",
+        "+99890123456",  # juda qisqa
+        "+9989012345678",  # juda uzun
+        "+998 10 123 45 67",  # noma'lum operator kodi
+        "+998 00 123 45 67",
+        "+7 901 234 56 78",  # boshqa davlat
+        "+901234567",  # 9 xonali, lekin '+' bilan
+        "90123456",  # 8 xonali
+        "+998 90 123 45 6a",
+        "++998901234567",
+        "+99890+1234567",
+        "abcdefghijkl",
+        "+٩٩٨٩٠١٢٣٤٥٦٧",  # arab-hind raqamlari
+    ],
+)
+def test_invalid_phone(value):
+    assert is_valid_phone(value) is False
+
+
+@pytest.mark.parametrize("value", [None, 998901234567, 90.1, [], b"+998901234567"])
+def test_non_string_phone(value):
+    assert is_valid_phone(value) is False
+    assert normalize_phone(value) is None
+
+
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [
+        ("+998 90 123-45-67", "+998901234567"),
+        ("998901234567", "+998901234567"),
+        ("90 123 45 67", "+998901234567"),
+        ("(93) 765-43-21", "+998937654321"),
+        ("+998-33-111-22-33", "+998331112233"),
+    ],
+)
+def test_normalize_phone(raw, expected):
+    assert normalize_phone(raw) == expected
+
+
+def test_normalize_phone_invalid_returns_none():
+    assert normalize_phone("+998 10 123 45 67") is None
+    assert normalize_phone("hello") is None
+
+
+def test_normalize_is_idempotent():
+    once = normalize_phone("90 123 45 67")
+    assert normalize_phone(once) == once
+
+
+# ----------------------------------------------------------- davlat raqami
+@pytest.mark.parametrize(
+    "value",
+    [
+        "01 A 123 AA",
+        "01 123 AAA",
+        "01A123AA",
+        "01123AAA",
+        "01 a 123 aa",
+        "  30 B 456 CD  ",
+        "95 Z 999 ZZ",
+        "80 777 XYZ",
+        "10 A 001 BC",
+    ],
+)
+def test_valid_plate(value):
+    assert is_valid_plate(value) is True
+
+
+@pytest.mark.parametrize("code", [f"{i:02d}" for i in range(1, 100)])
+def test_every_region_code_is_accepted(code):
+    assert is_valid_plate(f"{code} A 123 AA")
+    assert is_valid_plate(f"{code} 123 AAA")
+
+@pytest.mark.parametrize("code", ["02", "31", "99"])
+def test_selected_plate_codes_accepted(code):
+    assert is_valid_plate(f"{code} A 123 AA")
+
+def test_plate_code_00_rejected():
+    assert is_valid_plate("00 A 123 AA") is False
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "",
+        "   ",
+        "00 A 123 AA",  # noma'lum viloyat kodi
+        "1 A 123 AA",  # viloyat kodi bitta raqam
+        "001 A 123 AA",
+        "01 AA 123 AA",
+        "01 A 12 AA",
+        "01 A 1234 AA",
+        "01 A 123 A",
+        "01 A 123 AAA",  # ikki format aralashgan
+        "01 12 AAA",
+        "01 1234 AAA",
+        "01 123 AA",
+        "01 123 AAAA",
+        "01 1 123 AA",
+        "A 01 123 AA",
+        "01-A-123-AA",
+        "01  A 123 AA",  # ikkita bo'shliq
+        "01 А 123 АА",  # kirill harflari
+    ],
+)
+def test_invalid_plate(value):
+    assert is_valid_plate(value) is False
+
+
+@pytest.mark.parametrize("value", [None, 123, [], b"01 A 123 AA"])
+def test_non_string_plate(value):
+    assert is_valid_plate(value) is False