turkificate 0.1.0__tar.gz

turkificate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enes
+
+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.

turkificate-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: turkificate
+Version: 0.1.0
+Summary: A Turkish text normalization library (numbers, dates, times, abbreviations, currency, and more)
+Author: Enes
+License: MIT
+Project-URL: Homepage, https://github.com/<kullanici-adi>/turkificate
+Project-URL: Repository, https://github.com/<kullanici-adi>/turkificate
+Project-URL: Issues, https://github.com/<kullanici-adi>/turkificate/issues
+Keywords: turkish,nlp,text-normalization,tts,normalization
+Classifier: Programming Language :: Python :: 3
+Classifier: Natural Language :: Turkish
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# turkificate
+
+A Turkish text normalization library. It converts numbers, dates, times,
+abbreviations, currencies, percentages, ordinals and symbols into their written
+Turkish form, following Turkish grammar. Built for TTS pre-processing, search
+indexing and text cleaning.
+
+> _"The language is the core of our being - Noam Chomsky"_ 
+
+No external dependencies — pure standard library.
+
+## Installation
+
+```bash
+pip install turkificate
+```
+
+Or from a local checkout:
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```python
+import turkificate
+
+turkificate.turkificate("Dr. Ahmet 15.03.2024'te %25 indirimle 1.250 TL ödedi.")
+# "doktor Ahmet on beş Mart iki bin yirmi dört'te yüzde yirmi beş
+#  indirimle bin iki yüz elli lira ödedi."
+```
+
+`turkificate()` is the main function; `normalize()` is a kept alias for the same call.
+
+> The **output** is intentionally Turkish (e.g. `yüz`, `bin`, `Mart`) — that is the
+> whole point of the library. Only the **code, API and docs** are in English.
+
+## Selecting concepts
+
+```python
+from turkificate import TurkishNormalizer
+
+tn = TurkishNormalizer(features=["numbers", "dates"])
+tn.normalize("Saat 14:30, fiyat 99,90 TL")
+# "Saat 14:30, fiyat doksan dokuz virgül doksan TL"  (times & currency untouched)
+```
+
+### Normalize everything
+
+Pass nothing (the default), or the explicit `"all"` keyword:
+
+```python
+TurkishNormalizer()                          # all concepts (default)
+TurkishNormalizer(features="all")            # all concepts
+TurkishNormalizer(features=["all"])          # all concepts
+TurkishNormalizer(features=turkificate.ALL)  # all concepts
+```
+
+List available concepts with `turkificate.available_features()`.
+
+| Concept | Description | Example |
+|---|---|---|
+| `numbers` | integer / decimal / signed | `3,5` → üç virgül beş |
+| `dates` | DD.MM.YYYY | `15.03.2024` → on beş Mart iki bin yirmi dört |
+| `times` | HH:MM(:SS) | `14:30` → on dört otuz |
+| `percent` | percent sign | `%50` → yüzde elli |
+| `currency` | currencies | `100 TL` → yüz lira |
+| `ordinals` | ordinal numbers | `5'inci` → beşinci |
+| `units` | units of measure | `42 km` → kırk iki kilometre |
+| `abbreviations` | lexical abbreviations | `Dr.` → doktor |
+| `symbols` | single-character symbols | `&` → ve |
+| `whitespace` | whitespace cleanup | (always the final step) |
+
+## Per-concept options
+
+```python
+tn = TurkishNormalizer(options={
+    "times": {"prefix_hour": True},        # 09:05 → "saat dokuz beş"
+    "ordinals": {"period_ordinals": True}, # "3. kat" → "üçüncü kat"
+})
+```
+
+## Per-concept helpers
+
+```python
+turkificate.normalize_numbers("3 elma")     # "üç elma"
+turkificate.normalize_dates(...)
+turkificate.normalize_currency(...)
+# normalize_times, normalize_percent, normalize_ordinals,
+# normalize_units, normalize_abbreviations, normalize_symbols
+```
+
+Direct number engine:
+
+```python
+from turkificate import integer_to_words, integer_to_ordinal, read_number
+integer_to_words(1_000_000)   # "bir milyon"
+integer_to_ordinal(4)         # "dördüncü"
+read_number("1.234,5")        # "bin iki yüz otuz dört virgül beş"
+```
+
+## Adding a new concept
+
+Subclass `Normalizer` and register it with `@register`:
+
+```python
+from turkificate import Normalizer, register
+import re
+
+@register
+class EmojiNormalizer(Normalizer):
+    name = "emoji"
+
+    def configure(self, **opts):
+        self._re = re.compile(r":\)")
+
+    def apply(self, text):
+        return self._re.sub("gülen yüz", text)
+```
+
+It is now usable via `TurkishNormalizer(features=["emoji", ...])` or `"all"`.
+
+## Architecture
+
+- **Strategy** — each concept is an independent class with a common `Normalizer` interface.
+- **Pipeline (Chain)** — normalizers run in order; number-bearing concepts run before the bare `numbers` concept to avoid double conversion.
+- **Registry + Facade** — concepts are selected by name; `TurkishNormalizer` composes them.
+
+Optimization: every regex is compiled once in the constructor; the abbreviation,
+unit and currency dictionaries are compiled into a single alternation regex; the
+number-to-words engine is `lru_cache`-d; and because `apply` is pure, a single
+instance is reused across thousands of calls.
+
+## Known limits (roadmap)
+
+- The period ordinal form (`3.`) is disabled by default because it clashes with a sentence-final period; enable it with `period_ordinals=True`.
+- The number engine is one-way; the reverse direction (words → digits) is not yet implemented.
+- Context-sensitive suffixes (`5'te` → "beşte") are not handled yet.
+- Roman numerals, phone numbers and fractions (`3/4`) can be added.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Publishing
+
+This repo ships a GitHub Actions workflow (`.github/workflows/publish.yml`) that
+publishes to PyPI via Trusted Publishing (no API tokens) when you create a
+GitHub Release. See the project README section below or the PyPI docs on
+trusted publishers.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

