write_provenance.py

"""A file whose every part says where it came from.

The Python twin of the `write_provenance` example in Rust. A document says what
it is, and that has always been written once, for the whole file. It is not
enough for anything assembled out of pieces: a register bound from two sittings,
a scan whose plate belongs to somebody other than whoever holds the paper. Here
each page carries a packet of its own, the plate on the second page carries one
too, and the transcription of each sitting is tied to the page it transcribes
rather than to the file at large. A paperclip in the top corner of each page opens that
transcription.

Tying a carried file to anything but the document as a whole arrived with PDF
2.0, so the file declares 2.0. Nothing is raised on the caller's behalf: a file
that tied one while declaring less would be refused rather than written.

The words are held in `Words`, once per language, and `HQF_PDF_LANG` picks which
set the register is bound in. Every one of them is written twice: once on the
page and once in the packet the page carries, from the one set, so that what a
person reads and what a machine reads cannot drift apart. What is not a word
stands apart from them — the names the carried files are looked up by, the
clerks' own names, and the dates the sittings were written down.

Usage: python examples/write_provenance.py [out.pdf] [font.ttf]
       HQF_PDF_LANG=fr python examples/write_provenance.py
"""

from __future__ import annotations

from dataclasses import dataclass
from pathlib import Path

import _language
import _licence
import _out

import hqf_pdf

# A4, in points.
SHEET = (595.276, 841.890)

# How far in from the edge of the sheet everything is set.
MARGIN = 64.0

# How far in from the left edge what a part says stands, leaving the label to its left.
SAID = 220.0

# How wide the plate is drawn on the page, in points.
PLATE = 180.0

# The name the record of the scan is carried under.
SCAN = "plate-12-scan.xml"

# The two sittings the register is bound from: who wrote each down, when, and the name
# its transcription is carried under. What the page says of it is a word, and stands in
# `Words` under the same order.
SITTINGS = (
    ("R. Delaunay", "1911-03-14T09:00:00+01:00", "first-sitting.xml"),
    ("M. Aubert", "1911-06-02T14:30:00+02:00", "second-sitting.xml"),
)


@dataclass(frozen=True)
class Words:
    """Every word the register is bound in, in one language."""

    # What the file says it is.
    title: str
    # What each sitting is called, in its band and in its own packet.
    sittings: tuple[str, str]
    # What whoever wrote a sitting down is called, set after their name.
    clerk: str
    # What a page says it is about.
    subject: str
    # What each page says under its band.
    lines: tuple[tuple[str, str, str], tuple[str, str, str]]
    # The heading over what a page says of itself, the one over what the file carries,
    # and the one over what the plate says of itself.
    headings: tuple[str, str, str]
    # What a part is asked about: its title, the hand that wrote it, when it was
    # written, and the file tied to it.
    asked: tuple[str, str, str, str]
    # What claims each carried file, in the order they are carried.
    claimed_by: tuple[str, str, str]
    # The row that says the file at large claims none of them.
    at_large: tuple[str, str]
    # What the plate is called, on the page and in its own packet.
    plate: str
    # What the plate is asked, and who answers to it.
    holder: tuple[str, str]
    # What the plate says it is about.
    plate_subject: str
    # What each carried file says it is: a transcription, and the record of a scan.
    carried: tuple[str, str]
    # The closing note at the foot of the last page.
    closing: tuple[str, str, str, str]

    def hand(self, index: int) -> str:
        """Who wrote the sitting at `index` down: their name, then what such a person is
        called."""
        return f"{SITTINGS[index][0]}, {self.clerk}"


