Python API reference

The pdfboss package re-exports the compiled extension module pdfboss._pdfboss. Its public API is the document, page, layout and iteration classes, thirteen classes for the interactive form and the catalog's document-level structures, the md and write submodules and the __version__ string; the typed stubs in _pdfboss.pyi are the authoritative reference for every signature and docstring. This chapter is the inventory; worked examples live in the guide chapters.

The document classes

Document.metadata is a property returning the document information dictionary as a dict[str, str], only keys present in the file included; AsyncDocument.metadata() is a coroutine yielding the same mapping. AsyncDocument also has page(index) (synchronous, 0-based, no negative indexes; subscription doc[i] accepts them) and get_object(num, gen=0), a coroutine fetching one indirect object and returning it through the same plain-Python conversion as Element.value().

The form and catalog classes

Ten Document methods read the interactive form and the catalog's document-level structures, each with an AsyncDocument coroutine of the same name and result: interactive_form(), form_fields(), outline(), named_destinations(), page_labels(), page_label(index), embedded_files(), embedded_file_data(file), viewer_preferences() and extensions(). They return frozen instances of the classes below; every enumeration is a kebab-case string ("check-box", "roman-upper", "fit-r"), every object reference a (num, gen) tuple like Element.ref, and a field's value plain Python data through the Element.value() conversion. form_fields, outline, named_destinations and embedded_file_data release the GIL while they read.

import pdfboss

doc = pdfboss.Document("form.pdf")
for field in doc.form_fields():
    if field.field_type == "text":
        print(field.name, field.text)
    elif field.button_kind == "check-box":
        print(field.name, field.checked)
    elif field.field_type == "choice":
        print(field.name, field.selected)

for item in doc.outline():
    print(item.title, item.page)
for attachment in doc.embedded_files():
    open(attachment.name, "wb").write(doc.embedded_file_data(attachment))

Guide chapters with runnable examples: Extracting text, Markdown output, Styled spans, Rendering pages, Extracting images, Reading forms, bookmarks and attachments, Creating PDFs, Markdown to PDF, Async and remote documents, Encrypted documents, Editing PDFs, Assembling documents.

The document and page structure classes

Nine more Document methods read structures beyond the catalog readers above: linearization(), is_linearized(), output_intents(), optional_content_groups(event), piece_info(), articles(), permission_handlers(), requirements() and legal_attestation(). AsyncDocument has each under the same name; the first two are plain calls there too, since the file head is read at open, the rest are coroutines. Ten Page methods read a page's own structures, each with an AsyncPage coroutine twin: piece_info(), thumbnail(), thumbnail_image(compression), beads(), presentation(), viewports(), separation_info(), annotations(), additional_actions() and content_items(). Document.additional_actions() reads the catalog's trigger events and Document.file_spec_data(spec) decodes the file a FileSpec embeds, both with AsyncDocument twins. The conventions above hold: enumerations are kebab-case strings, object references (num, gen) tuples, dates ISO 8601 strings, and every reader that resolves objects releases the GIL.

import pdfboss

doc = pdfboss.Document("slides.pdf")
print(doc.is_linearized(), [intent.subtype for intent in doc.output_intents()])
for thread in doc.articles():
    print(thread.info.get("title"), [(bead.page, bead.rect) for bead in thread.beads])

page = doc[0]
shown = page.presentation()
if shown and shown.transition:
    print(shown.duration, shown.transition.style)
thumb = page.thumbnail_image()
if thumb:
    open("thumb.png", "wb").write(thumb.data)

for viewport in page.viewports():
    scale = viewport.measure
    if scale:
        print(viewport.name, scale.scale_ratio, [f.unit for f in scale.distance])
separation = page.separation_info()
if separation:
    print(separation.device_colorant, separation.pages)
for requirement in doc.requirements():
    print(requirement.kind, [handler.kind for handler in requirement.handlers])
legal = doc.legal_attestation()
if legal:
    print(legal.attestation, legal.counts())

for annotation in page.annotations():
    action = annotation.action
    if annotation.subtype == "Link" and action and action.kind == "URI":
        print(annotation.rect, action.uri)
    elif annotation.destination:
        print(annotation.rect, "-> page", annotation.destination.page)
    if annotation.markup:
        print(annotation.markup.title, annotation.contents, annotation.state)
    if annotation.file and annotation.file.ref:
        open(annotation.file.name, "wb").write(doc.file_spec_data(annotation.file))
for triggered in page.additional_actions() + doc.additional_actions():
    print(triggered.trigger, triggered.action.kind)
for item in page.content_items():
    print(item.rank, item.standard_type, item.ref if item.kind == "object" else item.mcid)

The md submodule

pdfboss.md.to_pdf(markdown, theme=None, size="a4", landscape=False, base_dir=None) composes CommonMark+GFM source into a themed PDF and returns the file bytes. theme is CSS source text, not a path; size is a page size name (a0 to a10, b0 to b10, letter, legal, tabloid) or <width>x<height> in pt, mm, cm or in, and an unknown one raises PdfError; replaced characters and skipped raw HTML surface as one UserWarning. Details and examples in Markdown to PDF.

Canvas-level and element-level creation from Python is the write submodule below.

The write submodule

pdfboss.write composes new PDFs from frozen values joined with |; the same vocabulary is the Rust crate pdfboss-write and the pdfboss create CLI, and worked examples live in Creating PDFs. Fourteen classes:

Every | returns a new value and leaves the receiver unchanged; copies are cheap handle clones, and nothing is built until save or to_bytes, which lower the composition once under the GIL and release it to serialize. to_bytes may be called repeatedly, since the composed value is never consumed.

