A pack built on three supplied sheets

"""Assembles a document onto three PDFs somebody else made: one behind its first
page, one behind every page in the middle, and one that goes in whole as its last
page.

The Python twin of the `write_imported_pages` example in Rust. This is what a
document server is asked for most often. The customer sends stationery — a headed
sheet, a plain continuation sheet, a page of standing conditions — and the document
has to be laid on it without any of it being redrawn. Each sheet is read, brought in
as a form, and stamped under what this example draws. The conditions sheet carries
nothing of its own but the page number, and is a counted page like the rest.

The page the schedule needs is decided by the schedule: the table is handed over
whole and says how many pages it takes, so the continuation sheet backs as many
pages as there turn out to be.

The three sheets may be handed over on the command line. With none given, the
example writes them itself, so it runs on any machine.

Usage: python examples/write_imported_pages.py [out.pdf]
       [headed.pdf continuation.pdf conditions.pdf]
"""

from __future__ import annotations

import sys
from dataclasses import dataclass
from typing import Callable

import _licence
import _out

import hqf_pdf

# A4, in points.
PAGE_WIDTH = 595.276
# The page's left edge and, mirrored, its right.
LEFT = 56.0
RIGHT = PAGE_WIDTH - LEFT
# The width the table is fitted across.
TABLE_WIDTH = PAGE_WIDTH - 2 * LEFT
# Where the second column of the two address blocks begins.
SECOND_COLUMN = 320.0

# The ink the headings and rules are drawn in, and the grey of the small print.
ACCENT = hqf_pdf.Rgb(0.11, 0.33, 0.55)
MUTED = hqf_pdf.Rgb(0.42, 0.42, 0.45)
INK = hqf_pdf.Rgb(0.1, 0.1, 0.12)

# The agreement this pack schedules, and the day it was drawn up.
REFERENCE = "SA-2027-0088"
DRAWN_UP = "12 March 2027"

# The box the schedule is fitted into, on whichever page it lands.
TABLE_TOP = 780.0
TABLE_BOTTOM = 80.0


def text(
    content: hqf_pdf.Content,
    font: hqf_pdf.FontHandle,
    size: float,
    x: float,
    y: float,
    color: hqf_pdf.Rgb,
    s: str,
) -> None:
    """Draws a line of text with its left edge at ``x`` and its baseline at ``y``."""
    content.set_fill(color)
    content.draw_text(font, size, x, y, s)


def text_right(
    content: hqf_pdf.Content,
    font: hqf_pdf.FontHandle,
    size: float,
    right: float,
    y: float,
    color: hqf_pdf.Rgb,
    s: str,
) -> None:
    """Draws a line of text whose right edge sits at ``right``."""
    text(content, font, size, right - font.measure(s, size), y, color, s)


def rule(
    content: hqf_pdf.Content,
    x1: float,
    x2: float,
    y: float,
    width: float,
    color: hqf_pdf.Rgb,
) -> None:
    """A horizontal rule from ``x1`` to ``x2`` at height ``y``."""
    content.set_stroke(color)
    content.set_line_width(width)
    content.move_to(x1, y)
    content.line_to(x2, y)
    content.stroke()


def full_rule(
    content: hqf_pdf.Content, y: float, width: float, color: hqf_pdf.Rgb
) -> None:
    """A rule across the whole text width, at height ``y``."""
    rule(content, LEFT, RIGHT, y, width, color)


def one_page_sheet(
    font_path, draw: Callable[[hqf_pdf.Content, hqf_pdf.FontHandle], None]
) -> bytes:
    """Puts a one-page document together from what a caller draws on it."""
    document = hqf_pdf.Document()
    document.set_license(_licence.licensed())
    font = document.add_font(hqf_pdf.Font.from_path(font_path))

    content = hqf_pdf.Content()
    draw(content, font)

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


def a_headed_sheet(font_path) -> bytes:
    """The headed sheet: a band across the top with the firm's name and address in
    it."""

    def draw(content: hqf_pdf.Content, font: hqf_pdf.FontHandle) -> None:
        content.save_state()
        content.set_fill(hqf_pdf.Rgb(0.91, 0.94, 0.98))
        content.rect(0.0, 742.0, PAGE_WIDTH, 100.0)
        content.fill()
        content.set_fill(ACCENT)
        content.rect(0.0, 738.0, PAGE_WIDTH, 4.0)
        content.fill()
        content.restore_state()

        text(content, font, 22.0, LEFT, 786.0, INK, "HQF Development")
        text(
            content,
            font,
            9.0,
            LEFT,
            764.0,
            MUTED,
            "42 lot les Genêts — 13480 Calas, France — VAT FR59 752 492 777",
        )

    return one_page_sheet(font_path, draw)


