texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/__init__.py

@@ -0,0 +1,107 @@
+"""Primary public API for TeXSmith."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+from texsmith import _alias as _legacy_aliases
+from texsmith.api import (
+    ConversionBundle,
+    ConversionRequest,
+    ConversionResponse,
+    ConversionService,
+    Document,
+    DocumentRenderOptions,
+    LaTeXFragment,
+    RenderSettings,
+    SlotAssignment,
+    TemplateOptions,
+    TemplateRenderResult,
+    TemplateSession,
+    TitleStrategy,
+    classify_input_source,
+    convert_documents,
+    get_template,
+)
+from texsmith.core.bibliography import (
+    BibliographyCollection,
+    BibliographyIssue,
+    DoiBibliographyFetcher,
+    DoiLookupError,
+    bibliography_data_from_string,
+)
+from texsmith.core.config import BookConfig, LaTeXConfig
+from texsmith.core.context import AssetRegistry, DocumentState, RenderContext
+from texsmith.core.rules import RenderPhase, renders
+from texsmith.core.templates import (
+    DEFAULT_TEMPLATE_LANGUAGE,
+    TemplateBinding,
+    TemplateError,
+    TemplateRuntime,
+    TemplateSlot,
+    WrappableTemplate,
+    build_template_overrides,
+    copy_template_assets,
+    load_template,
+    load_template_runtime,
+    resolve_template_language,
+)
+from texsmith.core.user_dir import (
+    TexsmithUserDir,
+    configure_user_dir,
+    get_user_dir,
+    user_dir_context,
+)
+
+
+try:
+    __version__ = _pkg_version("texsmith")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "DEFAULT_TEMPLATE_LANGUAGE",
+    "AssetRegistry",
+    "BibliographyCollection",
+    "BibliographyIssue",
+    "BookConfig",
+    "ConversionBundle",
+    "ConversionRequest",
+    "ConversionResponse",
+    "ConversionService",
+    "Document",
+    "DocumentRenderOptions",
+    "DocumentState",
+    "DoiBibliographyFetcher",
+    "DoiLookupError",
+    "LaTeXConfig",
+    "LaTeXFragment",
+    "RenderContext",
+    "RenderPhase",
+    "RenderSettings",
+    "SlotAssignment",
+    "TemplateBinding",
+    "TemplateError",
+    "TemplateOptions",
+    "TemplateRenderResult",
+    "TemplateRuntime",
+    "TemplateSession",
+    "TemplateSlot",
+    "TexsmithUserDir",
+    "TitleStrategy",
+    "WrappableTemplate",
+    "__version__",
+    "bibliography_data_from_string",
+    "build_template_overrides",
+    "classify_input_source",
+    "configure_user_dir",
+    "convert_documents",
+    "copy_template_assets",
+    "get_template",
+    "get_user_dir",
+    "load_template",
+    "load_template_runtime",
+    "renders",
+    "resolve_template_language",
+    "user_dir_context",
+]

texsmith/_alias.py

@@ -0,0 +1,59 @@
+"""Register legacy extension module aliases for backwards compatibility."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+import types
+
+
+_EXTENSION_ALIAS_MODULES: dict[str, tuple[str, dict[str, str] | None]] = {
+    "smallcaps": ("texsmith.extensions.smallcaps", None),
+    "mermaid": ("texsmith.extensions.mermaid", None),
+    "multi_citations": ("texsmith.extensions.multi_citations", None),
+    "latex_raw": ("texsmith.extensions.latex_raw", None),
+    "latex_text": ("texsmith.extensions.latex_text", None),
+    "missing_footnotes": ("texsmith.extensions.missing_footnotes", None),
+    "rawlatex": ("texsmith.extensions.latex_raw", {"RawLatexExtension": "LatexRawExtension"}),
+}
+
+
+class _AliasModule(types.ModuleType):
+    """Lazy module wrapper that proxies attribute access to the canonical module."""
+
+    __slots__ = ("_alias_map", "_target")
+
+    def __init__(self, name: str, target: str, alias_map: dict[str, str] | None) -> None:
+        super().__init__(name)
+        self._target = target
+        self._alias_map = alias_map or {}
+        self.__package__ = name.rpartition(".")[0]
+
+    def _load(self) -> types.ModuleType:
+        module = importlib.import_module(self._target)
+        if self._alias_map:
+            for alias_attr, target_attr in self._alias_map.items():
+                setattr(module, alias_attr, getattr(module, target_attr))
+            exported = set(getattr(module, "__all__", [])) | set(self._alias_map.keys())
+            if exported:
+                module.__all__ = sorted(exported)
+        sys.modules[self.__name__] = module
+        return module
+
+    def __getattr__(self, item: str) -> object:
+        module = self._load()
+        return getattr(module, item)
+
+
+def register_aliases() -> None:
+    package = sys.modules.get("texsmith")
+    if package is None:  # pragma: no cover - defensive
+        return
+    for alias, (target, attr_map) in _EXTENSION_ALIAS_MODULES.items():
+        module_name = f"texsmith.{alias}"
+        placeholder = _AliasModule(module_name, target, attr_map)
+        sys.modules.setdefault(module_name, placeholder)
+        setattr(package, alias, placeholder)
+
+
+register_aliases()

