PDF export

Document.to_pdf() renders a parsed document to PDF with a streaming flow layout and real pagination — content flows and breaks across pages the way Word lays it out.

API

class Document:
    def to_pdf(self, *, font_map: dict[str, str] | None = None) -> bytes: ...
    def save_pdf(
        self, path: str | os.PathLike[str], *, font_map: dict[str, str] | None = None
    ) -> None: ...

import docspine

doc = docspine.open("report.docx")

pdf_bytes = doc.to_pdf()             # -> bytes, starts with b"%PDF-"
doc.save_pdf("report.pdf")          # writes the same bytes to a file

Per-section page geometry

Page size, margins, and orientation come from each sectPr, so a document whose sections mix paper sizes and orientations paginates correctly — for example a US-Letter portrait section followed by an A4 landscape one:

# section 1 -> 612 × 792 pt   (US Letter, portrait)
# section 2 -> 841.9 × 595.3 pt (A4, landscape)
pdf = docspine.open("mixed-sections.docx").to_pdf()

Section breaks and explicit page breaks (w:br w:type="page") both start a new page.

Fonts and the font_map

The renderer resolves styles.xml + theme effective fonts (including the east-Asian eastAsia slot for CJK) and embeds each used face once, subset. Pass font_map to override family resolution — each entry maps a requested family to a font file path or another family name:

pdf = doc.to_pdf(font_map={"宋体": "Songti SC"})

import warnings

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    pdf = doc.to_pdf(font_map={"Missing Family": "Liberation Serif"})

for w in caught:
    print(w.category.__name__, w.message)   # UserWarning ...

What the renderer covers

Embedded pictures render. Each inline picture (with usable media bytes and a wp:extent size) is placed in the flow as a block image at the point its paragraph occurs; a picture that is the whole paragraph takes no extra blank line. Floating (wp:anchor) raster pictures are absolutely positioned — the picture is drawn as a page overlay at its wp:positionH / wp:positionV posOffset (relative to the page or the section margins) on the section's first page. Text does not wrap around it — that emits a one-time FloatingNoWrap warning (per-line exclusion rectangles remain out of v1). Vector-format (EMF / WMF) or byte-missing anchored pictures fall back to the inline-placeholder or skip paths; a picture with missing media bytes or no size is skipped with a UserWarning (its bytes stay available at parse level via image_bytes()).

Rendering is deterministic per font environment: the same document and the same installed fonts produce the same PDF bytes.