pyyudit 0.1.0__py3-none-any.whl

pyyudit/__init__.py

@@ -0,0 +1,101 @@
+"""pyyudit — cross-platform Python binding to Yudit's Unicode shaping engine.
+
+``pyyudit`` wraps Yudit's standalone shaping engine for complex scripts
+(Indic, Arabic, Thai, Lao, Tibetan, Jamo) into a cross-platform Python wheel
+with per-step trace output.
+
+Typical usage::
+
+    import pyyudit
+
+    font_bytes = open("NotoSansDevanagari.ttf", "rb").read()
+    glyphs = pyyudit.shape(font_bytes, "नमस्ते")
+    for g in glyphs:
+        print(g.gid, g.cl, g.ax)
+
+    with pyyudit.YuditFont.from_path("NotoSansDevanagari.ttf") as f:
+        traced = f.shape_trace("नमस्ते")
+        for stage in traced.stages:
+            print(stage.m, len(stage.glyphs))
+
+Pure-Python helpers (:func:`upem_from_ttf`, :func:`has_table`) work even
+when no native library is installed.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._errors import FontError, LibraryNotFound, ShapingError, YuditError
+from ._font_meta import FontSource, has_table, read_font_bytes, upem_from_ttf
+from ._loader import configure, is_available, library_info, library_path
+from ._types import GlyphRecord, ShapedText, ShapedTrace, TraceStage
+from ._version import __version__, version_tuple
+
+if TYPE_CHECKING:
+    from ._font import YuditFont
+    from ._shaper import shape, shape_trace
+
+__all__ = [
+    "FontError",
+    "FontSource",
+    "GlyphRecord",
+    "LibraryNotFound",
+    "ShapedText",
+    "ShapedTrace",
+    "ShapingError",
+    "TraceStage",
+    "YuditError",
+    "YuditFont",
+    "__version__",
+    "configure",
+    "has_table",
+    "is_available",
+    "library_info",
+    "library_path",
+    "read_font_bytes",
+    "upem_from_ttf",
+    "version_tuple",
+]
+
+_LIB_HINT = (
+    "yudit_shaper native library not available. Build it with CMake "
+    "(see README.md) and place the shared library in pyyudit/_lib/ "
+    "or set PYYUDIT_LIBRARY_PATH."
+)
+
+
+if is_available():
+    from ._font import YuditFont
+    from ._shaper import shape, shape_trace
+
+    __all__.extend(["shape", "shape_trace"])
+else:  # pragma: no cover
+
+    class _UnavailableFont:
+        """Placeholder when the native library is unavailable."""
+
+        def __init__(self, *a: object, **kw: object) -> None:
+            raise LibraryNotFound(_LIB_HINT)
+
+        def __enter__(self) -> _UnavailableFont:
+            return self
+
+        def __exit__(self, *exc: object) -> None:
+            return None
+
+        @classmethod
+        def from_bytes(cls, data: bytes | bytearray = b"") -> _UnavailableFont:
+            return cls(data)
+
+        @classmethod
+        def from_path(cls, path: object = ".") -> _UnavailableFont:
+            return cls(path)
+
+    YuditFont = _UnavailableFont  # type: ignore[misc, assignment]
+
+    def shape(font: FontSource, text: str, **kwargs: object) -> list[GlyphRecord]:  # type: ignore[no-redef]
+        raise LibraryNotFound(_LIB_HINT)
+
+    def shape_trace(font: FontSource, text: str, **kwargs: object) -> ShapedTrace:  # type: ignore[no-redef]
+        raise LibraryNotFound(_LIB_HINT)

pyyudit/_binding.py

@@ -0,0 +1,90 @@
+"""Low-level ctypes binding to the yudit_shaper native library."""
+
+from __future__ import annotations
+
+import ctypes
+from ctypes import (
+    POINTER,
+    Structure,
+    c_char_p,
+    c_int,
+    c_int32,
+    c_size_t,
+    c_uint8,
+    c_uint32,
+    c_void_p,
+)
+from typing import Any, Callable
+
+from ._loader import load
+
+_loaded = load()
+if _loaded is None:
+    raise ImportError("yudit_shaper native library not found. See pyyudit._loader")
+
+_lib: ctypes.CDLL = _loaded
+
+
+def _fn(name: str, res: Any, *params: Any, **kwds: Any) -> None:
+    """Declare the restype/argtypes for a native function."""
+    f = getattr(_lib, name)
+    f.restype = res
+    f.argtypes = params
+    errcheck = kwds.get("errcheck")
+    if errcheck:
+        f.errcheck = errcheck
+
+
+def _check(err: int, func: Callable[..., Any], _args: tuple[Any, ...]) -> int:
+    """Raise on negative error codes."""
+    if err < 0:
+        raise RuntimeError(f"{func.__name__} failed: error code {err}")
+    return err
+
+
+# ── Structures ─────────────────────────────────────────────────────────────
+
+
+class _Glyph(Structure):
+    _fields_ = [
+        ("glyph_id", c_uint32),
+        ("codepoint", c_uint32),
+        ("x", c_int32),
+        ("y", c_int32),
+        ("width", c_int32),
+        ("cluster", c_int32),
+    ]
+
+
+class _TraceStage(Structure):
+    _fields_ = [
+        ("message", c_char_p),
+        ("glyphs", POINTER(_Glyph)),
+        ("glyph_count", c_uint32),
+        ("depth", c_int),
+        ("effective", c_int),
+    ]
+
+
+# ── Function declarations ─────────────────────────────────────────────────
+
+_fn("yudit_version", c_char_p)
+_fn("yudit_error_string", c_char_p, c_int)
+
+# Font
+_fn("yudit_font_open", c_int, POINTER(c_uint8), c_size_t, c_int, POINTER(c_void_p), errcheck=_check)
+_fn("yudit_font_close", None, c_void_p)
+_fn("yudit_font_upem", c_int, c_void_p)
+_fn("yudit_font_glyph_count", c_int, c_void_p)
+_fn("yudit_font_name", c_char_p, c_void_p)
+
+# Shaping
+_fn("yudit_shape", c_int, c_void_p, POINTER(c_uint32), c_uint32, POINTER(c_void_p), errcheck=_check)
+_fn("yudit_result_free", None, c_void_p)
+
+# Result queries
+_fn("yudit_result_glyph_count", c_uint32, c_void_p)
+_fn("yudit_result_glyphs", POINTER(_Glyph), c_void_p)
+_fn("yudit_result_width", c_int, c_void_p)
+_fn("yudit_result_trace_count", c_uint32, c_void_p)
+_fn("yudit_result_trace_stage", POINTER(_TraceStage), c_void_p, c_uint32)

pyyudit/_errors.py

@@ -0,0 +1,19 @@
+"""Exception hierarchy for pyyudit."""
+
+from __future__ import annotations
+
+
+class YuditError(Exception):
+    """Base exception for all pyyudit errors."""
+
+
+class LibraryNotFound(YuditError):
+    """The native yudit_shaper library could not be found or loaded."""
+
+
+class FontError(YuditError):
+    """The font data is invalid or unsupported."""
+
+
+class ShapingError(YuditError):
+    """Shaping failed (unsupported script, empty text, etc.)."""

pyyudit/_font.py

@@ -0,0 +1,185 @@
+"""YuditFont — a loaded font ready for shaping."""
+
+from __future__ import annotations
+
+import ctypes
+from pathlib import Path
+from typing import Any
+
+from ._binding import _lib
+from ._errors import FontError, LibraryNotFound
+from ._font_meta import read_font_bytes
+from ._types import GlyphRecord, ShapedText, ShapedTrace, TraceStage
+
+__all__ = ["YuditFont"]
+
+
+class YuditFont:
+    """A TrueType/OpenType font loaded by Yudit's shaping engine.
+
+    Usage::
+
+        font = YuditFont.from_path("NotoSansDevanagari.ttf")
+        result = font.shape_trace("नमस्ते")
+        for stage in result.stages:
+            print(stage.m, len(stage.glyphs))
+    """
+
+    def __init__(self, data: bytes, *, face_index: int = 0) -> None:
+        if not _lib:
+            raise LibraryNotFound("yudit_shaper native library not available.")
+
+        self._handle = ctypes.c_void_p()
+        buf = (ctypes.c_uint8 * len(data))(*data)
+        try:
+            _lib.yudit_font_open(buf, len(data), face_index, ctypes.byref(self._handle))
+        except RuntimeError as exc:
+            raise FontError(str(exc)) from exc
+
+        if not self._handle:
+            raise FontError("yudit_font_open returned NULL")
+
+        self._data = data  # prevent GC of the buffer
+
+    @classmethod
+    def from_path(cls, path: str | Path) -> YuditFont:
+        """Load a font from a file path."""
+        return cls(read_font_bytes(path))
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> YuditFont:
+        """Load a font from raw bytes."""
+        return cls(data)
+
+    def close(self) -> None:
+        """Release the native font handle."""
+        if self._handle:
+            _lib.yudit_font_close(self._handle)
+            self._handle = ctypes.c_void_p()
+
+    def __enter__(self) -> YuditFont:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    @property
+    def upem(self) -> int:
+        """Units per em."""
+        return _lib.yudit_font_upem(self._handle)
+
+    @property
+    def glyph_count(self) -> int:
+        """Number of glyphs in the font."""
+        return _lib.yudit_font_glyph_count(self._handle)
+
+    @property
+    def name(self) -> str:
+        """Font name."""
+        n = _lib.yudit_font_name(self._handle)
+        return n.decode("utf-8", errors="replace") if n else ""
+
+    # ── Shaping ────────────────────────────────────────────────────────────
+
+    def shape(self, text: str) -> ShapedText:
+        """Shape text and return positioned glyphs (no trace)."""
+        result = self.shape_trace(text)
+        return ShapedText(
+            glyphs=result.final_glyphs,
+            advance_x=result.advance_x,
+            advance_y=result.advance_y,
+            text=text,
+            engine="yudit",
+        )
+
+    def shape_trace(self, text: str) -> ShapedTrace:
+        """Shape text and return positioned glyphs with per-step trace."""
+        if not text:
+            from ._types import ShapedTrace
+
+            return ShapedTrace(
+                stages=(),
+                final_glyphs=(),
+                advance_x=0,
+                advance_y=0,
+                text=text,
+                engine="yudit",
+            )
+
+        # Encode text as UTF-32
+        encoded = text.encode("utf-32-le")
+        n_codepoints = len(encoded) // 4
+        # Convert bytes to c_uint32 array via cast
+        import array
+
+        arr = array.array("I", encoded)
+        buf = (ctypes.c_uint32 * n_codepoints)(*arr)
+
+        result_handle = ctypes.c_void_p()
+        try:
+            _lib.yudit_shape(self._handle, buf, n_codepoints, ctypes.byref(result_handle))
+        except RuntimeError as exc:
+            from ._errors import ShapingError
+
+            raise ShapingError(str(exc)) from exc
+
+        try:
+            return self._extract_result(result_handle, text)
+        finally:
+            _lib.yudit_result_free(result_handle)
+
+    def _extract_result(self, handle: ctypes.c_void_p, text: str) -> ShapedTrace:
+        """Extract glyphs and trace from a native result handle."""
+        # Final glyphs
+        glyph_count = _lib.yudit_result_glyph_count(handle)
+        glyphs_ptr = _lib.yudit_result_glyphs(handle)
+        final_glyphs = self._parse_glyphs(glyphs_ptr, glyph_count)
+
+        # Trace stages
+        trace_count = _lib.yudit_result_trace_count(handle)
+        stages: list[TraceStage] = []
+        for i in range(trace_count):
+            stage_ptr = _lib.yudit_result_trace_stage(handle, i)
+            if not stage_ptr:
+                continue
+            stage = stage_ptr.contents
+            msg = stage.message.decode("utf-8", errors="replace") if stage.message else ""
+            stage_glyphs = self._parse_glyphs(stage.glyphs, stage.glyph_count)
+            stages.append(
+                TraceStage(
+                    m=msg,
+                    glyphs=tuple(stage_glyphs),
+                    depth=stage.depth,
+                    effective=bool(stage.effective),
+                )
+            )
+
+        advance_x = _lib.yudit_result_width(handle)
+
+        return ShapedTrace(
+            stages=tuple(stages),
+            final_glyphs=tuple(final_glyphs),
+            advance_x=advance_x,
+            advance_y=0,
+            text=text,
+            engine="yudit",
+        )
+
+    @staticmethod
+    def _parse_glyphs(ptr: Any, count: int) -> list[GlyphRecord]:
+        """Parse a native glyph array into Python GlyphRecords."""
+        glyphs: list[GlyphRecord] = []
+        for i in range(count):
+            g = ptr[i]
+            glyphs.append(
+                GlyphRecord(
+                    g=g.glyph_id,
+                    cl=g.cluster,
+                    dx=g.x,
+                    dy=g.y,
+                    ax=g.width,
+                    ay=0,
+                    flags=0,
+                )
+            )
+        return glyphs

pyyudit/_font_meta.py

@@ -0,0 +1,80 @@
+"""Pure-Python font metadata helpers (no native library required)."""
+
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+from typing import Union
+
+__all__ = ["FontSource", "has_table", "read_font_bytes", "upem_from_ttf"]
+
+
+FontSource = Union[bytes, bytearray, str, Path]
+
+
+def read_font_bytes(source: FontSource) -> bytes:
+    """Read font data from bytes or a file path."""
+    if isinstance(source, (bytes, bytearray)):
+        return bytes(source)
+    path = Path(source)
+    if not path.is_file():
+        raise FileNotFoundError(f"Font file not found: {path}")
+    return path.read_bytes()
+
+
+def _read_u16(data: bytes, offset: int) -> int:
+    return struct.unpack_from(">H", data, offset)[0]
+
+
+def _read_u32(data: bytes, offset: int) -> int:
+    return struct.unpack_from(">I", data, offset)[0]
+
+
+def upem_from_ttf(font_bytes: bytes) -> int:
+    """Read units-per-em from the head table of a TrueType/OpenType font."""
+    try:
+        num_tables = _read_u16(font_bytes, 4)
+        for i in range(num_tables):
+            offset = 12 + i * 16
+            tag = font_bytes[offset : offset + 4]
+            table_offset = _read_u32(font_bytes, offset + 8)
+            if tag == b"head" and table_offset + 18 + 2 <= len(font_bytes):
+                return _read_u16(font_bytes, table_offset + 18)
+    except (struct.error, IndexError):
+        pass
+    return 1000  # default
+
+
+def has_table(font_bytes: bytes, tag: str) -> bool:
+    """Check if a font contains a specific OpenType table."""
+    tag_bytes = tag.encode("ascii")[:4]
+    try:
+        num_tables = _read_u16(font_bytes, 4)
+        for i in range(num_tables):
+            offset = 12 + i * 16
+            t = font_bytes[offset : offset + 4]
+            if t == tag_bytes:
+                return True
+    except (struct.error, IndexError):
+        pass
+    return False
+
+
+def is_graphite_font(font_bytes: bytes) -> bool:
+    """Check if a font has Graphite tables (silf/sill/glat/gloc)."""
+    return any(has_table(font_bytes, t) for t in ("silf", "sill"))
+
+
+def glyph_count_from_ttf(font_bytes: bytes) -> int:
+    """Read the number of glyphs from the maxp table."""
+    try:
+        num_tables = _read_u16(font_bytes, 4)
+        for i in range(num_tables):
+            offset = 12 + i * 16
+            tag = font_bytes[offset : offset + 4]
+            table_offset = _read_u32(font_bytes, offset + 8)
+            if tag == b"maxp" and table_offset + 6 <= len(font_bytes):
+                return _read_u16(font_bytes, table_offset + 4)
+    except (struct.error, IndexError):
+        pass
+    return 0

pyyudit/_loader.py

@@ -0,0 +1,141 @@
+"""Cross-platform discovery and loading of the yudit_shaper native library.
+
+Search order (first hit wins):
+
+1. An explicit path passed to :func:`configure`.
+2. The ``PYYUDIT_LIBRARY_PATH`` environment variable.
+3. A library bundled inside the wheel at ``pyyudit/_lib/``.
+4. A system-installed library (``libyudit_shaper.so`` / ``yudit_shaper.dll``).
+"""
+
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+import os
+import sys
+from collections.abc import Iterator
+from pathlib import Path
+
+__all__ = [
+    "configure",
+    "is_available",
+    "library_info",
+    "library_path",
+    "load",
+]
+
+if os.name == "nt":
+    _PLATFORM_NAMES: tuple[str, ...] = ("yudit_shaper.dll",)
+elif sys.platform == "darwin":
+    _PLATFORM_NAMES = ("libyudit_shaper.dylib",)
+else:
+    _PLATFORM_NAMES = ("libyudit_shaper.so", "libyudit_shaper.so.0")
+
+_PACKAGE_DIR = Path(__file__).resolve().parent
+_LIB_DIR = _PACKAGE_DIR / "_lib"
+
+# Explicit override set via configure(); None means "auto-discover".
+_configured_path: Path | None = None
+_resolved_path: Path | None = None
+_cached_library: ctypes.CDLL | None = None
+
+
+def _platform_candidates(directory: Path) -> Iterator[Path]:
+    for name in _PLATFORM_NAMES:
+        yield directory / name
+
+
+def _candidate_paths() -> Iterator[Path]:
+    seen: set[Path] = set()
+
+    def _offer(path: Path) -> Iterator[Path]:
+        if path not in seen:
+            seen.add(path)
+            yield path
+
+    # 1. explicit runtime configuration
+    if _configured_path is not None:
+        if _configured_path.is_dir():
+            for p in _platform_candidates(_configured_path):
+                yield from _offer(p)
+        else:
+            yield from _offer(_configured_path)
+
+    # 2. environment variable
+    env = os.environ.get("PYYUDIT_LIBRARY_PATH")
+    if env:
+        env_path = Path(env)
+        if env_path.is_dir():
+            for p in _platform_candidates(env_path):
+                yield from _offer(p)
+        else:
+            yield from _offer(env_path)
+
+    # 3. wheel-local _lib/ directory
+    if _LIB_DIR.is_dir():
+        for p in _platform_candidates(_LIB_DIR):
+            yield from _offer(p)
+
+    # 4. system library
+    for name in _PLATFORM_NAMES:
+        found = ctypes.util.find_library(name.rsplit(".", 1)[0])
+        if found:
+            yield from _offer(Path(found))
+
+
+def resolve() -> Path | None:
+    global _resolved_path
+    if _resolved_path is not None:
+        return _resolved_path
+    for path in _candidate_paths():
+        if path.is_file():
+            _resolved_path = path
+            return path
+    return None
+
+
+def load() -> ctypes.CDLL | None:
+    global _cached_library
+    if _cached_library is not None:
+        return _cached_library
+    path = resolve()
+    if path is None:
+        return None
+    try:
+        if os.name == "nt" and path.is_file():
+            os.add_dll_directory(str(path.parent))
+        _cached_library = ctypes.CDLL(str(path))
+        return _cached_library
+    except OSError:
+        return None
+
+
+def configure(path: str | Path | None = None) -> None:
+    global _configured_path, _resolved_path, _cached_library
+    _configured_path = Path(path) if path else None
+    _resolved_path = None
+    _cached_library = None
+
+
+def is_available() -> bool:
+    return load() is not None
+
+
+def library_path() -> Path | None:
+    return resolve()
+
+
+def library_info() -> dict[str, object]:
+    path = resolve()
+    lib = load()
+    return {
+        "available": lib is not None,
+        "path": str(path) if path else None,
+        "search_order": [
+            "configure()",
+            "PYYUDIT_LIBRARY_PATH",
+            "pyyudit/_lib/",
+            "system library",
+        ],
+    }

pyyudit/_shaper.py

@@ -0,0 +1,51 @@
+"""One-shot shaping functions (the main user-facing API)."""
+
+from __future__ import annotations
+
+from ._font_meta import FontSource, read_font_bytes
+from ._types import GlyphRecord, ShapedTrace
+
+__all__ = ["shape", "shape_trace"]
+
+_LIB_HINT = (
+    "yudit_shaper native library not available. Build it with CMake "
+    "(see README.md) and place the shared library in pyyudit/_lib/ "
+    "or set PYYUDIT_LIBRARY_PATH."
+)
+
+
+def shape(
+    font: FontSource,
+    text: str,
+    **kwargs: object,
+) -> list[GlyphRecord]:
+    """Shape text with a font and return positioned glyphs.
+
+    This is a convenience wrapper around :class:`YuditFont`.
+
+    :param font: font bytes or file path.
+    :param text: Unicode text to shape.
+    :returns: list of :class:`GlyphRecord` with positioning.
+    """
+    from ._font import YuditFont
+
+    with YuditFont.from_bytes(read_font_bytes(font)) as f:
+        result = f.shape(text)
+        return list(result.glyphs)
+
+
+def shape_trace(
+    font: FontSource,
+    text: str,
+    **kwargs: object,
+) -> ShapedTrace:
+    """Shape text with a font and return the full trace.
+
+    :param font: font bytes or file path.
+    :param text: Unicode text to shape.
+    :returns: :class:`ShapedTrace` with per-step stages.
+    """
+    from ._font import YuditFont
+
+    with YuditFont.from_bytes(read_font_bytes(font)) as f:
+        return f.shape_trace(text)