The draw protocol is structural: any object with a callable draw attribute composes onto a Page, and its draw(canvas) receives a Canvas with twelve methods (text, line, rect, move_to, line_to, curve_to, close, stroke, fill, set_fill, set_stroke, set_line_width) that paints in content order. The stub declares a Draw protocol type for checkers only; there is no runtime Draw class to import or inherit. The canvas is only usable inside the call, and every method raises PdfError once draw has returned.

Two more names work on existing files, neither in the table above since neither composes with |: watermark(data, overlay, *, rewrite=False, under=False) takes two PDFs as bytes and returns data with the first page of overlay drawn over every page, as an incremental update appended to data's bytes, or with rewrite=True as a fresh, compressed file; under=True draws the overlay beneath each page's own content instead of over it (see Watermarking an existing file); Update(doc) stages a metadata edit over an existing Document, with set_metadata(title=None, author=None, subject=None, keywords=None, creator=None, producer=None) merging the given fields and save(path) or to_bytes() writing the result as an incremental update (see Editing PDFs). Both release the GIL while they run. Update always raises PdfError for an encrypted base, whether or not it opens. watermark's default (rewrite=False, appending) does the same for an encrypted data or overlay; with rewrite=True, only a data or overlay that cannot be opened at all raises PdfError, and one that opens under its password, including the empty user password, copies across as plain, unencrypted bytes instead.

Six more functions assemble documents from existing file bytes, also outside the table since none composes with | (see Assembling documents): merge(inputs) gathers each item, raw bytes for every page or a (bytes, list[int]) tuple for specific 0-based pages, into one fresh document in argument order; split(data, every) cuts data into consecutive parts of every pages, the last part carrying whatever remains; split_parts(data, every, *, password="") yields the same parts one at a time as a SplitIterator iterator usable with both for and async for; split_stream(stream, every, *, password="") does the same for a PDF arriving as an async iterable of bytes chunks, collecting the chunks before the first part is built (see One part at a time); rotate(data, by, pages=None, rewrite=False) turns pages (0-based, every page when omitted) by by degrees clockwise, restricted to 90, 180 or 270 (else ValueError), appending an incremental update by default or writing a fresh file with rewrite=True; rewrite(data) writes data fresh, recompressed with unreachable objects and earlier update sections left behind. every below 1 raises ValueError from all three split functions at the call. merge, the split functions and rewrite always produce fresh files; only rotate can append instead, the same choice Update/meta offers. An input that cannot be opened at all (encrypted with no working password) raises PdfError from merge, split, rotate and rewrite immediately, before any assembly work begins; split_parts and split_stream parse lazily, so they raise it from the first part instead, split_stream after the whole stream has been read. One that opens under its password, including the empty user password, passes through merge, split and rewrite as plain, unencrypted bytes, through split_parts and split_stream the same way when opened with their password, and through rotate the same way when rewrite=True; rotate's default appending mode still raises PdfError for any encrypted input, opened or not. An owner-password-only file therefore loses its /P restrictions the moment its holder runs it through rewrite (or merge, a split function, or rotate(rewrite=True)): the freshly written output carries no encryption at all, restrictions included. rotate also refuses, in either mode, a page inlined directly into /Kids with no object of its own, since pdfboss does not yet restructure such a page to rotate it.

Two more functions protect or remove protection from a document's bytes, also outside the table above (see Encrypted PDFs): encrypt(data, *, user_password="", owner_password="", allow=None) AES-256, revision-6 protects data and returns the fresh file, restricted by allow, a list drawn from print, modify, copy, annotate, fill-forms, accessibility, assemble and print-hires (every permission when omitted); an unknown allow value raises ValueError naming it, and so does leaving both user_password and owner_password empty, while an empty owner_password alone falls back to user_password. decrypt(data, *, password="") opens data under its user or owner password and returns a fresh, unencrypted file; a wrong or missing password raises PdfError. Both release the GIL around the actual work.

Error handling

Everything raises PdfError: bad or truncated data, unsupported encryption, stream decode failures and I/O errors, with the underlying detail in the message. Messages from the element and async APIs are prefixed by the layer they came from: "parse: …", "io: …" or "http: …".

import pdfboss

try:
    doc = pdfboss.Document("report.pdf")
except pdfboss.PdfError as e:
    print(f"could not open: {e}")

Two conventional exceptions apply where Python conventions demand them: constructing a Document with neither or both of path and data raises ValueError (as does a non-positive scale, an unknown fonts=, compression= or format= string, a quality= outside 1 to 100, or an unusable fonts="full" setup in render), and an out-of-range page index raises IndexError. Element iterators have salvage semantics: a per-item failure raises PdfError for that item, and iteration may be continued. Span iterators raise PdfError when a page cannot be materialized.

The write submodule splits its failures by phase. TypeError is raised at construction for a Link with neither or both of url and page, an unknown align, page-label style, viewer layout or mode, or Image data that is neither str nor bytes; and at composition for an unsupported | operand or a second Metadata, Outline or Viewer. Everything that fails while lowering (an unreadable or undecodable image file, a paragraph overflowing its rect, an unencodable character, a target page out of range) raises PdfError from save/to_bytes. A draw object's Canvas stops working the moment its draw call returns: any later method call on it raises PdfError at that call site. An exception raised inside draw() itself propagates from save/to_bytes exactly as the Python code raised it.

Threading

A Document (and any Page it hands out) may be used from any thread. Access to the underlying parsed document is serialized internally, and extract_text/render release the GIL while they run, so other Python threads keep making progress during long extractions or renders. Element and span iteration release the GIL per step the same way. Document.render_pages fans page rendering out across the machine's cores.

The async API needs no thread juggling: AsyncDocument's coroutines are driven by one global multi-thread tokio runtime, and AsyncDocument.render_pages fans out as tokio tasks so the asyncio loop stays free.