Reading page labels and /PieceInfo from AlvaStamp PDFs

pip install pypdf
python read-page-info.py document.pdf

#!/usr/bin/env python3
"""Read page labels and /PieceInfo from a PDF stamped by AlvaStamp.

Page labels appear in Acrobat and most browsers. /PieceInfo is private
page-level data and needs a script like this.

    pip install pypdf
    python read-page-info.py document.pdf
"""

from __future__ import annotations

import sys
from typing import Any

from pypdf import PdfReader
from pypdf.generic import DictionaryObject, IndirectObject


def deref(obj: Any) -> Any:
    if isinstance(obj, IndirectObject):
        return obj.get_object()
    return obj


def as_dict(obj: Any) -> DictionaryObject | None:
    obj = deref(obj)
    return obj if isinstance(obj, DictionaryObject) else None


def as_text(obj: Any) -> str | None:
    obj = deref(obj)
    if obj is None:
        return None
    if isinstance(obj, DictionaryObject):
        parts = []
        for key, value in obj.items():
            parts.append(f"{key}={as_text(value)}")
        return "{" + ", ".join(parts) + "}"
    text = str(obj)
    return text[1:] if text.startswith("/") and len(text) > 1 else text


def piece_info_entries(page) -> list[tuple[str, str | None, str | None]]:
    piece = as_dict(page.get("/PieceInfo"))
    if piece is None:
        return []
    rows: list[tuple[str, str | None, str | None]] = []
    for key, data in piece.items():
        data = as_dict(data)
        name = str(key)
        if data is None:
            rows.append((name, None, as_text(piece.get(key))))
            continue
        rows.append(
            (
                name,
                as_text(data.get("/LastModified")),
                as_text(data.get("/Private")),
            )
        )
    return rows


def main() -> int:
    if len(sys.argv) != 2:
        print("Usage: python read-page-info.py document.pdf", file=sys.stderr)
        return 2
    path = sys.argv[1]
    reader = PdfReader(path)
    labels = reader.page_labels
    for index, page in enumerate(reader.pages):
        print(f"# page {index + 1}")
        print(f"label: {labels[index]}")
        entries = piece_info_entries(page)
        if not entries:
            print("PieceInfo: (none)")
        for name, modified, private in entries:
            print(f"PieceInfo {name}:")
            if modified:
                print(f"  LastModified: {modified}")
            print(f"  Private: {private}")
        print()
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

npm install pdf-lib
node read-page-info.mjs document.pdf

#!/usr/bin/env node
/**
 * Read page labels and /PieceInfo from a PDF stamped by AlvaStamp.
 *
 * Page labels appear in Acrobat and most browsers. /PieceInfo is private
 * page-level data and needs a script like this.
 *
 *   npm install pdf-lib
 *   node read-page-info.mjs document.pdf
 */

import { readFile } from "node:fs/promises";
import {
	PDFArray,
	PDFDict,
	PDFDocument,
	PDFHexString,
	PDFName,
	PDFNumber,
	PDFString,
} from "pdf-lib";

function asText(obj) {
	if (!obj) return null;
	if (obj instanceof PDFString || obj instanceof PDFHexString) return obj.decodeText();
	if (obj instanceof PDFName) {
		const name = obj.asString();
		return name.startsWith("/") ? name.slice(1) : name;
	}
	if (obj instanceof PDFNumber) return String(obj.asNumber());
	if (obj instanceof PDFDict) {
		return (
			"{" +
			[...obj.keys()]
				.map((key) => `${asText(key)}=${asText(obj.lookup(key))}`)
				.join(", ") +
			"}"
		);
	}
	return String(obj);
}

function labelForPage(labels, pageIndex) {
	if (!(labels instanceof PDFDict)) return String(pageIndex + 1);
	const nums = labels.lookup(PDFName.of("Nums"));
	if (!(nums instanceof PDFArray)) return String(pageIndex + 1);

	let rangeStart = 0;
	let dict = null;
	for (let i = 0; i + 1 < nums.size(); i += 2) {
		const startObj = nums.lookup(i);
		const start = startObj instanceof PDFNumber ? startObj.asNumber() : NaN;
		if (Number.isNaN(start) || start > pageIndex) break;
		rangeStart = start;
		dict = nums.lookup(i + 1);
	}
	if (!(dict instanceof PDFDict)) return String(pageIndex + 1);

	const prefix = asText(dict.lookup(PDFName.of("P"))) ?? "";
	const style = dict.lookup(PDFName.of("S"));
	if (!style) return prefix || String(pageIndex + 1);

	const st = dict.lookup(PDFName.of("St"));
	const n = (st instanceof PDFNumber ? st.asNumber() : 1) + (pageIndex - rangeStart);
	const kind = asText(style);
	if (kind === "D") return `${prefix}${n}`;
	return prefix || String(n);
}

function pieceInfoEntries(page) {
	const piece = page.node.lookup(PDFName.of("PieceInfo"));
	if (!(piece instanceof PDFDict)) return [];
	return [...piece.keys()].map((key) => {
		const data = piece.lookup(key);
		if (!(data instanceof PDFDict)) {
			return { name: asText(key), modified: null, private: asText(data) };
		}
		return {
			name: asText(key),
			modified: asText(data.lookup(PDFName.of("LastModified"))),
			private: asText(data.lookup(PDFName.of("Private"))),
		};
	});
}

const path = process.argv[2];
if (!path) {
	console.error("Usage: node read-page-info.mjs document.pdf");
	process.exit(2);
}

const pdf = await PDFDocument.load(await readFile(path), {
	updateMetadata: false,
});
const labels = pdf.catalog.lookup(PDFName.of("PageLabels"));
const pages = pdf.getPages();

for (let i = 0; i < pages.length; i++) {
	console.log(`# page ${i + 1}`);
	console.log(`label: ${labelForPage(labels, i)}`);
	const entries = pieceInfoEntries(pages[i]);
	if (entries.length === 0) {
		console.log("PieceInfo: (none)");
	}
	for (const entry of entries) {
		console.log(`PieceInfo /${entry.name}:`);
		if (entry.modified) console.log(`  LastModified: ${entry.modified}`);
		console.log(`  Private: ${entry.private}`);
	}
	console.log();
}