python-pages 0.1.0__tar.gz

python_pages-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuki Tamura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_pages-0.1.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: python-pages
+Version: 0.1.0
+Summary: A python-docx-inspired API for Apple Pages documents
+Author-email: Yuki Tamura <isoparametric@isoparametric.xyz>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/isoparametric/python-pages
+Project-URL: Issues, https://github.com/isoparametric/python-pages/issues
+Keywords: apple-pages,document,iwork,python-docx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Office Suites
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# python-pages
+
+`python-pages` is a Python library for reading and editing modern Apple Pages
+documents with an object model inspired by
+[`python-docx`](https://python-docx.readthedocs.io/). The distribution name is
+`python-pages`; the import name is `pages`:
+
+```python
+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:
+
+```sh
+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
+
+```python
+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:
+
+```python
+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](REPORT.md).
+
+## Command-line interface
+
+```sh
+python-pages inspect input.pages
+python-pages bold input.pages output.pages "unique body substring"
+```
+
+Without installation:
+
+```sh
+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:
+
+```sh
+python3 -m unittest discover -s tests -v
+```
+
+Use the decoded-IWA audit tool for every write path:
+
+```sh
+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.

python_pages-0.1.0/README.md

@@ -0,0 +1,248 @@
+# python-pages
+
+`python-pages` is a Python library for reading and editing modern Apple Pages
+documents with an object model inspired by
+[`python-docx`](https://python-docx.readthedocs.io/). The distribution name is
+`python-pages`; the import name is `pages`:
+
+```python
+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:
+
+```sh
+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
+
+```python
+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:
+
+```python
+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](REPORT.md).
+
+## Command-line interface
+
+```sh
+python-pages inspect input.pages
+python-pages bold input.pages output.pages "unique body substring"
+```
+
+Without installation:
+
+```sh
+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:
+
+```sh
+python3 -m unittest discover -s tests -v
+```
+
+Use the decoded-IWA audit tool for every write path:
+
+```sh
+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.

python_pages-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-pages"
+version = "0.1.0"
+description = "A python-docx-inspired API for Apple Pages documents"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Yuki Tamura", email = "isoparametric@isoparametric.xyz" }]
+requires-python = ">=3.11"
+keywords = ["apple-pages", "document", "iwork", "python-docx"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Office Suites",
+]
+
+[project.urls]
+Repository = "https://github.com/isoparametric/python-pages"
+Issues = "https://github.com/isoparametric/python-pages/issues"
+
+[project.scripts]
+python-pages = "pages.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pages = ["data/*.pages"]

python_pages-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

python_pages-0.1.0/src/pages/__init__.py

@@ -0,0 +1,65 @@
+"""Dependency-free Apple Pages IWA reading and character formatting."""
+
+from .api import (
+    AnnotationHighlight,
+    Cm,
+    Comment,
+    Comments,
+    Document,
+    Inches,
+    InlineShape,
+    Hyperlink,
+    Style,
+    Styles,
+    Length,
+    Pt,
+    Section,
+    Table,
+    TableCell,
+    WD_ALIGN_PARAGRAPH,
+    WD_COLOR,
+    WD_COLOR_INDEX,
+    WD_LINE_SPACING,
+    WD_PARAGRAPH_ALIGNMENT,
+    WD_TAB_ALIGNMENT,
+    WD_TAB_LEADER,
+    WD_ORIENT,
+    WD_ORIENTATION,
+    WD_STYLE_TYPE,
+)
+from .pages import PagesDocument
+from .core_properties import CoreProperties
+from .stylesheet import CharacterProperties, ParagraphProperties, RGBColor
+
+__all__ = [
+    "AnnotationHighlight",
+    "CharacterProperties",
+    "Cm",
+    "Comment",
+    "Comments",
+    "CoreProperties",
+    "Document",
+    "Inches",
+    "InlineShape",
+    "Hyperlink",
+    "Style",
+    "Styles",
+    "Length",
+    "PagesDocument",
+    "ParagraphProperties",
+    "Pt",
+    "RGBColor",
+    "Section",
+    "Table",
+    "TableCell",
+    "WD_ALIGN_PARAGRAPH",
+    "WD_COLOR",
+    "WD_COLOR_INDEX",
+    "WD_LINE_SPACING",
+    "WD_PARAGRAPH_ALIGNMENT",
+    "WD_TAB_ALIGNMENT",
+    "WD_TAB_LEADER",
+    "WD_ORIENT",
+    "WD_ORIENTATION",
+    "WD_STYLE_TYPE",
+]