texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/extensions/texlogos/markdown.py

@@ -0,0 +1,236 @@
+"""Markdown extension that replaces TeX logo keywords with semantic HTML."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Mapping
+import re
+import xml.etree.ElementTree as ElementTree
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.treeprocessors import Treeprocessor
+
+from .specs import LogoSpec, alias_mapping
+
+
+class _TexLogosTreeprocessor(Treeprocessor):
+    """Replace textual tokens with spans that carry TeX logo metadata."""
+
+    def __init__(self, md: Markdown) -> None:
+        super().__init__(md)
+        self._alias_map = alias_mapping()
+        self._pattern = _compile_pattern(self._alias_map)
+
+    def run(self, root: ElementTree.Element) -> None:  # type: ignore[override]
+        self._process_element(root)
+
+    # -- recursive traversal -------------------------------------------------
+    def _process_element(self, element: ElementTree.Element) -> None:
+        if self._is_logo_container(element):
+            return
+
+        if self._is_code_element(element):
+            for child in list(element):
+                if child.tail:
+                    self._replace_tail(element, child)
+            return
+
+        self._replace_text_node(element)
+
+        for child in list(element):
+            self._process_element(child)
+            if child.tail:
+                self._replace_tail(element, child)
+
+    def _replace_text_node(self, element: ElementTree.Element) -> None:
+        text = element.text
+        if not text:
+            return
+
+        segments = list(self._split_segments(text))
+        if not any(isinstance(part, LogoSpec) for part in segments):
+            return
+
+        element.text = ""
+        insert_pos = 0
+        last_fragment: ElementTree.Element | None = None
+        for part in segments:
+            if isinstance(part, str):
+                if last_fragment is None:
+                    element.text += part
+                else:
+                    last_fragment.tail = (last_fragment.tail or "") + part
+                continue
+
+            fragment = self._build_fragment(part)
+            element.insert(insert_pos, fragment)
+            insert_pos += 1
+            last_fragment = fragment
+
+    def _replace_tail(self, parent: ElementTree.Element, child: ElementTree.Element) -> None:
+        tail = child.tail
+        if not tail:
+            return
+
+        segments = list(self._split_segments(tail))
+        if not any(isinstance(part, LogoSpec) for part in segments):
+            return
+
+        child.tail = ""
+        insert_pos = list(parent).index(child) + 1
+        last_fragment: ElementTree.Element | None = None
+        for part in segments:
+            if isinstance(part, str):
+                if last_fragment is None:
+                    child.tail += part
+                else:
+                    last_fragment.tail = (last_fragment.tail or "") + part
+                continue
+
+            fragment = self._build_fragment(part)
+            parent.insert(insert_pos, fragment)
+            insert_pos += 1
+            last_fragment = fragment
+
+    # -- helpers -------------------------------------------------------------
+    def _split_segments(self, value: str) -> Iterator[str | LogoSpec]:
+        cursor = 0
+        for match in self._pattern.finditer(value):
+            start, end = match.span()
+            if start > cursor:
+                yield value[cursor:start]
+            alias = match.group(0)
+            spec = self._alias_map.get(alias)
+            if (start > 0 and value[start - 1].isalnum()) or (
+                end < len(value) and value[end].isalnum()
+            ):
+                yield value[start:end]
+            elif spec:
+                yield spec
+            else:  # pragma: no cover - defensive
+                yield alias
+            cursor = end
+        if cursor < len(value):
+            yield value[cursor:]
+
+    def _build_fragment(self, spec: LogoSpec) -> ElementTree.Element:
+        outer = ElementTree.Element(
+            "span",
+            {
+                "class": f"tex-logo tex-{spec.slug}",
+                "data-tex-command": spec.command,
+                "data-tex-logo": spec.slug,
+                "title": spec.description,
+                "role": "img",
+                "aria-label": spec.display,
+                "style": _BASE_STYLE,
+            },
+        )
+
+        builder = _HTML_BUILDERS.get(spec.slug, _build_plain_logo)
+        builder(outer, spec)
+        return outer
+
+    def _is_code_element(self, element: ElementTree.Element) -> bool:
+        tag = element.tag
+        if isinstance(tag, str):
+            tag = tag.lower()
+        return tag in {"code", "pre"}
+
+    def _is_logo_container(self, element: ElementTree.Element) -> bool:
+        classes = element.get("class", "")
+        if not isinstance(classes, str):
+            return False
+        return "tex-logo" in classes.split()
+
+
+_BASE_STYLE = "font-family: 'Times New Roman', serif;"
+
+
+def _build_plain_logo(container: ElementTree.Element, spec: LogoSpec) -> None:
+    container.text = spec.display
+
+
+def _build_tex_logo(container: ElementTree.Element, _: LogoSpec, *, prefix: str = "") -> None:
+    container.text = f"{prefix}T"
+    lowered_e = ElementTree.SubElement(
+        container,
+        "span",
+        {"style": "position: relative; top: 0.2em; font-size: 0.8em;"},
+    )
+    lowered_e.text = "E"
+    lowered_e.tail = "X"
+
+
+def _build_latex_logo(
+    container: ElementTree.Element, _: LogoSpec, *, prefix: str = ""
+) -> ElementTree.Element:
+    container.text = f"{prefix}L"
+    raised_a = ElementTree.SubElement(
+        container,
+        "span",
+        {"style": "position: relative; top: -0.3em; font-size: 0.8em;"},
+    )
+    raised_a.text = "A"
+    raised_a.tail = "T"
+
+    lowered_e = ElementTree.SubElement(
+        container,
+        "span",
+        {"style": "position: relative; top: 0.2em; font-size: 0.8em;"},
+    )
+    lowered_e.text = "E"
+    lowered_e.tail = "X"
+    return lowered_e
+
+
+def _build_latex(container: ElementTree.Element, spec: LogoSpec) -> None:
+    _build_latex_logo(container, spec)
+
+
+def _build_latex2e(container: ElementTree.Element, spec: LogoSpec) -> None:
+    lowered_e = _build_latex_logo(container, spec)
+
+    superscript_two = ElementTree.SubElement(
+        container,
+        "span",
+        {"style": "position: relative; top: -0.35em; font-size: 0.65em; margin-left: 0.05em;"},
+    )
+    superscript_two.text = "2"
+
+    epsilon = ElementTree.SubElement(
+        container,
+        "span",
+        {
+            "style": "position: relative; top: -0.2em; font-size: 0.7em; font-style: italic; margin-left: 0.02em;"
+        },
+    )
+    epsilon.text = "\u03b5"
+    lowered_e.tail = "X"
+
+
+_HTML_BUILDERS: Mapping[str, Callable[[ElementTree.Element, LogoSpec], None]] = {
+    "tex": _build_tex_logo,
+    "latex": _build_latex,
+    "latex2e": _build_latex2e,
+}
+
+
+class TexLogosExtension(Extension):
+    """Register the TeX logo tree-processor."""
+
+    def extendMarkdown(self, md: Markdown) -> None:  # type: ignore[override]  # noqa: N802
+        md.treeprocessors.register(_TexLogosTreeprocessor(md), "texsmith_texlogos", priority=14)
+
+
+def makeExtension(**_: object) -> TexLogosExtension:  # pragma: no cover - API hook  # noqa: N802
+    return TexLogosExtension()
+
+
+def _compile_pattern(mapping: Mapping[str, LogoSpec]) -> re.Pattern[str]:
+    aliases = sorted(mapping.keys(), key=len, reverse=True)
+    pattern = "|".join(re.escape(alias) for alias in aliases)
+    return re.compile(pattern)
+
+
+__all__ = ["TexLogosExtension", "makeExtension"]

texsmith/extensions/texlogos/renderer.py

@@ -0,0 +1,81 @@
+"""Renderer hooks to convert TeX logo spans into LaTeX macros."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from bs4 import NavigableString, Tag
+
+from texsmith.adapters.handlers._helpers import gather_classes, mark_processed
+from texsmith.core.context import RenderContext
+from texsmith.core.rules import RenderPhase, renders
+
+from .specs import LogoSpec, alias_mapping, iter_specs
+
+
+_COMMAND_LOOKUP: Mapping[str, LogoSpec] = {spec.command: spec for spec in iter_specs()}
+_SLUG_LOOKUP: Mapping[str, LogoSpec] = {spec.slug: spec for spec in iter_specs()}
+_ALIAS_LOOKUP = alias_mapping()
+_REGISTER_ATTR = "_texsmith_texlogos_registered"
+
+
+@renders(
+    "span",
+    phase=RenderPhase.INLINE,
+    priority=32,
+    name="texsmith_tex_logo",
+    nestable=False,
+    auto_mark=False,
+)
+def render_tex_logo_span(element: Tag, context: RenderContext) -> None:
+    """Process ``<span class="tex-logo">`` placeholders."""
+
+    classes = gather_classes(element.get("class"))
+    if "tex-logo" not in classes:
+        return
+
+    spec = _deduce_spec(element)
+    if spec is None:
+        return
+
+    latex = mark_processed(NavigableString(spec.command))
+    context.mark_processed(element)
+    context.suppress_children(element)
+    element.replace_with(latex)
+
+
+def _deduce_spec(element: Tag) -> LogoSpec | None:
+    command = element.get("data-tex-command")
+    if command:
+        spec = _COMMAND_LOOKUP.get(command)
+        if spec:
+            return spec
+
+    slug = element.get("data-tex-logo")
+    if slug:
+        spec = _SLUG_LOOKUP.get(slug)
+        if spec:
+            return spec
+
+    text = element.get_text(strip=True)
+    if text:
+        return _ALIAS_LOOKUP.get(text)
+
+    return None
+
+
+def register(renderer: object) -> None:
+    """Convenience helper to register all logo handlers on a renderer."""
+
+    register_callable = getattr(renderer, "register", None)
+    if callable(register_callable):
+        if getattr(renderer, _REGISTER_ATTR, False):
+            return
+        register_callable(render_tex_logo_span)
+        setattr(renderer, _REGISTER_ATTR, True)
+        return
+
+    raise TypeError("Renderer object does not expose a 'register' method")
+
+
+__all__ = ["register", "render_tex_logo_span"]

