Introduction

pdfboss is a PDF engine written from scratch in safe Rust against the ISO 32000 specification. It is a clean-room implementation: no C dependencies, no bindings to another engine, and the image and color codecs a PDF needs (JPEG 2000, JBIG2, CCITT, ICC) are its own. One core sits behind every surface: the pdfboss command-line tool, an interactive terminal explorer (pdfboss tui), a set of Rust library crates, and a native Python extension.

The surfaces expose the same engine at different altitudes. The CLI covers extraction, rendering, creation and explorer subcommands over a document's structure; the terminal explorer browses a file interactively, local or remote. Python gets Document and its async twin AsyncDocument, with pages, styled spans, lazy element iteration, rendering and image extraction, plus document creation through pdfboss.write and pdfboss.md.to_pdf. The Rust crates split the core by concern, from parsing (pdfboss-core) through layout analysis (pdfboss-output) and rasterization (pdfboss-render) to creation (pdfboss-write).

Leniency

Real-world PDFs are damaged: truncated downloads, editors that miscount stream lengths, generators that write cross-reference tables pointing nowhere. pdfboss reads them anyway:

• A broken or missing cross-reference table is reconstructed by scanning the file for its objects.
• A stream whose declared length is wrong is still decoded.
• Content-stream operators that will not parse are skipped, and the rest of the page still extracts and rasterizes.

Leniency never hides what it cost. Every dropped or approximated piece of content lands in a report: pdfboss render warns on stderr, the terminal explorer raises a notice, and the libraries return the report as a value, through render_page_reporting and extract_text_reporting in Rust and Page.render_reporting() in Python. A page that came out exactly as the file describes it carries an empty report, so silence means fidelity, not luck.

Scope

pdfboss extracts plain text and Markdown (headings, lists and tables inferred from page layout), yields styled text spans carrying position, font, weight, decorations and color, rasterizes pages to PNG through its own JPEG 2000, JBIG2, CCITT and ICC codecs, extracts embedded images at their native pixel size, creates new PDFs (canvas painting and element composition through the pdfboss-write crate, the pdfboss.write Python module and pdfboss create, a TOML manifest form included, plus CommonMark+GFM composed into CSS-themed documents from the CLI, Python pdfboss.md.to_pdf and Rust), and reads documents asynchronously over range-fetching I/O, from local files or HTTP, without ever reading the whole file.

Encrypted files open through the standard security handler: RC4 and AES-128/256, with either the user or the owner password; a file whose user password is empty opens without one.

Where to go next

Installation covers the wheel, the binary and the crates; the Quickstart shows each surface doing real work. The guide then takes one task per chapter:

• Extracting text: plain text, reading order, page selection.
• Markdown output: headings, lists and tables inferred from layout.
• Styled spans: positioned text runs with font, size, weight, decorations and color.
• Rendering pages: PNG output, scale, font tiers, render reports.
• Extracting images: every image a page draws, at native size.
• Creating PDFs: canvas painting, composed elements and document slots from the CLI, Python and Rust.
• Editing PDFs: incremental updates to an existing file, starting with meta.
• Markdown to PDF: CommonMark+GFM composed into themed, paginated documents.
• Async and remote documents: range-fetching access to local files and HTTP URLs.
• Exploring PDF internals: the JSON value tree, jq queries, hexdumps and the terminal explorer.
• Encrypted documents: passwords on every surface.

The reference section holds the CLI reference, the Python API, the Rust crates and the list of limitations.

pdfboss is dual-licensed under MIT or Apache-2.0, at your option.

Installation

Python

pip install pdfboss

Prebuilt abi3 wheels for CPython 3.12 and later; no Rust toolchain required. The wheel compiles in the predefined CJK CMap set, so CJK-coded documents extract out of the box.

Rendering with fonts="full" substitutes replacement faces for fonts the PDF does not embed. Those faces ship as a separate package, pulled in by the full extra:

pip install "pdfboss[full]"

This installs pdfboss-fonts alongside the wheel. Without it, fonts="full" requires a font_dir argument pointing at faces of your own. See Rendering pages.

CLI

cargo install pdfboss-cli

This installs the pdfboss binary. Two features are on by default:

• substitute-fonts: bundles the OFL Croscore substitute faces (about 4 MB) so render and tui can paint text for PDFs with non-embedded fonts out of the box.
• predefined-cmaps: compiles in the predefined CJK CMap set of ISO 32000 Table 118 (about 830 KB) so text reads Shift-JIS/EUC/Big5/GBK/UHC-coded Type0 fonts.

Opt out of both for a leaner binary:

cargo install pdfboss-cli --no-default-features

Rust crates

The library crates are on crates.io:

cargo add pdfboss-core pdfboss-text pdfboss-output pdfboss-render pdfboss-write pdfboss-markdown pdfboss-aio

Add only what you use: pdfboss-core alone parses; the others build on it.

The library crates keep their optional features off by default:

• pdfboss-render substitute-fonts: the bundled substitute faces.
• pdfboss-core predefined-cmaps: the predefined CJK CMap set.
• pdfboss-aio http: remote documents over HTTP range requests.
• pdfboss-aio write: streaming created documents into tokio writers; ships TokioSink, which presents any tokio::io::AsyncWrite to Pdf::write_into_with (see Creating PDFs).

Enable a feature at add time, for example:

cargo add pdfboss-aio --features http

Building from source

git clone https://github.com/4thel00z/pdfboss
cd pdfboss
cargo build --release           # the CLI lands at target/release/pdfboss
cargo test --workspace          # Rust test suite

The Python extension builds with maturin into the active virtualenv:

maturin develop                 # build the extension into your venv
pytest                          # Python integration tests

Next: the Quickstart.

Quickstart

One taste of each surface. report.pdf stands in for any PDF of yours; Installation covers getting the binary, the wheel and the crates.

CLI

pdfboss info    report.pdf                    # version, page count, page sizes, metadata
pdfboss text    report.pdf --page 2           # extract text (omit --page for all pages)
pdfboss md      report.pdf                    # markdown: headings, lists, tables from layout
pdfboss render  report.pdf --page 1 -o page.png --scale 2.0
mkdir out
pdfboss images  report.pdf -o out/            # embedded images as native-size PNGs
pdfboss create text notes.txt -o notes.pdf    # a new PDF from a word-wrapped text file
pdfboss create md   notes.md -o notes.pdf     # markdown composed with a CSS theme

render prints what it wrote (wrote page.png (1224 x 1584 px)) and warns on stderr about anything it had to drop; images names every file it writes, out/page-1-image-1.png style. Page numbers are 1-based on the command line.

Python

from pathlib import Path

import pdfboss

doc = pdfboss.Document("report.pdf")
print(doc.page_count, "pages, PDF", doc.version)

text = doc.extract_text()          # all pages, form-feed separated
markdown = doc.extract_markdown()  # headings, lists, tables from layout

page = doc[0]
Path("page.png").write_bytes(page.render(scale=2.0))

for image in page.extract_images():
    print(image.width, image.height, len(image.data))

pdf = pdfboss.md.to_pdf(Path("notes.md").read_text())  # markdown -> PDF bytes

Document also opens from memory (Document(data=raw_bytes)), pages index 0-based with negative indexes from the end, and render returns PNG bytes directly. extract_images yields each image the page draws at its native pixel size, PNG-encoded. pdfboss.md.to_pdf composes CommonMark+GFM into a themed PDF (Markdown to PDF); pdfboss.write composes pages, elements and document slots with |, the same vocabulary the CLI and the pdfboss-write crate expose (Creating PDFs).

Rust

With pdfboss-core, pdfboss-output and pdfboss-render added:

use pdfboss_core::Document;
use pdfboss_output::ReadingOrder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    println!("{} pages", doc.page_count());

    let page = doc.page(0)?;
    let text = pdfboss_output::extract_text(&doc, &page, ReadingOrder::Content)?;
    println!("{text}");

    let pixmap = pdfboss_render::render_page(&doc, &page, 2.0)?;
    pixmap.save_png("page.png")?;
    Ok(())
}

render_page returns an RGBA Pixmap (width, height, data); save_png and encode_png turn it into a file or bytes. Page indexes are 0-based, as in Python; only the CLI counts from 1.

Next steps

• Extracting text and Markdown output for layout analysis details.
• Rendering pages for scale, font tiers and PNG compression.
• Extracting images for what counts as an embedded image.
• Creating PDFs for canvas painting, composed pages and document slots.
• Markdown to PDF for themed CommonMark+GFM composition.
• Async and remote documents for AsyncDocument and HTTP range fetching.

Extracting text from PDFs

Text extraction turns a page's positioned glyphs back into readable text: spans are grouped into lines, lines are joined with \n, and spaces are inserted at horizontal gaps. By default reading order follows the content stream: a typeset document writes each column whole before the next begins, so the text comes out column by column, and a figure caption or a footnote reads where the producer placed it. Geometry corrects the streams that write across two columns row by row (a page with a clear gutter still reads column-major) and takes over entirely when a stream was not written in reading order at all, which then reads top to bottom. Two other orders can be selected; see Reading order. Whole-document extraction joins pages with a form feed (\f). For structured output (headings, lists, tables), see Markdown output; for the spans themselves, with fonts, sizes and positions, see Styled spans.

Text drawn turned a quarter, such as a landscape exhibit set on a portrait page or a label running up a chart's side, is laid out in its own upright frame: each span's baseline direction is snapped to the nearest quarter turn, the spans sharing one are grouped into lines and tables the way upright text is, and the groups follow one another top to bottom by where they sit on the page. Text at other angles, such as a diagonal watermark, is treated as the nearest quarter turn. A page with no turned text skips this step.

Reading order

Every extraction entry point takes a reading order. There are three:

pdfboss text report.pdf --reading-order structure-tree
pdfboss md report.pdf --reading-order geometric

from pdfboss import Document, ReadingOrder

doc = Document("report.pdf")
doc.extract_text(reading_order=ReadingOrder.STRUCTURE_TREE)
doc[0].extract_markdown(reading_order="geometric")   # the string value works too

In Rust the order is the last argument of every entry point:

use pdfboss_core::Document;
use pdfboss_output::ReadingOrder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    let page = doc.page(0)?;
    let (text, report) =
        pdfboss_output::extract_text_reporting(&doc, &page, ReadingOrder::StructureTree)?;
    println!("{text}");
    println!("read in {} order", report.order);
    Ok(())
}

ExtractReport::order says which order the page actually came out in: the one requested, or Content when the structure tree was asked for and the page has no entry in it. The content-order walk is compiled without the marked-content bookkeeping the structure-tree walk needs, so the default costs nothing extra.

Annotations in the reading order

Annotations live in the page's /Annots array, not in the content stream, so their place in the reading order comes from the structure tree alone (ISO 32000-1 14.8.2.3.2): a Link, Form or Annot element holds the annotation through an object reference (/Type /OBJR, 14.7.4.3), and the annotation precedes or follows the marked-content sequences its element sits between. Page.content_items() returns the page's content items in that order, sequences and annotations ranked together, each with the element holding it. Text extraction returns no annotation text, so this is where an annotation's slot among the text is read off:

page = doc[0]
annotations = {a.ref: a for a in page.annotations()}
for item in page.content_items():
    if item.kind == "object":
        print(item.rank, item.standard_type, annotations[item.ref].subtype)
    else:
        print(item.rank, item.standard_type, "marked content", item.mcid)

In Rust Document::content_items(&page) returns the same list as PlacedItem records, and StructureTree::place_items_with places any set of ContentItems (sequences by their /StructParents key and MCID, objects by reference) in one shared rank space; the spans of pdfboss_text under structure-tree order carry the holding element in structure.path, which is how a span and an item of the same Link element are matched. Only the page's own content stream and its /Annots are enumerated: the sequences of a form XObject with its own /StructParents are placed when handed in. The Python spans expose the element's description and language but not its reference, so in Python the match between a span and an item goes through the annotation's rectangle.

CLI

pdfboss text report.pdf

prints every page, separated by form feeds. --page selects one page, 1-based:

pdfboss text --page 4 report.pdf

Content that cannot be read is reported on stderr, one warning per skipped stream, with the same 1-based page numbers:

warning: page 17: skipped a form XObject (form limit exceeded)

stdout carries only the extracted text, so the output stays safe to pipe. Encrypted files take --password. See Encrypted documents.

Python

from pdfboss import Document

doc = Document("report.pdf")

text = doc.extract_text()           # all pages, joined by "\f"
page_text = doc[3].extract_text()   # one page (0-based index)

Document.extract_text fans the pages out across the machine's cores: each worker thread holds its own fork of the document (the immutable parsed core is shared, the caches are private), and one font cache serves every worker so each font loads once per document. Both calls release the GIL while they run, so other Python threads keep making progress during long extractions.

Rust

Per page, with pdfboss_output::extract_text:

use pdfboss_core::Document;
use pdfboss_output::ReadingOrder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    for i in 0..doc.page_count() {
        let page = doc.page(i)?;
        let text = pdfboss_output::extract_text(&doc, &page, ReadingOrder::Content)?;
        println!("{text}");
    }
    Ok(())
}

For a whole document, pdfboss_core::map_pages runs a closure over every page in parallel and returns the results in page order. It fans out over std::thread::available_parallelism() threads, each holding its own document fork; workers pull page indexes from a shared counter, so pages of uneven cost cannot strand a fast core behind a slow stripe. Pass one FontCache to the _cached variant so fonts load once per document rather than once per page:

use pdfboss_core::{map_pages, Document};
use pdfboss_output::{FontCache, ReadingOrder};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    let fonts = FontCache::default();
    let outcomes = map_pages(&doc, |doc, page| {
        let (text, _) = pdfboss_output::extract_text_reporting_cached(
            doc,
            page,
            &fonts,
            ReadingOrder::Content,
        )?;
        Ok(text)
    });
    let texts = outcomes.into_iter().collect::<Result<Vec<String>, _>>()?;
    println!("{}", texts.join("\u{c}"));
    Ok(())
}

Under ReadingOrder::StructureTree the _cached call still loads the structure tree on every page, and loading reads the whole parent tree. A document walk loads it once with structure_for, the optional-content state once with oc_state, and drives the _with twin over Immediate from each worker. The tree keeps what each page walk read for the next page, so map_pages_forking gives every worker its own fork of it (the same tree over an empty cache) rather than one tree the workers would queue on:

use pdfboss_core::{map_pages_forking, source::block_on, Document, Immediate};
use pdfboss_output::{structure_for, FontCache, ReadingOrder};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    let order = ReadingOrder::StructureTree;
    let fonts = FontCache::default();
    let oc = doc.oc_state();
    let structure = structure_for(&doc, order);
    let outcomes = map_pages_forking(
        &doc,
        || structure.clone(),
        |structure, doc, page| {
            let (text, _) = block_on(pdfboss_output::extract_text_reporting_cached_with(
                Immediate(doc),
                page,
                &fonts,
                oc.as_ref(),
                structure.as_ref(),
                order,
            ))?;
            Ok(text)
        },
    );
    let texts = outcomes.into_iter().collect::<Result<Vec<String>, _>>()?;
    println!("{}", texts.join("\u{c}"));
    Ok(())
}

Asynchronous callers use extract_text_with against any object source. See Async and remote documents.

Lenient semantics and reporting

Extraction is lenient the way rendering is: content that will not fetch, decode, or parse yields no text rather than an error, so one unreadable stream never costs the rest of the document. extract_text_reporting is what keeps that leniency accountable. It returns the text together with an ExtractReport:

use pdfboss_core::Document;
use pdfboss_output::ReadingOrder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    let page = doc.page(0)?;
    let (text, report) =
        pdfboss_output::extract_text_reporting(&doc, &page, ReadingOrder::Content)?;
    for skip in &report.skipped {
        eprintln!("skipped {} ({})", skip.kind, skip.cause);
    }
    println!("{text}");
    Ok(())
}

report.skipped names each stream that yielded no text: the kind (the page's own contents, a form XObject, an unresolvable XObject, a font's CMap encoding) and the cause (an unsupported filter, a stream that would not read, content that would not parse, a missing resource, an exhausted form nesting or invocation limit). report.hidden counts content the document's optional-content configuration turns off; that is configured behavior, not a loss, so report.is_complete() ignores it and is true exactly when nothing was left out. An empty text with an empty report really is an empty page. The CLI warnings above are this report, printed. Layers the document turns off on screen are excluded from the text: the default optional-content configuration with the View usage application applied, so a print-only layer is left out while a group of another /Intent is kept. The Rust _with entries take the state explicitly, so doc.oc_state_for(Some(OcEvent::Print)) extracts the text as printed.

Encodings

