Skip to content

Open Processing Model

Output functions

eeditiones/open-processing-model

Output functions¶

ProcessingModelFunctions is the abstract base every output format implements. The generated transform module calls its methods (paragraph, heading, block, inline, …) to emit output. Subclass it to add a new output format; see the concrete implementations for HTML, Print, EPUB, Markdown, Typst, DOCX and JSON.

Base class and helpers¶

opm.runtime.output_functions ¶

Output format abstraction for TEI transformation.

Equivalent to html-functions.xql (and sibling format modules) in tei-publisher-lib/content. Each concrete subclass of ProcessingModelFunctions implements a specific serialisation target (HTML, Markdown, …). The generated transformation module calls methods on config.pmf and never imports a format-specific module directly.

HTML and Markdown implementations live in opm.html_output_functions and opm.markdown_output_functions; they are re-exported here for convenience.

TemplateOutput ¶

Bases: str

Preformatted or template text; skip prose normalisation that collapses line breaks.

ProcessingModelFunctions ¶

Bases: ABC

Abstract base for output format implementations.

Method names mirror the TEI Processing Model function vocabulary used by html-functions.xql / markdown-functions.xql etc. The generated transformation module calls these methods via config.pmf so that only the config construction needs to change when a different output format is required.

Every method receives config, a RenderContext, as its first argument. Output functions delegate recursive processing through it without importing the dispatch module:

config.apply – apply(config, nodes) → list config.apply_children – apply_children(config, node, content, parent) → None

A run creates its own instance, so per-run caches may live on self.

code ¶

code(config, node, cls, content, language=None) -> PMResult

Fallback code behaviour for output modes without dedicated formatting.

Source code in src/opm/runtime/output_functions.py

def code(self, config, node, cls, content, language=None) -> PMResult:
    """Fallback code behaviour for output modes without dedicated formatting."""
    _ = language
    return self.pass_through(config, node, cls, content)

code_inline ¶

code_inline(config, node, cls, content) -> PMResult

Inline code span — raw text, no markup escaping applied to the body.

Source code in src/opm/runtime/output_functions.py

def code_inline(self, config, node, cls, content) -> PMResult:
    """Inline code span — raw text, no markup escaping applied to the body."""
    return self.inline(config, node, cls, content)

unmatched ¶

unmatched(config, node) -> PMResult

Handle an element no model matched, i.e. the generated case _: arm.

Default: recurse into the children, which is what the generated dispatch does inline for every other output mode. Only the JSON mode overrides this — it is the sole way to see elements the ODD has no model for, since they otherwise never reach a pmf method at all.

Source code in src/opm/runtime/output_functions.py

def unmatched(self, config, node) -> PMResult:
    """Handle an element no model matched, i.e. the generated ``case _:`` arm.

    Default: recurse into the children, which is what the generated dispatch
    does inline for every other output mode.  Only the JSON mode overrides
    this — it is the sole way to see elements the ODD has no model for,
    since they otherwise never reach a ``pmf`` method at all.
    """
    return config.apply(config, child_nodes(node))

finish ¶

finish(config, nodes: list) -> list

Post-process output after apply, before footnotes.

Equivalent to pmf:finish in markdown-functions.xql / HTML siblings. Default: return nodes unchanged.

Source code in src/opm/runtime/output_functions.py

def finish(self, config, nodes: list) -> list:
    """Post-process output after [`apply`][opm.runtime.pm_runtime.apply], before footnotes.

    Equivalent to ``pmf:finish`` in ``markdown-functions.xql`` / HTML siblings.
    Default: return *nodes* unchanged.
    """
    return nodes

map_rend_to_class ¶

map_rend_to_class(node)

Map @rend attribute tokens directly to CSS class names, e.g. 'bold' → 'bold'.

Source code in src/opm/runtime/output_functions.py

def map_rend_to_class(node):
    """Map @rend attribute tokens directly to CSS class names, e.g. 'bold' → 'bold'."""
    rend = node.get('rend')
    if rend:
        return ' '.join(rend.split())
    return None

classes ¶

classes(*args)

Build a CSS class string, discarding None / empty entries.

Source code in src/opm/runtime/output_functions.py

def classes(*args):
    """Build a CSS class string, discarding None / empty entries."""
    return ' '.join(c for c in args if c)

add_lang_attrs ¶

add_lang_attrs(el, source_node)

Copy @xml:lang from source_node as HTML lang/dir attributes on el.

Source code in src/opm/runtime/output_functions.py

def add_lang_attrs(el, source_node):
    """Copy @xml:lang from *source_node* as HTML lang/dir attributes on *el*."""
    lang = source_node.get(XML_LANG)
    if lang:
        base = lang.split('-')[0]
        el.set('lang', lang)
        el.set('dir', 'rtl' if base in RTL_LANGUAGES else 'ltr')

normalize ¶

normalize(content)

Return content as a flat list of strings and lxml Elements.

Source code in src/opm/runtime/output_functions.py

def normalize(content):
    """Return content as a flat list of strings and lxml Elements."""
    if content is None:
        return []
    if isinstance(content, (str, etree._ElementUnicodeResult)):
        return [str(content)]
    if isinstance(content, etree._Element):
        return [content]
    # XPath atomics (number(), count unwrapped elsewhere, booleans) from ``xpath_content``
    if isinstance(content, (int, float, bool)):
        return [str(content)]
    return list(content)

param_str ¶

param_str(value) -> str

Coerce an ODD behaviour parameter (string or singleton sequence) to text.

A parameter whose XPath selected nothing arrives as an empty list, not as None — <param name="label" value="…//note[@target=$t]/@n"/> with no match, say. Returns '' for all of those, so a caller can treat "no value" uniformly.

Source code in src/opm/runtime/output_functions.py

