A self-paginating table

"""Hands a long table over whole, and lets it decide how many pages it needs.

The Python twin of the `write_table_paginated` example in Rust, and the shape a
document server wants: build the table, say what box it gets on the first page and
what box it gets on the ones after, and call `paginate` once. It answers with one
placement per page. The caller makes each page — here, by stamping it onto an
imported stationery template — and draws the placement onto it. No loop to write,
and no way to write it wrong: a table that could not advance raises, rather than
asking for another blank page.

Three things the table does on its own:

  - the heading row is drawn again at the top of every page;
  - the footnote row is drawn again under the last line of every page;
  - a section title is kept with the rows under it, so it is never stranded at the
    foot of a page away from what it introduces.

Under each page the caller adds a note of its own, saying which of the table's rows
the page carried and hanging its page number on the grid line between the two
columns. The placement is asked for all of it: where its rows ended, where that grid
line fell, and which rows it took.

Every word the statement draws is held in `Words`, once per language, and
`HQF_PDF_LANG` picks which one is drawn. The amounts are the same in both.

Usage: python examples/write_table_paginated.py [out.pdf] [stationery.pdf]
       HQF_PDF_LANG=fr python examples/write_table_paginated.py
"""

from __future__ import annotations

import sys
from dataclasses import dataclass
from pathlib import Path

import _language
import _licence
import _out

import hqf_pdf

PAGE_WIDTH = 595.276
MARGIN = 56.0
TABLE_WIDTH = PAGE_WIDTH - 2 * MARGIN