def a_continuation_sheet(font_path) -> bytes:
    """The continuation sheet: the firm's name small at the top, between two
    hairlines."""

    def draw(content: hqf_pdf.Content, font: hqf_pdf.FontHandle) -> None:
        text(
            content,
            font,
            8.0,
            LEFT,
            806.0,
            MUTED,
            "HQF Development — 42 lot les Genêts, 13480 Calas, France",
        )
        full_rule(content, 800.0, 0.5, ACCENT)
        full_rule(content, 64.0, 0.5, hqf_pdf.Rgb.gray(0.78))

    return one_page_sheet(font_path, draw)


# The clauses printed on the conditions sheet.
CLAUSES = (
    "Prices are firm for the term of this agreement, in euros, exclusive of value"
    " added tax.",
    "A batch is due on the day named in the schedule, at the address the schedule was"
    " sent to.",
    "Quantities are counted on arrival. A count that differs is settled within five"
    " working days.",
    "Payment falls thirty days after the batch arrives, by transfer to the account on"
    " the invoice.",
    "Title to a batch passes on payment. Risk passes on arrival.",
    "A batch refused on arrival is collected within ten working days, at the"
    " supplier's cost.",
    "Either party may end this agreement on ninety days' notice, in writing.",
    "Batches already scheduled at the end of the notice are supplied and paid for as"
    " scheduled.",
    "Neither party is answerable for a delay caused by an event outside its reasonable"
    " control.",
    "This agreement is governed by French law, and the courts of Aix-en-Provence hear"
    " disputes.",
    "A change to a scheduled batch takes effect only when both parties agree it in"
    " writing.",
    "The supplier keeps a certificate of conformity for each batch three years after"
    " it arrives.",
    "The customer's marks may go on cartons and cases for the term, and to no other"
    " purpose.",
    "Neither party may hand this agreement to anyone else without the other's written"
    " consent.",
    "Notices are given in writing, to the addresses printed on the first page of this"
    " pack.",
    "This pack, its schedule and these conditions are the whole of what the parties"
    " agreed.",
)


def a_conditions_sheet(font_path) -> bytes:
    """The conditions sheet: a heading and the standing clauses, one to a line."""

    def draw(content: hqf_pdf.Content, font: hqf_pdf.FontHandle) -> None:
        text(content, font, 14.0, LEFT, 780.0, INK, "Conditions of supply")
        full_rule(content, 770.0, 0.8, ACCENT)

        y = 744.0
        for index, clause in enumerate(CLAUSES):
            text(content, font, 8.5, LEFT, y, INK, f"{index + 1}. {clause}")
            y -= 26.0

        text(
            content,
            font,
            8.0,
            LEFT,
            96.0,
            MUTED,
            "HQF Development — conditions of supply, edition of 1 January 2027",
        )

    return one_page_sheet(font_path, draw)


@dataclass(frozen=True)
class Batch:
    """One line of the schedule: what is delivered, on which day of the quarter, how
    many, and the price of one."""

    label: str
    day: int
    quantity: int
    unit_price: float


# The batches a quarter delivers.
BATCHES = (
    Batch("Lens blanks, 62 mm, coated", 6, 1200, 7.20),
    Batch("Lens blanks, 68 mm, coated", 6, 900, 8.40),
    Batch("Lens blanks, 74 mm, uncoated", 9, 640, 6.15),
    Batch("Frame fronts, acetate, assorted", 13, 480, 11.90),
    Batch("Frame temples, acetate, pairs", 13, 480, 4.35),
    Batch("Hinges, sprung, stainless", 17, 2400, 0.95),
    Batch("Nose pads, silicone", 17, 3600, 0.22),
    Batch("Screws, M1.4, boxed by hundred", 20, 120, 3.10),
    Batch("Cases, hard, printed", 24, 1500, 2.65),
    Batch("Cloths, microfibre, printed", 24, 3000, 0.48),
    Batch("Cartons, shipping, printed", 27, 300, 1.75),
)

# The quarters the schedule runs over: the month a quarter's batches are due in, and its
# year.
QUARTERS = (("April", 2027), ("July", 2027), ("October", 2027), ("January", 2028))


def amount(value: float) -> str:
    """An amount, as a schedule writes it: "8 640.00"."""
    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}"


