truthound 1.0.8__py3-none-any.whl

truthound/datadocs/i18n/loader.py

@@ -0,0 +1,256 @@
+"""Locale loader for external translation files.
+
+This module provides utilities for loading translations
+from JSON, YAML, and other external sources.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from truthound.datadocs.i18n.catalog import ReportCatalog, register_catalog
+
+
+class LocaleLoader:
+    """Loader for external locale files.
+
+    Supports JSON and YAML formats for loading custom translations.
+
+    Example:
+        loader = LocaleLoader()
+
+        # Load single file
+        loader.load_file(Path("locales/fr.json"))
+
+        # Load directory of locale files
+        loader.load_directory(Path("locales/"))
+    """
+
+    def __init__(self, auto_register: bool = True) -> None:
+        """Initialize loader.
+
+        Args:
+            auto_register: Automatically register loaded catalogs.
+        """
+        self._auto_register = auto_register
+        self._catalogs: dict[str, ReportCatalog] = {}
+
+    def load_file(self, path: Path) -> ReportCatalog:
+        """Load a locale file.
+
+        Args:
+            path: Path to locale file (JSON or YAML).
+
+        Returns:
+            Loaded ReportCatalog.
+
+        Raises:
+            ValueError: If file format is unsupported.
+            FileNotFoundError: If file doesn't exist.
+        """
+        if not path.exists():
+            raise FileNotFoundError(f"Locale file not found: {path}")
+
+        suffix = path.suffix.lower()
+
+        if suffix == ".json":
+            catalog = self._load_json(path)
+        elif suffix in (".yaml", ".yml"):
+            catalog = self._load_yaml(path)
+        else:
+            raise ValueError(f"Unsupported locale file format: {suffix}")
+
+        self._catalogs[catalog.locale] = catalog
+
+        if self._auto_register:
+            register_catalog(catalog)
+
+        return catalog
+
+    def load_directory(
+        self,
+        directory: Path,
+        pattern: str = "*.json",
+    ) -> dict[str, ReportCatalog]:
+        """Load all locale files from a directory.
+
+        Args:
+            directory: Directory containing locale files.
+            pattern: Glob pattern for files.
+
+        Returns:
+            Dictionary of locale to catalog.
+        """
+        if not directory.is_dir():
+            raise NotADirectoryError(f"Not a directory: {directory}")
+
+        catalogs = {}
+        for file_path in directory.glob(pattern):
+            try:
+                catalog = self.load_file(file_path)
+                catalogs[catalog.locale] = catalog
+            except Exception:
+                # Skip invalid files
+                pass
+
+        return catalogs
+
+    def _load_json(self, path: Path) -> ReportCatalog:
+        """Load JSON locale file."""
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        return self._parse_locale_data(data, path)
+
+    def _load_yaml(self, path: Path) -> ReportCatalog:
+        """Load YAML locale file."""
+        try:
+            import yaml
+        except ImportError:
+            raise ImportError(
+                "PyYAML is required for YAML locale files. "
+                "Install with: pip install pyyaml"
+            )
+
+        with open(path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+
+        return self._parse_locale_data(data, path)
+
+    def _parse_locale_data(
+        self,
+        data: dict[str, Any],
+        path: Path,
+    ) -> ReportCatalog:
+        """Parse locale data into a catalog.
+
+        Supports both flat and nested message structures.
+
+        Args:
+            data: Parsed locale data.
+            path: Source file path (for locale inference).
+
+        Returns:
+            ReportCatalog.
+        """
+        # Extract locale
+        locale = data.get("locale")
+        if not locale:
+            # Infer from filename (e.g., "ko.json" -> "ko")
+            locale = path.stem
+
+        # Extract messages
+        messages = data.get("messages", {})
+        if not messages:
+            # Try flat structure (key: value at root level)
+            messages = {
+                k: v for k, v in data.items()
+                if k not in ("locale", "metadata") and isinstance(v, str)
+            }
+
+        # Flatten nested messages
+        if any(isinstance(v, dict) for v in messages.values()):
+            messages = self._flatten_messages(messages)
+
+        # Extract metadata
+        metadata = data.get("metadata", {})
+        if "name" not in metadata:
+            metadata["name"] = locale
+        if "source" not in metadata:
+            metadata["source"] = str(path)
+
+        return ReportCatalog(
+            locale=locale,
+            messages=messages,
+            metadata=metadata,
+        )
+
+    def _flatten_messages(
+        self,
+        nested: dict[str, Any],
+        prefix: str = "",
+    ) -> dict[str, str]:
+        """Flatten nested message structure.
+
+        Args:
+            nested: Nested message dictionary.
+            prefix: Key prefix.
+
+        Returns:
+            Flat message dictionary.
+
+        Example:
+            Input:  {"report": {"title": "..."}}
+            Output: {"report.title": "..."}
+        """
+        flat = {}
+
+        for key, value in nested.items():
+            full_key = f"{prefix}.{key}" if prefix else key
+
+            if isinstance(value, dict):
+                flat.update(self._flatten_messages(value, full_key))
+            elif isinstance(value, str):
+                flat[full_key] = value
+
+        return flat
+
+    def get_catalogs(self) -> dict[str, ReportCatalog]:
+        """Get all loaded catalogs."""
+        return self._catalogs.copy()
+
+    def get(self, locale: str) -> ReportCatalog | None:
+        """Get a loaded catalog by locale."""
+        return self._catalogs.get(locale)
+
+
+def load_locale_from_file(path: Path | str) -> ReportCatalog:
+    """Load a locale from a file.
+
+    Args:
+        path: Path to locale file.
+
+    Returns:
+        Loaded catalog.
+    """
+    loader = LocaleLoader(auto_register=True)
+    return loader.load_file(Path(path))
+
+
+def load_locale_from_dict(
+    locale: str,
+    messages: dict[str, str],
+    metadata: dict[str, Any] | None = None,
+) -> ReportCatalog:
+    """Create and register a catalog from a dictionary.
+
+    Args:
+        locale: Locale code.
+        messages: Message dictionary.
+        metadata: Optional metadata.
+
+    Returns:
+        Created catalog.
+    """
+    catalog = ReportCatalog.from_dict(locale, messages, metadata)
+    register_catalog(catalog)
+    return catalog
+
+
+def load_locales_from_directory(
+    directory: Path | str,
+    pattern: str = "*.json",
+) -> dict[str, ReportCatalog]:
+    """Load all locales from a directory.
+
+    Args:
+        directory: Directory path.
+        pattern: File pattern.
+
+    Returns:
+        Dictionary of loaded catalogs.
+    """
+    loader = LocaleLoader(auto_register=True)
+    return loader.load_directory(Path(directory), pattern)

truthound/datadocs/i18n/plurals.py

@@ -0,0 +1,378 @@
+"""Plural rules for report internationalization.
+
+This module provides CLDR-compliant plural handling for reports,
+supporting proper pluralization in 100+ languages.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Callable
+
+
+class PluralCategory(Enum):
+    """CLDR plural categories."""
+
+    ZERO = "zero"
+    ONE = "one"
+    TWO = "two"
+    FEW = "few"
+    MANY = "many"
+    OTHER = "other"
+
+
+@dataclass
+class PluralOperands:
+    """CLDR plural operands.
+
+    See: https://unicode.org/reports/tr35/tr35-numbers.html#Operands
+    """
+
+    n: float  # Absolute value
+    i: int    # Integer digits
+    v: int    # Visible fraction digits (with trailing zeros)
+    w: int    # Visible fraction digits (without trailing zeros)
+    f: int    # Fraction digits as integer (with trailing zeros)
+    t: int    # Fraction digits as integer (without trailing zeros)
+
+    @classmethod
+    def from_number(cls, n: float | int) -> "PluralOperands":
+        """Create operands from a number."""
+        abs_n = abs(n)
+        i = int(abs_n)
+
+        if isinstance(n, int):
+            return cls(n=float(abs_n), i=i, v=0, w=0, f=0, t=0)
+
+        str_n = str(abs_n)
+        if "." in str_n:
+            fraction_str = str_n.split(".")[1]
+            v = len(fraction_str)
+            f = int(fraction_str) if fraction_str else 0
+            t_str = fraction_str.rstrip("0")
+            w = len(t_str)
+            t = int(t_str) if t_str else 0
+        else:
+            v = w = f = t = 0
+
+        return cls(n=float(abs_n), i=i, v=v, w=w, f=f, t=t)
+
+
+# Type for plural rule function
+PluralRuleFunc = Callable[[float | int], PluralCategory]
+
+
+class PluralRules:
+    """CLDR plural rules provider.
+
+    Provides plural category determination for 100+ languages.
+
+    Example:
+        rules = PluralRules()
+        category = rules.get_category(5, "ru")  # PluralCategory.MANY
+    """
+
+    def __init__(self) -> None:
+        self._cardinal_rules: dict[str, PluralRuleFunc] = {}
+        self._ordinal_rules: dict[str, PluralRuleFunc] = {}
+        self._register_rules()
+
+    def _register_rules(self) -> None:
+        """Register all plural rules."""
+        # English, German, Dutch, Italian, Portuguese, Spanish, etc.
+        def english(n: float | int) -> PluralCategory:
+            op = PluralOperands.from_number(n)
+            if op.i == 1 and op.v == 0:
+                return PluralCategory.ONE
+            return PluralCategory.OTHER
+
+        for lang in ["en", "de", "nl", "it", "pt", "es", "ca", "da", "no", "sv", "fi", "et", "hu", "tr", "id", "ms"]:
+            self._cardinal_rules[lang] = english
+
+        # French
+        def french(n: float | int) -> PluralCategory:
+            op = PluralOperands.from_number(n)
+            if op.i in (0, 1):
+                return PluralCategory.ONE
+            return PluralCategory.OTHER
+
+        self._cardinal_rules["fr"] = french
+
+        # Russian, Ukrainian, Serbian, Croatian, Bosnian
+        def slavic(n: float | int) -> PluralCategory:
+            op = PluralOperands.from_number(n)
+            i10 = op.i % 10
+            i100 = op.i % 100
+
+            if op.v == 0 and i10 == 1 and i100 != 11:
+                return PluralCategory.ONE
+            if op.v == 0 and 2 <= i10 <= 4 and not (12 <= i100 <= 14):
+                return PluralCategory.FEW
+            if op.v == 0 and (i10 == 0 or 5 <= i10 <= 9 or 11 <= i100 <= 14):
+                return PluralCategory.MANY
+            return PluralCategory.OTHER
+
+        for lang in ["ru", "uk", "sr", "hr", "bs"]:
+            self._cardinal_rules[lang] = slavic
+
+        # Polish
+        def polish(n: float | int) -> PluralCategory:
+            op = PluralOperands.from_number(n)
+            i10 = op.i % 10
+            i100 = op.i % 100
+
+            if op.i == 1 and op.v == 0:
+                return PluralCategory.ONE
+            if op.v == 0 and 2 <= i10 <= 4 and not (12 <= i100 <= 14):
+                return PluralCategory.FEW
+            if op.v == 0 and (op.i != 1 and i10 in (0, 1) or 5 <= i10 <= 9 or 12 <= i100 <= 14):
+                return PluralCategory.MANY
+            return PluralCategory.OTHER
+
+        self._cardinal_rules["pl"] = polish
+
+        # Arabic
+        def arabic(n: float | int) -> PluralCategory:
+            op = PluralOperands.from_number(n)
+            n100 = int(op.n) % 100
+
+            if op.n == 0:
+                return PluralCategory.ZERO
+            if op.n == 1:
+                return PluralCategory.ONE
+            if op.n == 2:
+                return PluralCategory.TWO
+            if 3 <= n100 <= 10:
+                return PluralCategory.FEW
+            if 11 <= n100 <= 99:
+                return PluralCategory.MANY
+            return PluralCategory.OTHER
+
+        self._cardinal_rules["ar"] = arabic
+
+        # Hebrew
+        def hebrew(n: float | int) -> PluralCategory:
+            op = PluralOperands.from_number(n)
+
+            if op.i == 1 and op.v == 0:
+                return PluralCategory.ONE
+            if op.i == 2 and op.v == 0:
+                return PluralCategory.TWO
+            if op.v == 0 and not (0 <= op.i <= 10) and op.i % 10 == 0:
+                return PluralCategory.MANY
+            return PluralCategory.OTHER
+
+        self._cardinal_rules["he"] = hebrew
+
+        # Japanese, Korean, Chinese, Vietnamese, Thai (no plurals)
+        def no_plural(n: float | int) -> PluralCategory:
+            return PluralCategory.OTHER
+
+        for lang in ["ja", "ko", "zh", "vi", "th"]:
+            self._cardinal_rules[lang] = no_plural
+
+        # Czech, Slovak
+        def czech(n: float | int) -> PluralCategory:
+            op = PluralOperands.from_number(n)
+
+            if op.i == 1 and op.v == 0:
+                return PluralCategory.ONE
+            if 2 <= op.i <= 4 and op.v == 0:
+                return PluralCategory.FEW
+            if op.v != 0:
+                return PluralCategory.MANY
+            return PluralCategory.OTHER
+
+        self._cardinal_rules["cs"] = czech
+        self._cardinal_rules["sk"] = czech
+
+        # Romanian
+        def romanian(n: float | int) -> PluralCategory:
+            op = PluralOperands.from_number(n)
+            n100 = int(op.n) % 100
+
+            if op.i == 1 and op.v == 0:
+                return PluralCategory.ONE
+            if op.v != 0 or op.n == 0 or 2 <= n100 <= 19:
+                return PluralCategory.FEW
+            return PluralCategory.OTHER
+
+        self._cardinal_rules["ro"] = romanian
+
+        # English ordinals
+        def english_ordinal(n: float | int) -> PluralCategory:
+            n10 = int(n) % 10
+            n100 = int(n) % 100
+
+            if n10 == 1 and n100 != 11:
+                return PluralCategory.ONE
+            if n10 == 2 and n100 != 12:
+                return PluralCategory.TWO
+            if n10 == 3 and n100 != 13:
+                return PluralCategory.FEW
+            return PluralCategory.OTHER
+
+        self._ordinal_rules["en"] = english_ordinal
+
+    def get_category(
+        self,
+        count: float | int,
+        locale: str,
+        ordinal: bool = False,
+    ) -> PluralCategory:
+        """Get plural category for a number.
+
+        Args:
+            count: The number.
+            locale: Locale code (e.g., "en", "ko").
+            ordinal: Use ordinal rules.
+
+        Returns:
+            Plural category.
+        """
+        rules = self._ordinal_rules if ordinal else self._cardinal_rules
+        lang = locale.split("_")[0].split("-")[0]
+
+        if lang in rules:
+            return rules[lang](count)
+
+        return PluralCategory.OTHER
+
+    def get_supported_languages(self) -> list[str]:
+        """Get supported language codes."""
+        return list(self._cardinal_rules.keys())
+
+    def register_rule(
+        self,
+        language: str,
+        rule: PluralRuleFunc,
+        ordinal: bool = False,
+    ) -> None:
+        """Register a custom plural rule."""
+        if ordinal:
+            self._ordinal_rules[language] = rule
+        else:
+            self._cardinal_rules[language] = rule
+
+
+# Global instance
+_rules = PluralRules()
+
+
+def get_plural_category(
+    count: float | int,
+    locale: str = "en",
+    ordinal: bool = False,
+) -> PluralCategory:
+    """Get plural category for a number.
+
+    Args:
+        count: The number.
+        locale: Locale code.
+        ordinal: Use ordinal rules.
+
+    Returns:
+        Plural category.
+
+    Example:
+        get_plural_category(1, "en")  # ONE
+        get_plural_category(5, "ru")  # MANY
+    """
+    return _rules.get_category(count, locale, ordinal)
+
+
+def pluralize(
+    count: float | int,
+    singular: str,
+    plural: str,
+    locale: str = "en",
+) -> str:
+    """Simple pluralization for two-form languages.
+
+    Args:
+        count: The number.
+        singular: Singular form.
+        plural: Plural form.
+        locale: Locale code.
+
+    Returns:
+        Appropriate form with count.
+
+    Example:
+        pluralize(1, "file", "files")  # "1 file"
+        pluralize(5, "file", "files")  # "5 files"
+    """
+    category = _rules.get_category(count, locale)
+    form = singular if category == PluralCategory.ONE else plural
+    return f"{count} {form}"
+
+
+def pluralize_with_forms(
+    count: float | int,
+    forms: dict[PluralCategory | str, str],
+    locale: str = "en",
+    **params,
+) -> str:
+    """Pluralize with multiple forms.
+
+    Args:
+        count: The number.
+        forms: Forms for each category.
+        locale: Locale code.
+        **params: Format parameters.
+
+    Returns:
+        Formatted string.
+
+    Example:
+        pluralize_with_forms(
+            5,
+            {
+                PluralCategory.ONE: "{count} file",
+                PluralCategory.OTHER: "{count} files",
+            },
+            "en",
+        )
+        # -> "5 files"
+
+        pluralize_with_forms(
+            3,
+            {
+                "one": "{count} файл",
+                "few": "{count} файла",
+                "many": "{count} файлов",
+                "other": "{count} файла",
+            },
+            "ru",
+        )
+        # -> "3 файла"
+    """
+    category = _rules.get_category(count, locale)
+
+    # Normalize keys
+    normalized: dict[PluralCategory, str] = {}
+    for key, value in forms.items():
+        if isinstance(key, str):
+            try:
+                normalized[PluralCategory(key.lower())] = value
+            except ValueError:
+                pass
+        else:
+            normalized[key] = value
+
+    # Get template
+    template = normalized.get(category)
+    if template is None:
+        template = normalized.get(PluralCategory.OTHER, str(count))
+
+    # Format
+    try:
+        return template.format(count=count, **params)
+    except KeyError:
+        return template
+
+
+def get_plural_rules() -> PluralRules:
+    """Get global plural rules instance."""
+    return _rules

