python-pages 0.1.0

A python-docx-inspired API for Apple Pages documents

python-pages

python-pages is a Python library for reading and editing modern Apple Pages documents with an object model inspired by python-docx. The distribution name is python-pages; the import name is pages:

from pages import Document

The library edits .pages packages directly. It does not launch Pages, use AppleScript, or automate the GUI. Its runtime is dependency-free and consists of a ZIP container layer, a lossless protobuf-wire layer, an iWork Snappy/IWA layer, and a public document API.

This project is alpha-quality. Keep the source document and inspect important outputs in Pages before using them in production.

Installation

From a local checkout:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e .

The editable install provides both import pages and the python-pages command. To run without installing, prefix commands with PYTHONPATH=src.

The project requires Python 3.11 or newer. There are no runtime dependencies.

The requested pages import name is also used by an unrelated PyPI static-site generator. Install python-pages in a dedicated virtual environment and do not co-install that distribution; both projects would otherwise provide the same top-level import name.

Quick start

from pages import (
    Document,
    Inches,
    Pt,
    RGBColor,
    WD_ALIGN_PARAGRAPH,
    WD_COLOR_INDEX,
    WD_ORIENT,
)

document = Document("input.pages")

paragraph = document.paragraphs[0]
run = paragraph.runs[0]
print(paragraph.text, run.text)

# Character formatting uses python-docx-style tri-state values.
run.bold = True
run.italic = False
run.underline = None
run.font.name = "Helvetica-Bold"
run.font.size = Pt(14)
run.font.color.rgb = RGBColor(0x22, 0x66, 0xCC)
run.font.strike = True
run.font.subscript = False
run.font.superscript = True

# Pages stores the observed text background at paragraph granularity.
paragraph.highlight_color = WD_COLOR_INDEX.YELLOW
paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER
paragraph.paragraph_format.line_spacing = Pt(24)
paragraph.paragraph_format.space_before = Pt(12)
paragraph.paragraph_format.left_indent = Inches(0.25)

paragraph.add_run(" Appended text")
document.add_paragraph("A new body paragraph")
document.add_heading("A new heading", level=1)
document.add_page_break()

section = document.sections[0]
section.orientation = WD_ORIENT.LANDSCAPE
section.page_width, section.page_height = section.page_height, section.page_width
section.left_margin = Inches(0.75)
section.header.paragraphs[0].text = "Header text"

document.save("output.pages")

Document() without a path starts with a bundled minimal Pages template. The template contains blank body text/previews and a neutral white placeholder for an otherwise unreachable image graph. The input path is never modified; changes are written only by save().

API coverage

The public API intentionally follows python-docx naming where Pages has a reasonable counterpart:

Area	python-pages support
Documents	Document(path), Document(), save()
Text	paragraphs, Paragraph.text, runs, Run.text, insertion and deletion
Fonts	bold, italic, underline, strike, name, size, RGB color, subscript, superscript
Paragraphs	alignment, line spacing, spacing before/after, indents, tab stops, named styles
Sections	one Pages section with page size, margins, orientation, headers, and footers
Tables	read rows/cells, edit materialized text cells, clone a blank table with add_table()
Pictures	inspect/replace PNG images and clone an inline image with add_picture()
Links and styles	inspect/edit existing hyperlinks; enumerate/apply named paragraph and character styles
Properties	python-docx-shaped core_properties facade
Comments	read comments, replies, authors, anchors, and edit existing comment text

Examples for additional object types:

table = document.tables[0]
print([[cell.text for cell in row.cells] for row in table.rows])
table.cell(1, 1).text = "Updated cell"
new_table = document.add_table(rows=3, cols=4)

picture = document.inline_shapes[0]
print(picture.filename, picture.width, picture.height)
picture.replace("replacement.png", "replacement-256px-thumbnail.png")
new_picture = document.add_picture("new-image.png", width=Inches(4))

hyperlink = document.hyperlinks[0]
hyperlink.text = "Project website"
hyperlink.address = "https://example.com"