# The register in English.
ENGLISH = Words(
    title="A register bound from two sittings",
    sittings=("First sitting", "Second sitting"),
    clerk="clerk",
    subject="One sitting of the register",
    lines=(
        (
            "This page carries a packet of its own, saying what it is, whose hand",
            "wrote it and when. The file says nothing on its behalf: read the page",
            "out of the file and what it says travels with it.",
        ),
        (
            "The plate below is a part in its own right. It says who holds it, which",
            "is not who holds the paper, and it carries the record of the scan it",
            "came off — tied to the plate, not to the file.",
        ),
    ),
    headings=(
        "What this page says about itself",
        "What this file carries, and which part claims it",
        "What the plate says about itself",
    ),
    asked=(
        "Its title",
        "The hand that wrote it",
        "When it was written",
        "The file tied to it",
    ),
    claimed_by=(
        "The first page",
        "The second page",
        "The plate on the second page",
    ),
    at_large=("Claimed by the file at large", "nothing"),
    plate="Plate 12, second sitting",
    holder=("Who holds it", "Departmental archive"),
    plate_subject="The plate, which is held apart from the paper",
    carried=("The sitting, transcribed", "How the plate was scanned"),
    closing=(
        "Every carried file is offered to every reader through the list of embedded",
        "files, whichever part of the document claims it. What the tie adds is which",
        "part it belongs to — and a file one part claims leaves the tie the document",
        "itself holds, so nothing is ever said to belong to two things at once.",
    ),
)

# The register in French.
FRENCH = Words(
    title="Deux séances reliées en un registre",
    sittings=("Première séance", "Deuxième séance"),
    clerk="greffier",
    subject="Une séance du registre",
    lines=(
        (
            "Cette page a son propre paquet, qui dit ce qu’elle est, quelle",
            "main l’a écrite et quand. Le fichier ne parle pas pour elle :",
            "sortez la page du fichier, ce qu’elle dit part avec elle.",
        ),
        (
            "La planche ci-dessous est une pièce à part entière. Elle dit qui la",
            "détient, qui n’est pas le détenteur du papier, et elle comporte le",
            ("relevé de la numérisation dont elle est issue — lié à elle, pas au "
             "fichier."),
        ),
    ),
    headings=(
        "Ce que cette page dit d’elle-même",
        "Ce que ce fichier contient, et quelle partie le revendique",
        "Ce que la planche dit d’elle-même",
    ),
    asked=(
        "Son titre",
        "La main qui l’a écrite",
        "Quand elle a été écrite",
        "Le fichier qui lui est lié",
    ),
    claimed_by=(
        "La première page",
        "La deuxième page",
        "La planche de la deuxième page",
    ),
    at_large=("Revendiqué par le fichier entier", "rien"),
    plate="Planche 12, deuxième séance",
    holder=("Qui la détient", "Archives départementales"),
    plate_subject="La planche, détenue séparément du papier",
    carried=("La séance, transcrite", "Comment la planche a été numérisée"),
    closing=(
        "Chaque fichier joint est proposé à tout lecteur par la liste des pièces",
        "jointes, quelle que soit la partie du document qui le revendique. Le lien",
        ("indique à quelle partie il appartient — et un fichier qu’une partie "
         "revendique"),
        ("quitte le lien du document : rien n’appartient jamais à deux choses à la "
         "fois."),
    ),
)

# The register in Dutch.
DUTCH = Words(
    title="Een register gebonden uit twee zittingen",
    sittings=("Eerste zitting", "Tweede zitting"),
    clerk="griffier",
    subject="Eén zitting van het register",
    lines=(
        (
            "Deze pagina heeft een eigen pakket, dat zegt wat ze is, wiens hand",
            "haar schreef en wanneer. Het bestand zegt niets namens haar: haal de pagina",
            "uit het bestand en wat ze zegt reist met haar mee.",
        ),
        (
            "De plaat hieronder is een deel op zichzelf. Ze zegt wie haar beheert,",
            "en dat is niet wie het papier beheert, en ze bevat het verslag van de scan",
            "waar ze vandaan komt, gekoppeld aan de plaat, niet aan het bestand.",
        ),
    ),
    headings=(
        "Wat deze pagina over zichzelf zegt",
        "Wat dit bestand bevat, en welk deel het claimt",
        "Wat de plaat over zichzelf zegt",
    ),
    asked=(
        "De titel",
        "De hand die haar schreef",
        "Wanneer ze geschreven is",
        "Het eraan gekoppelde bestand",
    ),
    claimed_by=(
        "De eerste pagina",
        "De tweede pagina",
        "De plaat op de tweede pagina",
    ),
    at_large=("Geclaimd door het bestand als geheel", "niets"),
    plate="Plaat 12, tweede zitting",
    holder=("Wie haar beheert", "Departementaal archief"),
    plate_subject="De plaat, die apart van het papier bewaard wordt",
    carried=("De zitting, uitgeschreven", "Hoe de plaat gescand is"),
    closing=(
        "Elk bijgevoegd bestand wordt aan elke lezer aangeboden via de lijst van ingesloten",
        "bestanden, welk deel van het document het ook claimt. De koppeling voegt toe bij welk",
        "deel het hoort, en een bestand dat een deel claimt, verlaat de koppeling van het",
        "document zelf, dus wordt nooit gezegd dat iets bij twee dingen tegelijk hoort.",
    ),
)

