dataface 0.1.2__py3-none-any.whl

mdsvg/fonts.py

@@ -0,0 +1,656 @@
+"""Font-based text measurement for precise width calculations.
+
+This module provides accurate text measurement using fonttools to read
+actual glyph metrics from font files.
+
+## Basic Usage
+
+    from mdsvg.fonts import FontMeasurer, get_system_font
+
+    # Use system font (auto-detected)
+    measurer = FontMeasurer.system_default()
+    width = measurer.measure("Hello World", font_size=14)
+
+## Custom Fonts
+
+You can use any TTF/OTF font file:
+
+    measurer = FontMeasurer("/path/to/your/font.ttf")
+    width = measurer.measure("Hello", 14)
+
+### Where to put custom font files
+
+Recommended locations:
+- Project directory: `./fonts/MyFont.ttf`
+- User fonts (macOS): `~/Library/Fonts/MyFont.ttf`
+- User fonts (Linux): `~/.local/share/fonts/MyFont.ttf`
+- User fonts (Windows): `C:\\Users\\<user>\\AppData\\Local\\Microsoft\\Windows\\Fonts\\`
+
+### Google Fonts
+
+Download fonts from Google Fonts automatically:
+
+    from mdsvg.fonts import download_google_font, FontMeasurer
+
+    font_path = download_google_font("Inter")
+    measurer = FontMeasurer(font_path)
+
+Or download manually from https://fonts.google.com and place in your project.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import re
+from dataclasses import dataclass, field
+from functools import lru_cache
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+
+@dataclass
+class FontMeasurer:
+    """
+    Measure text width using actual font metrics via fonttools.
+
+    Example:
+        >>> measurer = FontMeasurer("/System/Library/Fonts/Helvetica.ttc")
+        >>> measurer.measure("Hello World", 14)
+        72.4
+    """
+
+    font_path: str
+    font_number: int = 0  # For .ttc files with multiple fonts
+    _cmap: Optional[Dict[int, str]] = field(default=None, init=False, repr=False)
+    _hmtx: Optional[Any] = field(default=None, init=False, repr=False)
+    _units_per_em: int = field(default=1000, init=False, repr=False)
+    _available: bool = field(default=False, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._init_font()
+
+    def _init_font(self) -> None:
+        """Load font metrics from the font file."""
+        try:
+            from fontTools.ttLib import TTFont, TTLibError
+        except ImportError:
+            # fontTools not installed — measurement unavailable.
+            self._available = False
+            return
+        try:
+            font = TTFont(self.font_path, fontNumber=self.font_number)
+            self._cmap = font.getBestCmap()
+            self._hmtx = font["hmtx"]
+            self._units_per_em = font["head"].unitsPerEm
+            self._available = True
+        except (FileNotFoundError, OSError, TTLibError):
+            # Font file not found, unreadable, or invalid.
+            self._available = False
+
+    def measure(self, text: str, font_size: float) -> float:
+        """
+        Measure the width of text in pixels.
+
+        Args:
+            text: The text to measure.
+            font_size: Font size in pixels.
+
+        Returns:
+            Width in pixels.
+
+        Raises:
+            RuntimeError: If fonttools is not available.
+        """
+        if not text:
+            return 0.0
+
+        if not self._available:
+            raise RuntimeError(
+                "FontMeasurer not available. Install fonttools: pip install fonttools"
+            )
+
+        total_width: float = 0
+        for char in text:
+            glyph_id = self._cmap.get(ord(char)) if self._cmap else None
+            if glyph_id and self._hmtx and glyph_id in self._hmtx.metrics:
+                advance_width, _ = self._hmtx.metrics[glyph_id]
+                total_width += advance_width
+            else:
+                # Fallback for unknown glyphs (space-like width)
+                total_width += self._units_per_em * 0.25
+
+        return (total_width / self._units_per_em) * font_size
+
+    @property
+    def is_available(self) -> bool:
+        """Check if font measurement is available."""
+        return self._available
+
+    @classmethod
+    def system_default(cls) -> Optional[FontMeasurer]:
+        """
+        Create a FontMeasurer using the system default font.
+
+        Returns:
+            FontMeasurer if a system font is found and fonttools is available,
+            None otherwise.
+        """
+        font_path = get_system_font()
+        if font_path:
+            measurer = cls(font_path)
+            if measurer.is_available:
+                return measurer
+        return None
+
+
+@dataclass(frozen=True)
+class WrapPiece:
+    """A measured word/token plus the separator that may precede it."""
+
+    text: str
+    width: float
+    separator: str = ""
+    separator_width: float = 0.0
+    meta: Any = None
+
+
+def get_system_font() -> Optional[str]:
+    """
+    Find a system font that can be used for measurement.
+
+    Looks for common sans-serif fonts that match typical "system-ui" rendering.
+
+    Returns:
+        Path to a font file, or None if not found.
+    """
+    system = platform.system()
+
+    if system == "Darwin":  # macOS
+        candidates = [
+            "/System/Library/Fonts/SFNS.ttf",
+            "/System/Library/Fonts/SFNSText.ttf",
+            "/System/Library/Fonts/Helvetica.ttc",
+            "/Library/Fonts/Arial.ttf",
+            "/System/Library/Fonts/Supplemental/Arial.ttf",
+        ]
+    elif system == "Windows":
+        windir = os.environ.get("WINDIR", "C:\\Windows")
+        candidates = [
+            os.path.join(windir, "Fonts", "segoeui.ttf"),
+            os.path.join(windir, "Fonts", "arial.ttf"),
+            os.path.join(windir, "Fonts", "calibri.ttf"),
+        ]
+    else:  # Linux
+        candidates = [
+            "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+            "/usr/share/fonts/TTF/DejaVuSans.ttf",
+            "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
+            "/usr/share/fonts/truetype/ubuntu/Ubuntu-R.ttf",
+        ]
+
+    for path in candidates:
+        if os.path.exists(path):
+            return path
+
+    return None
+
+
+def get_system_mono_font() -> Optional[str]:
+    """Find a system monospace font for inline-code measurement."""
+    system = platform.system()
+
+    if system == "Darwin":  # macOS
+        candidates = [
+            "/System/Library/Fonts/SFNSMono.ttf",
+            "/System/Library/Fonts/SFMono-Regular.otf",
+            "/System/Library/Fonts/Menlo.ttc",
+            "/System/Library/Fonts/Supplemental/Menlo.ttc",
+            "/Library/Fonts/Courier New.ttf",
+        ]
+    elif system == "Windows":
+        windir = os.environ.get("WINDIR", "C:\\Windows")
+        candidates = [
+            os.path.join(windir, "Fonts", "consola.ttf"),
+            os.path.join(windir, "Fonts", "cour.ttf"),
+        ]
+    else:  # Linux
+        candidates = [
+            "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",
+            "/usr/share/fonts/TTF/DejaVuSansMono.ttf",
+            "/usr/share/fonts/truetype/liberation2/LiberationMono-Regular.ttf",
+            "/usr/share/fonts/truetype/liberation/LiberationMono-Regular.ttf",
+        ]
+
+    for path in candidates:
+        if os.path.exists(path):
+            return path
+
+    return None
+
+
+@lru_cache(maxsize=32)
+def _cached_measurer(font_path: str, font_number: int = 0) -> FontMeasurer:
+    """Return a process-global cached FontMeasurer for *font_path*.
+
+    FontMeasurer is read-only after __post_init__, so sharing a single
+    instance across many SVGRenderer calls (the common Dataface pattern)
+    is safe and avoids repeated TTF CMAP decompile overhead.
+    """
+    return FontMeasurer(font_path, font_number)
+
+
+@lru_cache(maxsize=1)
+def get_default_measurer() -> Optional[FontMeasurer]:
+    """Get a cached FontMeasurer using the system default font."""
+    font_path = get_system_font()
+    if font_path is None:
+        return None
+    measurer = _cached_measurer(font_path)
+    return measurer if measurer.is_available else None
+
+
+def measure_text_precise(
+    text: str,
+    font_size: float,
+    measurer: FontMeasurer,
+) -> float:
+    """Measure text with a real FontMeasurer."""
+    if not measurer.is_available:
+        raise RuntimeError(
+            "Precise font measurer is required for strict wrapping/truncation"
+        )
+    return float(measurer.measure(text, font_size))
+
+
+_SEAM_CHARS = frozenset("_/.-?&=:")
+
+
+def _find_seam_break(
+    token: str, max_width: float, measure: Callable[[str], float]
+) -> int | None:
+    """Return the index after the longest seam-char-terminated prefix that fits max_width.
+
+    Scans left-to-right collecting the last seam position whose prefix fits, so
+    the first acceptable position is always the longest one.  Returns None when
+    no seam-terminated prefix fits within max_width.
+    """
+    best: int | None = None
+    for i, ch in enumerate(token):
+        if ch in _SEAM_CHARS and i > 0 and measure(token[: i + 1]) <= max_width:
+            best = i + 1
+    return best
+
+
+def split_token_precise(
+    token: str,
+    max_width: float,
+    measure: Callable[[str], float],
+) -> list[str]:
+    """Split a long token into pieces that fit within max_width.
+
+    Tries seam characters first (``_/.-?&=:``) then falls back to a
+    binary-search character break for tokens with no seam that fits.
+
+    Args:
+        token: The token to split.
+        max_width: Maximum width of each piece.
+        measure: Width measurement function.
+    """
+    if not token:
+        return [""]
+    if measure(token) <= max_width:
+        return [token]
+
+    pieces: list[str] = []
+    remaining = token
+    while remaining:
+        if measure(remaining) <= max_width:
+            pieces.append(remaining)
+            break
+        seam_pos = _find_seam_break(remaining, max_width, measure)
+        if seam_pos is not None:
+            pieces.append(remaining[:seam_pos])
+            remaining = remaining[seam_pos:]
+        else:
+            # No seam fits — fall back to binary-search character break
+            lo, hi = 1, len(remaining)
+            best = 1
+            while lo <= hi:
+                mid = (lo + hi) // 2
+                candidate = remaining[:mid]
+                if measure(candidate) <= max_width:
+                    best = mid
+                    lo = mid + 1
+                else:
+                    hi = mid - 1
+            pieces.append(remaining[:best])
+            remaining = remaining[best:]
+    return pieces
+
+
+def wrap_measured_pieces(
+    pieces: list[WrapPiece],
+    max_width: float,
+) -> list[list[WrapPiece]]:
+    """Wrap already-measured pieces into lines."""
+    if not pieces:
+        return []
+
+    lines: list[list[WrapPiece]] = [[]]
+    current_width = 0.0
+    for piece in pieces:
+        candidate_width = piece.width
+        if lines[-1]:
+            candidate_width += piece.separator_width
+        if lines[-1] and current_width + candidate_width > max_width:
+            lines.append([piece])
+            current_width = piece.width
+        else:
+            lines[-1].append(piece)
+            current_width += candidate_width
+    return [line for line in lines if line]
+
+
+def pieces_to_text(pieces: list[WrapPiece]) -> str:
+    """Join measured pieces back into text."""
+    rendered: list[str] = []
+    for index, piece in enumerate(pieces):
+        if index > 0 and piece.separator:
+            rendered.append(piece.separator)
+        rendered.append(piece.text)
+    return "".join(rendered)
+
+
+def truncate_text_precise(
+    text: str,
+    max_width: float,
+    font_size: float,
+    measurer: FontMeasurer,
+    *,
+    ellipsis: bool,
+    normalize_whitespace: bool = True,
+) -> str:
+    """Clip or ellipsize text to fit within max_width using precise measurement."""
+    if normalize_whitespace:
+        text = re.sub(r"\s+", " ", text.strip())
+    if not text:
+        return ""
+
+    def measure(value: str) -> float:
+        return measure_text_precise(value, font_size, measurer)
+
+    if measure(text) <= max_width:
+        return text
+
+    suffix = "…" if ellipsis else ""
+    lo, hi = 0, len(text)
+    best = ""
+    while lo <= hi:
+        mid = (lo + hi) // 2
+        candidate = text[:mid].rstrip() + suffix
+        if measure(candidate) <= max_width:
+            best = candidate
+            lo = mid + 1
+        else:
+            hi = mid - 1
+    if best:
+        return best
+    return text[:1]
+
+
+def wrap_text_precise(
+    text: str,
+    max_width: float,
+    font_size: float,
+    measurer: FontMeasurer,
+    *,
+    max_lines: int | None = None,
+    ellipsis: bool = False,
+    normalize_whitespace: bool = True,
+) -> list[str]:
+    """Wrap plain text using precise measurement only."""
+    if normalize_whitespace:
+        text = re.sub(r"\s+", " ", text.strip())
+    if not text:
+        return []
+
+    def measure(value: str) -> float:
+        return measure_text_precise(value, font_size, measurer)
+
+    space_width = measure(" ")
+    pieces: list[WrapPiece] = []
+    words = text.split(" ")
+    for word_index, word in enumerate(words):
+        for chunk_index, chunk in enumerate(
+            split_token_precise(word, max_width, measure)
+        ):
+            separator = " " if word_index > 0 and chunk_index == 0 else ""
+            separator_width = space_width if separator else 0.0
+            pieces.append(
+                WrapPiece(
+                    text=chunk,
+                    width=measure(chunk),
+                    separator=separator,
+                    separator_width=separator_width,
+                )
+            )
+
+    lines = wrap_measured_pieces(pieces, max_width)
+    if max_lines is not None and len(lines) > max_lines:
+        tail: list[WrapPiece] = []
+        for line in lines[max_lines - 1 :]:
+            tail.extend(line)
+        rendered = [pieces_to_text(line) for line in lines[: max_lines - 1]]
+        rendered.append(
+            truncate_text_precise(
+                pieces_to_text(tail),
+                max_width,
+                font_size,
+                measurer,
+                ellipsis=ellipsis,
+                normalize_whitespace=False,
+            )
+        )
+        return rendered
+    return [pieces_to_text(line) for line in lines]
+
+
+def create_precise_wrapper(
+    max_width: float,
+    font_size: float,
+    measurer: FontMeasurer | None = None,
+) -> Callable[[str], list[str]]:
+    """
+    Create a text wrapper function that uses precise font measurement.
+
+    Args:
+        max_width: Maximum line width in pixels.
+        font_size: Font size in pixels.
+        measurer: FontMeasurer to use (auto-detects if None).
+
+    Returns:
+        A function that takes text and returns list of wrapped lines.
+    """
+    if measurer is None:
+        measurer = get_default_measurer()
+
+    if measurer is None or not measurer.is_available:
+        raise RuntimeError(
+            "FontMeasurer is required for precise wrapping; no heuristic fallback is allowed"
+        )
+
+    def wrap_precise(text: str) -> list[str]:
+        lines = wrap_text_precise(text, max_width, font_size, measurer)
+        return lines if lines else [""]
+
+    return wrap_precise
+
+
+def calibrate_heuristic(
+    measurer: Optional[FontMeasurer] = None,
+    font_size: float = 14.0,
+) -> Tuple[float, float]:
+    """
+    Calibrate heuristic character width ratios based on actual font measurement.
+
+    Returns adjusted ratios for use with the heuristic estimator.
+
+    Args:
+        measurer: FontMeasurer to use for calibration.
+        font_size: Font size for calibration.
+
+    Returns:
+        Tuple of (char_width_ratio, bold_char_width_ratio).
+    """
+    if measurer is None:
+        measurer = get_default_measurer()
+
+    if measurer is None or not measurer.is_available:
+        return (0.48, 0.52)
+
+    sample = "The quick brown fox jumps over the lazy dog. 0123456789"
+    actual_width = measurer.measure(sample, font_size)
+    ratio = actual_width / (font_size * len(sample))
+
+    return (ratio, ratio * 1.08)
+
+
+def get_font_cache_dir() -> str:
+    """
+    Get the directory for caching downloaded fonts.
+
+    Creates the directory if it doesn't exist.
+
+    Returns:
+        Path to the font cache directory.
+    """
+    # Use platform-appropriate cache directory
+    system = platform.system()
+
+    if system == "Darwin":
+        cache_base = os.path.expanduser("~/Library/Caches")
+    elif system == "Windows":
+        cache_base = os.environ.get("LOCALAPPDATA", os.path.expanduser("~"))
+    else:
+        cache_base = os.environ.get("XDG_CACHE_HOME", os.path.expanduser("~/.cache"))
+
+    cache_dir = os.path.join(cache_base, "mdsvg", "fonts")
+    os.makedirs(cache_dir, exist_ok=True)
+    return cache_dir
+
+
+def download_google_font(
+    font_name: str,
+    weight: int = 400,
+    cache_dir: Optional[str] = None,
+) -> str:
+    """
+    Download a font from Google Fonts.
+
+    Downloads the font file and caches it locally. Subsequent calls
+    return the cached file.
+
+    Args:
+        font_name: Name of the font (e.g., "Inter", "Roboto", "Open Sans").
+        weight: Font weight (100-900). Default 400 (regular).
+        cache_dir: Directory to cache fonts. Uses system cache if None.
+
+    Returns:
+        Path to the downloaded font file.
+
+    Raises:
+        RuntimeError: If download fails or font not found.
+
+    Example:
+        >>> font_path = download_google_font("Inter")
+        >>> measurer = FontMeasurer(font_path)
+        >>> measurer.measure("Hello", 14)
+
+        >>> # With specific weight
+        >>> bold_path = download_google_font("Inter", weight=700)
+    """
+    import re
+    import urllib.error
+    import urllib.request
+
+    if cache_dir is None:
+        cache_dir = get_font_cache_dir()
+
+    # Normalize font name for filename
+    safe_name = re.sub(r"[^a-zA-Z0-9]", "", font_name)
+    font_filename = f"{safe_name}-{weight}.ttf"
+    font_path = os.path.join(cache_dir, font_filename)
+
+    # Return cached font if exists
+    if os.path.exists(font_path):
+        return font_path
+
+    # Google Fonts CSS API URL
+    css_url = f"https://fonts.googleapis.com/css2?family={font_name.replace(' ', '+')}:wght@{weight}"
+
+    try:
+        # Fetch CSS to get the actual font URL
+        # Use a browser-like User-Agent to get TTF instead of WOFF2
+        request = urllib.request.Request(
+            css_url, headers={"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"}
+        )
+        with urllib.request.urlopen(request, timeout=30) as response:
+            css = response.read().decode("utf-8")
+
+        # Extract font URL from CSS
+        # Looking for: src: url(https://fonts.gstatic.com/...) format('truetype')
+        match = re.search(r"src:\s*url\(([^)]+\.ttf)\)", css)
+        if not match:
+            # Try woff2 and convert note
+            match = re.search(r"src:\s*url\(([^)]+)\)", css)
+            if match:
+                raise RuntimeError(
+                    f"Font '{font_name}' only available as WOFF2. "
+                    f"Download TTF manually from https://fonts.google.com/specimen/{font_name.replace(' ', '+')}"
+                )
+            raise RuntimeError(f"Could not find font URL for '{font_name}'")
+
+        font_url = match.group(1)
+
+        # Download the font file
+        with urllib.request.urlopen(font_url, timeout=60) as response:
+            font_data = response.read()
+
+        # Save to cache
+        with open(font_path, "wb") as f:
+            f.write(font_data)
+
+        return font_path
+
+    except urllib.error.HTTPError as e:
+        if e.code == 400:
+            raise RuntimeError(
+                f"Font '{font_name}' not found on Google Fonts. "
+                f"Check spelling at https://fonts.google.com"
+            ) from e
+        raise RuntimeError(f"Failed to download font: {e}") from e
+    except urllib.error.URLError as e:
+        raise RuntimeError(f"Network error downloading font: {e}") from e
+
+
+def list_cached_fonts(cache_dir: Optional[str] = None) -> List[str]:
+    """
+    List all fonts in the cache directory.
+
+    Args:
+        cache_dir: Cache directory to list. Uses system cache if None.
+
+    Returns:
+        List of cached font file paths.
+    """
+    if cache_dir is None:
+        cache_dir = get_font_cache_dir()
+
+    if not os.path.exists(cache_dir):
+        return []
+
+    return [
+        os.path.join(cache_dir, f)
+        for f in os.listdir(cache_dir)
+        if f.endswith((".ttf", ".otf", ".ttc"))
+    ]