universal-render 0.1.0__py3-none-any.whl

universal_render/__init__.py

@@ -0,0 +1,277 @@
+# universal_render/__init__.py
+
+"""
+universal_render: universal complex-script text rendering for Matplotlib.
+
+Text is shaped through Qt's text stack (HarfBuzz), so scripts that
+Matplotlib's own text engine cannot shape — Bengali, Hindi, Tamil,
+Arabic, Thai, and other complex scripts — render correctly in titles,
+axis labels, tick labels, annotations, legends, and heatmap cells.
+Fonts are chosen automatically from each string's dominant Unicode
+script, with per-script fallback tables and glyph-coverage validation.
+
+Typical usage:
+
+    import universal_render as ur
+    import matplotlib.pyplot as plt
+
+    ur.init_renderer()
+
+    fig, ax = plt.subplots()
+    ax.plot([1, 2, 3], [3, 1, 4])
+
+    ur.set_multilingual_title(ax, "বাংলা শিরোনাম")     # Bengali
+    ur.set_multilingual_xlabel(ax, "أشهر السنة")        # Arabic (RTL)
+    ur.set_multilingual_ylabel(ax, "மாத விற்பனை")       # Tamil
+
+    ur.set_multilingual_xticks(ax, [1, 2, 3], ["एक", "दो", "तीन"])  # Hindi
+    ur.text(ax, 0.5, 0.5, "ข้อความ Mixed 2026", coord="axes")       # Thai + Latin
+
+    ur.apply_multilingual_layout(fig, auto=True)
+"""
+
+__version__ = "0.1.0"
+
+# ---------------------------------------------------------------------
+# Backend / environment
+# ---------------------------------------------------------------------
+
+from .backend import (
+    init_renderer,
+    ensure_qt_application,
+    get_renderer_status,
+    check_environment,
+    is_headless_environment,
+    is_notebook_environment,
+    is_colab_environment,
+    is_kaggle_environment,
+    reset_renderer_state,
+)
+
+# ---------------------------------------------------------------------
+# Script detection
+# ---------------------------------------------------------------------
+
+from .scripts import (
+    KNOWN_SCRIPTS,
+    RTL_SCRIPTS,
+    TextRun,
+    detect_char_script,
+    detect_script,
+    detect_scripts,
+    describe_text,
+    is_mixed_script,
+    is_rtl_text,
+    script_direction,
+    scripts_with_native_digits,
+    segment_runs,
+    to_native_numerals,
+)
+
+# Roadmap-compatible alias
+script_detection_auto = detect_script
+
+# ---------------------------------------------------------------------
+# Font management
+# ---------------------------------------------------------------------
+
+from .fonts import (
+    SCRIPT_FONT_CANDIDATES,
+    auto_font_fallback,
+    coverage_report,
+    family_exists,
+    find_font_for_script,
+    font_covers_text,
+    font_info,
+    get_default_font,
+    get_script_font,
+    list_available_fonts,
+    list_registered_fonts,
+    register_font,
+    register_fonts,
+    resolve_font,
+    resolve_fonts_for_runs,
+    set_default_font,
+    set_script_font,
+    validate_font,
+)
+
+# ---------------------------------------------------------------------
+# Rendering
+# ---------------------------------------------------------------------
+
+from .renderer import (
+    render_text,
+    render_text_array,
+    render_mixed_text,
+    render_paragraph,
+    render_text_qimage,
+    render_paragraph_qimage,
+    measure_text,
+    clear_render_cache,
+    get_render_cache_info,
+    set_render_cache_maxsize,
+    set_render_defaults,
+    get_render_defaults,
+)
+
+# ---------------------------------------------------------------------
+# Layout
+# ---------------------------------------------------------------------
+
+from .layout import (
+    get_layout_manager,
+    clear_layout_manager,
+)
+
+# ---------------------------------------------------------------------
+# Matplotlib-facing APIs
+# ---------------------------------------------------------------------
+
+from .mpl_support import (
+    set_multilingual_legend,
+    set_multilingual_numeric_ticks,
+    set_multilingual_title,
+    set_multilingual_xlabel,
+    set_multilingual_ylabel,
+    set_multilingual_suptitle,
+    set_multilingual_xticks,
+    set_multilingual_yticks,
+    add_multilingual_cell_text,
+    multilingual_text,
+    annotate_multilingual,
+    multilingual_paragraph,
+    apply_multilingual_layout,
+)
+
+# ---------------------------------------------------------------------
+# High-level API
+# ---------------------------------------------------------------------
+
+from .highlevel import (
+    LANGUAGE_TO_SCRIPT,
+    font_for_language,
+    language_to_script,
+    localize_axes,
+    localized_numerals,
+    multilingual_bar_labels,
+    multilingual_heatmap,
+    set_language_font,
+    supported_languages,
+)
+
+# ---------------------------------------------------------------------
+# Diagnostics / evaluation
+# ---------------------------------------------------------------------
+
+from .diagnostics import (
+    SCRIPT_TEST_SAMPLES,
+    benchmark_render,
+    save_comparison_figure,
+    self_test,
+)
+
+
+def text(ax, *args, **kwargs):
+    """
+    Short alias for multilingual_text(), so you can write:
+
+        import universal_render as ur
+        ur.text(ax, 0.5, 0.5, "বাংলা / العربية / ไทย", coord="axes")
+    """
+    return multilingual_text(ax, *args, **kwargs)
+
+
+__all__ = [
+    "__version__",
+    # backend
+    "init_renderer",
+    "ensure_qt_application",
+    "get_renderer_status",
+    "check_environment",
+    "is_headless_environment",
+    "is_notebook_environment",
+    "is_colab_environment",
+    "is_kaggle_environment",
+    "reset_renderer_state",
+    # scripts
+    "KNOWN_SCRIPTS",
+    "RTL_SCRIPTS",
+    "TextRun",
+    "detect_char_script",
+    "detect_script",
+    "detect_scripts",
+    "describe_text",
+    "is_mixed_script",
+    "is_rtl_text",
+    "script_direction",
+    "script_detection_auto",
+    "scripts_with_native_digits",
+    "segment_runs",
+    "to_native_numerals",
+    # fonts
+    "SCRIPT_FONT_CANDIDATES",
+    "auto_font_fallback",
+    "coverage_report",
+    "family_exists",
+    "find_font_for_script",
+    "font_covers_text",
+    "font_info",
+    "get_default_font",
+    "get_script_font",
+    "list_available_fonts",
+    "list_registered_fonts",
+    "register_font",
+    "register_fonts",
+    "resolve_font",
+    "resolve_fonts_for_runs",
+    "set_default_font",
+    "set_script_font",
+    "validate_font",
+    # renderer
+    "render_text",
+    "render_text_array",
+    "render_mixed_text",
+    "render_paragraph",
+    "render_text_qimage",
+    "render_paragraph_qimage",
+    "measure_text",
+    "clear_render_cache",
+    "get_render_cache_info",
+    "set_render_cache_maxsize",
+    "set_render_defaults",
+    "get_render_defaults",
+    # layout
+    "get_layout_manager",
+    "clear_layout_manager",
+    # mpl support
+    "set_multilingual_legend",
+    "set_multilingual_numeric_ticks",
+    "set_multilingual_title",
+    "set_multilingual_xlabel",
+    "set_multilingual_ylabel",
+    "set_multilingual_suptitle",
+    "set_multilingual_xticks",
+    "set_multilingual_yticks",
+    "add_multilingual_cell_text",
+    "multilingual_text",
+    "annotate_multilingual",
+    "multilingual_paragraph",
+    "apply_multilingual_layout",
+    "text",
+    # high-level
+    "LANGUAGE_TO_SCRIPT",
+    "font_for_language",
+    "language_to_script",
+    "localize_axes",
+    "localized_numerals",
+    "multilingual_bar_labels",
+    "multilingual_heatmap",
+    "set_language_font",
+    "supported_languages",
+    # diagnostics
+    "SCRIPT_TEST_SAMPLES",
+    "benchmark_render",
+    "save_comparison_figure",
+    "self_test",
+]

