texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/adapters/transformers/utils.py

@@ -0,0 +1,59 @@
+"""Utility helpers shared across transformer strategies."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from texsmith.core.exceptions import TransformerExecutionError
+
+
+def points_to_mm(points: float) -> float:
+    """Convert PDF points to millimetres."""
+    return points * 25.4 / 72
+
+
+def normalise_pdf_version(pdf_path: Path, *, target_version: str = "1.5") -> None:
+    """Re-write a PDF so its header advertises the requested version."""
+    try:
+        import pypdf  # type: ignore[import]
+    except ImportError as exc:  # pragma: no cover - optional dependency
+        msg = "pypdf is required to normalise PDF artefacts."
+        raise TransformerExecutionError(msg) from exc
+
+    try:
+        reader = pypdf.PdfReader(str(pdf_path))
+    except Exception as exc:  # pragma: no cover - defensive
+        msg = f"Failed to read generated PDF '{pdf_path}': {exc}"
+        raise TransformerExecutionError(msg) from exc
+
+    # Skip rewriting when already on the desired version.
+    header = getattr(reader, "pdf_header", b"")
+    if isinstance(header, bytes):
+        header_text = header.decode("latin-1", "ignore")
+        if header_text.startswith("%PDF-"):
+            current_version = header_text[5:].strip()
+            if current_version == target_version:
+                return
+
+    writer = pypdf.PdfWriter()
+    for page in reader.pages:
+        writer.add_page(page)
+    writer.pdf_header = f"%PDF-{target_version}\n"
+
+    metadata = reader.metadata or {}
+    filtered_metadata = {k: v for k, v in metadata.items() if isinstance(v, str)}
+    if filtered_metadata:
+        writer.add_metadata(filtered_metadata)
+
+    tmp_path = pdf_path.with_suffix(pdf_path.suffix + ".tmp")
+    try:
+        with tmp_path.open("wb") as handle:
+            writer.write(handle)
+    except Exception as exc:  # pragma: no cover - defensive
+        msg = f"Failed to rewrite PDF '{pdf_path}' to version {target_version}: {exc}"
+        raise TransformerExecutionError(msg) from exc
+
+    tmp_path.replace(pdf_path)
+
+
+__all__ = ["normalise_pdf_version", "points_to_mm"]

texsmith/api/__init__.py

@@ -0,0 +1,80 @@
+"""Facade aggregating the high-level TeXSmith authoring experience.
+
+Architecture
+: `Document` and `DocumentRenderOptions` model the source inputs that travel
+  through the conversion pipeline. They encapsulate content, front matter, and
+  slot selections independently of the engine internals.
+: `convert_documents` together with `RenderSettings` coordinates the conversion
+  engine and wraps results in `ConversionBundle` instances exposing convenience
+  helpers such as `combined_output`.
+: `TemplateSession` and related classes manage higher-level template workflows,
+  combining multiple converted fragments into coherent LaTeX projects.
+
+Implementation Rationale
+: Providing downstream code with a single import location helps preserve
+  backward compatibility. Internal modules can evolve while this facade offers a
+  declarative list of supported entry points.
+: Concentrating documentation and doctest coverage here guides users toward the
+  intended composition patterns when embedding TeXSmith.
+
+Usage Example
+:
+    >>> from pathlib import Path
+    >>> from tempfile import TemporaryDirectory
+    >>> from texsmith.api import Document, convert_documents
+    >>> with TemporaryDirectory() as tmpdir:
+    ...     path = Path(tmpdir) / "example.md"
+    ...     _ = path.write_text("# Demo\\nHello")
+    ...     bundle = convert_documents([Document.from_markdown(path)])
+    ...     [fragment.stem for fragment in bundle.fragments]
+    ['example']
+"""
+
+from __future__ import annotations
+
+from texsmith.core.user_dir import (
+    TexsmithUserDir,
+    configure_user_dir,
+    get_user_dir,
+    user_dir_context,
+)
+
+from .document import Document, DocumentRenderOptions, TitleStrategy
+from .pipeline import ConversionBundle, LaTeXFragment, RenderSettings, convert_documents
+from .service import (
+    ConversionRequest,
+    ConversionResponse,
+    ConversionService,
+    SlotAssignment,
+    classify_input_source,
+)
+from .templates import (
+    TemplateOptions,
+    TemplateRenderResult,
+    TemplateSession,
+    get_template,
+)
+
+
+__all__ = [
+    "ConversionBundle",
+    "ConversionRequest",
+    "ConversionResponse",
+    "ConversionService",
+    "Document",
+    "DocumentRenderOptions",
+    "LaTeXFragment",
+    "RenderSettings",
+    "SlotAssignment",
+    "TemplateOptions",
+    "TemplateRenderResult",
+    "TemplateSession",
+    "TexsmithUserDir",
+    "TitleStrategy",
+    "classify_input_source",
+    "configure_user_dir",
+    "convert_documents",
+    "get_template",
+    "get_user_dir",
+    "user_dir_context",
+]

texsmith/api/_utils.py

@@ -0,0 +1,56 @@
+"""Supporting utilities shared by the high-level API modules.
+
+Architecture
+: `build_unique_stem_map` receives the original source paths used by the API and
+  produces collision-free stem identifiers. Conversion pipelines rely on these
+  stems to generate fragment file names and manifest entries without leaking
+  implementation details from the caller.
+
+Implementation Rationale
+: The conversion pipeline needs deterministic names to produce predictable
+  outputs across runs. Centralising the stem logic ensures that future
+  refinements, such as Unicode slug handling, propagate consistently.
+: Encapsulating the naming strategy inside a dedicated helper keeps pipeline
+  tests focused on transformation behaviour instead of string manipulation edge
+  cases.
+
+Usage Example
+:
+    >>> from pathlib import Path
+    >>> paths = [Path("book/chapter.md"), Path("notes/chapter.md"), Path("notes/appendix.md")]
+    >>> mapping = build_unique_stem_map(paths)
+    >>> mapping[Path("book/chapter.md")]
+    'chapter'
+    >>> mapping[Path("notes/chapter.md")]
+    'chapter-2'
+    >>> mapping[Path("notes/appendix.md")]
+    'appendix'
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+
+__all__ = ["build_unique_stem_map"]
+
+
+def build_unique_stem_map(paths: Iterable[Path]) -> dict[Path, str]:
+    """Generate unique stems for a sequence of paths to avoid filename collisions during rendering."""
+    counters: dict[str, int] = {}
+    used: set[str] = set()
+    mapping: dict[Path, str] = {}
+
+    for path in paths:
+        base = path.stem
+        index = counters.get(base, 0)
+        candidate = base if index == 0 else f"{base}-{index + 1}"
+        while candidate in used:
+            index += 1
+            candidate = f"{base}-{index + 1}"
+        counters[base] = index + 1
+        used.add(candidate)
+        mapping[path] = candidate
+
+    return mapping