scriptconv 0.0.3a1__tar.gz → 0.0.3a3__tar.gz

{scriptconv-0.0.3a1 → scriptconv-0.0.3a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scriptconv
-Version: 0.0.3a1
+Version: 0.0.3a3
 Summary: Zero-dependency script & phoneme-notation core — ISO-15924 detection & metadata, IPA↔ARPABET/X-SAMPA/Lexique/Kirshenbaum/Cotovía/RFE, Buckwalter↔Arabic, Hangul→jamo, kana
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/TigreGotico/scriptconv
@@ -20,9 +20,15 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: ja
+Requires-Dist: pykakasi<3,>=2.3; extra == "ja"
+Provides-Extra: zh
+Requires-Dist: pypinyin<1,>=0.50; extra == "zh"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-timeout; extra == "test"
+Requires-Dist: pykakasi<3,>=2.3; extra == "test"
+Requires-Dist: pypinyin<1,>=0.50; extra == "test"
 Dynamic: license-file
 
 # scriptconv

{scriptconv-0.0.3a1 → scriptconv-0.0.3a3}/pyproject.toml

@@ -33,7 +33,9 @@ version = {attr = "scriptconv.version.VERSION_STR"}
 dependencies = {file = ["requirements.txt"]}
 
 [project.optional-dependencies]
-test = ["pytest", "pytest-timeout"]
+ja = ["pykakasi>=2.3,<3"]
+zh = ["pypinyin>=0.50,<1"]
+test = ["pytest", "pytest-timeout", "pykakasi>=2.3,<3", "pypinyin>=0.50,<1"]
 
 [project.urls]
 Homepage = "https://github.com/TigreGotico/scriptconv"

{scriptconv-0.0.3a1 → scriptconv-0.0.3a3}/scriptconv/__init__.py

@@ -17,8 +17,12 @@ notation:
 translit:
     Script-level decomposition and transliteration (Hangul → jamo,
     Hiragana ↔ Katakana).
+readings:
+    Dictionary-backed respelling (Japanese kanji → kana via the ``ja``
+    extra; Chinese hanzi → pinyin/bopomofo via the ``zh`` extra).
 
-Zero runtime dependencies (stdlib only).
+Zero required runtime dependencies (stdlib only); the readings module
+needs the optional ``ja``/``zh`` extras.
 """
 
 from scriptconv.scripts import (
@@ -61,6 +65,12 @@ from scriptconv.translit import (
     hira_to_kana,
     kana_to_hira,
 )
+from scriptconv.readings import (
+    to_hiragana,
+    to_katakana,
+    to_pinyin,
+    to_bopomofo,
+)
 
 __all__ = [
     # scripts
@@ -100,4 +110,9 @@ __all__ = [
     "decompose_hangul",
     "hira_to_kana",
     "kana_to_hira",
+    # readings (dictionary-backed, needs scriptconv[ja])
+    "to_hiragana",
+    "to_katakana",
+    "to_pinyin",
+    "to_bopomofo",
 ]

scriptconv-0.0.3a3/scriptconv/readings.py

@@ -0,0 +1,119 @@
+"""Dictionary-backed script respelling (Japanese kanji → kana, Chinese hanzi → pinyin/bopomofo).
+
+Unlike the table-driven modules (:mod:`scriptconv.translit`,
+:mod:`scriptconv.notation`), converting kanji to kana is not a codepoint
+mapping: a kanji's kana spelling is a *lexical* property resolved against a
+reading dictionary, and genuinely ambiguous readings are decided by the
+dictionary's segmentation.  This is still orthography — the output is how the
+word is written in kana, exactly as an IME or furigana would render it — not
+phonemization; no sound rules are applied.
+
+The same reasoning covers Chinese: a hanzi's pinyin or bopomofo spelling is a
+lexical property with genuinely ambiguous readings (heteronyms such as 行
+xíng/háng) resolved by a phrase dictionary — standard orthographic respelling,
+not phonemization.
+
+Because it needs reading dictionaries, this module requires optional
+dependencies: ``pykakasi`` for Japanese (``pip install scriptconv[ja]``) and
+``pypinyin`` for Chinese (``pip install scriptconv[zh]``).  Importing the
+module is always safe; the dependency is resolved on first conversion and a
+missing dictionary raises :class:`ImportError` rather than silently returning
+unconverted text.
+"""
+from __future__ import annotations
+
+__all__ = ["to_hiragana", "to_katakana", "to_pinyin", "to_bopomofo"]
+
+_kakasi = None
+
+_HIRA = range(0x3040, 0x30A0)
+_KANA = range(0x30A0, 0x3100)
+
+
+def _converter():
+    global _kakasi
+    if _kakasi is None:
+        try:
+            import pykakasi
+        except ImportError:
+            raise ImportError(
+                "kanji→kana conversion needs the reading dictionary from "
+                "pykakasi — install with `pip install scriptconv[ja]`"
+            ) from None
+        _kakasi = pykakasi.kakasi()
+    return _kakasi
+
+
+def to_hiragana(text: str, keep_katakana: bool = False) -> str:
+    """Respell Japanese text in hiragana.
+
+    Kanji are resolved to their dictionary reading; existing kana and any
+    non-Japanese characters pass through.  With ``keep_katakana=True``,
+    katakana tokens keep their original script (useful when katakana marks
+    loanwords deliberately) instead of being folded into hiragana.
+    """
+    out = []
+    for token in _converter().convert(text):
+        orig = token["orig"]
+        if keep_katakana and orig and all(ord(c) in _KANA or not _is_japanese(c)
+                                          for c in orig):
+            out.append(orig)
+        else:
+            out.append(token["hira"])
+    return "".join(out)
+
+
+def to_katakana(text: str) -> str:
+    """Respell Japanese text in katakana.
+
+    Kanji are resolved to their dictionary reading; existing kana are
+    transposed to katakana and any non-Japanese characters pass through.
+    """
+    return "".join(token["kana"] for token in _converter().convert(text))
+
+
+def _is_japanese(ch: str) -> bool:
+    cp = ord(ch)
+    return cp in _HIRA or cp in _KANA or 0x4E00 <= cp <= 0x9FFF
+
+
+_PINYIN_STYLES = None
+
+
+def _pinyin(text: str, style_name: str) -> str:
+    global _PINYIN_STYLES
+    if _PINYIN_STYLES is None:
+        try:
+            from pypinyin import Style, lazy_pinyin
+        except ImportError:
+            raise ImportError(
+                "hanzi→pinyin/bopomofo conversion needs the phrase dictionary "
+                "from pypinyin — install with `pip install scriptconv[zh]`"
+            ) from None
+        _PINYIN_STYLES = {"mark": Style.TONE, "number": Style.TONE3,
+                          "none": Style.NORMAL, "bopomofo": Style.BOPOMOFO,
+                          "_fn": lazy_pinyin}
+    if style_name not in _PINYIN_STYLES:
+        raise ValueError(f"tone must be one of 'mark', 'number', 'none' — got {style_name!r}")
+    tokens = _PINYIN_STYLES["_fn"](text, style=_PINYIN_STYLES[style_name])
+    return " ".join(" ".join(tokens).split())
+
+
+def to_pinyin(text: str, tone: str = "mark") -> str:
+    """Respell Chinese text in pinyin, syllables space-separated.
+
+    Hanzi are resolved to their dictionary reading (heteronyms decided by
+    pypinyin's phrase dictionary); non-Chinese characters pass through.
+    ``tone`` selects the tone spelling: ``"mark"`` (``zhōng``, default),
+    ``"number"`` (``zhong1``) or ``"none"`` (``zhong``).
+    """
+    return _pinyin(text, tone)
+
+
+def to_bopomofo(text: str) -> str:
+    """Respell Chinese text in bopomofo (zhuyin), syllables space-separated.
+
+    Hanzi are resolved to their dictionary reading; non-Chinese characters
+    pass through.  Tone marks follow zhuyin convention (first tone unmarked).
+    """
+    return _pinyin(text, "bopomofo")

{scriptconv-0.0.3a1 → scriptconv-0.0.3a3}/scriptconv/version.py

@@ -2,7 +2,7 @@
 VERSION_MAJOR = 0
 VERSION_MINOR = 0
 VERSION_BUILD = 3
-VERSION_ALPHA = 1
+VERSION_ALPHA = 3
 # END_VERSION_BLOCK
 
 VERSION_STR = f"{VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_BUILD}"

{scriptconv-0.0.3a1 → scriptconv-0.0.3a3}/scriptconv.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scriptconv
-Version: 0.0.3a1
+Version: 0.0.3a3
 Summary: Zero-dependency script & phoneme-notation core — ISO-15924 detection & metadata, IPA↔ARPABET/X-SAMPA/Lexique/Kirshenbaum/Cotovía/RFE, Buckwalter↔Arabic, Hangul→jamo, kana
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/TigreGotico/scriptconv
@@ -20,9 +20,15 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: ja
+Requires-Dist: pykakasi<3,>=2.3; extra == "ja"
+Provides-Extra: zh
+Requires-Dist: pypinyin<1,>=0.50; extra == "zh"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-timeout; extra == "test"
+Requires-Dist: pykakasi<3,>=2.3; extra == "test"
+Requires-Dist: pypinyin<1,>=0.50; extra == "test"
 Dynamic: license-file
 
 # scriptconv

{scriptconv-0.0.3a1 → scriptconv-0.0.3a3}/scriptconv.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ scriptconv/__init__.py
 scriptconv/__main__.py
 scriptconv/notation.py
 scriptconv/py.typed
+scriptconv/readings.py
 scriptconv/scripts.py
 scriptconv/translit.py
 scriptconv/version.py
@@ -17,5 +18,7 @@ scriptconv.egg-info/top_level.txt
 tests/test_cli.py
 tests/test_examples.py
 tests/test_notation.py
+tests/test_readings.py
+tests/test_readings_zh.py
 tests/test_scripts.py
 tests/test_translit.py

scriptconv-0.0.3a3/scriptconv.egg-info/requires.txt

@@ -0,0 +1,12 @@
+
+[ja]
+pykakasi<3,>=2.3
+
+[test]
+pytest
+pytest-timeout
+pykakasi<3,>=2.3
+pypinyin<1,>=0.50
+
+[zh]
+pypinyin<1,>=0.50

scriptconv-0.0.3a3/tests/test_readings.py

@@ -0,0 +1,73 @@
+import sys
+import unittest
+from unittest import mock
+
+from scriptconv import to_hiragana, to_katakana
+from scriptconv import readings
+
+
+class TestToHiragana(unittest.TestCase):
+    def test_kanji_resolved_to_reading(self):
+        self.assertEqual(to_hiragana("日本語"), "にほんご")
+
+    def test_katakana_folded_by_default(self):
+        self.assertEqual(to_hiragana("コーヒー"), "こーひー")
+
+    def test_keep_katakana_flag_preserves_loanwords(self):
+        self.assertEqual(to_hiragana("コーヒー", keep_katakana=True), "コーヒー")
+
+    def test_keep_katakana_still_converts_kanji(self):
+        out = to_hiragana("私はコーヒーが好き", keep_katakana=True)
+        self.assertIn("コーヒー", out)
+        self.assertNotIn("私", out)
+        self.assertNotIn("好", out)
+
+    def test_hiragana_passes_through(self):
+        self.assertEqual(to_hiragana("こんにちは"), "こんにちは")
+
+    def test_non_japanese_passes_through(self):
+        self.assertEqual(to_hiragana("OVOS 123!"), "OVOS 123!")
+
+    def test_mixed_script_sentence(self):
+        out = to_hiragana("東京タワーは333mです")
+        self.assertIn("とうきょう", out)
+        self.assertIn("333m", out)
+
+    def test_empty_string(self):
+        self.assertEqual(to_hiragana(""), "")
+
+
+class TestToKatakana(unittest.TestCase):
+    def test_kanji_resolved_to_reading(self):
+        self.assertEqual(to_katakana("日本語"), "ニホンゴ")
+
+    def test_hiragana_transposed(self):
+        self.assertEqual(to_katakana("こんにちは"), "コンニチハ")
+
+    def test_katakana_passes_through(self):
+        self.assertEqual(to_katakana("コーヒー"), "コーヒー")
+
+    def test_non_japanese_passes_through(self):
+        self.assertEqual(to_katakana("OVOS 123!"), "OVOS 123!")
+
+    def test_empty_string(self):
+        self.assertEqual(to_katakana(""), "")
+
+
+class TestDependencyBoundary(unittest.TestCase):
+    def test_missing_pykakasi_raises_with_install_hint(self):
+        with mock.patch.object(readings, "_kakasi", None), \
+                mock.patch.dict(sys.modules, {"pykakasi": None}):
+            with self.assertRaises(ImportError) as ctx:
+                to_hiragana("日本語")
+            self.assertIn("scriptconv[ja]", str(ctx.exception))
+
+    def test_converter_instance_is_cached(self):
+        to_hiragana("日本語")
+        first = readings._kakasi
+        to_katakana("日本語")
+        self.assertIs(readings._kakasi, first)
+
+
+if __name__ == "__main__":
+    unittest.main()

scriptconv-0.0.3a3/tests/test_readings_zh.py

@@ -0,0 +1,78 @@
+import sys
+import unittest
+from unittest import mock
+
+from scriptconv import to_pinyin, to_bopomofo
+from scriptconv import readings
+
+
+class TestToPinyin(unittest.TestCase):
+    def test_hanzi_resolved_with_tone_marks(self):
+        self.assertEqual(to_pinyin("中国人"), "zhōng guó rén")
+
+    def test_tone_number_style(self):
+        self.assertEqual(to_pinyin("中国人", tone="number"), "zhong1 guo2 ren2")
+
+    def test_tone_none_style(self):
+        self.assertEqual(to_pinyin("中国人", tone="none"), "zhong guo ren")
+
+    def test_heteronym_resolved_by_phrase_context(self):
+        # 行 reads háng in 银行 (bank) but xíng in 行走 (to walk)
+        self.assertIn("háng", to_pinyin("银行"))
+        self.assertIn("xíng", to_pinyin("行走"))
+
+    def test_non_chinese_passes_through(self):
+        self.assertEqual(to_pinyin("OVOS 123!"), "OVOS 123!")
+
+    def test_mixed_script_sentence(self):
+        out = to_pinyin("我有3个apple")
+        self.assertIn("wǒ", out)
+        self.assertIn("apple", out)
+
+    def test_invalid_tone_raises_value_error(self):
+        with self.assertRaises(ValueError):
+            to_pinyin("中", tone="fancy")
+
+    def test_empty_string(self):
+        self.assertEqual(to_pinyin(""), "")
+
+
+class TestToBopomofo(unittest.TestCase):
+    def test_hanzi_resolved_to_zhuyin(self):
+        self.assertEqual(to_bopomofo("中国"), "ㄓㄨㄥ ㄍㄨㄛˊ")
+
+    def test_first_tone_unmarked_second_tone_marked(self):
+        out = to_bopomofo("中国")
+        self.assertNotIn("ˉ", out)
+        self.assertIn("ˊ", out)
+
+    def test_non_chinese_passes_through(self):
+        self.assertEqual(to_bopomofo("OVOS 123!"), "OVOS 123!")
+
+    def test_empty_string(self):
+        self.assertEqual(to_bopomofo(""), "")
+
+
+class TestDependencyBoundary(unittest.TestCase):
+    def test_missing_pypinyin_raises_with_install_hint(self):
+        with mock.patch.object(readings, "_PINYIN_STYLES", None), \
+                mock.patch.dict(sys.modules, {"pypinyin": None}):
+            with self.assertRaises(ImportError) as ctx:
+                to_pinyin("中国")
+            self.assertIn("scriptconv[zh]", str(ctx.exception))
+
+    def test_style_table_is_cached(self):
+        to_pinyin("中国")
+        first = readings._PINYIN_STYLES
+        to_bopomofo("中国")
+        self.assertIs(readings._PINYIN_STYLES, first)
+
+    def test_chinese_and_japanese_backends_independent(self):
+        # pypinyin absence must not break Japanese conversion
+        with mock.patch.object(readings, "_PINYIN_STYLES", None), \
+                mock.patch.dict(sys.modules, {"pypinyin": None}):
+            self.assertEqual(readings.to_hiragana("日本語"), "にほんご")
+
+
+if __name__ == "__main__":
+    unittest.main()

scriptconv-0.0.3a1/scriptconv.egg-info/requires.txt

@@ -1,4 +0,0 @@
-
-[test]
-pytest
-pytest-timeout