universal_render/backend.py

@@ -0,0 +1,375 @@
+# universal_render/backend.py
+from __future__ import annotations
+
+import os
+import sys
+import platform
+from dataclasses import dataclass, asdict, field
+from typing import Any, Dict, List, Optional
+
+try:
+    from PySide6.QtGui import QGuiApplication
+    from PySide6.QtWidgets import QApplication
+    QT_AVAILABLE = True
+    QT_IMPORT_ERROR = None
+except Exception as e:  # pragma: no cover
+    QGuiApplication = None
+    QApplication = None
+    QT_AVAILABLE = False
+    QT_IMPORT_ERROR = e
+
+
+# ---------------------------------------------------------------------
+# Internal state
+# ---------------------------------------------------------------------
+
+_APP = None
+_INITIALIZED = False
+
+
+@dataclass
+class RendererStatus:
+    qt_available: bool = QT_AVAILABLE
+    qt_import_error: Optional[str] = None
+    initialized: bool = False
+    app_created: bool = False
+    app_class: Optional[str] = None
+    platform_name: str = field(default_factory=lambda: platform.system())
+    python_version: str = field(default_factory=lambda: platform.python_version())
+    headless: bool = False
+    offscreen_requested: bool = False
+    offscreen_enabled: bool = False
+    qt_qpa_platform: Optional[str] = None
+    warnings: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+_STATUS = RendererStatus(
+    qt_import_error=str(QT_IMPORT_ERROR) if QT_IMPORT_ERROR else None
+)
+
+
+# ---------------------------------------------------------------------
+# Environment helpers
+# ---------------------------------------------------------------------
+
+def is_notebook_environment() -> bool:
+    """
+    Best-effort detection for Jupyter/Colab/Kaggle-like notebook environments.
+    """
+    try:
+        from IPython import get_ipython  # type: ignore
+        shell = get_ipython()
+        if shell is None:
+            return False
+        return True
+    except Exception:
+        return False
+
+
+def is_colab_environment() -> bool:
+    return "google.colab" in sys.modules
+
+
+def is_kaggle_environment() -> bool:
+    return (
+        "KAGGLE_KERNEL_RUN_TYPE" in os.environ
+        or "KAGGLE_URL_BASE" in os.environ
+        or "/kaggle/" in os.getcwd().replace("\\", "/")
+    )
+
+
+def is_headless_environment() -> bool:
+    """
+    Heuristic headless detection.
+
+    On Linux, the absence of DISPLAY/WAYLAND_DISPLAY usually means headless.
+    On Colab/Kaggle, assume headless.
+    On Windows/macOS, default to False unless explicitly offscreen.
+    """
+    if is_colab_environment() or is_kaggle_environment():
+        return True
+
+    system_name = platform.system().lower()
+
+    if system_name == "linux":
+        display = os.environ.get("DISPLAY")
+        wayland = os.environ.get("WAYLAND_DISPLAY")
+        return not (display or wayland)
+
+    return False
+
+
+def _normalize_bool(value: Optional[bool], default: bool) -> bool:
+    if value is None:
+        return default
+    return bool(value)
+
+
+def _ensure_offscreen_env(force: bool = False) -> bool:
+    """
+    Enable Qt offscreen mode by setting QT_QPA_PLATFORM=offscreen.
+
+    Returns True if the environment variable is set to 'offscreen' after this call.
+    """
+    current = os.environ.get("QT_QPA_PLATFORM")
+
+    if current:
+        # Respect explicit user setting unless force=True
+        if force:
+            os.environ["QT_QPA_PLATFORM"] = "offscreen"
+            return True
+        return current.lower() == "offscreen"
+
+    os.environ["QT_QPA_PLATFORM"] = "offscreen"
+    return True
+
+
+def _existing_app():
+    """
+    Return an existing Qt application instance if one exists.
+    """
+    if not QT_AVAILABLE:
+        return None
+
+    try:
+        app = QApplication.instance()
+        if app is not None:
+            return app
+    except Exception:
+        pass
+
+    try:
+        app = QGuiApplication.instance()
+        if app is not None:
+            return app
+    except Exception:
+        pass
+
+    return None
+
+
+# ---------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------
+
+def init_renderer(
+    headless: Optional[bool] = None,
+    offscreen: bool = True,
+    force: bool = False,
+) -> Any:
+    """
+    Initialize a Qt application safely for multilingual text rendering.
+
+    Parameters
+    ----------
+    headless:
+        Whether to treat the current environment as headless.
+        If None, a best-effort detection is used.
+    offscreen:
+        Whether to request Qt offscreen mode in headless environments.
+    force:
+        If True, re-run initialization logic even if already initialized.
+
+    Returns
+    -------
+    app:
+        The active QApplication/QGuiApplication instance.
+
+    Notes
+    -----
+    - In Colab/Kaggle/headless Linux, offscreen mode is usually required.
+    - This function tries to reuse an existing Qt app if one already exists.
+    """
+    global _APP, _INITIALIZED, _STATUS
+
+    if not QT_AVAILABLE:
+        raise RuntimeError(
+            "PySide6 is not available. Install PySide6 to use universal_render.\n"
+            f"Original import error: {QT_IMPORT_ERROR}"
+        )
+
+    inferred_headless = is_headless_environment()
+    use_headless = _normalize_bool(headless, inferred_headless)
+
+    warnings: List[str] = []
+
+    if _INITIALIZED and not force:
+        _STATUS.headless = use_headless
+        _STATUS.offscreen_requested = bool(offscreen)
+        _STATUS.qt_qpa_platform = os.environ.get("QT_QPA_PLATFORM")
+        _STATUS.offscreen_enabled = (
+            (_STATUS.qt_qpa_platform or "").lower() == "offscreen"
+        )
+        if warnings:
+            _STATUS.warnings.extend(warnings)
+        return _APP
+
+    if use_headless and offscreen:
+        enabled = _ensure_offscreen_env(force=force)
+        if enabled:
+            _STATUS.offscreen_enabled = True
+        else:
+            warnings.append(
+                "Headless mode detected, but QT_QPA_PLATFORM is not set to 'offscreen'."
+            )
+
+    existing = _existing_app()
+    if existing is not None:
+        _APP = existing
+        _INITIALIZED = True
+
+        _STATUS.initialized = True
+        _STATUS.app_created = True
+        _STATUS.app_class = type(existing).__name__
+        _STATUS.headless = use_headless
+        _STATUS.offscreen_requested = bool(offscreen)
+        _STATUS.qt_qpa_platform = os.environ.get("QT_QPA_PLATFORM")
+        _STATUS.offscreen_enabled = (
+            (_STATUS.qt_qpa_platform or "").lower() == "offscreen"
+        )
+        _STATUS.warnings = warnings
+        return _APP
+
+    argv = [sys.argv[0] if sys.argv else "universal_render"]
+
+    try:
+        _APP = QApplication(argv)
+    except Exception as e:
+        _STATUS.initialized = False
+        _STATUS.app_created = False
+        _STATUS.app_class = None
+        _STATUS.headless = use_headless
+        _STATUS.offscreen_requested = bool(offscreen)
+        _STATUS.qt_qpa_platform = os.environ.get("QT_QPA_PLATFORM")
+        _STATUS.offscreen_enabled = (
+            (_STATUS.qt_qpa_platform or "").lower() == "offscreen"
+        )
+        _STATUS.warnings = warnings
+
+        extra = []
+        if use_headless and offscreen:
+            extra.append(
+                "This looks like a headless environment. Qt offscreen rendering was requested."
+            )
+        if is_colab_environment():
+            extra.append(
+                "Detected Google Colab. You may also need to install fonts and keep QT_QPA_PLATFORM=offscreen."
+            )
+        if is_kaggle_environment():
+            extra.append(
+                "Detected Kaggle. You may also need to install fonts and keep QT_QPA_PLATFORM=offscreen."
+            )
+
+        extra_text = "\n".join(extra)
+        raise RuntimeError(
+            "Failed to initialize Qt for universal_render.\n"
+            f"Qt error: {e}\n"
+            f"{extra_text}".strip()
+        ) from e
+
+    _INITIALIZED = True
+
+    _STATUS.initialized = True
+    _STATUS.app_created = True
+    _STATUS.app_class = type(_APP).__name__
+    _STATUS.headless = use_headless
+    _STATUS.offscreen_requested = bool(offscreen)
+    _STATUS.qt_qpa_platform = os.environ.get("QT_QPA_PLATFORM")
+    _STATUS.offscreen_enabled = (
+        (_STATUS.qt_qpa_platform or "").lower() == "offscreen"
+    )
+    _STATUS.warnings = warnings
+
+    if use_headless and not _STATUS.offscreen_enabled:
+        _STATUS.warnings.append(
+            "Headless environment detected, but offscreen Qt platform is not active."
+        )
+
+    return _APP
+
+
+def ensure_qt_application() -> Any:
+    """
+    Convenience wrapper for lazy initialization with safe defaults.
+    """
+    return init_renderer(headless=None, offscreen=True, force=False)
+
+
+def get_renderer_status() -> Dict[str, Any]:
+    """
+    Return backend/Qt initialization status as a plain dictionary.
+    """
+    _STATUS.qt_available = QT_AVAILABLE
+    _STATUS.qt_import_error = str(QT_IMPORT_ERROR) if QT_IMPORT_ERROR else None
+    _STATUS.qt_qpa_platform = os.environ.get("QT_QPA_PLATFORM")
+    _STATUS.offscreen_enabled = ((_STATUS.qt_qpa_platform or "").lower() == "offscreen")
+    _STATUS.headless = is_headless_environment()
+    return _STATUS.to_dict()
+
+
+def check_environment() -> Dict[str, Any]:
+    """
+    Lightweight diagnostic snapshot of the current runtime.
+    """
+    warnings: List[str] = []
+
+    qt_qpa = os.environ.get("QT_QPA_PLATFORM")
+    headless = is_headless_environment()
+
+    if not QT_AVAILABLE:
+        warnings.append("PySide6 is not installed or failed to import.")
+
+    if headless and (qt_qpa or "").lower() != "offscreen":
+        warnings.append(
+            "Headless environment detected but QT_QPA_PLATFORM is not 'offscreen'."
+        )
+
+    if is_colab_environment():
+        warnings.append(
+            "Running in Google Colab. Script fonts may need manual installation or registration."
+        )
+
+    if is_kaggle_environment():
+        warnings.append(
+            "Running in Kaggle. Script fonts may need manual installation or registration."
+        )
+
+    return {
+        "qt_available": QT_AVAILABLE,
+        "qt_import_error": str(QT_IMPORT_ERROR) if QT_IMPORT_ERROR else None,
+        "headless": headless,
+        "notebook": is_notebook_environment(),
+        "colab": is_colab_environment(),
+        "kaggle": is_kaggle_environment(),
+        "qt_qpa_platform": qt_qpa,
+        "warnings": warnings,
+    }
+
+
+def reset_renderer_state() -> None:
+    """
+    Reset only the Python-side tracking state.
+
+    This does not destroy an already-running Qt application, because Qt apps are
+    generally process-global and should not be forcefully torn down here.
+    """
+    global _APP, _INITIALIZED, _STATUS
+
+    existing = _existing_app()
+    _APP = existing
+    _INITIALIZED = existing is not None
+
+    _STATUS = RendererStatus(
+        qt_import_error=str(QT_IMPORT_ERROR) if QT_IMPORT_ERROR else None
+    )
+    _STATUS.initialized = _INITIALIZED
+    _STATUS.app_created = existing is not None
+    _STATUS.app_class = type(existing).__name__ if existing is not None else None
+    _STATUS.qt_qpa_platform = os.environ.get("QT_QPA_PLATFORM")
+    _STATUS.offscreen_enabled = (
+        ((_STATUS.qt_qpa_platform or "").lower() == "offscreen")
+    )
+    _STATUS.headless = is_headless_environment()