Character decoding covers ToUnicode CMaps, the WinAnsi, MacRoman and Standard simple-font encodings, the built-in encoding of an embedded Type 1 program (the base table of a simple font that names no /Encoding of its own, which is how TeX's symbol and math fonts arrive), and CID-keyed Type0 fonts: embedded /Encoding CMap streams parse, the predefined ISO 32000 CJK CMap set is compiled in (behind the predefined-cmaps feature, on by default in the CLI and the Python wheel), and when /ToUnicode is absent CIDs map to Unicode through the font's character collection. Glyph names resolve through the full Adobe Glyph List plus the TeX symbol-font names the list lacks, so ligatures (fi, fl, …), small-caps variants and math symbols (∀, ∃, ↦, ′) decode to their proper Unicode text.

PDF to Markdown

Markdown output runs layout analysis over the same positioned spans that plain text extraction flattens, and renders the result as CommonMark. The analysis infers:

• Headings: ATX headings (# … ######), ranked by font size. With whole-document extraction the sizes are ranked against every page at once, so a title page or a chapter opener (all of it larger than body text) is read as headings rather than as its own idea of body size. Page-local extraction ranks against that page alone; a page whose text is all one size has no heading to find. Prefer document-wide extraction whenever the document is at hand.
• Lists: bulleted and numbered. Bullets render as - regardless of the source glyph; numbered items keep their detected number as n. .
• Tables: detected both from column gaps and from drawn borders, so bordered grids and boxed lists without column gaps are found too. When a table's structure is drawn as ruled lines, those borders decide the grid ahead of column occupancy. Tables render as pipe tables while every cell stands in one column, and as HTML tables as soon as a cell spans several.
• Two-column pages: read column-major: the left column top to bottom, then the right. The reading_order keyword (CLI --reading-order) selects content order, the structure tree of a tagged PDF, or geometric position; see Reading order.
• Tagged PDFs: under structure-tree reading order the tags decide the blocks on every page the tree reaches (ISO 32000-1 14.8.4.3): H1 to H6 are headings at that level, H a heading as deep as its Part, Art and Sect elements nest, L a list with one item per LI and the Lbl text as the marker (read as a number, a letter or a Roman numeral when the list's ListNumbering attribute names that numbering system, an unlabelled item continuing the count), Table a table with a row per TR and a cell per TH or TD spanning what its ColSpan and RowSpan attributes say, and every other block-level element a paragraph; a Caption or a TOC entry is a paragraph of its own, the text of Figures, Formulas and Forms is laid out by the heuristics below apart from the text around it, and the paragraphs of a BlockQuote render as a block quote. Content the tree does not reach still goes through the heuristics below.
• Page headers, footers and page numbers: a page's first or last line, repeated near-verbatim at the same height on at least half the pages (three at minimum), is tagged as a running page header or footer; a line that is nothing but a page number is tagged without any repetition required. Content the producer marked as a pagination artifact (ISO 32000-1 14.8.2.2: a running head, a folio, a watermark) is tagged on the producer's word, with no repetition needed. Tagged lines are dropped from the Markdown output.

CLI

pdfboss md report.pdf

--page extracts one page, 1-based; heading sizes are then ranked per page rather than across the document:

pdfboss md --page 4 report.pdf

Warnings for skipped content appear on stderr, exactly as for pdfboss text. See lenient semantics.

Before and after

Page 4 of a physics report carries a cut-flow table. Plain text extraction flattens it into space-separated lines:

Table 4: Muon RD Branch no. 1
Cuts km2loose acc km2tight acc bipulkm2acc acc
BADRUN 5189813 (-) 5189813 (-) - (-)
ictime − cktbm 3324048 (-) 3324048 (-) - (-)
icbit 3322245 (-) 3322245 (-) - (-)

pdfboss md --page 4 report.pdf recovers the grid (first rows shown):

Table 4: Muon RD Branch no. 1

| Cuts | km2loose acc | km2tight acc | bipulkm2acc acc |
| --- | --- | --- | --- |
| BADRUN | 5189813 (-) | 5189813 (-) | - (-) |
| ictime − cktbm | 3324048 (-) | 3324048 (-) | - (-) |
| icbit | 3322245 (-) | 3322245 (-) | - (-) |

Python

from pdfboss import Document

doc = Document("report.pdf")

markdown = doc.extract_markdown()       # whole document, headings ranked globally
page_md = doc[3].extract_markdown()     # one page, headings ranked per page

Document.extract_markdown extracts the pages in parallel and releases the GIL, like extract_text.

Layout blocks

layout returns the structure the Markdown is rendered from instead of the text: per page, a list of LayoutBlock objects in reading order, each with its kind ("heading", "paragraph", "list", "table"), its bbox in PDF user space (y-up, like Span.bbox), its plain text, a heading's level, a paragraph's role ("body", "quote", "page_header", "page_footer"), a list's items (each with its own marker, text and bbox) and a table's rows of cells.

for page in doc.layout():               # every page, headings ranked globally
    for block in page:
        print(block.kind, block.bbox, block.text[:40])

blocks = doc[3].layout()                # one page, headings ranked per page
first_two = doc.layout(pages=[0, 1])    # document-wide ranking, two pages returned

The thresholds that cut the blocks are keyword arguments, defaulting to the values extract_markdown uses. Callers that need block boxes cut differently tune them per call:

blocks = doc.layout(
    paragraph_gap=1.6,                  # break paragraphs at 1.6 line pitches
    paragraph_pitch="lower_half_median",  # pitch from the tighter half of the steps
    header_footer_min_pages=2,
)

Some producers draw a line twice at the same position, for example over a fresh white box or offset by a fraction of a point to fake bold. Text, Markdown and layout() read such a line once: before layout, a span that repeats an earlier span on the page (same text, size and rotation, origin within redraw_tolerance of the size, default 0.1, and starting in the first half of that span) is dropped, so the copy counts neither in the line nor in the heading size ranking. redraw_tolerance=0 keeps every copy. spans() always reports every draw.

The stubs list every keyword with its default and meaning. AsyncDocument.layout and AsyncPage.layout are the coroutine twins. In Rust the same blocks come from extract_layout_opts and extract_page_layout_opts, the thresholds from LayoutOptions.

Rust

Whole document, with pdfboss_output::extract_markdown:

use pdfboss_core::Document;
use pdfboss_output::ReadingOrder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    let markdown = pdfboss_output::extract_markdown(&doc, ReadingOrder::Content)?;
    println!("{markdown}");
    Ok(())
}

One page, with extract_page_markdown:

use pdfboss_core::Document;
use pdfboss_output::ReadingOrder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    let page = doc.page(0)?;
    let markdown = pdfboss_output::extract_page_markdown(&doc, &page, ReadingOrder::Content)?;
    println!("{markdown}");
    Ok(())
}

extract_markdown_reporting returns the Markdown together with one ExtractReport per page, in page order (the same accountability contract as text extraction): unreadable content costs its own text and nothing else, and the report says what was left out. See lenient semantics for the report's shape. Asynchronous callers compose extract_page_markdown_with against any object source. See Async and remote documents.

Emphasis survives into the output: bold and italic runs render as **bold** and *italic* inside paragraphs and list items, and under structure-tree reading order text tagged as a Code element renders as inline code between backticks. Headings drop emphasis markers: a heading is already the strongest thing on the page. Blocks are separated by a blank line, across page boundaries too, so the document reads as one continuous Markdown file. For the raw style information itself, see Styled spans; for the reverse direction (Markdown composed into a PDF), see Markdown to PDF.

Styled spans

Text extraction gives you a page as flowing plain text. Spans are the layer underneath: each span is one positioned run of text together with everything the file states about how it is shown (position, size, font, weight, color, visibility). Use spans when you need to know not just what a page says but where and in what style: finding headings, separating an OCR layer from printed text, or feeding a layout analysis of your own.

What a span carries

Two of these deserve a note up front:

• invisible is the signature of an OCR text layer. Scanned PDFs with a text layer draw the page image and then show the recognized text under render mode 3 or 7, which paint nothing. The text extracts normally: it is just never painted.
• color is None for pattern fills, which have no single color.

Box and baseline

y is the baseline. The box is the em box the font declares, placed on it: bbox[1] == y + descent and bbox[3] == y + ascent, where ascent is the FontDescriptor's /Ascent (else the /FontBBox top, else /CapHeight, else 800 per mille) and descent its /Descent (else the /FontBBox bottom, else -200 per mille), both scaled by the effective size. descent is zero or negative, the way /Descent is. The box is a font metric rather than glyph ink: a span of digits does not reach the descent and a span of capitals does not reach the ascent. A font whose descriptor states zero metrics, as the math extension fonts of tectonic documents do, takes its /FontBBox extent, so a display integral hanging two em below the baseline sits inside its span box, which then stands well clear of the ink of the smaller glyphs in that font. Horizontally the box runs from the origin to the advance after the last glyph.

Vertical writing (vertical) takes the advance as its vertical extent, so ascent and descent are the advance's extents above and below the origin, and the box spans half the size to each side of the baseline.

The decoration flags below are judged in this frame: a ruling is an underline or a strikethrough by where it crosses the box, and a highlight band by how much of the box it covers.

Decorations

PDF has no underline, strikethrough or highlight attribute in its text state. The flags come from two places:

• What the page draws. A horizontal ruling (a stroked line or a thin filled bar) is an underline when it sits between 0.3 of the size below the baseline (or a tenth of the size under the box bottom, for a font whose descent reaches deeper) and 0.05 of the size above it, and a strikethrough when it crosses the x-height band, 0.15 to 0.6 of the size above the baseline. A filled rectangle about a line tall is a highlight when it is painted before the text, has a hue (white and gray bands are backgrounds, knockouts and cell fills), is lighter than the text's color, and covers at least half the box; highlight_color is its fill color, read the way color is. In every case the decoration must cover at least 60% of the span's width and stop within an em of the text it covers on both ends. That last rule is what separates decorations from table borders and paragraph shading, which run to the cell edge or the margin rather than to the text; bands that tile one shaded area (same color, same extent, one above the other) are judged together, so a shaded row whose text happens to fill it does not count when its neighbours overhang theirs. A cell border that ends where the cell's text ends, or shading whose every line is filled with text, still reads as an underline or a highlight. Coverage is judged per span: a mark over one word of a span that is a whole line covers too little of it to count.
• Text markup annotations. /Highlight, /Underline, /Squiggly and /StrikeOut annotations (ISO 32000-1 §12.5.6.10) set the flags on every span their /QuadPoints quadrilaterals cover by 60% of the width and half the box height; a squiggly underline counts as an underline, and highlight_color is the annotation's /C (or None without one). Annotations flagged Hidden or NoView, or hidden by their /OC entry, mark nothing. Authored markup is taken as such: no color, paint order or extent test applies to it.

Vertical writing is left unmarked: its decorations are vertical lines beside the text, indistinguishable from column rules.

Python

Page.spans() returns the page's spans in emission order. It releases the GIL while it runs and is lenient the same way text extraction is: unreadable content yields no spans rather than raising.

import pdfboss

doc = pdfboss.Document("report.pdf")
for span in doc[0].spans():
    if not span.bold:
        continue
    print(f"{span.size:5.1f}pt  {span.font_name:30s}  {span.text!r}")

Document.spans() iterates the whole document lazily, page by page: it buffers one page's spans at a time, extracts each page with the GIL released, and shares one font cache across the walk, so a font used on every page loads once. Pass pages=[...] (0-based) to restrict the walk, in the order given.

Finding headings (bold text larger than the document's body size) is a document-level walk:

from collections import Counter

import pdfboss

doc = pdfboss.Document("report.pdf")
sizes: Counter[int] = Counter()
bold = []
for span in doc.spans():
    sizes[round(span.size)] += len(span.text)
    if span.bold:
        bold.append(span)

body = sizes.most_common(1)[0][0]
for span in bold:
    if span.size <= body:
        continue
    print(f"page {span.page + 1}: {span.size:.0f}pt {span.text}")

Detecting an OCR layer is a one-liner over invisible:

spans = doc[0].spans()
ocr = [span for span in spans if span.invisible]
print(f"{len(ocr)} of {len(spans)} spans are invisible (an OCR text layer)")

Both have async twins, await page.spans() and async for span in doc.spans(), described in Async and remote documents.

Rust

pdfboss_text::extract_spans returns a Vec<TextSpan> carrying the same fields as the Python Span (as plain struct fields: text, x, y, end_x, end_y, rotate, size, font, font_name, page, bbox, ascent, descent, bold, italic, monospace, serif, font_family, font_stretch, font_weight, rise, vertical, invisible, color, underline, strikethrough, highlight, highlight_color):

use pdfboss_core::Document;
use pdfboss_text::extract_spans;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    for index in 0..doc.page_count() {
        let page = doc.page(index)?;
        for span in extract_spans(&doc, &page)? {
            if !span.bold || span.size <= 12.0 {
                continue;
            }
            println!("page {}: {:.0}pt {}", span.page + 1, span.size, span.text);
        }
    }
    Ok(())
}

The crate also offers extract_spans_reporting (an ExtractReport naming each stream that could not be read: an empty span list with an empty report really is an empty page), extract_spans_reporting_cached (one FontCache shared across a whole-document walk, the same trick Document.spans() uses), and extract_spans_and_rulings_reporting, which additionally returns the page's Ruling segments, the drawn lines the underline and strikethrough flags are derived from.

Spans are the input to the layout analysis behind Markdown output; reach for that chapter when you want headings, lists and tables inferred for you rather than deriving them from spans yourself.

Rendering PDF pages to PNG

pdfboss rasterizes pages to RGBA pixels with anti-aliasing and encodes them as PNG, PPM, BMP or JPEG. The scale factor is the points-to-pixels ratio: at 1.0 one PDF point becomes one pixel, so a US Letter page renders to 612 × 792 pixels; at 2.0 to 1224 × 1584. The pixel size is ceil(crop_w * scale) × ceil(crop_h * scale) after page rotation, on a white background.

This chapter is about rasterizing whole pages. To pull out the images a page embeds, at their native resolution, see Extracting images.

CLI

pdfboss render report.pdf --page 1
pdfboss render report.pdf --page 1 --scale 2 -o page-1@2x.png
pdfboss render report.pdf --page 1 --scale 2 -o page-1.ppm

The first form writes page-1.png (--page is 1-based). Further flags:

• -o <OUT>: the output file; its extension picks the format, .png, .ppm, .bmp or .jpg (see Output formats). Any other extension is an error.
• --fonts <FONTS>: which fonts to paint, one of embedded-only, all-embedded or full (see the tiers below). The default resolves to full when substitute faces are available (the compiled-in OFL set or --font-dir), otherwise all-embedded.
• --font-dir <FONT_DIR>: a directory of substitute faces for --fonts full (e.g. an installed pdfboss-fonts package), named as listed under Substitute face files. Overrides the compiled-in OFL set.
• --png-compression <PNG_COMPRESSION>: none, fast, default or best; PNG only.
• --jpeg-quality <1-100>: the JPEG quality (default 90); JPEG only.
• --password <PASSWORD>: for encrypted files, covered in Encrypted documents.

Anything the render dropped is warned on stderr.

Font tiers

Glyph painting is staged in tiers; each tier is a strict superset of the previous one.

• embedded-only paints only embedded TrueType outlines: the fastest tier, and TrueType only, not every embedded font.
• all-embedded (the default when no substitute faces are available) paints every embedded font program: TrueType, CFF, Type1 and Type3.
• full (the default whenever substitute faces are available) additionally substitutes a replacement face for non-embedded simple fonts: from a directory you supply (--font-dir, font_dir=), or from the compiled-in OFL Croscore set (Arimo/Tinos/Cousine, metric-compatible with Helvetica/Times/Courier). In Python, pip install pdfboss[full] installs those faces as the pdfboss-fonts package; with neither font_dir nor that package available, fonts="full" raises ValueError.

Text a tier leaves unpainted still advances (through the PDF's own /Widths, or the Adobe Core-14 AFM tables for a standard-14 face), so everything painted around it stays where the page put it. /Symbol and /ZapfDingbats have no license-clean substitute and stay blank; see Limitations.

Substitute face files

A substitute directory (--font-dir, font_dir=, SubstituteSource::Dir) holds one file per face, looked up by these exact names:

A file that is missing or unreadable means no substitution for the faces that map to it; nothing else in the directory is read.

Leniency and reporting

Rendering never fails because one construct in a page would not read: content pdfboss cannot fetch, decode or parse is skipped and the rest of the page still rasterizes. The honest consequence is that a page can come back blank without an error. The reporting variants return what was dropped or approximated, one line per distinct loss, for example "153 glyphs skipped: no glyph for code 9 in /MBIPWP+Times-Roman" or "6 annotations skipped: the resource is missing". An empty report means the page rasterized exactly as it describes itself.

Two things are deliberately not reported, because they are configured behavior rather than a failure: text left unpainted by the requested font tier, and content in optional-content layers (PDF layers) the document turns off. The latter is counted separately, on the report's hidden counter in Rust.

The layers that are off are the ones a viewer hides on screen: the default configuration's /BaseState, /ON and /OFF, then the usage application dictionaries for the View event (a layer whose usage says /ViewState /OFF, such as a print-only notice, does not paint), and a group whose /Intent does not match the configuration's never hides anything. That is the state Document::oc_state() builds and pdfium and pdf.js render by default. Document::oc_state_for(Some(OcEvent::Print)) builds the printed state and oc_state_for(None) the default configuration alone, without any usage application, which ISO 32000-1 prescribes for printing and aggregating applications; pass either through RenderOptions::oc.

Annotations and transparency groups

Annotations paint after the page content. An annotation with an appearance stream (/AP /N, with /AS choosing the state) runs that stream fitted to its /Rect. Square, Circle, Line, Polygon, PolyLine, Ink and text markup annotations without one get an appearance built from their own entries (colour, border width and dash, interior colour, opacity), and a Link with /Border or /BS gets its border. The Hidden, NoView, Invisible and NoRotate flags are honoured. A widget without an appearance stream paints nothing: field values are read (see Reading forms, bookmarks and attachments) but never turned into pixels.

A form XObject with /Group /S /Transparency is composited as one object: its content runs from constant alpha 1, blend mode Normal and no soft mask, renders offscreen, and the result is composited once with the alpha, blend mode and soft mask in force at its Do. A group with /K true paints as an ordinary group and reports knockout group skipped: not supported yet.

Python

Page.render returns PNG bytes. scale must be positive and finite (ValueError otherwise).

from pathlib import Path

import pdfboss

doc = pdfboss.Document("report.pdf")
page = doc[0]
png = page.render(scale=2.0)
Path("page-1.png").write_bytes(png)

render accepts fonts= ("embedded-only", "all-embedded", "full"), font_dir=, compression= ("none", "fast", "default", "best"), format= ("png", "ppm", "bmp", "jpeg", see Output formats) and quality= (1 to 100, JPEG only), and releases the GIL while it runs. fonts= defaults to None, which resolves to "full" when font_dir= is given or the pdfboss-fonts package is importable, and to "all-embedded" otherwise. Page.render_reporting renders the same way and returns (png, warnings):

png, warnings = page.render_reporting()
for line in warnings:
    print(line)

Document.render_pages renders many pages fanned out across the machine's cores: every page by default, or the 0-based pages given, returned in the order given.

pngs = doc.render_pages(scale=2.0)
first_two_reversed = doc.render_pages(pages=[1, 0])

The full signature is render_pages(pages=None, scale=1.0, fonts=None, font_dir=None, compression="default", format="png", quality=90); fonts, font_dir, compression, format and quality mean the same as on Page.render, applied to every page, and a fonts of None resolves the same way. The stub file _pdfboss.pyi documents each parameter.

All three have async twins on AsyncPage/AsyncDocument, which also render documents opened over HTTP. See Async and remote documents.

Output formats

Every render entry point writes one of four formats, chosen by format= in Python, by the -o extension on the CLI, and by pdfboss_render::ImageFormat in Rust:

PPM and BMP drop the alpha channel; a rendered page is filled white, so alpha is 255 everywhere and nothing is lost. Reach for them when the pixels are consumed right away (a benchmark, an OCR or vision pipeline, a diff against another renderer) and the PNG encode would be wasted work: Pillow, numpy and ImageMagick read both directly.

JPEG is the one lossy choice: it trades exact pixels for smaller files on photographic and scanned pages, with the quality knob scaling the standard quantization tables (50 uses them as printed, 100 keeps every coefficient). On a mostly white text page PNG stays both smaller and exact, so prefer JPEG only where the content is continuous-tone. Chroma is not subsampled, so colored text keeps sharp edges. The encoder is pdfboss's own, written from the JPEG specification, and costs two to three times the default PNG encode per page.

ppm = page.render(scale=2.0, format="ppm")
bmp, warnings = page.render_reporting(scale=2.0, format="bmp")
jpg = page.render(scale=2.0, format="jpeg", quality=80)

PNG compression

The compression level trades encode time against file size; every level produces the same pixels. none is fastest and largest, fast is very fast with a decent ratio, default balances the two, and best produces the smallest files, much slower. The level only touches the PNG encoder; even none still filters rows and writes checksums, so a raw-pixel consumer is better served by ppm or bmp. Pick it by whether you are writing throwaway intermediates or archiving.

Rust

pdfboss_render::render_page(doc, page, scale) returns a Pixmap: width, height, and data holding width * height * 4 RGBA bytes (straight alpha, row-major from the top-left). Pixmap::save_png writes it to a file; encode_png/encode_png_with return the bytes, the latter taking a PngCompression (None, Fast, Balanced or Best; Balanced is the level the other surfaces call default).

render_page_with_options adds RenderOptions, a struct of four public fields:

• glyph_painting selects the GlyphPainting tier: EmbeddedTrueTypeOnly, AllEmbedded or Full.
• substitutes says where the Full tier's replacement faces come from. SubstituteSource::Builtin is the compiled-in OFL set, present only when the crate is built with the substitute-fonts Cargo feature; without that feature, Builtin degrades to no substitution, so Full behaves exactly like AllEmbedded. The probe pdfboss_render::builtin_fonts_available() reports whether the compiled-in set exists. SubstituteSource::Dir(path) reads faces from a directory named as in Substitute face files. The default SubstituteSource::None substitutes nothing, so Full behaves like AllEmbedded until you opt in.
• oc: Option<Arc<OcState>> is the document's optional-content visibility. The synchronous entry points fill it from the document when it is None; an asynchronous caller builds it itself, from AsyncDocument::oc_state, and leaving it None there renders every layer. See Async and remote documents.
• cache: Option<Arc<RenderCache>> shares one RenderCache across a whole-document walk. It retains loaded fonts and parsed ICCBased colorspace outcomes across pages; None keeps every load page-local.

render_page_reporting returns the RenderReport alongside the pixels; report.summary() is a one-line count per kind, report.warnings() one line per distinct drop.

use pdfboss_core::Document;
use pdfboss_render::{
    render_page, render_page_reporting, GlyphPainting, PngCompression, RenderOptions,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    let page = doc.page(0)?;

    let pixmap = render_page(&doc, &page, 2.0)?;
    pixmap.save_png("page-1.png")?;

    let opts = RenderOptions {
        glyph_painting: GlyphPainting::EmbeddedTrueTypeOnly,
        ..RenderOptions::default()
    };
    let (pixmap, report) = render_page_reporting(&doc, &page, 1.0, &opts)?;
    if let Some(summary) = report.summary() {
        eprintln!("{summary}");
    }
    for warning in report.warnings() {
        eprintln!("{warning}");
    }
    let png = pixmap.encode_png_with(PngCompression::Best)?;
    std::fs::write("page-1-small.png", png)?;
    Ok(())
}

For a whole document, pass one RenderCache to every page, so each font program and each ICCBased profile loads once per document rather than once per page:

use std::sync::Arc;

use pdfboss_core::{map_pages, Document};
use pdfboss_render::{render_page_with_options, RenderCache, RenderOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    let opts = RenderOptions {
        cache: Some(Arc::new(RenderCache::default())),
        ..RenderOptions::default()
    };
    let outcomes = map_pages(&doc, |doc, page| {
        render_page_with_options(doc, page, 2.0, &opts)
    });
    for (index, pixmap) in outcomes.into_iter().enumerate() {
        pixmap?.save_png(format!("page-{}.png", index + 1))?;
    }
    Ok(())
}

Extracting images from PDFs

pdfboss extracts the images a page draws (photographs, scans, logos, figures), each decoded at its own pixel dimensions and delivered as RGBA with alpha. Three surfaces expose it: the pdfboss images CLI command, Page.extract_images in Python, and pdfboss_render::extract_page_images in Rust. To rasterize a whole page to a single PNG instead, see Rendering pages.

What gets extracted

Extraction walks the page's content stream and collects an image at every point where one is drawn:

• Occurrence-based. The result reflects what the page draws, not what its resources contain. An image drawn twice appears twice; an image XObject listed in the resources but never drawn does not appear at all.
• Drawing order. Images come back in the order the content draws them.
• Form XObjects are followed. An image drawn inside a form (a reused header graphic, an overlaid figure) is reached through the form, to the same bounded nesting depth the renderer uses, so a form that draws itself terminates instead of recursing forever.
• Inline images are included. BI … ID … EI sequences embedded directly in the content stream extract like any image XObject.
• Stencil masks are skipped. An image with /ImageMask true paints the current fill color through a 1-bit stencil; it carries no pixels of its own, so there is nothing to extract.
• /SMask becomes the alpha channel. An image's soft mask is merged into the output as straight (non-premultiplied) alpha.
• Native size. Each image decodes at its own /Width × /Height, never at render resolution or at the size it occupies on the page. A 3000 × 2000 photo scaled into a thumbnail box still comes out at 3000 × 2000.
• Optional content is not consulted. An image inside a hidden /OC group is still embedded in the file, so it still extracts.
• Lenient. Content that cannot be read or decoded contributes nothing rather than failing the call, matching how rendering skips what it cannot draw.

Filtering small images

There is no hidden minimum-size filter: every drawn image comes back, including one-pixel spacers and thin decorative strips. Each result carries its native width and height, so callers apply their own threshold: the synchronous Python and Rust examples below skip anything under 100 × 100 pixels.

Where an image is drawn

extract_images answers what a page draws. Page.images answers where, without decoding a pixel: one PlacedImage per draw, in the same drawing order, each carrying the device-space box the image occupies. It comes from the same content-stream walk that produces styled spans, so a span's bbox and an image's bbox share one frame and can be compared directly. Use it to tell a scanned page from a born-digital one, to find the figure regions of a mixed page, or to measure how much of a page is picture before deciding whether a vision model needs to see it.

import pdfboss

doc = pdfboss.Document("report.pdf")
for number, page in enumerate(doc, start=1):
    mx0, my0, mx1, my1 = page.media_box
    area = (mx1 - mx0) * (my1 - my0)
    covered = 0.0
    for image in page.images():
        x0, y0, x1, y1 = image.bbox
        x0, y0 = max(x0, mx0), max(y0, my0)
        x1, y1 = min(x1, mx1), min(y1, my1)
        covered += max(x1 - x0, 0.0) * max(y1 - y0, 0.0)
    print(f"page {number}: {covered / area:.0%} covered by images")

What a PlacedImage carries:

The box is image space's unit square mapped through the CTM in force at the Do (or BI), including every enclosing form's /Matrix, so a rotated or skewed image reports the axis-aligned box around its outline. It is in the same space as media_box: unrotated PDF user space, before any /Rotate, which is why the example measures against media_box and not against width and height (those are after rotation). It is not clipped: an image the content places partly off the page reports the box the content gave it, and intersecting with media_box or crop_box is the caller's decision, as the example does.

Placement differs from extraction on two points, both deliberate:

• Stencil masks are placed. A 1-bit fax scan is often an /ImageMask stencil, and for the question "how much of this page is picture" it is the page. extract_images skips stencils because they carry no pixels of their own, so when a page draws one the two lists do not align index for index; the stencil flag says which entries extract_images left out.
• Hidden optional content is excluded. Like text, an image inside a BDC /OC span the document turns off on screen (the default configuration with the View usage application applied), or an XObject with a hidden /OC entry, is drawn nowhere and placed nowhere. extract_images embeds it anyway, because the bytes are in the file.

Otherwise the two agree: occurrence-based, drawing order, form XObjects followed to the same bounded depth, inline images included, lenient about content that will not read. AsyncPage.images is the async twin.

In Rust the same walk is pdfboss_text::placed_images (and placed_images_with over any AsyncObjectSource), returning Vec<PlacedImage> with the fields above and bbox as a Rect.

CLI

pdfboss images writes every image the selected pages draw as a PNG named page-N-image-M.png, with both numbers 1-based and M counting in drawing order within the page:

mkdir images
pdfboss images --page 6 -o images report.pdf

wrote images/page-6-image-1.png (137 x 178 px)
wrote images/page-6-image-2.png (750 x 989 px)
wrote images/page-6-image-3.png (132 x 177 px)
wrote images/page-6-image-4.png (216 x 295 px)
wrote images/page-6-image-5.png (144 x 168 px)
wrote images/page-6-image-6.png (50 x 120 px)
wrote images/page-6-image-7.png (165 x 211 px)
wrote images/page-6-image-8.png (145 x 188 px)
wrote images/page-6-image-9.png (165 x 206 px)
extracted 9 images

Without --page every page is processed. -o names the output directory (default: the current directory); it must already exist. --png-compression trades encode time against file size: none, fast, default or best, all producing the same pixels. A page whose images cannot be decoded writes nothing for them and still exits 0.

Python

Page.extract_images returns a list of PageImage objects, each holding the PNG-encoded pixels as data plus the native width and height. Saving every sufficiently large image in a document:

from pathlib import Path

import pdfboss

doc = pdfboss.Document("report.pdf")
out = Path("images")
out.mkdir(exist_ok=True)
for number, page in enumerate(doc, start=1):
    for i, image in enumerate(page.extract_images(), start=1):
        if image.width < 100 or image.height < 100:
            continue
        target = out / f"page-{number}-image-{i}.png"
        target.write_bytes(image.data)
        print(f"{target}: {image.width} x {image.height}")

The drawing-order index i is kept even for skipped images, so file names stay aligned with what pdfboss images would produce. extract_images accepts the same compression argument as render ("none", "fast", "default", "best").

AsyncPage.extract_images is the async twin, with the same drawing-order, native-size and leniency semantics (see Async and remote documents):

import asyncio

import pdfboss

async def main() -> None:
    doc = await pdfboss.AsyncDocument.open("report.pdf")
    page = doc.page(0)
    images = await page.extract_images()
    print(f"page 1 draws {len(images)} images")

asyncio.run(main())

Rust

pdfboss_render::extract_page_images returns Vec<Pixmap>: RGBA8 pixels with straight alpha, row-major from the top-left, with public width, height and data fields. Pixmap::save_png writes one to disk; encode_png/encode_png_with produce the bytes in memory. With pdfboss-core and pdfboss-render as dependencies:

use pdfboss_core::Document;
use pdfboss_render::extract_page_images;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    let page = doc.page(0)?;
    let images = extract_page_images(&doc, &page)?;
    for (i, image) in images.iter().enumerate() {
        if image.width < 100 || image.height < 100 {
            continue;
        }
        image.save_png(format!("image-{}.png", i + 1))?;
        println!("image-{}.png: {} x {}", i + 1, image.width, image.height);
    }
    Ok(())
}

extract_page_images_with is the same walk over any pdfboss_core::AsyncObjectSource. pdfboss_aio::AsyncDocument implements that trait and is an Arc handle, so cloning one to pass by value is cheap (with pdfboss-aio, pdfboss-render and tokio as dependencies):

use pdfboss_aio::AsyncDocument;
use pdfboss_render::extract_page_images_with;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = AsyncDocument::open("report.pdf").await?;
    for index in 0..doc.page_count() {
        let page = doc.page(index)?;
        let images = extract_page_images_with(doc.clone(), &page).await?;
        for (i, image) in images.iter().enumerate() {
            image.save_png(format!("page-{}-image-{}.png", index + 1, i + 1))?;
        }
    }
    Ok(())
}