# The register in Portuguese.
PORTUGUESE = Words(
    title="Um registo encadernado de duas sessões",
    sittings=("Primeira sessão", "Segunda sessão"),
    clerk="escrivão",
    subject="Uma sessão do registo",
    lines=(
        (
            "Esta página leva um pacote próprio, que diz o que é, de que mão",
            "é e quando. O ficheiro não diz nada em seu nome: tire a página",
            "do ficheiro e o que ela diz viaja com ela.",
        ),
        (
            "A estampa abaixo é uma parte de pleno direito. Diz quem a guarda,",
            "que não é quem guarda o papel, e leva o registo da digitalização",
            "de onde saiu, ligado à estampa e não ao ficheiro.",
        ),
    ),
    headings=(
        "O que esta página diz de si mesma",
        "O que este ficheiro leva, e que parte o reclama",
        "O que a estampa diz de si mesma",
    ),
    asked=(
        "O seu título",
        "A mão que a escreveu",
        "Quando foi escrita",
        "O ficheiro ligado a ela",
    ),
    claimed_by=(
        "A primeira página",
        "A segunda página",
        "A estampa da segunda página",
    ),
    at_large=("Reclamado pelo ficheiro no seu todo", "nada"),
    plate="Estampa 12, segunda sessão",
    holder=("Quem a guarda", "Arquivo distrital"),
    plate_subject="A estampa, guardada à parte do papel",
    carried=("A sessão, transcrita", "Como a estampa foi digitalizada"),
    closing=(
        "Cada ficheiro incluído é dado a qualquer leitor pela lista de ficheiros incorporados,",
        "seja qual for a parte do documento que o reclame. A ligação acrescenta a que parte",
        "pertence, e um ficheiro que uma parte reclama sai da ligação que o próprio documento",
        "guarda, por isso nunca se diz que algo pertence a duas coisas ao mesmo tempo.",
    ),
)

# The register in Italian.
ITALIAN = Words(
    title="Un registro rilegato da due sedute",
    sittings=("Prima seduta", "Seconda seduta"),
    clerk="cancelliere",
    subject="Una seduta del registro",
    lines=(
        (
            "Questa pagina porta un pacchetto proprio, che dice cos’è, di quale mano",
            "è e quando. Il file non dice nulla per lei: estraete la pagina",
            "dal file e ciò che dice viaggia con essa.",
        ),
        (
            "La tavola qui sotto è una parte a pieno titolo. Dice chi la custodisce,",
            "che non è chi custodisce la carta, e porta la registrazione della scansione",
            "da cui viene, legata alla tavola e non al file.",
        ),
    ),
    headings=(
        "Ciò che questa pagina dice di sé",
        "Ciò che porta questo file, e quale parte lo rivendica",
        "Ciò che la tavola dice di sé",
    ),
    asked=(
        "Il suo titolo",
        "La mano che l’ha scritta",
        "Quando è stata scritta",
        "Il file legato a essa",
    ),
    claimed_by=(
        "La prima pagina",
        "La seconda pagina",
        "La tavola della seconda pagina",
    ),
    at_large=("Rivendicato dal file nel suo insieme", "nulla"),
    plate="Tavola 12, seconda seduta",
    holder=("Chi la custodisce", "Archivio dipartimentale"),
    plate_subject="La tavola, custodita separatamente dalla carta",
    carried=("La seduta, trascritta", "Come è stata scansionata la tavola"),
    closing=(
        "Ogni file incorporato è offerto a ogni lettore dall’elenco dei file incorporati,",
        "qualunque parte del documento lo rivendichi. Il legame aggiunge a quale parte",
        "appartiene, e un file rivendicato da una parte esce dal legame che tiene il documento",
        "stesso, così non si dice mai che qualcosa appartenga a due cose insieme.",
    ),
)

