texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/core/callouts.py

@@ -0,0 +1,99 @@
+"""Built-in callout definitions and helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+CalloutConfig = dict[str, Any]
+
+DEFAULT_CALLOUTS: dict[str, CalloutConfig] = {
+    "note": {"background_color": "ecf3ff", "border_color": "448aff", "icon": "📝"},
+    "abstract": {"background_color": "e5f7ff", "border_color": "00b0ff", "icon": "📄"},
+    "summary": {"background_color": "e5f8fb", "border_color": "00b8d4", "icon": "📋"},
+    "info": {"background_color": "e5f8fb", "border_color": "00b8d4", "icon": "ℹ"},  # noqa: RUF001
+    "tip": {"background_color": "e5f8f6", "border_color": "00bfa5", "icon": "⭐"},
+    "success": {"background_color": "e5f9ed", "border_color": "00c853", "icon": "✅"},
+    "question": {"background_color": "effce7", "border_color": "64dd17", "icon": "❓"},
+    "warning": {"background_color": "fff1d6", "border_color": "ffb200", "icon": "⚠"},
+    "caution": {"background_color": "fff8e1", "border_color": "ff9100", "icon": "🚧"},
+    "failure": {"background_color": "ffeded", "border_color": "ff5252", "icon": "❗"},
+    "danger": {"background_color": "ffe2e7", "border_color": "c62828", "icon": "🔥"},
+    "important": {"background_color": "ffe0f0", "border_color": "d81b60", "icon": "❗"},
+    "bug": {"background_color": "fee5ee", "border_color": "f50057", "icon": "🐞"},
+    "example": {"background_color": "f2edff", "border_color": "7c4dff", "icon": "🧪"},
+    "quote": {"background_color": "f5f5f5", "border_color": "9e9e9e", "icon": "✒️"},
+    "hint": {"background_color": "e5f8f6", "border_color": "00bfa5", "icon": "💡"},
+    "default": {"background_color": "f0f0f0", "border_color": "808080", "icon": "🎤"},
+}
+
+
+def _flatten_callouts(definitions: Mapping[str, Any]) -> dict[str, CalloutConfig]:
+    """Flatten nested callout definitions declared under arbitrary keys."""
+    flat: dict[str, CalloutConfig] = {}
+    for name, cfg in definitions.items():
+        if not isinstance(cfg, Mapping):
+            continue
+        if {"icon", "background_color", "border_color", "title_color"} & set(cfg):
+            flat[name] = dict(cfg)
+            continue
+        nested = _flatten_callouts(cfg)
+        for child_name, child_cfg in nested.items():
+            flat[child_name] = child_cfg
+    return flat
+
+
+def merge_callouts(
+    base: Mapping[str, CalloutConfig],
+    overrides: Mapping[str, Any] | None = None,
+) -> dict[str, CalloutConfig]:
+    """Merge callout definitions with user-provided overrides."""
+    combined: dict[str, CalloutConfig] = {
+        key: dict(value) for key, value in _flatten_callouts(base).items()
+    }
+    if not overrides:
+        return combined
+    for key, cfg in _flatten_callouts(overrides).items():
+        merged = dict(combined.get(key, {}))
+        for name, value in cfg.items():
+            if value is None:
+                continue
+            merged[name] = value
+        combined[key] = merged
+    return combined
+
+
+def _normalise_color(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, int):
+        return f"{value:06X}"
+    if isinstance(value, str):
+        stripped = value.strip().lstrip("#").lstrip("0x").lstrip("0X")
+        if not stripped:
+            return None
+        try:
+            parsed = int(stripped, 16)
+        except ValueError:
+            return None
+        return f"{parsed:06X}"
+    return None
+
+
+def normalise_callouts(definitions: Mapping[str, CalloutConfig]) -> dict[str, CalloutConfig]:
+    """Return a copy of callouts with hex color strings normalised."""
+    normalised: dict[str, CalloutConfig] = {}
+    for name, cfg in definitions.items():
+        if not isinstance(cfg, Mapping):
+            continue
+        updated: CalloutConfig = dict(cfg)
+        for key in ("background_color", "border_color", "title_color"):
+            colour = _normalise_color(updated.get(key))
+            if colour:
+                updated[key] = colour
+        normalised[name] = updated
+    return normalised
+
+
+__all__ = ["DEFAULT_CALLOUTS", "CalloutConfig", "merge_callouts"]

texsmith/core/config.py

@@ -0,0 +1,191 @@
+"""Configuration models used by the LaTeX renderer.
+
+CommonConfig
+
+`build_dir` (`Path | None`)
+: Base directory for LaTeX artifacts. Provide an absolute or project-relative
+  path to override the default export root that books inherit when they do not
+  specify one.
+
+`save_html` (`bool`)
+: Persist the intermediate HTML render next to the PDF to aid troubleshooting
+  before LaTeX compilation.
+
+`mermaid_config` (`Path | None`)
+: Path to a Mermaid configuration file. Point to a `.json` or `.mermaid`
+  document to customise diagram rendering.
+
+`project_dir` (`Path | None`)
+: MkDocs project root used to resolve relative paths when copying additional
+  assets.
+
+: BCP 47 language code forwarded to LaTeX for hyphenation, translations, and
+: metadata localisation.
+
+`legacy_latex_accents` (`bool`)
+: When `True`, escape accented characters, ligatures, and typographic punctuation
+  using legacy LaTeX macros. When `False`, keep Unicode glyphs compatible with
+  LuaLaTeX/XeLaTeX (default).
+
+`language` (`str | None`)
+: BCP 47 language code forwarded to LaTeX for hyphenation, translations, and
+  metadata localisation.
+
+CoverConfig
+
+`name` (`str`)
+: Identifier of the cover template to apply. The value must match a template
+  declared in the cover bundle.
+
+`color` (`str | None`)
+: Primary colour override applied by the cover template.
+
+`logo` (`str | None`)
+: Project-relative path to a logo asset displayed on the cover.
+
+BookConfig
+
+`root` (`str | None`)
+: Navigation entry treated as the starting point for the book. Use it when the
+  root differs from the first MkDocs page.
+
+`title` (`str | None`)
+: Title displayed on the cover and in output metadata. Falls back to `site_name`
+  when omitted.
+
+`subtitle` (`str | None`)
+: Optional subtitle appended to the cover and metadata.
+
+`author` (`str | None`)
+: Primary author string rendered in the book metadata.
+
+`year` (`int | None`)
+: Publication year to freeze in the output when `site_date` is not supplied.
+
+`email` (`str | None`)
+: Contact address printed in the credits.
+
+`folder` (`Path | None`)
+: Output directory for the rendered book. Defaults to a slug of the title when
+  not provided.
+
+`frontmatter` (`list[str]`)
+: MkDocs page titles moved before the main matter.
+
+`backmatter` (`list[str]`)
+: MkDocs page titles grouped into the appendices.
+
+`base_level` (`int`)
+: Heading offset applied to align section numbering with the template
+  expectations.
+
+`copy_files` (`dict[str, str]`)
+: Mapping of glob patterns to destination paths for copying additional assets
+  alongside the book.
+
+`index_is_foreword` (`bool`)
+: Treat the `index` page as a foreword, typically removing numbering.
+
+`drop_title_index` (`bool`)
+: Suppress the `index` page heading when it acts as a foreword.
+
+`cover` (`CoverConfig`)
+: Nested configuration controlling the book cover.
+
+LaTeXConfig
+
+`enabled` (`bool`)
+: Toggle LaTeX generation without discarding configuration.
+
+`books` (`list[BookConfig]`)
+: Collection of books to produce, inheriting defaults from `CommonConfig`.
+
+`clean_assets` (`bool`)
+: Remove stale assets from `build_dir` to avoid accumulating unused files.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from slugify import slugify
+
+
+class CommonConfig(BaseModel):
+    """Common configuration propagated to each book."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    build_dir: Path | None = None
+    save_html: bool = False
+    mermaid_config: Path | None = None
+    project_dir: Path | None = None
+    language: str | None = None
+    legacy_latex_accents: bool = False
+
+
+class CoverConfig(BaseModel):
+    """Metadata used to render book covers."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(default="circles", description="Cover template name")
+    color: str | None = Field(default="black", description="Primary color")
+    logo: str | None = Field(default=None, description="Logo path")
+
+
+class BookConfig(CommonConfig):
+    """Configuration for an individual book."""
+
+    root: str | None = None
+    title: str | None = None
+    subtitle: str | None = None
+    author: str | None = None
+    year: int | None = None
+    email: str | None = None
+    folder: Path | None = None
+    frontmatter: list[str] = Field(default_factory=list)
+    backmatter: list[str] = Field(default_factory=list)
+    base_level: int = -2
+    copy_files: dict[str, str] = Field(default_factory=dict)
+    index_is_foreword: bool = False
+    drop_title_index: bool = False
+    cover: CoverConfig = Field(default_factory=CoverConfig)
+
+    @model_validator(mode="after")
+    def set_folder(self) -> BookConfig:
+        """Populate the output folder from the book title when missing."""
+        if self.folder is None and self.title:
+            self.folder = Path(slugify(self.title, separator="-"))
+        return self
+
+
+class LaTeXConfig(CommonConfig):
+    """Configuration for LaTeX taken from ``mkdocs.yml``."""
+
+    enabled: bool = True
+    books: list[BookConfig] = Field(default_factory=lambda: [BookConfig()])
+    clean_assets: bool = True
+
+    @model_validator(mode="after")
+    def propagate(self) -> LaTeXConfig:
+        """Propagate common values to nested book configurations."""
+        to_propagate = (
+            "build_dir",
+            "mermaid_config",
+            "save_html",
+            "project_dir",
+            "language",
+        )
+        for book in self.books:
+            for key in to_propagate:
+                if getattr(book, key) is None:
+                    setattr(book, key, getattr(self, key))
+        return self
+
+    def add_extra(self, **extra_data: Any) -> None:
+        """Allow consumers to attach additional attributes at runtime."""
+        for key, value in extra_data.items():
+            object.__setattr__(self, key, value)