The async form works identically over a remote document opened with AsyncDocument::open_url, fetching only the byte ranges the images need. Full option listings live in the CLI reference.

Reading forms, bookmarks and attachments

A PDF carries more than its pages: an interactive form with its field values, a bookmark tree, page labels such as iv or A-3, named destinations, embedded files and viewer preferences. pdfboss reads all of them from the catalog as plain data, from Python, Rust and the async surfaces. Nothing here writes: form fields are read, not filled, and signatures are read as dictionaries, not verified. The full class list is in the Python reference.

Python

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, len(item.children))

labels = doc.page_labels()
print(doc.page_label(0))

for attachment in doc.embedded_files():
    with open(attachment.name, "wb") as out:
        out.write(doc.embedded_file_data(attachment))

prefs = doc.viewer_preferences()
if prefs:
    print(prefs.display_doc_title, prefs.direction)

form_fields() returns every terminal field with the entries it inherits from its parents filled in: name is the fully qualified name, flags a FieldFlags with one boolean per flag, value the field's value as plain Python data, and widgets the widget annotations that draw it. The typed readers text, checked, selected, state and signature return None when the field is of another type. interactive_form() returns the form dictionary itself (need_appearances, signatures_exist, calculation_order, xfa) or None when the document has no form.

outline() returns the bookmark tree, each item with its title, the 0-based page it points to when the destination resolves through the page tree, its destination (fit mode and coordinates), open, color, bold and italic, and nested children. named_destinations() maps each name to a Destination. page_labels() returns the numbering ranges, and page_label(index) formats one page's label. embedded_files() lists attachments with their names, MIME type, size and dates; embedded_file_data(file) decodes one. Every reader has an AsyncDocument coroutine of the same name.

Four more readers cover the catalog and page structures a viewer consults before showing anything. requirements() lists the features the document needs a reader to support, each with the handlers a reader that lacks the feature would run; pdfboss reports a JavaScript handler by name and never runs it. legal_attestation() returns the counts of content a certifying signature cannot vouch for, one integer attribute per count and counts() for the whole table, with the signer's attestation. On a page, viewports() returns the measurement viewports, each a bbox with a measure whose number-format chains (distance, area, angle and the rest) say how user-space lengths convert to real-world units, and separation_info() returns a pre-separated page's device_colorant with the pages of its separation set as 0-based indices. Both page readers have AsyncPage coroutine twins.

for viewport in doc[0].viewports():
    if viewport.measure:
        print(viewport.name, viewport.measure.scale_ratio)

separation = doc[0].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.counts()["non_embedded_fonts"], legal.attestation)

optional_content_groups(event) lists the document's optional content groups, the PDF layers, in the order the catalog declares them. Each has its name, its intent names, its usage dictionary (view, print, export states, print_subtype, zoom_min, zoom_max, language, page_element, creator and the user entries) and visible, the group's state under the event asked for. The default "view" is the state a viewer shows on screen and the one text extraction and rendering use: the default configuration's on and off lists, then the usage application dictionaries for the View event, while a group whose intent does not match the configuration's never hides content. "print" and "export" apply that event's dictionaries instead, and None applies none, which is the state the standard prescribes for printing and aggregating applications.

for layer in doc.optional_content_groups():
    print(layer.name, layer.visible, layer.usage.print_subtype)

printed = {layer.name: layer.visible for layer in doc.optional_content_groups("print")}

Annotations, links and actions

annotations() on a page returns its annotation dictionaries in /Annots order, each read as data: the common entries of every annotation (subtype, rect, contents, name, modified, flags, border, color, struct_parent, optional_content, whether an appearance stream is present), the markup entries in markup (title, subject, opacity, in_reply_to, reply_type, intent, created, rich_contents, popup), and the entries of the subtypes pdfboss reads further: a link's destination (explicit or looked up by name, the page resolved to a 0-based index), a text reply's state and state_model, a text or pop-up annotation's open and icon, a pop-up's parent, and a file attachment's file. file_spec_data(spec) on the document decodes the stream a FileSpec embeds; a specification whose file system is URL exposes the address as url instead.

Every action is read and none is executed. action holds an annotation's /A with its /Next chain in next; additional_actions on an annotation, a page and the document hold the /AA trigger events ("cursor-enter", "mouse-up", "page-open", "open", "will-close" and the rest of the standard's tables) with the action each fires. An Action names its kind as the /S entry is written: GoTo carries a destination, GoToR and GoToE a file and a page-numbered destination or a named_destination in the other document (an embedded go-to adds its target path), Launch a file and windows parameters, URI the uri and is_map, Named the viewer action's name, JavaScript the script text; any other kind, SubmitForm for instance, keeps its whole dictionary in entries.