# The register in Spanish.
SPANISH = Words(
    title="Un registro encuadernado de dos sesiones",
    sittings=("Primera sesión", "Segunda sesión"),
    clerk="escribano",
    subject="Una sesión del registro",
    lines=(
        (
            "Esta página lleva un paquete propio que dice qué es, de qué mano",
            "salió y cuándo. El archivo no dice nada en su nombre: saque la página",
            "del archivo y lo que dice viaja con ella.",
        ),
        (
            "La lámina de abajo es una parte por derecho propio. Dice quién la custodia,",
            "que no es quien custodia el papel, y lleva el registro del escaneo del",
            "que salió, atado a la lámina y no al archivo.",
        ),
    ),
    headings=(
        "Lo que esta página dice de sí misma",
        "Lo que lleva este archivo, y qué parte lo reclama",
        "Lo que la lámina dice de sí misma",
    ),
    asked=(
        "Su título",
        "La mano que la escribió",
        "Cuándo se escribió",
        "El archivo atado a ella",
    ),
    claimed_by=(
        "La primera página",
        "La segunda página",
        "La lámina de la segunda página",
    ),
    at_large=("Reclamado por el archivo entero", "nada"),
    plate="Lámina 12, segunda sesión",
    holder=("Quién la custodia", "Archivo departamental"),
    plate_subject="La lámina, que se guarda aparte del papel",
    carried=("La sesión, transcrita", "Cómo se escaneó la lámina"),
    closing=(
        "Cada archivo incrustado se ofrece al lector en la lista de archivos incrustados,",
        "sea cual sea la parte del documento que lo reclame. El vínculo añade a qué parte",
        "pertenece, y un archivo que reclama una parte sale del vínculo que guarda el propio",
        "documento, así que nunca se dice que algo pertenezca a dos cosas a la vez.",
    ),
)

# The register in German.
GERMAN = Words(
    title="Ein aus zwei Sitzungen gebundenes Register",
    sittings=("Erste Sitzung", "Zweite Sitzung"),
    clerk="Schreiber",
    subject="Eine Sitzung des Registers",
    lines=(
        (
            "Diese Seite trägt ein eigenes Paket, das sagt, was sie ist, wessen",
            "Hand sie schrieb und wann. Die Datei spricht nicht für sie: Wer die",
            "Seite aus der Datei holt, nimmt mit, was sie sagt.",
        ),
        (
            "Die Tafel unten ist ein eigener Teil. Sie sagt, wer sie verwahrt,",
            "(ein anderer als der, der das Papier verwahrt), und trägt den Nachweis",
            "ihres Scans — an die Tafel gebunden, nicht an die Datei.",
        ),
    ),
    headings=(
        "Was diese Seite über sich sagt",
        "Was diese Datei trägt und welcher Teil es beansprucht",
        "Was die Tafel über sich sagt",
    ),
    asked=(
        "Ihr Titel",
        "Die Hand, die sie schrieb",
        "Wann sie geschrieben wurde",
        "Die daran gebundene Datei",
    ),
    claimed_by=(
        "Die erste Seite",
        "Die zweite Seite",
        "Die Tafel auf der zweiten Seite",
    ),
    at_large=("Von der Datei insgesamt beansprucht", "nichts"),
    plate="Tafel 12, zweite Sitzung",
    holder=("Wer sie verwahrt", "Abteilungsarchiv"),
    plate_subject="Die Tafel, getrennt vom Papier verwahrt",
    carried=("Die Sitzung, abgeschrieben", "Wie die Tafel gescannt wurde"),
    closing=(
        "Jede mitgeführte Datei wird jedem Leser über die Liste der eingebetteten",
        "Dateien angeboten, welcher Teil des Dokuments sie auch beansprucht. Die Bindung",
        "sagt, zu welchem Teil sie gehört — und eine von einem Teil beanspruchte Datei",
        "verlässt die Bindung des Dokuments, also gehört nichts je zwei Dingen zugleich.",
    ),
)