truthound/datadocs/renderers/__init__.py

@@ -0,0 +1,42 @@
+"""Renderers for the Data Docs report pipeline.
+
+Renderers convert the transformed report data into intermediate HTML
+that can then be exported to various formats.
+
+Available Renderers:
+- JinjaRenderer: Jinja2-based template rendering
+- SimpleRenderer: Basic HTML rendering without templates
+- CustomRenderer: Support for user-defined templates
+- CallableRenderer: Render using any Python callable
+"""
+
+from truthound.datadocs.renderers.base import (
+    Renderer,
+    BaseRenderer,
+    RenderResult,
+)
+from truthound.datadocs.renderers.jinja import (
+    JinjaRenderer,
+    JinjaTemplateLoader,
+)
+from truthound.datadocs.renderers.custom import (
+    CustomRenderer,
+    StringTemplateRenderer,
+    FileTemplateRenderer,
+    CallableRenderer,
+)
+
+__all__ = [
+    # Base
+    "Renderer",
+    "BaseRenderer",
+    "RenderResult",
+    # Jinja
+    "JinjaRenderer",
+    "JinjaTemplateLoader",
+    # Custom
+    "CustomRenderer",
+    "StringTemplateRenderer",
+    "FileTemplateRenderer",
+    "CallableRenderer",
+]