for annotation in doc[0].annotations():
    action = annotation.action
    if action and action.kind == "URI":
        print("link to", action.uri, "at", annotation.rect)
    elif annotation.destination:
        print("link to page", annotation.destination.page)
    if annotation.markup and annotation.markup.in_reply_to is None:
        print(annotation.markup.title, "wrote:", annotation.contents)
    if annotation.file and annotation.file.ref:
        with open(annotation.file.name, "wb") as out:
            out.write(doc.file_spec_data(annotation.file))

for triggered in doc.additional_actions():
    print("document", triggered.trigger, triggered.action.kind)

Rust

use pdfboss_core::Document;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("form.pdf")?;
    for field in doc.form_fields() {
        println!("{} = {:?}", field.name, field.value);
    }
    for item in doc.outline() {
        println!("{} ({} children)", item.title, item.children.len());
    }
    if let Some(labels) = doc.page_labels() {
        println!("{} label ranges", labels.len());
    }
    for file in doc.embedded_files() {
        std::fs::write(&file.name, doc.embedded_file_data(&file)?)?;
    }
    Ok(())
}

The same readers exist as free functions over any async object source, named with a _with suffix and taking the source and the trailer dictionary: pdfboss_core::{form_fields_with, interactive_form_with, outline_with, named_destinations_with, page_labels_with, embedded_files_with, embedded_file_data_with, file_spec_data_with, viewer_preferences_with, requirements_with, legal_attestation_with, viewports_with, separation_info_with, annotations_with, action_with, page_additional_actions_with, document_additional_actions_with, optional_content_groups_with}. pdfboss_aio::AsyncDocument exposes them as methods, and Document::{requirements, legal_attestation, viewports, separation_info, annotations, action, page_additional_actions, additional_actions, file_spec_data, optional_content_groups} are the sync forms of the last ten. The groups reader takes an Option<OcEvent>, the same value Document::oc_state_for builds a visibility state from.

CLI

The command line has no dedicated command for these structures, but pdfboss q reaches the raw catalog dictionary through the object tree: the trailer's Root is a reference, objects are keyed by number, and a reference prints as {"_r": [number, generation]}.

pdfboss q form.pdf '.trailer.value.Root'              # {"_r": [131, 0]}
pdfboss q form.pdf '.objects["131"].value | keys'     # ["AcroForm", "Names", "Pages", ...]
pdfboss q form.pdf '.objects["131"].value.AcroForm'   # {"_r": [132, 0]}

See Exploring PDF internals for the tree and the query language.

Creating PDFs

The write side of pdfboss is the pdfboss-write Rust crate, the pdfboss.write Python module and the pdfboss create CLI. This chapter covers two altitudes: the canvas level, where you place every shape, glyph run and image yourself, and the element level one step above it, where Text, Paragraph, Image and Link values compose onto pages and document slots carry outlines, attachments, page labels and viewer preferences. Python reaches both: pdfboss.write composes elements and slots with |, and its draw protocol paints on the canvas directly. To compose a document from CommonMark+GFM source instead, from the CLI, Rust or Python (pdfboss.md.to_pdf), see Markdown to PDF. Everything the writer emits uses the same content-stream IR the reader parses, so a created file round-trips through the rest of the toolkit.

The document model

A document is plain data: Pdf { metadata, pages, outline, attachments, page_labels, viewer, options }. The fields are the composition: pages appear in the output in the order of the Vec, singleton slots are Options, sequences may stay empty, and Default fills everything optional. Each Page { size, rotation, canvas, content, links } carries operators painted directly on its canvas, composed elements in content (lowered onto the canvas at serialization time, after anything painted directly), and its clickable areas: a LinkAnnotation { rect, target } marks a rectangle in page user space, emitted as a /Link annotation under /Annots, whose LinkTarget is either Uri(String) (a /URI action) or Page(usize) (a /GoTo action with an explicit /XYZ null null null destination that keeps the viewer's current position and zoom).

use pdfboss_write::{Page, PageSize, Pdf, Standard14};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut page = Page::new(PageSize::A4);
    page.canvas
        .text("Hello from pdfboss", 72.0, 770.0, Standard14::Helvetica, 24.0)?;
    let pdf = Pdf {
        pages: vec![page],
        ..Pdf::default()
    };
    pdf.save("hello.pdf")?;
    Ok(())
}

Coordinates are PDF user space: the origin is the bottom-left corner of the page, y grows upward, and one unit is 1/72 inch (a point). PageSize offers A3 (841.89 × 1190.55), A4 (595.28 × 841.89, the default), A5 (419.53 × 595.28), Letter (612 × 792), Legal (612 × 1008) and Custom { width, height }; dimensions() returns the pair, and landscape() swaps it into a Custom. rotation is a clockwise view rotation in degrees.

Serialization validates rather than guesses. A document with zero pages is an error, and so are a rotation that is not a multiple of 90, a link, bookmark or open_to target page out of range, a duplicate attachment name, a page-label set without a range at page 0 or with a duplicate first_page or a start_at of 0 (numbering starts at 1), and a paragraph whose wrapped lines overflow its rect.

Canvas

Canvas is an imperative painter. Path construction (move_to, line_to, curve_to, close) is separate from painting (fill, fill_even_odd, stroke, close_stroke, fill_stroke, end_path), exactly as in PDF content streams. Convenience shapes append complete subpaths: rect, circle and ellipse (four Bézier arcs), and polygon over a slice of pdfboss_core::Point (fewer than three points appends nothing).

Graphics state follows the same operators: save/restore push and pop, transform concatenates a pdfboss_core::Matrix onto the CTM, and set_line_width, set_line_cap, set_line_join, set_miter_limit and set_dash control stroking. clip and clip_even_odd intersect the clip region with the current path and consume it. Colors are device colors (Color::Gray(g), Color::Rgb(r, g, b), Color::Cmyk(c, m, y, k), components in 0.0..=1.0, with Color::BLACK and Color::WHITE constants), set independently for fill (set_fill) and stroke (set_stroke). For anything the methods do not cover, op pushes a raw pdfboss_core::content::Op.

Canvases nest and carry transparency state. group(canvas, bbox) registers a finished sub-canvas as a Form XObject and returns a GroupHandle; draw_group(handle, matrix) paints it under a matrix, and two calls with the same handle reference one form resource. set_fill_alpha, set_stroke_alpha and set_blend_mode each emit a gs operator over a deduplicated single-key /ExtGState entry (/ca, /CA and /BM respectively); BlendMode covers the twelve separable modes. The resource naming contract, which op callers must keep consistent, is fixed: fonts are F1, F2, …, images Im1, …, groups Gp1, …, graphics states Gs1, …. Fonts are deduplicated document-wide, nested groups included, but a canvas registered as a group on two pages produces two Form XObjects; cross-page group sharing is deferred.

Text

canvas.text(text, x, y, font, size) shows one line with its baseline origin at (x, y). The faces are the fourteen standard fonts every conforming reader provides, as Standard14 variants: Helvetica, HelveticaBold, HelveticaOblique, HelveticaBoldOblique, TimesRoman, TimesBold, TimesItalic, TimesBoldItalic, Courier, CourierBold, CourierOblique, CourierBoldOblique, Symbol, ZapfDingbats. No font program is embedded: readers carry these faces.

The twelve text faces encode as WinAnsi. A character outside the encoding is an error, never silently dropped or replaced, and the error is raised before any operator is pushed, leaving the canvas untouched. Symbol and ZapfDingbats encode through their built-in encodings (ISO 32000-1 Annex D.5 and D.6): Greek letters and mathematical signs for Symbol, the dingbats for ZapfDingbats; a character outside those tables is an encoding error, and no metrics are bundled for the two faces, so text_width has nothing to say about them. The library does not wrap or lay out text: one call is one line; Standard14::text_width(text, size) returns a string's width from the AFM metrics (bare advance widths, no kerning) for callers doing their own layout.

Fonts are deduplicated document-wide: each distinct face gets one font object, in first-use order, no matter how many pages use it.

Images

ImageData imports or wraps pixels; add_image registers it on a canvas and draw_image(handle, x, y, width, height) paints it into an axis-aligned box:

• ImageData::png(&bytes): decodes a PNG; truecolor and grayscale (16-bit reduced to 8), palette expanded, alpha split into a soft mask.
• ImageData::jpeg(&bytes): baseline or progressive JPEG by passthrough. The original bytes are embedded as /DCTDecode, dimensions sniffed from the SOF marker. Grayscale and three-component images only.
• ImageData::rgb8(w, h, data), gray8(w, h, data): 8-bit rasters, data length checked against the dimensions.
• ImageData::mono(w, h, data): 1-bit rasters, rows packed MSB-first and byte-padded; a set bit is black.
• ImageData::decode(&bytes): dispatches on content rather than file extension. A PNG signature goes to png, a JPEG SOI marker to jpeg, anything else is an error.

Images are embedded per page with no cross-page deduplication: the same raster drawn on two pages is stored twice.

A complete page

One page with shapes, text in two faces, and a generated raster:

use pdfboss_core::Point;
use pdfboss_write::{Color, Date, ImageData, Metadata, Page, PageSize, Pdf, Standard14};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut page = Page::new(PageSize::A4);
    let canvas = &mut page.canvas;

    // A stroked frame with a dash pattern.
    canvas.set_stroke(Color::Gray(0.3));
    canvas.set_line_width(1.5);
    canvas.set_dash(&[6.0, 3.0], 0.0);
    canvas.rect(36.0, 36.0, 523.28, 769.89);
    canvas.stroke();
    canvas.set_dash(&[], 0.0);

    // Filled shapes: a rectangle, a circle, a triangle.
    canvas.set_fill(Color::Rgb(0.85, 0.2, 0.2));
    canvas.rect(72.0, 600.0, 120.0, 80.0);
    canvas.fill();
    canvas.set_fill(Color::Rgb(0.2, 0.5, 0.85));
    canvas.circle(280.0, 640.0, 45.0);
    canvas.fill();
    canvas.set_fill(Color::Cmyk(0.6, 0.0, 0.9, 0.1));
    canvas.polygon(&[
        Point::new(380.0, 600.0),
        Point::new(500.0, 600.0),
        Point::new(440.0, 690.0),
    ]);
    canvas.fill();

    // Text in two of the fourteen standard faces.
    canvas.set_fill(Color::BLACK);
    canvas.text("Quarterly report", 72.0, 540.0, Standard14::HelveticaBold, 28.0)?;
    canvas.text(
        "Generated with pdfboss-write.",
        72.0,
        510.0,
        Standard14::TimesRoman,
        12.0,
    )?;

    // A generated raster, embedded and drawn at 200 x 100 pt.
    let mut pixels = Vec::with_capacity(64 * 32 * 3);
    for y in 0..32u32 {
        for x in 0..64u32 {
            pixels.extend([(x * 4) as u8, (y * 8) as u8, 128]);
        }
    }
    let gradient = ImageData::rgb8(64, 32, pixels)?;
    let handle = canvas.add_image(gradient);
    canvas.draw_image(handle, 72.0, 380.0, 200.0, 100.0);

    let pdf = Pdf {
        metadata: Some(Metadata {
            title: Some("Quarterly report".into()),
            author: Some("pdfboss".into()),
            creation_date: Some(Date {
                year: 2026,
                month: 8,
                day: 27,
                hour: 12,
                minute: 0,
                second: 0,
                utc_offset_minutes: 0,
            }),
            ..Metadata::default()
        }),
        pages: vec![page],
        ..Pdf::default()
    };
    pdf.save("report.pdf")?;
    Ok(())
}

To embed an existing file instead of a generated raster: ImageData::png(&std::fs::read("photo.png")?)?.

Composing pages

Page::content holds Content values, an element vocabulary one step above raw canvas operators: Text, Image, Link and Paragraph, each convertible with Content::from, plus Content::Custom(Box<dyn Draw>) via Content::custom for anything implementing Draw (fn draw(&self, canvas: &mut Canvas) -> Result<()>, plus Send). Elements lower onto the page's canvas at serialization time, in order, after any operators already painted there directly, so elements paint over manual canvas work, never under it. A Link element is the exception: it lowers into the page's links vector instead of painting.

Paragraph { text, rect, font, size, leading, align } wraps text into its rect. \n forces a line break, other whitespace runs between words collapse to one space, and a blank source line keeps its vertical advance. leading defaults to 1.2 * size; align is ParagraphAlign::Left, Center, Right or Justify, and justification stretches word spacing on every line except the last visible one. A paragraph that does not fit is an error naming how many lines fit and how many were needed, and an unencodable character errors exactly as in canvas.text.

Image { data, at, width, height } sizes itself from what is given: with both dimensions None it paints at the natural pixel size at 72 dpi, one given dimension scales the other by aspect, and both given paint the exact box.

use pdfboss_core::Point;
use pdfboss_write::{Content, Link, LinkTarget, Page, PageSize, Paragraph, Pdf, Standard14, Text};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut page = Page::new(PageSize::A4);
    page.content.push(Content::from(Text {
        value: "Q3 Report".into(),
        at: Point::new(72.0, 770.0),
        font: Standard14::HelveticaBold,
        size: 28.0,
        ..Text::default()
    }));
    page.content.push(Content::from(Paragraph {
        text: "Prepared for the board. Revenue, costs and outlook for the \
               quarter, wrapped and aligned without manual line breaks."
            .into(),
        rect: [72.0, 600.0, 523.0, 740.0],
        ..Paragraph::default()
    }));
    page.content.push(Content::from(Link {
        rect: [72.0, 60.0, 200.0, 80.0],
        target: LinkTarget::Uri("https://example.com/q3".into()),
    }));
    let pdf = Pdf {
        pages: vec![page],
        ..Pdf::default()
    };
    pdf.save("q3.pdf")?;
    Ok(())
}

Document slots

Beside pages, four Pdf fields carry document-level structure, each plain data and each optional.

Outline { bookmarks } is the viewer's bookmark panel: an ordered forest of Bookmark { title, page, children } nodes, Bookmark::new(title, page) building a leaf. Each bookmark targets a 0-based page index with an explicit /XYZ null null null destination, keeping the viewer's current position and zoom.

Attachment { name, data, mime, modified, description } embeds a file via the catalog's /Names /EmbeddedFiles name tree. name becomes the filespec's /F and /UF and the name-tree key; data is stored as the embedded-file stream, compressed per WriteOptions::compress; mime is the stream's /Subtype, defaulting to application/octet-stream; modified and description write /Params /ModDate and /Desc only when given. Attachments are reordered bytewise by name at emission, since the name tree's keys must be sorted, so the order given is not preserved; a duplicate name is an error.

page_labels holds PageLabel { first_page, style, prefix, start_at } ranges controlling how viewers display page numbers. A range takes effect from first_page (0-based) until the next range or the document's end. LabelStyle is Decimal, RomanUpper, RomanLower, LettersUpper or LettersLower, written as /S D, R, r, A or a; prefix prepends text to every number in the range, and /St is written only when start_at is not 1. Ranges are reordered by first_page, and a non-empty set must include a range starting at page 0.

Viewer { layout, mode, open_to } writes the catalog's opening preferences: /PageLayout from PageLayout (SinglePage, OneColumn, TwoColumnLeft, TwoColumnRight, TwoPageLeft, TwoPageRight), /PageMode from PageMode (UseNone, UseOutlines, UseThumbs, FullScreen), and /OpenAction opening the document at a page, keeping position and zoom.

use pdfboss_write::{
    Attachment, Bookmark, LabelStyle, Outline, Page, PageLabel, PageMode, PageSize, Pdf,
    Standard14, Viewer,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut cover = Page::new(PageSize::A4);
    cover
        .canvas
        .text("Cover", 72.0, 770.0, Standard14::HelveticaBold, 24.0)?;
    let mut body = Page::new(PageSize::A4);
    body.canvas
        .text("Body", 72.0, 770.0, Standard14::Helvetica, 12.0)?;
    let pdf = Pdf {
        pages: vec![cover, body],
        outline: Some(Outline {
            bookmarks: vec![Bookmark::new("Cover", 0), Bookmark::new("Body", 1)],
        }),
        attachments: vec![Attachment {
            name: "raw-numbers.csv".into(),
            data: b"a,b,c\n1,2,3\n".to_vec(),
            mime: Some("text/csv".into()),
            modified: None,
            description: Some("Source data".into()),
        }],
        page_labels: vec![PageLabel {
            first_page: 0,
            style: Some(LabelStyle::RomanLower),
            prefix: None,
            start_at: 1,
        }],
        viewer: Some(Viewer {
            mode: Some(PageMode::UseOutlines),
            ..Viewer::default()
        }),
        ..Pdf::default()
    };
    pdf.save("book.pdf")?;
    Ok(())
}

Python: pdfboss.write

pdfboss.write exposes the same vocabulary as frozen values joined with |. A Page(size="a4", landscape=False) composes Text, Image, Link and Paragraph elements — size is a name (a0 to a10, b0 to b10, letter, legal, tabloid), a "<width>x<height>" string in pt, mm, cm or in, or a (width, height) tuple of points; a Pdf() composes pages, Attachment and PageLabel values (each appended, in order) and the singleton Metadata, Outline and Viewer slots, where a second raises TypeError. Every | returns a new value and leaves the receiver unchanged, and copies are cheap handle clones: nothing is built until save(path) or to_bytes(), which lower the composition once and release the GIL to serialize. to_bytes may be called repeatedly.

from pdfboss.write import (
    Bookmark,
    Link,
    Metadata,
    Outline,
    Page,
    Paragraph,
    Pdf,
    Standard14,
    Text,
)

cover = (
    Page(size="a4")
    | Text("Q3 Report", at=(72, 770), font=Standard14.HELVETICA_BOLD, size=28)
    | Paragraph("Prepared for the board.", rect=(72, 700, 500, 740))
    | Link(rect=(72, 60, 200, 80), url="https://example.com/q3")
)
pdf = Pdf() | Metadata(title="Q3 Report") | cover | Outline(Bookmark("Cover", 0))
pdf.save("q3.pdf")