# 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, _language.GERMAN: GERMAN, _language.SPANISH: SPANISH, _language.ITALIAN: ITALIAN, _language.PORTUGUESE: PORTUGUESE, _language.DUTCH: DUTCH}


def plate():
    """The plate: a square of grey read off a pattern, needing no file beside it."""
    side = 64
    samples = bytes(
        ((across * 4) ^ (down * 4)) & 0xFF
        for down in range(side)
        for across in range(side)
    )
    return hqf_pdf.Image.from_gray(side, side, samples)


def head(content, font, words, index):
    """Draw the band across the head of a page, and the lines under it."""
    content.save_state()
    content.set_fill(hqf_pdf.Rgb(0.16, 0.20, 0.26))
    content.rect(0.0, SHEET[1] - 96.0, SHEET[0], 96.0)
    content.fill()
    content.set_fill(hqf_pdf.Rgb(1.0, 1.0, 1.0))
    content.draw_text(font, 20.0, MARGIN, SHEET[1] - 58.0, words.sittings[index])
    content.restore_state()

    content.save_state()
    content.set_fill(hqf_pdf.Color.gray(0.25))
    y = SHEET[1] - 140.0
    for line in words.lines[index]:
        content.draw_text(font, 11.0, MARGIN, y, line)
        y -= 18.0
    content.restore_state()


def says(content, font, top, heading, rows):
    """Draw what one part of the file says about itself, as a pair of columns."""
    content.save_state()
    content.set_stroke(hqf_pdf.Color.gray(0.82))
    content.set_line_width(0.4)
    content.move_to(MARGIN, top)
    content.line_to(SHEET[0] - MARGIN, top)
    content.stroke()
    content.restore_state()

    content.save_state()
    content.set_fill(hqf_pdf.Color.gray(0.1))
    content.draw_text(font, 13.0, MARGIN, top - 28.0, heading)
    content.restore_state()

    content.save_state()
    content.set_fill(hqf_pdf.Color.gray(0.3))
    y = top - 56.0
    for said, written in rows:
        content.draw_text(font, 11.0, MARGIN, y, said)
        content.draw_text(font, 10.0, MARGIN + SAID, y, written)
        y -= 20.0
    content.restore_state()


def foot(content, font, words):
    """Draw the closing note, at the foot of the last page."""
    content.save_state()
    content.set_fill(hqf_pdf.Color.gray(0.45))
    y = 178.0
    for line in words.closing:
        content.draw_text(font, 10.5, MARGIN, y, line)
        y -= 17.0
    content.set_fill(hqf_pdf.Color.gray(0.5))
    content.draw_text(font, 8.0, MARGIN, 62.0, "HQF Development")
    content.restore_state()


def first_sheet(font, words):
    """The first page: what it says of itself, and the transcription tied to it."""
    content = hqf_pdf.Content()
    head(content, font, words, 0)
    says(
        content,
        font,
        SHEET[1] - 220.0,
        words.headings[0],
        (
            (words.asked[0], words.sittings[0]),
            (words.asked[1], words.hand(0)),
            (words.asked[2], SITTINGS[0][1]),
            (words.asked[3], SITTINGS[0][2]),
        ),
    )
    says(
        content,
        font,
        SHEET[1] - 380.0,
        words.headings[1],
        (
            (SITTINGS[0][2], words.claimed_by[0]),
            (SITTINGS[1][2], words.claimed_by[1]),
            (SCAN, words.claimed_by[2]),
            (words.at_large[0], words.at_large[1]),
        ),
    )
    return content


