A multi-page invoice table

"""Lays an invoice table out across as many pages as its lines need.

The Python twin of the `write_table` example in Rust, and the one worth reading
first: the table is longer than a page, so it is fitted, drawn, and continued.
The row it stopped at is where the next page picks up, and the headings are drawn
again at the top of each one.

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

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

from __future__ import annotations

from dataclasses import dataclass
from pathlib import Path

import _language
import _licence
import _out

import hqf_pdf

# The margins, and the box the table is fitted into on every page.
MARGIN = 56.0
TOP = 780.0
BOTTOM = 64.0
PAGE_WIDTH = 595.276
TABLE_WIDTH = PAGE_WIDTH - 2 * MARGIN


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

    What is not language stays out of it: the quantities and the unit prices are drawn
    from ``ITEMS`` and read the same in every language.
    """

    # What each billed line is called, in the order ``ITEMS`` bills them.
    items: tuple[str, ...]
    # The four column headings.
    description: str
    quantity: str
    unit_price: str
    amount: str
    # The three totals under the billed lines.
    subtotal: str
    tax: str
    total: str


# The table in English.
ENGLISH = Words(
    items=(
        "Rendering engine development",
        "Font engine integration, including cutting each face down to the glyphs "
        "actually drawn",
        "Invoice template rework",
        "Historical data migration",
        "Acceptance testing and fixes",
        "Team training",
        "Standby cover for the release night",
        "Performance audit",
        "Technical documentation",
        "First year of support",
    ),
    description="Description",
    quantity="Qty",
    unit_price="Unit price",
    amount="Amount",
    subtotal="Subtotal",
    tax="VAT at 20 %",
    total="Total due",
)

# The table in French.
FRENCH = Words(
    items=(
        "Développement du moteur de rendu",
        "Intégration du moteur de polices, avec réduction de chaque police aux "
        "seuls glyphes dessinés",
        "Refonte du modèle de facture",
        "Migration des données historiques",
        "Recette et corrections",
        "Formation de l'équipe",
        "Astreinte la nuit de la mise en production",
        "Audit de performance",
        "Documentation technique",
        "Première année de support",
    ),
    description="Désignation",
    quantity="Qté",
    unit_price="Prix unitaire",
    amount="Montant",
    subtotal="Total HT",
    tax="TVA 20 %",
    total="Total TTC",
)


# 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}


@dataclass(frozen=True)
class Item:
    """One line of the invoice."""

    quantity: int
    unit_price: float


# The lines the invoice bills, in the order ``Words.items`` names them.
ITEMS = [
    Item(12, 620.0),
    Item(8, 620.0),
    Item(3, 480.0),
    Item(5, 540.0),
    Item(6, 480.0),
    Item(2, 750.0),
    Item(1, 1200.0),
    Item(4, 690.0),
    Item(3, 420.0),
    Item(12, 350.0),
]


def amount(value: float) -> str:
    """An amount, as an invoice 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 invoice_table(font: hqf_pdf.FontHandle, words: Words) -> hqf_pdf.Table:
    """The invoice's table: a heading row, the billed lines, and the totals."""
    # The designation takes whatever the three figure columns leave it.
    columns = hqf_pdf.Columns(
        [
            hqf_pdf.ColumnWidth.fraction(1.0),
            hqf_pdf.ColumnWidth.points(46.0),
            hqf_pdf.ColumnWidth.points(94.0),
            hqf_pdf.ColumnWidth.points(94.0),
        ],
        TABLE_WIDTH,
    )

    table = hqf_pdf.Table(columns)
    table.header(1)
    table.rule(hqf_pdf.Rule.frame(), hqf_pdf.Stroke(0.8))
    hairline = hqf_pdf.Stroke(0.25, hqf_pdf.Rgb.gray(0.75))
    table.rule(hqf_pdf.Rule.horizontal_other(), hairline)
    table.rule(hqf_pdf.Rule.vertical_other(), hairline)
    # Under the headings, and above the totals.
    table.rule(hqf_pdf.Rule.horizontal(1), hqf_pdf.Stroke(0.8))
    table.rule(hqf_pdf.Rule.horizontal_from_end(1), hqf_pdf.Stroke(0.8))

    pad = hqf_pdf.Padding.symmetric(5.0, 4.0)
    shade = hqf_pdf.Rgb.gray(0.88)

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

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

    # The lines are billed five times over, so that the table runs past a page and its
    # continuation can be seen.
    total = 0.0
    for index in range(len(ITEMS) * 5):
        item = ITEMS[index % len(ITEMS)]
        label = words.items[index % len(ITEMS)]
        line_total = item.quantity * item.unit_price
        total += line_total

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

        table.push(
            hqf_pdf.Row(
                [
                    hqf_pdf.Cell(font, 9.0, label, padding=pad),
                    figure(str(item.quantity)),
                    figure(amount(item.unit_price)),
                    figure(amount(line_total)),
                ],
                min_height=18.0,
                # Every other line is shaded, which is what a row fill is for.
                fill=hqf_pdf.Rgb.gray(0.97) if index % 2 else None,
            )
        )

    tax = total * 0.2
    for label, value, size, is_grand_total in (
        (words.subtotal, total, 9.0, False),
        (words.tax, tax, 9.0, False),
        (words.total, total + tax, 10.0, True),
    ):
        # The grand total is boxed in a border of its own, held off the grid by a margin
        # so that it reads as a total rather than as one more line of the table. The box
        # is drawn side by side: the label carries its left edge and the figure its
        # right, so the two cells trace one box between them rather than a box each.
        if is_grand_total:
            rule = hqf_pdf.Stroke(0.8)
            label_border = hqf_pdf.Border(top=rule, bottom=rule, left=rule)
            value_border = hqf_pdf.Border(top=rule, bottom=rule, right=rule)
            box_margin = hqf_pdf.Margin.symmetric(0.0, 2.0)
        else:
            label_border = value_border = hqf_pdf.Border.none()
            box_margin = hqf_pdf.Margin()

        table.push(
            hqf_pdf.Row(
                [
                    hqf_pdf.Cell(
                        font,
                        size,
                        label,
                        span=3,
                        align=hqf_pdf.Align.Right,
                        padding=pad,
                        margin=box_margin,
                        border=label_border,
                    ),
                    hqf_pdf.Cell(
                        font,
                        size,
                        amount(value),
                        align=hqf_pdf.Align.Right,
                        padding=pad,
                        margin=box_margin,
                        border=value_border,
                    ),
                ],
                min_height=18.0,
            )
        )

    return table


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

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

    table = invoice_table(font, words)

    # Fit, draw, and continue on a new page for as long as rows remain.
    start = 0
    pages = 0
    while True:
        placed = table.fit(MARGIN, TOP, TOP - BOTTOM, start)

        content = hqf_pdf.Content()
        placed.draw(content)

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

        if placed.done:
            break
        start = placed.next_row

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


if __name__ == "__main__":
    main()