scriptconv 0.0.3a7__tar.gz → 0.0.3a8__tar.gz

{scriptconv-0.0.3a7 → scriptconv-0.0.3a8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scriptconv
-Version: 0.0.3a7
+Version: 0.0.3a8
 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

{scriptconv-0.0.3a7 → scriptconv-0.0.3a8}/scriptconv/__init__.py

@@ -22,6 +22,10 @@ readings:
     extra; Chinese hanzi → pinyin/bopomofo via the ``zh`` extra).
 cangjie:
     Hanzi → Cangjie5 input codes (shape decomposition, vendored table).
+graph:
+    Conversion-graph engine: representations (notations and orthographies)
+    as nodes, registered transforms as edges, lossless-preferring routing.
+    External packages extend graph instances explicitly.
 conventions:
     Orthographic conventions — script-scoped decorations orthogonal to
     identity (tashkeel, niqqud, wakachigaki, pinyin tone spelling…).
@@ -81,6 +85,7 @@ from scriptconv.readings import (
 )
 from scriptconv.conventions import (
     Convention,
+    Transition,
     CONVENTION_REGISTRY,
     conventions_for,
     restyle,
@@ -88,6 +93,13 @@ from scriptconv.conventions import (
     apply,
     detect as detect_convention,
 )
+from scriptconv.graph import (
+    Representation,
+    Edge,
+    ConversionGraph,
+    DEFAULT_GRAPH,
+    REPRESENTATIONS,
+)
 from scriptconv.cangjie import (
     cangjie_code,
     to_cangjie,
@@ -138,12 +150,19 @@ __all__ = [
     "to_katakana",
     # conventions (orthographic decorations, orthogonal to script identity)
     "Convention",
+    "Transition",
     "CONVENTION_REGISTRY",
     "conventions_for",
     "restyle",
     "strip",
     "apply",
     "detect_convention",
+    # graph (conversion routing engine over representations)
+    "Representation",
+    "Edge",
+    "ConversionGraph",
+    "DEFAULT_GRAPH",
+    "REPRESENTATIONS",
     # cangjie (vendored Cangjie5 table)
     "cangjie_code",
     "to_cangjie",

{scriptconv-0.0.3a7 → scriptconv-0.0.3a8}/scriptconv/__main__.py

@@ -11,6 +11,7 @@ Usage
     python -m scriptconv strip <convention> <text>
     python -m scriptconv restyle <convention> <style> <text>
     python -m scriptconv conventions [--script CODE]
+    python -m scriptconv route <src> <dst>
 
 Examples
 --------
@@ -64,6 +65,10 @@ def main(argv: list[str] | None = None) -> int:
     cv = sub.add_parser("conventions", help="List orthographic conventions")
     cv.add_argument("--script", default=None, help="Filter by ISO-15924 script code")
 
+    rt = sub.add_parser("route", help="Show the conversion path between representations")
+    rt.add_argument("src", help="Source representation id")
+    rt.add_argument("dst", help="Target representation id")
+
     args = p.parse_args(argv)
 
     if args.command is None:
@@ -80,6 +85,7 @@ def main(argv: list[str] | None = None) -> int:
         "strip": lambda: _do_strip(args),
         "restyle": lambda: _do_restyle(args),
         "conventions": lambda: _do_conventions(args),
+        "route": lambda: _do_route(args),
     }
     dispatch[args.command]()
     return 0
@@ -89,9 +95,31 @@ def _do_convert(args: argparse.Namespace) -> None:
     from scriptconv.notation import Notation, convert
     try:
         print(convert(args.text, args.src, args.dst))
+        return
+    except ValueError:
+        pass
+    # not a notation pair — try any representation pair on the default graph
+    from scriptconv.graph import DEFAULT_GRAPH
+    try:
+        print(DEFAULT_GRAPH.convert(args.text, args.src, args.dst))
     except ValueError as e:
         valid = ", ".join(n.value for n in Notation)
-        raise SystemExit(f"error: {e} (valid notations: {valid})")
+        raise SystemExit(f"error: {e} (valid notations: {valid}; "
+                         f"graph nodes: {', '.join(DEFAULT_GRAPH.nodes)})")
+
+
+def _do_route(args: argparse.Namespace) -> None:
+    from scriptconv.graph import DEFAULT_GRAPH
+    try:
+        path = DEFAULT_GRAPH.route(args.src, args.dst)
+    except ValueError as e:
+        raise SystemExit(f"error: {e}")
+    if not path:
+        print("(identity)")
+    for e in path:
+        flags = "lossless" if e.lossless else "lossy"
+        extra = f", needs scriptconv[{e.requires}]" if e.requires else ""
+        print(f"  {e.src} -> {e.dst}  ({flags}, cost {e.cost:g}{extra})")
 
 
 def _do_detect(args: argparse.Namespace) -> None:

{scriptconv-0.0.3a7 → scriptconv-0.0.3a8}/scriptconv/conventions.py

@@ -43,6 +43,7 @@ repertoires and the restyle is deterministic.
 """
 from __future__ import annotations
 
+import functools
 import re
 import unicodedata
 from dataclasses import dataclass
@@ -50,6 +51,7 @@ from typing import Callable, Dict, List, Optional, Tuple
 
 __all__ = [
     "Convention",
+    "Transition",
     "CONVENTION_REGISTRY",
     "conventions_for",
     "detect",
@@ -59,98 +61,118 @@ __all__ = [
 ]
 
 
+@dataclass(frozen=True)
+class Transition:
+    """One rewrite between two styles of a convention.
+
+    ``fn`` is a pure ``str -> str`` transform.  ``requires`` names the
+    optional extra the transform needs, if any (queryable before calling —
+    the transform itself raises :class:`ImportError` with an install hint
+    when the dependency is missing).
+    """
+    frm: str
+    to: str
+    fn: Callable[[str], str]
+    lossless: bool = False
+    requires: Optional[str] = None
+
+
 @dataclass(frozen=True)
 class Convention:
-    """Metadata for one orthographic convention (NotationInfo-style: data, not prose)."""
+    """One orthographic convention: metadata plus the behavior that owns it.
+
+    Transitions and the optional detector live on the convention itself, so
+    every operation is generic — nothing in this module branches on a
+    convention's identity.
+    """
     id: str
     name: str
     scripts: Tuple[str, ...]           # ISO-15924 codes whose text it decorates
     system: Optional[str]              # sub-script system qualifier ("pinyin", "japanese")
     styles: Tuple[str, ...]            # mutually exclusive states; includes "none" if strippable
     default_style: str
-    detectable: bool                   # current style is character-evident
-    strip_lossless: bool               # can the stripped information be recovered?
-    apply_requires: Optional[str]      # optional-extra name needed to leave "none", if any
     ranges: Tuple[Tuple[int, int], ...]  # decoration codepoints (empty for spacing/variant conventions)
     reference: str
+    transitions: Tuple[Transition, ...] = ()
+    detector: Optional[Callable[[str], Optional[str]]] = None
+
+    @property
+    def detectable(self) -> bool:
+        return self.detector is not None
+
+    @property
+    def strip_lossless(self) -> bool:
+        stripping = [t for t in self.transitions if t.to == "none"]
+        return bool(stripping) and all(t.lossless for t in stripping)
+
+    @property
+    def apply_requires(self) -> Optional[str]:
+        return next((t.requires for t in self.transitions if t.frm == "none"), None)
+
+    def transition(self, frm: str, to: str) -> Optional[Transition]:
+        return next((t for t in self.transitions
+                     if t.frm == frm and t.to == to), None)
+
+    def restyle(self, text: str, to: str, frm: Optional[str] = None) -> str:
+        """Rewrite *text* from one style of this convention to another."""
+        if to not in self.styles and to != "none":
+            raise ValueError(f"{self.id!r} has styles {self.styles}, not {to!r}")
+        if frm is None:
+            frm = self._infer_source(text, to)
+        if frm == to:
+            return text
+        t = self.transition(frm, to)
+        if t is None:
+            supported = sorted(f"{x.frm}->{x.to}" for x in self.transitions)
+            raise ValueError(f"{self.id!r} does not define {frm!r}->{to!r}; "
+                             f"supported: {', '.join(supported)}")
+        return t.fn(text)
+
+    def _infer_source(self, text: str, to: str) -> str:
+        if self.detector is not None:
+            detected = self.detector(text)
+            if detected is not None and (detected == to
+                                         or self.transition(detected, to)):
+                return detected
+        sources = sorted({t.frm for t in self.transitions if t.to == to})
+        if len(sources) == 1:
+            return sources[0]
+        if self.default_style != to:
+            return self.default_style
+        raise ValueError(f"{self.id!r}: source style for ->{to!r} is ambiguous "
+                         f"({', '.join(sources)}); pass frm=")
+
+    def strip(self, text: str) -> str:
+        """Remove this convention's decoration (restyle to ``"none"``)."""
+        stripping = [t for t in self.transitions if t.to == "none"]
+        if not stripping:
+            raise ValueError(f"{self.id!r} has no unmarked style; "
+                             f"styles: {self.styles}")
+        # when every stripping transition is the same transform (e.g. one
+        # strip handles both pinyin tone spellings), the source is irrelevant
+        if len({t.fn for t in stripping}) == 1:
+            return stripping[0].fn(text)
+        return self.restyle(text, "none")
+
+    def apply(self, text: str, style: Optional[str] = None) -> str:
+        """Add this convention's decoration to unmarked text."""
+        if style is None:
+            marked = [s for s in self.styles if s != "none"]
+            style = self.default_style if self.default_style != "none" else marked[0]
+        return self.restyle(text, style, frm="none")
+
+    def detect(self, text: str) -> Optional[str]:
+        """Current style of *text*, or None when not character-evident.
+
+        For binary decorations this means "any mark present" — a single
+        shadda in a paragraph reports ``"marked"``.
+        """
+        return self.detector(text) if self.detector is not None else None
 
 
 # ---------------------------------------------------------------------------
-# Registry
+# Shared helpers
 # ---------------------------------------------------------------------------
-# Tashkeel deliberately EXCLUDES U+0653–0655 (madda above, hamza above, hamza
-# below): in NFD text آ/أ/إ decompose to alef + those marks, which are letter
-# identity — stripping them would corrupt the consonantal skeleton.
-_TASHKEEL_RANGES = ((0x064B, 0x0652), (0x0656, 0x065F), (0x0670, 0x0670),
-                    (0x08F0, 0x08F2))
-_KASHIDA_RANGES = ((0x0640, 0x0640),)
-# 06DD/06DE (end of ayah, rub el hizb) are structural signs and 06E5/06E6 are
-# small letters — kept; 06E7-06E9 (small high marks, place of sajdah) and
-# 06EA-06ED are annotation marks — stripped.
-_QURANIC_RANGES = ((0x06D6, 0x06DC), (0x06DF, 0x06E4), (0x06E7, 0x06ED))
-# Niqqud includes dagesh/mapiq U+05BC, meteg U+05BD (a masoretic stress mark,
-# but traditionally stripped with the points), rafe U+05BF and the shin/sin
-# dots U+05C1/05C2 — stripping loses the שׁ/שׂ distinction, exactly as
-# unpointed Hebrew does.  Maqaf U+05BE, sof pasuq U+05C3 and nun hafukha
-# U+05C6 are punctuation and survive.
-_NIQQUD_RANGES = ((0x05B0, 0x05BD), (0x05BF, 0x05BF), (0x05C1, 0x05C2),
-                  (0x05C7, 0x05C7))
-_TEAMIM_RANGES = ((0x0591, 0x05AF), (0x05C0, 0x05C0), (0x05C4, 0x05C5))
-
-CONVENTION_REGISTRY: Dict[str, Convention] = {c.id: c for c in (
-    Convention("tashkeel", "Arabic vocalization (harakat/tanwin/shadda/sukun)",
-               ("Arab",), None, ("marked", "none"), "marked",
-               detectable=True, strip_lossless=False, apply_requires=None,
-               ranges=_TASHKEEL_RANGES,
-               reference="Unicode 15 ch. 9.2 (Arabic); excludes letter-identity U+0653-0655"),
-    Convention("kashida", "Arabic justification elongation (tatweel)",
-               ("Arab",), None, ("marked", "none"), "none",
-               detectable=True, strip_lossless=False, apply_requires=None,
-               ranges=_KASHIDA_RANGES, reference="Unicode U+0640 ARABIC TATWEEL"),
-    Convention("quranic-marks", "Quranic annotation signs",
-               ("Arab",), None, ("marked", "none"), "none",
-               detectable=True, strip_lossless=False, apply_requires=None,
-               ranges=_QURANIC_RANGES, reference="Unicode U+06D6-06ED Quranic annotation signs"),
-    Convention("niqqud", "Hebrew vocalization points",
-               ("Hebr",), None, ("marked", "none"), "marked",
-               detectable=True, strip_lossless=False, apply_requires=None,
-               ranges=_NIQQUD_RANGES,
-               reference="Unicode 15 ch. 9.1 (Hebrew); strip loses the shin/sin dot distinction"),
-    Convention("teamim", "Hebrew cantillation marks",
-               ("Hebr",), None, ("marked", "none"), "none",
-               detectable=True, strip_lossless=False, apply_requires=None,
-               ranges=_TEAMIM_RANGES, reference="Unicode U+0591-05AF Hebrew accents (masoretic)"),
-    Convention("wakachigaki", "Japanese spaced writing (分かち書き)",
-               ("Hira", "Kana", "Hani"), "japanese", ("marked", "none"), "none",
-               detectable=False, strip_lossless=False, apply_requires="ja",
-               ranges=(),
-               reference="Spaced orthographic mode of Japanese (children's books, games)"),
-    Convention("pinyin-tone", "Pinyin tone spelling",
-               ("Latn",), "pinyin", ("mark", "number", "none"), "mark",
-               detectable=False, strip_lossless=False, apply_requires=None,
-               ranges=(),
-               reference="GB/T 16159 Basic rules of Hanyu Pinyin orthography"),
-    Convention("jamo-form", "Hangul jamo repertoire (compatibility vs conjoining)",
-               ("Hang",), None, ("compatibility", "conjoining"), "compatibility",
-               detectable=True, strip_lossless=True, apply_requires=None,
-               ranges=(),
-               reference="Unicode Hangul Compatibility Jamo U+3130 vs Hangul Jamo U+1100"),
-)}
-
-
-def conventions_for(script: str) -> List[Convention]:
-    """Conventions that decorate *script* (ISO-15924 code), registry order."""
-    return [c for c in CONVENTION_REGISTRY.values() if script in c.scripts]
-
-
-def _conv(convention_id: str) -> Convention:
-    try:
-        return CONVENTION_REGISTRY[convention_id]
-    except KeyError:
-        raise ValueError(
-            f"unknown convention {convention_id!r}; known: "
-            f"{', '.join(sorted(CONVENTION_REGISTRY))}") from None
-
 
 def _in_ranges(cp: int, ranges: Tuple[Tuple[int, int], ...]) -> bool:
     return any(lo <= cp <= hi for lo, hi in ranges)
@@ -162,6 +184,12 @@ def _range_strip(ranges: Tuple[Tuple[int, int], ...]) -> Callable[[str], str]:
     return _strip
 
 
+def _range_detector(ranges: Tuple[Tuple[int, int], ...]) -> Callable[[str], Optional[str]]:
+    def _detect(text: str) -> Optional[str]:
+        return "marked" if any(_in_ranges(ord(c), ranges) for c in text) else "none"
+    return _detect
+
+
 # ---------------------------------------------------------------------------
 # Wakachigaki
 # ---------------------------------------------------------------------------
@@ -338,6 +366,7 @@ def _pinyin_strip(text: str) -> str:
 # U+3131), so a consonant is treated as an onset when a vowel follows,
 # otherwise as a coda — deterministic over well-formed jamo sequences.
 
+@functools.lru_cache(maxsize=1)
 def _jamo_tables():
     from scriptconv.translit import _ONSETS as _CO, _VOWELS as _CV, _CODAS as _CT
     conj_to_compat = {}
@@ -357,22 +386,13 @@ def _jamo_tables():
     return conj_to_compat, compat_onset, compat_vowel, compat_coda
 
 
-_JAMO_TABLES = None
-
-
 def _jamo_conjoining_to_compat(text: str) -> str:
-    global _JAMO_TABLES
-    if _JAMO_TABLES is None:
-        _JAMO_TABLES = _jamo_tables()
-    table = _JAMO_TABLES[0]
+    table = _jamo_tables()[0]
     return "".join(table.get(c, c) for c in text)
 
 
 def _jamo_compat_to_conjoining(text: str) -> str:
-    global _JAMO_TABLES
-    if _JAMO_TABLES is None:
-        _JAMO_TABLES = _jamo_tables()
-    _, onset, vowel, coda = _JAMO_TABLES
+    _, onset, vowel, coda = _jamo_tables()
     out = []
     for i, c in enumerate(text):
         if c in vowel:
@@ -401,95 +421,116 @@ def _jamo_detect(text: str) -> Optional[str]:
 
 
 # ---------------------------------------------------------------------------
-# Transition matrix and operations
+# Registry
 # ---------------------------------------------------------------------------
 
-_TRANSITIONS: Dict[Tuple[str, str, str], Callable[[str], str]] = {
-    ("tashkeel", "marked", "none"): _range_strip(_TASHKEEL_RANGES),
-    ("kashida", "marked", "none"): _range_strip(_KASHIDA_RANGES),
-    ("quranic-marks", "marked", "none"): _range_strip(_QURANIC_RANGES),
-    ("niqqud", "marked", "none"): _range_strip(_NIQQUD_RANGES),
-    ("teamim", "marked", "none"): _range_strip(_TEAMIM_RANGES),
-    ("wakachigaki", "marked", "none"): _wakachigaki_strip,
-    ("wakachigaki", "none", "marked"): _wakachigaki_apply,
-    ("pinyin-tone", "mark", "number"): _pinyin_mark_to_number,
-    ("pinyin-tone", "number", "mark"): _pinyin_number_to_mark,
-    ("pinyin-tone", "mark", "none"): _pinyin_strip,
-    ("pinyin-tone", "number", "none"): _pinyin_strip,
-    ("jamo-form", "conjoining", "compatibility"): _jamo_conjoining_to_compat,
-    ("jamo-form", "compatibility", "conjoining"): _jamo_compat_to_conjoining,
-}
+# Tashkeel deliberately EXCLUDES U+0653–0655 (madda above, hamza above, hamza
+# below): in NFD text آ/أ/إ decompose to alef + those marks, which are letter
+# identity — stripping them would corrupt the consonantal skeleton.
+_TASHKEEL_RANGES = ((0x064B, 0x0652), (0x0656, 0x065F), (0x0670, 0x0670),
+                    (0x08F0, 0x08F2))
+_KASHIDA_RANGES = ((0x0640, 0x0640),)
+# 06DD/06DE (end of ayah, rub el hizb) are structural signs and 06E5/06E6 are
+# small letters — kept; 06E7-06E9 (small high marks, place of sajdah) and
+# 06EA-06ED are annotation marks — stripped.
+_QURANIC_RANGES = ((0x06D6, 0x06DC), (0x06DF, 0x06E4), (0x06E7, 0x06ED))
+# Niqqud includes dagesh/mapiq U+05BC, meteg U+05BD (a masoretic stress mark,
+# but traditionally stripped with the points), rafe U+05BF and the shin/sin
+# dots U+05C1/05C2 — stripping loses the שׁ/שׂ distinction, exactly as
+# unpointed Hebrew does.  Maqaf U+05BE, sof pasuq U+05C3 and nun hafukha
+# U+05C6 are punctuation and survive.
+_NIQQUD_RANGES = ((0x05B0, 0x05BD), (0x05BF, 0x05BF), (0x05C1, 0x05C2),
+                  (0x05C7, 0x05C7))
+_TEAMIM_RANGES = ((0x0591, 0x05AF), (0x05C0, 0x05C0), (0x05C4, 0x05C5))
 
 
-def restyle(text: str, convention_id: str, to: str,
-            frm: Optional[str] = None) -> str:
-    """Rewrite *text* from one style of a convention to another.
+def _marks(id: str, name: str, scripts: Tuple[str, ...],
+           ranges: Tuple[Tuple[int, int], ...], reference: str,
+           *, default: str = "marked") -> Convention:
+    """A binary decoration: strippable marks with a range-based detector."""
+    return Convention(id, name, scripts, None, ("marked", "none"), default,
+                      ranges, reference,
+                      transitions=(Transition("marked", "none", _range_strip(ranges)),),
+                      detector=_range_detector(ranges))
 
-    ``frm`` defaults to the convention's marked/default style for strips and
-    is required where the source style is not inferable.  Unsupported
-    transitions raise :class:`ValueError`; transitions that need a missing
-    optional dependency raise :class:`ImportError` with an install hint.
-    """
-    conv = _conv(convention_id)
-    if to not in conv.styles and to != "none":
-        raise ValueError(f"{convention_id!r} has styles {conv.styles}, not {to!r}")
-    if frm is None:
-        if conv.id == "jamo-form":
-            frm = _jamo_detect(text) or conv.default_style
-        else:
-            sources = sorted({f for (c, f, t) in _TRANSITIONS
-                              if c == convention_id and t == to})
-            if len(sources) == 1:
-                frm = sources[0]
-            elif conv.default_style != to:
-                frm = conv.default_style
-            else:
-                raise ValueError(
-                    f"{convention_id!r}: source style for ->{to!r} is ambiguous "
-                    f"({', '.join(sources)}); pass frm=")
-    if frm == to:
-        return text
-    fn = _TRANSITIONS.get((convention_id, frm, to))
-    if fn is None:
-        supported = sorted(f"{f}->{t}" for (c, f, t) in _TRANSITIONS
-                           if c == convention_id)
+
+CONVENTION_REGISTRY: Dict[str, Convention] = {c.id: c for c in (
+    _marks("tashkeel", "Arabic vocalization (harakat/tanwin/shadda/sukun)",
+           ("Arab",), _TASHKEEL_RANGES,
+           "Unicode 15 ch. 9.2 (Arabic); excludes letter-identity U+0653-0655"),
+    _marks("kashida", "Arabic justification elongation (tatweel)",
+           ("Arab",), _KASHIDA_RANGES, "Unicode U+0640 ARABIC TATWEEL",
+           default="none"),
+    _marks("quranic-marks", "Quranic annotation signs",
+           ("Arab",), _QURANIC_RANGES,
+           "Unicode U+06D6-06ED Quranic annotation signs", default="none"),
+    _marks("niqqud", "Hebrew vocalization points",
+           ("Hebr",), _NIQQUD_RANGES,
+           "Unicode 15 ch. 9.1 (Hebrew); strip loses the shin/sin dot distinction"),
+    _marks("teamim", "Hebrew cantillation marks",
+           ("Hebr",), _TEAMIM_RANGES,
+           "Unicode U+0591-05AF Hebrew accents (masoretic)", default="none"),
+    Convention("wakachigaki", "Japanese spaced writing (分かち書き)",
+               ("Hira", "Kana", "Hani"), "japanese", ("marked", "none"), "none",
+               (), "Spaced orthographic mode of Japanese (children's books, games)",
+               transitions=(
+                   Transition("marked", "none", _wakachigaki_strip),
+                   Transition("none", "marked", _wakachigaki_apply, requires="ja"),
+               )),
+    Convention("pinyin-tone", "Pinyin tone spelling",
+               ("Latn",), "pinyin", ("mark", "number", "none"), "mark",
+               (), "GB/T 16159 Basic rules of Hanyu Pinyin orthography",
+               transitions=(
+                   Transition("mark", "number", _pinyin_mark_to_number),
+                   Transition("number", "mark", _pinyin_number_to_mark),
+                   Transition("mark", "none", _pinyin_strip),
+                   Transition("number", "none", _pinyin_strip),
+               )),
+    Convention("jamo-form", "Hangul jamo repertoire (compatibility vs conjoining)",
+               ("Hang",), None, ("compatibility", "conjoining"), "compatibility",
+               (), "Unicode Hangul Compatibility Jamo U+3130 vs Hangul Jamo U+1100",
+               transitions=(
+                   Transition("conjoining", "compatibility",
+                              _jamo_conjoining_to_compat, lossless=True),
+                   Transition("compatibility", "conjoining",
+                              _jamo_compat_to_conjoining, lossless=True),
+               ),
+               detector=_jamo_detect),
+)}
+
+
+def conventions_for(script: str) -> List[Convention]:
+    """Conventions that decorate *script* (ISO-15924 code), registry order."""
+    return [c for c in CONVENTION_REGISTRY.values() if script in c.scripts]
+
+
+def _conv(convention_id: str) -> Convention:
+    try:
+        return CONVENTION_REGISTRY[convention_id]
+    except KeyError:
         raise ValueError(
-            f"{convention_id!r} does not define {frm!r}->{to!r}; "
-            f"supported: {', '.join(supported)}")
-    return fn(text)
+            f"unknown convention {convention_id!r}; known: "
+            f"{', '.join(sorted(CONVENTION_REGISTRY))}") from None
+
+
+# Module-level facades over the conventions' own behavior — the published API.
+
+def restyle(text: str, convention_id: str, to: str,
+            frm: Optional[str] = None) -> str:
+    """Rewrite *text* from one style of a convention to another."""
+    return _conv(convention_id).restyle(text, to, frm=frm)
 
 
 def strip(text: str, convention_id: str) -> str:
     """Remove a convention's decoration (restyle to ``"none"``)."""
-    conv = _conv(convention_id)
-    if "none" not in conv.styles:
-        raise ValueError(f"{convention_id!r} has no unmarked style; "
-                         f"styles: {conv.styles}")
-    frm = "mark" if conv.id == "pinyin-tone" else "marked"
-    if conv.id == "pinyin-tone":
-        # digits and marks are both handled by the strip transition
-        return _pinyin_strip(text)
-    return restyle(text, convention_id, "none", frm=frm)
+    return _conv(convention_id).strip(text)
 
 
 def apply(text: str, convention_id: str, style: Optional[str] = None) -> str:
     """Add a convention's decoration to unmarked text (restyle from ``"none"``)."""
-    conv = _conv(convention_id)
-    if style is None:
-        marked = [s for s in conv.styles if s != "none"]
-        style = conv.default_style if conv.default_style != "none" else marked[0]
-    return restyle(text, convention_id, style, frm="none")
+    return _conv(convention_id).apply(text, style)
 
 
 def detect(text: str, convention_id: str) -> Optional[str]:
-    """Current style of *text* under a convention, or None when not character-evident.
-
-    For binary decorations this means "any mark present" — a single shadda in
-    a paragraph reports ``"marked"``.
-    """
-    conv = _conv(convention_id)
-    if not conv.detectable:
-        return None
-    if conv.id == "jamo-form":
-        return _jamo_detect(text)
-    return "marked" if any(_in_ranges(ord(c), conv.ranges) for c in text) else "none"
+    """Current style of *text* under a convention, or None when not character-evident."""
+    return _conv(convention_id).detect(text)

scriptconv-0.0.3a8/scriptconv/graph.py

@@ -0,0 +1,259 @@
+"""Conversion graph — one routing engine for every text representation.
+
+Nodes are *representations*: phoneme notations ("ipa", "arpa") and
+orthographies ("hira", "hanzi", "cangjie") are peers in one flat id
+namespace, described by :class:`Representation` metadata.  Edges are
+registered transforms between two representations.  Routing finds the
+cheapest edge path, preferring lossless edges — silent lossy multi-hop is
+the classic failure mode of conversion graphs, so losing information costs
+extra by construction.
+
+The engine is generic and dependency-free.  :data:`DEFAULT_GRAPH` comes
+pre-registered with scriptconv's own edges: every notation pair (the IPA-hub
+routing that :func:`scriptconv.notation.convert` exposes) and the
+orthographic conversions from :mod:`translit`, :mod:`cangjie` and
+:mod:`readings` (the latter behind their optional extras — the edge exists,
+and raises :class:`ImportError` with an install hint when traversed without
+the dictionary installed).
+
+External packages extend graphs explicitly — ``pkg.register(graph)`` on a
+:meth:`ConversionGraph.copy` or the default graph; there is no entry-point
+autoloading, so a graph's contents never depend on what happens to be
+installed.  This is also the purity boundary: scriptconv's own edges are
+orthography only, but a client (e.g. a TTS stack) may register phonemization
+edges into *its* graph instance — the engine routes them without knowing.
+
+Two deliberate non-nodes: "graphemes" (a per-language contextual alias the
+caller must resolve — which script a language ordinarily writes in is not a
+property of text) and convention styles (:mod:`scriptconv.conventions` —
+decorations are parameters of a representation, never nodes, or the graph
+would double per style).
+"""
+from __future__ import annotations
+
+import heapq
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Optional, Tuple
+
+__all__ = ["Representation", "Edge", "ConversionGraph", "DEFAULT_GRAPH",
+           "REPRESENTATIONS"]
+
+_LOSSY_COST = 10.0
+
+
+@dataclass(frozen=True)
+class Representation:
+    """Metadata for one node of the conversion space."""
+    id: str
+    kind: str                      # "notation" | "orthography"
+    script: Optional[str] = None   # ISO-15924, when script-bound
+    system: Optional[str] = None   # sub-script system ("pinyin", "japanese")
+    reference: str = ""
+
+
+@dataclass(frozen=True)
+class Edge:
+    """One registered transform between two representations.
+
+    ``fn`` is called as ``fn(text, **context)``; context keys (``lang``,
+    engine-specific options…) pass through the router opaquely.  ``requires``
+    names an optional extra the transform needs — metadata only; the
+    transform itself raises :class:`ImportError` with an install hint.
+    ``cost`` defaults from ``lossless`` so routing prefers lossless paths.
+    """
+    src: str
+    dst: str
+    fn: Callable[..., str]
+    lossless: bool = False
+    requires: Optional[str] = None
+    cost: float = field(default=-1.0)
+
+    def __post_init__(self):
+        if self.cost < 0:
+            object.__setattr__(self, "cost",
+                               1.0 if self.lossless else _LOSSY_COST)
+
+
+class ConversionGraph:
+    """A registry of edges plus cheapest-path routing between representations."""
+
+    def __init__(self, edges: Optional[List[Edge]] = None):
+        self._edges: Dict[str, List[Edge]] = {}
+        for e in edges or []:
+            self.register(e)
+
+    def register(self, edge: Edge) -> None:
+        """Add an edge. A later edge for the same (src, dst) pair wins routing
+        only if cheaper; both remain queryable via :attr:`edges`."""
+        self._edges.setdefault(edge.src, []).append(edge)
+
+    @property
+    def edges(self) -> List[Edge]:
+        return [e for outs in self._edges.values() for e in outs]
+
+    @property
+    def nodes(self) -> List[str]:
+        seen = {e.src for e in self.edges} | {e.dst for e in self.edges}
+        return sorted(seen)
+
+    def copy(self) -> "ConversionGraph":
+        """Independent copy — registrations on it never affect this graph."""
+        return ConversionGraph(self.edges)
+
+    def extend(self, register_fn: Callable[["ConversionGraph"], None]) -> "ConversionGraph":
+        """Return a copy extended by *register_fn* (explicit, no autoloading)."""
+        g = self.copy()
+        register_fn(g)
+        return g
+
+    def route(self, src: str, dst: str) -> List[Edge]:
+        """Cheapest edge path from *src* to *dst* (empty when src == dst).
+
+        Raises :class:`ValueError` when unroutable, naming the reachable
+        targets so callers can self-diagnose.
+        """
+        if src == dst:
+            return []
+        best: Dict[str, float] = {src: 0.0}
+        back: Dict[str, Edge] = {}
+        queue: List[Tuple[float, str]] = [(0.0, src)]
+        while queue:
+            cost, node = heapq.heappop(queue)
+            if node == dst:
+                break
+            if cost > best.get(node, float("inf")):
+                continue
+            for e in self._edges.get(node, ()):
+                nxt = cost + e.cost
+                if nxt < best.get(e.dst, float("inf")):
+                    best[e.dst] = nxt
+                    back[e.dst] = e
+                    heapq.heappush(queue, (nxt, e.dst))
+        if dst not in back:
+            reachable = sorted(n for n in best if n != src)
+            raise ValueError(
+                f"no conversion path {src!r} -> {dst!r}; "
+                f"reachable from {src!r}: {', '.join(reachable) or '(nothing)'}")
+        path: List[Edge] = []
+        node = dst
+        while node != src:
+            edge = back[node]
+            path.append(edge)
+            node = edge.src
+        return list(reversed(path))
+
+    def can_convert(self, src: str, dst: str) -> bool:
+        if src == dst:
+            return True
+        try:
+            self.route(src, dst)
+            return True
+        except ValueError:
+            return False
+
+    def convert(self, text: str, src: str, dst: str, **context) -> str:
+        """Convert *text* along the cheapest path; context passes through."""
+        for edge in self.route(src, dst):
+            text = edge.fn(text, **context)
+        return text
+
+
+# ---------------------------------------------------------------------------
+# Representation registry and the default graph
+# ---------------------------------------------------------------------------
+
+REPRESENTATIONS: Dict[str, Representation] = {r.id: r for r in (
+    Representation("ipa", "notation", reference="International Phonetic Alphabet"),
+    Representation("arpa", "notation", reference="ARPABET"),
+    Representation("x-sampa", "notation", reference="X-SAMPA"),
+    Representation("lexique", "notation", reference="Lexique 383"),
+    Representation("kirshenbaum", "notation", reference="Kirshenbaum ASCII-IPA"),
+    Representation("cotovia", "notation", reference="Cotovía (Galician TTS)"),
+    Representation("rfe", "notation", reference="Revista de Filología Española"),
+    Representation("buckwalter", "notation", script="Latn",
+                   reference="Buckwalter Arabic transliteration"),
+    Representation("arabic", "orthography", script="Arab",
+                   reference="Arabic script"),
+    Representation("japanese", "orthography", script="Jpan", system="japanese",
+                   reference="ordinary mixed Japanese orthography (kanji+kana)"),
+    Representation("hira", "orthography", script="Hira", reference="Hiragana"),
+    Representation("kana", "orthography", script="Kana", reference="Katakana"),
+    Representation("hangul", "orthography", script="Hang",
+                   reference="Hangul syllable blocks"),
+    Representation("jamo", "orthography", script="Hang",
+                   reference="decomposed jamo (form is the jamo-form convention)"),
+    Representation("hanzi", "orthography", script="Hani",
+                   reference="Chinese characters"),
+    Representation("cangjie", "orthography", script="Hani",
+                   reference="Cangjie5 input codes (glyph shape)"),
+    Representation("pinyin", "orthography", script="Latn", system="pinyin",
+                   reference="Hanyu Pinyin romanization"),
+    Representation("bopomofo", "orthography", script="Bopo",
+                   reference="Zhuyin fuhao"),
+)}
+
+
+def _notation_edges() -> List[Edge]:
+    from scriptconv.notation import (_TO_IPA, _FROM_IPA, _DIRECT_PAIRS,
+                                     NOTATION_INFO)
+    edges = []
+    for notation, fn in _TO_IPA.items():
+        info = NOTATION_INFO[notation]
+        edges.append(Edge(notation.value, "ipa", (lambda f: lambda t, **_: f(t))(fn),
+                          lossless=info.lossless_to_ipa))
+    for notation, fn in _FROM_IPA.items():
+        info = NOTATION_INFO[notation]
+        edges.append(Edge("ipa", notation.value, (lambda f: lambda t, **_: f(t))(fn),
+                          lossless=info.lossless_from_ipa))
+    for (src, dst), fn in _DIRECT_PAIRS.items():
+        edges.append(Edge(src.value, dst.value, (lambda f: lambda t, **_: f(t))(fn),
+                          lossless=True))
+    return edges
+
+
+def _orthography_edges() -> List[Edge]:
+    def hira_to_kana(text, **_):
+        from scriptconv.translit import hira_to_kana as f
+        return f(text)
+
+    def kana_to_hira(text, **_):
+        from scriptconv.translit import kana_to_hira as f
+        return f(text)
+
+    def hangul_to_jamo(text, **_):
+        from scriptconv.translit import decompose_hangul
+        return decompose_hangul(text)
+
+    def japanese_to_hira(text, **_):
+        from scriptconv.readings import to_hiragana
+        return to_hiragana(text)
+
+    def japanese_to_kana(text, **_):
+        from scriptconv.readings import to_katakana
+        return to_katakana(text)
+
+    def hanzi_to_pinyin(text, **_):
+        from scriptconv.readings import to_pinyin
+        return to_pinyin(text)
+
+    def hanzi_to_bopomofo(text, **_):
+        from scriptconv.readings import to_bopomofo
+        return to_bopomofo(text)
+
+    def hanzi_to_cangjie(text, **_):
+        from scriptconv.cangjie import to_cangjie
+        return to_cangjie(text)
+
+    return [
+        Edge("hira", "kana", hira_to_kana, lossless=True),
+        Edge("kana", "hira", kana_to_hira, lossless=True),
+        Edge("hangul", "jamo", hangul_to_jamo, lossless=False),
+        Edge("japanese", "hira", japanese_to_hira, requires="ja"),
+        Edge("japanese", "kana", japanese_to_kana, requires="ja"),
+        Edge("hanzi", "pinyin", hanzi_to_pinyin, requires="zh"),
+        Edge("hanzi", "bopomofo", hanzi_to_bopomofo, requires="zh"),
+        Edge("hanzi", "cangjie", hanzi_to_cangjie),
+    ]
+
+
+DEFAULT_GRAPH = ConversionGraph(_notation_edges() + _orthography_edges())

{scriptconv-0.0.3a7 → scriptconv-0.0.3a8}/scriptconv/notation.py

@@ -951,19 +951,14 @@ def convert(text: str, src: str | Notation, dst: str | Notation) -> str:
     if src == dst:
         return text
 
-    # IPA-pivot notations: <notation> → IPA → <notation>.
-    if src in _TO_IPA and dst == Notation.IPA:
-        return _TO_IPA[src](text)
-    if src == Notation.IPA and dst in _FROM_IPA:
-        return _FROM_IPA[dst](text)
-    if src in _TO_IPA and dst in _FROM_IPA:
-        return _FROM_IPA[dst](_TO_IPA[src](text))
-
-    # Buckwalter ↔ Arabic script is a direct pair (not IPA-routable).
-    if (src, dst) in _DIRECT_PAIRS:
-        return _DIRECT_PAIRS[(src, dst)](text)
-
-    raise ValueError(f"Unsupported conversion: {src!r} → {dst!r}")
+    # Routing lives on the shared conversion graph; the notation tables below
+    # are registered there as edges (IPA-pivot pairs route through the "ipa"
+    # node, Buckwalter <-> Arabic is a direct edge).
+    from scriptconv.graph import DEFAULT_GRAPH
+    try:
+        return DEFAULT_GRAPH.convert(text, src.value, dst.value)
+    except ValueError:
+        raise ValueError(f"Unsupported conversion: {src!r} → {dst!r}") from None
 
 
 # ---------------------------------------------------------------------------
@@ -1000,20 +995,7 @@ _DIRECT_PAIRS: dict[tuple[Notation, Notation], "callable"] = {
 # can_convert — predicate for supported conversion paths
 # ---------------------------------------------------------------------------
 
-def _build_supported_pairs() -> set[tuple[Notation, Notation]]:
-    pairs: set[tuple[Notation, Notation]] = set(_DIRECT_PAIRS)
-    for _s in _TO_IPA:
-        pairs.add((_s, Notation.IPA))
-    for _d in _FROM_IPA:
-        pairs.add((Notation.IPA, _d))
-    for _s in _TO_IPA:
-        for _d in _FROM_IPA:
-            if _s != _d:
-                pairs.add((_s, _d))
-    return pairs
-
-
-_SUPPORTED_PAIRS: set[tuple[Notation, Notation]] = _build_supported_pairs()
+_NOTATION_VALUES = {n.value for n in Notation}
 
 
 def can_convert(src: str | Notation, dst: str | Notation) -> bool:
@@ -1037,7 +1019,16 @@ def can_convert(src: str | Notation, dst: str | Notation) -> bool:
     """
     src = Notation(src)
     dst = Notation(dst)
-    return (src, dst) in _SUPPORTED_PAIRS
+    if src == dst:
+        # historical contract: identity is not a "conversion"
+        return False
+    from scriptconv.graph import DEFAULT_GRAPH
+    if not DEFAULT_GRAPH.can_convert(src.value, dst.value):
+        return False
+    # only notation-to-notation reachability counts here; guard against paths
+    # that would leave the notation node set (none exist today, cheap to keep)
+    return all(e.src in _NOTATION_VALUES and e.dst in _NOTATION_VALUES
+               for e in DEFAULT_GRAPH.route(src.value, dst.value))
 
 
 # ---------------------------------------------------------------------------

{scriptconv-0.0.3a7 → scriptconv-0.0.3a8}/scriptconv/version.py

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

{scriptconv-0.0.3a7 → scriptconv-0.0.3a8}/scriptconv.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scriptconv
-Version: 0.0.3a7
+Version: 0.0.3a8
 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

{scriptconv-0.0.3a7 → scriptconv-0.0.3a8}/scriptconv.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ scriptconv/__init__.py
 scriptconv/__main__.py
 scriptconv/cangjie.py
 scriptconv/conventions.py
+scriptconv/graph.py
 scriptconv/notation.py
 scriptconv/py.typed
 scriptconv/readings.py
@@ -23,6 +24,7 @@ tests/test_cangjie.py
 tests/test_cli.py
 tests/test_conventions.py
 tests/test_examples.py
+tests/test_graph.py
 tests/test_notation.py
 tests/test_readings.py
 tests/test_readings_zh.py

{scriptconv-0.0.3a7 → scriptconv-0.0.3a8}/tests/test_cli.py

@@ -108,3 +108,20 @@ def test_strip_unknown_convention_clean_error():
     with pytest.raises(SystemExit) as exc:
         main(["strip", "bogus", "text"])
     assert str(exc.value).startswith("error:")
+
+
+def test_route_notation_pair(capsys):
+    assert main(["route", "arpa", "x-sampa"]) == 0
+    out = capsys.readouterr().out
+    assert "arpa -> ipa" in out and "ipa -> x-sampa" in out
+
+
+def test_convert_orthography_pair_via_graph(capsys):
+    assert main(["convert", "hira", "kana", "こんにちは"]) == 0
+    assert capsys.readouterr().out.strip() == "コンニチハ"
+
+
+def test_route_unroutable_clean_error():
+    with pytest.raises(SystemExit) as exc:
+        main(["route", "ipa", "hangul"])
+    assert str(exc.value).startswith("error:")

{scriptconv-0.0.3a7 → scriptconv-0.0.3a8}/tests/test_conventions.py

@@ -208,3 +208,31 @@ class TestRestyleContract(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class TestEncapsulation(unittest.TestCase):
+    """Operations are fully driven by a convention's own transitions/detector."""
+
+    def test_ad_hoc_convention_works_through_generic_operations(self):
+        from scriptconv.conventions import Convention, Transition
+        rot = Convention(
+            "x-demo", "demo", ("Latn",), None, ("upper", "none"), "none", (),
+            "test fixture",
+            transitions=(Transition("none", "upper", str.upper),
+                         Transition("upper", "none", str.lower)),
+            detector=lambda t: "upper" if t.isupper() else "none")
+        self.assertEqual(rot.apply("abc"), "ABC")
+        self.assertEqual(rot.strip("ABC"), "abc")
+        self.assertEqual(rot.detect("ABC"), "upper")
+        self.assertEqual(rot.restyle("ABC", "none"), "abc")
+
+    def test_wakachigaki_apply_requires_is_queryable(self):
+        conv = CONVENTION_REGISTRY["wakachigaki"]
+        self.assertEqual(conv.apply_requires, "ja")
+        self.assertIsNone(CONVENTION_REGISTRY["tashkeel"].apply_requires)
+
+    def test_jamo_form_strip_lossless_derived_from_transitions(self):
+        self.assertFalse(CONVENTION_REGISTRY["tashkeel"].strip_lossless)
+        self.assertFalse(CONVENTION_REGISTRY["jamo-form"].strip_lossless)  # no "none" transitions
+        self.assertTrue(all(t.lossless for t in
+                            CONVENTION_REGISTRY["jamo-form"].transitions))

scriptconv-0.0.3a8/tests/test_graph.py

@@ -0,0 +1,132 @@
+import sys
+import unittest
+from unittest import mock
+
+from scriptconv.graph import (
+    DEFAULT_GRAPH,
+    REPRESENTATIONS,
+    ConversionGraph,
+    Edge,
+    Representation,
+)
+from scriptconv.notation import Notation, can_convert, convert
+
+
+class TestEngine(unittest.TestCase):
+    def test_identity_is_empty_route(self):
+        g = ConversionGraph([Edge("a", "b", lambda t, **_: t + "b")])
+        self.assertEqual(g.route("a", "a"), [])
+        self.assertEqual(g.convert("x", "a", "a"), "x")
+
+    def test_multi_hop_route_and_convert(self):
+        g = ConversionGraph([
+            Edge("a", "b", lambda t, **_: t + ">b", lossless=True),
+            Edge("b", "c", lambda t, **_: t + ">c", lossless=True),
+        ])
+        self.assertEqual([e.dst for e in g.route("a", "c")], ["b", "c"])
+        self.assertEqual(g.convert("x", "a", "c"), "x>b>c")
+
+    def test_lossless_two_hop_beats_lossy_direct(self):
+        g = ConversionGraph([
+            Edge("a", "c", lambda t, **_: "LOSSY"),
+            Edge("a", "b", lambda t, **_: t + ">b", lossless=True),
+            Edge("b", "c", lambda t, **_: t + ">c", lossless=True),
+        ])
+        self.assertEqual(g.convert("x", "a", "c"), "x>b>c")
+
+    def test_unroutable_names_reachable_targets(self):
+        g = ConversionGraph([Edge("a", "b", lambda t, **_: t, lossless=True)])
+        with self.assertRaises(ValueError) as ctx:
+            g.route("a", "z")
+        self.assertIn("reachable from 'a': b", str(ctx.exception))
+
+    def test_context_passes_through_opaquely(self):
+        seen = {}
+
+        def edge_fn(text, **context):
+            seen.update(context)
+            return text
+
+        g = ConversionGraph([Edge("a", "b", edge_fn)])
+        g.convert("x", "a", "b", lang="pt-PT", phoneme_type="espeak")
+        self.assertEqual(seen, {"lang": "pt-PT", "phoneme_type": "espeak"})
+
+    def test_copy_and_extend_are_isolated(self):
+        g = ConversionGraph([Edge("a", "b", lambda t, **_: t)])
+        g2 = g.extend(lambda gg: gg.register(Edge("b", "c", lambda t, **_: t)))
+        self.assertTrue(g2.can_convert("a", "c"))
+        self.assertFalse(g.can_convert("a", "c"))
+
+    def test_cost_defaults_from_lossless(self):
+        self.assertEqual(Edge("a", "b", lambda t, **_: t, lossless=True).cost, 1.0)
+        self.assertGreater(Edge("a", "b", lambda t, **_: t).cost, 1.0)
+        self.assertEqual(Edge("a", "b", lambda t, **_: t, cost=3.5).cost, 3.5)
+
+
+class TestNotationParity(unittest.TestCase):
+    def test_every_supported_notation_pair_routes_and_matches(self):
+        samples = {"ipa": "həˈloʊ", "arpa": "HH AH0 L OW1"}
+        for src in Notation:
+            for dst in Notation:
+                if src == dst:
+                    continue
+                graph_ok = DEFAULT_GRAPH.can_convert(src.value, dst.value)
+                self.assertEqual(can_convert(src, dst), graph_ok,
+                                 f"{src}->{dst}")
+                if graph_ok and src.value in samples:
+                    self.assertEqual(
+                        convert(samples[src.value], src, dst),
+                        DEFAULT_GRAPH.convert(samples[src.value],
+                                              src.value, dst.value))
+
+    def test_buckwalter_not_ipa_routable(self):
+        self.assertFalse(DEFAULT_GRAPH.can_convert("buckwalter", "ipa"))
+        self.assertTrue(DEFAULT_GRAPH.can_convert("buckwalter", "arabic"))
+
+
+class TestDefaultGraphOrthography(unittest.TestCase):
+    def test_hira_kana_edges(self):
+        self.assertEqual(DEFAULT_GRAPH.convert("こんにちは", "hira", "kana"),
+                         "コンニチハ")
+        self.assertEqual(DEFAULT_GRAPH.convert("コーヒー", "kana", "hira"),
+                         "こーひー")
+
+    def test_hangul_to_jamo(self):
+        self.assertEqual(DEFAULT_GRAPH.convert("가", "hangul", "jamo"), "ㄱㅏ")
+
+    def test_hanzi_to_cangjie(self):
+        self.assertEqual(DEFAULT_GRAPH.convert("日", "hanzi", "cangjie"), "a")
+
+    def test_japanese_readings_edges(self):
+        self.assertEqual(DEFAULT_GRAPH.convert("東京", "japanese", "hira"),
+                         "とうきょう")
+        self.assertEqual(DEFAULT_GRAPH.convert("中国", "hanzi", "pinyin"),
+                         "zhōng guó")
+
+    def test_requires_metadata_and_import_hint(self):
+        ja_edges = [e for e in DEFAULT_GRAPH.edges
+                    if e.src == "japanese" and e.dst == "hira"]
+        self.assertEqual(ja_edges[0].requires, "ja")
+        import scriptconv.readings as readings
+        with mock.patch.object(readings, "_kakasi", None), \
+                mock.patch.dict(sys.modules, {"pykakasi": None}):
+            with self.assertRaises(ImportError) as ctx:
+                DEFAULT_GRAPH.convert("東京", "japanese", "hira")
+            self.assertIn("scriptconv[ja]", str(ctx.exception))
+
+    def test_representations_cover_all_default_nodes(self):
+        for node in DEFAULT_GRAPH.nodes:
+            self.assertIn(node, REPRESENTATIONS, node)
+
+    def test_no_graphemes_node(self):
+        self.assertNotIn("graphemes", REPRESENTATIONS)
+        self.assertNotIn("graphemes", DEFAULT_GRAPH.nodes)
+
+    def test_representation_kinds(self):
+        self.assertEqual(REPRESENTATIONS["ipa"].kind, "notation")
+        self.assertEqual(REPRESENTATIONS["pinyin"].system, "pinyin")
+        self.assertEqual(REPRESENTATIONS["cangjie"].script, "Hani")
+
+
+if __name__ == "__main__":
+    unittest.main()