Constructors mirror the Rust fields with Python spellings: Standard14 members are SCREAMING_SNAKE (Standard14.HELVETICA_BOLD), string enums are kebab-case (align="justify", style="roman-lower", layout="single-page", mode="use-outlines"), Text takes an optional (r, g, b) color tuple, Image takes a path string or raw bytes (read and decoded only at save/to_bytes time), Link takes exactly one of url or page, and Bookmark(title, page, children=(...)) nests by construction rather than |. The Python write surface stays clock-free, so Metadata and Attachment carry no date parameters. The full inventory is in the Python API reference.

The draw protocol

Any object with a callable draw attribute composes onto a Page like an element. During save/to_bytes the page's in-progress canvas is handed to draw(canvas) as a Canvas value with twelve methods: text, line, rect, move_to, line_to, curve_to, close, stroke, fill, set_fill, set_stroke and set_line_width. Painting lands in content order, exactly where the object sits in the | chain.

from pdfboss.write import Page, Pdf, Text


class Letterhead:
    def draw(self, canvas):
        canvas.line(72, 806, 523, 806, width=0.5)
        canvas.text("ACME GmbH", at=(72, 812), size=8)


page = Page(size="a4") | Letterhead() | Text("Body copy", at=(72, 700))
data = (Pdf() | page).to_bytes()

The canvas is only usable inside the call: any method raises PdfError once draw has returned. An exception raised inside draw propagates from save/to_bytes exactly as the Python code raised it. The protocol is structural: the stub declares a Draw protocol type for checkers, but there is no runtime class to import or inherit.

Metadata and dates

Metadata fills the document information dictionary: title, author, subject, keywords, creator, producer, creation_date, modification_date. Every field is an Option, and an all-None value writes no /Info dictionary at all. Dates are explicit Date { year, month, day, hour, minute, second, utc_offset_minutes } values; the writer never reads a clock, so dates appear in output only when supplied.

Any Some metadata, all-None included, also writes an XMP metadata stream referenced from the catalog as /Metadata, built from the same value so the two always match: title becomes dc:title, author dc:creator, subject dc:description, keywords pdf:Keywords, producer pdf:Producer, creator xmp:CreatorTool, and the dates xmp:CreateDate/xmp:ModifyDate in ISO-8601. The packet carries no xmpMM:InstanceID, no xmpMM:DocumentID and no generated timestamps. Nothing in the crate reads clocks or randomness, and the file identifier derives from a hash of the emitted body, so the same input produces identical output bytes.

Writing the file

Four paths produce the same bytes:

• pdf.save(path): serialize and write to a file.
• pdf.to_bytes(): the whole file as one Vec<u8>.
• pdf.write_into(impl std::io::Write): the same bytes streamed in bounded chunks. An error can leave a prefix of the file already written, and no flush is performed. Flush a buffered writer yourself.
• pdf.write_into_with(sink).await: the asynchronous twin over any AsyncByteSink; it hands the sink back unflushed. Vec<u8> is a sink, Immediate presents any std::io::Write as one, and pdfboss_aio::TokioSink (behind that crate's write feature) presents any tokio::io::AsyncWrite.

use pdfboss_write::{Page, PageSize, Pdf, Standard14};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut page = Page::new(PageSize::A4);
    page.canvas
        .text("Asynchronous emission", 72.0, 770.0, Standard14::Helvetica, 14.0)?;
    let pdf = Pdf {
        pages: vec![page],
        ..Pdf::default()
    };
    let bytes = pdf.write_into_with(Vec::new()).await?;
    tokio::fs::write("async.pdf", &bytes).await?;
    Ok(())
}

To stream into a tokio writer directly, wrap it in pdfboss_aio::TokioSink (the write feature of pdfboss-aio). The one line is pdf.write_into_with(TokioSink(writer)).await?; the writer comes back out of the returned sink's .0 field, unflushed, so flush it yourself:

use pdfboss_aio::TokioSink;
use pdfboss_write::{Page, PageSize, Pdf, Standard14};
use tokio::io::AsyncWriteExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut page = Page::new(PageSize::A4);
    page.canvas
        .text("Streamed through tokio", 72.0, 770.0, Standard14::Helvetica, 14.0)?;
    let pdf = Pdf {
        pages: vec![page],
        ..Pdf::default()
    };
    let file = tokio::fs::File::create("streamed.pdf").await?;
    let mut sink = pdf.write_into_with(TokioSink(file)).await?;
    sink.0.flush().await?;
    Ok(())
}

Pdf::options is a WriteOptions controlling file emission. xref picks the cross-reference flavor: XrefStyle::Stream (the default) emits a compact PDF 1.5+ cross-reference stream, XrefStyle::Table a classic xref table with a trailer dictionary readable by PDF 1.0-era consumers. compress Flate-compresses stream data that carries no filter of its own (JPEG passthrough keeps its /DCTDecode and is never recompressed). object_streams packs non-stream objects into object streams, effective only with XrefStyle::Stream. version is the header version. The defaults are Stream, compressed, object streams on, version 1.7. For maximum compatibility:

use std::fs::File;
use std::io::{BufWriter, Write};

use pdfboss_write::{Page, PageSize, Pdf, Standard14, WriteOptions, XrefStyle};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut page = Page::new(PageSize::Letter);
    page.canvas
        .text("Classic xref table", 72.0, 700.0, Standard14::Courier, 12.0)?;
    let pdf = Pdf {
        pages: vec![page],
        options: WriteOptions {
            xref: XrefStyle::Table,
            compress: false,
            object_streams: false,
            version: (1, 4),
        },
        ..Pdf::default()
    };
    let mut out = BufWriter::new(File::create("classic.pdf")?);
    pdf.write_into(&mut out)?;
    out.flush()?;
    Ok(())
}

CLI

pdfboss create covers the common cases without writing Rust, plus create md, which composes a Markdown file with a CSS theme and has its own chapter. Blank pages, with --pages, --size (a name from a0 to a10, b0 to b10, letter, legal, tabloid, or <width>x<height> in pt, mm, cm or in, e.g. 210mmx297mm) and --landscape:

pdfboss create blank --out blank.pdf --pages 3 --size a5 --landscape

A UTF-8 text file, word-wrapped into pages. --font takes any of the fourteen standard faces, plus --font-size and --margin in points:

pdfboss create text notes.txt --out notes.pdf --font times-roman --font-size 12

One page per input image (PNG or JPEG, detected by content); without --size, each page matches its image at 72 dpi:

pdfboss create images photo.png --out photos.pdf

A TOML manifest describes metadata and whole pages declaratively, mapping [meta], [[page]], [[page.text]], [[page.paragraph]], [[page.image]] and [[page.link]] tables onto the element vocabulary above; the schema is in the CLI reference:

pdfboss create manifest q3.toml -o q3.pdf

Each result can be checked immediately with pdfboss info, which reports the version, page count and page sizes. The full flag reference is in the CLI reference.

Round trip

The writer and the reader are two halves of the same engine: generated content streams parse with pdfboss_core::content like any other PDF, so a created document reads back without leaving the process.

use pdfboss_output::ReadingOrder;
use pdfboss_write::{Page, PageSize, Pdf, Standard14};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut page = Page::new(PageSize::A4);
    page.canvas
        .text("Round trip", 72.0, 770.0, Standard14::Helvetica, 18.0)?;
    let pdf = Pdf {
        pages: vec![page],
        ..Pdf::default()
    };
    let bytes = pdf.to_bytes()?;

    let doc = pdfboss_core::Document::load(bytes)?;
    let first = doc.page(0)?;
    let text = pdfboss_output::extract_text(&doc, &first, ReadingOrder::Content)?;
    println!("{text}");
    Ok(())
}

This prints Round trip. The same holds across tools: pdfboss info reads back the metadata, pdfboss text extracts the drawn strings, and pdfboss render rasterizes the page. One render detail: the standard fourteen faces carry no embedded font program, and rendering paints embedded programs by default. Pass --fonts full to substitute bundled faces and see the text in the raster.

Watermarking an existing file

watermark draws the first page of one document over every page of another. It does not rewrite the base file: the result is the base's bytes followed by an incremental update (ISO 32000-1 §7.5.6) holding the overlay page as a form XObject, its resources copied into the base's object space, and one replacement dictionary per page whose content is wrapped in q … Q before the form is drawn. The output therefore grows by the overlay page's size, keeps the base's cross-reference style, and takes no longer than parsing the two files. An encrypted base is refused.

use pdfboss_core::Document;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let base = Document::open("report.pdf")?;
    let overlay = Document::open("draft.pdf")?;
    let bytes = pdfboss_write::watermark(&base, &overlay)?;
    std::fs::write("report-watermarked.pdf", bytes)?;
    Ok(())
}

watermark_with(base, overlay, WriteOptions::default()) is the other shape of the same operation: a fresh file written through the Writer, every object the catalog reaches copied over, filterless streams compressed and the rest packed into object streams, so unreachable objects and earlier update sections are left behind and the result is usually smaller than the base.

From Python, pdfboss.write.watermark(data, overlay) takes and returns bytes; rewrite=True selects the fresh-file shape:

import pdfboss

marked = pdfboss.write.watermark(open("report.pdf", "rb").read(), open("draft.pdf", "rb").read())
open("report-watermarked.pdf", "wb").write(marked)

watermark_under(&base, &overlay) in Rust and pdfboss.write.watermark(data, overlay, under=True) in Python draw the overlay beneath the page's own content instead of on top of it, so the page's own content paints over it.

Editing PDFs

pdfboss_write::Update edits an existing document without rewriting it. It appends an incremental update (ISO 32000-1 §7.5.6): a cross-reference section holding only the changed and new objects, chained to the base document's own newest section by /Prev. The base's bytes never move; a conforming reader parses the newest cross-reference section first and falls back to /Prev only for object numbers that section does not cover, so an edit takes effect over the whole file without touching a byte of what came before it.

An encrypted base is refused outright. Update::new checks the trailer for an /Encrypt entry before reading or writing anything and returns Error::EncryptedBase (cannot update an encrypted document, or copy from an encrypted document not opened with its password) if one is there, whether or not the document was opened with the correct password: the check is for the entry, not for whether decryption succeeded, because the new strings and streams an update writes would need encrypting too.

This chapter covers meta and overlay. merge, split, rotate and the whole-document rewrite are in Assembling documents; encrypt and decrypt are in Encrypted PDFs. No command can append an incremental update onto an encrypted base; overlay is built on the same incremental-append machinery as meta, through the watermark family of functions described below; see also Watermarking an existing file for the same family from the composition side.

When the catalog already names an XMP packet, set_metadata rebuilds it from the eight modeled Metadata fields alone: any other XMP property the original packet carried (a PDF/A identifier, a rights statement, edit history, a custom schema) is not carried into the new packet, though the original packet's bytes stay physically present in the base, superseded only by the appended section's newer entry for that object number.

CLI

pdfboss meta sets one or more /Info fields and writes the result as an appended update:

pdfboss meta report.pdf -o report-titled.pdf --set title="Q3 Report" --set author="Finance"

--set KEY=VALUE repeats, one per field: title, author, subject, keywords, creator, producer. --password opens an encrypted input for reading; the write step still refuses it, for the reason above. --rewrite writes the whole document fresh instead of appending: the same rewrite operation, with the metadata merged in along the way.

Python

import pdfboss
from pdfboss.write import Update

update = Update(pdfboss.Document("report.pdf"))
update.set_metadata(title="Q3 Report", author="Finance")
update.save("report-titled.pdf")

set_metadata may be called more than once before saving: a field passed as None keeps whatever an earlier call staged, so calls compose. to_bytes() returns the same bytes without writing a file, and may be called more than once.

Rust

use pdfboss_core::Document;
use pdfboss_write::{Metadata, Update};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    let mut update = Update::new(&doc)?;
    update.set_metadata(Metadata {
        title: Some("Q3 Report".to_string()),
        author: Some("Finance".to_string()),
        ..Metadata::default()
    })?;
    update.save("report-titled.pdf")?;
    Ok(())
}

Calling set_metadata more than once on the same Update does not compound the way the Python binding's own staging does: each call merges its fields against the base document's own /Info, never against an earlier call's, so the later call wins outright and any field it leaves None falls back to the base's original value rather than what an earlier call set.

append_into writes to any impl Write and bytes() returns the bytes directly; both build the update section before a byte reaches the output, so a refused or failing update leaves nothing behind. set, remove and reserve on Update stage arbitrary objects into the same appended section for edits beyond metadata.

Overlay

pdfboss overlay draws the overlay file's first page onto every page of the base file. On top of the page's own content by default; --under draws it beneath instead. Appends an incremental update by default, the same way meta does; --rewrite writes a fresh file instead. Both inputs are refused when encrypted, each error naming its own file.

pdfboss overlay report.pdf draft.pdf -o out.pdf --under

--password opens both encrypted inputs for reading; the write step still refuses them, for the reason above.

From Python, pdfboss.write.watermark(data, overlay, *, rewrite=False, under=False) takes and returns bytes:

import pdfboss

data = open("report.pdf", "rb").read()
mark = open("draft.pdf", "rb").read()
out = pdfboss.write.watermark(data, mark, under=True)
open("out.pdf", "wb").write(out)

pdfboss_write exposes the same choice as four functions: watermark (over, appended), watermark_under (under, appended), watermark_with (over, a fresh file through Writer) and watermark_under_with (under, a fresh file). Drawing under paints the overlay form first and the page's own content after, so opaque content covers it; drawing over paints the page's own content first and the form last, on top.

use pdfboss_core::Document;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let base = Document::open("report.pdf")?;
    let overlay = Document::open("draft.pdf")?;
    let bytes = pdfboss_write::watermark_under(&base, &overlay)?;
    std::fs::write("out.pdf", bytes)?;
    Ok(())
}

Limitations

Placement is absolute and unscaled: the overlay page draws at its own coordinates on every page of the base file, with no scaling to that page's size, and the overlay page's /Rotate and /CropBox are not applied, so an overlay file should use the same page size as the base.

For the over placement, a page whose own content leaves unbalanced graphics state (an unclosed clip or transform) can clip or restyle the overlay, since the wrapper's one closing Q cannot undo it; --under is unaffected, since the form paints before any of the page's own operators run.

Async

pdfboss-aio's write feature carries the same append over an AsyncDocument, without holding the whole base in memory: overlay_base(&doc) reads its trailer and newest cross-reference section into an OverlayBase, and append_overlay(&doc, &overlay, sink) streams the base's bytes through any AsyncByteSink in 64 KiB chunks, then writes the built section in one call. Update itself stays synchronous; Overlay, OverlayBase and set_metadata_with are the pieces both sides are built from, but not start_offset, since append_overlay reads the base's own last byte to compute its pad instead of calling it.

Assembling documents

pdfboss_write::assemble builds new documents out of existing ones: merge_documents gathers selected pages from several sources under a fresh page tree (ISO 32000-1 §7.7.3), split_document cuts one document into consecutive-page parts, rotate_rewrite turns selected pages by a quarter-turn multiple in a whole fresh copy, and rewrite_document/rewrite_with_metadata write a document fresh with no page change. merge_documents, split_document, rewrite_document/rewrite_with_metadata, and rotate_rewrite all route through Importer, which renumbers every object reference it meets once and copies it into the output; rotate's default append mode instead stages its change through Update, the same way meta does.

At the CLI, merge, split, rotate, rewrite and overlay all refuse every encrypted input outright, whether or not the password opened it, the same way Update does. The pdfboss_write functions underneath are narrower: Importer::new refuses only a locked source, one that is encrypted with no working decryptor; a source already opened under its password copies its content across as plaintext, the same content encrypt_document relies on to re-encrypt a document under new passwords.

Merging

merge combines selected pages from one or more inputs into a single fresh document, keeping the pages in argument order. A source contributes either every page or a specific, reorderable selection.

pdfboss merge report.pdf:2-9 appendix.pdf -o combined.pdf

report.pdf:2-9 is a 1-based CLI range; appendix.pdf alone takes every page. From Python, the same selection is 0-based and expressed as a list:

from pdfboss.write import merge

combined = merge([(report_bytes, [1, 2, 3, 4, 5, 6, 7, 8]), appendix_bytes])

Only the pages themselves are imported: document-level trees carried by the inputs, such as outlines, name trees and optional content, are not part of the merged output.

Link annotations are not yet rewritten for the new page tree. When a merged or split page carries a link annotation pointing at another page of its source, that referenced page's objects ride along in the output outside the new page tree, unreferenced by any /Kids array (a larger file than the selection alone would need), and the link still resolves to those carried objects rather than to whichever imported page they came from.

Splitting

split cuts a document into consecutive chunks of every pages, the last chunk carrying whatever remains.

pdfboss split report.pdf -o 'part-%d.pdf' --every 10

-o names an output pattern containing %d, substituted with each part's 1-based number. Python's split(data, every) returns the parts as a list of bytes instead of writing files:

from pdfboss.write import split

parts = split(report_bytes, every=10)

One part at a time

split holds every part in memory at once. split_parts(data, every, *, password="") builds the same parts one at a time as you iterate, so only one part is held besides the input; each part reads the input afresh, so nothing cached for one part stays alive for the next. It works with both for and async for; under async for each part is built on a worker thread, so the event loop keeps running. A step that is cancelled or times out leaves its part for the next step, and awaiting a second step while one is pending raises RuntimeError, so parts always arrive complete and in order. The input is parsed when the first part is requested, so an unreadable file, or a wrong or missing password, raises PdfError there rather than at the call; every below 1 raises ValueError at the call. A protected input opened with password yields plain, unencrypted parts.

split_stream(stream, every, *, password="") takes the PDF as an async iterable of bytes chunks, such as an upload body or an S3 object body, and yields the parts as they are built. every and password are checked before the first chunk is read. A PDF's cross-reference table sits at the end of the file, so no page can be located before the last chunk arrives: split_stream copies each chunk into the input as it arrives and parses once the stream ends. Memory holds the file plus one part.

