python-pages 0.1.0__py3-none-any.whl

pages/core_properties.py

@@ -0,0 +1,126 @@
+"""python-docx-shaped core properties stored as an explicit Pages extension."""
+
+from __future__ import annotations
+
+import datetime as dt
+import plistlib
+
+from .pages import PagesDocument
+
+
+CORE_PROPERTIES_MEMBER = "Metadata/PythonPagesCoreProperties.plist"
+LEGACY_CORE_PROPERTIES_MEMBER = "Metadata/IWALabCoreProperties.plist"
+_STRING_PROPERTIES = (
+    "author",
+    "category",
+    "comments",
+    "content_status",
+    "identifier",
+    "keywords",
+    "language",
+    "last_modified_by",
+    "subject",
+    "title",
+    "version",
+)
+_DATE_PROPERTIES = ("created", "last_printed", "modified")
+
+
+class CoreProperties:
+    """Dublin Core facade for concepts Pages does not natively archive.
+
+    Values live in a namespaced package member so native Pages metadata is not
+    overloaded with meanings its schema does not define.
+    """
+
+    def __init__(self, package: PagesDocument):
+        self._package = package
+        raw = package.package_data(CORE_PROPERTIES_MEMBER)
+        if raw is None:
+            # Read documents produced before the project was renamed. New
+            # writes always use the python-pages namespace above.
+            raw = package.package_data(LEGACY_CORE_PROPERTIES_MEMBER)
+        if raw is None:
+            self._values: dict[str, str | int] = {}
+            return
+        parsed = plistlib.loads(raw)
+        if not isinstance(parsed, dict) or parsed.get("formatVersion") != 1:
+            raise ValueError("unsupported python-pages core-properties format")
+        values = parsed.get("properties", {})
+        if not isinstance(values, dict):
+            raise ValueError("invalid python-pages core-properties payload")
+        self._values = dict(values)
+
+    def _save(self) -> None:
+        payload = {"formatVersion": 1, "properties": self._values}
+        self._package.set_package_data(
+            CORE_PROPERTIES_MEMBER,
+            plistlib.dumps(payload, fmt=plistlib.FMT_XML, sort_keys=True),
+        )
+
+    def _string(self, name: str) -> str:
+        value = self._values.get(name, "")
+        return value if isinstance(value, str) else ""
+
+    def _set_string(self, name: str, value: str) -> None:
+        if not isinstance(value, str):
+            raise TypeError(f"{name} must be a string")
+        if len(value) > 255:
+            raise ValueError(f"{name} must not exceed 255 characters")
+        self._values[name] = value
+        self._save()
+
+    def _date(self, name: str) -> dt.datetime | None:
+        value = self._values.get(name)
+        if not isinstance(value, str):
+            return None
+        try:
+            return dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            return None
+
+    def _set_date(self, name: str, value: dt.datetime | None) -> None:
+        if value is None:
+            self._values.pop(name, None)
+            self._save()
+            return
+        if not isinstance(value, dt.datetime):
+            raise TypeError(f"{name} must be a datetime or None")
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=dt.timezone.utc)
+        else:
+            value = value.astimezone(dt.timezone.utc)
+        self._values[name] = value.replace(microsecond=0).isoformat().replace("+00:00", "Z")
+        self._save()
+
+    @property
+    def revision(self) -> int:
+        value = self._values.get("revision", 0)
+        return value if isinstance(value, int) and value >= 0 else 0
+
+    @revision.setter
+    def revision(self, value: int) -> None:
+        if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+            raise ValueError(f"revision property requires positive int, got {value!r}")
+        self._values["revision"] = value
+        self._save()
+
+
+def _string_property(name: str):
+    return property(
+        lambda self: self._string(name),
+        lambda self, value: self._set_string(name, value),
+    )
+
+
+def _date_property(name: str):
+    return property(
+        lambda self: self._date(name),
+        lambda self, value: self._set_date(name, value),
+    )
+
+
+for _name in _STRING_PROPERTIES:
+    setattr(CoreProperties, _name, _string_property(_name))
+for _name in _DATE_PROPERTIES:
+    setattr(CoreProperties, _name, _date_property(_name))

pages/document.py