turkificate-0.1.0/README.md

@@ -0,0 +1,158 @@
+# turkificate
+
+A Turkish text normalization library. It converts numbers, dates, times,
+abbreviations, currencies, percentages, ordinals and symbols into their written
+Turkish form, following Turkish grammar. Built for TTS pre-processing, search
+indexing and text cleaning.
+
+> _"The language is the core of our being - Noam Chomsky"_ 
+
+No external dependencies — pure standard library.
+
+## Installation
+
+```bash
+pip install turkificate
+```
+
+Or from a local checkout:
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```python
+import turkificate
+
+turkificate.turkificate("Dr. Ahmet 15.03.2024'te %25 indirimle 1.250 TL ödedi.")
+# "doktor Ahmet on beş Mart iki bin yirmi dört'te yüzde yirmi beş
+#  indirimle bin iki yüz elli lira ödedi."
+```
+
+`turkificate()` is the main function; `normalize()` is a kept alias for the same call.
+
+> The **output** is intentionally Turkish (e.g. `yüz`, `bin`, `Mart`) — that is the
+> whole point of the library. Only the **code, API and docs** are in English.
+
+## Selecting concepts
+
+```python
+from turkificate import TurkishNormalizer
+
+tn = TurkishNormalizer(features=["numbers", "dates"])
+tn.normalize("Saat 14:30, fiyat 99,90 TL")
+# "Saat 14:30, fiyat doksan dokuz virgül doksan TL"  (times & currency untouched)
+```
+
+### Normalize everything
+
+Pass nothing (the default), or the explicit `"all"` keyword:
+
+```python
+TurkishNormalizer()                          # all concepts (default)
+TurkishNormalizer(features="all")            # all concepts
+TurkishNormalizer(features=["all"])          # all concepts
+TurkishNormalizer(features=turkificate.ALL)  # all concepts
+```
+
+List available concepts with `turkificate.available_features()`.
+
+| Concept | Description | Example |
+|---|---|---|
+| `numbers` | integer / decimal / signed | `3,5` → üç virgül beş |
+| `dates` | DD.MM.YYYY | `15.03.2024` → on beş Mart iki bin yirmi dört |
+| `times` | HH:MM(:SS) | `14:30` → on dört otuz |
+| `percent` | percent sign | `%50` → yüzde elli |
+| `currency` | currencies | `100 TL` → yüz lira |
+| `ordinals` | ordinal numbers | `5'inci` → beşinci |
+| `units` | units of measure | `42 km` → kırk iki kilometre |
+| `abbreviations` | lexical abbreviations | `Dr.` → doktor |
+| `symbols` | single-character symbols | `&` → ve |
+| `whitespace` | whitespace cleanup | (always the final step) |
+
+## Per-concept options
+
+```python
+tn = TurkishNormalizer(options={
+    "times": {"prefix_hour": True},        # 09:05 → "saat dokuz beş"
+    "ordinals": {"period_ordinals": True}, # "3. kat" → "üçüncü kat"
+})
+```
+
+## Per-concept helpers
+
+```python
+turkificate.normalize_numbers("3 elma")     # "üç elma"
+turkificate.normalize_dates(...)
+turkificate.normalize_currency(...)
+# normalize_times, normalize_percent, normalize_ordinals,
+# normalize_units, normalize_abbreviations, normalize_symbols
+```
+
+Direct number engine:
+
+```python
+from turkificate import integer_to_words, integer_to_ordinal, read_number
+integer_to_words(1_000_000)   # "bir milyon"
+integer_to_ordinal(4)         # "dördüncü"
+read_number("1.234,5")        # "bin iki yüz otuz dört virgül beş"
+```
+
+## Adding a new concept
+
+Subclass `Normalizer` and register it with `@register`:
+
+```python
+from turkificate import Normalizer, register
+import re
+
+@register
+class EmojiNormalizer(Normalizer):
+    name = "emoji"
+
+    def configure(self, **opts):
+        self._re = re.compile(r":\)")
+
+    def apply(self, text):
+        return self._re.sub("gülen yüz", text)
+```
+
+It is now usable via `TurkishNormalizer(features=["emoji", ...])` or `"all"`.
+
+## Architecture
+
+- **Strategy** — each concept is an independent class with a common `Normalizer` interface.
+- **Pipeline (Chain)** — normalizers run in order; number-bearing concepts run before the bare `numbers` concept to avoid double conversion.
+- **Registry + Facade** — concepts are selected by name; `TurkishNormalizer` composes them.
+
+Optimization: every regex is compiled once in the constructor; the abbreviation,
+unit and currency dictionaries are compiled into a single alternation regex; the
+number-to-words engine is `lru_cache`-d; and because `apply` is pure, a single
+instance is reused across thousands of calls.
+
+## Known limits (roadmap)
+
+- The period ordinal form (`3.`) is disabled by default because it clashes with a sentence-final period; enable it with `period_ordinals=True`.
+- The number engine is one-way; the reverse direction (words → digits) is not yet implemented.
+- Context-sensitive suffixes (`5'te` → "beşte") are not handled yet.
+- Roman numerals, phone numbers and fractions (`3/4`) can be added.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Publishing
+
+This repo ships a GitHub Actions workflow (`.github/workflows/publish.yml`) that
+publishes to PyPI via Trusted Publishing (no API tokens) when you create a
+GitHub Release. See the project README section below or the PyPI docs on
+trusted publishers.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

