python-pages 0.1.0__py3-none-any.whl

pages/cli.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from zipfile import ZipFile
+
+from .pages import PagesDocument
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="python-pages")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    inspect = sub.add_parser("inspect", help="parse and summarize a .pages file")
+    inspect.add_argument("input", type=Path)
+
+    bold = sub.add_parser("bold", help="make a body-text substring bold")
+    bold.add_argument("input", type=Path)
+    bold.add_argument("output", type=Path)
+    bold.add_argument("substring")
+    bold.add_argument("--occurrence", type=int, default=1)
+
+    args = parser.parse_args()
+    document = PagesDocument.load(args.input)
+    if args.command == "inspect":
+        storage = document.body_storage()
+        result = document.validate() | {
+            "storage_id": storage.segment.identifier,
+            "body_codepoints": len(document.text(storage)),
+        }
+    else:
+        result = document.make_substring_bold(args.substring, occurrence=args.occurrence)
+        document.save(args.output)
+        with ZipFile(args.output) as archive:
+            bad_member = archive.testzip()
+        reparsed = PagesDocument.load(args.output)
+        result |= reparsed.validate() | {"zip_test": "pass" if bad_member is None else bad_member}
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

pages/comments.py

@@ -0,0 +1,168 @@
+"""Middle-layer access to Pages text comments and their replies."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+import struct
+from typing import TYPE_CHECKING
+
+from .protobuf import Message
+from .stylesheet import RGBColor, decode_color
+from .text import LocatedObject, parse_reference
+
+if TYPE_CHECKING:
+    from .pages import PagesDocument
+
+
+TYPE_ANNOTATION_AUTHOR = 212
+TYPE_HIGHLIGHT = 2013
+TYPE_COMMENT_STORAGE = 3056
+
+STORAGE_TABLE_OVERLAPPING_HIGHLIGHT = 25
+HIGHLIGHT_COMMENT_STORAGE = 1
+COMMENT_TEXT = 1
+COMMENT_CREATION_DATE = 2
+COMMENT_AUTHOR = 3
+COMMENT_REPLIES = 4
+AUTHOR_NAME = 1
+
+_APPLE_EPOCH = datetime(2001, 1, 1, tzinfo=timezone.utc)
+
+
+def _reference(message: Message, number: int) -> int | None:
+    field = message.one(number)
+    return None if field is None else parse_reference(bytes(field.value))
+
+
+def _date(message: Message) -> datetime | None:
+    field = message.one(COMMENT_CREATION_DATE)
+    if field is None:
+        return None
+    value = Message.parse(bytes(field.value)).one(1)
+    if value is None or value.wire_type != 1:
+        return None
+    seconds = struct.unpack("<d", int(value.value).to_bytes(8, "little"))[0]
+    return _APPLE_EPOCH + timedelta(seconds=seconds)
+
+
+@dataclass
+class CommentStore:
+    """One type-3056 comment storage, optionally attached to a text range."""
+
+    document: "PagesDocument"
+    object: LocatedObject
+    highlight: LocatedObject | None = None
+    start_utf16: int | None = None
+    end_utf16: int | None = None
+
+    @property
+    def text(self) -> str:
+        field = self.object.message.one(COMMENT_TEXT)
+        return "" if field is None else bytes(field.value).decode("utf-8", "replace")
+
+    @text.setter
+    def text(self, value: str) -> None:
+        if not isinstance(value, str):
+            raise TypeError("comment text must be a string")
+        field = self.object.message.one(COMMENT_TEXT)
+        if field is None:
+            self.object.message.add_bytes(COMMENT_TEXT, value.encode("utf-8"))
+        else:
+            field.set_bytes(value.encode("utf-8"))
+
+    @property
+    def author_object(self) -> LocatedObject | None:
+        identifier = _reference(self.object.message, COMMENT_AUTHOR)
+        author = self.document.objects().get(identifier) if identifier is not None else None
+        if author is None or author.info.type_id != TYPE_ANNOTATION_AUTHOR:
+            return None
+        return author
+
+    @property
+    def author(self) -> str:
+        author = self.author_object
+        if author is None:
+            return ""
+        field = author.message.one(AUTHOR_NAME)
+        return "" if field is None else bytes(field.value).decode("utf-8", "replace")
+
+    @property
+    def annotation_color(self) -> RGBColor | None:
+        author = self.author_object
+        if author is None:
+            return None
+        field = author.message.one(2)
+        return None if field is None else decode_color(bytes(field.value))
+
+    @property
+    def timestamp(self) -> datetime | None:
+        return _date(self.object.message)
+
+    @property
+    def identifier(self) -> int:
+        return self.object.segment.identifier
+
+    @property
+    def comment_id(self) -> int:
+        return (
+            self.highlight.segment.identifier
+            if self.highlight is not None
+            else self.object.segment.identifier
+        )
+
+    @property
+    def replies(self) -> list["CommentStore"]:
+        objects = self.document.objects()
+        result: list[CommentStore] = []
+        for field in self.object.message.get(COMMENT_REPLIES):
+            identifier = parse_reference(bytes(field.value))
+            reply = objects.get(identifier) if identifier is not None else None
+            if reply is not None and reply.info.type_id == TYPE_COMMENT_STORAGE:
+                result.append(CommentStore(self.document, reply))
+        return result
+
+
+def storage_comments(
+    document: "PagesDocument", storage: LocatedObject
+) -> list[CommentStore]:
+    """Return comments anchored by storage field 25 in document order."""
+    table_field = storage.message.one(STORAGE_TABLE_OVERLAPPING_HIGHLIGHT)
+    if table_field is None:
+        return []
+    objects = document.objects()
+    result: list[CommentStore] = []
+    table = Message.parse(bytes(table_field.value))
+    for raw in table.get(1):
+        entry = Message.parse(bytes(raw.value))
+        range_field = entry.one(1)
+        highlight_ref = entry.one(2)
+        if range_field is None or highlight_ref is None:
+            continue
+        range_message = Message.parse(bytes(range_field.value))
+        location = range_message.one(1)
+        length = range_message.one(2)
+        highlight_id = parse_reference(bytes(highlight_ref.value))
+        highlight = objects.get(highlight_id) if highlight_id is not None else None
+        if (
+            location is None
+            or length is None
+            or highlight is None
+            or highlight.info.type_id != TYPE_HIGHLIGHT
+        ):
+            continue
+        comment_id = _reference(highlight.message, HIGHLIGHT_COMMENT_STORAGE)
+        comment = objects.get(comment_id) if comment_id is not None else None
+        if comment is None or comment.info.type_id != TYPE_COMMENT_STORAGE:
+            continue
+        start = int(location.value)
+        result.append(
+            CommentStore(
+                document,
+                comment,
+                highlight=highlight,
+                start_utf16=start,
+                end_utf16=start + int(length.value),
+            )
+        )
+    return sorted(result, key=lambda item: (item.start_utf16 or 0, item.comment_id))

pages/components.py

@@ -0,0 +1,403 @@
+"""Schema-light cloning for complete iWork component subgraphs.
+
+The high-level table and image insertion APIs use this module to duplicate a
+Pages-authored object graph.  Shared stylesheet objects remain shared while
+owned archive objects, standalone component locators, UUID registrations, and
+cross-component references receive fresh identities.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import uuid
+from zipfile import ZipInfo
+
+from .iwa import ArchiveSegment, IWAFile, MessageInfo
+from .metadata import (
+    COMPONENT_EXTERNAL_REFERENCES,
+    COMPONENT_IDENTIFIER,
+    COMPONENT_LOCATOR,
+    COMPONENT_OBJECT_UUID_MAP,
+    COMPONENT_PREFERRED_LOCATOR,
+    PACKAGE_COMPONENTS,
+    component_name,
+    object_uuid_map,
+    package_revision_identifier,
+    register_component_object,
+)
+from .pages import PagesDocument, StoredEntry
+from .protobuf import Message, ProtobufError, encode_varint, read_varint
+from .text import (
+    AttributeRun,
+    LocatedObject,
+    add_object_reference,
+    encode_attribute_table,
+    parse_attribute_table,
+    unpack_packed_varints,
+)
+
+
+@dataclass(frozen=True)
+class GraphClone:
+    """The old-to-new identity map and cloned root object."""
+
+    root: LocatedObject
+    identifiers: dict[int, int]
+    component_identifiers: dict[int, int]
+
+
+def _set_varint(message: Message, number: int, value: int) -> None:
+    field = message.one(number)
+    if field is None:
+        message.add_varint(number, value)
+    else:
+        field.set_varint(value)
+
+
+def _set_bytes(message: Message, number: int, value: bytes) -> None:
+    field = message.one(number)
+    if field is None:
+        message.add_bytes(number, value)
+    else:
+        field.set_bytes(value)
+
+
+def _pack_varints(values: list[int]) -> bytes:
+    return b"".join(encode_varint(value) for value in values)
+
+
+def _info_references(obj: LocatedObject) -> list[int]:
+    result: list[int] = []
+    for field in obj.info.message.get(5):
+        result.extend(unpack_packed_varints(bytes(field.value)))
+    return result
+
+
+def _remap_nested_references(
+    message: Message,
+    object_identifiers: dict[int, int],
+    data_identifiers: dict[int, int] | None = None,
+) -> bool:
+    """Remap embedded TSP.Reference/DataReference messages recursively."""
+    changed = False
+    data_identifiers = data_identifiers or {}
+    for field in message.fields:
+        if field.wire_type != 2:
+            continue
+        try:
+            child = Message.parse(bytes(field.value))
+        except ProtobufError:
+            continue
+        first = child.one(1)
+        reference_shape = (
+            first is not None
+            and first.wire_type == 0
+            and all(item.wire_type == 0 and item.number in (1, 2, 3) for item in child.fields)
+        )
+        if reference_shape and int(first.value) in object_identifiers:
+            first.set_varint(object_identifiers[int(first.value)])
+            field.set_bytes(child.encode())
+            changed = True
+            continue
+        if reference_shape and int(first.value) in data_identifiers:
+            first.set_varint(data_identifiers[int(first.value)])
+            field.set_bytes(child.encode())
+            changed = True
+            continue
+        if _remap_nested_references(child, object_identifiers, data_identifiers):
+            field.set_bytes(child.encode())
+            changed = True
+    return changed
+
+
+def _remap_message_info(
+    info: Message,
+    object_identifiers: dict[int, int],
+    data_identifiers: dict[int, int] | None = None,
+) -> None:
+    data_identifiers = data_identifiers or {}
+    for field in info.get(5):
+        values = unpack_packed_varints(bytes(field.value))
+        field.set_bytes(_pack_varints([object_identifiers.get(value, value) for value in values]))
+    for field in info.get(6):
+        values = unpack_packed_varints(bytes(field.value))
+        field.set_bytes(_pack_varints([data_identifiers.get(value, value) for value in values]))
+
+
+def remap_payload_data_references(
+    obj: LocatedObject, data_identifiers: dict[int, int]
+) -> None:
+    """Update data references in an already-cloned payload and MessageInfo."""
+    _remap_nested_references(obj.message, {}, data_identifiers)
+    _remap_message_info(obj.info.message, {}, data_identifiers)
+
+
+def _clone_segment(
+    source: LocatedObject,
+    identifier: int,
+    object_identifiers: dict[int, int],
+) -> ArchiveSegment:
+    if len(source.segment.infos) != 1:
+        raise ValueError("component graph templates must use one-message archive segments")
+    payload = Message.parse(source.message.encode())
+    _remap_nested_references(payload, object_identifiers)
+
+    header = Message.parse(source.segment.header.encode())
+    header_identifier = header.one(1)
+    if header_identifier is None:
+        raise ValueError("component graph ArchiveInfo lacks an identifier")
+    header_identifier.set_varint(identifier)
+    info_fields = header.get(2)
+    if len(info_fields) != 1:
+        raise ValueError("component graph ArchiveInfo must contain one MessageInfo")
+    info_field = info_fields[0]
+    info_message = Message.parse(bytes(info_field.value))
+    _remap_message_info(info_message, object_identifiers)
+    length = info_message.one(3)
+    type_field = info_message.one(1)
+    if length is None or type_field is None:
+        raise ValueError("component graph MessageInfo is incomplete")
+    info = MessageInfo(info_field, info_message, int(type_field.value), int(length.value))
+    info.update_length(len(payload.encode()))
+    return ArchiveSegment(header, b"", identifier, [info], [payload], [b""])
+
+
+def _component_records(package: Message) -> dict[int, tuple[object, Message]]:
+    result: dict[int, tuple[object, Message]] = {}
+    for field in package.get(PACKAGE_COMPONENTS):
+        component = Message.parse(bytes(field.value))
+        identifier = component.one(COMPONENT_IDENTIFIER)
+        if identifier is not None:
+            result[int(identifier.value)] = (field, component)
+    return result
+
+
+def _component_for_filename(
+    filename: str, components: dict[int, tuple[object, Message]]
+) -> int | None:
+    locator = filename.removeprefix("Index/").removesuffix(".iwa")
+    for identifier, (_, component) in components.items():
+        if component_name(component) == locator:
+            return identifier
+    return None
+
+
+def _remap_external_reference(
+    reference: Message,
+    object_identifiers: dict[int, int],
+    component_identifiers: dict[int, int],
+) -> bool:
+    changed = False
+    component = reference.one(1)
+    if component is not None and int(component.value) in component_identifiers:
+        component.set_varint(component_identifiers[int(component.value)])
+        changed = True
+    obj = reference.one(2)
+    if obj is not None and int(obj.value) in object_identifiers:
+        obj.set_varint(object_identifiers[int(obj.value)])
+        changed = True
+    return changed
+
+
+def _append_external_reference(component: Message, reference: Message) -> None:
+    encoded = reference.encode()
+    if all(bytes(field.value) != encoded for field in component.get(COMPONENT_EXTERNAL_REFERENCES)):
+        component.add_bytes(COMPONENT_EXTERNAL_REFERENCES, encoded)
+
+
+def clone_object_graph(
+    document: PagesDocument,
+    root_identifier: int,
+    *,
+    include,
+) -> GraphClone:
+    """Clone the reference closure selected by ``include``.
+
+    ``include`` receives each referenced :class:`LocatedObject`.  It is used
+    to retain shared styles while selecting all objects owned by the template
+    table or drawable.
+    """
+    source_objects = document.objects()
+    root = source_objects.get(root_identifier)
+    if root is None:
+        raise KeyError(f"component graph root {root_identifier} was not found")
+
+    selected: dict[int, LocatedObject] = {}
+    queue = [root]
+    while queue:
+        obj = queue.pop(0)
+        identifier = obj.segment.identifier
+        if identifier in selected:
+            continue
+        selected[identifier] = obj
+        for reference in _info_references(obj):
+            candidate = source_objects.get(reference)
+            if candidate is not None and include(candidate):
+                queue.append(candidate)
+
+    object_identifiers = {
+        old: document.allocate_object_identifier() for old in sorted(selected)
+    }
+    package = document.package_metadata()
+    components = _component_records(package.message)
+    standalone_components: dict[int, int] = {}
+    for old, obj in selected.items():
+        component_id = _component_for_filename(obj.filename, components)
+        if component_id == old:
+            standalone_components[old] = object_identifiers[old]
+
+    # Clone standalone component records first so their new IWA locators are
+    # available when archive segments are placed.
+    new_locators: dict[int, str] = {}
+    for old_component, new_component in standalone_components.items():
+        source_component = components[old_component][1]
+        component = Message.parse(source_component.encode())
+        _set_varint(component, COMPONENT_IDENTIFIER, new_component)
+        preferred = component.one(COMPONENT_PREFERRED_LOCATOR)
+        if preferred is None:
+            raise ValueError(f"component {old_component} has no preferred locator")
+        base = bytes(preferred.value).decode("utf-8")
+        locator = f"{base}-{new_component}-2"
+        _set_bytes(component, COMPONENT_LOCATOR, locator.encode("utf-8"))
+        for field in component.get(COMPONENT_EXTERNAL_REFERENCES):
+            reference = Message.parse(bytes(field.value))
+            _remap_external_reference(reference, object_identifiers, standalone_components)
+            field.set_bytes(reference.encode())
+        for field in component.get(COMPONENT_OBJECT_UUID_MAP):
+            entry = Message.parse(bytes(field.value))
+            identifier = entry.one(1)
+            if identifier is not None and int(identifier.value) in object_identifiers:
+                identifier.set_varint(object_identifiers[int(identifier.value)])
+                field.set_bytes(entry.encode())
+        package.message.add_bytes(PACKAGE_COMPONENTS, component.encode())
+        new_locators[old_component] = locator
+
+    cloned: dict[int, LocatedObject] = {}
+    for old, source in selected.items():
+        new = object_identifiers[old]
+        segment = _clone_segment(source, new, object_identifiers)
+        if old in standalone_components:
+            filename = "Index/" + new_locators[old] + ".iwa"
+            document.entries.append(
+                StoredEntry(ZipInfo(filename), IWAFile([segment], []))
+            )
+        else:
+            filename = source.filename
+            document.iwa_files[filename].segments.append(segment)
+        cloned[new] = LocatedObject(
+            filename, segment, segment.infos[0], segment.payloads[0]
+        )
+
+    # Mirror cross-component links from existing owning components. Links in
+    # newly cloned standalone records were handled above.
+    for component_id, (raw_component, source_component) in components.items():
+        if component_id in standalone_components:
+            continue
+        component = Message.parse(bytes(raw_component.value))
+        for raw_reference in source_component.get(COMPONENT_EXTERNAL_REFERENCES):
+            reference = Message.parse(bytes(raw_reference.value))
+            if not _remap_external_reference(
+                reference, object_identifiers, standalone_components
+            ):
+                continue
+            _append_external_reference(component, reference)
+        raw_component.set_bytes(component.encode())
+
+    # Existing components use an explicit UUID map only for addressable top
+    # objects. Mirror precisely the source map's membership.
+    revision = package_revision_identifier(package.message)
+    for component_id, (raw_component, source_component) in components.items():
+        if component_id in standalone_components:
+            continue
+        registered = object_uuid_map(source_component)
+        locator = component_name(source_component)
+        for old in selected:
+            if old not in registered:
+                continue
+            register_component_object(
+                package.message,
+                locator,
+                object_identifiers[old],
+                uuid_seed=f"python-pages:{revision}:clone:{old}:{object_identifiers[old]}",
+            )
+
+    return GraphClone(
+        cloned[object_identifiers[root_identifier]],
+        object_identifiers,
+        standalone_components,
+    )
+
+
+def replace_uuid_identities(message: Message, *, seed: str) -> None:
+    """Give cloned table UUID/CFUUID identities deterministic fresh values."""
+    uuid_pairs: dict[tuple[int, int], tuple[int, int]] = {}
+    cfuuid_parts: dict[tuple[int, int, int, int], tuple[int, int, int, int]] = {}
+
+    def visit(current: Message, path: str) -> None:
+        fields = current.fields
+        if (
+            len(fields) == 2
+            and {field.number for field in fields} == {1, 2}
+            and all(field.wire_type == 0 for field in fields)
+        ):
+            first, second = current.one(1), current.one(2)
+            key = (int(first.value), int(second.value))
+            if min(key) > 0xFFFFFFFF:
+                replacement = uuid_pairs.get(key)
+                if replacement is None:
+                    generated = uuid.uuid5(uuid.NAMESPACE_URL, f"{seed}:uuid:{key}")
+                    replacement = (
+                        generated.int >> 64,
+                        generated.int & ((1 << 64) - 1),
+                    )
+                    uuid_pairs[key] = replacement
+                first.set_varint(replacement[0])
+                second.set_varint(replacement[1])
+                return
+        if (
+            len(fields) == 4
+            and {field.number for field in fields} == {2, 3, 4, 5}
+            and all(field.wire_type == 0 for field in fields)
+        ):
+            key = tuple(int(current.one(number).value) for number in (2, 3, 4, 5))
+            replacement = cfuuid_parts.get(key)
+            if replacement is None:
+                raw = uuid.uuid5(uuid.NAMESPACE_URL, f"{seed}:cfuuid:{key}").bytes
+                replacement = tuple(
+                    int.from_bytes(raw[offset : offset + 4], "big")
+                    for offset in range(0, 16, 4)
+                )
+                cfuuid_parts[key] = replacement
+            for number, value in zip((2, 3, 4, 5), replacement):
+                current.one(number).set_varint(value)
+            return
+        for index, field in enumerate(fields):
+            if field.wire_type != 2:
+                continue
+            try:
+                child = Message.parse(bytes(field.value))
+            except ProtobufError:
+                continue
+            before = child.encode()
+            visit(child, f"{path}.{field.number}[{index}]")
+            after = child.encode()
+            if after != before:
+                field.set_bytes(after)
+
+    visit(message, "root")
+
+
+def append_attachment_run(
+    storage: LocatedObject, position_utf16: int, attachment_identifier: int
+) -> None:
+    """Add an attachment boundary to StorageArchive field 9."""
+    field = storage.message.one(9)
+    if field is None:
+        field = storage.message.add_bytes(9, b"")
+    runs = parse_attribute_table(bytes(field.value))
+    if any(run.character_index == position_utf16 for run in runs):
+        raise ValueError(f"attachment boundary already exists at UTF-16 {position_utf16}")
+    runs.append(AttributeRun(position_utf16, attachment_identifier))
+    runs.sort(key=lambda run: run.character_index)
+    field.set_bytes(encode_attribute_table(runs))
+    add_object_reference(storage.info, attachment_identifier)