texsmith/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Integration layer for TexSmith adapters."""
+
+from __future__ import annotations
+
+
+__all__ = []

texsmith/adapters/docker.py

@@ -0,0 +1,258 @@
+"""Abstractions for invoking Docker containers safely."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+import os
+from pathlib import Path
+import shutil
+import subprocess
+
+from texsmith.core.exceptions import TransformerExecutionError
+
+
+@dataclass(slots=True)
+class VolumeMount:
+    """Bind mount configuration."""
+
+    source: Path | str
+    target: str
+    read_only: bool = False
+
+
+@dataclass(slots=True)
+class DockerLimits:
+    """Runtime constraints for Docker containers."""
+
+    cpus: float | int | None = None
+    memory: str | None = None
+    pids_limit: int | None = None
+
+
+@dataclass(slots=True)
+class DockerRunRequest:
+    """Full request payload for a Docker execution."""
+
+    image: str
+    args: Sequence[str] = field(default_factory=tuple)
+    mounts: Sequence[VolumeMount] = field(default_factory=tuple)
+    environment: Mapping[str, str] = field(default_factory=dict)
+    workdir: str | None = None
+    user: str | None = None
+    use_host_user: bool = True
+    remove: bool = True
+    limits: DockerLimits | None = None
+    network: str | None = None
+    extra_args: Sequence[str] = field(default_factory=tuple)
+
+
+class DockerRunner:
+    """Utility class encapsulating Docker invocations."""
+
+    def __init__(self, executable: str | None = None) -> None:
+        self._explicit_executable = executable
+        self._cached_executable: str | None = None
+
+    def is_available(self) -> bool:
+        """Return True when Docker can be located."""
+        try:
+            return self._resolve_executable(optional=True) is not None
+        except TransformerExecutionError:
+            return False
+
+    def reset(self) -> None:
+        """Clear cached executable lookup results."""
+        self._cached_executable = None
+
+    def run(
+        self,
+        request: DockerRunRequest,
+        *,
+        capture_output: bool = True,
+        text: bool = True,
+    ) -> subprocess.CompletedProcess[str]:
+        """Execute Docker with the supplied request."""
+        command = self._build_run_command(request)
+        try:
+            result = subprocess.run(
+                command,
+                check=False,
+                capture_output=capture_output,
+                text=text,
+            )
+        except FileNotFoundError as exc:
+            self._cached_executable = None
+            raise TransformerExecutionError("Docker executable could not be located.") from exc
+        except OSError as exc:
+            raise TransformerExecutionError(f"Failed to invoke Docker: {exc}") from exc
+
+        if result.returncode != 0:
+            stderr = (result.stderr or "").strip()
+            stdout = (result.stdout or "").strip()
+            detail = stderr or stdout
+            message = f"Docker image '{request.image}' failed with exit code {result.returncode}"
+            if detail:
+                message = f"{message}: {detail}"
+            raise TransformerExecutionError(message)
+
+        return result
+
+    def _build_run_command(self, request: DockerRunRequest) -> list[str]:
+        executable = self._resolve_executable(optional=False)
+        assert executable is not None
+        command: list[str] = [executable, "run"]
+
+        if request.remove:
+            command.append("--rm")
+
+        if request.extra_args:
+            command.extend(request.extra_args)
+
+        user = request.user or (self._resolve_host_user() if request.use_host_user else None)
+        if user:
+            command.extend(["--user", user])
+
+        if request.environment:
+            for key in sorted(request.environment):
+                value = request.environment[key]
+                command.extend(["-e", f"{key}={value}"])
+
+        if request.workdir:
+            command.extend(["--workdir", request.workdir])
+
+        if request.network:
+            command.extend(["--network", request.network])
+
+        command.extend(self._build_mounts(request.mounts))
+        command.extend(self._build_limits(request.limits))
+
+        command.append(request.image)
+        command.extend(request.args)
+        return command
+
+    def _build_mounts(self, mounts: Sequence[VolumeMount]) -> list[str]:
+        flags: list[str] = []
+        for mount in mounts:
+            host = Path(mount.source).expanduser()
+            if not host.exists():
+                raise TransformerExecutionError(f"Docker mount source '{host}' does not exist.")
+            try:
+                resolved = host.resolve(strict=True)
+            except (OSError, RuntimeError):
+                resolved = host.absolute()
+
+            parts = [
+                "type=bind",
+                f"src={resolved}",
+                f"dst={mount.target}",
+            ]
+
+            if mount.read_only:
+                parts.append("readonly")
+
+            flags.extend(["--mount", ",".join(parts)])
+        return flags
+
+    def _build_limits(self, limits: DockerLimits | None) -> list[str]:
+        if limits is None:
+            return []
+
+        flags: list[str] = []
+        if limits.cpus is not None:
+            flags.extend(["--cpus", str(limits.cpus)])
+        if limits.memory:
+            flags.extend(["--memory", str(limits.memory)])
+        if limits.pids_limit is not None:
+            flags.extend(["--pids-limit", str(limits.pids_limit)])
+        return flags
+
+    def _resolve_executable(self, *, optional: bool) -> str | None:
+        if self._explicit_executable:
+            return self._explicit_executable
+
+        if self._cached_executable:
+            return self._cached_executable
+
+        try:
+            executable = shutil.which("docker")
+        except (AssertionError, OSError, ValueError):
+            executable = None
+
+        if executable:
+            self._cached_executable = executable
+            return executable
+
+        if optional:
+            return None
+
+        raise TransformerExecutionError("Docker is required but was not found on PATH.")
+
+    def _resolve_host_user(self) -> str | None:
+        getuid = getattr(os, "getuid", None)
+        getgid = getattr(os, "getgid", None)
+
+        if callable(getuid) and callable(getgid):
+            try:
+                uid = getuid()
+                gid = getgid()
+            except OSError:
+                return None
+            return f"{uid}:{gid}"
+
+        return None
+
+
+_default_runner = DockerRunner()
+
+
+def is_docker_available() -> bool:
+    """Check if Docker can be executed."""
+    return _default_runner.is_available()
+
+
+def run_container(
+    image: str,
+    args: Sequence[str] = (),
+    *,
+    mounts: Sequence[VolumeMount] = (),
+    environment: Mapping[str, str] | None = None,
+    workdir: str | None = None,
+    user: str | None = None,
+    use_host_user: bool = True,
+    limits: DockerLimits | None = None,
+    network: str | None = None,
+    remove: bool = True,
+    extra_args: Sequence[str] = (),
+    capture_output: bool = True,
+    text: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    """Execute Docker using the shared runner."""
+    request = DockerRunRequest(
+        image=image,
+        args=tuple(args),
+        mounts=tuple(mounts),
+        environment=environment or {},
+        workdir=workdir,
+        user=user,
+        use_host_user=use_host_user,
+        remove=remove,
+        limits=limits,
+        network=network,
+        extra_args=tuple(extra_args),
+    )
+    return _default_runner.run(
+        request,
+        capture_output=capture_output,
+        text=text,
+    )
+
+
+__all__ = [
+    "DockerLimits",
+    "DockerRunRequest",
+    "DockerRunner",
+    "VolumeMount",
+    "is_docker_available",
+    "run_container",
+]

texsmith/adapters/handlers/__init__.py

@@ -0,0 +1,3 @@
+"""Built-in handler collections."""
+
+from . import admonitions, basic, blocks, code, inline, links, media