def param_str(value) -> str:
    """Coerce an ODD behaviour parameter (string or singleton sequence) to text.

    A parameter whose XPath selected nothing arrives as an empty list, not as
    ``None`` — ``<param name="label" value="…//note[@target=$t]/@n"/>`` with no
    match, say. Returns ``''`` for all of those, so a caller can treat "no
    value" uniformly.
    """
    if value is None:
        return ''
    if isinstance(value, (list, tuple)):
        if not value:
            return ''
        value = value[0]
    return str(value).strip()

resolve_xml_id ¶

resolve_xml_id(
    node: _Element, idref: str
) -> _Element | None

Resolve a bare or #-prefixed xml:id against node's document.

Source code in src/opm/runtime/output_functions.py

def resolve_xml_id(node: etree._Element, idref: str) -> etree._Element | None:
    """Resolve a bare or ``#``-prefixed ``xml:id`` against *node*'s document."""
    tid = (idref or '').lstrip('#').strip()
    if not tid:
        return None
    root = node.getroottree().getroot()
    for el in root.iter():
        if isinstance(el.tag, str) and (el.get(XML_ID) == tid or el.get('id') == tid):
            return el
    return None

note_for_anchor ¶

note_for_anchor(anchor: _Element) -> _Element | None

The <note> whose @target points at anchor, if any.

Source code in src/opm/runtime/output_functions.py

def note_for_anchor(anchor: etree._Element) -> etree._Element | None:
    """The ``<note>`` whose ``@target`` points at *anchor*, if any."""
    aid = anchor.get(XML_ID) or anchor.get('id')
    if not aid:
        return None
    root = anchor.getroottree().getroot()
    for el in root.iter():
        if not isinstance(el.tag, str) or _local_name(el) != 'note':
            continue
        target = el.get('target')
        if target and target.lstrip('#') == aid:
            return el
    return None

is_lemma_range_note ¶

is_lemma_range_note(node: _Element) -> bool

True when node is an inline note that closes a lemma range.

That is a <note target="…"> pointing at an <anchor> (usually @type="note") which marks where the annotated passage begins. Stand-off notes in listAnnotation are excluded — those are point footnotes rendered at the anchor, not range ends.

Source code in src/opm/runtime/output_functions.py

def is_lemma_range_note(node: etree._Element) -> bool:
    """True when *node* is an inline note that closes a lemma range.

    That is a ``<note target="…">`` pointing at an ``<anchor>`` (usually
    ``@type="note"``) which marks where the annotated passage begins.
    Stand-off notes in ``listAnnotation`` are excluded — those are point
    footnotes rendered at the anchor, not range ends.
    """
    if not isinstance(getattr(node, 'tag', None), str):
        return False
    if _local_name(node) != 'note':
        return False
    if any(_local_name(a) == 'listAnnotation' for a in node.iterancestors()):
        return False
    target = node.get('target')
    if not target:
        return False
    peer = resolve_xml_id(node, target)
    return peer is not None and _local_name(peer) == 'anchor'

lemma_range_markers ¶

lemma_range_markers(label: str) -> tuple[str, str, str]

Return (start, end, footnote) markers for a lemma-range label.

For label a that is ('a-', '-a', 'a-a').

Source code in src/opm/runtime/output_functions.py

def lemma_range_markers(label: str) -> tuple[str, str, str]:
    """Return ``(start, end, footnote)`` markers for a lemma-range label.

    For label ``a`` that is ``('a-', '-a', 'a-a')``.
    """
    return f'{label}-', f'-{label}', f'{label}-{label}'

note_element_id ¶

note_element_id(node: _Element, fallback: str) -> str

Stable id fragment for footnote links (xml:id, else fallback).

Source code in src/opm/runtime/output_functions.py

def note_element_id(node: etree._Element, fallback: str) -> str:
    """Stable id fragment for footnote links (``xml:id``, else *fallback*)."""
    raw = node.get(XML_ID) or node.get('id') or fallback
    return re.sub(r'[-.]', '_', raw)

child_nodes ¶

child_nodes(node)

All child content as a flat list of strings and elements.

Equivalent to the XPath node() axis: preserves interleaved text and element children (including tail text of each child element).

Source code in src/opm/runtime/output_functions.py

def child_nodes(node):
    """All child content as a flat list of strings and elements.

    Equivalent to the XPath ``node()`` axis: preserves interleaved text and
    element children (including tail text of each child element).
    """
    result = []
    if node.text:
        result.append(node.text)
    for child in node:
        result.append(child)
        if child.tail:
            result.append(child.tail)
    return result

should_preserve_whitespace ¶

should_preserve_whitespace(cls: list) -> bool

Return True when dispatch classes indicate preformatted / code content.

Source code in src/opm/runtime/output_functions.py

def should_preserve_whitespace(cls: list) -> bool:
    """Return True when dispatch classes indicate preformatted / code content."""
    for item in cls:
        if not item:
            continue
        for name in str(item).split():
            if name in _PRESERVE_WHITESPACE_CLASS_NAMES:
                return True
    return False

apply_children_without_normalization ¶

apply_children_without_normalization(
    config: dict, source_node, content, parent_el
) -> None

Call config.apply_children with normalize_text off for this subtree.

Source code in src/opm/runtime/output_functions.py

def apply_children_without_normalization(
    config: dict,
    source_node,
    content,
    parent_el,
) -> None:
    """Call ``config.apply_children`` with ``normalize_text`` off for this subtree."""
    config.apply_children(config.derive(normalize_text=None), source_node, content, parent_el)

serialize_element_content_literal ¶

serialize_element_content_literal(el: _Element) -> str

Serialize the mixed content inside el as literal XML/text.

Source code in src/opm/runtime/output_functions.py