def schedule(font: hqf_pdf.FontHandle) -> hqf_pdf.Table:
    """The schedule, as one table: a heading drawn again on every page, every batch of
    every quarter, and the total of the lot."""
    columns = hqf_pdf.Columns(
        [
            hqf_pdf.ColumnWidth.fraction(1.0),
            hqf_pdf.ColumnWidth.points(92.0),
            hqf_pdf.ColumnWidth.points(58.0),
            hqf_pdf.ColumnWidth.points(78.0),
        ],
        TABLE_WIDTH,
    )

    table = hqf_pdf.Table(columns)
    table.header(1)
    table.rule(hqf_pdf.Rule.frame(), hqf_pdf.Stroke(0.8, ACCENT))
    table.rule(
        hqf_pdf.Rule.horizontal_other(), hqf_pdf.Stroke(0.25, hqf_pdf.Rgb.gray(0.78))
    )
    table.rule(hqf_pdf.Rule.horizontal(1), hqf_pdf.Stroke(0.8, ACCENT))
    table.fill(hqf_pdf.Area.even_rows(), hqf_pdf.Rgb.gray(0.97))
    table.fill(hqf_pdf.Area.header(), ACCENT)

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

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

    table.push(
        hqf_pdf.Row(
            [
                heading("Batch", hqf_pdf.Align.Left),
                heading("Due", hqf_pdf.Align.Left),
                heading("Quantity", hqf_pdf.Align.Right),
                heading("Value", hqf_pdf.Align.Right),
            ],
            min_height=20.0,
        )
    )

    total = 0.0
    for month, year in QUARTERS:
        for batch in BATCHES:
            value = batch.quantity * batch.unit_price
            total += value
            table.push(
                hqf_pdf.Row(
                    [
                        hqf_pdf.Cell(font, 9.0, batch.label, padding=pad),
                        hqf_pdf.Cell(
                            font, 9.0, f"{batch.day} {month} {year}", padding=pad
                        ),
                        hqf_pdf.Cell(
                            font,
                            9.0,
                            str(batch.quantity),
                            padding=pad,
                            align=hqf_pdf.Align.Right,
                        ),
                        hqf_pdf.Cell(
                            font,
                            9.0,
                            amount(value),
                            padding=pad,
                            align=hqf_pdf.Align.Right,
                        ),
                    ],
                    min_height=16.0,
                )
            )

    box_margin = hqf_pdf.Margin.symmetric(0.0, 2.0)
    table.push(
        hqf_pdf.Row(
            [
                hqf_pdf.Cell(
                    font,
                    10.0,
                    "Total, before tax",
                    padding=pad,
                    align=hqf_pdf.Align.Right,
                    span=3,
                    margin=box_margin,
                ),
                hqf_pdf.Cell(
                    font,
                    10.0,
                    amount(total),
                    padding=pad,
                    align=hqf_pdf.Align.Right,
                    margin=box_margin,
                ),
            ],
            min_height=20.0,
        )
    )

    return table


# The lines the front page explains the pack with, and what it stands on.
EXPLAINED = (
    "This pack stands on three sheets the customer sent as PDF files. The headed sheet"
    " is under",
    "this page. A plain continuation sheet is under every page the schedule runs to."
    " The page of",
    "standing conditions at the back is the third sheet, taken in whole and counted"
    " like the rest.",
    "",
    "None of the three is redrawn. The team reads each file, brings its page in as a"
    " drawing, and",
    "stamps it under the text — so a letterhead comes out of the printer as its owner"
    " made it, and",
    "the conditions on the last page are the ones on file, to the letter.",
)


@dataclass(frozen=True)
class Contents:
    """What the front page can say about the pack once the schedule has said how many
    pages it takes."""

    pages: int
    schedule: tuple[int, int]
    rows: int

    def lines(self) -> tuple[tuple[str, str], ...]:
        """The three lines the front page lists the pack by: which pages, and what is
        on them."""
        first, last = self.schedule
        return (
            ("Page 1", "This page, on the headed sheet."),
            (
                f"Pages {first} to {last}",
                f"The delivery schedule, {self.rows} rows, on the continuation sheet.",
            ),
            (
                f"Page {self.pages}",
                "The conditions of supply, as the customer supplied them.",
            ),
        )


def signatures(content: hqf_pdf.Content, font: hqf_pdf.FontHandle) -> None:
    """Draws the two places the parties sign, each a rule with a label under it."""
    text(content, font, 11.0, LEFT, 330.0, ACCENT, "Signed")
    text(
        content,
        font,
        9.0,
        LEFT,
        312.0,
        INK,
        "Each party signs one copy. The schedule and the conditions of supply are part"
        " of it.",
    )

    hair = hqf_pdf.Rgb.gray(0.6)
    parties = (
        (LEFT, "For HQF Development"),
        (SECOND_COLUMN, "For Meridian Optics SAS"),
    )
    for x, party in parties:
        rule(content, x, x + 210.0, 262.0, 0.5, hair)
        text(content, font, 8.0, x, 250.0, MUTED, party)
        rule(content, x, x + 210.0, 210.0, 0.5, hair)
        text(content, font, 8.0, x, 198.0, MUTED, "Name and date")


