cadrumo.adapters.inbound.einvoice.shape module

Derive a DocumentShape from a document’s own bytes.

Never consults a declared MIME type, a filename suffix, or any caller-supplied label. The whole point of the probe is that those three all answered application/pdf for a ZUGFeRD invoice whose embedded XML carried the complete invoice, so the most exactly readable document in the corpus was routed to prose extraction.

The probe is read-only and allocates nothing outside memory. XML detection runs through the hardened parser in xml, so a probe against a hostile document cannot resolve an external entity or expand a billion-laughs payload.

EMBEDDED_XML_SUFFIXES: tuple[str, ...]

Filenames the EN16931 PDF/A-3 profiles use for the embedded invoice.

Used only to rank candidates when a PDF carries several attachments. A document is never classified on the filename alone – the payload is parsed and its root element is what decides, so a mislabelled attachment cannot promote a non-invoice into a structured shape.

SII_PAYLOAD_ELEMENTS

Every top-level record family the SII envelope schema declares.

All seventeen, not only the two this reader claims. Recognising the SHAPE is separate from supporting the FAMILY: a document we decline to read must still be identified, so the refusal can name what it is instead of reporting unrecognised bytes.

Spelled out rather than parsed, because the probe runs on a hot path and must not touch the filesystem. It is not unattested: every name is held to the global xs:element declarations of the bundled corpus/aeat_official/einvoice_record_schemas/sii/SuministroLR.xsd by tests/test_aeat_payload_elements_match_schemas.py, so a re-bundled AEAT revision fails a gate instead of leaving a real record reported as UNKNOWN.

VERIFACTU_PAYLOAD_ELEMENTS

The VERI*FACTU envelope plus the two bare record elements.

The bare forms are listed because real captures ship a lone RegistroAlta or RegistroAnulacion with no envelope around it. AEAT declares them in the base-types schema and the envelope in SuministroLR.xsd, so the same gate that guards the SII set checks this one against the UNION of both bundled VERI*FACTU schemas.

iter_pdf_embedded_files(pdf_bytes)

Return (filename, payload) for every embedded file in a PDF.

The read half of the embedded-file walk the sanitiser already performs. The fixture-preparation sanitiser strips these; this reads them without mutating anything, so a ZUGFeRD payload is visible to a parser.

Returns an empty tuple when the bytes are not a readable PDF or carry no attachments – an unreadable document is not an error at probe time.

Return type:

tuple[tuple[str, bytes], ...]

Parameters:

pdf_bytes (bytes)

probe_document_shape(data, *, has_text_layer=None)

Return the DocumentShape of data, derived from its bytes.

Parameters:

• data (bytes) – The document’s full in-memory bytes.

• has_text_layer (bool | None) – Whether the caller has already established that a PDF carries extractable text. Supplied by callers that have run the text-layer extractor, so the probe never re-runs it. When omitted a PDF with no embedded structured record resolves to DocumentShape.PDF_TEXT_LAYER, the conservative answer: it routes to text extraction, which then reports emptiness itself rather than the probe pre-judging a scan.

Return type:

DocumentShape

Returns:

The derived shape, or DocumentShape.UNKNOWN when the bytes match nothing recognised. UNKNOWN is always refused by callers, never guessed into a neighbouring shape.