Readers & Writers¶

TeXSmith converts a document through a typed intermediate representation (IR):

read(HTML) → IR (texsmith.ir) → write(IR) → LaTeX

A reader lowers BeautifulSoup nodes into backend-agnostic IR nodes, and a writer emits a backend (LATEX) from that IR. Custom constructs are added in two halves that mirror how the built-in constructs work.

Reader lowerings — `@reads`¶

A reader lowering is a callable decorated with @reads(*tags, level, priority, name). It returns an IR node (never mutates the tree). Returning NotHandled lets the next candidate — or the generic fallback — run.

from bs4 import Tag

from texsmith.ir import nodes as ir
from texsmith.readers.html.registry import NotHandled, ReadLevel, reads


@reads("span", level=ReadLevel.INLINE, name="data_counter", priority=50)
def read_data_counter(tag: Tag, ctx) -> ir.Span | object:
    classes = tag.get("class") or []
    tokens = {classes} if isinstance(classes, str) else set(classes)
    if "data-counter" not in tokens:
        return NotHandled
    return ir.Span(content=(), attrs=(("role", "counter"),))

Writer emitters — `@writes`¶

A writer emitter is a method decorated with @writes(NodeType) on a LaTeXWriter subclass. Dispatch is typed by node class via the MRO; a node without an emitter raises a clear LaTeXWriteError.

from texsmith.ir import nodes as ir
from texsmith.writers.latex import LaTeXWriter, writes


class CountingWriter(LaTeXWriter):
    @writes(ir.Span)
    def _counter_span(self, node: ir.Span) -> str:
        if dict(node.attrs).get("role") == "counter":
            value = self.state.state.next_counter("data-counter")
            return f"\\counter{{{value}}}"
        return super()._span(node)

See examples/custom-render/counter.py for a complete, runnable extension wiring both halves into a LaTeXRenderer.

Tip

Keep the IR semantic and backend-neutral: encode hints via Span/Div attrs (e.g. ("role", "counter")) rather than backend strings. Only the writer knows about LATEX.

Shipping readers & writers in a template¶

When custom constructs belong to a specific template (an exam, a thesis, a poster…), declare the reader modules and the writer subclass in that template's [latex.template] manifest section. TeXSmith resolves them when the template is selected and applies them to the renderer for that template only — other templates keep the default bundled read→write path.

[latex.template]
name = "exam"
version = "1.0.0"
entrypoint = "template/template.tex"
engine = "lualatex"

# Modules whose @reads lowerings are layered on top of the bundled registry.
# A higher-priority handler may return NotHandled to fall through to a core one.
readers = ["my_exam_pkg.reader"]

# A "module:Class" reference to a LaTeXWriter subclass adding/overriding @writes.
writer = "my_exam_pkg.writer:ExamLaTeXWriter"

readers — a list of importable module paths. Every @reads-decorated callable found in each module is registered, layered on top of the bundled HTML→IR lowerings (texsmith.readers.html.build_reader_registry).
writer — a "module:Class" reference to a LaTeXWriter subclass. It is validated at render time (must subclass LaTeXWriter), then used as the template's writer so its @writes emitters and overrides take effect.

Both are resolved with the same import machinery as attribute normalisers and fragment entrypoints, so a typo or a bad reference fails early with an actionable TemplateError. A template that declares neither is unaffected.

Scope

These hooks are template-scoped by design. Because exam-style rules (e.g. mapping every h1 to \question) would corrupt unrelated documents, they are never registered globally — only while the declaring template renders. There is no global reader/writer entry point.

Inside an extension, read template front-matter overrides from self.state.runtime["template_overrides"] (already populated by the pipeline); keep cross-node state on self.state.state (the DocumentState) and harvest it in a pre-pass over the IR (texsmith.ir.visitor.walk) rather than mutating shared state during emission.

Reference¶

Lowering registry — the @reads decorator and its registry.

@reads declares a handler that returns an IR node (or a sequence of IR nodes) for a given HTML tag — never mutating the BeautifulSoup tree. The registry keeps the mapping extensible so extensions can register their own lowering without touching the core reader.

A lowering is selected by (level, tag): the reader walks the tree at a known level (BLOCK while collecting top-level/structural nodes, INLINE while gathering phrasing content) and asks the registry for the most specific handler. Handlers are tried in registration order — earlier registrations win — and a handler signals "not mine" by returning :data:NotHandled, letting the reader fall through to the next candidate (and ultimately to a generic fallback that never drops content silently).

NotHandled `module-attribute` ¶

NotHandled = _NotHandledType()

Singleton sentinel; return it from a lowering to decline an element.

ReadLevel ¶

Bases: Enum

The structural level a lowering produces.