@@ -0,0 +1,215 @@
+"""Middle-layer access to TP document geometry and header/footer storage."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import struct
+from typing import TYPE_CHECKING
+
+from .protobuf import Message
+from .text import LocatedObject, parse_attribute_table, parse_reference, unpack_packed_varints
+
+if TYPE_CHECKING:
+    from .pages import PagesDocument
+
+
+TYPE_DOCUMENT = 10000
+TYPE_SECTION = 10011
+TYPE_SECTION_TEMPLATE = 10143
+
+DOCUMENT_USES_SINGLE_HEADER_FOOTER = 21
+DOCUMENT_PAGE_WIDTH = 30
+DOCUMENT_PAGE_HEIGHT = 31
+DOCUMENT_LEFT_MARGIN = 32
+DOCUMENT_RIGHT_MARGIN = 33
+DOCUMENT_TOP_MARGIN = 34
+DOCUMENT_BOTTOM_MARGIN = 35
+DOCUMENT_HEADER_MARGIN = 36
+DOCUMENT_FOOTER_MARGIN = 37
+DOCUMENT_PAGE_SCALE = 38
+DOCUMENT_ORIENTATION = 42
+
+SECTION_FIRST_PAGE_DIFFERENT = 18
+SECTION_EVEN_ODD_DIFFERENT = 19
+SECTION_FIRST_TEMPLATE = 23
+SECTION_EVEN_TEMPLATE = 24
+SECTION_ODD_TEMPLATE = 25
+
+TEMPLATE_HEADERS = 1
+TEMPLATE_FOOTERS = 2
+STORAGE_TEXT = 3
+
+# These fields have ObjectAttributeTable wire shape in the supplied header and
+# footer storage objects. Nonzero boundaries require Stage-C offset rewriting.
+HEADER_FOOTER_ATTRIBUTE_TABLES = (5, 6, 7, 8, 9, 11, 12, 14, 24)
+
+
+def _float_bits(value: float) -> int:
+    return int.from_bytes(struct.pack("<f", float(value)), "little")
+
+
+def _bits_float(value: int) -> float:
+    return struct.unpack("<f", int(value).to_bytes(4, "little"))[0]
+
+
+@dataclass(frozen=True)
+class PageGeometry:
+    page_width: float | None
+    page_height: float | None
+    left_margin: float | None
+    right_margin: float | None
+    top_margin: float | None
+    bottom_margin: float | None
+    header_margin: float | None
+    footer_margin: float | None
+    orientation: int
+
+
+class DocumentLayout:
+    """Mutation facade for a package's single Pages document/section model."""
+
+    def __init__(self, document: "PagesDocument", body_storage: LocatedObject):
+        self.document = document
+        roots = [obj for obj in document.object_messages() if obj.info.type_id == TYPE_DOCUMENT]
+        if len(roots) != 1:
+            raise ValueError(f"expected one TP.DocumentArchive, found {len(roots)}")
+        self.root = roots[0]
+        self.section = self._find_section(body_storage)
+
+    def _find_section(self, storage: LocatedObject) -> LocatedObject:
+        references = storage.info.message.one(5)
+        identifiers = (
+            unpack_packed_varints(bytes(references.value)) if references is not None else []
+        )
+        sections = [
+            self.document.objects()[identifier]
+            for identifier in identifiers
+            if identifier in self.document.objects()
+            and self.document.objects()[identifier].info.type_id == TYPE_SECTION
+        ]
+        if len(sections) != 1:
+            raise ValueError(
+                "expected body storage to reference one TP.SectionArchive, "
+                f"found {len(sections)}"
+            )
+        return sections[0]
+
+    def fixed32(self, number: int) -> float | None:
+        field = self.root.message.one(number)
+        return None if field is None else _bits_float(int(field.value))
+
+    def set_fixed32(self, number: int, value: float | None) -> None:
+        fields = self.root.message.get(number)
+        if value is None:
+            self.root.message.fields = [field for field in self.root.message.fields if field.number != number]
+            return
+        if fields:
+            fields[0].set_fixed32(_float_bits(value))
+            self.root.message.fields = [
+                field for field in self.root.message.fields if field.number != number or field is fields[0]
+            ]
+        else:
+            self.root.message.add_fixed32(number, _float_bits(value))
+
+    def varint(self, number: int, default: int = 0) -> int:
+        field = self.root.message.one(number)
+        return default if field is None else int(field.value)
+
+    def set_varint(self, number: int, value: int | None) -> None:
+        fields = self.root.message.get(number)
+        if value is None:
+            self.root.message.fields = [field for field in self.root.message.fields if field.number != number]
+            return
+        if fields:
+            fields[0].set_varint(value)
+            self.root.message.fields = [
+                field for field in self.root.message.fields if field.number != number or field is fields[0]
+            ]
+        else:
+            self.root.message.add_varint(number, value)
+
+    @property
+    def geometry(self) -> PageGeometry:
+        return PageGeometry(
+            self.fixed32(DOCUMENT_PAGE_WIDTH),
+            self.fixed32(DOCUMENT_PAGE_HEIGHT),
+            self.fixed32(DOCUMENT_LEFT_MARGIN),
+            self.fixed32(DOCUMENT_RIGHT_MARGIN),
+            self.fixed32(DOCUMENT_TOP_MARGIN),
+            self.fixed32(DOCUMENT_BOTTOM_MARGIN),
+            self.fixed32(DOCUMENT_HEADER_MARGIN),
+            self.fixed32(DOCUMENT_FOOTER_MARGIN),
+            self.varint(DOCUMENT_ORIENTATION),
+        )
+
+    def section_flag(self, number: int, default: bool = False) -> bool:
+        field = self.section.message.one(number)
+        return default if field is None else bool(field.value)
+
+    def set_section_flag(self, number: int, value: bool) -> None:
+        field = self.section.message.one(number)
+        if field is None:
+            self.section.message.add_varint(number, int(value))
+        else:
+            field.set_varint(int(value))
+
+    def template(self, kind: str) -> LocatedObject:
+        number = {
+            "first": SECTION_FIRST_TEMPLATE,
+            "even": SECTION_EVEN_TEMPLATE,
+            "primary": SECTION_ODD_TEMPLATE,
+        }[kind]
+        field = self.section.message.one(number)
+        identifier = parse_reference(bytes(field.value)) if field is not None else None
+        obj = self.document.objects().get(identifier) if identifier is not None else None
+        if obj is None or obj.info.type_id != TYPE_SECTION_TEMPLATE:
+            raise ValueError(f"section has no {kind} TP.SectionTemplateArchive")
+        return obj
+
+    def header_footer_storages(self, kind: str, *, footer: bool) -> list[LocatedObject]:
+        template = self.template(kind)
+        number = TEMPLATE_FOOTERS if footer else TEMPLATE_HEADERS
+        result = []
+        for field in template.message.get(number):
+            identifier = parse_reference(bytes(field.value))
+            obj = self.document.objects().get(identifier) if identifier is not None else None
+            if obj is None or obj.info.type_id != 2001:
+                raise ValueError(f"{kind} header/footer references a missing storage")
+            result.append(obj)
+        if not result:
+            raise ValueError(f"{kind} header/footer has no storage fragments")
+        return result
+
+    @staticmethod
+    def storage_text(storage: LocatedObject) -> str:
+        return "".join(
+            bytes(field.value).decode("utf-8") for field in storage.message.get(STORAGE_TEXT)
+        )
+
+    @staticmethod
+    def set_storage_text(storage: LocatedObject, value: str) -> None:
+        if not isinstance(value, str):
+            raise TypeError("header/footer text must be a string")
+        for number in HEADER_FOOTER_ATTRIBUTE_TABLES:
+            field = storage.message.one(number)
+            if field is None:
+                continue
+            try:
+                runs = parse_attribute_table(bytes(field.value))
+            except ValueError:
+                continue
+            if any(run.character_index != 0 for run in runs):
+                raise NotImplementedError(
+                    "header/footer text with nonzero attribute boundaries requires Stage C"
+                )
+        text_fields = storage.message.get(STORAGE_TEXT)
+        encoded = value.encode("utf-8")
+        if text_fields:
+            text_fields[0].set_bytes(encoded)
+            storage.message.fields = [
+                field
+                for field in storage.message.fields
+                if field.number != STORAGE_TEXT or field is text_fields[0]
+            ]
+        elif value:
+            storage.message.add_bytes(STORAGE_TEXT, encoded)