turkificate-0.1.0/__init__.py

@@ -0,0 +1,109 @@
+"""turkificate — a Turkish text normalization library.
+
+Quick start
+-----------
+>>> import turkificate
+>>> turkificate.turkificate("Dr. Ahmet 15.03.2024'te %25 indirimle 1.250 TL ödedi.")
+"doktor Ahmet on beş Mart iki bin yirmi dört'te yüzde yirmi beş indirimle bin iki yüz elli lira ödedi."
+
+``turkificate()`` is the main function; ``normalize()`` is a kept alias.
+
+Selecting concepts
+-------------------
+>>> tn = turkificate.TurkishNormalizer(features=["numbers", "dates"])
+>>> tn.normalize("Saat 14:30, fiyat 99,90 TL")   # times and currency untouched
+'Saat 14:30, fiyat doksan dokuz virgül doksan TL'
+
+Normalize everything (default, or explicit "all")
+-------------------------------------------------
+>>> turkificate.TurkishNormalizer(features="all").normalize("%50")
+'yüzde elli'
+
+Per-concept helpers
+-------------------
+>>> turkificate.normalize_numbers("3 kişi geldi")
+'üç kişi geldi'
+"""
+
+from .base import Normalizer, available_features, get_registry, register
+from .numbers import (
+    integer_to_ordinal,
+    integer_to_words,
+    number_to_words,
+    read_number,
+)
+from .pipeline import ALL, DEFAULT_ORDER, Pipeline, TurkishNormalizer
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main interface
+    "TurkishNormalizer",
+    "Pipeline",
+    "turkificate",
+    "normalize",
+    "DEFAULT_ORDER",
+    "ALL",
+    # Number engine
+    "integer_to_words",
+    "integer_to_ordinal",
+    "read_number",
+    "number_to_words",
+    # Extension
+    "Normalizer",
+    "register",
+    "get_registry",
+    "available_features",
+    # Per-concept helpers
+    "normalize_emails",
+    "normalize_urls",
+    "normalize_numbers",
+    "normalize_dates",
+    "normalize_times",
+    "normalize_percent",
+    "normalize_currency",
+    "normalize_ordinals",
+    "normalize_units",
+    "normalize_abbreviations",
+    "normalize_symbols",
+]
+
+# Default, reusable instance covering every concept.
+_default = TurkishNormalizer()
+
+
+def turkificate(text: str) -> str:
+    """Normalize Turkish text using every available concept (the main function)."""
+    return _default.normalize(text)
+
+
+# Kept alias for readability / discoverability.
+normalize = turkificate
+
+
+def _make_single(feature):
+    """Build a cached helper that runs a single concept."""
+    holder = {}
+
+    def fn(text: str) -> str:
+        tn = holder.get("tn")
+        if tn is None:
+            tn = holder["tn"] = TurkishNormalizer(features=[feature])
+        return tn.normalize(text)
+
+    fn.__name__ = f"normalize_{feature}"
+    fn.__doc__ = f"Normalize only the '{feature}' concept."
+    return fn
+
+
+normalize_emails = _make_single("emails")
+normalize_urls = _make_single("urls")
+normalize_numbers = _make_single("numbers")
+normalize_dates = _make_single("dates")
+normalize_times = _make_single("times")
+normalize_percent = _make_single("percent")
+normalize_currency = _make_single("currency")
+normalize_ordinals = _make_single("ordinals")
+normalize_units = _make_single("units")
+normalize_abbreviations = _make_single("abbreviations")
+normalize_symbols = _make_single("symbols")