def serialize_element_content_literal(el: etree._Element) -> str:
    """Serialize the mixed content inside *el* as literal XML/text."""
    parts: list[str] = []
    if el.text:
        parts.append(el.text)
    for child in el:
        if isinstance(child.tag, str):
            parts.append(_serialize_xml_element_local(child, with_tail=True))
        else:
            raw = etree.tostring(child, encoding='unicode')
            if isinstance(raw, bytes):
                raw = raw.decode('utf-8')
            parts.append(raw)
            if child.tail:
                parts.append(child.tail)
    return ''.join(parts)

literal_code_body ¶

literal_code_body(node: _Element, content) -> str

Build a code-block body without running child elements through the PM.

Source code in src/opm/runtime/output_functions.py

def literal_code_body(node: etree._Element, content) -> str:
    """Build a code-block body without running child elements through the PM."""
    items = normalize(content)
    if len(items) == 1 and isinstance(items[0], etree._Element) and items[0] is node:
        return serialize_element_content_literal(node)
    parts: list[str] = []
    for item in items:
        if isinstance(item, str):
            parts.append(item)
        elif isinstance(item, etree._Element):
            parts.append(_serialize_xml_element_local(item, with_tail=True))
    return ''.join(parts)

join_eol_hyphen ¶

join_eol_hyphen(s: str) -> str

Close up a word the source split across lines at a soft hyphen.

Where an encoder marks the split with U+00AD and indents the continuation (Arra<lb/>gon), dropping the lb leaves that indentation behind, and every renderer collapses it to a space: "Arra gon". The soft hyphen is kept, so a reading system may still break the word there.

Source code in src/opm/runtime/output_functions.py

def join_eol_hyphen(s: str) -> str:
    """Close up a word the source split across lines at a soft hyphen.

    Where an encoder marks the split with U+00AD and indents the continuation
    (``Arra\u00ad<lb/>gon``), dropping the ``lb`` leaves that indentation behind,
    and every renderer collapses it to a space: "Arra gon". The soft hyphen is
    kept, so a reading system may still break the word there.
    """
    return _EOL_HYPHEN_RE.sub('\u00ad', s)

maybe_normalize_text ¶

maybe_normalize_text(s: str, norm) -> str

Apply norm unless s is template output that must keep \n.

Source code in src/opm/runtime/output_functions.py

def maybe_normalize_text(s: str, norm) -> str:
    """Apply *norm* unless *s* is template output that must keep ``\\n``."""
    if isinstance(s, TemplateOutput):
        return s
    s = join_eol_hyphen(s)
    return norm(s) if norm else s

apply_pb_template ¶

apply_pb_template(
    template_str: str,
    params: dict,
    config: dict | None = None,
) -> list

Execute a pb:template: parse template_str as XML, substitute [[param]] placeholders, and return the resulting list of nodes (strings and lxml Elements).

config is accepted for API symmetry but not currently used; element-valued params that appear in text positions are inserted directly into the result tree. The ODD compiler is expected to pass already-rendered output nodes (see apply_template_param_value, which expands a context node to processed children instead of raw TEI).

Source code in src/opm/runtime/output_functions.py

def apply_pb_template(template_str: str, params: dict, config: dict | None = None) -> list:
    """Execute a pb:template: parse *template_str* as XML, substitute [[param]] placeholders,
    and return the resulting list of nodes (strings and lxml Elements).

    *config* is accepted for API symmetry but not currently used; element-valued params that
    appear in text positions are inserted directly into the result tree. The ODD compiler is
    expected to pass already-rendered output nodes (see
    [`apply_template_param_value`][opm.runtime.pm_runtime.apply_template_param_value], which expands a context node
    to processed children instead of raw TEI).
    """
    wrapped = f'<__w__>{template_str}</__w__>'
    try:
        root = etree.fromstring(wrapped.encode('utf-8'))
    except etree.XMLSyntaxError:
        return []
    _substitute_node(root, params)
    result = []
    if root.text:
        result.append(root.text)
    for child in root:
        tail = child.tail
        child.tail = None
        result.append(child)
        if tail:
            result.append(tail)
    return _coerce_template_strings(result)

HTML¶

opm.runtime.html_output_functions.HtmlOutputFunctions ¶

Bases: ProcessingModelFunctions

Serialise to HTML5 using lxml elements.

finish ¶

finish(config, nodes: list) -> list

HTML pipeline has no finish normalisation; return nodes unchanged.

Source code in src/opm/runtime/html_output_functions.py

def finish(self, config, nodes: list) -> list:
    """HTML pipeline has no ``finish`` normalisation; return *nodes* unchanged."""
    return nodes

pass_through ¶

pass_through(config, node, cls, content) -> PMResult

Render content without adding a wrapper element.

Source code in src/opm/runtime/html_output_functions.py

def pass_through(self, config, node, cls, content) -> PMResult:
    """Render content without adding a wrapper element."""
    result = []
    for item in normalize(content):
        if isinstance(item, str):
            result.append(item)
        elif isinstance(item, etree._Element):
            sub = (config.apply(config, child_nodes(node))
                   if item is node
                   else config.apply(config, [item]))
            result.extend(sub)
    return result

note ¶

note(
    config, node, cls, content, place=None, label=None
) -> PMResult

Emit note - margin notes as inline spans, others as footnotes.

A footnote body is deferred to RunState and placed by inject_cached_footnotes at the end of the run, which is where a footnote_order hook may reorder it. The label is also kept as data-n — as PrintOutputFunctions.note does — so CSS can tell a note carrying its own @n from one numbered by the running counter without parsing the marker back out.

Lemma ranges (<anchor type="note"/> … <note target="…">) show a- at the start, -a at the end, and a-a on the footnote.

Source code in src/opm/runtime/html_output_functions.py