pages/hyperlinks.py

@@ -0,0 +1,57 @@
+"""Middle-layer access to TSWP smart-field hyperlink runs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .text import LocatedObject, parse_attribute_table
+
+if TYPE_CHECKING:
+    from .pages import PagesDocument
+
+
+TYPE_HYPERLINK_FIELD = 2032
+STORAGE_TABLE_SMART_FIELDS = 11
+HYPERLINK_URL = 2
+
+
+@dataclass
+class HyperlinkStore:
+    object: LocatedObject
+    start_utf16: int
+    end_utf16: int
+
+    @property
+    def url(self) -> str:
+        field = self.object.message.one(HYPERLINK_URL)
+        return "" if field is None else bytes(field.value).decode("utf-8", "replace")
+
+    @url.setter
+    def url(self, value: str) -> None:
+        if not isinstance(value, str):
+            raise TypeError("hyperlink URL must be a string")
+        field = self.object.message.one(HYPERLINK_URL)
+        if field is None:
+            self.object.message.add_bytes(HYPERLINK_URL, value.encode("utf-8"))
+        else:
+            field.set_bytes(value.encode("utf-8"))
+
+
+def storage_hyperlinks(
+    document: "PagesDocument", storage: LocatedObject
+) -> list[HyperlinkStore]:
+    field = storage.message.one(STORAGE_TABLE_SMART_FIELDS)
+    if field is None:
+        return []
+    objects = document.objects()
+    runs = parse_attribute_table(bytes(field.value))
+    result: list[HyperlinkStore] = []
+    for index, run in enumerate(runs):
+        obj = objects.get(run.object_id) if run.object_id is not None else None
+        if obj is None or obj.info.type_id != TYPE_HYPERLINK_FIELD:
+            continue
+        end = runs[index + 1].character_index if index + 1 < len(runs) else run.character_index
+        if end > run.character_index:
+            result.append(HyperlinkStore(obj, run.character_index, end))
+    return result

pages/iwa.py

@@ -0,0 +1,101 @@
+"""IWA archive framing on top of raw protobuf wire messages."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .protobuf import Message, ProtobufError, encode_varint, read_varint
+from .snappy import compress_iwork, decompress_iwork
+
+
+@dataclass
+class MessageInfo:
+    field: object
+    message: Message
+    type_id: int
+    length: int
+
+    def update_length(self, length: int) -> None:
+        length_field = self.message.one(3)
+        if length_field is None:
+            raise ProtobufError("MessageInfo lacks required length field 3")
+        length_field.set_varint(length)
+        self.field.children = self.message
+        self.field.dirty = True
+        self.length = length
+
+
+@dataclass
+class ArchiveSegment:
+    header: Message
+    header_original: bytes
+    identifier: int
+    infos: list[MessageInfo]
+    payloads: list[Message]
+    payload_originals: list[bytes]
+
+    def encode(self) -> bytes:
+        encoded_payloads = [p.encode() for p in self.payloads]
+        for info, payload in zip(self.infos, encoded_payloads):
+            if info.length != len(payload):
+                info.update_length(len(payload))
+        header = self.header.encode()
+        return encode_varint(len(header)) + header + b"".join(encoded_payloads)
+
+
+@dataclass
+class IWAFile:
+    segments: list[ArchiveSegment]
+    decoded_sizes: list[int]
+    compressed_original: bytes = b""
+    decoded_original: bytes = b""
+
+    @classmethod
+    def parse(cls, data: bytes) -> "IWAFile":
+        decoded, decoded_sizes = decompress_iwork(data)
+        segments: list[ArchiveSegment] = []
+        pos = 0
+        while pos < len(decoded):
+            header_length, pos = read_varint(decoded, pos)
+            if pos + header_length > len(decoded):
+                raise ProtobufError("truncated ArchiveInfo")
+            header_bytes = decoded[pos : pos + header_length]
+            pos += header_length
+            header = Message.parse(header_bytes)
+            identifier_field = header.one(1)
+            identifier = int(identifier_field.value) if identifier_field else 0
+            infos: list[MessageInfo] = []
+            for info_field in header.get(2):
+                if info_field.wire_type != 2:
+                    raise ProtobufError("ArchiveInfo.message_infos is not a message")
+                info_message = Message.parse(bytes(info_field.value))
+                info_field.children = info_message
+                type_field, length_field = info_message.one(1), info_message.one(3)
+                if type_field is None or length_field is None:
+                    raise ProtobufError("MessageInfo missing type or length")
+                infos.append(MessageInfo(info_field, info_message, int(type_field.value), int(length_field.value)))
+            payloads: list[Message] = []
+            originals: list[bytes] = []
+            for info in infos:
+                end = pos + info.length
+                if end > len(decoded):
+                    raise ProtobufError("truncated archive payload")
+                raw = decoded[pos:end]
+                originals.append(raw)
+                payloads.append(Message.parse(raw))
+                pos = end
+            segments.append(ArchiveSegment(header, header_bytes, identifier, infos, payloads, originals))
+        return cls(segments, decoded_sizes, data, decoded)
+
+    def encode_decoded(self) -> bytes:
+        return b"".join(segment.encode() for segment in self.segments)
+
+    def encode(self) -> bytes:
+        decoded = self.encode_decoded()
+        if self.compressed_original and decoded == self.decoded_original:
+            return self.compressed_original
+        sizes = self.decoded_sizes if sum(self.decoded_sizes) == len(decoded) else None
+        return compress_iwork(decoded, sizes)
+
+    def type_ids(self) -> list[int]:
+        return [info.type_id for segment in self.segments for info in segment.infos]