turkificate-0.1.0/base.py

@@ -0,0 +1,61 @@
+"""Core abstractions: the Normalizer interface (Strategy) and the Registry.
+
+Every normalization concept is an independent subclass of ``Normalizer``. Classes
+register themselves into a central registry via ``@register``, so that
+``TurkishNormalizer`` can select and order concepts by name only
+(e.g. "numbers", "dates").
+
+Design principle: each normalizer does all of its setup (regex compilation, etc.)
+in its constructor, while ``apply`` stays completely pure and side-effect free.
+That lets a single instance be reused across thousands of texts.
+"""
+
+from abc import ABC, abstractmethod
+
+__all__ = ["Normalizer", "register", "get_registry", "available_features"]
+
+_REGISTRY: dict[str, type["Normalizer"]] = {}
+
+
+class Normalizer(ABC):
+    """Abstract base for a single normalization concept (Strategy)."""
+
+    #: Unique name used in the registry and in feature selection.
+    name: str = ""
+
+    def __init__(self, **options):
+        self.options = options
+        self.configure(**options)
+
+    def configure(self, **options) -> None:
+        """Subclasses do their setup (e.g. regex compilation) here."""
+
+    @abstractmethod
+    def apply(self, text: str) -> str:
+        """Transform the text and return the new text. Must be side-effect free."""
+
+    def __call__(self, text: str) -> str:
+        return self.apply(text)
+
+    def __repr__(self) -> str:
+        return f"<Normalizer {self.name!r}>"
+
+
+def register(cls: type[Normalizer]) -> type[Normalizer]:
+    """Decorator that registers a Normalizer subclass by its ``name`` attribute."""
+    if not getattr(cls, "name", ""):
+        raise ValueError(f"{cls.__name__} must define a 'name'.")
+    if cls.name in _REGISTRY:
+        raise ValueError(f"The name '{cls.name}' is already registered.")
+    _REGISTRY[cls.name] = cls
+    return cls
+
+
+def get_registry() -> dict[str, type[Normalizer]]:
+    """Return a copy of all registered normalizer classes."""
+    return dict(_REGISTRY)
+
+
+def available_features() -> list[str]:
+    """List the available concept names."""
+    return sorted(_REGISTRY)