def note(self, config, node, cls, content, place=None, label=None) -> PMResult:
    """Emit note - margin notes as inline spans, others as footnotes.

    A footnote body is deferred to [`RunState`][opm.runtime.context.RunState]
    and placed by
    [`inject_cached_footnotes`][opm.runtime.pm_runtime.inject_cached_footnotes]
    at the end of the run, which is where a
    [`footnote_order`][opm.runtime.context.RenderContext]
    hook may reorder it. The label is also kept as ``data-n`` — as
    [`PrintOutputFunctions.note`][opm.runtime.print_output_functions.PrintOutputFunctions.note]
    does — so CSS can tell a note carrying its own ``@n`` from one numbered
    by the running counter without parsing the marker back out.

    Lemma ranges (``<anchor type="note"/>`` … ``<note target="…">``) show
    ``a-`` at the start, ``-a`` at the end, and ``a-a`` on the footnote.
    """
    # An ODD param whose XPath selected nothing arrives as an empty
    # sequence, not as None — the stand-off ``anchor`` models look the note
    # up in a ``listAnnotation`` the document may not have.
    label_s = param_str(label) or None
    place_s = param_str(place) or None

    # Start of a lemma range: the ODD passes place="start" and the label
    # of the note that closes the range. Emit only the opening marker.
    if place_s == 'start':
        return self._lemma_range_start(config, node, cls, label_s)

    # Such a lookup that found neither content nor a label is not a note:
    # emit nothing rather than an empty numbered entry, and leave both
    # counters alone.
    if place_s != 'margin' and not label_s and isinstance(content, (list, tuple)) \
            and not content:
        return []

    # A note without an id of its own still needs a unique one for the
    # ``#fn_…`` link. Its own counter, not the running note number: a
    # labelled note leaves that one alone (see below), so two of them would
    # otherwise collide on the same id.
    safe_id = note_element_id(node, str(config.state.next_id()))

    # Margin notes: output inline span(s), not footnotes
    if place_s == 'margin':
        result = []
        if label_s:
            # Label reference span
            ref_span = self._el('span', list(cls) + ['margin-note-ref'], node)
            config.apply_children(config, node, [label_s], ref_span)
            result.append(ref_span)
            # Margin note content with label
            note_span = self._el('span', list(cls) + ['margin-note'], node)
            n_span = etree.SubElement(note_span, 'span')
            n_span.set('class', 'n')
            n_span.text = label_s
            n_span.tail = ' '
            config.apply_children(config, node, content, note_span)
            result.append(note_span)
        else:
            # Margin note without label
            note_span = self._el('span', list(cls) + ['margin-note'], node)
            note_span.set('id', f'margin_ref_{safe_id}')
            config.apply_children(config, node, content, note_span)
            result.append(note_span)
        return result

    # Footnote handling (default). A note carrying its own ``@n`` does not
    # draw on the running counter — otherwise the two series of a critical
    # edition share one sequence and the numbered commentary skips every
    # value the lettered apparatus took (1, 3, 4, 7, …).
    range_note = bool(label_s) and is_lemma_range_note(node)
    if label_s:
        counter = config.state.note_counter
        if range_note:
            _start, ref_marker, fn_marker = lemma_range_markers(label_s)
        else:
            ref_marker = fn_marker = label_s
    else:
        counter = config.state.next_note()
        ref_marker = fn_marker = str(counter)

    ref_span = etree.Element('span')
    ref_span.set('id', f'fnref_{safe_id}')
    ref_span.set('style', 'display:inline-block')
    ref_span.set('class', classes(*cls))
    if label_s:
        ref_span.set('data-n', label_s)
        if range_note:
            ref_span.set('data-range', 'end')
    a = etree.SubElement(ref_span, 'a')
    a.set('class', 'note')
    a.set('rel', 'footnote')
    a.set('href', f'#fn_{safe_id}')
    a.text = ref_marker

    dl = etree.Element('dl')
    dl.set('class', 'footnote')
    dl.set('id', f'fn_{safe_id}')
    if label_s:
        dl.set('data-n', label_s)
        if range_note:
            dl.set('data-range', 'end')
    dt = etree.SubElement(dl, 'dt')
    dt.set('class', 'fn-number')
    dt.text = fn_marker
    dd = etree.SubElement(dl, 'dd')
    dd.set('class', 'fn-content')
    add_lang_attrs(dd, node)
    config.apply_children(config, node, content, dd)
    back = etree.SubElement(dd, 'a')
    back.set('class', 'fn-back')
    back.set('href', f'#fnref_{safe_id}')
    back.text = '↩'

    config.state.add_note(
        dl,
        number=counter,
        label=label_s,
        anchor=f'fn_{safe_id}',
        place=place_s,
        node=node,
    )
    return [ref_span]

code ¶

code(config, node, cls, content, language=None) -> PMResult

Emit a <pre><code> block so whitespace is preserved without JS.

data-language is omitted when web components are on: Prism in pb-components would otherwise re-highlight already-rendered listings (Pygments spans from tp:highlight, or the source itself).

Source code in src/opm/runtime/html_output_functions.py

def code(self, config, node, cls, content, language=None) -> PMResult:
    """Emit a ``<pre><code>`` block so whitespace is preserved without JS.

    ``data-language`` is omitted when web components are on: Prism in
    pb-components would otherwise re-highlight already-rendered listings
    (Pygments spans from ``tp:highlight``, or the source itself).
    """
    pre = self._el('pre', cls, node)
    code_el = etree.SubElement(pre, 'code')
    if (
        language is not None
        and not isinstance(language, (list, tuple))
        and not config.webcomponents
    ):
        lang = str(language).strip()
        if lang:
            code_el.set('data-language', lang)
    config.apply_children(config, node, content, code_el)
    return [pre]

Print (paged media)¶

opm.runtime.print_output_functions.PrintOutputFunctions ¶