texsmith/extensions/texlogos/specs.py

@@ -0,0 +1,66 @@
+"""Shared specifications for the TeX logo renderer and Markdown extension."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class LogoSpec:
+    """Describe how to recognise and render a TeX logo token."""
+
+    command: str
+    display: str
+    description: str
+    slug: str
+    aliases: tuple[str, ...]
+
+    def match_values(self) -> tuple[str, ...]:
+        """Get the strings that should trigger this logo."""
+
+        return self.aliases or (self.display,)
+
+
+_SPECS: tuple[LogoSpec, ...] = (
+    LogoSpec(
+        command=r"\TeX{}",
+        display="TeX",
+        description="Le moteur de base cree par Donald Knuth",
+        slug="tex",
+        aliases=("TeX",),
+    ),
+    LogoSpec(
+        command=r"\LaTeX{}",
+        display="LaTeX",
+        description="Le systeme de composition base sur TeX",
+        slug="latex",
+        aliases=("LaTeX",),
+    ),
+    LogoSpec(
+        command=r"\LaTeXe{}",
+        display="LaTeX2\u03b5",
+        description="La version moderne de LaTeX",
+        slug="latex2e",
+        aliases=("LaTeX2e", "LaTeX2\u03b5", "LaTeXe"),
+    ),
+)
+
+
+def iter_specs() -> Iterable[LogoSpec]:
+    """Iterate over the known logo specifications."""
+
+    return _SPECS
+
+
+def alias_mapping() -> Mapping[str, LogoSpec]:
+    """Build a lookup from alias to spec."""
+
+    mapping: dict[str, LogoSpec] = {}
+    for spec in _SPECS:
+        for alias in spec.match_values():
+            mapping[alias] = spec
+    return mapping
+
+
+__all__ = ["LogoSpec", "alias_mapping", "iter_specs"]

texsmith/fonts/__init__.py

@@ -0,0 +1,57 @@
+"""Font toolchain façade used to prepare reliable LaTeX fallbacks.
+
+Architecture
+: `FontCache` pins downloads of Noto metadata, ucharclasses tables, and computed
+  fallback indexes to a single cache root so repeated renders never thrash the
+  network. The cache also carries signatures so on-disk data can be trusted.
+: Builders such as `NotoCoverageBuilder` and `UCharClassesBuilder` transform
+  upstream datasets into structured coverage ranges. `FallbackBuilder` consumes
+  that data to calculate the minimal set of fonts required for arbitrary text.
+: `FallbackManager` wraps the pipeline with memoisation, exposing simple lookup
+  helpers while persisting results via `FallbackRepository` for reuse.
+: Convenience generators (``generate_fallback_entries``/``generate_noto_metadata``/
+  ``generate_ucharclasses_data``) orchestrate the above pieces and return
+  ready-to-embed artifacts for renderers and CLI tooling.
+
+Goal
+: Provide deterministic, cache-aware font selection so TeXSmith can emit
+  LaTeX that compiles on machines without full Unicode font coverage while
+  keeping downloads minimal and reproducible.
+"""
+
+from texsmith.fonts.cache import FontCache
+from texsmith.fonts.coverage import NotoCoverage, NotoCoverageBuilder
+from texsmith.fonts.fallback import (
+    FallbackBuilder,
+    FallbackEntry,
+    FallbackIndex,
+    FallbackLookup,
+    FallbackRepository,
+)
+from texsmith.fonts.logging import FontPipelineLogger
+from texsmith.fonts.pipeline import (
+    FallbackManager,
+    generate_fallback_entries,
+    generate_noto_metadata,
+    generate_ucharclasses_data,
+)
+from texsmith.fonts.ucharclasses import UCharClass, UCharClassesBuilder
+
+
+__all__ = [
+    "FallbackBuilder",
+    "FallbackEntry",
+    "FallbackIndex",
+    "FallbackLookup",
+    "FallbackManager",
+    "FallbackRepository",
+    "FontCache",
+    "FontPipelineLogger",
+    "NotoCoverage",
+    "NotoCoverageBuilder",
+    "UCharClass",
+    "UCharClassesBuilder",
+    "generate_fallback_entries",
+    "generate_noto_metadata",
+    "generate_ucharclasses_data",
+]

texsmith/fonts/cache.py

@@ -0,0 +1,46 @@
+"""Lightweight cache utilities for font-related assets."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+import tempfile
+
+from texsmith.core.user_dir import get_user_dir
+
+
+DEFAULT_ROOT = get_user_dir().data_dir("fonts", create=False)
+
+
+class FontCache:
+    """Resolve persistent and temporary paths for font tooling.
+
+    The cache defaults to ``~/.texsmith/fonts`` so that repeated runs of the
+    toolchain can reuse downloaded assets (CTAN packages, lookup indexes, ...).
+    """
+
+    def __init__(self, root: Path | None = None) -> None:
+        self.root = root or get_user_dir().data_dir("fonts", create=False)
+
+    def ensure(self) -> Path:
+        """Ensure the cache root exists and return it."""
+        self.root.mkdir(parents=True, exist_ok=True)
+        return self.root
+
+    def path(self, *parts: str | Path) -> Path:
+        """Return a path under the cache root, creating parent directories."""
+        base = self.ensure()
+        target = base.joinpath(*parts)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        return target
+
+    @contextmanager
+    def tempdir(self) -> Iterator[Path]:
+        """Provide a temporary directory inside the cache root."""
+        self.ensure()
+        with tempfile.TemporaryDirectory(dir=self.root) as tmp:
+            yield Path(tmp)
+
+
+__all__ = ["DEFAULT_ROOT", "FontCache"]

