python-pages 0.1.0__py3-none-any.whl

pages/pages.py

@@ -0,0 +1,365 @@
+"""Container-level Pages document loader/saver."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from io import BytesIO
+from pathlib import Path
+from zipfile import ZIP_DEFLATED, ZipFile, ZipInfo
+
+from .iwa import IWAFile
+from .metadata import (
+    PACKAGE_LAST_OBJECT_IDENTIFIER,
+    TYPE_PACKAGE_METADATA,
+)
+from .protobuf import Message
+from .stylesheet import CharacterProperties, ParagraphProperties, Stylesheet
+from .document import DocumentLayout
+from .text import (
+    CHAR_BOLD,
+    CHAR_FONT_NAME,
+    DEFAULT_BOLD_FONT_NAME,
+    STYLE_CHAR_PROPERTIES,
+    STYLE_SUPER,
+    STORAGE_TABLE_CHAR_STYLE,
+    STORAGE_TEXT,
+    TYPE_CHARACTER_STYLE,
+    TYPE_STORAGE,
+    LocatedObject,
+    add_object_reference,
+    codepoint_to_utf16,
+    encode_attribute_table,
+    parse_attribute_table,
+    replace_style_range,
+)
+
+
+@dataclass
+class StoredEntry:
+    info: ZipInfo
+    data: bytes | IWAFile
+
+
+class ObjectIndex(dict[int, LocatedObject]):
+    """Object-ID index retaining every payload in multi-message segments."""
+
+    def __init__(self, objects: list[LocatedObject]):
+        grouped: dict[int, list[LocatedObject]] = {}
+        for obj in objects:
+            grouped.setdefault(obj.segment.identifier, []).append(obj)
+        super().__init__((identifier, messages[0]) for identifier, messages in grouped.items())
+        self._grouped = grouped
+
+    def all(self, identifier: int) -> tuple[LocatedObject, ...]:
+        return tuple(self._grouped.get(identifier, ()))
+
+    def messages(self) -> tuple[LocatedObject, ...]:
+        return tuple(obj for messages in self._grouped.values() for obj in messages)
+
+
+class PagesDocument:
+    def __init__(self, entries: list[StoredEntry], source: Path):
+        self.entries = entries
+        self.source = source
+        self._stylesheet: Stylesheet | None = None
+        self._document_layout: DocumentLayout | None = None
+
+    @classmethod
+    def load(cls, path: str | Path) -> "PagesDocument":
+        source = Path(path)
+        entries: list[StoredEntry] = []
+        with ZipFile(source, "r", metadata_encoding="utf-8") as outer:
+            bad = outer.testzip()
+            if bad:
+                raise ValueError(f"bad outer ZIP member: {bad}")
+            for info in outer.infolist():
+                blob = outer.read(info)
+                if info.filename.lower().endswith("index.zip"):
+                    nested = BytesIO(blob)
+                    with ZipFile(nested, "r", metadata_encoding="utf-8") as index:
+                        for nested_info in index.infolist():
+                            nested_blob = index.read(nested_info)
+                            item = IWAFile.parse(nested_blob) if nested_info.filename.endswith(".iwa") else nested_blob
+                            synthetic = ZipInfo("@INDEXZIP@/" + nested_info.filename, nested_info.date_time)
+                            synthetic.compress_type = nested_info.compress_type
+                            entries.append(StoredEntry(synthetic, item))
+                else:
+                    item = IWAFile.parse(blob) if info.filename.endswith(".iwa") else blob
+                    entries.append(StoredEntry(info, item))
+        return cls(entries, source)
+
+    @property
+    def iwa_files(self) -> dict[str, IWAFile]:
+        return {entry.info.filename: entry.data for entry in self.entries if isinstance(entry.data, IWAFile)}
+
+    def save(self, path: str | Path) -> None:
+        path = Path(path)
+        nested_entries = [e for e in self.entries if e.info.filename.startswith("@INDEXZIP@/")]
+        direct_entries = [e for e in self.entries if not e.info.filename.startswith("@INDEXZIP@/")]
+        if nested_entries:
+            nested_buf = BytesIO()
+            with ZipFile(nested_buf, "w", ZIP_DEFLATED) as nested:
+                for entry in nested_entries:
+                    name = entry.info.filename.removeprefix("@INDEXZIP@/")
+                    blob = entry.data.encode() if isinstance(entry.data, IWAFile) else entry.data
+                    nested.writestr(name, blob)
+            direct_entries.append(StoredEntry(ZipInfo("Index.zip"), nested_buf.getvalue()))
+        with ZipFile(path, "w", ZIP_DEFLATED) as outer:
+            for entry in direct_entries:
+                blob = entry.data.encode() if isinstance(entry.data, IWAFile) else entry.data
+                info = ZipInfo(entry.info.filename, entry.info.date_time)
+                info.external_attr = entry.info.external_attr
+                info.comment = entry.info.comment
+                info.extra = entry.info.extra
+                info.flag_bits = entry.info.flag_bits
+                info.compress_type = ZIP_DEFLATED
+                outer.writestr(info, blob)
+
+    def validate(self) -> dict[str, int]:
+        reparsed = 0
+        segments = 0
+        for iwa in self.iwa_files.values():
+            fresh = IWAFile.parse(iwa.encode())
+            reparsed += 1
+            segments += len(fresh.segments)
+        return {"iwa_files": reparsed, "segments": segments}
+
+    def package_data(self, name: str) -> bytes | None:
+        """Return a non-IWA package member, or ``None`` when it is absent."""
+        for entry in self.entries:
+            if entry.info.filename == name:
+                if isinstance(entry.data, IWAFile):
+                    raise TypeError(f"{name} is an IWA member")
+                return entry.data
+        return None
+
+    def set_package_data(self, name: str, data: bytes) -> None:
+        """Add or replace a non-IWA member without disturbing package peers."""
+        for entry in self.entries:
+            if entry.info.filename != name:
+                continue
+            if isinstance(entry.data, IWAFile):
+                raise TypeError(f"{name} is an IWA member")
+            entry.data = data
+            return
+        self.entries.append(StoredEntry(ZipInfo(name), data))
+
+    def object_messages(self) -> list[LocatedObject]:
+        """Return every MessageInfo/payload, including multi-message segments."""
+        result: list[LocatedObject] = []
+        for filename, iwa in self.iwa_files.items():
+            for segment in iwa.segments:
+                for info, message in zip(segment.infos, segment.payloads):
+                    result.append(LocatedObject(filename, segment, info, message))
+        return result
+
+    def objects(self) -> ObjectIndex:
+        return ObjectIndex(self.object_messages())
+
+    def body_storage(self, storage_id: int | None = None) -> LocatedObject:
+        candidates: list[LocatedObject] = []
+        for obj in self.objects().values():
+            if obj.info.type_id != TYPE_STORAGE or not obj.message.get(STORAGE_TEXT):
+                continue
+            if storage_id is not None and obj.segment.identifier == storage_id:
+                return obj
+            kind = obj.message.one(1)
+            if kind is not None and int(kind.value) == 0:
+                candidates.append(obj)
+        if storage_id is not None:
+            raise KeyError(
+                f"TSWP.StorageArchive {storage_id} was not found or has no text payload"
+            )
+        if not candidates:
+            storage_count = sum(
+                obj.info.type_id == TYPE_STORAGE for obj in self.object_messages()
+            )
+            raise ValueError(
+                "no BODY TSWP.StorageArchive with text was found "
+                f"({storage_count} storage object(s) parsed)"
+            )
+        return max(candidates, key=lambda obj: len(self.text(obj)))
+
+    @staticmethod
+    def text(storage: LocatedObject) -> str:
+        return "".join(bytes(field.value).decode("utf-8") for field in storage.message.get(STORAGE_TEXT))
+
+    def find_bold_character_style(self) -> LocatedObject:
+        named: list[LocatedObject] = []
+        anonymous: list[LocatedObject] = []
+        for obj in self.objects().values():
+            if obj.info.type_id != TYPE_CHARACTER_STYLE:
+                continue
+            props_field = obj.message.one(STYLE_CHAR_PROPERTIES)
+            if props_field is None:
+                continue
+            props = Message.parse(bytes(props_field.value))
+            bold = props.one(CHAR_BOLD)
+            if bold is None or int(bold.value) != 1:
+                continue
+            # A bold-only style is safest: it leaves font, color and size inherited.
+            if len(props.fields) != 1:
+                continue
+            super_field = obj.message.one(STYLE_SUPER)
+            super_message = Message.parse(bytes(super_field.value)) if super_field else Message()
+            name_field = super_message.one(1)
+            if name_field and bytes(name_field.value).decode("utf-8", "replace") == "Emphasis":
+                named.append(obj)
+            else:
+                anonymous.append(obj)
+        choices = named or anonymous
+        if not choices:
+            raise ValueError("document has no reusable bold-only CharacterStyleArchive")
+        return choices[0]
+
+    def find_anonymous_character_style_template(self) -> LocatedObject:
+        """Return an anonymous type-2021 style, preferring a bold-only one."""
+        anonymous: list[tuple[bool, LocatedObject]] = []
+        for obj in self.objects().values():
+            if obj.info.type_id != TYPE_CHARACTER_STYLE:
+                continue
+            super_field = obj.message.one(STYLE_SUPER)
+            props_field = obj.message.one(STYLE_CHAR_PROPERTIES)
+            if super_field is None or props_field is None:
+                continue
+            super_message = Message.parse(bytes(super_field.value))
+            anonymous_marker = super_message.one(4)
+            if anonymous_marker is None or int(anonymous_marker.value) != 1:
+                continue
+            props = Message.parse(bytes(props_field.value))
+            bold = props.one(CHAR_BOLD)
+            bold_only = bold is not None and int(bold.value) == 1 and len(props.fields) == 1
+            anonymous.append((bold_only, obj))
+        if not anonymous:
+            raise ValueError("document has no anonymous CharacterStyleArchive template")
+        anonymous.sort(key=lambda item: (not item[0], item[1].segment.identifier))
+        return anonymous[0][1]
+
+    def package_metadata(self) -> LocatedObject:
+        matches = [obj for obj in self.objects().values() if obj.info.type_id == TYPE_PACKAGE_METADATA]
+        if len(matches) != 1:
+            raise ValueError(f"expected one TSP.PackageMetadata, found {len(matches)}")
+        return matches[0]
+
+    def allocate_object_identifier(self) -> int:
+        package = self.package_metadata()
+        last_field = package.message.one(PACKAGE_LAST_OBJECT_IDENTIFIER)
+        if last_field is None:
+            raise ValueError("PackageMetadata lacks last_object_identifier")
+        identifier = max(int(last_field.value), max(self.objects())) + 1
+        last_field.set_varint(identifier)
+        return identifier
+
+    def stylesheet(self) -> Stylesheet:
+        if self._stylesheet is None:
+            self._stylesheet = Stylesheet(self)
+        return self._stylesheet
+
+    def document_layout(self, body_storage: LocatedObject | None = None) -> DocumentLayout:
+        if self._document_layout is None:
+            self._document_layout = DocumentLayout(self, body_storage or self.body_storage())
+        return self._document_layout
+
+    def synthesize_character_style(
+        self,
+        props: CharacterProperties,
+        *,
+        experimental_allow_paragraph_background: bool = False,
+    ) -> tuple[LocatedObject, dict[str, int | str | bool]]:
+        return self.stylesheet().synthesize_character_style(
+            props,
+            experimental_allow_paragraph_background=(
+                experimental_allow_paragraph_background
+            ),
+        )
+
+    def synthesize_paragraph_style(
+        self,
+        parent_identifier: int,
+        props: ParagraphProperties,
+        *,
+        character_properties: bytes = b"",
+    ) -> tuple[LocatedObject, dict[str, int | str | bool]]:
+        return self.stylesheet().synthesize_paragraph_style(
+            parent_identifier,
+            props,
+            character_properties=character_properties,
+        )
+
+    def synthesize_bold_character_style(
+        self, font_name: str = DEFAULT_BOLD_FONT_NAME
+    ) -> tuple[LocatedObject, dict[str, int | str]]:
+        """Compatibility wrapper around generalized style synthesis."""
+        style, result = self.synthesize_character_style(
+            CharacterProperties(bold=True, font_name=font_name)
+        )
+        return style, result | {
+            "bold_style_id": style.segment.identifier,
+            "font_name": font_name,
+            "referencing_component": "Document",
+        }
+
+    def make_bold(
+        self,
+        start: int,
+        length: int,
+        *,
+        storage_id: int | None = None,
+        coordinates: str = "codepoint",
+        font_name: str | None = DEFAULT_BOLD_FONT_NAME,
+    ) -> dict[str, int | str]:
+        storage = self.body_storage(storage_id)
+        text = self.text(storage)
+        if start < 0 or length <= 0 or start + length > len(text):
+            raise ValueError("requested range is outside body text")
+        if coordinates == "codepoint":
+            wire_start = codepoint_to_utf16(text, start)
+            wire_end = codepoint_to_utf16(text, start + length)
+        elif coordinates == "utf16":
+            wire_start, wire_end = start, start + length
+        else:
+            raise ValueError("coordinates must be 'codepoint' or 'utf16'")
+        table_field = storage.message.one(STORAGE_TABLE_CHAR_STYLE)
+        if table_field is None:
+            table_field = storage.message.add_bytes(STORAGE_TABLE_CHAR_STYLE, b"")
+        runs = parse_attribute_table(bytes(table_field.value))
+        props = CharacterProperties(bold=True, font_name=font_name)
+        bold, creation = self.synthesize_character_style(props)
+        creation = creation | {"font_name": font_name or "inherited"}
+        updated = replace_style_range(runs, wire_start, wire_end, bold.segment.identifier)
+        table_field.set_bytes(encode_attribute_table(updated))
+        add_object_reference(storage.info, bold.segment.identifier)
+        return creation | {
+            "storage_id": storage.segment.identifier,
+            "bold_style_id": bold.segment.identifier,
+            "start_utf16": wire_start,
+            "end_utf16": wire_end,
+            "runs_before": len(runs),
+            "runs_after": len(updated),
+        }
+
+    def make_substring_bold(
+        self,
+        substring: str,
+        *,
+        occurrence: int = 1,
+        storage_id: int | None = None,
+        font_name: str | None = DEFAULT_BOLD_FONT_NAME,
+    ) -> dict[str, int | str]:
+        storage = self.body_storage(storage_id)
+        text = self.text(storage)
+        if occurrence < 1:
+            raise ValueError("occurrence is one-based")
+        start = -1
+        search_from = 0
+        for _ in range(occurrence):
+            start = text.find(substring, search_from)
+            if start < 0:
+                raise ValueError(f"substring occurrence {occurrence} not found")
+            search_from = start + len(substring)
+        return self.make_bold(
+            start,
+            len(substring),
+            storage_id=storage.segment.identifier,
+            font_name=font_name,
+        )