Bases: HtmlOutputFunctions

Serialise to HTML tuned for paged-media CSS (Prince, Paged.js, print).

Equivalent to the pmf:* overrides in ext-printcss.xql.

note ¶

note(
    config, node, cls, content, place=None, label=None
) -> PMResult

Emit note as an inline span for CSS float: footnote / margin notes.

Unlike HtmlOutputFunctions.note, does not build callout links or append bodies to config.state.footnotes. A label (TEI @n) is kept as data-n so print CSS can show a, b, … instead of the running number.

Lemma ranges: place="start" emits a plain a- marker; a note with @target pointing at that anchor gets data-range so print CSS can show -a as the call and a-a as the footnote marker.

Source code in src/opm/runtime/print_output_functions.py

def note(self, config, node, cls, content, place=None, label=None) -> PMResult:
    """Emit note as an inline span for CSS ``float: footnote`` / margin notes.

    Unlike [`HtmlOutputFunctions.note`][opm.runtime.html_output_functions.HtmlOutputFunctions.note], does not build callout links or
    append bodies to ``config.state.footnotes``. A label (TEI ``@n``) is kept
    as ``data-n`` so print CSS can show a, b, … instead of the running number.

    Lemma ranges: ``place="start"`` emits a plain ``a-`` marker; a note with
    ``@target`` pointing at that anchor gets ``data-range`` so print CSS can
    show ``-a`` as the call and ``a-a`` as the footnote marker.
    """
    label_s = param_str(label) or None
    place_s = param_str(place) or None

    if place_s == 'start':
        if not label_s:
            return []
        start_marker, _end, _fn = lemma_range_markers(label_s)
        el = etree.Element('span')
        el.set('class', classes(*cls, 'note-range-start'))
        el.set('data-n', label_s)
        el.set('data-range', 'start')
        el.text = start_marker
        return [el]

    fn_class = 'margin-note' if place_s == 'margin' else 'footnote'
    el = self._el('span', list(cls) + [fn_class], node)
    if label_s:
        el.set('data-n', ' '.join(label_s.split()))
        if is_lemma_range_note(node):
            el.set('data-range', 'end')
    config.apply_children(config, node, content, el)
    return [el]

alternate ¶

alternate(
    config,
    node,
    cls,
    content,
    default,
    alternate,
    optional=None,
) -> PMResult

Emit the default reading plus the alternate as a print footnote.

Ignores webcomponents / popovers — print has no interactive UI.

Source code in src/opm/runtime/print_output_functions.py

def alternate(self, config, node, cls, content, default, alternate, optional=None) -> PMResult:
    """Emit the default reading plus the alternate as a print footnote.

    Ignores ``webcomponents`` / popovers — print has no interactive UI.
    """
    _ = content, optional
    outer = self._el('span', cls, node)
    config.apply_children(config, node, default, outer)
    result: PMResult = [outer]
    if alternate is not None:
        result.extend(
            self.note(config, node, cls, alternate, place='footnote', label=None)
        )
    return result

EPUB¶

opm.runtime.epub_output_functions.EpubOutputFunctions ¶

Bases: HtmlOutputFunctions

Serialise to HTML with EPUB 3 structural semantics.

Equivalent to the pmf:* overrides in ext-epub.xql. Packaging into a .epub ZIP is handled separately by opm.epub.

note ¶

note(
    config, node, cls, content, place=None, label=None
) -> PMResult

Emit an EPUB noteref + footnote aside (in-flow; packager may hoist).

Labels and lemma ranges follow HtmlOutputFunctions.note: a note carrying its own @n shows that label and leaves the running number alone, and a range reads a- … -a in the text and a-a on the note. The label is kept as data-n so a stylesheet can set the two series apart.

Source code in src/opm/runtime/epub_output_functions.py

def note(self, config, node, cls, content, place=None, label=None) -> PMResult:
    """Emit an EPUB noteref + footnote aside (in-flow; packager may hoist).

    Labels and lemma ranges follow
    [`HtmlOutputFunctions.note`][opm.runtime.html_output_functions.HtmlOutputFunctions.note]:
    a note carrying its own ``@n`` shows that label and leaves the running
    number alone, and a range reads ``a-`` … ``-a`` in the text and ``a-a``
    on the note. The label is kept as ``data-n`` so a stylesheet can set the
    two series apart.
    """
    label_s = param_str(label) or None
    place_s = param_str(place) or None
    if place_s == 'start':
        return self._lemma_range_start(config, node, cls, label_s)
    # A lookup that found neither content nor a label is not a note.
    if not label_s and isinstance(content, (list, tuple)) and not content:
        return []

    range_note = bool(label_s) and is_lemma_range_note(node)
    if label_s:
        if range_note:
            _start, ref_marker, fn_marker = lemma_range_markers(label_s)
        else:
            ref_marker = fn_marker = label_s
    else:
        ref_marker = fn_marker = str(config.state.next_note())
    fn_id = _epub_safe_id(node, config)

    ref = etree.Element('a', nsmap={'epub': EPUB_NS})
    ref.set(EPUB_TYPE, 'noteref')
    ref.set('href', f'#fn{fn_id}')
    ref.set('class', 'noteref')
    ref.text = ref_marker

    aside = etree.Element('aside', nsmap={'epub': EPUB_NS})
    aside.set(EPUB_TYPE, 'footnote')
    aside.set('id', f'fn{fn_id}')
    aside.set('class', classes('note', *cls))
    if label_s:
        for el in (ref, aside):
            el.set('data-n', label_s)
            if range_note:
                el.set('data-range', 'end')
    add_lang_attrs(aside, node)
    aside.append(_footnote_body(config, node, content, fn_marker))
    return [ref, aside]

alternate ¶

alternate(
    config,
    node,
    cls,
    content,
    default,
    alternate,
    optional=None,
) -> PMResult