texsmith/fonts/constants.py

@@ -0,0 +1,60 @@
+"""Shared constants and helpers for Noto font handling."""
+
+from __future__ import annotations
+
+
+_STYLE_SUFFIXES = {
+    "regular": "Regular",
+    "italic": "Italic",
+    "bold": "Bold",
+    "bolditalic": "BoldItalic",
+}
+
+_CJK_PATHS = {
+    "jp": "Sans/OTF/Japanese/",
+    "kr": "Sans/OTF/Korean/",
+    "sc": "Sans/OTF/SimplifiedChinese/",
+    "tc": "Sans/OTF/TraditionalChinese/",
+    "hk": "Sans/OTF/TraditionalChineseHK/",
+}
+
+CJK_ALIASES = {
+    "NotoSansJP": ("NotoSansCJKjp", _CJK_PATHS["jp"]),
+    "NotoSansKR": ("NotoSansCJKkr", _CJK_PATHS["kr"]),
+    "NotoSansSC": ("NotoSansCJKsc", _CJK_PATHS["sc"]),
+    "NotoSansTC": ("NotoSansCJKtc", _CJK_PATHS["tc"]),
+    "NotoSansHK": ("NotoSansCJKhk", _CJK_PATHS["hk"]),
+}
+
+
+def style_suffix(style: str) -> str:
+    """Return the canonical filename suffix for a Noto style."""
+    return _STYLE_SUFFIXES.get(style.lower(), style.title())
+
+
+def filename_base(filename: str) -> str:
+    """Return the base name of a Noto font file, stripping style suffixes."""
+    return filename.split("-")[0]
+
+
+def guess_cjk_path(filename: str) -> str:
+    """Guess the CJK subpath for a Noto CJK font filename."""
+    base = filename_base(filename)
+    if base in CJK_ALIASES:
+        return CJK_ALIASES[base][1]
+
+    lowered = base.lower()
+    if "cjkjp" in lowered:
+        return _CJK_PATHS["jp"]
+    if "cjkkr" in lowered:
+        return _CJK_PATHS["kr"]
+    if "cjksc" in lowered:
+        return _CJK_PATHS["sc"]
+    if "cjktc" in lowered:
+        return _CJK_PATHS["tc"]
+    if "cjkhk" in lowered:
+        return _CJK_PATHS["hk"]
+    return ""
+
+
+__all__ = ["CJK_ALIASES", "filename_base", "guess_cjk_path", "style_suffix"]