truthound 1.0.8__py3-none-any.whl

truthound/datadocs/themes/loader.py

@@ -0,0 +1,336 @@
+"""Theme loader for loading themes from external files.
+
+This module provides utilities for loading themes from YAML, JSON,
+or dictionary configurations.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from truthound.datadocs.themes.base import (
+    ThemeConfig,
+    ThemeColors,
+    ThemeTypography,
+    ThemeSpacing,
+    ThemeAssets,
+)
+from truthound.datadocs.themes.enterprise import (
+    EnterpriseTheme,
+    EnterpriseThemeConfig,
+    BrandingConfig,
+)
+
+
+class ThemeLoader:
+    """Loader for theme configurations from various sources.
+
+    Supports loading from:
+    - YAML files
+    - JSON files
+    - Python dictionaries
+
+    Example:
+        loader = ThemeLoader()
+
+        # Load from YAML
+        theme = loader.load("./themes/my-theme.yaml")
+
+        # Load from JSON
+        theme = loader.load("./themes/my-theme.json")
+
+        # Load from dict
+        theme = loader.from_dict({
+            "name": "my-theme",
+            "colors": {"primary": "#FF5722"},
+        })
+    """
+
+    def load(self, path: Path | str) -> EnterpriseTheme:
+        """Load a theme from a file.
+
+        Args:
+            path: Path to theme file (YAML or JSON).
+
+        Returns:
+            Loaded theme instance.
+
+        Raises:
+            FileNotFoundError: If file doesn't exist.
+            ValueError: If file format is unsupported.
+        """
+        path = Path(path)
+
+        if not path.exists():
+            raise FileNotFoundError(f"Theme file not found: {path}")
+
+        suffix = path.suffix.lower()
+
+        if suffix in (".yaml", ".yml"):
+            return self.load_yaml(path)
+        elif suffix == ".json":
+            return self.load_json(path)
+        else:
+            raise ValueError(f"Unsupported theme file format: {suffix}")
+
+    def load_yaml(self, path: Path | str) -> EnterpriseTheme:
+        """Load a theme from a YAML file.
+
+        Args:
+            path: Path to YAML file.
+
+        Returns:
+            Loaded theme instance.
+        """
+        try:
+            import yaml
+        except ImportError:
+            raise ImportError(
+                "PyYAML is required for YAML theme loading. "
+                "Install with: pip install pyyaml"
+            )
+
+        path = Path(path)
+        with open(path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+
+        return self.from_dict(data)
+
+    def load_json(self, path: Path | str) -> EnterpriseTheme:
+        """Load a theme from a JSON file.
+
+        Args:
+            path: Path to JSON file.
+
+        Returns:
+            Loaded theme instance.
+        """
+        import json
+
+        path = Path(path)
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        return self.from_dict(data)
+
+    def from_dict(self, data: dict[str, Any]) -> EnterpriseTheme:
+        """Create a theme from a dictionary.
+
+        Args:
+            data: Theme configuration dictionary.
+
+        Returns:
+            EnterpriseTheme instance.
+        """
+        # Parse branding
+        branding_data = data.get("branding", {})
+        branding = BrandingConfig(
+            company_name=branding_data.get("company_name", data.get("company_name", "")),
+            tagline=branding_data.get("tagline", ""),
+            logo_url=branding_data.get("logo_url", data.get("logo_url")),
+            logo_base64=branding_data.get("logo_base64", data.get("logo_base64")),
+            logo_height=branding_data.get("logo_height", "40px"),
+            favicon_url=branding_data.get("favicon_url"),
+            copyright_text=branding_data.get("copyright_text", ""),
+            website_url=branding_data.get("website_url", ""),
+            support_email=branding_data.get("support_email", ""),
+        )
+
+        # Parse colors
+        colors_data = data.get("colors", {})
+        colors = ThemeColors(
+            background=colors_data.get("background", "#fafbfc"),
+            surface=colors_data.get("surface", "#ffffff"),
+            text_primary=colors_data.get("text_primary", "#1f2937"),
+            text_secondary=colors_data.get("text_secondary", "#6b7280"),
+            primary=colors_data.get("primary", data.get("primary_color", "#2563eb")),
+            secondary=colors_data.get("secondary", data.get("secondary_color", "#4f46e5")),
+            accent=colors_data.get("accent", "#7c3aed"),
+            success=colors_data.get("success", "#059669"),
+            warning=colors_data.get("warning", "#d97706"),
+            error=colors_data.get("error", "#dc2626"),
+            info=colors_data.get("info", "#0284c7"),
+            border=colors_data.get("border", "#d1d5db"),
+            shadow=colors_data.get("shadow", "rgba(0, 0, 0, 0.05)"),
+            chart_palette=tuple(colors_data.get("chart_palette", [])) or ThemeColors().chart_palette,
+        )
+
+        # Parse typography
+        typography_data = data.get("typography", {})
+        typography = ThemeTypography(
+            font_family=typography_data.get("font_family", data.get("font_family", "'Inter', system-ui, sans-serif")),
+            font_family_mono=typography_data.get("font_family_mono", "'JetBrains Mono', monospace"),
+        )
+
+        # Parse spacing
+        spacing_data = data.get("spacing", {})
+        spacing_kwargs = {}
+        for key in ("border_radius_sm", "border_radius_md", "border_radius_lg", "border_radius_xl",
+                    "spacing_xs", "spacing_sm", "spacing_md", "spacing_lg", "spacing_xl",
+                    "shadow_sm", "shadow_md", "shadow_lg", "shadow_xl"):
+            if key in spacing_data:
+                spacing_kwargs[key] = spacing_data[key]
+        spacing = ThemeSpacing(**spacing_kwargs) if spacing_kwargs else ThemeSpacing()
+
+        # Build config
+        config = EnterpriseThemeConfig(
+            name=data.get("name", "custom"),
+            display_name=data.get("display_name", data.get("name", "Custom Theme")),
+            description=data.get("description", ""),
+            branding=branding,
+            colors=colors,
+            typography=typography,
+            spacing=spacing,
+            custom_css=data.get("custom_css", ""),
+            print_css=data.get("print_css", ""),
+            show_header=data.get("show_header", True),
+            show_footer=data.get("show_footer", True),
+            show_toc=data.get("show_toc", True),
+            show_branding=data.get("show_branding", True),
+            pdf_options=data.get("pdf_options", {}),
+        )
+
+        return EnterpriseTheme.from_config(config)
+
+    def to_dict(self, theme: EnterpriseTheme) -> dict[str, Any]:
+        """Convert a theme to a dictionary.
+
+        Args:
+            theme: Theme to convert.
+
+        Returns:
+            Dictionary representation.
+        """
+        config = theme.enterprise_config
+        branding = config.branding
+        colors = config.colors
+        typography = config.typography
+        spacing = config.spacing
+
+        return {
+            "name": config.name,
+            "display_name": config.display_name,
+            "description": config.description,
+            "branding": {
+                "company_name": branding.company_name,
+                "tagline": branding.tagline,
+                "logo_url": branding.logo_url,
+                "logo_base64": branding.logo_base64,
+                "logo_height": branding.logo_height,
+                "favicon_url": branding.favicon_url,
+                "copyright_text": branding.copyright_text,
+                "website_url": branding.website_url,
+                "support_email": branding.support_email,
+            },
+            "colors": {
+                "background": colors.background,
+                "surface": colors.surface,
+                "text_primary": colors.text_primary,
+                "text_secondary": colors.text_secondary,
+                "primary": colors.primary,
+                "secondary": colors.secondary,
+                "accent": colors.accent,
+                "success": colors.success,
+                "warning": colors.warning,
+                "error": colors.error,
+                "info": colors.info,
+                "border": colors.border,
+                "shadow": colors.shadow,
+                "chart_palette": list(colors.chart_palette),
+            },
+            "typography": {
+                "font_family": typography.font_family,
+                "font_family_mono": typography.font_family_mono,
+            },
+            "spacing": {
+                "border_radius_sm": spacing.border_radius_sm,
+                "border_radius_md": spacing.border_radius_md,
+                "border_radius_lg": spacing.border_radius_lg,
+                "border_radius_xl": spacing.border_radius_xl,
+            },
+            "custom_css": config.custom_css,
+            "show_header": config.show_header,
+            "show_footer": config.show_footer,
+            "show_toc": config.show_toc,
+            "show_branding": config.show_branding,
+        }
+
+    def save_yaml(self, theme: EnterpriseTheme, path: Path | str) -> None:
+        """Save a theme to a YAML file.
+
+        Args:
+            theme: Theme to save.
+            path: Output file path.
+        """
+        try:
+            import yaml
+        except ImportError:
+            raise ImportError(
+                "PyYAML is required for YAML export. "
+                "Install with: pip install pyyaml"
+            )
+
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        data = self.to_dict(theme)
+        with open(path, "w", encoding="utf-8") as f:
+            yaml.dump(data, f, default_flow_style=False, allow_unicode=True)
+
+    def save_json(self, theme: EnterpriseTheme, path: Path | str) -> None:
+        """Save a theme to a JSON file.
+
+        Args:
+            theme: Theme to save.
+            path: Output file path.
+        """
+        import json
+
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        data = self.to_dict(theme)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+
+# Convenience functions
+
+_loader = ThemeLoader()
+
+
+def load_theme_from_yaml(path: Path | str) -> EnterpriseTheme:
+    """Load a theme from a YAML file.
+
+    Args:
+        path: Path to YAML file.
+
+    Returns:
+        Loaded theme.
+    """
+    return _loader.load_yaml(path)
+
+
+def load_theme_from_json(path: Path | str) -> EnterpriseTheme:
+    """Load a theme from a JSON file.
+
+    Args:
+        path: Path to JSON file.
+
+    Returns:
+        Loaded theme.
+    """
+    return _loader.load_json(path)
+
+
+def load_theme_from_dict(data: dict[str, Any]) -> EnterpriseTheme:
+    """Create a theme from a dictionary.
+
+    Args:
+        data: Theme configuration dictionary.
+
+    Returns:
+        EnterpriseTheme instance.
+    """
+    return _loader.from_dict(data)

truthound/datadocs/themes.py

@@ -0,0 +1,301 @@
+"""Pre-defined themes for Data Docs reports.
+
+This module provides carefully designed themes that are clean, modern,
+and suitable for enterprise use.
+"""
+
+from truthound.datadocs.base import (
+    ReportTheme,
+    ThemeColors,
+    ThemeTypography,
+    ThemeSpacing,
+    ThemeConfig,
+)
+
+
+# =============================================================================
+# Light Theme - Clean and Professional
+# =============================================================================
+
+LIGHT_THEME = ThemeConfig(
+    name="light",
+    colors=ThemeColors(
+        # Main colors
+        background="#ffffff",
+        surface="#f8fafc",
+        text_primary="#0f172a",
+        text_secondary="#64748b",
+
+        # Brand colors
+        primary="#3b82f6",
+        secondary="#8b5cf6",
+        accent="#ec4899",
+
+        # Semantic colors
+        success="#22c55e",
+        warning="#f59e0b",
+        error="#ef4444",
+        info="#0ea5e9",
+
+        # Border and shadow
+        border="#e2e8f0",
+        shadow="rgba(15, 23, 42, 0.08)",
+
+        # Chart colors (Blue-based palette)
+        chart_palette=(
+            "#3b82f6", "#8b5cf6", "#ec4899", "#06b6d4",
+            "#22c55e", "#f59e0b", "#ef4444", "#6366f1",
+            "#14b8a6", "#f97316"
+        ),
+    ),
+    typography=ThemeTypography(
+        font_family="'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+        font_family_mono="'JetBrains Mono', 'Fira Code', 'Consolas', monospace",
+    ),
+    spacing=ThemeSpacing(
+        border_radius_sm="6px",
+        border_radius_md="8px",
+        border_radius_lg="12px",
+        border_radius_xl="16px",
+        shadow_md="0 4px 6px -1px rgba(15, 23, 42, 0.1), 0 2px 4px -1px rgba(15, 23, 42, 0.06)",
+    ),
+)
+
+
+# =============================================================================
+# Dark Theme - Modern and Elegant
+# =============================================================================
+
+DARK_THEME = ThemeConfig(
+    name="dark",
+    colors=ThemeColors(
+        # Main colors
+        background="#0f172a",
+        surface="#1e293b",
+        text_primary="#f1f5f9",
+        text_secondary="#94a3b8",
+
+        # Brand colors
+        primary="#60a5fa",
+        secondary="#a78bfa",
+        accent="#f472b6",
+
+        # Semantic colors
+        success="#4ade80",
+        warning="#fbbf24",
+        error="#f87171",
+        info="#38bdf8",
+
+        # Border and shadow
+        border="#334155",
+        shadow="rgba(0, 0, 0, 0.25)",
+
+        # Chart colors (Vibrant for dark background)
+        chart_palette=(
+            "#60a5fa", "#a78bfa", "#f472b6", "#22d3ee",
+            "#4ade80", "#fbbf24", "#f87171", "#818cf8",
+            "#2dd4bf", "#fb923c"
+        ),
+    ),
+    typography=ThemeTypography(
+        font_family="'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+        font_family_mono="'JetBrains Mono', 'Fira Code', 'Consolas', monospace",
+    ),
+    spacing=ThemeSpacing(
+        shadow_md="0 4px 6px -1px rgba(0, 0, 0, 0.3), 0 2px 4px -1px rgba(0, 0, 0, 0.2)",
+        shadow_lg="0 10px 15px -3px rgba(0, 0, 0, 0.3), 0 4px 6px -2px rgba(0, 0, 0, 0.2)",
+    ),
+)
+
+
+# =============================================================================
+# Professional Theme - Corporate and Subdued
+# =============================================================================
+
+PROFESSIONAL_THEME = ThemeConfig(
+    name="professional",
+    colors=ThemeColors(
+        # Main colors
+        background="#fafbfc",
+        surface="#ffffff",
+        text_primary="#1f2937",
+        text_secondary="#6b7280",
+
+        # Brand colors (Corporate blue)
+        primary="#2563eb",
+        secondary="#4f46e5",
+        accent="#7c3aed",
+
+        # Semantic colors
+        success="#059669",
+        warning="#d97706",
+        error="#dc2626",
+        info="#0284c7",
+
+        # Border and shadow
+        border="#d1d5db",
+        shadow="rgba(0, 0, 0, 0.05)",
+
+        # Chart colors (Professional palette)
+        chart_palette=(
+            "#2563eb", "#4f46e5", "#7c3aed", "#0891b2",
+            "#059669", "#d97706", "#dc2626", "#4338ca",
+            "#0d9488", "#ea580c"
+        ),
+    ),
+    typography=ThemeTypography(
+        font_family="'Segoe UI', 'SF Pro Display', -apple-system, BlinkMacSystemFont, Roboto, sans-serif",
+        font_family_mono="'Cascadia Code', 'SF Mono', 'Consolas', monospace",
+    ),
+    spacing=ThemeSpacing(
+        border_radius_sm="4px",
+        border_radius_md="6px",
+        border_radius_lg="8px",
+        border_radius_xl="12px",
+    ),
+)
+
+
+# =============================================================================
+# Minimal Theme - Clean and Unobtrusive
+# =============================================================================
+
+MINIMAL_THEME = ThemeConfig(
+    name="minimal",
+    colors=ThemeColors(
+        # Main colors
+        background="#ffffff",
+        surface="#fafafa",
+        text_primary="#171717",
+        text_secondary="#737373",
+
+        # Brand colors (Monochromatic)
+        primary="#404040",
+        secondary="#525252",
+        accent="#262626",
+
+        # Semantic colors (Muted)
+        success="#16a34a",
+        warning="#ca8a04",
+        error="#dc2626",
+        info="#2563eb",
+
+        # Border and shadow
+        border="#e5e5e5",
+        shadow="rgba(0, 0, 0, 0.03)",
+
+        # Chart colors (Grayscale with accent)
+        chart_palette=(
+            "#404040", "#525252", "#737373", "#a3a3a3",
+            "#16a34a", "#ca8a04", "#dc2626", "#2563eb",
+            "#0d9488", "#ea580c"
+        ),
+    ),
+    typography=ThemeTypography(
+        font_family="'Helvetica Neue', Arial, sans-serif",
+        font_family_mono="'Monaco', 'Menlo', monospace",
+    ),
+    spacing=ThemeSpacing(
+        border_radius_sm="2px",
+        border_radius_md="4px",
+        border_radius_lg="6px",
+        border_radius_xl="8px",
+        shadow_sm="0 1px 2px rgba(0, 0, 0, 0.03)",
+        shadow_md="0 2px 4px rgba(0, 0, 0, 0.05)",
+    ),
+)
+
+
+# =============================================================================
+# Modern Theme - Vibrant and Contemporary
+# =============================================================================
+
+MODERN_THEME = ThemeConfig(
+    name="modern",
+    colors=ThemeColors(
+        # Main colors
+        background="#fefefe",
+        surface="#f5f5f7",
+        text_primary="#1d1d1f",
+        text_secondary="#86868b",
+
+        # Brand colors (Gradient-inspired)
+        primary="#5e5ce6",
+        secondary="#bf5af2",
+        accent="#ff375f",
+
+        # Semantic colors
+        success="#32d74b",
+        warning="#ff9f0a",
+        error="#ff453a",
+        info="#0a84ff",
+
+        # Border and shadow
+        border="#d2d2d7",
+        shadow="rgba(0, 0, 0, 0.08)",
+
+        # Chart colors (Apple-inspired)
+        chart_palette=(
+            "#5e5ce6", "#bf5af2", "#ff375f", "#30d158",
+            "#ff9f0a", "#64d2ff", "#ff453a", "#ffd60a",
+            "#ac8e68", "#0a84ff"
+        ),
+    ),
+    typography=ThemeTypography(
+        font_family="'SF Pro Display', -apple-system, BlinkMacSystemFont, 'Helvetica Neue', sans-serif",
+        font_family_mono="'SF Mono', 'Monaco', monospace",
+    ),
+    spacing=ThemeSpacing(
+        border_radius_sm="8px",
+        border_radius_md="12px",
+        border_radius_lg="16px",
+        border_radius_xl="22px",
+        shadow_md="0 4px 12px rgba(0, 0, 0, 0.08)",
+        shadow_lg="0 8px 24px rgba(0, 0, 0, 0.12)",
+    ),
+)
+
+
+# =============================================================================
+# Theme Registry
+# =============================================================================
+
+THEMES: dict[ReportTheme, ThemeConfig] = {
+    ReportTheme.LIGHT: LIGHT_THEME,
+    ReportTheme.DARK: DARK_THEME,
+    ReportTheme.PROFESSIONAL: PROFESSIONAL_THEME,
+    ReportTheme.MINIMAL: MINIMAL_THEME,
+    ReportTheme.MODERN: MODERN_THEME,
+}
+
+
+def get_theme(theme: ReportTheme | str) -> ThemeConfig:
+    """Get a theme configuration by name or enum.
+
+    Args:
+        theme: Theme name or enum value
+
+    Returns:
+        ThemeConfig for the requested theme
+
+    Raises:
+        ValueError: If theme is not found
+    """
+    if isinstance(theme, str):
+        try:
+            theme = ReportTheme(theme)
+        except ValueError:
+            available = [t.value for t in ReportTheme]
+            raise ValueError(
+                f"Unknown theme '{theme}'. Available: {available}"
+            )
+
+    if theme not in THEMES:
+        raise ValueError(f"Theme '{theme.value}' not configured")
+
+    return THEMES[theme]
+
+
+def get_available_themes() -> list[str]:
+    """Get list of available theme names."""
+    return [t.value for t in THEMES.keys()]

truthound/datadocs/transformers/__init__.py

@@ -0,0 +1,57 @@
+"""Transformers for the Data Docs report pipeline.
+
+Transformers modify the ReportContext data during the pipeline's transform phase.
+They are applied in order, with each receiving the output of the previous.
+
+Available Transformers:
+- I18nTransformer: Internationalization and localization
+- FilterTransformer: Section and data filtering
+- EnricherTransformer: Metadata and data enrichment
+- AggregatorTransformer: Data aggregation and summarization
+"""
+
+from truthound.datadocs.transformers.base import (
+    Transformer,
+    BaseTransformer,
+    ChainedTransformer,
+    ConditionalTransformer,
+    TransformResult,
+)
+from truthound.datadocs.transformers.i18n import (
+    I18nTransformer,
+    TranslationResolver,
+)
+from truthound.datadocs.transformers.filters import (
+    FilterTransformer,
+    SectionFilter,
+    ColumnFilter,
+    AlertFilter,
+)
+from truthound.datadocs.transformers.enrichers import (
+    EnricherTransformer,
+    MetadataEnricher,
+    QualityScoreEnricher,
+    RecommendationEnricher,
+)
+
+__all__ = [
+    # Base
+    "Transformer",
+    "BaseTransformer",
+    "ChainedTransformer",
+    "ConditionalTransformer",
+    "TransformResult",
+    # I18n
+    "I18nTransformer",
+    "TranslationResolver",
+    # Filters
+    "FilterTransformer",
+    "SectionFilter",
+    "ColumnFilter",
+    "AlertFilter",
+    # Enrichers
+    "EnricherTransformer",
+    "MetadataEnricher",
+    "QualityScoreEnricher",
+    "RecommendationEnricher",
+]