# The table starts below the letterhead on the first page, and higher up on every page
# after it: that is the whole reason `paginate` takes two boxes.
FIRST_TOP = 700.0
NEXT_TOP = 800.0
BOTTOM = 64.0


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

    What is not language stays out of it: the amounts, the company's name and its
    address read the same in every language.
    """

    # The line the letterhead of the stationery carries.
    letterhead: str
    # The two column headings.
    description: str
    amount: str
    # What each section is called, in the order ``SECTIONS`` gives them.
    sections: tuple[str, ...]
    # What each billed line is called, section after section.
    lines: tuple[str, ...]
    # The label of the boxed total.
    total: str
    # The footnote repeated under the last line of every page.
    footnote: str
    # The caller's own note, cut where the row numbers go into it.
    rows_before: str
    rows_between: str
    rows_of: str
    # The same for the page number.
    page_before: str
    page_of: str


# The statement in English.
ENGLISH = Words(
    letterhead="ACME Ltd — statement of services",
    description="Description",
    amount="Amount",
    sections=(
        "Development",
        "Reworking what was there",
        "Support",
        "Audit",
    ),
    lines=(
        "Rendering engine",
        "Font engine",
        "Glyph subsetting",
        "Charstring interpreter",
        "Tables and layout",
        "Invoice template",
        "Data migration",
        "Acceptance testing and fixes",
        "Team training",
        "Standby cover for the release night",
        "First year of support",
        "Technical documentation",
        "Performance audit",
        "Security audit",
        "Architecture review",
    ),
    total="Total due",
    footnote=(
        "Amounts in euros, exclusive of value added tax. ACME Ltd, "
        "Bureau 4, 12 rue des Fabriques, 59000 Lille."
    ),
    rows_before="Rows ",
    rows_between=" to ",
    rows_of=" of ",
    page_before="Page ",
    page_of=" of ",
)

# The statement in French.
FRENCH = Words(
    letterhead="ACME Ltd — relevé de prestations",
    description="Désignation",
    amount="Montant",
    sections=(
        "Développement",
        "Reprise de l'existant",
        "Assistance",
        "Audit",
    ),
    lines=(
        "Moteur de rendu",
        "Moteur de polices",
        "Réduction des polices aux glyphes utilisés",
        "Interpréteur de contours de glyphes",
        "Tableaux et mise en page",
        "Modèle de facture",
        "Migration des données",
        "Recette et corrections",
        "Formation de l'équipe",
        "Astreinte la nuit de la mise en production",
        "Première année d'assistance",
        "Documentation technique",
        "Audit de performance",
        "Audit de sécurité",
        "Revue d'architecture",
    ),
    total="Total dû",
    footnote=(
        "Montants en euros, hors taxe sur la valeur ajoutée. ACME Ltd, "
        "Bureau 4, 12 rue des Fabriques, 59000 Lille."
    ),
    rows_before="Lignes ",
    rows_between=" à ",
    rows_of=" sur ",
    page_before="Page ",
    page_of=" sur ",
)


# 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 a_stationery(font_path, words: Words) -> bytes:
    """The stationery every page is stamped onto, for when the caller has none."""
    document = hqf_pdf.Document()
    document.set_license(_licence.licensed())
    font = document.add_font(hqf_pdf.Font.from_path(font_path))

    content = hqf_pdf.Content()
    content.save_state()
    content.set_fill(hqf_pdf.Rgb(0.91, 0.94, 0.98))
    content.rect(0.0, 812.0, PAGE_WIDTH, 30.0)
    content.fill()
    content.set_fill(hqf_pdf.Rgb(0.2, 0.35, 0.6))
    content.rect(0.0, 809.0, PAGE_WIDTH, 3.0)
    content.fill()
    content.restore_state()

    content.draw_text(font, 13.0, MARGIN, 820.0, words.letterhead)

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


@dataclass(frozen=True)
class Section:
    """One section of the statement: what each of its lines is billed, in the order
    ``Words.lines`` names them."""

    lines: tuple[float, ...]


SECTIONS = (
    Section((7440.0, 4960.0, 2480.0, 3720.0, 5580.0)),
    Section((1440.0, 2700.0, 2880.0)),
    Section((1500.0, 1200.0, 4200.0, 1260.0)),
    Section((2760.0, 3100.0, 1850.0)),
)


def amount(value: float) -> str:
    """An amount, as a statement writes it: "4 250.00 EUR"."""
    units, hundredths = f"{value:.2f}".split(".")
    grouped = ""
    for index, digit in enumerate(units):
        if index > 0 and (len(units) - index) % 3 == 0:
            grouped += " "
        grouped += digit
    return f"{grouped}.{hundredths} EUR"


def statement(font: hqf_pdf.FontHandle, words: Words) -> hqf_pdf.Table:
    """The statement, as one table: a heading, then every section, four times over
    so that it runs well past a single page."""
    columns = hqf_pdf.Columns(
        [hqf_pdf.ColumnWidth.fraction(1.0), hqf_pdf.ColumnWidth.points(110.0)],
        TABLE_WIDTH,
    )

    table = hqf_pdf.Table(columns)
    # The heading row is drawn again at the top of every page, and the footnote row
    # under the last line of every page.
    table.header(1)
    table.footer(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.75))
    )
    table.rule(hqf_pdf.Rule.horizontal(1), hqf_pdf.Stroke(0.8))
    # The shading is said once, for the table, rather than cell by cell: every other row
    # faintly, and the heading over the top of that.
    table.fill(hqf_pdf.Area.even_rows(), hqf_pdf.Rgb.gray(0.97))
    table.fill(hqf_pdf.Area.header(), hqf_pdf.Rgb.gray(0.88))

    pad = hqf_pdf.Padding.symmetric(5.0, 4.0)

    def heading(label: str, align: hqf_pdf.Align) -> hqf_pdf.Cell:
        return hqf_pdf.Cell(
            font,
            9.0,
            label,
            padding=pad,
            align=align,
            valign=hqf_pdf.VAlign.Middle,
        )

    table.push(
        hqf_pdf.Row(
            [
                heading(words.description, hqf_pdf.Align.Left),
                heading(words.amount, hqf_pdf.Align.Right),
            ],
            min_height=20.0,
        )
    )

    for round_ in range(4):
        line = 0
        for section, title in zip(SECTIONS, words.sections):
            # The section title is kept with the first line under it: a title alone at
            # the foot of a page introduces nothing.
            table.push(
                hqf_pdf.Row(
                    [
                        hqf_pdf.Cell(
                            font,
                            9.5,
                            f"{title} ({round_ + 1})",
                            padding=pad,
                            span=2,
                            fill=hqf_pdf.Rgb.gray(0.93),
                            border=hqf_pdf.Border(bottom=hqf_pdf.Stroke(0.5)),
                        )
                    ],
                    min_height=18.0,
                    keep_with_next=True,
                )
            )

            for value in section.lines:
                label = words.lines[line]
                line += 1
                table.push(
                    hqf_pdf.Row(
                        [
                            hqf_pdf.Cell(font, 9.0, label, padding=pad),
                            hqf_pdf.Cell(
                                font,
                                9.0,
                                amount(value),
                                padding=pad,
                                align=hqf_pdf.Align.Right,
                            ),
                        ],
                        min_height=16.0,
                    )
                )

    # The total, boxed, and kept with nothing: it ends the table.
    total = sum(value for s in SECTIONS for value in s.lines) * 4
    rule = hqf_pdf.Stroke(0.8)
    box_margin = hqf_pdf.Margin.symmetric(0.0, 2.0)
    table.push(
        hqf_pdf.Row(
            [
                hqf_pdf.Cell(
                    font,
                    10.0,
                    words.total,
                    padding=pad,
                    align=hqf_pdf.Align.Right,
                    margin=box_margin,
                    border=hqf_pdf.Border(top=rule, bottom=rule, left=rule),
                ),
                hqf_pdf.Cell(
                    font,
                    10.0,
                    amount(total),
                    padding=pad,
                    align=hqf_pdf.Align.Right,
                    margin=box_margin,
                    border=hqf_pdf.Border(top=rule, bottom=rule, right=rule),
                ),
            ],
            min_height=20.0,
        )
    )

    # The footnote, repeated under the last line of every page.
    table.push(
        hqf_pdf.Row(
            [
                hqf_pdf.Cell(
                    font,
                    7.5,
                    words.footnote,
                    padding=pad,
                    span=2,
                    color=hqf_pdf.Rgb.gray(0.45),
                ),
            ],
            space_before=6.0,
        )
    )

    return table


def continuation_note(
    content: hqf_pdf.Content,
    font: hqf_pdf.FontHandle,
    words: Words,
    placed: hqf_pdf.Placement,
    page: int,
    pages: int,
    rows: int,
) -> None:
    """Draws the caller's own note under a page's table.

    Everything it needs comes from the placement: where the rows ended, where the
    table's left edge and the grid line between its two columns fell, and which of
    the table's rows this page carried. Nothing here counts rows or adds heights on
    the side, so the note cannot drift away from the table it describes.
    """
    body = placed.body_rows
    if body is None:
        return
    baseline = placed.bottom - 12.0

    content.save_state()
    content.set_fill(hqf_pdf.Rgb(0.45, 0.45, 0.45))
    content.draw_text(
        font,
        7.5,
        placed.x,
        baseline,
        f"{words.rows_before}{body.start}{words.rows_between}"
        f"{body.stop - 1}{words.rows_of}{rows}",
    )

    line = placed.column_x(1)
    if line is not None:
        content.draw_text(
            font,
            7.5,
            line,
            baseline,
            f"{words.page_before}{page + 1}{words.page_of}{pages}",
        )

    content.restore_state()


def main() -> None:
    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("paginated.pdf", language)).stem)
    font_path = _out.DEFAULT_FONT

    # The stationery every page is stamped onto: the caller's, or one made here.
    if len(sys.argv) > 2:
        stationery = open(sys.argv[2], "rb").read()
    else:
        stationery = a_stationery(font_path, words)
    reader = hqf_pdf.Reader(stationery)

    document = hqf_pdf.Document()
    document.set_license(_licence.licensed())
    template = document.import_page(reader, 0)
    font = document.add_font(hqf_pdf.Font.from_path(font_path))

    table = statement(font, words)

    # The whole of pagination: one call, one placement per page.
    pages = table.paginate(
        hqf_pdf.Frame(MARGIN, FIRST_TOP, FIRST_TOP - BOTTOM),
        hqf_pdf.Frame(MARGIN, NEXT_TOP, NEXT_TOP - BOTTOM),
    )

    for index, placed in enumerate(pages):
        content = hqf_pdf.Content()
        # The stationery goes down first, and the table on top of it.
        content.draw_form(template, 0.0, 0.0, 1.0)
        placed.draw(content)
        continuation_note(
            content, font, words, placed, index, len(pages), table.row_count
        )

        page = hqf_pdf.Page.a4()
        page.set_content(content)
        # The stationery is a form, and a page may only draw what its resources name.
        template.add_to(page)
        document.add_page(page)

    written = document.write(out)
    print(f"wrote {out}: {written} bytes, {len(pages)} pages, {table.row_count} rows")


if __name__ == "__main__":
    main()