Default reading as noteref; alternate body as footnote aside.

An alternate that adds nothing — empty, or only the default reading again, as a register reference does when no register is configured — stays plain text: a popup repeating the word just tapped is noise.

Source code in src/opm/runtime/epub_output_functions.py

def alternate(self, config, node, cls, content, default, alternate, optional=None) -> PMResult:
    """Default reading as noteref; alternate body as footnote aside.

    An alternate that adds nothing — empty, or only the default reading
    again, as a register reference does when no register is configured —
    stays plain text: a popup repeating the word just tapped is noise.
    """
    _ = content, optional
    body = _footnote_body(config, node, alternate)
    shown = self._el('span', cls, node)
    config.apply_children(config, node, default, shown)
    extra = ' '.join(''.join(body.itertext()).split())
    if not extra or extra == ' '.join(''.join(shown.itertext()).split()):
        return [shown]

    fn_id = _epub_safe_id(node, config)
    ref = etree.Element('a', nsmap={'epub': EPUB_NS})
    ref.set(EPUB_TYPE, 'noteref')
    ref.set('href', f'#fn{fn_id}')
    ref.set('class', classes('alternate', *cls))
    ref.text = shown.text
    for child in list(shown):
        ref.append(child)

    aside = etree.Element('aside', nsmap={'epub': EPUB_NS})
    aside.set(EPUB_TYPE, 'footnote')
    aside.set('id', f'fn{fn_id}')
    aside.set('class', classes('altcontent', *cls))
    aside.append(body)
    return [ref, aside]

webcomponent ¶

webcomponent(
    config, node, cls, content, name, optional=None
) -> PMResult

Degrade custom elements: EPUB 3 XHTML has no place for them.

pb-link keeps its cross-reference as a fragment link (rewritten to the target chapter file during packaging); everything else becomes a transparent div / span wrapper.

Source code in src/opm/runtime/epub_output_functions.py

def webcomponent(self, config, node, cls, content, name, optional=None) -> PMResult:
    """Degrade custom elements: EPUB 3 XHTML has no place for them.

    ``pb-link`` keeps its cross-reference as a fragment link (rewritten to
    the target chapter file during packaging); everything else becomes a
    transparent ``div`` / ``span`` wrapper.
    """
    opts = optional or {}
    if name == 'pb-code-highlight':
        return super().webcomponent(config, node, cls, content, name, optional)

    if name == 'pb-link':
        target = opts.get('xml-id') or opts.get('xml_id')
        if target:
            a = self._el('a', cls, node)
            a.set('href', f'#{target}')
            config.apply_children(config, node, content, a)
            return [a]

    el = self._el('div', cls, node)
    xml_id = node.get(XML_ID)
    if xml_id:
        el.set('id', xml_id)
    config.apply_children(config, node, content, el)
    if not any(
        isinstance(child.tag, str) and etree.QName(child).localname in BLOCK_TAGS
        for child in el
    ):
        el.tag = 'span'
    return [el]

cells ¶

cells(config, node, cls, content) -> PMResult

Wrap each content item as a <td> inside a <tr> (ext-epub).

Source code in src/opm/runtime/epub_output_functions.py

def cells(self, config, node, cls, content) -> PMResult:
    """Wrap each content item as a ``<td>`` inside a ``<tr>`` (``ext-epub``)."""
    tr = etree.Element('tr')
    for item in normalize(content):
        td = etree.SubElement(tr, 'td')
        td.set('class', classes(*cls))
        config.apply_children(config, node, item, td)
    return [tr]

EPUB packaging (ZIP / OPF / nav) lives in opm.epub, not in the PMF.

Markdown¶

opm.runtime.markdown_output_functions.MarkdownOutputFunctions ¶

Bases: ProcessingModelFunctions

Serialise to Markdown text fragments (CommonMark-style).

Mirrors pmf:* in tei-publisher-lib/content/markdown-functions.xql: paragraph breaks, headings with #, list markers, pipe tables, links, reference-style notes, and simple rend-based emphasis.

finish ¶

finish(config, nodes: list) -> list

Run pmf:finish-style cleanup: collapse blank lines, tighten _ / ** spans.

Source code in src/opm/runtime/markdown_output_functions.py

def finish(self, config, nodes: list) -> list:
    """Run ``pmf:finish``-style cleanup: collapse blank lines, tighten ``_`` / ``**`` spans."""
    text = apply_markdown_finish_regexes(_serialize_pm_result(nodes))
    return [text]

note ¶

note(
    config, node, cls, content, place=None, label=None
) -> PMResult

Emit a [^id] reference; the definition is placed when the run ends.

The marker a reader sees comes from the Markdown renderer, so label is kept only on the Footnote record, for a footnote_order hook to sort on. The hook decides the order of the definition block this writes out.

Lemma ranges still write the a- / -a markers into the text; the definition is prefixed with a-a so the label survives rendering.

Source code in src/opm/runtime/markdown_output_functions.py

