"""Creates an electronic invoice and asks the document what stands in its way. The Python twin of the `write_checked_invoice` example in Rust: the same document, through the binding rather than through the library directly. Every other example reaches a standard by declaring it. This one asks first. `Document.check` reads the document as it stands, writes nothing, changes nothing, and hands back everything known here to stand between it and the standard named — all of it at once, each finding citing the clause it comes from. The invoice is composed the way a caller first writes it, with three things wrong that only a report can name: it claims no archival standard, it names an invoice it never attached, and it claims a profile the XML does not carry. The first two hide the third, because a file that is not there cannot be read; so each round prints what came back, puts it right, and asks again. Nothing is written while anything stands. An empty report is not a certificate. It says that nothing this library knows to look for is in the way, which is not the same as conforming: `veraPDF` says whether the file conforms, and `scripts/check_pdfa.sh` asks it. The page is written in the language `HQF_PDF_LANG` names. The XML is not: it is read by an accounting system rather than by a person, and the same file goes to a buyer in any country. What the terminal says is not either — it is the library's own report, in the words the library states its clauses in. Usage: python examples/write_checked_invoice.py [out.pdf] [font.ttf] HQF_PDF_LANG=fr python examples/write_checked_invoice.py """ from __future__ import annotations from dataclasses import dataclass from pathlib import Path import _language import _licence import _out import hqf_pdf # When the invoice was issued. The library never reads the clock — a document that # stamped itself with the time would be a different file on every build — so the caller # says when, and here the caller is an example. ISSUED = "2026-07-14T09:30:00+02:00" # The part of the archival standard an electronic invoice belongs in. CONTAINER = hqf_pdf.PdfA.A3B # The profile the caller claims before reading the XML. CLAIMED_AT_FIRST = hqf_pdf.InvoiceProfile.En16931 # The profile the XML states under `GuidelineSpecifiedDocumentContextParameter`. CARRIED = hqf_pdf.InvoiceProfile.Basic # The version of the Factur-X specification the XML follows. SPECIFICATION = "1.0" # The name the standard has reading software look the XML up by, and the name # `Attachment.invoice` carries it under. INVOICE_FILE_NAME = "factur-x.xml" # The invoice, as a machine reads it: a Factur-X BASIC profile document, which carries # the billed lines as well as the header. A real invoice carries more, and carries it # under the same rules. INVOICE_XML = """ urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:basic 2026-0207 380 20260714 1 Rendering engine licence 12400.00 1 VAT S 20.00 12400.00 HQF Development 752492777 FR Northwind Trading SARL EUR 12400.00 2480.00 14880.00 14880.00 """ # The invoice's number, which the page shows and the XML carries under `ram:ID`. One # number, written once on each side. NUMBER = "2026-0207" # Who issued the invoice, on the page and in the XML both. SELLER = "HQF Development" # What each of the three billed lines comes to, in the order they are set. These are the # figures the XML totals, so they read the same wherever the page is read. AMOUNTS = ["12 400.00 EUR", "2 480.00 EUR", "14 880.00 EUR"] # How many characters a billed line runs to: its label, a space, the leader dots, a # space, then its amount. The dots take whatever is left, so the amounts end on the same # character however long the label before them is. LINE_CHARS = 58 # The size each line of the page is set at, in points, in the order they are drawn. SIZES = [16.0, 10.0, 11.0, 11.0, 11.0, 12.0] # How far in from the left edge of the sheet every line is set, in points. LEFT = 72.0 @dataclass(frozen=True) class Words: """Every word the page is written in, in one language. What is not language stays out of it: the invoice's number, the seller's name and the three amounts read the same wherever the page is read, and so does every word of the XML. """ # What stands before the invoice's number, at the head of the page and in the # document's own title. number_label: str # What the file says it holds. subject: str # What stands before the seller's name. issued_by: str # The line that gives the day it was issued and the term it falls due in. dates: str # What each billed line is called, in the order `AMOUNTS` prices them. items: tuple[str, str, str] def title(self) -> str: """What the page is headed by, which is also what the file says of itself.""" return f"{self.number_label} {NUMBER}" def lines(self) -> list[str]: """The lines the page shows, which say what the XML says.""" lines = [self.title(), f"{self.issued_by} {SELLER}", self.dates] for item, amount in zip(self.items, AMOUNTS): dots = max(LINE_CHARS - len(item) - len(amount) - 2, 0) lines.append(f"{item} {'.' * dots} {amount}") return lines # The page in English. ENGLISH = Words( number_label="Invoice No.", subject="An electronic invoice, measured before it was claimed", issued_by="Issued by", dates="Issued 14 July 2026 — due within 30 days", items=("Rendering engine licence", "VAT at 20 %", "Total due"), ) # The page in French. FRENCH = Words( number_label="Facture n°", subject="Une facture électronique, mesurée avant d'être revendiquée", issued_by="Émise par", dates="Émise le 14 juillet 2026 — payable sous 30 jours", items=("Licence du moteur de rendu", "TVA 20 %", "Total à payer"), ) # 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 facts(words: Words, profile: hqf_pdf.InvoiceProfile) -> hqf_pdf.Metadata: """The facts the document states about itself, naming the invoice it carries and claiming ``profile`` for it.""" return hqf_pdf.Metadata( title=words.title(), author=SELLER, subject=words.subject, producer="hqf-pdf", created=ISSUED, invoice=hqf_pdf.Invoice(INVOICE_FILE_NAME, profile, SPECIFICATION), ) def invoice_page(handle: hqf_pdf.FontHandle, words: Words) -> hqf_pdf.Page: """The page a person reads, saying what the attached XML says.""" content = hqf_pdf.Content() top = 760.0 for line, size in zip(words.lines(), SIZES): content.draw_text(handle, size, LEFT, top, line) top -= size * 2.0 page = hqf_pdf.Page.a4() page.set_content(content) return page def print_report(asked: str, report: hqf_pdf.Report) -> None: """Print what ``report`` holds: the clause each finding cites, what it says, and the one thing it is about where it names one.""" if report.is_empty(): print(f"{asked}: nothing known here stands in the way") return print(f"{asked}: {len(report)} in the way") for finding in report.findings: if finding.subject is None: print(f" {finding.clause}: {finding.what}") else: print(f" {finding.clause}: {finding.what} — {finding.subject}") 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("checked_invoice.pdf", language)).stem ) # The profile the document claims, which is what it is measured against: a report # answers the claim that was made, not the one that should have been. claimed = CLAIMED_AT_FIRST document = hqf_pdf.Document() document.set_license(_licence.licensed()) document.set_metadata(facts(words, claimed)) handle = document.add_font(hqf_pdf.Font.from_path(_out.font_path())) document.add_page(invoice_page(handle, words)) report = document.check(hqf_pdf.Standard.invoice(claimed)) print_report("as first composed", report) # An invoice belongs in a document claiming the third part of the archival standard, # and the file it names is one it carries. What the attachment *is* to the document # has no sensible default: `Data` is right for the profiles that carry part of the # invoice, and `Alternative` for those that carry all of it. This one is BASIC, # which carries part. document.set_conformance(CONTAINER) document.attach( hqf_pdf.Attachment.invoice( INVOICE_XML.encode(), hqf_pdf.Relationship.Data, ISSUED ) ) report = document.check(hqf_pdf.Standard.invoice(claimed)) print_report("once the file is carried and the standard claimed", report) # The XML states the profile it keeps to, and the document says what the XML states. claimed = CARRIED document.set_metadata(facts(words, claimed)) report = document.check(hqf_pdf.Standard.invoice(claimed)) print_report("once the profile is the one the XML carries", report) # The archival standard is a second claim, and a claim nobody asked about is a claim # nobody measured. archival = document.check(hqf_pdf.Standard.archival(CONTAINER)) print_report("against the archival standard now claimed", archival) if not report.is_empty() or not archival.is_empty(): raise SystemExit("something still stands in the way, and nothing is written") written = document.write(out) print(f"wrote {out} ({written} bytes)") if __name__ == "__main__": main()