def front_page(
    content: hqf_pdf.Content, font: hqf_pdf.FontHandle, contents: Contents
) -> None:
    """The pack's front page: what it is, who it is between, what it is made of, what
    is in it, and where it is signed."""
    text(content, font, 20.0, LEFT, 700.0, ACCENT, "Supply agreement")
    text(content, font, 9.5, LEFT, 682.0, MUTED, f"{REFERENCE} — drawn up {DRAWN_UP}")
    full_rule(content, 672.0, 0.8, ACCENT)

    text(content, font, 8.0, LEFT, 652.0, MUTED, "Supplier")
    text(content, font, 8.0, SECOND_COLUMN, 652.0, MUTED, "Customer")

    supplier = ("42 lot les Genêts", "13480 Calas, France", "VAT FR59 752 492 777")
    customer = (
        "18 avenue des Peupliers",
        "69100 Villeurbanne, France",
        "VAT FR41 512 336 908",
    )
    text(content, font, 10.0, LEFT, 637.0, INK, "HQF Development")
    text(content, font, 10.0, SECOND_COLUMN, 637.0, INK, "Meridian Optics SAS")
    y = 624.0
    for theirs, ours in zip(supplier, customer):
        text(content, font, 9.0, LEFT, y, MUTED, theirs)
        text(content, font, 9.0, SECOND_COLUMN, y, MUTED, ours)
        y -= 12.0

    text(content, font, 11.0, LEFT, 566.0, ACCENT, "What this pack is made of")
    y = 548.0
    for line in EXPLAINED:
        if line:
            text(content, font, 9.0, LEFT, y, INK, line)
        y -= 13.0

    text(content, font, 11.0, LEFT, 430.0, ACCENT, "What is in it")
    y = 412.0
    for pages, what in contents.lines():
        text(content, font, 9.0, LEFT, y, INK, pages)
        text(content, font, 9.0, LEFT + 96.0, y, MUTED, what)
        y -= 16.0

    signatures(content, font)


def add_page(
    document: hqf_pdf.Document,
    sheet: hqf_pdf.ImportedPage,
    content: hqf_pdf.Content,
    font: hqf_pdf.FontHandle,
    number: int,
    pages: int,
) -> None:
    """Adds one page to the pack: what the pack drew over its sheet, and the page
    number, which every page carries."""
    text_right(content, font, 8.0, RIGHT, 48.0, MUTED, f"Page {number} of {pages}")

    leaf = hqf_pdf.Page.a4()
    leaf.set_content(content)
    # A page may only draw what its resources name.
    sheet.add_to(leaf)
    document.add_page(leaf)


def sheet(
    given: str | None, font_path, make: Callable[[object], bytes]
) -> hqf_pdf.Reader:
    """Reads a sheet named on the command line, or the one made here when none is
    named."""
    if given is not None:
        with open(given, "rb") as handle:
            return hqf_pdf.Reader(handle.read())
    return hqf_pdf.Reader(make(font_path))


def main() -> None:
    out = _out.output_path("pack")
    font_path = _out.DEFAULT_FONT
    given = [sys.argv[index] if len(sys.argv) > index else None for index in (2, 3, 4)]

    headed = sheet(given[0], font_path, a_headed_sheet)
    continuation = sheet(given[1], font_path, a_continuation_sheet)
    conditions = sheet(given[2], font_path, a_conditions_sheet)

    document = hqf_pdf.Document()
    document.set_license(_licence.licensed())

    # Each sheet comes in as a form: the same page, now a drawing this document can
    # stamp wherever it likes, as many times as it likes.
    headed = document.import_page(headed, 0)
    continuation = document.import_page(continuation, 0)
    conditions = document.import_page(conditions, 0)

    font = document.add_font(hqf_pdf.Font.from_path(font_path))
    table = schedule(font)

    # The schedule says how many pages it needs, so the pack's length is known before a
    # page of it is made: the front page, the schedule's pages, and the conditions.
    box_of = hqf_pdf.Frame(LEFT, TABLE_TOP, TABLE_TOP - TABLE_BOTTOM)
    placed = table.paginate(box_of, box_of)
    pages = len(placed) + 2

    contents = Contents(pages, (2, len(placed) + 1), table.row_count)

    # Each page: its sheet goes down first, and what the pack draws goes on top of it.
    content = hqf_pdf.Content()
    content.draw_form(headed, 0.0, 0.0, 1.0)
    front_page(content, font, contents)
    add_page(document, headed, content, font, 1, pages)

    for index, placement in enumerate(placed):
        content = hqf_pdf.Content()
        content.draw_form(continuation, 0.0, 0.0, 1.0)
        placement.draw(content)
        add_page(document, continuation, content, font, index + 2, pages)

    # The conditions sheet carries nothing of the pack's but its page number: it is a
    # page of the pack, not an attachment to it.
    content = hqf_pdf.Content()
    content.draw_form(conditions, 0.0, 0.0, 1.0)
    add_page(document, conditions, content, font, pages, pages)

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


if __name__ == "__main__":
    main()