def note(self, config, node, cls, content, place=None, label=None) -> PMResult:
    """Emit a ``[^id]`` reference; the definition is placed when the run ends.

    The marker a reader sees comes from the Markdown renderer, so ``label``
    is kept only on the
    [`Footnote`][opm.runtime.context.Footnote] record, for a
    [`footnote_order`][opm.runtime.context.RenderContext]
    hook to sort on. The hook decides the order of the definition block
    this writes out.

    Lemma ranges still write the ``a-`` / ``-a`` markers into the text;
    the definition is prefixed with ``a-a`` so the label survives
    rendering.
    """
    label_s = param_str(label) or None
    place_s = param_str(place) or None
    if place_s == 'start':
        if not label_s:
            return []
        start_marker, _end, _fn = lemma_range_markers(label_s)
        return [start_marker]
    # A stand-off lookup that found nothing is not a note.
    if not label_s and isinstance(content, (list, tuple)) and not content:
        return []
    # As in HTML: a note with its own ``@n`` leaves the counter alone, so
    # the two series of a critical edition number independently.
    nr = config.state.note_counter if label_s else config.state.next_note()
    # As in HTML, the id falls back to its own counter so two labelled
    # notes without an ``xml:id`` cannot collide.
    safe_id = note_element_id(node, str(config.state.next_id()))
    range_note = bool(label_s) and is_lemma_range_note(node)
    if range_note:
        _start, end_marker, fn_marker = lemma_range_markers(label_s)
        ref = f'{end_marker}[^{safe_id}]'
        prefix = f'{fn_marker} '
    else:
        ref = f'[^{safe_id}]'
        prefix = ''
    buf: list = []
    config.apply_children(config, node, content, buf)
    body = _join_buf(buf).strip()
    config.state.add_note(
        f'\n[^{safe_id}]: {prefix}{body}\n',
        number=nr,
        label=label_s,
        anchor=safe_id,
        place=place_s,
        node=node,
    )
    return [ref]

Typst¶

opm.runtime.typst_output_functions.TypstOutputFunctions ¶

Bases: ProcessingModelFunctions

Serialise to Typst markup text fragments.

DOCX¶

opm.runtime.docx_output_functions.DocxOutputFunctions ¶

DocxOutputFunctions()

Bases: ProcessingModelFunctions

DOCX output for TEI processing model.

Style resolution rules (matching tei-publisher-lib): - For each ODD cssClass that does not start with tei-, look up the name (case-insensitive) in the template's paragraph / character / table style index. First match wins; unknown classes are silently skipped. - Paragraph fallback: "Normal". Character fallback: no style (CSS properties like bold/italic still apply). Table fallback: "TableGrid".

Source code in src/opm/runtime/docx_output_functions.py

def __init__(self) -> None:
    self._styles_loaded = False
    self._para_styles: dict[str, str] = {}
    self._char_styles: dict[str, str] = {}
    self._table_styles: dict[str, str] = {}
    self._bullet_numid: int = 1
    self._ordered_numid: int = 5
    self._bullet_abstract_id: int = 8   # python-docx default abstract for bullet
    self._ordered_abstract_id: int = 7  # python-docx default abstract for ordered
    self._needs_numbering: bool = False
    self._current_template: str | None = None  # Store template path globally
    # Per-run package state; a run creates its own instance.
    self._footnotes: dict[int, list] = {}
    self._num_instances: list[tuple[int, str]] = []
    self._image_counter = 0
    self._image_rid_map: dict[str, str] = {}

metadata ¶

metadata(config, node, cls, content, key=None) -> PMResult

Collect a header value under key instead of emitting body content.

Mirrors TypstOutputFunctions.metadata: the ODD names the field, the collected text lands in config.state.metadata and is mapped onto the .docx core properties by finish.

Source code in src/opm/runtime/docx_output_functions.py

def metadata(self, config, node, cls, content, key=None) -> PMResult:
    """Collect a header value under *key* instead of emitting body content.

    Mirrors `TypstOutputFunctions.metadata`: the ODD names the field,
    the collected text lands in ``config.state.metadata`` and is
    mapped onto the ``.docx`` core properties by [`finish`][opm.runtime.docx_output_functions.DocxOutputFunctions.finish].
    """
    if key:
        self._ensure_styles(config)
        text = _ooxml_text(self._collect(config, node, content)).strip()
        config.state.metadata.setdefault(str(key), []).append(text)
    return []

finish ¶

finish(config: dict, nodes: list) -> list

Assemble body elements into a .docx and return [bytes].

Source code in src/opm/runtime/docx_output_functions.py