turkificate-0.1.0/data.py

@@ -0,0 +1,107 @@
+"""Lexical data: month names, abbreviations, units, symbols, currencies.
+
+Keeping this data in one place lets the normalizers build their regexes from it
+and makes extending the library (adding a new abbreviation, etc.) a one-line change.
+
+The values are intentionally Turkish — they are the spoken/written forms the
+library emits.
+"""
+
+# 1..12 -> month name
+MONTHS = {
+    1: "Ocak", 2: "Şubat", 3: "Mart", 4: "Nisan",
+    5: "Mayıs", 6: "Haziran", 7: "Temmuz", 8: "Ağustos",
+    9: "Eylül", 10: "Ekim", 11: "Kasım", 12: "Aralık",
+}
+
+# Lexical abbreviations (matched case-insensitively). Keys are lowercase.
+ABBREVIATIONS = {
+    "dr.": "doktor",
+    "prof.": "profesör",
+    "doç.": "doçent",
+    "yrd.": "yardımcı",
+    "av.": "avukat",
+    "sn.": "sayın",
+    "vs.": "vesaire",
+    "vb.": "ve benzeri",
+    "vd.": "ve diğerleri",
+    "bkz.": "bakınız",
+    "örn.": "örneğin",
+    "yy.": "yüzyıl",
+    "no.": "numara",
+    "tel.": "telefon",
+    "cad.": "cadde",
+    "sok.": "sokak",
+    "apt.": "apartman",
+    "mah.": "mahalle",
+}
+
+# Units of measure (expanded only when they follow a number).
+# Longer keys must appear before shorter prefix-matches (e.g. "°C" before "°").
+UNITS = {
+    "°C": "derece",
+    "°F": "fahrenheit",
+    "km²": "kilometre kare",
+    "m²": "metre kare",
+    "m³": "metre küp",
+    "km/h": "kilometre bölü saat",
+    "km/sa": "kilometre bölü saat",
+    "m/s": "metre bölü saniye",
+    "kWh": "kilowatt saat",
+    "GHz": "gigahertz",
+    "MHz": "megahertz",
+    "kHz": "kilohertz",
+    "Hz": "hertz",
+    "kW": "kilowatt",
+    "MW": "megawatt",
+    "km": "kilometre",
+    "cm": "santimetre",
+    "mm": "milimetre",
+    "kg": "kilogram",
+    "mg": "miligram",
+    "gr": "gram",
+    "ml": "mililitre",
+    "lt": "litre",
+    "kb": "kilobayt",
+    "mb": "megabayt",
+    "gb": "gigabayt",
+    "tb": "terabayt",
+    "sa": "saat",
+    "dk": "dakika",
+    "sn": "saniye",
+    "m": "metre",
+    "g": "gram",
+    "l": "litre",
+}
+
+# Currency symbols and codes -> spoken form.
+CURRENCY = {
+    "₺": "lira",
+    "tl": "lira",
+    "try": "lira",
+    "$": "dolar",
+    "usd": "dolar",
+    "€": "avro",
+    "eur": "avro",
+    "£": "sterlin",
+    "gbp": "sterlin",
+    "₽": "ruble",
+}
+
+# Single-character symbols -> spoken form.
+SYMBOLS = {
+    "&": "ve",
+    "@": "et",
+    "°": "derece",
+    "×": "çarpı",
+    "÷": "bölü",
+    "+": "artı",
+    "=": "eşittir",
+    "₊": "artı",
+    "≠": "eşit değil",
+    "≤": "küçük eşit",
+    "≥": "büyük eşit",
+    "√": "karekök",
+    "∞": "sonsuz",
+    "π": "pi",
+}