texsmith/core/context.py

@@ -0,0 +1,242 @@
+"""Rendering context primitives shared across the LaTeX pipeline."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable, MutableMapping
+from dataclasses import dataclass, field
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+import warnings
+
+from slugify import slugify
+
+from .exceptions import AssetMissingError
+
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from texsmith.adapters.latex.formatter import LaTeXFormatter
+
+    from .config import BookConfig
+    from .rules import RenderPhase
+
+
+@dataclass(slots=True)
+class DocumentState:
+    """In-memory state accumulated while rendering a document."""
+
+    abbreviations: dict[str, str] = field(default_factory=dict)
+    acronym_keys: dict[str, str] = field(default_factory=dict)
+    acronyms: dict[str, tuple[str, str]] = field(default_factory=dict)
+    glossary: dict[str, dict[str, Any]] = field(default_factory=dict)
+    snippets: dict[str, dict[str, Any]] = field(default_factory=dict)
+    solutions: list[dict[str, Any]] = field(default_factory=list)
+    headings: list[dict[str, Any]] = field(default_factory=list)
+    exercise_counter: int = 0
+    has_index_entries: bool = False
+    requires_shell_escape: bool = False
+    counters: dict[str, int] = field(default_factory=dict)
+    bibliography: dict[str, dict[str, Any]] = field(default_factory=dict)
+    citations: list[str] = field(default_factory=list)
+    _citation_index: set[str] = field(default_factory=set, init=False, repr=False)
+    footnotes: dict[str, str] = field(default_factory=dict)
+    index_entries: list[tuple[str, ...]] = field(default_factory=list)
+    pygments_styles: dict[str, str] = field(default_factory=dict)
+    script_usage: list[dict[str, Any]] = field(default_factory=list)
+    fallback_summary: list[dict[str, Any]] = field(default_factory=list)
+    callouts_used: bool = False
+
+    def remember_acronym(self, term: str, description: str) -> str:
+        """Register an acronym definition keyed by a normalised identifier."""
+        return self.remember_abbreviation(term=term, description=description)
+
+    def remember_abbreviation(self, term: str, description: str) -> str:
+        """Track abbreviation definitions while ensuring consistency."""
+        normalised_term = term.strip()
+        normalised_description = description.strip()
+        if not normalised_term or not normalised_description:
+            return ""
+
+        existing_description = self.abbreviations.get(normalised_term)
+        if existing_description is not None:
+            if existing_description != normalised_description:
+                warnings.warn(
+                    (
+                        f"Inconsistent acronym definition for '{normalised_term}': "
+                        f"'{existing_description}' vs '{normalised_description}'"
+                    ),
+                    stacklevel=2,
+                )
+            return self.acronym_keys.get(normalised_term, "")
+
+        key = self._generate_acronym_key(normalised_term)
+        self.abbreviations[normalised_term] = normalised_description
+        self.acronym_keys[normalised_term] = key
+        self.acronyms[key] = (normalised_term, normalised_description)
+        return key
+
+    def _generate_acronym_key(self, term: str) -> str:
+        """Produce a unique key suitable for the glossaries package."""
+        slug = slugify(term, separator="", lowercase=False)
+        if not slug:
+            slug = "acronym"
+        candidate = slug
+        suffix = 2
+        while candidate in self.acronyms:
+            candidate = f"{slug}{suffix}"
+            suffix += 1
+        return candidate
+
+    def remember_glossary(self, key: str, entry: dict[str, Any]) -> None:
+        """Record a glossary entry keyed by its identifier."""
+        self.glossary[key] = entry
+
+    def register_snippet(self, key: str, payload: dict[str, Any]) -> None:
+        """Cache snippet metadata to render later in the pipeline."""
+        self.snippets[key] = payload
+
+    def add_solution(self, solution: dict[str, Any]) -> None:
+        """Append a solution block encountered during parsing."""
+        self.solutions.append(solution)
+
+    def add_heading(self, *, level: int, text: str, ref: str | None = None) -> None:
+        """Track heading metadata to power table-of-contents generation."""
+        self.headings.append({"level": level, "text": text, "ref": ref})
+
+    def next_exercise(self) -> int:
+        """Increment and return the exercise counter."""
+        counter = self.next_counter("exercise")
+        self.exercise_counter = counter
+        return counter
+
+    def next_counter(self, key: str = "default") -> int:
+        """Increment and return the named counter."""
+        value = self.counters.get(key, 0) + 1
+        self.counters[key] = value
+        return value
+
+    def peek_counter(self, key: str = "default") -> int:
+        """Return the current value of the named counter without modifying it."""
+        return self.counters.get(key, 0)
+
+    def reset_counter(self, key: str) -> None:
+        """Clear the named counter if it has been tracked."""
+        self.counters.pop(key, None)
+
+    def record_citation(self, key: str) -> None:
+        """Track citation keys used throughout the document."""
+        if key in self._citation_index:
+            return
+        self._citation_index.add(key)
+        self.citations.append(key)
+
+
+@dataclass(slots=True)
+class AssetRegistry:
+    """Centralised registry for rendered assets."""
+
+    output_root: Path
+    assets_map: MutableMapping[str, Path] = field(default_factory=dict)
+    copy_assets: bool = True
+
+    def register(self, key: str, artefact: Path | str) -> Path:
+        """Register a generated artefact and return its resolved path."""
+        path = Path(artefact)
+        if not path.is_absolute():
+            path = (self.output_root / path).resolve() if self.copy_assets else Path(path)
+        self.assets_map[key] = path
+        return path
+
+    def lookup(self, key: str) -> Path | None:
+        """Return a previously registered artefact when available."""
+        stored = self.assets_map.get(key)
+        return Path(stored) if stored is not None else None
+
+    def get(self, key: str) -> Path:
+        """Retrieve a previously registered artefact."""
+        try:
+            return Path(self.assets_map[key])
+        except KeyError as exc:
+            raise AssetMissingError(f"Missing asset '{key}'") from exc
+
+    def items(self) -> Iterable[tuple[str, Path]]:
+        """Iterate over registered assets yielding key/path pairs."""
+        return ((k, Path(v)) for k, v in self.assets_map.items())
+
+    def latex_path(self, path: Path | str) -> str:
+        """Return a LaTeX-friendly path for an artefact."""
+        candidate = Path(path)
+        if not candidate.is_absolute():
+            return candidate.as_posix()
+
+        output_dir = self.output_root.parent
+        try:
+            reference = candidate.relative_to(output_dir)
+        except ValueError:
+            try:
+                reference = Path(os.path.relpath(candidate, output_dir))
+            except ValueError:
+                reference = candidate
+
+        return reference.as_posix()
+
+
+@dataclass
+class RenderContext:
+    """Shared context passed to every handler during rendering."""
+
+    config: BookConfig
+    formatter: LaTeXFormatter
+    document: Any
+    assets: AssetRegistry
+    state: DocumentState = field(default_factory=DocumentState)
+    runtime: dict[str, Any] = field(default_factory=dict)
+    phase: RenderPhase | None = None
+
+    _processed_nodes: defaultdict[int, set[int]] = field(
+        default_factory=lambda: defaultdict(set), init=False
+    )
+    _skip_children: defaultdict[int, set[int]] = field(
+        default_factory=lambda: defaultdict(set), init=False
+    )
+    _persistent_runtime: dict[str, Any] = field(default_factory=dict, init=False)
+
+    def enter_phase(self, phase: RenderPhase) -> None:
+        """Mark the current phase and reset transient runtime data."""
+        self.phase = phase
+        self.runtime = dict(self._persistent_runtime)
+        self._skip_children[phase.value].clear()
+
+    def attach_runtime(self, **runtime: Any) -> None:
+        """Attach ad-hoc data visible to handlers for the running phase."""
+        self._persistent_runtime.update(runtime)
+        self.runtime.update(runtime)
+
+    def mark_processed(self, node: Any, *, phase: RenderPhase | None = None) -> None:
+        """Flag a node as already transformed for the selected phase."""
+        label = phase or self.phase
+        if label is None:
+            return
+        self._processed_nodes[label.value].add(id(node))
+
+    def is_processed(self, node: Any, *, phase: RenderPhase | None = None) -> bool:
+        """Check whether a node has been processed in the given phase."""
+        label = phase or self.phase
+        if label is None:
+            return False
+        return id(node) in self._processed_nodes[label.value]
+
+    def suppress_children(self, node: Any, *, phase: RenderPhase | None = None) -> None:
+        """Prevent traversal of node children for the active phase."""
+        label = phase or self.phase
+        if label is None:
+            return
+        self._skip_children[label.value].add(id(node))
+
+    def should_skip_children(self, node: Any, *, phase: RenderPhase | None = None) -> bool:
+        """Check whether children should be skipped during traversal."""
+        label = phase or self.phase
+        if label is None:
+            return False
+        return id(node) in self._skip_children[label.value]

texsmith/core/conversion/__init__.py

@@ -0,0 +1,103 @@
+"""Public gateway into the low-level conversion engine."""
+
+from __future__ import annotations
+
+from texsmith.core.conversion_contexts import (
+    BinderContext,
+    DocumentContext,
+    GenerationStrategy,
+    SegmentContext,
+)
+from texsmith.core.templates import (
+    DEFAULT_TEMPLATE_LANGUAGE,
+    TemplateBinding,
+    TemplateRuntime,
+    build_template_overrides,
+    load_template_runtime,
+    resolve_template_language,
+)
+
+from .core import (
+    ConversionResult,
+    attempt_transformer_fallback,
+    convert_document,
+    copy_document_state,
+    ensure_fallback_converters,
+    render_with_fallback,
+)
+from .debug import (
+    ConversionError,
+    DiagnosticEmitter,
+    LoggingEmitter,
+    NullEmitter,
+    debug_enabled,
+    ensure_emitter,
+    format_rendering_error,
+    persist_debug_artifacts,
+    raise_conversion_error,
+    record_event,
+)
+from .inputs import (
+    DOCUMENT_SELECTOR_SENTINEL,
+    InputKind,
+    UnsupportedInputError,
+    build_document_context,
+    coerce_slot_selector,
+    extract_content,
+    extract_front_matter_bibliography,
+    extract_front_matter_slots,
+    parse_slot_mapping,
+)
+from .renderer import (
+    FragmentOverrideError,
+    TemplateFragment,
+    TemplateRenderer,
+    TemplateRendererResult,
+)
+from .templates import build_binder_context, extract_slot_fragments, heading_level_for
+
+
+__all__ = [
+    "DEFAULT_TEMPLATE_LANGUAGE",
+    "DOCUMENT_SELECTOR_SENTINEL",
+    "BinderContext",
+    "ConversionError",
+    "ConversionResult",
+    "DiagnosticEmitter",
+    "DocumentContext",
+    "FragmentOverrideError",
+    "GenerationStrategy",
+    "InputKind",
+    "LoggingEmitter",
+    "NullEmitter",
+    "SegmentContext",
+    "TemplateBinding",
+    "TemplateFragment",
+    "TemplateRenderer",
+    "TemplateRendererResult",
+    "TemplateRuntime",
+    "UnsupportedInputError",
+    "attempt_transformer_fallback",
+    "build_binder_context",
+    "build_document_context",
+    "build_template_overrides",
+    "coerce_slot_selector",
+    "convert_document",
+    "copy_document_state",
+    "debug_enabled",
+    "ensure_emitter",
+    "ensure_fallback_converters",
+    "extract_content",
+    "extract_front_matter_bibliography",
+    "extract_front_matter_slots",
+    "extract_slot_fragments",
+    "format_rendering_error",
+    "heading_level_for",
+    "load_template_runtime",
+    "parse_slot_mapping",
+    "persist_debug_artifacts",
+    "raise_conversion_error",
+    "record_event",
+    "render_with_fallback",
+    "resolve_template_language",
+]