from pdfboss.write import split_stream

async def split_upload(request, s3, bucket):
    index = 0
    async for part in split_stream(request.stream(), every=10):
        index += 1
        await s3.put_object(Bucket=bucket, Key=f"part-{index}.pdf", Body=part)

In Rust, split_runs(doc, every) gives the runs of page indices split_document cuts doc into, counting the pages the page tree actually holds rather than its declared /Count, and split_part(doc, run, options) builds one of them into a Vec<u8>; split_document is those two in a loop. copy_pages_with(src, pages, options, sink) is the asynchronous form: it builds one fresh document from pages of src and writes it into sink, handing the sink back so the caller can finish it (close a file, complete an upload) before building the next part. src is any AsyncObjectSource: a Document through pdfboss_core::Immediate(&doc) (not pdfboss_write::Immediate, which wraps a byte sink), or an AsyncDocument reading a file or a URL by range. Every page must come from src; a page whose object in src is missing or different is refused. Fetch each run's pages just before building its part, so only one run's pages are held at a time:

use pdfboss_aio::{AsyncDocument, TokioSink};
use pdfboss_core::Page;
use pdfboss_write::{copy_pages_with, WriteOptions};
use tokio::io::AsyncWriteExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = AsyncDocument::open("report.pdf").await?;
    let total = doc.page_count();
    for (index, start) in (0..total).step_by(10).enumerate() {
        let pages = (start..(start + 10).min(total))
            .map(|page| doc.page(page))
            .collect::<Result<Vec<Page>, _>>()?;
        let file = tokio::fs::File::create(format!("part-{}.pdf", index + 1)).await?;
        let TokioSink(mut file) =
            copy_pages_with(doc.clone(), pages, WriteOptions::default(), TokioSink(file)).await?;
        file.flush().await?;
    }
    Ok(())
}

TokioSink needs pdfboss-aio's write feature. An AsyncDocument keeps every object it has read cached for as long as it lives, so over a long split its memory grows by the objects each part copies; open the document again for each part where that matters.

Rotating

rotate turns selected pages by 90, 180 or 270 degrees clockwise. By default it appends an incremental update, the same way meta does; --rewrite (rewrite=True in Python) writes the whole document fresh instead.

pdfboss rotate report.pdf -o rotated.pdf --pages 2,4-9 --by 90

from pdfboss.write import rotate

rotated = rotate(report_bytes, 90, pages=[1, 3, 4, 5, 6, 7, 8])

Either mode refuses a page inlined directly into /Kids with no object of its own: pdfboss does not yet restructure such a page to rotate it.

Rewriting

rewrite writes a document fresh through the Writer with no page change: streams recompressed, unreachable objects and earlier update sections left behind. meta --rewrite (see Editing PDFs) is the same operation with metadata merged in along the way.

pdfboss rewrite report.pdf -o report-clean.pdf

from pdfboss.write import rewrite

clean = rewrite(report_bytes)

Append or rewrite

The Importer

Importer::new(writer, source) opens one source document for copying into a Writer, refusing a locked source: one that is encrypted with no working decryptor. A source already opened under its password copies across as plaintext instead, the same way encrypt_document relies on it to re-encrypt a document under new passwords. page(index, parent) imports one page as a self-contained object under parent, translating its effective resources, media box and rotation and returning the page's new reference; it is what merge_documents calls once per selected page. document() instead walks the whole reachable graph from the source catalog and returns the new root reference; rewrite_document and rotate_rewrite build on it.

Importer::with_source(writer, source) opens any AsyncObjectSource instead, such as an AsyncDocument, for the asynchronous twins: page_with(&page, parent) imports a Page the caller already holds, which must come from source, and finish_with() drains the queue, awaiting each fetch. The synchronous methods are these twins run over pdfboss_core::Immediate(&doc), the source type Importer defaults to, so Importer<'_, '_> still names the importer over a borrowed Document. A source cannot report whether it is locked, so with_source trusts the caller to hand over one that already decrypts, as an opened AsyncDocument does.

use pdfboss_core::{Dict, Document, Name, Object};
use pdfboss_write::{Importer, WriteOptions, Writer};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    let mut writer = Writer::new(WriteOptions::default());
    let pages_ref = writer.reserve();

    let mut importer = Importer::new(&mut writer, &doc)?;
    let kids = vec![importer.page(2, pages_ref)?, importer.page(0, pages_ref)?];

    let mut tree = Dict::new();
    tree.insert(Name("Type".to_string()), Object::Name(Name("Pages".to_string())));
    tree.insert(
        Name("Kids".to_string()),
        Object::Array(kids.into_iter().map(Object::Ref).collect()),
    );
    tree.insert(Name("Count".to_string()), Object::Int(2));
    writer.fill(pages_ref, Object::Dict(tree))?;

    let mut catalog = Dict::new();
    catalog.insert(Name("Type".to_string()), Object::Name(Name("Catalog".to_string())));
    catalog.insert(Name("Pages".to_string()), Object::Ref(pages_ref));
    let root = writer.put(Object::Dict(catalog));

    std::fs::write("reordered.pdf", writer.finish(root)?)?;
    Ok(())
}

substitute(r, body) replaces the body a queued reference r will get once the drain reaches it, with body already in target space; copy(obj) translates a source-space object's own references into the target, the piece substitute callers use to build that body. rotate_rewrite is exactly this pattern: it calls document() to queue the whole graph, but first calls copy on each selected page's dictionary (with /Rotate set to its new value) and substitutes the result for that page's own reference, so the drain fills it with the rotated body instead of the source's original one. A substitution must be staged before the drain reaches that reference; page itself never risks the ordering, since it only substitutes a reference it has just queued for the first time.

Markdown to PDF

pdfboss composes CommonMark+GFM source into a themed, paginated PDF: the pdfboss create md CLI subcommand, pdfboss.md.to_pdf in Python, and pdfboss_markdown::to_pdf in Rust. This is the reverse of Markdown output, which extracts Markdown from a PDF; the composed document reads back through the whole toolkit like any other file.

What the composition covers: headings, paragraphs, bulleted and numbered lists (nested included), GFM tables with per-column alignment, fenced and indented code blocks, block quotes, thematic breaks, emphasis, strong, strikethrough and inline code runs, hyperlinks (emitted as real clickable /Link annotations), and images (PNG or JPEG, detected by content, with relative paths resolved against a base directory). Raw HTML fragments are skipped and reported rather than half-rendered.

Two properties worth designing around:

• Deterministic. The same markdown, theme and options always produce byte-identical output: nothing reads a clock, randomness or the environment.
• Replace-and-report. Text renders in the standard Helvetica, Times and Courier families, which encode as WinAnsi. A character outside that encoding is replaced with ? and tallied in a report naming each replaced character; a clean document reports nothing.

Themes

A theme is a small CSS subset: element-type selectors only, cascading over the built-in default theme, with inheritance from body down. The twenty selectable elements are body, h1–h6, p, code, pre, blockquote, ul, ol, li, table, th, td, a, del and hr. Properties include font-family (helvetica, times, courier, or the sans-serif/ serif/monospace aliases), font-size (pt, px, em, mm, cm, in), font-style, font-weight, color and background-color (named, #hex or rgb()), text-align, text-decoration, line-height, and margin/padding with their per-side forms. Parse errors are strict and located: a typo fails with a line and column rather than being ignored.

body { font-family: times; font-size: 10.5pt; color: #222; }
h1   { font-family: helvetica; font-size: 2.2em; color: #a33; }
code { font-family: courier; background-color: #eee; }
pre  { background-color: #eee; padding: 8pt; }

CLI

pdfboss create md notes.md -o notes.pdf --theme theme.css --size letter

--theme takes a CSS file (omitted, the built-in default theme applies); --size is a page size name (a0 to a10, b0 to b10, letter, legal, tabloid; default a4) or <width>x<height> in pt, mm, cm or in, and --landscape swaps width and height. Relative image paths in the markdown resolve against the input file's directory. The result round-trips immediately:

pdfboss info themed.pdf     # 1 page, 612 x 792 pt
pdfboss text themed.pdf     # the composed text back out

Python

pdfboss.md.to_pdf returns the PDF as bytes. theme is CSS source text, not a path: read the file yourself when the theme lives in one. size names the page size case-insensitively, landscape swaps the dimensions, and base_dir anchors relative image paths (default: the current directory).

from pathlib import Path

import pdfboss

theme = Path("theme.css").read_text()
pdf = pdfboss.md.to_pdf(Path("notes.md").read_text(), theme=theme, size="letter")
Path("notes.pdf").write_bytes(pdf)

Replacements and skipped raw HTML surface as a single UserWarning naming what changed, so a clean run stays silent and a lossy one is visible without being fatal:

import warnings

import pdfboss

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    pdf = pdfboss.md.to_pdf("Snowman ☃ here")
for warning in caught:
    print(warning.message)   # replaced 1 character unavailable in the standard fonts: '☃'×1

An unknown size or an invalid theme raises PdfError.

Rust

pdfboss_markdown::to_pdf(markdown, &options) returns the composed pdfboss_write::Pdf (still a value, not yet bytes) alongside the replace-and-report Report. Options carries the parsed Theme, the PageSize and the image base_dir; Theme::parse reads CSS source, Theme::default_theme() is the built-in look. Serialize the Pdf with any of the write paths:

use pdfboss_markdown::{to_pdf, Options, PageSize, Theme};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let markdown = std::fs::read_to_string("notes.md")?;
    let theme = Theme::parse("h1 { font-family: helvetica; color: #a33; }")?;
    let options = Options {
        theme,
        page_size: PageSize::Letter,
        ..Options::default()
    };
    let (pdf, report) = to_pdf(&markdown, &options)?;
    if !report.is_empty() {
        eprintln!("{}", report.summary());
    }
    pdf.save("notes.pdf")?;
    Ok(())
}

Because the result is a plain Pdf, everything from Creating PDFs applies afterwards: set metadata, attach an outline or embedded files, add page labels or viewer preferences, append pages of your own, or stream the bytes asynchronously.

Round trip

Composition and extraction are the two directions of one engine. A document composed from Markdown reads back with pdfboss text, renders with pdfboss render, and, closing the loop, pdfboss md re-infers headings, lists and tables from the composed layout. The composed text uses only standard-14 faces, so rendering paints it at the full font tier.

Async and remote PDFs over HTTP

AsyncDocument opens a PDF without reading the whole file. The open flow fetches only what it needs (the header, the cross-reference chain and the page tree) and every later operation fetches only the byte ranges it touches. The file backend reads windows of the file on demand; the HTTP backend turns each read into a Range request, so a document on a server can be paged through without downloading it. A server that ignores Range and answers 200 with the full body (python3 -m http.server, for one) still works: the first such answer is kept as the whole resource and every read is served from it, at the cost of one full download held in memory for the life of the document.

Python

Three constructors, all coroutines. Each takes password= for encrypted files (see Encrypted documents):

What is sync and what is a coroutine follows from what the open flow already parsed. page_count, version, len(doc) and page access (doc[i], doc.page(i) and every AsyncPage geometry property) are plain sync attributes: the xref chain and the page tree were parsed at open, so nothing there needs I/O. Everything that must read more of the file is a coroutine: extract_text, extract_markdown, render_pages, metadata, get_object on the document, and extract_text, extract_markdown, render, render_reporting, extract_images and spans on a page.

Coroutines are driven by one shared multi-thread tokio runtime behind the asyncio loop. render_pages fans pages across the machine's cores as tokio tasks, so the loop stays free while pages rasterize.

import asyncio

import pdfboss


async def main() -> None:
    doc = await pdfboss.AsyncDocument.open("report.pdf")
    print(doc.page_count, doc.version)

    text = await doc.extract_text()
    metadata = await doc.metadata()
    png = await doc[0].render(scale=2.0)

    async for span in doc.spans(pages=[0]):
        print(span.text, span.font_name)


asyncio.run(main())

doc.elements() and doc.spans() return async iterators, consumed with async for, with the same ordering and salvage semantics as their sync twins. Each step returns one item. The iterator refills an internal buffer from the document in batches, so most steps return without suspending and a long walk costs about as much as the sync one. A step that is cancelled or times out leaves its item for the next step, so no item is lost or repeated. See Exploring PDF internals and Styled spans.

A remote document differs only in the constructor:

import asyncio

import pdfboss


async def main() -> None:
    doc = await pdfboss.AsyncDocument.open_url("https://example.com/report.pdf")
    print(doc.page_count)
    print(await doc.extract_markdown())


asyncio.run(main())

Rust

pdfboss_aio::AsyncDocument has the same constructors: open/open_with_password, from_bytes/from_bytes_with_password and, behind the crate's http feature, open_url/open_url_with_password/open_url_with_headers (the last takes a reqwest::header::HeaderMap sent on every request). with_backend opens a document over any byte source you build yourself.

use pdfboss_aio::AsyncDocument;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = AsyncDocument::open_url("https://example.com/report.pdf").await?;
    println!("{} pages", doc.page_count());

    let metadata = doc.metadata().await?;
    println!("{:?}", metadata.title);
    Ok(())
}

Backends

A document reads through the Backend trait: len() and read_at(offset, buf), both returning boxed futures so the trait is object-safe and a document can hold Arc<dyn Backend>. Four implementations ship with the crate:

• MemBackend: bytes fully resident in memory; from_bytes uses it directly, with no cache.
• FileBackend: positioned reads (pread-style, no shared cursor) run on tokio's blocking thread pool, so disk I/O never stalls the async runtime. The length is captured once at open; the file is treated as immutable while the backend lives.
• HttpBackend (feature http): the length comes from a HEAD request's Content-Length; each read is a GET with a Range: bytes= header. A 200 answer where 206 was asked for means the server ignores Range; its body is the whole resource, so it is collected once (capped at the declared length, so a buggy or hostile server cannot balloon memory) and all reads are served from it. on_fallback_progress registers an observer for that one-time download (the CLI draws its stderr progress bar through it). A 206 body is likewise collected only up to the requested size.
• CachedBackend: a chunked LRU read cache over any backend: many small reads become few chunk-sized fetches, and hot chunks stay resident up to a byte budget. Defaults: 64 KiB chunks, 32 MiB total. Misses batch adaptively: a miss landing near the previous one doubles the batch, up to 8 MiB (and a quarter of the budget), a far jump halves it, and each miss fetches its uncached neighborhood, growing around the missed chunk until it hits resident chunks or the batch budget. Dense access over a high-latency server collapses into few large requests, whichever direction the reader walks the file, while scattered access never over-fetches. on_fetch registers an observer called with the offset and length of every inner fetch a miss triggers (the CLI draws its ranged-open coverage minimap through it); cache hits never call it.

open and open_url wrap their backend in a CachedBackend automatically. from_bytes stays uncached, and with_backend adds nothing, so a composition of your own is used exactly as given (with_backend_with_password is the same for encrypted files):

use pdfboss_aio::{AsyncDocument, CachedBackend, FileBackend};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let backend = FileBackend::open("report.pdf").await?;
    let cached = CachedBackend::with_capacity(backend, 128 * 1024, 64 * 1024 * 1024);
    let doc = AsyncDocument::with_backend(cached).await?;
    println!("{} pages", doc.page_count());
    Ok(())
}

The sync crates over an async document

The extraction and rendering crates are written sans-I/O. Each entry point is implemented as a *_with function generic over pdfboss_core::AsyncObjectSource; the sync signature is that same implementation run over an immediate, no-I/O source. AsyncDocument implements AsyncObjectSource, so pdfboss_output::extract_text_with, pdfboss_output::extract_page_markdown_with, pdfboss_render::render_page_reporting_with and pdfboss_render::extract_page_images_with all run over range-fetching reads unchanged. The document is an Arc handle: cloning one to hand to an entry point by value costs two atomic increments.

use pdfboss_aio::AsyncDocument;
use pdfboss_output::{extract_text_with, ReadingOrder};
use pdfboss_render::extract_page_images_with;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = AsyncDocument::open("report.pdf").await?;
    println!("{} pages", doc.page_count());

    let page = doc.page(0)?;
    let oc = doc.oc_state().await;
    let text = extract_text_with(doc.clone(), &page, oc.as_ref(), None, ReadingOrder::Content)
        .await?;
    println!("{text}");

    let images = extract_page_images_with(doc.clone(), &page).await?;
    for (index, image) in images.iter().enumerate() {
        image.save_png(format!("image-{index}.png"))?;
    }
    Ok(())
}

The oc parameter carries the document's optional-content visibility (doc.oc_state().await, the state a viewer shows on screen; doc.oc_state_for(event).await builds the printed or exported state, or the default configuration alone for None); text and markdown extraction use it to exclude layers that state turns off, exactly as the sync entry points do. The structure parameter next to it is the document's structure tree (doc.structure_tree().await), read only under ReadingOrder::StructureTree; pass None for the other orders. See Reading order. Rendering takes the same state through RenderOptions::oc: set opts.oc = doc.oc_state().await.map(Arc::new); before calling render_page_reporting_with. Leaving it None renders every layer; only the sync entry points fill it from the document. What the extracted images contain (drawing order, native size, /SMask alpha) is described in Extracting images; the sync Rust and Python surfaces are in Rust crates and Python API.

Exploring PDF internals

A PDF is two structures at once: a physical file (header, numbered objects, cross-reference sections, trailer) and the logical document those objects encode (pages, fonts, images, annotations). pdfboss exposes both as one lazy stream of elements, reachable from Python and Rust, and from the CLI as a JSON tree, jq queries, hexdumps and an interactive terminal explorer.

The element model

A walk yields the physical elements first, in file order, each with its byte span in the file:

Then the logical elements, in document order:

Parsing is lazy: nothing is located, parsed or decoded before it is yielded. Iteration salvages: an element that cannot be parsed raises for that item alone, and the walk continues past it.

Python

Document.elements() returns a lazy iterator; each step releases the GIL while the next element is parsed. Keyword arguments select the layers: physical= and logical= toggle the two passes, pages= restricts logical elements to the 0-based pages given, and content_ops=True adds the (high-volume) per-page operators.

import pdfboss

doc = pdfboss.Document("report.pdf")

for element in doc.elements(logical=False):
    print(element.kind, element.span, element.ref)

Each Element carries kind, span (byte range, where applicable), ref (the (num, gen) object reference, where applicable) and page (0-based index for logical elements). value() converts the element lazily to plain Python data: dicts, lists, str, bytes, numbers, bool, None; PDF names become str, streams become {"dict": ..., "length": n}, references become {"ref": (num, gen)}. That full conversion applies to object and trailer elements; the other kinds convert to fixed shapes:

import pdfboss

doc = pdfboss.Document("report.pdf")

for element in doc.elements(physical=False, pages=[0]):
    if element.kind != "font":
        continue
    print(element.value())

A for loop stops at the first raising element, so a walk that must survive damage drives the iterator explicitly. A per-item PdfError leaves the iterator usable:

import pdfboss

doc = pdfboss.Document("report.pdf")

elements = doc.elements()
while True:
    try:
        element = next(elements)
    except StopIteration:
        break
    except pdfboss.PdfError as err:
        print("unreadable element:", err)
        continue
    print(element.kind)

AsyncDocument.elements() is the async twin: same arguments, same ordering, same salvage semantics, consumed with async for (Async and remote documents).

Rust

The same walk in Rust is pdfboss_core::Document::elements(ElementOpts), an iterator of Result<Element>. ElementOpts selects the layers with the same four knobs (physical, logical, pages, content_ops); Element is an enum; variants carry their payload fields directly, with byte spans on the physical variants.

use pdfboss_core::{Document, Element, ElementOpts};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    for element in doc.elements(ElementOpts::default()) {
        match element {
            Ok(Element::IndirectObject { r, span, .. }) => {
                println!("{} {} obj at {}..{}", r.num, r.gen, span.start, span.end);
            }
            Ok(_) => {}
            Err(err) => eprintln!("unreadable element: {err}"),
        }
    }
    Ok(())
}

