Files

303 lines
12 KiB
Python
Raw Permalink Normal View History

#!/usr/bin/env python3
"""What a document somebody fills in has to be, measured in the finished PDF.
A form is only a form where a reader can tick a box, type an entry of any
length and save the file. Nothing of that is visible on a rendered page, so it
is read out of the PDF itself: the field dictionaries, their names, their
flags, and the rectangles they stand in.
python3 tests/forms.py
"""
import os
import re
import sys
import zlib
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import support
from support import Check
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
OUT = os.path.join(ROOT, "tests", "build", "form")
CONVERTER = os.path.join(ROOT, "bin", "md2pdf.py")
support.name_example_company()
# The two shapes the platforms already render, and nothing else: a task list
# item and a line of a label with underscores. The third item carries no
# identifier, the second arrives ticked, and the last two lines are a
# signature block.
FORM_MD = """---
title: Sign-off
---
## Changes to approve
- [ ] **S1 First condition.** What is confirmed, in one sentence.
Remarks: ________________________________
- [x] **S2 Second condition.** Delivered ticked.
Remarks: ________________________________
- [ ] An item without an identifier.
Remarks: ________________________________
## General remarks
General remarks: ________________________________
## Confirmation
Name: ________________________________
Date: ________________________________
"""
# The same document without the two shapes: a list that is no task list, and a
# line that carries underscores without a label. Neither may make a field, and
# the underscores alone stay what every platform makes of them, a rule.
PLAIN_MD = """---
title: Report
---
## Findings
- First finding of the report.
- Second finding of the report.
The line under this one is a rule and no field.
________________________________
Closing sentence of the report.
"""
# What the two flags mean, out of the PDF specification: bit 13 is the
# multi-line field, bit 24 forbids scrolling. A field that scrolls takes an
# entry longer than its box, which is what «any length» asks for.
MULTILINE = 1 << 12
NO_SCROLL = 1 << 23
def convert(check, name, markdown):
"""One document through the converter, as a reader receives it."""
os.makedirs(OUT, exist_ok=True)
path = os.path.join(OUT, name + ".md")
with open(path, "w", encoding="utf-8") as handle:
handle.write(markdown)
# `--keep-tex` so the build log stays: the measurement of the logs reads
# every log of this directory, and a conversion that throws its log away
# leaves the one an earlier build wrote to be measured instead — a log of a
# state nobody has any more. The PDF of an earlier run goes first, so a
# failed build is not measured on it.
pdf = os.path.join(OUT, name + ".pdf")
if os.path.exists(pdf):
os.remove(pdf)
result = support.run(["python3", CONVERTER, "--identity", "nordwind",
"--keep-tex", "--out-dir", OUT, path])
check.that(os.path.exists(pdf),
f"{name}.md did not build:\n{result.stdout[-1000:]}")
return pdf if os.path.exists(pdf) else None
def objects(pdf):
"""The PDF with every stream it carries unpacked, as one string of bytes."""
with open(pdf, "rb") as handle:
data = handle.read()
chunks = [data]
for match in re.finditer(rb"stream\r?\n(.*?)endstream", data, re.S):
try:
chunks.append(zlib.decompress(match.group(1)))
except zlib.error:
pass
return b"\n".join(chunks)
def names(whole):
"""Every field name, in the order the document writes them."""
found = []
for match in re.finditer(rb"/T\s*(?:<([0-9a-fA-F]+)>|\(([^)]*)\))", whole):
if match.group(1):
raw = bytes.fromhex(match.group(1).decode())
found.append(raw.decode("utf-16-be", "replace").lstrip(""))
else:
found.append(match.group(2).decode("latin-1"))
return found
def flags(whole):
"""The flag word of every field that carries one."""
return [int(value) for value in re.findall(rb"/Ff\s*(\d+)", whole)]
def rectangles(whole):
"""Every annotation rectangle: left, bottom, right, top."""
return [tuple(float(value) for value in match.groups())
for match in re.finditer(
rb"/Rect\s*\[\s*([\d.]+)\s+([\d.]+)\s+([\d.]+)\s+([\d.]+)\s*\]",
whole)]
# A chapter long enough to run over a page, with items of different length, so
# that one of them meets the foot of a page wherever the page happens to end.
SPILL_MD = ("---\ntitle: Sign-off\n---\n\n## Changes to approve\n\n"
+ "".join(
"- [ ] **S%d Condition %d.** %s\n\n Remarks: ____________\n\n"
% (number, number,
("What is confirmed here, in a sentence that carries "
"enough words to fill a line or two of the page. ")
* (1 + number % 3))
for number in range(1, 13)))
def together(check):
"""An item, its label and its field stand on one page.
A box, the text beside it and the field under it are one thing to read and
one thing to fill in. The page used to break between them: the text of an
item stood at the foot of a page and its «Remarks» label and frame began
the next one, so the reader ticks on one page and writes on the other.
"""
pdf = convert(check, "spill", SPILL_MD)
if not pdf:
return
pages = support.pages(pdf)
check.that(pages > 1,
f"the fixture of twelve items fits on {pages} page and proves "
"nothing about a page break")
seen = {}
for page in range(1, pages + 1):
for word, left, top, right, bottom in support.words(pdf, page):
if re.fullmatch(r"S\d+", word):
seen.setdefault(word, []).append((page, bottom))
elif word == "Remarks":
seen.setdefault("remarks", []).append((page, top))
check.that(len(seen) > 12,
f"the fixture carries {len(seen) - 1} identifiers of twelve")
remarks = seen.pop("remarks", [])
for name, places in sorted(seen.items()):
page, bottom = places[0]
following = [spot for spot in remarks
if spot[0] > page or (spot[0] == page and spot[1] > bottom)]
check.that(following and following[0][0] == page,
f"the item {name} stands on page {page} and its label on "
f"page {following[0][0] if following else 0}")
def fields(check):
"""Every field of the form, by name, by kind and by flag."""
pdf = convert(check, "form", FORM_MD)
if not pdf:
return
whole = objects(pdf)
found = names(whole)
expected = ["S1", "S2", "q1", "S1-remarks", "S2-remarks", "q1-remarks",
"General-remarks", "Name", "Date"]
for name in expected:
check.that(name in found, f"the form carries no field «{name}»")
check.that(len(found) == len(set(found)),
f"a field name is used twice: {sorted(found)}")
boxes = whole.count(b"/FT/Btn") + whole.count(b"/FT /Btn")
texts = whole.count(b"/FT/Tx") + whole.count(b"/FT /Tx")
check.that(boxes == 3, f"the form carries {boxes} checkboxes and not three")
check.that(texts == 6, f"the form carries {texts} text fields and not six")
# An entry of any length: no limit, and the field scrolls.
check.that(b"/MaxLen" not in whole,
"a field limits how much may be typed into it")
written = [value for value in flags(whole) if value & MULTILINE]
check.that(len(written) == texts,
f"{len(written)} of {texts} text fields take several lines")
check.that(not [value for value in flags(whole) if value & NO_SCROLL],
"a field forbids scrolling, so a long entry is cut off")
# What the reader needs to draw what somebody types.
check.that(b"/NeedAppearances true" in whole,
"the form does not ask the reader to draw what is typed")
# The ticked item arrives ticked. The on state of a checkbox carries the
# name of its appearance, and hyperref calls that one `Yes`: the box holds
# `/V/Yes` as its value and `/AS/Yes` as what is drawn, while an unticked
# one holds `/Off` in both. Read out of the three dictionaries of this
# document, where exactly one carries it.
on = len(re.findall(rb"/V\s*/Yes", whole))
check.that(on == 1,
f"{on} of the three boxes arrive ticked, and one was written "
"ticked")
# The large field at the end of a form takes what somebody writes: it is
# clearly taller than the remark of an item, which is three lines.
boxes = rectangles(whole)
heights = sorted(box[3] - box[1] for box in boxes)
check.that(heights[-1] > 3 * heights[len(heights) // 2],
f"the large field is {heights[-1]:.0f} points tall and the "
f"others {heights[len(heights) // 2]:.0f}")
# The lines of a signature block begin on one edge, whatever their labels
# are called: «Name» and «Date» are four letters and not the same width, so
# each label pushed its own frame to a different place.
lines = sorted(box[0] for box in boxes if 10 < box[3] - box[1] < 25)
check.that(lines and max(lines) - min(lines) < 0.5,
f"the lines of the signature block begin at {lines}")
# Nothing stands outside the text block, which is where the page ends for
# ink as much as for a field.
edge = 566.93
over = [box for box in rectangles(whole) if box[2] > edge + 0.2]
check.that(not over,
f"{len(over)} field(s) reach past the text block, the widest to "
f"{max((box[2] for box in over), default=0):.1f} points")
SECRET = "Zebra marker of the file the label asked for"
def labels(check):
"""The label of a field is set as the text it is, never read as LaTeX.
A label closed the brace of the command it is written into and asked for a
file with `\\input`, which put that file into the PDF, and a `%`, `&` or `#`
in a label stopped the build.
"""
os.makedirs(OUT, exist_ok=True)
secret = os.path.join(OUT, "label-secret.tex")
with open(secret, "w", encoding="utf-8") as handle:
handle.write(SECRET + "\n")
markdown = ("---\ntitle: Labels\n---\n\n## Entries\n\n"
"Notes}\\input{" + secret + "}\\iffalse: ________________\n\n"
"Cost % & # Ref_no: ________________\n\n"
"## Remarks\n\n"
"Say \\textbf{bold}: ________________\n")
pdf = convert(check, "labels", markdown)
if not pdf:
return
text = " ".join(support.text(pdf).split())
check.that(SECRET not in text, "a label read a file into the PDF")
for label in ("Notes}\\input{", "Cost % & # Ref_no", "Say \\textbf{bold}"):
check.that(label in text, f"the label «{label}» is not on the page as written")
def untouched(check):
"""A document that fills in nothing carries no form at all.
Every other document of every company goes through the same converter, and
the one thing a feature like this may not do is change them.
"""
pdf = convert(check, "plain", PLAIN_MD)
if not pdf:
return
whole = objects(pdf)
check.that(b"/AcroForm" not in whole,
"a document without a single field carries a form dictionary")
check.that(not names(whole),
f"a document without a single field carries fields: "
f"{names(whole)}")
def main():
check = Check("forms")
fields(check)
together(check)
labels(check)
untouched(check)
return check.done()
if __name__ == "__main__":
sys.exit(main())