A tagged list whose column is a picture

"""Writes a tagged parts list whose first column is a picture, not a word.

The Python twin of the `write_tagged_pictures` example in Rust: the same document,
through the binding rather than through the library directly.

A picture says nothing to something that reads a document aloud, so a tagged file
has to say it instead: each picture is marked as a figure of its own and carries the
words a reader hears in its place. That is what a cell's `alt` is for, and this is
what it comes to — a table whose every row is a row of the structure tree, whose text
cells are read as text, and whose picture cells are read as the sentence the catalogue
gave them.

The tree is not built by hand here: the table hands back the branch describing itself,
figures and all, from the same counter the page numbers its marks from.

Where `write_tagged` shows prose, headings and a table of figures, this shows the one
thing prose cannot: a picture inside a cell, standing for something a reader must be
told about.

The list is held in `Words`, once per language, and `HQF_PDF_LANG` picks which set is
written. The language a document is in is part of what makes it readable aloud: the
structure tree carries the tag of the language its words are in, and it comes from the
same set of words as the words themselves.

Usage: python examples/write_tagged_pictures.py [out.pdf] [font.ttf]
       python examples/write_tagged_pictures.py out.pdf --archival
       python examples/write_tagged_pictures.py out.pdf --ua
       HQF_PDF_LANG=fr python examples/write_tagged_pictures.py
"""

from __future__ import annotations

import sys
from dataclasses import dataclass
from pathlib import Path

import _language
import _licence
import _out

import hqf_pdf

# The pictures the list shows, committed with the tests.
PICTURES = (
    Path(__file__).resolve().parents[3] / "crates" / "hqf-pdf" / "tests" / "images"
)

# The left edge everything is set from.
MARGIN = 64.0

# The room the table has across an A4 page between the margins.
WIDTH = 595.276 - 2.0 * MARGIN

# The colour the heading row is painted on.
HEAD_FILL = hqf_pdf.Rgb.gray(0.88)


# The picture each part is shown by, under the committed images. A picture is the same
# picture in every language.
PART_PICTURES = ("logo.png", "hqf_development.png", "indexed_16colours.png")


@dataclass(frozen=True)
class Words:
    """Every word the list writes, in one language.

    The tag of the language is here too: a document that says nothing about the language
    its words are in cannot be read aloud properly, and it is one more thing a set of
    words has to get right.
    """

    # The tag the structure tree carries, saying what the words below are in.
    lang: str
    # The title the document is filed under, in its information dictionary and in its
    # metadata both.
    title: str
    # The line at the head of the page.
    heading: str
    # The heading of each column, in the order the columns are set.
    columns: tuple[str, str, str]
    # What each part is called, in the order the rows are written.
    names: tuple[str, str, str]
    # What each part is for.
    purposes: tuple[str, str, str]
    # What each picture is, said in words. A figure with nothing here is a figure
    # nothing can read out, and a validator says so.
    alts: tuple[str, str, str]
    # The paragraph under the list.
    closing: str
    # The page number at the foot, which is furniture rather than what the document
    # says.
    footer: str


# The list in English.
ENGLISH = Words(
    lang="en-GB",
    title="A tagged parts list",
    heading="Parts of the housing",
    columns=("Picture", "Part", "What it is for"),
    names=("Cover plate", "Rating label", "Heat scale"),
    purposes=(
        "Closes the housing once the board is seated.",
        "Carries the serial number and the supply it is rated for.",
        "Read against the winding to say how hot it is running.",
    ),
    alts=(
        "The house mark: a ring, one half blue and the other yellow.",
        "The maker's name, printed across the label in full.",
        "A band running from red at the top down to blue at the bottom.",
    ),
    closing=(
        "Every picture above is marked as a figure and carries the words a "
        "reader hears in its place, so nothing in this list is lost on somebody "
        "who cannot see it. The table itself is a branch of the structure tree: "
        "each row is a row there too, and each cell says which column it sits "
        "in."
    ),
    footer="Page 1 of 1",
)

# The list in French.
FRENCH = Words(
    lang="fr-FR",
    title="Une liste de pièces balisée",
    heading="Les pièces du boîtier",
    columns=("Image", "Pièce", "À quoi elle sert"),
    names=("Couvercle", "Plaque signalétique", "Échelle de chaleur"),
    purposes=(
        "Ferme le boîtier une fois la carte en place.",
        "Porte le numéro de série et la tension prévue.",
        "Se lit contre le bobinage pour dire à quelle chaleur il tourne.",
    ),
    alts=(
        "La marque de la maison : un anneau, moitié bleu, moitié jaune.",
        "Le nom du fabricant, imprimé en entier sur l'étiquette.",
        "Une bande qui va du rouge en haut au bleu en bas.",
    ),
    closing=(
        "Chaque image ci-dessus est marquée comme figure et porte les mots "
        "qu'un lecteur entend à sa place : rien de cette liste n'échappe à qui "
        "ne la voit pas. Le tableau lui-même est une branche de l'arbre de "
        "structure : chaque rangée y est une rangée aussi, et chaque cellule dit "
        "dans quelle colonne elle se trouve."
    ),
    footer="Page 1 sur 1",
)


# Every language the example is written in. A language is added by writing its own set
# of words and naming it here.
WORDS = {_language.ENGLISH: ENGLISH, _language.FRENCH: FRENCH}


def heading(
    content: hqf_pdf.Content,
    handle: hqf_pdf.FontHandle,
    marks: hqf_pdf.Marks,
    page: int,
    words: Words,
) -> hqf_pdf.StructElement:
    """The heading, marked and numbered so that the tree can point at it."""
    number = marks.next_id()
    content.begin_tagged("H1", number)
    content.draw_text(handle, 18.0, MARGIN, 762.0, words.heading)
    content.end_marked()
    return hqf_pdf.StructElement("H1", children=[(page, number)])