pdfboss_aio::AsyncDocument::elements(ElementOpts) returns an ElementStream, a futures_core::Stream of Result<Element> with the same ordering and salvage semantics. The stream owns an Arc clone of the document, so it is 'static and can be spawned:

use futures_util::StreamExt;
use pdfboss_aio::AsyncDocument;
use pdfboss_core::ElementOpts;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = AsyncDocument::open("report.pdf").await?;
    let mut elements = doc.elements(ElementOpts::default());
    while let Some(element) = elements.next().await {
        match element {
            Ok(element) => println!("{element:?}"),
            Err(err) => eprintln!("unreadable element: {err}"),
        }
    }
    Ok(())
}

CLI

Four subcommands plus the terminal explorer. json, q, hex and tui accept a local path or an http(s) URL (a URL is fetched in ranges when the server honors Range; one that doesn't costs a single full download); obj takes a local path. Full flag listings are in the CLI reference.

json: the document as a JSON value tree

pdfboss json report.pdf > report.json

The tree's top-level keys are header, objects (keyed "N G"), pages, xref, trailer and startxref. Physical entries carry a _span byte range; indirect references appear as {"_r": [num, gen]}. --layout adds a top-level layout array: per page, the inferred blocks (headings, paragraphs, lists, tables). --pages restricts the logical layer, --no-logical skips it, --content-ops adds per-page operators, and --raw/--decode embed stream data as base64 (still encoded, or decoded).

q: jq programs over the same tree

pdfboss q report.pdf '. | keys'
pdfboss q report.pdf '[.pages[].fonts[].base_font] | unique'
pdfboss q report.pdf '.objects["2 0"]'

The second one answers "which fonts does this document use" in one line:

[
  "BAMEDE+StoneSans-Bold",
  "BAMFAO+StoneSerif-Italic",
  ...
  "Helvetica",
  "Helvetica-Bold"
]

-r prints string results raw, and --hex hexdumps any result that carries a _span instead of printing its JSON: a query language for choosing what to dump.

hex: the bytes themselves

pdfboss hex report.pdf obj:2              # one object's bytes
pdfboss hex report.pdf trailer            # or: header, xref:0, range:0x100-0x140
pdfboss hex report.pdf --annotate         # whole file, element boundaries labeled

000000aa  32 20 30 20 6f 62 6a 0d  3c 3c 20 0d 2f 50 72 6f  |2 0 obj.<< ./Pro|
000000ba  63 53 65 74 20 5b 20 2f  50 44 46 20 2f 54 65 78  |cSet [ /PDF /Tex|

Selectors: obj:N[,G], header, xref:N (sections indexed in chain order, newest first), trailer, range:START-END (offsets decimal or 0x-hex); without one, the whole file. --annotate prints a labeled boundary line as the dump crosses each element.

obj: one object, pretty-printed

pdfboss obj report.pdf 2

<<
  /ColorSpace <<
    /Cs5 122 0 R
    ...
  >>
  /ExtGState <<
    /GS1 148 0 R
  >>
  /Font <<
    /F1 132 0 R
    ...
  >>
  /ProcSet [/PDF /Text /ImageB /ImageC]
  ...
>>

tui: the interactive explorer

pdfboss tui report.pdf

The screen splits into a tree pane on the left, an inspector above a hex pane on the right, and a status bar. The tree is the element model as a lazy hierarchy, populated by background tasks as sections expand: Document → Pages (each with its Fonts, Images, Annotations and Contents) → Objects → Xref sections → Trailer. The inspector pretty-prints the selection; d cycles it through raw bytes, decoded bytes and disassembled content operators for streams, and Enter jumps through any N G R reference under the cursor (Backspace goes back). p swaps the inspector for a rasterized page preview and m for the page's Markdown; both follow the selection when it moves to another page. The hex pane tracks the selection's bytes.

Tab cycles focus, arrows or j/k/h/l move, g/G jump to top/bottom, / searches (with n/N for next/previous hit), q quits. Alt+arrows (Option on macOS) resize the panes: left/right move the tree divider, up/down the inspector/hex divider (Ctrl+arrows and Ctrl+Shift+arrows also work where the terminal delivers them, and the ESC b/ESC f word motions stock iTerm2 and Terminal.app send for Option+Left/Right are accepted as horizontal resizes). Long operations (element streaming, hex fetches, search, preview rasterization) run off the event loop, so input never blocks, including over an HTTP-backed document.

y opens a yank menu that copies the selection to the clipboard: q the pdfboss q expression addressing it (.objects["12 0"], .pages[0].fonts, .trailer), c the full shell command, x a hexdump of its bytes, b the raw bytes, e the pretty-printed element, m the page's Markdown, o the object reference (12 0 R), Esc cancels. Copies go to the native clipboard, falling back to the OSC 52 escape sequence (which works over SSH in terminals that support it). A selection past 1 MiB yields the equivalent pdfboss hex command instead of the bytes.

Encrypted PDFs

pdfboss opens files encrypted with the PDF Standard security handler: RC4 (40–128-bit, /V 1–2, and /V 4 with crypt filter V2), AES-128 (/V 4, crypt filter AESV2) and AES-256 (/V 5, crypt filter AESV3). Either the user password or the owner password opens the document, and both unlock the same full content. A file protected only by an owner password has an empty user password and opens transparently, with no password at all.

Non-ASCII passwords are tried UTF-8 encoded and, for the legacy RC4/AES-128 revisions, Latin-1 encoded as well, covering both encodings real files use.

Checking whether a file needs a password

pdfboss info never fails on an encrypted file. Whether the file needs a password is the very question being asked:

pdfboss info locked.pdf

version:   1.7
encrypted: true
pages:     unknown

encrypted: true means the file did not open with the password supplied (by default, none). A file that opens (because it is unencrypted, protected only by an owner password, or because --password carried the right value) reports encrypted: false along with the full page and metadata listing:

pdfboss info --password hunter2 locked.pdf

version:   1.7
encrypted: false
pages:     1
  page 1: 612 x 792 pt

CLI

Every subcommand that reads a PDF (info, text, md, render, images, obj, tui, json, hex, meta and q) takes --password, accepted as either the user or the owner password. For meta it only unlocks the base for reading: every assembly command, meta included, refuses an encrypted input at write time regardless of password; decrypt is the one command that removes encryption instead of refusing it:

pdfboss text --password hunter2 locked.pdf

Apart from info, a command given no password (or a wrong one) for a password-protected file prints an error and exits nonzero.

Python

Document takes a password keyword, and raises PdfError when the file needs a password it was not given (or the given one is wrong):

import pdfboss

try:
    doc = pdfboss.Document("locked.pdf")
except pdfboss.PdfError:
    doc = pdfboss.Document("locked.pdf", password="hunter2")
print(doc.extract_text())

The same keyword exists on the data= form of the constructor and on all three async constructors: AsyncDocument.open, AsyncDocument.open_url and AsyncDocument.from_bytes (see Async and remote documents):

import asyncio

import pdfboss

async def main() -> None:
    doc = await pdfboss.AsyncDocument.open("locked.pdf", password="hunter2")
    print(doc.page_count)

asyncio.run(main())

Rust

Document::open (and Document::load for bytes in memory) handles the empty-user-password case on its own and returns Error::Encrypted when a real password is needed; open_with_password/load_with_password take one:

use pdfboss_core::{Document, Error};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = match Document::open("report.pdf") {
        Err(Error::Encrypted) => Document::open_with_password("report.pdf", "hunter2")?,
        other => other?,
    };
    println!("{} pages", doc.page_count());
    Ok(())
}

A wrong password also comes back as Error::Encrypted. The async document mirrors the sync surface with AsyncDocument::open_with_password, open_url_with_password and from_bytes_with_password:

use pdfboss_aio::AsyncDocument;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = AsyncDocument::open_with_password("report.pdf", "hunter2").await?;
    println!("{} pages", doc.page_count());
    Ok(())
}

Once a document is open, every operation (text, markdown, rendering, images) works exactly as on an unencrypted file; decryption happens transparently underneath. Full option listings live in the CLI reference.

Encrypting a file

encrypt builds a fresh AES-256, revision 6 protected copy of a document (ISO 32000-2 §7.6.4.3). At least one of the user or owner password must be set; an omitted owner password falls back to the user password, and either password opens the file:

pdfboss encrypt report.pdf -o locked.pdf --user-password hunter2

--allow restricts what a reader opening under the user password may do; the owner password always grants everything. Values: print, modify, copy, annotate, fill-forms, accessibility, assemble, print-hires; every permission is granted when --allow is omitted:

pdfboss encrypt report.pdf -o locked.pdf --user-password hunter2 --allow print,copy

--password opens an input that is itself encrypted, so an already-protected file re-encrypts under new passwords:

pdfboss encrypt locked.pdf -o relocked.pdf --password hunter2 --user-password newpass

Rust:

use pdfboss_core::{Document, Permissions};
use pdfboss_write::{encrypt_document, WriteOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open("report.pdf")?;
    let permissions = Permissions { modify: false, ..Permissions::all() };
    let bytes = encrypt_document(&doc, "hunter2", "", permissions, WriteOptions::default())?;
    std::fs::write("locked.pdf", bytes)?;
    Ok(())
}

Python:

from pdfboss.write import encrypt

locked = encrypt(report_bytes, user_password="hunter2", allow=["print", "copy"])

Removing encryption

decrypt opens a file under its user or owner password and writes a fresh, unencrypted copy:

pdfboss decrypt locked.pdf -o plain.pdf --password hunter2

use pdfboss_core::Document;
use pdfboss_write::{decrypt_document, WriteOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::open_with_password("locked.pdf", "hunter2")?;
    let bytes = decrypt_document(&doc, WriteOptions::default())?;
    std::fs::write("plain.pdf", bytes)?;
    Ok(())
}

from pdfboss.write import decrypt

plain = decrypt(locked_bytes, password="hunter2")

Limitations

pdfboss writes AES-256, revision 6 encryption only; RC4 and AES-128 files stay readable but are never produced. Each encrypted output uses a fresh random file key, salts and initialization vectors, so encrypting the same document twice under the same passwords never produces identical bytes. An incremental update appended onto an encrypted base (the default mode of meta, rotate and overlay, and pdfboss_write::Update directly) still refuses the base outright, whether or not it opens under a password. encrypt and decrypt are the only commands that take a password-opened encrypted input directly; merge, split, rewrite, meta --rewrite and the --rewrite forms of rotate/overlay refuse every encrypted input at the CLI regardless of password, even though the pdfboss_write functions behind them would accept an already-opened one and carry its content across as plaintext. A file pdfboss writes always encrypts the /Info dictionary's strings and the XMP metadata stream, like every other string and stream in the file. Reading a third-party file is different when its /Encrypt dictionary carries /EncryptMetadata false: its metadata stream was stored in plaintext, and pdfboss leaves those bytes untouched rather than decrypting them.

pdfboss CLI reference

One binary, pdfboss, with a subcommand per job. This chapter is the flag inventory; worked examples live in the guide chapters linked from each entry.

Shared behavior:

