texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/core/conversion_contexts.py

@@ -0,0 +1,95 @@
+"""Context objects used during document conversion."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .config import BookConfig
+from .templates import TemplateBinding
+
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from .bibliography.collection import BibliographyCollection
+
+
+@dataclass(slots=True)
+class AssetMapping:
+    """Describe how a source asset should be persisted for LaTeX generation."""
+
+    source: Path
+    target: Path
+    kind: str | None = None
+
+
+@dataclass(slots=True)
+class GenerationStrategy:
+    """Rendering strategy toggles shared across conversion workflows."""
+
+    copy_assets: bool = True
+    convert_assets: bool = False
+    hash_assets: bool = False
+    prefer_inputs: bool = False
+    persist_manifest: bool = False
+
+
+@dataclass(slots=True)
+class SegmentContext:
+    """Represent a fragment destined for insertion into a template slot."""
+
+    name: str
+    html: str
+    base_level: int
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+    bibliography: Mapping[str, Any] = field(default_factory=dict)
+    assets: list[AssetMapping] = field(default_factory=list)
+    destination: Path | None = None
+
+
+@dataclass(slots=True)
+class DocumentContext:
+    """Document-level context produced before rendering."""
+
+    name: str
+    source_path: Path
+    html: str
+    base_level: int
+    numbered: bool
+    drop_title: bool
+    title_from_heading: bool
+    extracted_title: str | None = None
+    front_matter: dict[str, Any] = field(default_factory=dict)
+    slot_requests: dict[str, str] = field(default_factory=dict)
+    slot_inclusions: set[str] = field(default_factory=set)
+    language: str | None = None
+    bibliography: dict[str, Any] = field(default_factory=dict)
+    assets: list[AssetMapping] = field(default_factory=list)
+    segments: dict[str, list[SegmentContext]] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class BinderContext:
+    """Binder-level context describing template binding and global state."""
+
+    output_dir: Path
+    config: BookConfig
+    strategy: GenerationStrategy
+    language: str
+    slot_requests: dict[str, str]
+    template_overrides: dict[str, Any]
+    bibliography_map: dict[str, dict[str, Any]] = field(default_factory=dict)
+    bibliography_collection: BibliographyCollection | None = None
+    template_binding: TemplateBinding | None = None
+    documents: list[DocumentContext] = field(default_factory=list)
+    bound_segments: dict[str, list[SegmentContext]] = field(default_factory=dict)
+
+
+__all__ = [
+    "AssetMapping",
+    "BinderContext",
+    "DocumentContext",
+    "GenerationStrategy",
+    "SegmentContext",
+]

texsmith/core/diagnostics.py

@@ -0,0 +1,118 @@
+"""Diagnostic abstractions shared across the conversion pipeline."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import logging
+from typing import Any, Protocol, runtime_checkable
+
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class DiagnosticEmitter(Protocol):
+    """Interface used to surface warnings, errors, and structured events."""
+
+    debug_enabled: bool
+
+    def warning(self, message: str, exc: BaseException | None = None) -> None: ...
+
+    def error(self, message: str, exc: BaseException | None = None) -> None: ...
+
+    def event(self, name: str, payload: Mapping[str, Any]) -> None: ...
+
+
+class NullEmitter:
+    """Emitter that ignores every diagnostic."""
+
+    debug_enabled: bool = False
+
+    def warning(self, message: str, exc: BaseException | None = None) -> None:
+        return
+
+    def error(self, message: str, exc: BaseException | None = None) -> None:
+        return
+
+    def event(self, name: str, payload: Mapping[str, Any]) -> None:
+        return
+
+
+class LoggingEmitter:
+    """Emitter that forwards diagnostics to the standard logging module."""
+
+    def __init__(
+        self, *, logger_obj: logging.Logger | None = None, debug_enabled: bool = False
+    ) -> None:
+        self._logger = logger_obj or logger
+        self.debug_enabled = debug_enabled
+
+    def warning(self, message: str, exc: BaseException | None = None) -> None:
+        if exc is not None:
+            self._logger.warning(message, exc_info=exc)
+        else:
+            self._logger.warning(message)
+
+    def error(self, message: str, exc: BaseException | None = None) -> None:
+        if exc is not None:
+            self._logger.error(message, exc_info=exc)
+        else:
+            self._logger.error(message)
+
+    def event(self, name: str, payload: Mapping[str, Any]) -> None:
+        message = format_event_message(name, payload)
+        if message:
+            self._logger.info(message)
+            return
+        try:
+            self._logger.debug("diagnostic event %s: %s", name, dict(payload))
+        except Exception:  # pragma: no cover - defensive
+            self._logger.debug("failed to log diagnostic event %s", name, exc_info=True)
+
+
+def format_event_message(name: str, payload: Mapping[str, Any]) -> str | None:
+    """Return a human-friendly summary for selected diagnostic events."""
+    try:
+        data = dict(payload)
+    except Exception:  # pragma: no cover - defensive
+        data = {}
+
+    if name == "asset_fetch":
+        url = data.get("url") or "<unknown>"
+        convert = data.get("convert")
+        suffix_hint = data.get("suffix_hint")
+        details: list[str] = []
+        if convert:
+            details.append("convert")
+        if suffix_hint:
+            details.append(f"suffix={suffix_hint}")
+        suffix = f" ({', '.join(details)})" if details else ""
+        return f"Fetching: {url}{suffix}"
+
+    if name == "asset_fetch_cached":
+        url = data.get("url") or "<unknown>"
+        reason = data.get("reason") or "cache"
+        return f"Reusing cached remote image: {url} ({reason})"
+
+    if name == "doi_fetch":
+        doi_value = data.get("value") or data.get("doi") or "<unknown>"
+        key = data.get("key") or "<unknown>"
+        mode = data.get("mode")
+        source = data.get("source") or data.get("resolved_source")
+        details: list[str] = []
+        if mode:
+            details.append(str(mode))
+        if source:
+            details.append(str(source))
+        suffix = f" ({', '.join(details)})" if details else ""
+        return f"Resolved DOI {doi_value} for entry '{key}'{suffix}"
+
+    return None
+
+
+__all__ = [
+    "DiagnosticEmitter",
+    "LoggingEmitter",
+    "NullEmitter",
+    "format_event_message",
+]