for comment in document.comments:
    print(comment.author, comment.anchor_text, comment.text)
    print([reply.text for reply in comment.replies])

Differences from python-docx

python-pages is API-inspired, not a byte-format adapter for DOCX. Important differences follow from the Pages data model:

• Pages page geometry is package-wide, so Document.sections contains one section. Multiple DOCX sections and linked-to-previous behavior are not emulated.
• A Pages header or footer is exposed as its left, center, and right text fragments rather than as a WordprocessingML story part.
• The observed Pages text-background property belongs to an anonymous paragraph style. Run.font.highlight_color is retained for call-shape compatibility but reads or writes the run's entire containing paragraph.
• core_properties values without a native Pages counterpart are stored in Metadata/PythonPagesCoreProperties.plist. Documents written by the earlier project name remain readable.
• add_table() needs an existing Pages-authored table in the target document as a structural template. It supports one tile of up to 256 rows and does not implement cell merge or sparse-cell materialization.
• add_picture() needs an existing Pages-authored image graph in the target document. New and replacement media are PNG; automatic thumbnails support non-interlaced 8-bit RGB/RGBA PNG.
• Existing comments and replies can be read and edited, but creating a new comment is intentionally disabled because Pages also writes collaboration and view-state objects whose lifecycle is not yet established.
• Existing hyperlinks can be edited. Creating a new hyperlink is not yet part of the public API.
• Pages formats are undocumented and can change between application versions. The implementation preserves unknown protobuf fields where possible, but it cannot guarantee support for every historical or future Pages variant.

The detailed compatibility ledger and reverse-engineering evidence are in REPORT.md.

Command-line interface

python-pages inspect input.pages
python-pages bold input.pages output.pages "unique body substring"

Without installation:

PYTHONPATH=src python3 -m pages.cli inspect input.pages

The bold helper expects an unambiguous substring unless --occurrence is provided. It converts Python string offsets to the UTF-16 offsets used by Pages.

Optional test fixtures are not distributed

The test suite is self-contained and passes from a standalone checkout. Private .pages files used for Pages.app interoperability checks can contain copyrighted or sensitive content, so samples/ and generated output/ packages are excluded from Git and distributions.

To enable the additional real-document tests, place a Pages-authored package at samples/local_fixture.pages. The tests activate automatically with unittest.skipUnless when the file is present. It must contain:

• at least one inline PNG image;
• at least one nonempty table;
• at least one hyperlink; and
• at least one comment with a reply.

No particular headings, formatted runs, or document text are required by these optional tests. Use only content you are allowed to publish and do not commit the fixture.

To enable the python-docx compatibility-ledger audit, place the upstream source tree at ref/python-docx/. Its tests must be under ref/python-docx/tests/; the ledger test also activates automatically when that directory is present.

Run the suite with:

python3 -m unittest discover -s tests -v

Use the decoded-IWA audit tool for every write path:

PYTHONPATH=src python3 tools/diff_iwa.py before.pages after.pages
unzip -t after.pages

Architecture

• Low level: snappy.py, protobuf.py, and iwa.py provide lossless wire parsing and 64-KiB iWork frame handling.
• Middle level: pages.py, metadata.py, stylesheet.py, text.py, and the component-specific modules traverse and mutate Pages object graphs.
• High level: api.py provides the python-docx-shaped object model exported by pages.

Synthesized styles are registered in the stylesheet, parent/child map, MessageInfo references, PackageMetadata UUID map, and cross-component reference map. Untouched ZIP members and IWA payloads are preserved byte-for-byte; changed members are re-encoded into valid Pages packages.

Project status

The compatibility ledger accounts for all 59 python-docx test files and 662 discovered behavior methods as migrated, partially migrated, or format-specific exclusions. When ref/python-docx/ is present, the optional ledger test verifies that the upstream checkout contains behavior tests. The dependency-free test suite runs standalone; optional fixture and ledger tests activate automatically when their local inputs are present.

python-pages is an independent project and is not affiliated with Apple or the python-docx project.