A handler is consulted only at its own level: BLOCK handlers build block nodes (paragraphs, lists, figures, tables…), INLINE handlers build phrasing nodes (emphasis, links, code spans…). A few constructs are valid at either level (e.g. images, math, margin notes) and register for :data:ReadLevel.ANY.

ReaderRegistry `dataclass` ¶

ReaderRegistry(_rules: list[ReaderRule] = list())

Collects :class:ReaderRule instances indexed by (level, tag).

Lookups return every candidate for a tag (at the requested level plus the ANY level), highest priority first then registration order. The reader walks the candidates, applying the first that does not return :data:NotHandled.

candidates ¶

candidates(
    tag: str, level: ReadLevel
) -> tuple[ReaderRule, ...]

Return lowerings for tag applicable at level (best first).

Source code in src/texsmith/readers/html/registry.py

def candidates(self, tag: str, level: ReadLevel) -> tuple[ReaderRule, ...]:
    """Return lowerings for ``tag`` applicable at ``level`` (best first)."""
    matched = [
        rule
        for rule in self._rules
        if tag in rule.tags and (rule.level is level or rule.level is ReadLevel.ANY)
    ]
    matched.sort(key=lambda rule: -rule.priority)
    return tuple(matched)

collect_from ¶

collect_from(owner: object) -> None

Register every @reads-decorated callable found on owner.

owner is typically a module; its public callables are scanned for the descriptor installed by :func:reads.

Source code in src/texsmith/readers/html/registry.py

def collect_from(self, owner: object) -> None:
    """Register every ``@reads``-decorated callable found on ``owner``.

    ``owner`` is typically a module; its public callables are scanned for
    the descriptor installed by :func:`reads`.
    """
    for attribute in dir(owner):
        handler = getattr(owner, attribute, None)
        if not callable(handler):
            continue
        definition = getattr(handler, "__reader_rule__", None)
        if isinstance(definition, _ReaderDefinition):
            self.register(definition.bind(handler))

register ¶

register(rule: ReaderRule) -> None

Append rule to the registry (registration order is stable).

Source code in src/texsmith/readers/html/registry.py

def register(self, rule: ReaderRule) -> None:
    """Append ``rule`` to the registry (registration order is stable)."""
    self._rules.append(rule)

ReaderRule `dataclass` ¶

ReaderRule(
    level: ReadLevel,
    tags: tuple[str, ...],
    handler: Lowering,
    name: str,
    priority: int = 0,
)

A concrete lowering bound to one or more tags at a given level.

reads ¶

reads(
    *tags: str,
    level: ReadLevel = ReadLevel.BLOCK,
    priority: int = 0,
    name: str | None = None,
) -> Callable[[Lowering], Lowering]

Declare handler as the lowering for tags at level.

The decorated callable returns an IR node (or sequence/None/ :data:NotHandled) instead of mutating a soup. Higher priority wins when several handlers target the same tag.

Source code in src/texsmith/readers/html/registry.py

def reads(
    *tags: str,
    level: ReadLevel = ReadLevel.BLOCK,
    priority: int = 0,
    name: str | None = None,
) -> Callable[[Lowering], Lowering]:
    """Declare ``handler`` as the lowering for ``tags`` at ``level``.

    The decorated callable *returns* an IR node (or sequence/``None``/
    :data:`NotHandled`) instead of mutating a soup. Higher ``priority`` wins
    when several handlers target the same tag.
    """
    definition = _ReaderDefinition(
        level=level,
        tags=tuple(tags),
        priority=priority,
        name=name,
    )

    def decorator(handler: Lowering) -> Lowering:
        handler.__reader_rule__ = definition  # type: ignore[attr-defined]
        return handler

    return decorator

The :class:HtmlReader — lower a BeautifulSoup tree into IR.

The reader is the inverse of the old mutate-and-flatten pipeline: instead of rewriting the DOM into LATEX strings and calling soup.get_text(), it constructs a :class:texsmith.ir.Document. It never emits a backend string.

Dispatch model¶

Two recursive passes share one registry (:mod:.registry):

:meth:lower_blocks collects block-level IR from a run of siblings. Loose inline content between block tags is gathered and wrapped in a Para.
:meth:lower_inline collects phrasing IR from a run of siblings, turning text nodes into Str / Space and recursing into inline tags.

For each element tag the reader asks the registry for candidate lowerings at the active level (plus the level-agnostic ones). The first candidate that does not return :data:~.registry.NotHandled wins.

Fallback (no construct is ever dropped silently)¶

If no lowering claims a tag, the reader emits a diagnostic warning and a generic :class:~texsmith.ir.Div (block level) or :class:~texsmith.ir.Span (inline level) that preserves the tag name and its classes in attrs and keeps the recursively-lowered children. Unknown content is therefore always represented and traceable, never lost.