pages/metadata.py

@@ -0,0 +1,117 @@
+"""Minimal TSP.PackageMetadata mutation for registering new component objects."""
+
+from __future__ import annotations
+
+import uuid
+
+from .protobuf import Message
+
+TYPE_PACKAGE_METADATA = 11006
+
+PACKAGE_LAST_OBJECT_IDENTIFIER = 1
+PACKAGE_REVISION = 2
+PACKAGE_COMPONENTS = 3
+
+COMPONENT_IDENTIFIER = 1
+COMPONENT_PREFERRED_LOCATOR = 2
+COMPONENT_LOCATOR = 3
+COMPONENT_EXTERNAL_REFERENCES = 6
+COMPONENT_OBJECT_UUID_MAP = 11
+
+
+def component_name(component: Message) -> str:
+    locator = component.one(COMPONENT_LOCATOR) or component.one(COMPONENT_PREFERRED_LOCATOR)
+    return bytes(locator.value).decode("utf-8") if locator is not None else ""
+
+
+def object_uuid_map(component: Message) -> dict[int, tuple[int, int]]:
+    result: dict[int, tuple[int, int]] = {}
+    for raw in component.get(COMPONENT_OBJECT_UUID_MAP):
+        entry = Message.parse(bytes(raw.value))
+        identifier = entry.one(1)
+        uuid_field = entry.one(2)
+        if identifier is None or uuid_field is None:
+            continue
+        uuid_message = Message.parse(bytes(uuid_field.value))
+        first, second = uuid_message.one(1), uuid_message.one(2)
+        if first is not None and second is not None:
+            result[int(identifier.value)] = (int(first.value), int(second.value))
+    return result
+
+
+def package_revision_identifier(package: Message) -> str:
+    field = package.one(PACKAGE_REVISION)
+    if field is None:
+        return "unknown-document"
+    revision = Message.parse(bytes(field.value))
+    identifier = revision.one(2)
+    return bytes(identifier.value).decode("utf-8", "replace") if identifier else "unknown-document"
+
+
+def register_component_object(
+    package: Message,
+    component_locator: str,
+    identifier: int,
+    *,
+    uuid_seed: str,
+) -> tuple[str, int]:
+    """Add an object UUID entry and return its RFC UUID and component ID."""
+    selected_field = None
+    selected = None
+    for field in package.get(PACKAGE_COMPONENTS):
+        component = Message.parse(bytes(field.value))
+        if component_name(component) == component_locator:
+            selected_field, selected = field, component
+            break
+    if selected_field is None or selected is None:
+        raise ValueError(f"PackageMetadata has no component {component_locator!r}")
+    if identifier in object_uuid_map(selected):
+        raise ValueError(f"object {identifier} is already registered in {component_locator}")
+
+    generated = uuid.uuid5(uuid.NAMESPACE_URL, uuid_seed)
+    uuid_message = Message()
+    uuid_message.add_varint(1, generated.int >> 64)
+    uuid_message.add_varint(2, generated.int & ((1 << 64) - 1))
+    entry = Message()
+    entry.add_varint(1, identifier)
+    entry.add_bytes(2, uuid_message.encode())
+    selected.add_bytes(COMPONENT_OBJECT_UUID_MAP, entry.encode())
+    selected_field.set_bytes(selected.encode())
+    component_id = selected.one(COMPONENT_IDENTIFIER)
+    if component_id is None:
+        raise ValueError(f"component {component_locator!r} has no identifier")
+    return str(generated), int(component_id.value)
+
+
+def register_external_reference(
+    package: Message,
+    source_component_locator: str,
+    target_component_identifier: int,
+    target_object_identifier: int,
+) -> None:
+    """Register a strong cross-component object reference if it is absent."""
+    selected_field = None
+    selected = None
+    for field in package.get(PACKAGE_COMPONENTS):
+        component = Message.parse(bytes(field.value))
+        if component_name(component) == source_component_locator:
+            selected_field, selected = field, component
+            break
+    if selected_field is None or selected is None:
+        raise ValueError(f"PackageMetadata has no component {source_component_locator!r}")
+    for raw in selected.get(COMPONENT_EXTERNAL_REFERENCES):
+        reference = Message.parse(bytes(raw.value))
+        component = reference.one(1)
+        obj = reference.one(2)
+        if (
+            component is not None
+            and obj is not None
+            and int(component.value) == target_component_identifier
+            and int(obj.value) == target_object_identifier
+        ):
+            return
+    reference = Message()
+    reference.add_varint(1, target_component_identifier)
+    reference.add_varint(2, target_object_identifier)
+    selected.add_bytes(COMPONENT_EXTERNAL_REFERENCES, reference.encode())
+    selected_field.set_bytes(selected.encode())