refactor: better information hiding

Author: nalgeon

README.md

@@ -8,7 +8,7 @@ Transliteration means representing Cyrillic data (mainly names and geographic lo
 
 ```python
 >>> import iuliia
->>> iuliia.translate("Юлия Щеглова", schema=iuliia.WIKIPEDIA)
+>>> iuliia.WIKIPEDIA.translate("Юлия Щеглова")
 'Yuliya Shcheglova'
 ```
 
@@ -31,6 +31,22 @@ pip install iuliia
 
 ## Usage
 
+Transliterate using specified schema:
+
+```python
+>>> source = "Юлия Щеглова"
+>>> iuliia.ICAO_DOC_9303.translate(source)
+'Iuliia Shcheglova'
+```
+
+Or pick schema by name
+
+```python
+>>> schema = iuliia.Schemas.get("wikipedia")
+>>> schema.translate(source)
+'Yuliya Shcheglova'
+```
+
 List all supported schemas:
 
 ```python
@@ -70,22 +86,6 @@ yandex_maps         Yandex.Maps transliteration schema
 yandex_money        Yandex.Money transliteration schema
 ```
 
-Transliterate using specified schema:
-
-```python
->>> source = "Юлия Щеглова"
->>> iuliia.translate(source, schema=iuliia.ICAO_DOC_9303)
-'Iuliia Shcheglova'
-```
-
-Or pick schema by name
-
-```python
->>> schema = iuliia.Schemas.get("wikipedia")
->>> iuliia.translate(source, schema)
-'Yuliya Shcheglova'
-```
-
 Command line:
 
 ```sh

iuliia/__init__.py

@@ -2,38 +2,69 @@
 Transliterate Cyrillic → Latin in every possible way
 """
 
-# flake8: noqa
 from .engine import translate
 from .schema import Schema
 from .schemas import Schemas
 
-__all__ = []  # type: ignore
+__all__ = [
+    "translate",
+    "Schema",
+    "Schemas",
+    "ALA_LC",
+    "ALA_LC_ALT",
+    "BGN_PCGN",
+    "BGN_PCGN_ALT",
+    "BS_2979",
+    "BS_2979_ALT",
+    "GOST_16876",
+    "GOST_16876_ALT",
+    "GOST_52290",
+    "GOST_52535",
+    "GOST_7034",
+    "GOST_779",
+    "GOST_779_ALT",
+    "ICAO_DOC_9303",
+    "ISO_9_1954",
+    "ISO_9_1968",
+    "ISO_9_1968_ALT",
+    "MOSMETRO",
+    "MVD_310",
+    "MVD_310_FR",
+    "MVD_782",
+    "SCIENTIFIC",
+    "TELEGRAM",
+    "UNGEGN_1987",
+    "UZ",
+    "WIKIPEDIA",
+    "YANDEX_MAPS",
+    "YANDEX_MONEY",
+]
 
-ALA_LC = Schemas.ala_lc.value  # type: ignore
-ALA_LC_ALT = Schemas.ala_lc_alt.value  # type: ignore
-BGN_PCGN = Schemas.bgn_pcgn.value  # type: ignore
-BGN_PCGN_ALT = Schemas.bgn_pcgn_alt.value  # type: ignore
-BS_2979 = Schemas.bs_2979.value  # type: ignore
-BS_2979_ALT = Schemas.bs_2979_alt.value  # type: ignore
-GOST_16876 = Schemas.gost_16876.value  # type: ignore
-GOST_16876_ALT = Schemas.gost_16876_alt.value  # type: ignore
-GOST_52290 = Schemas.gost_52290.value  # type: ignore
-GOST_52535 = Schemas.gost_52535.value  # type: ignore
-GOST_7034 = Schemas.gost_7034.value  # type: ignore
-GOST_779 = Schemas.gost_779.value  # type: ignore
-GOST_779_ALT = Schemas.gost_779_alt.value  # type: ignore
-ICAO_DOC_9303 = Schemas.icao_doc_9303.value  # type: ignore
-ISO_9_1954 = Schemas.iso_9_1954.value  # type: ignore
-ISO_9_1968 = Schemas.iso_9_1968.value  # type: ignore
-ISO_9_1968_ALT = Schemas.iso_9_1968_alt.value  # type: ignore
-MOSMETRO = Schemas.mosmetro.value  # type: ignore
-MVD_310 = Schemas.mvd_310.value  # type: ignore
-MVD_310_FR = Schemas.mvd_310_fr.value  # type: ignore
-MVD_782 = Schemas.mvd_782.value  # type: ignore
-SCIENTIFIC = Schemas.scientific.value  # type: ignore
-TELEGRAM = Schemas.telegram.value  # type: ignore
-UNGEGN_1987 = Schemas.ungegn_1987.value  # type: ignore
-UZ = Schemas.uz.value  # type: ignore
-WIKIPEDIA = Schemas.wikipedia.value  # type: ignore
-YANDEX_MAPS = Schemas.yandex_maps.value  # type: ignore
-YANDEX_MONEY = Schemas.yandex_money.value  # type: ignore
+ALA_LC = Schemas.ala_lc.value
+ALA_LC_ALT = Schemas.ala_lc_alt.value
+BGN_PCGN = Schemas.bgn_pcgn.value
+BGN_PCGN_ALT = Schemas.bgn_pcgn_alt.value
+BS_2979 = Schemas.bs_2979.value
+BS_2979_ALT = Schemas.bs_2979_alt.value
+GOST_16876 = Schemas.gost_16876.value
+GOST_16876_ALT = Schemas.gost_16876_alt.value
+GOST_52290 = Schemas.gost_52290.value
+GOST_52535 = Schemas.gost_52535.value
+GOST_7034 = Schemas.gost_7034.value
+GOST_779 = Schemas.gost_779.value
+GOST_779_ALT = Schemas.gost_779_alt.value
+ICAO_DOC_9303 = Schemas.icao_doc_9303.value
+ISO_9_1954 = Schemas.iso_9_1954.value
+ISO_9_1968 = Schemas.iso_9_1968.value
+ISO_9_1968_ALT = Schemas.iso_9_1968_alt.value
+MOSMETRO = Schemas.mosmetro.value
+MVD_310 = Schemas.mvd_310.value
+MVD_310_FR = Schemas.mvd_310_fr.value
+MVD_782 = Schemas.mvd_782.value
+SCIENTIFIC = Schemas.scientific.value
+TELEGRAM = Schemas.telegram.value
+UNGEGN_1987 = Schemas.ungegn_1987.value
+UZ = Schemas.uz.value
+WIKIPEDIA = Schemas.wikipedia.value
+YANDEX_MAPS = Schemas.yandex_maps.value
+YANDEX_MONEY = Schemas.yandex_money.value

iuliia/__main__.py

@@ -22,7 +22,7 @@ def main():
         sys.exit(1)
 
     source = sys.argv[2]
-    result = iuliia.translate(source, schema)
+    result = schema.translate(source)
     print(result)
 
 

iuliia/engine.py

@@ -1,79 +1,20 @@
 """
-Translate engine.
+Translate engine (deprecated).
 """
 
-import re
-from typing import Iterator
+import warnings
 from .schema import Schema
 
-SPLITTER = re.compile(r"\b")
-
 
 def translate(source: str, schema: Schema) -> str:
     """
-    Translate source Cyrillic string into Latin using specified schema.
-    Translates sentences word by word, delegating specifics of transliteration
-    to specified schema.
-    """
-    words = (word for word in SPLITTER.split(source) if word)
-    translated = (_translate_word(word, schema) for word in words)
-    return "".join(translated)
-
-
-def _translate_word(word: str, schema: Schema) -> str:
-    """Translate word using specified schema."""
-    stem, ending = _split_word(word)
-    translated_ending = schema.translate_ending(ending)
-    if translated_ending:
-        # There is a specific translation for the ending,
-        # so we need to translate the stem and ending separately.
-        translated = _translate_letters(stem, schema)
-        translated.append(translated_ending)
-    else:
-        # There is no specific translation for the ending,
-        # so we can translate the whole word at once.
-        translated = _translate_letters(word, schema)
-    return "".join(translated)
-
-
-def _translate_letters(word: str, schema: Schema) -> list[str]:
-    """Translate letters of a word using specified schema."""
-    translated = []
-    for prev, curr, next_ in _letter_reader(word):
-        letter = schema.translate_letter(prev, curr, next_)
-        translated.append(letter)
-    return translated
-
-
-def _split_word(word: str) -> tuple[str, str]:
-    """
-    Split word into stem and ending.
-    Ending is the last two letters of the word.
-    """
-    ending_length = 2
-    if len(word) > ending_length:
-        stem = word[:-ending_length]
-        ending = word[-ending_length:]
-    else:
-        stem = word
-        ending = ""
-    return stem, ending
-
-
-def _letter_reader(stem: str) -> Iterator[tuple[str, str, str]]:
-    """
-    Yield letters of a word in (prev, curr, next) tuples.
-    E.g. for "word" it will yield:
-        ("", "w", "o")
-        ("w", "o", "r")
-        ("o", "r", "d")
-        ("r", "d", "")
+    Translate the Cyrillic string into Latin using the provided schema.
+    Delegates transliteration specifics to the schema.
+    DEPRECATED: Use schema.translate() instead.
     """
-    if not stem:
-        return
-    it = iter(stem)
-    prev, curr = "", next(it, "")
-    for next_ in it:
-        yield prev, curr, next_
-        prev, curr = curr, next_
-    yield prev, curr, ""
+    warnings.warn(
+        "The 'translate' function is deprecated. Use schema.translate() instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return schema.translate(source)

iuliia/lazy.py

@@ -0,0 +1,78 @@
+"""
+Lazy schema loader.
+"""
+
+import json
+from pathlib import Path
+from .schema import TranslitSchema
+from .validator import Validator
+
+
+class Loader:
+    """Loads transliteration schemas from JSON files."""
+
+    def __init__(self):
+        self.base_path = Path(__file__).parent / "schemas"
+
+    def load(self, name: str) -> TranslitSchema:
+        """Load schema by its name."""
+        path = self.base_path / f"{name}.json"
+        if not path.exists():
+            raise ValueError(f"Schema path does not exist: {path}")
+        defn = self._load_definition(path)
+        Validator(defn).run()
+        return TranslitSchema(
+            name=defn.get("name", ""),
+            description=defn.get("description"),
+            mapping=defn.get("mapping", {}),
+            prev_mapping=defn.get("prev_mapping"),
+            next_mapping=defn.get("next_mapping"),
+            ending_mapping=defn.get("ending_mapping"),
+            samples=defn.get("samples"),
+        )
+
+    def _load_definition(self, path: str | Path) -> dict:
+        with open(path, encoding="utf-8") as file:
+            return json.load(file)
+
+
+class LazySchema:
+    """
+    Transliteration schema. Translates Cyrillic text into Latin
+    using a given set of rules (mappings).
+    Lazy loads schema from JSON file as needed.
+    """
+
+    def __init__(self, name: str):
+        self.name = name
+        self._loader = Loader()
+        self._schema: TranslitSchema | None = None
+
+    @property
+    def description(self) -> str | None:
+        """Schema description."""
+        if self._schema is None:
+            self._schema = self._loader.load(self.name)
+        return self._schema.description
+
+    @property
+    def samples(self) -> list[list[str]]:
+        """Schema samples."""
+        if self._schema is None:
+            self._schema = self._loader.load(self.name)
+        return self._schema.samples
+
+    def translate(self, source: str) -> str:
+        """
+        Translate source Cyrillic string into Latin.
+        Translates the source string word by word.
+        """
+        if self._schema is None:
+            self._schema = self._loader.load(self.name)
+        return self._schema.translate(source)
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}('{self.name}')"