texsmith/core/exceptions.py

@@ -0,0 +1,41 @@
+"""Custom exception hierarchy for the LaTeX rendering pipeline."""
+
+from __future__ import annotations
+
+
+class LatexRenderingError(RuntimeError):
+    """Base exception for LaTeX rendering failures."""
+
+
+class AssetMissingError(LatexRenderingError):
+    """Raised when an expected asset cannot be located or generated."""
+
+
+class TransformerExecutionError(LatexRenderingError):
+    """Raised when an external converter fails to execute properly."""
+
+
+class InvalidNodeError(LatexRenderingError):
+    """Raised when a handler receives an unexpected DOM node shape."""
+
+
+def exception_messages(exc: BaseException) -> list[str]:
+    """Return the collected message chain for an exception and its causes."""
+    messages: list[str] = []
+    visited: set[int] = set()
+    current: BaseException | None = exc
+    while current is not None and id(current) not in visited:
+        visited.add(id(current))
+        text = str(current).strip()
+        if text:
+            first_line = text.splitlines()[0].strip()
+            if first_line:
+                messages.append(first_line)
+        current = current.__cause__ or current.__context__
+    return messages
+
+
+def exception_hint(exc: BaseException) -> str | None:
+    """Return the most specific message available for an exception chain."""
+    messages = exception_messages(exc)
+    return messages[-1] if messages else None

texsmith/core/fonts/__init__.py

@@ -0,0 +1,3 @@
+"""Font utilities used by TexSmith's core rendering pipeline."""
+
+__all__ = []