def closing(
    content: hqf_pdf.Content,
    handle: hqf_pdf.FontHandle,
    marks: hqf_pdf.Marks,
    page: int,
    top: float,
    words: Words,
) -> hqf_pdf.StructElement:
    """The closing paragraph, broken into lines and marked as one run."""
    flow = hqf_pdf.TextFlow(
        handle, 10.0, leading=15.0, align=hqf_pdf.Align.Justify
    )
    lines = flow.break_lines(words.closing, WIDTH)
    numbers = flow.draw_tagged(content, lines, MARGIN, top, WIDTH, "P", marks)
    return hqf_pdf.StructElement("P", children=[(page, numbers[0])])


def parts_list(
    content: hqf_pdf.Content,
    handle: hqf_pdf.FontHandle,
    handles: list[hqf_pdf.ImageHandle],
    marks: hqf_pdf.Marks,
    page: int,
    words: Words,
) -> tuple[hqf_pdf.StructElement, float]:
    """The parts list, and the branch of the tree describing it.

    The pictures are drawn by the table, each into whatever rectangle its cell came
    to, and each marked as a figure carrying its own words.
    """
    columns = hqf_pdf.Columns(
        [
            hqf_pdf.ColumnWidth.points(96.0),
            hqf_pdf.ColumnWidth.points(120.0),
            hqf_pdf.ColumnWidth.points(WIDTH - 216.0),
        ],
        WIDTH,
    )
    table = hqf_pdf.Table(columns)
    table.header(1)
    table.rule(hqf_pdf.Rule.frame(), hqf_pdf.Stroke(0.8))
    table.rule(
        hqf_pdf.Rule.horizontal_other(), hqf_pdf.Stroke(0.25, hqf_pdf.Rgb.gray(0.7))
    )

    head_padding = hqf_pdf.Padding.symmetric(6.0, 5.0)
    table.push(
        hqf_pdf.Row(
            [
                hqf_pdf.Cell(
                    handle,
                    10.0,
                    label,
                    align=hqf_pdf.Align.Left,
                    padding=head_padding,
                )
                for label in words.columns
            ],
            fill=HEAD_FILL,
        )
    )

    for image, name, purpose, alt in zip(
        handles, words.names, words.purposes, words.alts
    ):
        table.push(
            hqf_pdf.Row(
                [
                    hqf_pdf.Cell.image(
                        image,
                        alt=alt,
                        align=hqf_pdf.Align.Center,
                        valign=hqf_pdf.VAlign.Middle,
                        padding=hqf_pdf.Padding.uniform(5.0),
                    ),
                    hqf_pdf.Cell(
                        handle,
                        10.0,
                        name,
                        valign=hqf_pdf.VAlign.Middle,
                        padding=head_padding,
                    ),
                    hqf_pdf.Cell(
                        handle,
                        10.0,
                        purpose,
                        valign=hqf_pdf.VAlign.Middle,
                        padding=head_padding,
                    ),
                ],
                min_height=54.0,
            )
        )

    placement = table.fit(MARGIN, 736.0, 620.0)
    return placement.draw_tagged(content, page, marks), placement.bottom


def main() -> None:
    language = _language.from_environment()
    words = _language.words_of(WORDS, language)

    archival = "--archival" in sys.argv
    ua = "--ua" in sys.argv
    sys.argv = [argument for argument in sys.argv if not argument.startswith("--")]
    # A named file is written as named; the default one carries the language, so the two
    # languages do not overwrite each other in `tmp/`.
    out = _out.output_path(
        Path(_language.file_name("tagged_pictures.pdf", language)).stem
    )

    document = hqf_pdf.Document()
    document.set_license(_licence.licensed())
    if archival:
        document.set_conformance(hqf_pdf.PdfA.A3A)
    if ua:
        document.set_ua_conformance(hqf_pdf.PdfUa.One)
    if archival or ua:
        document.set_metadata(
            hqf_pdf.Metadata(
                title=words.title,
                producer="hqf-pdf",
                created="2026-07-26T09:30:00+02:00",
            )
        )
    document.set_info("Title", words.title)

    handle = document.add_font(hqf_pdf.Font.from_path(_out.font_path()))
    handles = [
        document.add_image(hqf_pdf.Image.from_path(PICTURES / picture))
        for picture in PART_PICTURES
    ]

    content = hqf_pdf.Content()
    marks = hqf_pdf.Marks()
    children = [heading(content, handle, marks, 0, words)]
    table, bottom = parts_list(content, handle, handles, marks, 0, words)
    children.append(table)
    children.append(closing(content, handle, marks, 0, bottom - 24.0, words))

    # The page number is furniture, not what the document says, so it carries no number
    # and the tree never points at it.
    content.begin_artifact(hqf_pdf.Artifact.Footer)
    content.draw_text(handle, 9.0, MARGIN, 48.0, words.footer)
    content.end_marked()

    page = hqf_pdf.Page.a4()
    page.set_content(content)
    document.add_page(page)

    document.set_structure(
        hqf_pdf.StructureTree(
            lang=words.lang,
            children=[
                hqf_pdf.StructElement(
                    "Document",
                    children=[hqf_pdf.StructElement("Sect", children=children)],
                )
            ],
        )
    )

    written = document.write(out)
    print(f"wrote {out} ({written} bytes)")


if __name__ == "__main__":
    main()