• Every subcommand that reads a PDF takes --password <PASSWORD> for encrypted files: user or owner password; the empty user password opens transparently. See Encrypted documents.
• The explorer subcommands (tui, json, hex, q) accept either a local path or an http(s):// URL as input. URLs are range-fetched, and when stderr is a terminal the open draws a coverage minimap there: a caret marking the byte region being fetched over a map of which stretches of the file have arrived, erased once the document is open. A server that ignores Range costs one full download instead, reported with a progress bar. The other subcommands take a local path.
• Exit codes: 0 on success, 1 for PDF and I/O problems, 2 for an invalid jq program (mirroring clap's own usage-error code). render and images are lenient: content that cannot be read is skipped with a warning on stderr, and the exit code stays 0.

info

Show version, page count, page sizes and metadata.

pdfboss info [OPTIONS] <FILE>

pdfboss info report.pdf

text

Extract text; all pages separated by form feed unless --page (1-based) is given. See Extracting text.

pdfboss text [OPTIONS] <FILE>

pdfboss text report.pdf --page 1

md

Extract markdown, with headings, lists and tables inferred from layout. --page <PAGE> restricts to one 1-based page: heading sizes are then judged per page, not across the document. See Markdown output.

pdfboss md [OPTIONS] <FILE>

pdfboss md report.pdf > report.md

render

Render a page to PNG, PPM, BMP or JPEG. See Rendering pages.

pdfboss render [OPTIONS] --page <PAGE> <FILE>

• --page <PAGE>: 1-based page number (required)
• -o, --out <OUT>: output file; its extension picks the format, .png, .ppm, .bmp or .jpg (default: page-N.png)
• --scale <SCALE>: scale factor (default: 1)
• --fonts <FONTS>: which fonts to paint, one of embedded-only (only embedded TrueType outlines, fastest), all-embedded (every embedded program), full (also substitute bundled faces for non-embedded fonts); the default resolves to full when substitute faces are available (the compiled-in OFL set or --font-dir), otherwise all-embedded
• --font-dir <FONT_DIR>: directory of substitute faces for --fonts full; overrides the compiled-in OFL set
• --png-compression <PNG_COMPRESSION>: none, fast, default or best (encode time against file size, same pixels; PNG only)
• --jpeg-quality <JPEG_QUALITY>: 1 to 100 (default 90; JPEG only)

pdfboss render --page 1 --scale 2 -o page-1.png report.pdf
pdfboss render --page 1 --scale 2 -o page-1.ppm report.pdf
pdfboss render --page 1 --scale 2 -o page-1.jpg --jpeg-quality 80 report.pdf

images

Extract every image a page draws, each as a native-size PNG. See Extracting images.

pdfboss images [OPTIONS] <FILE>

• --page <PAGE>: 1-based page number (default: all pages)
• -o, --out <OUT>: output directory, which must already exist (default: current directory)
• --png-compression <PNG_COMPRESSION>: as in render

pdfboss images report.pdf --page 1 -o out

obj

Pretty-print a single object by number, with an optional generation number (default 0).

pdfboss obj [OPTIONS] <FILE> <NUM> [GEN]

pdfboss obj report.pdf 1

tui

Explore a PDF interactively in the terminal: element tree, object inspector, hex view, page preview and Markdown preview. Takes a path or http(s) URL and requires an interactive terminal. See Exploring PDF internals.

pdfboss tui [OPTIONS] <TARGET>

pdfboss tui report.pdf

json

Dump the document as a JSON value tree, for piping to external tools.

pdfboss json [OPTIONS] <INPUT>

• --raw: embed raw (still encoded) stream data as base64; combining it with --decode is a usage error
• --decode: embed decoded stream data as base64
• --pages <PAGES>: restrict logical elements to these 1-based pages (comma separated)
• --no-logical: skip the logical layer (pages/fonts/images/annotations)
• --content-ops: include per-page content-stream operators (high volume)
• --layout: include per-page layout blocks (headings, paragraphs, lists, tables)

pdfboss json report.pdf --no-logical > tree.json

hex

Hexdump the file or a selected element, hexyl-style.

pdfboss hex [OPTIONS] <INPUT> [SELECTOR]

The selector is one of obj:N[,G], header, xref:N, trailer or range:START-END (offsets decimal or 0x-hex; xref sections indexed in chain order, newest first); without one, the whole file is dumped.

• --annotate: print labeled element boundaries as the dump crosses them
• --width <WIDTH>: bytes per row (default: 16)

The dump is colorized with ANSI escapes when stdout is a tty; setting the NO_COLOR environment variable (any value) disables color.

pdfboss hex report.pdf header

q

Run a jq program over the document's JSON value tree (the same tree json prints).

pdfboss q [OPTIONS] <INPUT> <PROGRAM>

• --raw, --decode, --pages <PAGES>, --no-logical, --content-ops: as in json, including the --raw/--decode usage error when combined
• --hex: hexdump results carrying a _span instead of printing JSON; colorized on a tty like hex, with NO_COLOR honored
• -r: print string results raw, without quotes (like jq -r)

pdfboss q report.pdf -r '.pages[].fonts[].base_font'

create

Create a new PDF: blank pages, word-wrapped text, image pages, a themed Markdown document, or a TOML manifest of composed pages.

pdfboss create <COMMAND>

Five subcommands, each writing to -o, --out <OUT>. The first four share --size <SIZE> — a name (a0 to a10, b0 to b10, letter, legal, tabloid) or <width>x<height> with each length in points or suffixed pt, mm, cm or in (612x792, 210mmx297mm) — and --landscape (swap page width and height); manifest takes neither, since page size and orientation live per page inside the TOML. See Creating PDFs and Markdown to PDF.

create blank

Empty pages. --pages <PAGES> sets the page count (default: 1); --size defaults to a4.

pdfboss create blank [OPTIONS] --out <OUT>

pdfboss create blank -o blank.pdf --pages 3 --size letter

create text

A UTF-8 text file, word-wrapped into pages.

pdfboss create text [OPTIONS] --out <OUT> <INPUT>

• --font <FONT>: one of the fourteen standard fonts, helvetica (default), helvetica-bold, helvetica-oblique, helvetica-bold-oblique, times-roman, times-bold, times-italic, times-bold-italic, courier, courier-bold, courier-oblique, courier-bold-oblique, symbol, zapf-dingbats
• --font-size <FONT_SIZE>: font size in points (default: 11)
• --margin <MARGIN>: page margin in points, all four sides (default: 72)

pdfboss create text notes.txt -o notes.pdf --font times-roman --font-size 12

create images

One page per input image (PNG or JPEG, detected by content). Without --size, each page matches its image at 72 dpi. --landscape requires --size: passing it alone is a usage error, not a no-op.

pdfboss create images [OPTIONS] --out <OUT> <INPUTS>...

pdfboss create images scan-1.png scan-2.png -o scans.pdf

create md

A markdown file composed into a themed document. See Markdown to PDF.

pdfboss create md [OPTIONS] --out <OUT> <INPUT>

• --theme <THEME>: CSS theme file (default: the built-in theme)
• --size <SIZE>: as above; --landscape swaps width and height

Relative image paths in the markdown resolve against the input file's directory.

pdfboss create md notes.md -o notes.pdf --theme theme.css --size letter

create manifest

A TOML manifest describing metadata and pages: text, paragraphs, images and links mapped onto the compose vocabulary of pdfboss-write. See Creating PDFs for that vocabulary.

pdfboss create manifest --out <OUT> <INPUT>

The manifest's tables:

• [meta]: optional document information, mapped onto /Info: title, author, subject, keywords, creator, producer, each a string.
• [[page]]: one table per page, in reading order. size is a page size: a name (a0 to a10, b0 to b10, letter, legal, tabloid, case-insensitively) or <width>x<height> with each length in points or suffixed pt, mm, cm or in; absent defaults to a4 and landscape (boolean) swaps width and height, both per page.
• [[page.text]]: one line of text: value, at = [x, y] (the baseline origin), optional font and size.
• [[page.paragraph]]: wrapped text: value, rect = [x0, y0, x1, y1], optional font, size, leading and align (left, center, right, justify).
• [[page.image]]: a placed raster: path (resolved relative to the manifest's directory, decoded by content as PNG or JPEG), at = [x, y], optional width and height.
• [[page.link]]: a clickable rectangle: rect plus exactly one of url or page (a 0-based page index in the same document).

Font names are PostScript base names (Helvetica, Helvetica-Bold, Times-Roman, Courier-Oblique, …), unlike the kebab-case values of create text --font; an unknown name errors listing the valid set, and an absent one defaults to Helvetica. Unknown TOML keys are rejected, and every error message is prefixed with the manifest's path. Within a page, content lowers in schema order (text, then paragraphs, then images, then links) regardless of how the tables interleave in the file; TOML's separate arrays of tables carry no cross-type order.

[meta]
title  = "Q3 Report"
author = "pdfboss"

[[page]]
size = "a4"

  [[page.text]]
  value = "Q3 Report"
  at    = [72, 770]
  font  = "Helvetica-Bold"
  size  = 28

  [[page.paragraph]]
  value   = "Body copy for the quarter."
  rect    = [72, 380, 523, 720]
  size    = 11
  leading = 15
  align   = "left"

  [[page.image]]
  path  = "chart.png"
  at    = [72, 96]
  width = 200

  [[page.link]]
  rect = [72, 88, 523, 380]
  url  = "https://example.com/q3"

pdfboss create manifest q3.toml -o q3.pdf

meta

Set one or more /Info fields, appending an incremental update by default (the input file's own bytes untouched) or, with --rewrite, writing the whole document fresh. See Editing PDFs.

pdfboss meta [OPTIONS] --out <OUT> --set <SET> <FILE>

• -o, --out <OUT>: output file (required)
• --set <KEY=VALUE>: metadata assignment, repeatable and required at least once; KEY is one of title, author, subject, keywords, creator, producer
• --rewrite: full rewrite instead of an incremental append
• --password <PASSWORD>: opens an encrypted input for reading; an encrypted input is still refused at write time, in either mode

pdfboss meta report.pdf -o report-titled.pdf --set title="Q3 Report" --set author="Finance"

merge

Combine selected pages from several inputs into one fresh document. See Assembling documents.

pdfboss merge [OPTIONS] --out <OUT> <INPUTS>...

• <INPUTS>...: one or more inputs, each optionally FILE:RANGE (1-based, e.g. report.pdf:2-9); a bare path takes every page
• -o, --out <OUT>: output file (required)
• --password <PASSWORD>: one password tried against every encrypted input; an encrypted input is still refused at write time

pdfboss merge report.pdf:2-9 appendix.pdf -o combined.pdf

split

Cut a document into consecutive chunks of pages. See Assembling documents.

pdfboss split [OPTIONS] --out <OUT> --every <EVERY> <FILE>

• -o, --out <OUT>: output pattern containing %d, substituted with the 1-based part number (required)
• --every <EVERY>: pages per part (required); the last part carries whatever remains
• --password <PASSWORD>: password for an encrypted file (user or owner password); an encrypted input is still refused at write time

pdfboss split report.pdf -o 'part-%d.pdf' --every 10

rotate

Rotate selected pages by a quarter-turn multiple, clockwise. See Assembling documents.

pdfboss rotate [OPTIONS] --out <OUT> --by <BY> <FILE>

• -o, --out <OUT>: output file (required)
• --pages <PAGES>: 1-based pages, e.g. 2,4-9; every page when omitted
• --by <BY>: quarter turns clockwise, one of 90, 180, 270 (required)
• --rewrite: full rewrite instead of an incremental append
• --password <PASSWORD>: password for an encrypted file (user or owner password); an encrypted input is still refused at write time

Either mode refuses a page inlined directly into /Kids with no object of its own: pdfboss does not yet restructure such a page to rotate it.

pdfboss rotate report.pdf -o rotated.pdf --pages 2,4-9 --by 90

overlay

Draw the first page of <OVERLAY> onto every page of <FILE>, on top by default or beneath with --under. See Editing PDFs.

pdfboss overlay [OPTIONS] --out <OUT> <FILE> <OVERLAY>

• -o, --out <OUT>: output file (required)
• --under: draw beneath the page content instead of on top of it
• --rewrite: full rewrite instead of an incremental append
• --password <PASSWORD>: password for an encrypted file (user or owner password), tried against both <FILE> and <OVERLAY>; either encrypted input is still refused at write time

pdfboss overlay report.pdf draft.pdf -o out.pdf --under

rewrite

Rewrite a document fresh: recompressed, unreachable objects and earlier update sections left behind, with no page change. See Assembling documents.

pdfboss rewrite [OPTIONS] --out <OUT> <FILE>

• -o, --out <OUT>: output file (required)
• --password <PASSWORD>: password for an encrypted file (user or owner password); an encrypted input is still refused at write time

pdfboss rewrite report.pdf -o rewritten.pdf

encrypt

Encrypt a document with AES-256, revision 6, writing a fresh output. See Encrypting a file.

pdfboss encrypt [OPTIONS] --out <OUT> <FILE>

• -o, --out <OUT>: output file (required)
• --user-password <PASSWORD>: password readers must supply to open the file
• --owner-password <PASSWORD>: owner password; falls back to --user-password when omitted
• --allow <VALUES>: comma-separated permissions granted to a reader opening under the user password; one or more of print, modify, copy, annotate, fill-forms, accessibility, assemble, print-hires; every permission when omitted
• --password <PASSWORD>: opens an input that is itself encrypted, so it re-encrypts under the new passwords instead of refusing

At least one of --user-password/--owner-password must be set; both empty is refused.

pdfboss encrypt report.pdf -o locked.pdf --user-password hunter2 --allow print,copy

decrypt

Remove encryption from a document, writing a fresh plain output. See Removing encryption.

pdfboss decrypt [OPTIONS] --out <OUT> <FILE>

• -o, --out <OUT>: output file (required)
• --password <PASSWORD>: password for the encrypted file (user or owner password)

pdfboss decrypt locked.pdf -o report.pdf --password hunter2

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.

Rust crate reference

pdfboss is a workspace of focused crates, all sharing one version. Add the ones you need with cargo add; each crate's API reference lives on docs.rs.

A further workspace member, pdfboss-testkit, is an internal PDF fixture builder for the test suite; it is not published.

Where to start

• Reading a document: pdfboss_core::Document (open, load, and their _with_password twins), then page, page_count, metadata, version.
• Text and markdown: pdfboss_output::{extract_text, extract_markdown}, each taking a ReadingOrder (Content, StructureTree, Geometric); positioned styled spans via pdfboss_text::extract_spans; where each image is drawn, without decoding it, via pdfboss_text::placed_images.
• Rasterizing: pdfboss_render::{render_page, render_page_with_options, render_page_reporting} and Pixmap::save_png; embedded images via extract_page_images.
• Creating: pdfboss_write::{Pdf, Page, Canvas, Content}; see Creating PDFs.
• Composing Markdown: pdfboss_markdown::to_pdf with a pdfboss_style::Theme; see Markdown to PDF.
• Async and HTTP sources: pdfboss_aio::AsyncDocument (open, open_url, from_bytes); see Async and remote documents.
• Element iteration: pdfboss_core::Document::elements(ElementOpts), a lazy iterator over physical and logical elements, and the async AsyncDocument::elements, which returns an ElementStream; see Exploring PDF internals.
• Forms, bookmarks and attachments: Document::{interactive_form, form_fields, outline, named_destinations, page_labels, embedded_files, embedded_file_data, viewer_preferences}, each with a *_with(src, trailer) twin for an async source (pdfboss_core::{form_fields_with, outline_with, ...}); see Reading forms, bookmarks and attachments.
• Document-level structures: pdfboss_core::{linearization_dictionary, output_intents_with, articles_with, page_beads_with} and the page thumbnail, piece-info and presentation readers under the same naming.
• Structure tree: pdfboss_core::StructureTree (load_with, place_with, place_items_with, content_items_with, and content_item_counts_with for a summary count that reads no element) and Document::content_items(&page), a page's marked-content sequences and tagged annotations in tree order; see Annotations in the reading order.
• Editing existing files: pdfboss_write::{merge_documents, split_document, rotate_rewrite, rewrite_document, encrypt_document, decrypt_document} for a fresh document through the Importer, pdfboss_write::{split_runs, split_part, copy_pages_with} to build one part at a time, synchronously from a Document or from any AsyncObjectSource into any byte sink, and pdfboss_write::{Update, rotate_pages, set_metadata_with, watermark} for an incremental update; see Editing PDFs, Assembling documents and Encrypted PDFs.

The guide chapters carry compiled examples for each of these; the Quickstart has the shortest end-to-end one.

Limitations

Rendering is lenient and it says so: content pdfboss cannot read is skipped so the rest of the page still rasterizes, and every dropped or approximated item lands in a report. pdfboss render warns on stderr, the terminal explorer raises a notice, and the libraries return it through render_page_reporting (Rust) and Page.render_reporting() (Python). See Rendering pages for the reporting APIs.

The whole not-yet-supported list is two faces: /Symbol and /ZapfDingbats have no license-clean substitute, so they stay blank rather than borrowing an unrelated face's glyphs.

Clause by clause, the ISO 32000 conformance chapter lists every part of the standard with the status pdfboss claims for it and what is missing where the status is not implemented.

Fonts

Glyph painting is staged in tiers (embedded-only, all-embedded, full) selected with --fonts (CLI), the fonts parameter (Python) or RenderOptions::glyph_painting (Rust); the tiers are described in Rendering pages. What stays limited:

• full substitutes only non-embedded simple fonts, and a bold sans substitute is not visually distinct from regular weight.
• Standard-14 advance widths come from the Adobe Core-14 AFM tables, behind the PDF's own /Widths, both when a substitute is painted and when text extraction reports a span's end_x and bbox.

CMaps and CID fonts

Type0 /Encoding CMaps resolve: the predefined ISO 32000 Table 118 CJK set is compiled in (behind the predefined-cmaps feature, on by default in the CLI and the wheel), embedded CMap streams parse the same way, widths key on the mapped CID, vertical text (WMode 1) advances by /W2//DW2 with the default position vector, and extraction maps CIDs to Unicode through the character collection when /ToUnicode is absent.

Deferred: vertical runs still extract as horizontal-schema spans, one per show operator, with x/y at the glyph origin.

Turned text

Text drawn turned a quarter is grouped into lines in its own upright frame (see Extracting text). What stays limited:

• Text at other angles is treated as the nearest quarter turn, so a line set at 30 degrees can still split.
• Underline, strikethrough and highlight are judged in page space, so on turned text they are unreliable.
• A turned span carries no glyph_x, so combining marks in turned non-Latin text are joined without glyph positions.
• In layout output, the lines of a turned block keep the coordinates of their upright frame; the block's bbox is in page space.

JBIG2

JBIG2Decode covers the embedded stream format end to end: generic regions (all four templates, with TPGDON, arithmetic or MMR-coded), symbol dictionaries and text regions in both the arithmetic and the Huffman variant (refinement/aggregate-coded symbols and refined instance placements included), pattern dictionaries and halftone regions, generic refinement regions (both templates, with TPGRON) refining either the page or a retained intermediate region, intermediate regions of every type, and custom code table segments. Nothing in the standard's segment type table is refused; a malformed or truncated stream fails with a message naming what was wrong instead of rendering a blank.

Colour

Colour converts to sRGB. ICCBased spaces parse their embedded profile (v2 and v4; matrix/TRC and grayTRC models, and A2B0 lookup pipelines): a profile equivalent to sRGB keeps the exact device-RGB path, others transform per colour with Bradford adaptation from the D50 connection space, and a profile that will not parse falls back to the /N channel-count reduction. CalRGB, CalGray, and Lab convert through CIE XYZ the same way.

Only a profile's default transform is used (rendering intents are not switched), and DeviceN keeps a tint approximation.

JPEG 2000

JPXDecode implements ITU-T T.800 (JPEG 2000 Part 1); what it approximates it reports as a render warning rather than passing off silently.

ICC profiles embedded in the JPEG 2000 container are interpreted through the same ICC engine as ICCBased colour (a profile equivalent to sRGB or device gray keeps the exact device path, others transform per sample), and only a profile that will not parse falls back to the channel-count approximation. sYCC converts with the exact IEC 61966-2-1 Amd. 1 inverse.

Part 2 (ISO/IEC 15444-2) extensions are tolerated in the container but not decoded. Every output sample is normalized to 8 bits per channel with round-to-nearest, so sources deeper than 8 bits (the spec allows up to 38) still land on an 8-bit output grid.

Annotations

Appearance streams paint as the file carries them, and Square, Circle, Line, Polygon, PolyLine, Ink, text markup and Link annotations get an appearance built from their entries when they have none. A widget annotation without an appearance stream paints nothing: form field values are read through form_fields() but not rendered. Annotations are never written.

Transparency groups

A transparency group composites as one object with the alpha, blend mode and soft mask at its Do. Every group renders isolated (/I is not consulted); /K true is not honoured and is reported as a skipped knockout group; the group colour space /CS is never read, so blending stays in device RGB.

Optional content

Optional content groups (PDF layers, ISO 32000 §8.11) are honored per the document's default configuration: rendering and text extraction skip layers it turns off, counting them on the reports' hidden counters.

ISO 32000 conformance

pdfboss keeps a ledger of ISO 32000 clauses in iso32000/Iso32000/Catalogue/, one row per clause with the status pdfboss claims: implemented, incomplete, not implemented or out of scope. Clause numbers follow ISO 32000-1:2008; where ISO 32000-2:2020 numbers a clause differently the row carries both.

The ledger is checked by Lean 4 on every push (make iso32000-gate). Six theorems in iso32000/Iso32000/Gate.lean establish that every row is unique, that every clause of chapters 7 to 14 and the normative annexes has a row speaking to it, that every implemented row is cited by both implementation code and a test in the source tree, that every incomplete row is cited by implementation code and explains what is missing, that every other row explains itself, and that no first-edition citation names a clause the standard does not have. They are decided by Lean's compiled evaluator (native_decide), so they trust the Lean compiler as well as its kernel; the decode-after-encode theorems of the reference filter decoders in iso32000/Iso32000/Reference/, whose vectors the Rust tests replay, are checked by the kernel alone. Citation counts below are the number of source comments naming the clause or a sub-clause of it, in implementation code and in tests.

This page is generated by make iso32000-report. Edit the ledger, not the page.

7 Syntax

8 Graphics

9 Text

10 Rendering

11 Transparency

12 Interactive Features

13 Multimedia Features

14 Document Interchange