def second_sheet(font, image, words):
    """The second page: the plate, what it says of itself, and the note."""
    content = hqf_pdf.Content()
    head(content, font, words, 1)

    top = SHEET[1] - 220.0
    content.draw_image(image, MARGIN, top - PLATE, PLATE, PLATE)
    content.save_state()
    content.set_stroke(hqf_pdf.Color.gray(0.7))
    content.set_line_width(0.5)
    content.rect(MARGIN, top - PLATE, PLATE, PLATE)
    content.stroke()
    content.set_fill(hqf_pdf.Color.gray(0.45))
    content.draw_text(font, 9.0, MARGIN, top - PLATE - 14.0, words.plate)
    content.restore_state()

    says(
        content,
        font,
        top - PLATE - 44.0,
        words.headings[2],
        (
            (words.asked[0], words.plate),
            (words.holder[0], words.holder[1]),
            (words.asked[3], SCAN),
        ),
    )
    foot(content, font, words)
    return content


def said_by(words, index):
    """The packet a page speaks in: what it is, whose hand wrote it, and when."""
    return hqf_pdf.Xmp.facts(
        hqf_pdf.Metadata(
            title=words.sittings[index],
            author=words.hand(index),
            subject=words.subject,
            created=SITTINGS[index][1],
        )
    )


def transcription(words, index):
    """A transcription carried inside the file, under the name it is looked up by."""
    return hqf_pdf.Attachment(
        SITTINGS[index][2],
        words.carried[0],
        "text/xml",
        hqf_pdf.Relationship.Alternative,
        SITTINGS[index][1],
        f'<sitting hand="{words.hand(index)}"/>\n'.encode(),
    )


def paperclip(file, words):
    """A paperclip in the top corner of the sheet opening `file`, which says what it
    opens."""
    return (
        hqf_pdf.FileAttachmentAnnotation(SHEET[0] - 56.0, SHEET[1] - 56.0, file)
        .icon(hqf_pdf.AttachmentIcon.Paperclip)
        .contents(words.carried[0])
    )


def bind(document, font, image, words, carried):
    """The two pages, each carrying its own packet and the file tied to it."""
    first = hqf_pdf.Page(SHEET[0], SHEET[1])
    first.set_content(first_sheet(font, words))
    first.set_metadata(said_by(words, 0))
    first.set_associated_files([carried[0]])
    first.add_annotation(paperclip(carried[0], words))
    document.add_page(first)

    second = hqf_pdf.Page(SHEET[0], SHEET[1])
    second.set_content(second_sheet(font, image, words))
    second.set_metadata(said_by(words, 1))
    second.set_associated_files([carried[1]])
    second.add_annotation(paperclip(carried[1], words))
    document.add_page(second)


def main():
    """Write the register, and say where it went."""
    language = _language.from_environment()
    words = _language.words_of(WORDS, language)

    # 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("provenance.pdf", language)).stem)

    document = hqf_pdf.Document()
    document.set_license(_licence.licensed())
    font = document.add_font(hqf_pdf.Font.from_path(_out.font_path()))

    # Each transcription is claimed by the page it transcribes; the record of the scan
    # is claimed by the plate itself. Nothing here is claimed by the file at large, so
    # the file ties nothing to its catalogue.
    carried = [
        document.attach(transcription(words, 0)),
        document.attach(transcription(words, 1)),
    ]
    scan = document.attach(
        hqf_pdf.Attachment(
            SCAN,
            words.carried[1],
            "text/xml",
            hqf_pdf.Relationship.Supplement,
            "2026-02-19T11:05:00+01:00",
            b'<scan dpi="600" bits="8"/>\n',
        )
    )

    image = document.add_image(
        plate()
        .with_metadata(
            hqf_pdf.Xmp.facts(
                hqf_pdf.Metadata(
                    title=words.plate,
                    author=words.holder[1],
                    subject=words.plate_subject,
                )
            )
        )
        .associated_with([scan])
    )

    bind(document, font, image, words, carried)

    # Tying a carried file to anything but the document as a whole is ISO 32000-2, so
    # the file says 2.0 on its first line.
    document.set_version(hqf_pdf.Version.V2_0)
    document.set_metadata(hqf_pdf.Metadata(title=words.title, producer="hqf-pdf"))

    written = document.to_bytes()
    out.write_bytes(written)
    print(f"wrote {out}: {len(written)} bytes, every part saying where it came from")


if __name__ == "__main__":
    main()