def finish(self, config: dict, nodes: list) -> list:
    """Assemble body elements into a ``.docx`` and return ``[bytes]``."""
    from docx import Document  # noqa: PLC0415
    from docx.opc.part import Part  # noqa: PLC0415
    from docx.opc.packuri import PackURI  # noqa: PLC0415

    template_path = config.docx_template
    doc = Document(template_path) if template_path else Document()
    if not self._styles_loaded:
        self._load_style_index(doc)
    self._inject_missing_builtin_styles(doc)
    self._apply_core_properties(config, doc)

    if self._needs_numbering:
        import docx as _docx_pkg  # noqa: PLC0415
        import os  # noqa: PLC0415
        _default_path = os.path.join(os.path.dirname(_docx_pkg.__file__), 'templates', 'default.docx')
        _default_doc = Document(_default_path)
        _np = _default_doc.part.numbering_part
        from docx.opc.constants import RELATIONSHIP_TYPE as _RT  # noqa: PLC0415
        if doc.part.package:
            _new_np = type(_np)(_np.partname, _np.content_type, _np._element, doc.part.package)
            doc.part.relate_to(_new_np, _RT.NUMBERING)

    # Add per-list w:num instances so each list gets its own counter
    instances = self._num_instances
    if instances:
        numbering_el = doc.part.numbering_part._element
        # Create pStyle-free abstract copies so Word doesn't share a global
        # counter across instances (abstracts with w:pStyle bindings do that).
        bullet_abs_id, ordered_abs_id = self._add_pstyle_free_abstracts(numbering_el)
        kind_to_abs = {'bullet': bullet_abs_id, 'ordered': ordered_abs_id}
        for new_numid, kind in instances:
            num_el = _w('num')
            _wset(num_el, 'numId', str(new_numid))
            abs_ref = _wsub(num_el, 'abstractNumId')
            _wset(abs_ref, 'val', str(kind_to_abs[kind]))
            # Force counter restart at 1 — without this explicit override
            # Word may continue counting from a previous list.
            lvl_override = _wsub(num_el, 'lvlOverride')
            _wset(lvl_override, 'ilvl', '0')
            start_override = _wsub(lvl_override, 'startOverride')
            _wset(start_override, 'val', '1')
            numbering_el.append(num_el)

    body = doc.element.body
    sectPr = body.find(f'{{{W}}}sectPr')
    for child in list(body):
        if etree.QName(child).localname != 'sectPr':
            body.remove(child)

    # Inline content left at the top level (a page break's bare w:r, a
    # sentinel, loose text) must sit inside a w:p: Word rejects the file
    # when w:body holds runs directly.
    body_elements = self._blockify(self._filter_ooxml(nodes))
    doc_nsmap = doc.element.nsmap
    self._replace_footnote_sentinels(body_elements, doc_nsmap)
    self._replace_hyperlink_sentinels(body_elements, doc, doc_nsmap)
    self._replace_image_sentinels(body_elements, doc, doc_nsmap, config)

    for el in body_elements:
        if sectPr is not None:
            sectPr.addprevious(el)
        else:
            body.append(el)

    footnotes_data = self._footnotes
    if footnotes_data:
        # Drop any existing footnotes part from the template to avoid duplicates.
        existing_fn_rids = [
            rId for rId, rel in list(doc.part.rels.items())
            if rel.reltype == FOOTNOTES_RT
        ]
        for rId in existing_fn_rids:
            doc.part.rels.pop(rId)
        footnote_rels = self._resolve_footnote_sentinels(
            footnotes_data, doc, doc_nsmap, config
        )
        xml_bytes = self._build_footnotes_xml(footnotes_data)
        footnotes_part = Part(
            PackURI('/word/footnotes.xml'),
            FOOTNOTES_CT,
            xml_bytes,
            doc.part.package,
        )
        doc.part.relate_to(footnotes_part, FOOTNOTES_RT)

    self._drop_custom_xml_rels(doc)

    buf = BytesIO()
    doc.save(buf)

    buf = self._normalize_document_xml(buf)

    if footnotes_data:
        buf = self._inject_footnotes_rels(buf, footnote_rels)

    return [buf.getvalue()]

JSON¶

Records the processing model's own decisions rather than rendering the document. It is the only implementation that overrides unmatched, which the generated dispatch calls for elements no model matched.

opm.runtime.json_output_functions.JsonOutputFunctions ¶

Bases: ProcessingModelFunctions

Emit the processing model's decisions as JSON records.

template ¶

template(
    config, node, cls, template_str: str, params: dict
) -> PMResult

Record a pb:template and keep the content it wraps.

The generator hands templates their parameters already processed, so params['content'] is a list of finished records. Dropping it would lose every element a template-heavy ODD wraps — for DocBook that is most of the document.

Source code in src/opm/runtime/json_output_functions.py

def template(
    self, config, node, cls, template_str: str, params: dict,
) -> PMResult:  # type: ignore[override]
    """Record a ``pb:template`` and keep the content it wraps.

    The generator hands templates their parameters already processed, so
    ``params['content']`` is a list of finished records. Dropping it would
    lose every element a template-heavy ODD wraps — for DocBook that is
    most of the document.
    """
    _ = config
    children: list = []
    scalars: dict = {}
    for key, value in (params or {}).items():
        if isinstance(value, list):
            children.extend(
                item for item in value
                if isinstance(item, dict) or isinstance(item, str)
            )
        elif isinstance(value, dict):
            children.append(value)
        else:
            flat = _flatten(value)
            if flat is not None:
                scalars[key] = flat
    rec = self._build(
        node, cls, 'template', _prune(children), positions=_positions(config),
    )
    # Templates are indented XML blocks; collapse them so records stay legible.
    rec['template'] = ' '.join(template_str.split())
    if scalars:
        rec['params'] = scalars
    return [rec]

pass_through ¶

pass_through(config, node, cls, content) -> PMResult

Recurse, but still record that a pass_through model won.

Emitting nothing here would hide a real decision: when the model you expected did not fire because a pass_through one matched first, the element simply would not appear. The same argument that puts inline and suppressed behaviours in the tree applies to this one.

Source code in src/opm/runtime/json_output_functions.py

def pass_through(self, config, node, cls, content) -> PMResult:
    """Recurse, but still record that a ``pass_through`` model won.

    Emitting nothing here would hide a real decision: when the model you
    expected did not fire because a ``pass_through`` one matched first,
    the element simply would not appear. The same argument that puts inline
    and suppressed behaviours in the tree applies to this one.
    """
    result: list = []
    for item in normalize(content):
        if isinstance(item, (str, dict)):
            result.append(item)
        elif isinstance(item, etree._Element):
            sub = (
                config.apply(config, child_nodes(node))
                if item is node
                else config.apply(config, [item])
            )
            result.extend(sub)
    return [
        self._build(
            node, cls, 'pass_through', _prune(result),
            positions=_positions(config),
        ),
    ]

unmatched ¶

unmatched(config, node) -> PMResult

Record an element the ODD has no model for, then recurse into it.

The generated dispatch routes its case _: arm here for JSON output. Without this the element would never reach a pmf method and its text would surface in some ancestor with no provenance at all — which is the one thing you most want to find when an ODD looks incomplete.

Source code in src/opm/runtime/json_output_functions.py

def unmatched(self, config, node) -> PMResult:
    """Record an element the ODD has no model for, then recurse into it.

    The generated dispatch routes its ``case _:`` arm here for JSON output.
    Without this the element would never reach a ``pmf`` method and its
    text would surface in some ancestor with no provenance at all — which
    is the one thing you most want to find when an ODD looks incomplete.
    """
    children: list = []
    config.apply_children(config, node, node, children)
    return [self._build(node, [], None, _prune(children), positions=_positions(config))]